> For the complete documentation index, see [llms.txt](https://hub.equipme.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hub.equipme.io/development/api-reference-pro/sales-or-orders.md).
# Sales | Orders
## List sales orders of your customers
> Sales orders contain one or more items representing orders for new services and cancellations or changes to existing service instances (subscriptions).\
> \
> This route is primarily for controlling. To fulfill these items please see \fulfillment orders route\.\
> \
> You can only access orders of customers of your provider entity.\
> \`items\` carries the number and the price sums of the order items you deliver; retrieve the order to get the items.\
> status selects orders; it does not change which items are counted or summed.
```json
{"openapi":"3.0.4","info":{"title":"Equipme Supplier API","version":"v1"},"tags":[{"name":"Sales | Orders"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"SalesOrderStatus":{"enum":["unknown","new","inprocess","processed","cancelled"],"type":"string","description":"Status of an order / order item"},"SalesOrderList":{"required":["items","self","total"],"type":"object","properties":{"previous":{"$ref":"#/components/schemas/ResourceLink"},"next":{"$ref":"#/components/schemas/ResourceLink"},"items":{"type":"array","items":{"$ref":"#/components/schemas/SalesOrder"}},"total":{"type":"integer","format":"int32"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ResourceLink":{"type":"object","properties":{"href":{"type":"string","nullable":true},"method":{"type":"string","nullable":true}},"additionalProperties":false},"SalesOrder":{"required":["created","customer","id","items","orderedBy","orderNumber","self","status"],"type":"object","properties":{"status":{"$ref":"#/components/schemas/SalesOrderStatus"},"customer":{"$ref":"#/components/schemas/CustomerReference"},"note":{"type":"string","description":"Note the customer can add to their order in a html format.","nullable":true},"orderedBy":{"$ref":"#/components/schemas/UserReference"},"accountManager":{"$ref":"#/components/schemas/EmployeeReference"},"items":{"$ref":"#/components/schemas/SalesOrderItemListReference"},"id":{"type":"integer","description":"The identifier of the order is also the order number.","format":"int64"},"customerOrderNumber":{"maxLength":100,"minLength":0,"type":"string","description":"Order reference number from the customer","nullable":true},"orderNumber":{"minLength":1,"type":"string","description":"Unique reference number of the sales order."},"created":{"type":"string","description":"The date and time when the order was placed. (ISO 8601 format)","format":"date-time"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"CustomerReference":{"required":["id","name","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the customer.","format":"int32"},"name":{"minLength":1,"type":"string","description":"The name of the customer."},"customerNumber":{"type":"string","description":"Optional identifier of the customer defined by the supplier.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"UserReference":{"required":["self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the employee.","format":"int32"},"firstName":{"type":"string","description":"The first/given name of the employee.","nullable":true},"lastName":{"type":"string","description":"The last/family name of the employee.","nullable":true},"email":{"type":"string","description":"The contact and login mail address.","nullable":true},"username":{"type":"string","description":"The username to log in to the app. The value has to be an e-mail address.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"EmployeeReference":{"required":["id","self","username"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the employee.","format":"int32"},"firstName":{"maxLength":100,"minLength":0,"type":"string","description":"The first/given name of the employee.","nullable":true},"lastName":{"maxLength":100,"minLength":0,"type":"string","description":"The last/family name of the employee.","nullable":true},"fullName":{"maxLength":150,"minLength":0,"type":"string","description":"Combination of last and firstname","nullable":true,"readOnly":true},"email":{"maxLength":100,"minLength":0,"type":"string","description":"The contact and login mail address.","nullable":true},"username":{"maxLength":100,"minLength":0,"pattern":"^[a-zA-Z0-9.!#$%&’*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\\.[a-zA-Z0-9-]+)*\\.[a-zA-Z]{2,}$","type":"string","description":"The username to log in to the app. The value has to be an e-mail address."},"costCenter":{"maxLength":100,"minLength":0,"type":"string","description":"The cost center of the employee.","nullable":true},"costCenterId":{"type":"integer","description":"The identifier of the cost center.","format":"int32","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"SalesOrderItemListReference":{"required":["self","total"],"type":"object","properties":{"oneTimePrice":{"type":"number","description":"Sum of the one-time prices of the order items you deliver, without cancelled items.\nNull if these items have different currencies.","format":"double","nullable":true},"recurringPrice":{"type":"number","description":"Sum of the recurring prices of the order items you deliver, without cancelled items.\nNull if these items have different currencies.","format":"double","nullable":true},"currencyCode":{"type":"string","description":"Currency code of the price sums (ISO 4217). Null if the summed items have different currencies or none of them has one.","nullable":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/SalesOrderItem"},"description":"The order items you deliver. Only present on the single sales order route.","nullable":true},"total":{"type":"integer","format":"int32"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"SalesOrderItem":{"required":["id","oneTimePrice","recurringPrice","status","transactionType"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the order item.","format":"int64"},"name":{"type":"string","description":"Name of the ordered service.","nullable":true},"transactionType":{"$ref":"#/components/schemas/SalesOrderItemTransactionType"},"offer":{"$ref":"#/components/schemas/ResourceReference_Int32"},"status":{"$ref":"#/components/schemas/SalesOrderStatus"},"oneTimePrice":{"type":"number","description":"One-time price of the ordered offer including its ordered options.","format":"double"},"recurringPrice":{"type":"number","description":"Recurring price of the ordered offer including its ordered options.","format":"double"},"currencyCode":{"type":"string","description":"Currency code of the prices (ISO 4217).","nullable":true},"subscription":{"$ref":"#/components/schemas/ResourceReference_Int32"}},"additionalProperties":false},"SalesOrderItemTransactionType":{"enum":["order","change","cancellation","unknown"],"type":"string"},"ResourceReference_Int32":{"required":["id","self"],"type":"object","properties":{"id":{"type":"integer","format":"int32"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/sales/orders":{"get":{"tags":["Sales | Orders"],"summary":"List sales orders of your customers","description":"Sales orders contain one or more items representing orders for new services and cancellations or changes to existing service instances (subscriptions).\n\nThis route is primarily for controlling. To fulfill these items please see fulfillment orders route.\n\nYou can only access orders of customers of your provider entity.\n`items` carries the number and the price sums of the order items you deliver; retrieve the order to get the items.\nstatus selects orders; it does not change which items are counted or summed.","parameters":[{"name":"customers","in":"query","description":"Filter the orders by one or more customer ids or names.","schema":{"type":"array","items":{"type":"integer","format":"int32"}}},{"name":"status","in":"query","description":"Filter the orders by their status. An order's status is derived from the items you deliver.","schema":{"type":"array","items":{"$ref":"#/components/schemas/SalesOrderStatus"}}},{"name":"after","in":"query","description":"Filter the orders created after the specified date.","schema":{"type":"string","format":"date-time"}},{"name":"before","in":"query","description":"Filter the orders created before the specified date.","schema":{"type":"string","format":"date-time"}},{"name":"sortBy","in":"query","description":"Sort the results by a given criterion (customer|date).","schema":{"type":"string","default":"date"}},{"name":"sortOrder","in":"query","description":"Sort the results in a given order (asc|desc).","schema":{"type":"string","default":"desc"}},{"name":"offset","in":"query","description":"Specifies the index of the first result to return","schema":{"type":"integer","format":"int32","default":0}},{"name":"limit","in":"query","description":"Specifies the maximum number of results to return (min: 1; max: 1000)","schema":{"type":"integer","format":"int32","default":100}}],"responses":{"200":{"description":"OK: List of orders.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesOrderList"}}}},"400":{"description":"Bad request: See response message for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized: Invalid api key or expired access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: Resource access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Retrieve a single sales order by its id.
> Contains the order items you deliver.
```json
{"openapi":"3.0.4","info":{"title":"Equipme Supplier API","version":"v1"},"tags":[{"name":"Sales | Orders"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"SalesOrder":{"required":["created","customer","id","items","orderedBy","orderNumber","self","status"],"type":"object","properties":{"status":{"$ref":"#/components/schemas/SalesOrderStatus"},"customer":{"$ref":"#/components/schemas/CustomerReference"},"note":{"type":"string","description":"Note the customer can add to their order in a html format.","nullable":true},"orderedBy":{"$ref":"#/components/schemas/UserReference"},"accountManager":{"$ref":"#/components/schemas/EmployeeReference"},"items":{"$ref":"#/components/schemas/SalesOrderItemListReference"},"id":{"type":"integer","description":"The identifier of the order is also the order number.","format":"int64"},"customerOrderNumber":{"maxLength":100,"minLength":0,"type":"string","description":"Order reference number from the customer","nullable":true},"orderNumber":{"minLength":1,"type":"string","description":"Unique reference number of the sales order."},"created":{"type":"string","description":"The date and time when the order was placed. (ISO 8601 format)","format":"date-time"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"SalesOrderStatus":{"enum":["unknown","new","inprocess","processed","cancelled"],"type":"string","description":"Status of an order / order item"},"CustomerReference":{"required":["id","name","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the customer.","format":"int32"},"name":{"minLength":1,"type":"string","description":"The name of the customer."},"customerNumber":{"type":"string","description":"Optional identifier of the customer defined by the supplier.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ResourceLink":{"type":"object","properties":{"href":{"type":"string","nullable":true},"method":{"type":"string","nullable":true}},"additionalProperties":false},"UserReference":{"required":["self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the employee.","format":"int32"},"firstName":{"type":"string","description":"The first/given name of the employee.","nullable":true},"lastName":{"type":"string","description":"The last/family name of the employee.","nullable":true},"email":{"type":"string","description":"The contact and login mail address.","nullable":true},"username":{"type":"string","description":"The username to log in to the app. The value has to be an e-mail address.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"EmployeeReference":{"required":["id","self","username"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the employee.","format":"int32"},"firstName":{"maxLength":100,"minLength":0,"type":"string","description":"The first/given name of the employee.","nullable":true},"lastName":{"maxLength":100,"minLength":0,"type":"string","description":"The last/family name of the employee.","nullable":true},"fullName":{"maxLength":150,"minLength":0,"type":"string","description":"Combination of last and firstname","nullable":true,"readOnly":true},"email":{"maxLength":100,"minLength":0,"type":"string","description":"The contact and login mail address.","nullable":true},"username":{"maxLength":100,"minLength":0,"pattern":"^[a-zA-Z0-9.!#$%&’*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\\.[a-zA-Z0-9-]+)*\\.[a-zA-Z]{2,}$","type":"string","description":"The username to log in to the app. The value has to be an e-mail address."},"costCenter":{"maxLength":100,"minLength":0,"type":"string","description":"The cost center of the employee.","nullable":true},"costCenterId":{"type":"integer","description":"The identifier of the cost center.","format":"int32","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"SalesOrderItemListReference":{"required":["self","total"],"type":"object","properties":{"oneTimePrice":{"type":"number","description":"Sum of the one-time prices of the order items you deliver, without cancelled items.\nNull if these items have different currencies.","format":"double","nullable":true},"recurringPrice":{"type":"number","description":"Sum of the recurring prices of the order items you deliver, without cancelled items.\nNull if these items have different currencies.","format":"double","nullable":true},"currencyCode":{"type":"string","description":"Currency code of the price sums (ISO 4217). Null if the summed items have different currencies or none of them has one.","nullable":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/SalesOrderItem"},"description":"The order items you deliver. Only present on the single sales order route.","nullable":true},"total":{"type":"integer","format":"int32"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"SalesOrderItem":{"required":["id","oneTimePrice","recurringPrice","status","transactionType"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the order item.","format":"int64"},"name":{"type":"string","description":"Name of the ordered service.","nullable":true},"transactionType":{"$ref":"#/components/schemas/SalesOrderItemTransactionType"},"offer":{"$ref":"#/components/schemas/ResourceReference_Int32"},"status":{"$ref":"#/components/schemas/SalesOrderStatus"},"oneTimePrice":{"type":"number","description":"One-time price of the ordered offer including its ordered options.","format":"double"},"recurringPrice":{"type":"number","description":"Recurring price of the ordered offer including its ordered options.","format":"double"},"currencyCode":{"type":"string","description":"Currency code of the prices (ISO 4217).","nullable":true},"subscription":{"$ref":"#/components/schemas/ResourceReference_Int32"}},"additionalProperties":false},"SalesOrderItemTransactionType":{"enum":["order","change","cancellation","unknown"],"type":"string"},"ResourceReference_Int32":{"required":["id","self"],"type":"object","properties":{"id":{"type":"integer","format":"int32"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/sales/orders/{orderId}":{"get":{"tags":["Sales | Orders"],"summary":"Retrieve a single sales order by its id.","description":"Contains the order items you deliver.","parameters":[{"name":"orderId","in":"path","description":"The identifier of the sales order.","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK: The requested sales order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesOrder"}}}},"400":{"description":"Bad request: See response message for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized: Invalid api key or expired access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: Resource access denied or the order contains no items you deliver.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Set or clear your account manager on a sales order.
> The only patchable path is \`/accountManagerId\`: an employee of your provider entity, or \`null\` to clear it.\
> Every change is recorded in the account manager history; setting the current value again records nothing.
```json
{"openapi":"3.0.4","info":{"title":"Equipme Supplier API","version":"v1"},"tags":[{"name":"Sales | Orders"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"Operation":{"type":"object","properties":{"value":{"nullable":true},"path":{"type":"string","nullable":true},"op":{"type":"string","nullable":true},"from":{"type":"string","nullable":true}},"additionalProperties":false},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/sales/orders/{orderId}":{"patch":{"tags":["Sales | Orders"],"summary":"Set or clear your account manager on a sales order.","description":"The only patchable path is `/accountManagerId`: an employee of your provider entity, or `null` to clear it.\nEvery change is recorded in the account manager history; setting the current value again records nothing.","parameters":[{"name":"orderId","in":"path","description":"The identifier of the sales order.","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"description":"The JSON patch operations.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Operation"}}}}},"responses":{"204":{"description":"NoContent: The account manager has been set."},"400":{"description":"Bad request: See response message for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized: Invalid api key or expired access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: Resource access denied or the order contains no items you deliver.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://hub.equipme.io/development/api-reference-pro/sales-or-orders.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.