Purchases
Create a purchase
Subscribes a customer to a plan. Any existing SCHEDULED/ACTIVE purchase for the customer is cancelled first. A cycle-0 invoice is issued immediately for non-PAYG plans. The plan itself must be active — purchasing an inactive plan is rejected with 400. Every invoice includes the taxes set up for the customer's billing country (Settings → Taxes); see subtotal, taxAmount and taxes on the invoice.
Authorization
apiKey AuthorizationBearer <token>
Organisation-scoped key from Settings → API Keys.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Name the customer with customerId or externalId — one is required.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/purchases" \ -H "Content-Type: application/json" \ -d '{ "customerId": "cus_abc123", "planId": "plan_growth", "billingDate": "2026-08-01", "notes": "Upgraded from Free after the trial", "autoPayment": true, "voidAfterMinutes": 1440 }'{ "statusCode": 200, "statusDetail": { "status": "SUCCESS", "message": "OK" }, "result": { "purchase": { "id": "pur_ghi789", "purchaseNumber": "PUR-2026-0042", "customerId": "cus_abc123", "customerName": "Acme Inc", "planId": "plan_growth", "planName": "Growth", "planType": "WALLET", "hasWallet": true, "hasCredit": true, "hasOutcome": false, "hasUnit": false, "billingCycle": "MONTHLY", "cost": 499, "currencyCode": "USD", "billingDate": "2026-08-01T00:00:00.000Z", "status": "SCHEDULED", "autoPayment": true, "autoPaymentPauseReason": "string", "createdAt": "2026-07-01T09:45:00.000Z" } }}{ "statusCode": 400, "statusDetail": { "status": "ERROR", "message": "Request body must be valid JSON." }, "result": {}}{ "statusCode": 401, "statusDetail": { "status": "ERROR", "message": "Invalid API key." }, "result": {}}{ "statusCode": 404, "statusDetail": { "status": "ERROR", "message": "No customer with id \"cus_abc123\"." }, "result": {}}{ "statusCode": 422, "statusDetail": { "status": "ERROR", "message": "No credit with agent key \"summarize\" exists in this workspace." }, "result": {}}{ "statusCode": 500, "statusDetail": { "status": "ERROR", "message": "Could not complete the request." }, "result": {}}