Orders

Create, read, change, cancel and delete Exsited orders, quotes and contracts, with their lines, notes and billing.

An order is what an account buys: its lines, billing preferences, invoices and payments. This area creates and reads orders, quotes and contracts, changes their lines and billing, moves them through their states, and manages their notes and files. It has 60 endpoints, and every SDK supports all of them.

Only the preview endpoints are dry runs. Every other state change, such as upgrade, cancel or discard_draft, takes effect at once. Discarding a draft removes it, so the order can no longer be read.

At a glance

Endpoint	Method	Path	What it does
List orders	GET	/orders	Lists orders, one page at a time.
Create an order	POST	/orders	Creates an order for an account and returns it under order.
Retrieve an order	GET	/orders/{order_id}	Returns one order with its lines, totals and KPIs, under order.
Delete an order	DELETE	/orders/{order_id}	Deletes an order and returns no content.
Activate an order	POST	/orders/{order_id}/activate	Activates an order from the date you give.
Activate a draft order	POST	/orders/{order_id}/activate_draft	Activates a draft order, such as a quote, and returns it under order.
Retrieve an order’s billing preferences	GET	/orders/{order_id}/billing_preferences	Returns an order’s billing preferences, under order.billing_preferences.
Update an order’s billing preferences	PATCH	/orders/{order_id}/billing_preferences	Changes some of an order’s billing preferences and returns the order under order.
Replace an order’s billing preferences	PUT	/orders/{order_id}/billing_preferences	Sets an order’s billing preferences with PUT and returns the order under order.
Cancel an order	POST	/orders/{order_id}/cancel	Cancels an order from the date you give and returns it under order.
Change an order’s lines	POST	/orders/{order_id}/change	Adds, changes or removes order lines from a date and returns the order under order.
Convert a quote to an order	POST	/orders/{order_id}/convert_to_order	Turns a quote into a new regular order and returns the new order under order.
List an order’s custom objects	GET	/orders/{order_id}/custom_objects	Lists the custom objects attached to an order, one page at a time.
List an order’s custom objects (instances path)	GET	/orders/{order_id}/custom_objects_instances	Lists an order’s custom objects through the custom_objects_instances path, one page at a time.
Discard a draft order	POST	/orders/{order_id}/discard_draft	Discards a draft order, such as a quote, and returns a message under order.
Extend an order’s trial	POST	/orders/{order_id}/extend_trial	Sets a new trial window on a contract order and returns a message under order.
Retrieve an order’s information	GET	/orders/{order_id}/information	Returns an order’s header information without its lines, under order.
Update an order’s information	PATCH	/orders/{order_id}/information	Changes an order’s header information and returns the order under order.
List an order’s fulfillments	GET	/orders/{order_id}/item_fulfillments	Lists the item fulfillments of an order, one page at a time.
List an order’s lines	GET	/orders/{order_id}/lines	Returns an order with its lines, under order.lines.
List an order’s notes	GET	/orders/{order_id}/notes	Lists the notes on an order, one page at a time.
Create an order note	POST	/orders/{order_id}/notes	Adds a note to an order, with an optional file, and returns it under note.
List an order’s payment methods	GET	/orders/{order_id}/payment_methods	Returns the payment methods set aside for an order, under order.payment_methods.
Retrieve an order’s PDF	GET	/orders/{order_id}/pdf	Returns a link to the order’s PDF, under order.pdf.
Reactivate an order	POST	/orders/{order_id}/reactivate	Brings a cancelled order back from the date you give and returns it under order.
Relinquish an order	POST	/orders/{order_id}/relinquish	Relinquishes an order from the date you give and returns it under order.
Update an order line	PATCH	/orders/{order_id}/lines/{line_uuid}	Changes one line’s information and returns the order under order.
Retrieve an order line	GET	/orders/{order_id}/lines/{line_uuid}	Returns one line of an order, under order_line.
Delete an order note	DELETE	/orders/{order_id}/notes/{order_note_id}	Deletes a note from an order and returns no content.
Retrieve an order note	GET	/orders/{order_id}/notes/{order_note_id}	Returns one note on an order, under note.
Update an order note	PATCH	/orders/{order_id}/notes/{order_note_id}	Replaces a note’s text, with an optional file, and returns it under note.
Retrieve an order’s payment method	GET	/orders/{order_id}/payment_methods/{payment_method_ref}	Returns one payment method set aside for an order, under order.payment_method.
Update an order line’s billing preferences	PATCH	/orders/{order_id}/lines/{line_uuid}/billing_preferences	Changes one line’s billing settings and returns the order under order.
Replace an order line’s billing preferences	PUT	/orders/{order_id}/lines/{line_uuid}/billing_preferences	Sets one line’s billing settings with PUT and returns the order under order.
List an order note’s files	GET	/orders/{order_id}/notes/{order_note_id}/files	Lists the files attached to an order note, one page at a time.
Retrieve an order note file	GET	/orders/{order_id}/notes/{order_note_id}/files/{order_file_id}	Returns one file attached to an order note, under file.
List notes across all orders	GET	/orders/notes	Lists the notes of every order, one page at a time.
Preview an order	POST	/orders/preview	Checks an order body without creating the order.
Create an order through the express path	POST	/orders/express	Creates an order, and its invoice and payment if the body nests them, in one call.
Accept an order	POST	/orders/{order_id}/accept	Accepts an order that is waiting for customer acceptance.
Activate a dormant invoice	POST	/orders/{order_id}/activate_invoice_from_dormant/{invoice_uuid}	Activates one of an order’s dormant invoices with a due date and an amount.
Preview an order change	POST	/orders/{order_id}/change/preview	Checks a line change without making it and returns the order as it stands.
Change an order’s workflow status	POST	/orders/{order_id}/change_status	Moves an order to a workflow state and runs that workflow’s connections.
Adjust an order’s contract	POST	/orders/{order_id}/contract_adjustment	Upgrades or downgrades a contract’s lines by package rank from a date.
Preview a contract adjustment	POST	/orders/{order_id}/contract_adjustment/preview	Checks a contract adjustment without making it.
Downgrade an order	POST	/orders/{order_id}/downgrade	Moves a contract’s lines to a lower package from a date.
Preview an order downgrade	POST	/orders/{order_id}/downgrade/preview	Checks a downgrade without making it.
Upgrade an order	POST	/orders/{order_id}/upgrade	Moves a contract’s lines to a higher package from a date.
Preview an order upgrade	POST	/orders/{order_id}/upgrade/preview	Checks an upgrade without making it.
End an order’s trial	POST	/orders/{order_id}/terminate_trial	Ends a contract’s trial now, which starts the contract.
Delete an order note file	DELETE	/orders/{order_id}/notes/{order_note_id}/files/{order_file_id}	Deletes one file from an order note and returns no content.
Retrieve an order’s custom object	GET	/orders/{order_id}/custom_objects/{custom_object_id}	Returns one custom object with the order’s instances of it, under custom_object.
Retrieve an order’s custom object instance	GET	/orders/{order_id}/custom_objects/{custom_object_id}/instances/{instance_id}	Returns one instance of a custom object on an order.
Retrieve an order’s custom object (instances path)	GET	/orders/{order_id}/custom_objects_instances/{custom_object_id}	Returns one custom object with the order’s instances of it, under custom_object, through the custom_objects_instances path.
Retrieve an order’s custom object instance (instances path)	GET	/orders/{order_id}/custom_objects_instances/{custom_object_id}/instances/{instance_id}	Returns one instance of a custom object on an order, through the custom_objects_instances path.
Retrieve an order fulfillment	GET	/orders/{order_id}/item_fulfillments/{fulfillment_id}	Returns one item fulfillment, under item_fulfillment.
Retrieve an order’s KPIs	GET	/orders/{order_id}/kpis	Returns an order’s key figures, such as revenue and amounts due, under order_kpis.
Retrieve an order payment	GET	/orders/{order_id}/payments/{payment_id}	Returns one payment, under payment.
List a quote’s partial invoices	GET	/orders/{order_id}/quote_partial_invoices	Returns the deposit and instalment invoices of a converted quote, under order.partial_invoices.
Retrieve a shipping line’s PDF	GET	/orders/{order_id}/shipping_pdf/{shipping_line_id}	Returns the PDF of one of an order’s shipping lines.

Before you call

Register your API credentials once when your app starts, as shown in Authentication. Every SDK sample on these pages then gets its client in one line. With cURL, send the access token in an Authorization header: Authorization: Bearer $ACCESS_TOKEN.

Things to know

• Most order bodies go under order. The exceptions are upgrade, downgrade, contract_adjustment and their previews (effective_date and lines at the top level), the dormant invoice call (activate), the express call (account), and the note calls, which take a multipart form.
• A contract needs a recurring or metered item on a line. Set allow_contract to true and send contract_properties when you create the order.
• Lines are named two ways. Line paths take the line’s id as line_uuid; a change body names a line by its charge_item_uuid, sent as uuid.
• Previewing an order can still create an account. POST /orders/preview creates no order, but a body that names a new account creates that account.
• Payments and fulfillments are not checked against the order. GET /orders/{order_id}/payments/{payment_id} and .../item_fulfillments/{fulfillment_id} read the record by its own id.
• Listings page by cursor. Send limit, then pass pagination.next_cursor as cursor while pagination.has_more is true.