> Tychron Atlas API & Provisioning Reference — chapter 8 of 35 as Markdown. Web version: https://docs.tychron.com/api-reference/orders/ > Source: https://docs.tychron.com/api-reference/ · Updated 2026-08-12 · Generated from the Atlas OpenAPI spec (https://api.atlas.tychron.online/api/v1/openapi is the live contract; this file is a dated snapshot of it). > Source revision: atlas_api_reference_2026-08-12.md · sha256 482ebd3b014af053 · sanitize gate v1 clean · reconciled with OpenAPI 2026.8.25-p01 (spec sha256 cc049ef38c71cd6e) on 2026-09-05 · content last modified 2026-09-09 · newer definition under review since 2026-09-09 (not yet reconciled) > Scope: the Atlas platform API only. The SMS, MMS, CNAM, LRN and MCL services are separate APIs with their own specifications: https://docs.tychron.com/openapi/ > Machine index: https://docs.tychron.com/llms.txt # Orders When a Cart has undergone checkout, it will be treated as an Order. ## Schema An order that has been placed. Orders are a collection record for requests, a means by which requests are grouped together. Orders themselves do nothing after their checkout. __Type__ Object | Name | Type | Description | | ------------- | ---------------------------------------- | ------------------------------ | | `error_code` | [OrderErrorCode](https://docs.tychron.com/api-reference/schemas/#schema-ordererrorcode) | | | `id` | String(format:ulid) | [Desc. `id`](https://docs.tychron.com/api-reference/orders/#desc-68) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `name` | String(3..255) | [Desc. `name`](https://docs.tychron.com/api-reference/orders/#desc-69) | | `notes` | String(0..65535) | [Desc. `notes`](https://docs.tychron.com/api-reference/orders/#desc-70) | | `status` | [OrderStatus](https://docs.tychron.com/api-reference/schemas/#schema-orderstatus) | | | `updated_at` | String(format:date-time) | An ISO8601 formatted timestamp | #### Desc. `id` {#desc-68} Another format for UUID, used primarily for tasks, requests and messages. #### Desc. `name` {#desc-69} Display name for Order. #### Desc. `notes` {#desc-70} Any additional text about the order, useful for informing someone about the order's purpose. __Example__ ```json { "error_code": "OK", "id": "01EH2Y28M6KXG14QMPM3HSP1Y0", "inserted_at": "2021-08-13T04:08:44.762841Z", "name": "Add Messaging to 10 Numbers", "notes": "Order for Client XYZ\n", "status": "NEW", "updated_at": "2021-08-13T04:08:44.762841Z" } ``` ## API ### Updating An Existing Order ```http PATCH /api/v1/orders/{id} HTTP/1.1 ``` Update an existing order. Only the name and notes can be updated on the order once it has been checked out. __Path Parameters__ | Name | Type | Description | | ---- | ------- | ----------- | | id | String! | Order ID | #### Request application/json ```http PATCH /api/v1/orders/{id} HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 119 ``` ```json { "data": { "name": "Add Messaging to 10 Numbers", "notes": "Order for Client XYZ\n" }, "type": "order" } ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 303 ``` ```json { "data": { "error_code": "OK", "id": "01EH2Y28M6KXG14QMPM3HSP1Y0", "inserted_at": "2021-08-13T04:08:44.762841Z", "name": "Add Messaging to 10 Numbers", "notes": "Order for Client XYZ\n", "status": "NEW", "updated_at": "2021-08-13T04:08:44.762841Z" }, "type": "order" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### List Existing Orders ```http GET /api/v1/orders HTTP/1.1 ``` Retrieve a list of orders, ordered by descending order by inserted_at (i.e. most recent is first) __Query Parameters__ | Name | Type | Description | | ------ | ------- | ------------------------------ | | first | Integer | [Query Desc. first](https://docs.tychron.com/api-reference/orders/#desc-71) | | last | Integer | [Query Desc. last](https://docs.tychron.com/api-reference/orders/#desc-72) | | after | String | [Query Desc. after](https://docs.tychron.com/api-reference/orders/#desc-73) | | before | String | [Query Desc. before](https://docs.tychron.com/api-reference/orders/#desc-74) | #### Query Desc. first {#desc-71} The number of items to return starting from the 'after' cursor #### Query Desc. last {#desc-72} The number of items to return behind the 'before' cursor #### Query Desc. after {#desc-73} The cursor representing the starting point of a 'first' based paging #### Query Desc. before {#desc-74} The cursor representing the starting point of a 'last' based paging #### Request ```http GET /api/v1/orders HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 512 ``` ```json { "count": 1, "page_info": { "first": "string", "has_next_page": true, "has_previous_page": true, "last": "string" }, "results": [ { "data": { "error_code": "OK", "id": "01EH2Y28M6KXG14QMPM3HSP1Y0", "inserted_at": "2021-08-13T04:08:44.762841Z", "name": "Add Messaging to 10 Numbers", "notes": "Order for Client XYZ\n", "status": "NEW", "updated_at": "2021-08-13T04:08:44.762841Z" }, "type": "order" } ] } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### Get Order ```http GET /api/v1/orders/{id} HTTP/1.1 ``` Lookup an order by ID __Path Parameters__ | Name | Type | Description | | ---- | ------- | ----------- | | id | String! | Order ID | #### Request ```http GET /api/v1/orders/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 303 ``` ```json { "data": { "error_code": "OK", "id": "01EH2Y28M6KXG14QMPM3HSP1Y0", "inserted_at": "2021-08-13T04:08:44.762841Z", "name": "Add Messaging to 10 Numbers", "notes": "Order for Client XYZ\n", "status": "NEW", "updated_at": "2021-08-13T04:08:44.762841Z" }, "type": "order" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` --- Previous chapter: https://docs.tychron.com/api-reference/cart-request-documents.md Next chapter: https://docs.tychron.com/api-reference/requests.md Complete reference in one file: https://docs.tychron.com/llms-full.txt