Create an order
Creates an order for a customer with one or more lines. Each line is priced by the charges you list in its attributes, else by the plan you name in planId, else by the product's default plan. The order is a draft unless creationState is active, in which case it is activated straight away (see Activate an order). Seat-based charges get one seat per unit, at most 10,000 per charge. Answers 400 for invalid fields, a planId that isn't a plan of the line's product, or a billingContactIds entry that isn't a contact of the customer or of billingCustomerId; 404 for an unknown customer, product or billingCustomerId; 409 DUPLICATE_EXTERNAL_ID when another order has your externalId; and, for an order created active, 409 CUSTOMER_HAS_ACTIVE_ORDER or ORDER_BILLED_IN_STRIPE as Activate an order does, in which case nothing is created.
Body·
Billing terms you can set on an order.
- Type: stringcustomer
Id requiredThe customer's Spondo Billing ID.
- Type: 1…linesrequiredProperties: 9
The order's lines, at least one.
- Type: boolean | nullauto
Post Invoices Post the order's invoices as soon as the billing run makes them. Null or false, they wait as drafts for you to post.
- Type: boolean | nullauto
Send Billing Emails Email each invoice when it is posted, and reminders on its due date and 3, 7 and 14 days after while it is unpaid (unless Stripe is collecting it). A credit invoice (a negative total) is emailed as a credit, and an invoice with a zero total as one with nothing to pay; an invoice that owes nothing gets no reminders. They go to the billing contacts, else the customer's billing contacts, else the customer's email. Null or false, no emails.
- Type: boolean | nullauto
Send Payment Emails Email a receipt when an invoice is paid in full, stating the amount of the payment that settled it, unless nothing was paid (its total is zero or less, or Stripe settled it from the customer's Stripe balance). Null or false, no receipt.
- Type: integer | nullbilling
Anchor min:1max:31The day of the month the order's billing periods start, fixed once the order isn't a draft. Defaults to the start date's day. In shorter months the period starts on the month's last day. When the start date falls on another day, the first period runs from the start date to the first anchor day and is prorated.
- Type: array of stringbilling
Contact Ids The contacts (
con_…) who receive this order's invoices. Each must be a contact of the customer or ofbillingCustomerId(400 otherwise); duplicates are dropped. Create contacts with Create a contact. - Type: string | nullbilling
Customer Id Another customer who pays for this order. Answers 404 when there is no such customer.
- Type: integer | nullbilling
Frequency Custom Months min:1max:60Months in each billing period when
billingFrequencyOverrideiscustom, a whole number from 1 to 60 (400 otherwise). Default 1. Fixed once the order isn't a draft. - Type: string | nullbilling
Frequency Override Bill the order's recurring and seat-based charges at this frequency (
monthly,quarterly,semiAnnually,annual, orcustomfor everybillingFrequencyCustomMonthsmonths) instead of each charge's own. Usage and one-time charges keep theirs. Fixed once the order isn't a draft. - Type: "draft" or "active"enumcreation
State activeactivates the order as it is created (see Activate an order). - Type: stringcurrency
ISO 4217 code the order is priced and billed in, fixed for the order's life. Default, the currency of the first line's plan, else your account's.
- Type: string | nullend
Date The day the order ends, as a date or date-time. Default, none.
- Type: stringexternal
Id Your ID for the order, unique among your orders. Provisioning matches orders by it.
- Type:metadataProperties: 1
Your own key-value data, kept with the record and returned as sent.
- Type: stringname
The order's name. Default, its products' names joined with " + ".
- Type: string | nullenumpayment
Terms When the order's invoices fall due, counted from when each is posted. Null for 14 days.
valuesDueOnReceiptNet15Net30Net45Net60Net90null - Type: string | nullpurchase
Order Reference Your customer's purchase order reference, shown on the order's invoices.
- Type: stringstart
Date The day the order starts, as a date (YYYY-MM-DD) or ISO 8601 date-time (its UTC day). Default, today.
- Type: object | nullsubscription
Terms Properties: 1Your subscription terms for the order (term length, renewal), kept with the order and returned as sent.
Responses
- application/json
- application/json
- application/json
- application/json
curl https://billing.getspondo.com/api/v1/orders \
--request POST \
--header "Authorization: Bearer $SPONDO_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"customerId": "cus_Q2x9vB7mK4pT1sLw",
"name": "DocuMind Growth",
"externalId": "acme-legal-2026",
"startDate": "2026-10-01",
"creationState": "active",
"paymentTerms": "Net30",
"billingAnchor": 1,
"purchaseOrderReference": "PO-2026-0187",
"lines": [
{
"productId": "prod_7Hk2LmQ9xR4tVb1N",
"planId": "plan_4Fd8sK1mW9qZ2xCv",
"attributes": [
{ "name": "Platform fee" },
{ "name": "Document uploads" },
{ "name": "Seats", "quantity": 10 }
]
}
]
}'
{
"id": "ord_8Jt3Vw0Ym5Ln2Qp7",
"customerId": "cus_Q2x9vB7mK4pT1sLw",
"billingCustomerId": null,
"billingContactIds": [],
"createdAt": "2026-10-01T09:30:12.000Z",
"updatedAt": "2026-10-01T09:30:12.000Z",
"endDate": null,
"name": "DocuMind Growth",
"startDate": "2026-10-01T00:00:00.000Z",
"subscriptionTerms": null,
"billedAmountNoTax": 0,
"billedTax": 0,
"estimatedTax": 0,
"orderAmount": 749,
"pendingBillingAmount": 749,
"totalAmount": 749,
"totalBilledAmount": 0,
"creationState": "active",
"paymentTerms": "Net30",
"number": 42,
"metadata": null,
"showPaymentLink": null,
"showBankDetails": null,
"autoPostInvoices": null,
"autoSendBillingEmails": null,
"autoSendPaymentEmails": null,
"version": 1,
"billingFrequencyOverridden": false,
"billingFrequencyCustomMonths": null,
"purchaseOrderReference": "PO-2026-0187",
"status": "active",
"billingAnchor": 1,
"currency": "USD",
"billedThrough": null
}