Creates an order in the CRM, which owns the order spine. Post a customer and one or more line items; the service computes subtotal and total from the items and writes the order transactionally. An order.created event is emitted after commit. Requires the crm module and an editor role.
The id of the customer placing the order. Must belong to the same tenant as the API key.
The line items. At least one is required (max 500). The service sums them into the order totals.
Stock-keeping unit for the line.
Display name captured on the order line.
Defaults to 1. Must be positive.
Price per unit in currency units (e.g. 289.50). Defaults to 0.
Optional link to a catalog product (UUID).
Optional link to a specific variant (UUID).
Optional free-text line description.
ISO 4217 currency code. Defaults to USD.
Where the order originated: storefront, b2b_portal, admin, import, or mcp.
The site (property) the order was placed on. Optional for admin, import, and MCP orders.
Shipping charge in currency units. Defaults to 0.
Order-level discount. Defaults to 0.
Header-level tax override. If omitted, the service sums per-line tax amounts.
Shipping address snapshot (line1, city, … ).
Billing address snapshot.
A note from the customer, shown on the order.
An internal-only note, not shown to the customer.
Override the human-facing order number. Auto-generated when omitted.
Arbitrary key/value pairs you can attach. Returned verbatim; never used by Sparx.
Returns the created Order with its line items. New orders open at status placed and payment status unpaid; subtotal and total are computed from the items. Status then advances through dedicated endpoints (fulfill, deliver, cancel, refund).
Missing, malformed, revoked, or expired API key.
The tenant hasn’t activated the CRM module (or the key lacks the editor role).
The customerIddoesn’t resolve to a customer in this tenant.
The body failed validation — e.g. an empty items array or a missing sku.
curl https://api.sparx.works/v1/crm/orders \
-H "Authorization: Bearer $SPARX_KEY" \
-H "Content-Type: application/json" \
-d '{
"customerId": "8a1f0b2c-9d3e-4a5b-8c6d-1e2f3a4b5c6d",
"currency": "USD",
"channel": "b2b_portal",
"items": [
{ "sku": "INJ-6.7-CR", "name": "6.7L Common-Rail Injector", "quantity": 8, "unitPrice": 289.50 }
]
}'const res = await fetch("https://api.sparx.works/v1/crm/orders", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SPARX_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
customerId: "8a1f0b2c-9d3e-4a5b-8c6d-1e2f3a4b5c6d",
currency: "USD",
channel: "b2b_portal",
items: [
{ sku: "INJ-6.7-CR", name: "6.7L Common-Rail Injector", quantity: 8, unitPrice: 289.5 },
],
}),
});
const { data: order } = await res.json();order = requests.post(
"https://api.sparx.works/v1/crm/orders",
headers={"Authorization": f"Bearer {os.environ['SPARX_KEY']}"},
json={
"customerId": "8a1f0b2c-9d3e-4a5b-8c6d-1e2f3a4b5c6d",
"currency": "USD",
"channel": "b2b_portal",
"items": [
{"sku": "INJ-6.7-CR", "name": "6.7L Common-Rail Injector", "quantity": 8, "unitPrice": 289.50}
],
},
).json()["data"]{
"success": true,
"data": {
"id": "0c7b1a2d-4e5f-4a6b-9c8d-2e1f0a9b8c7d",
"orderNumber": "1042",
"status": "placed",
"paymentStatus": "unpaid",
"customerId": "8a1f0b2c-9d3e-4a5b-8c6d-1e2f3a4b5c6d",
"channel": "b2b_portal",
"currency": "USD",
"subtotal": 2316.00,
"shippingTotal": 0,
"discountTotal": 0,
"taxTotal": 0,
"total": 2316.00,
"items": [
{ "sku": "INJ-6.7-CR", "name": "6.7L Common-Rail Injector", "quantity": 8, "unitPrice": 289.50 }
],
"createdAt": "2026-06-05T17:41:09Z"
}
}{
"success": false,
"error": {
"code": "not_found",
"message": "Customer 8a1f0b2c-… was not found."
}
}