Create or update a contract
Creates or updates a contract by your reference. AlphaCount bills it every cycle: advance items for the coming period, usage and overage for the past one, each line with its own service period.
Items carry your own ref. A later PUT changes an item's quantity from the next cycle on, adds new items and ends left-out items after the current cycle; agreed prices stay frozen. While a contract is a draft, everything is replaced. Once it runs, interval and start are fixed. Scope partner:contracts:write.
apiKey partner:contracts:writeAuthorizationBearer <ab_…>An API key from Integrations → Connect AI assistants (MCP) → New access, bound to exactly one company. Each operation names the scope the key must carry.
Scope: partner:contracts:write
source*Source^[a-z0-9][a-z0-9_-]{0,49}$external_ref*External Ref^[A-Za-z0-9][A-Za-z0-9._:@+-]{0,254}$AlphaCount-Version?stringThe API version to use. Default: the current one.
application/json- body
PUT /contracts/by-ref/{source}/{external_ref}. Interval and start are
fixed once the contract runs; quantities change from the next cycle, an
item left out stops after the current one.
billing_interval?Billing Interval"month""month""quarter""year"billing_starts_on?|nullcustomer*end_date?|nullinvoice_mode?Invoice Mode"draft""draft""issue""issue_send"items*array<>1 <= items <= 50name*Name1 <= length <= 255payment_terms_days?|nullstart_date*Start Datedatestatus?Status"active""draft""active""paused"OK
application/json- response
billing_interval*Billing Interval"month""quarter""year"billing_starts_on*|nullcustomer_external_ref*string|nullcycles*array<>end_date*|nullexternal_ref*string|nullexternal_source*string|nullid*Idinvoice_mode*Invoice Mode"draft""issue""issue_send"items*array<>name*Namenext_billing_date*|nullnumber*Numberpayment_terms_days*integer|nullstart_date*Start Datedatestatus*Status"draft""active""paused""cancelled""ended"usage_open_from*|Usage before this day is billed already and refused.
curl -X PUT 'https://app.alphacount.ai/api/partner/v1/contracts/by-ref/string/string' \ -H 'Authorization: Bearer ab_...' \ -H 'Content-Type: application/json' \ -d '{ "customer": { "external_ref": "school-7", "source": "alphalearn" }, "invoice_mode": "draft", "items": [ { "product_ref": "seat", "quantity": 10, "ref": "seats" }, { "product_ref": "tokens", "quantity": 0, "ref": "tokens" }, { "product_ref": "sla", "ref": "sla" } ], "name": "Lernplattform", "start_date": "2026-01-01"}'{ "billing_interval": "month", "billing_starts_on": null, "customer_external_ref": "school-7", "cycles": [ { "end": "2026-01-31", "invoice_id": "00000000-0000-4000-8000-000000000002", "invoice_number": null, "invoice_status": "draft", "start": "2026-01-01", "status": "billed", "total_net": "425.00" } ], "end_date": null, "external_ref": "c-8", "external_source": "alphalearn", "id": "00000000-0000-4000-8000-000000000001", "invoice_mode": "draft", "items": [ { "billing_timing": "advance", "description": "Seat", "ends_after": null, "pricing_model": "per_unit", "product_ref": "seat", "quantity": "20", "ref": "seats", "unit_price_net": "12.50" }, { "billing_timing": "arrears", "description": "Token", "ends_after": null, "pricing_model": "per_unit", "product_ref": "tokens", "quantity": "0", "ref": "tokens", "unit_price_net": "0.20" }, { "billing_timing": "advance", "description": "SLA", "ends_after": "2026-01-31", "pricing_model": "flat", "product_ref": "sla", "quantity": "1", "ref": "sla", "unit_price_net": "300.00" } ], "name": "Lernplattform", "next_billing_date": "2026-02-01", "number": "VT-2026-0001", "payment_terms_days": null, "start_date": "2026-01-01", "status": "active", "usage_open_from": "2026-01-01"}