> ## Documentation Index
> Fetch the complete documentation index at: https://exsited.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

> [!WARNING]
>
> **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](https://exsited.mintlify.site/api-reference/orders/list-orders.md) | GET | `/orders` | Lists orders, one page at a time. |
| [Create an order](https://exsited.mintlify.site/api-reference/orders/create-an-order.md) | POST | `/orders` | Creates an order for an account and returns it under `order`. |
| [Retrieve an order](https://exsited.mintlify.site/api-reference/orders/retrieve-an-order.md) | GET | `/orders/{order_id}` | Returns one order with its lines, totals and KPIs, under `order`. |
| [Delete an order](https://exsited.mintlify.site/api-reference/orders/delete-an-order.md) | DELETE | `/orders/{order_id}` | Deletes an order and returns no content. |
| [Activate an order](https://exsited.mintlify.site/api-reference/orders/activate-an-order.md) | POST | `/orders/{order_id}/activate` | Activates an order from the date you give. |
| [Activate a draft order](https://exsited.mintlify.site/api-reference/orders/activate-a-draft-order.md) | 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](https://exsited.mintlify.site/api-reference/orders/retrieve-an-orders-billing-preferences.md) | GET | `/orders/{order_id}/billing_preferences` | Returns an order's billing preferences, under `order.billing_preferences`. |
| [Update an order's billing preferences](https://exsited.mintlify.site/api-reference/orders/update-an-orders-billing-preferences.md) | 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](https://exsited.mintlify.site/api-reference/orders/replace-an-orders-billing-preferences.md) | PUT | `/orders/{order_id}/billing_preferences` | Sets an order's billing preferences with `PUT` and returns the order under `order`. |
| [Cancel an order](https://exsited.mintlify.site/api-reference/orders/cancel-an-order.md) | POST | `/orders/{order_id}/cancel` | Cancels an order from the date you give and returns it under `order`. |
| [Change an order's lines](https://exsited.mintlify.site/api-reference/orders/change-an-orders-lines.md) | 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](https://exsited.mintlify.site/api-reference/orders/convert-a-quote-to-an-order.md) | 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](https://exsited.mintlify.site/api-reference/orders/list-an-orders-custom-objects.md) | 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)](https://exsited.mintlify.site/api-reference/orders/list-an-orders-custom-objects-instances-path.md) | 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](https://exsited.mintlify.site/api-reference/orders/discard-a-draft-order.md) | 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](https://exsited.mintlify.site/api-reference/orders/extend-an-orders-trial.md) | 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](https://exsited.mintlify.site/api-reference/orders/retrieve-an-orders-information.md) | GET | `/orders/{order_id}/information` | Returns an order's header information without its lines, under `order`. |
| [Update an order's information](https://exsited.mintlify.site/api-reference/orders/update-an-orders-information.md) | PATCH | `/orders/{order_id}/information` | Changes an order's header information and returns the order under `order`. |
| [List an order's fulfillments](https://exsited.mintlify.site/api-reference/orders/list-an-orders-fulfillments.md) | GET | `/orders/{order_id}/item_fulfillments` | Lists the item fulfillments of an order, one page at a time. |
| [List an order's lines](https://exsited.mintlify.site/api-reference/orders/list-an-orders-lines.md) | GET | `/orders/{order_id}/lines` | Returns an order with its lines, under `order.lines`. |
| [List an order's notes](https://exsited.mintlify.site/api-reference/orders/list-an-orders-notes.md) | GET | `/orders/{order_id}/notes` | Lists the notes on an order, one page at a time. |
| [Create an order note](https://exsited.mintlify.site/api-reference/orders/create-an-order-note.md) | 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](https://exsited.mintlify.site/api-reference/orders/list-an-orders-payment-methods.md) | GET | `/orders/{order_id}/payment_methods` | Returns the payment methods set aside for an order, under `order.payment_methods`. |
| [Retrieve an order's PDF](https://exsited.mintlify.site/api-reference/orders/retrieve-an-orders-pdf.md) | GET | `/orders/{order_id}/pdf` | Returns a link to the order's PDF, under `order.pdf`. |
| [Reactivate an order](https://exsited.mintlify.site/api-reference/orders/reactivate-an-order.md) | POST | `/orders/{order_id}/reactivate` | Brings a cancelled order back from the date you give and returns it under `order`. |
| [Relinquish an order](https://exsited.mintlify.site/api-reference/orders/relinquish-an-order.md) | POST | `/orders/{order_id}/relinquish` | Relinquishes an order from the date you give and returns it under `order`. |
| [Update an order line](https://exsited.mintlify.site/api-reference/orders/update-an-order-line.md) | PATCH | `/orders/{order_id}/lines/{line_uuid}` | Changes one line's information and returns the order under `order`. |
| [Retrieve an order line](https://exsited.mintlify.site/api-reference/orders/retrieve-an-order-line.md) | GET | `/orders/{order_id}/lines/{line_uuid}` | Returns one line of an order, under `order_line`. |
| [Delete an order note](https://exsited.mintlify.site/api-reference/orders/delete-an-order-note.md) | DELETE | `/orders/{order_id}/notes/{order_note_id}` | Deletes a note from an order and returns no content. |
| [Retrieve an order note](https://exsited.mintlify.site/api-reference/orders/retrieve-an-order-note.md) | GET | `/orders/{order_id}/notes/{order_note_id}` | Returns one note on an order, under `note`. |
| [Update an order note](https://exsited.mintlify.site/api-reference/orders/update-an-order-note.md) | 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](https://exsited.mintlify.site/api-reference/orders/retrieve-an-orders-payment-method.md) | 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](https://exsited.mintlify.site/api-reference/orders/update-an-order-lines-billing-preferences.md) | 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](https://exsited.mintlify.site/api-reference/orders/replace-an-order-lines-billing-preferences.md) | 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](https://exsited.mintlify.site/api-reference/orders/list-an-order-notes-files.md) | 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](https://exsited.mintlify.site/api-reference/orders/retrieve-an-order-note-file.md) | 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](https://exsited.mintlify.site/api-reference/orders/list-notes-across-all-orders.md) | GET | `/orders/notes` | Lists the notes of every order, one page at a time. |
| [Preview an order](https://exsited.mintlify.site/api-reference/orders/preview-an-order.md) | POST | `/orders/preview` | Checks an order body without creating the order. |
| [Create an order through the express path](https://exsited.mintlify.site/api-reference/orders/create-an-order-through-the-express-path.md) | POST | `/orders/express` | Creates an order, and its invoice and payment if the body nests them, in one call. |
| [Accept an order](https://exsited.mintlify.site/api-reference/orders/accept-an-order.md) | POST | `/orders/{order_id}/accept` | Accepts an order that is waiting for customer acceptance. |
| [Activate a dormant invoice](https://exsited.mintlify.site/api-reference/orders/activate-a-dormant-invoice.md) | 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](https://exsited.mintlify.site/api-reference/orders/preview-an-order-change.md) | 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](https://exsited.mintlify.site/api-reference/orders/change-an-orders-workflow-status.md) | POST | `/orders/{order_id}/change_status` | Moves an order to a workflow state and runs that workflow's connections. |
| [Adjust an order's contract](https://exsited.mintlify.site/api-reference/orders/adjust-an-orders-contract.md) | POST | `/orders/{order_id}/contract_adjustment` | Upgrades or downgrades a contract's lines by package rank from a date. |
| [Preview a contract adjustment](https://exsited.mintlify.site/api-reference/orders/preview-a-contract-adjustment.md) | POST | `/orders/{order_id}/contract_adjustment/preview` | Checks a contract adjustment without making it. |
| [Downgrade an order](https://exsited.mintlify.site/api-reference/orders/downgrade-an-order.md) | POST | `/orders/{order_id}/downgrade` | Moves a contract's lines to a lower package from a date. |
| [Preview an order downgrade](https://exsited.mintlify.site/api-reference/orders/preview-an-order-downgrade.md) | POST | `/orders/{order_id}/downgrade/preview` | Checks a downgrade without making it. |
| [Upgrade an order](https://exsited.mintlify.site/api-reference/orders/upgrade-an-order.md) | POST | `/orders/{order_id}/upgrade` | Moves a contract's lines to a higher package from a date. |
| [Preview an order upgrade](https://exsited.mintlify.site/api-reference/orders/preview-an-order-upgrade.md) | POST | `/orders/{order_id}/upgrade/preview` | Checks an upgrade without making it. |
| [End an order's trial](https://exsited.mintlify.site/api-reference/orders/end-an-orders-trial.md) | POST | `/orders/{order_id}/terminate_trial` | Ends a contract's trial now, which starts the contract. |
| [Delete an order note file](https://exsited.mintlify.site/api-reference/orders/delete-an-order-note-file.md) | 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](https://exsited.mintlify.site/api-reference/orders/retrieve-an-orders-custom-object.md) | 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](https://exsited.mintlify.site/api-reference/orders/retrieve-an-orders-custom-object-instance.md) | 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)](https://exsited.mintlify.site/api-reference/orders/retrieve-an-orders-custom-object-instances-path.md) | 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)](https://exsited.mintlify.site/api-reference/orders/retrieve-an-orders-custom-object-instance-instances-path.md) | 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](https://exsited.mintlify.site/api-reference/orders/retrieve-an-order-fulfillment.md) | GET | `/orders/{order_id}/item_fulfillments/{fulfillment_id}` | Returns one item fulfillment, under `item_fulfillment`. |
| [Retrieve an order's KPIs](https://exsited.mintlify.site/api-reference/orders/retrieve-an-orders-kpis.md) | GET | `/orders/{order_id}/kpis` | Returns an order's key figures, such as revenue and amounts due, under `order_kpis`. |
| [Retrieve an order payment](https://exsited.mintlify.site/api-reference/orders/retrieve-an-order-payment.md) | GET | `/orders/{order_id}/payments/{payment_id}` | Returns one payment, under `payment`. |
| [List a quote's partial invoices](https://exsited.mintlify.site/api-reference/orders/list-a-quotes-partial-invoices.md) | 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](https://exsited.mintlify.site/api-reference/orders/retrieve-a-shipping-lines-pdf.md) | 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](https://exsited.mintlify.site/authentication.md). 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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.