> Tychron Atlas API & Provisioning Reference — chapter 5 of 35 as Markdown. Web version: https://docs.tychron.com/api-reference/ordering-system-reference/
> 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

# Ordering System Reference

This section will give a further explantation on Tychron's ordering APIs and provides examples of how to request numbers for messaging and other features.

## Ordering Overview

The client is expected to make several HTTP requests to the system in order to request provisioning numbers for messaging or to setup TCR campaigns on existing numbers.

A general overview of the workflow would be the following:

* `POST /api/v1/carts` once
* `POST /api/v1/carts/:cart_id/requests` one or more times
* `POST /api/v1/carts/:cart_id/checkout` once per cart

The ordering system is based around the concept of carts. 

A cart is an order before checkout, within that cart are various requests that can be made (e.g. enable this number for CNAM, enable this number for messaging, remove this number, etc...), an order can contain multiple requests, and some requests allow multiple numbers within them to perform batch processing.

__WARNING__ A request with multiple numbers is treated as a single unit for processing, each stage in the processing of a request will wait for the completion of **all** numbers, if a number in the batch experiences any difficulties (e.g. upstream conflicts with registry) it may stall the entire enablement until it is resolved, therefore it is recommended for critical numbers a request with only that number is issued, for non-critical numbers batching is recommended.

When in doubt, use a single number per request.

Requests are processed asynchronously, therefore checkout will return immediately with the order id (which will be the same as the cart, as it is the same record just being transitioned to a new state).

## Carts

At the very start of a new request process a new cart **must** be created (or if one was created before, it can be used instead).

### Type

The type string for carts is `cart`

### Data Structures

__RequestData__

```json
{
  "name": "A unique name",
  "notes": "Optional notes"
}
```

| Name     | Type     | Description                   |
| -------- | -------- | ----------------------------- |
| `name` * | `String` | A unique name for the cart    |
| `notes`  | `String` | Optional notes about the cart |

For creating or updating an existing cart, only the `name` and `notes` can be supplied.

__ResponseData__

```json
{
  "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "inserted_at": "2021-08-04T10:00:00.000000Z",
  "name": "An unique order name",
  "notes": "Optional notes, describing what this order is for",
  "updated_at": "2021-08-04T10:00:00.000000Z"
}
```

| Name            | Type       | Description                                                                 |
| --------------- | ---------- | --------------------------------------------------------------------------- |
| `id` *          | `ULID`     | A unique identfier for the cart                                             |
| `inserted_at` * | `Datetime` | An ISO8601 formatted timestamp, representing when the cart was created      |
| `updated_at` *  | `Datetime` | An ISO8601 formatted timestamp, representing when the cart was last updated |
| `name` *        | `String`   | A unique name for the cart                                                  |
| `notes`         | `String`   | Optional notes about the cart                                               |

### Creating A New Cart

```http
POST /api/v1/carts HTTP/1.1
```

Create a new cart


#### Request application/json

```http
POST /api/v1/carts HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 81
```

```json
{
  "data": {
    "name": "string",
    "notes": "string"
  },
  "type": "cart"
}
```

#### Response 201

##### application/json

```http
HTTP/1.1 201
Content-Type: application/json
Content-Length: 226
```

```json
{
  "data": {
    "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "name": "My New Order",
    "notes": "string",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "cart"
}
```
#### 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 422

##### application/json

```http
HTTP/1.1 422
Content-Type: application/json
Content-Length: 241
```

```json
{
  "errors": [
    {
      "code": "invalid_parameter",
      "detail": "The specified resource could not be found",
      "source": {
        "pointer": "/data/type"
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}
```


### Updating An Existing Cart

```http
PATCH /api/v1/carts/{id} HTTP/1.1
```

Update an existing account


__Path Parameters__

| Name | Type                 | Description |
| ---- | -------------------- | ----------- |
| id   | String(format:ulid)! | Cart ID     |

#### Request application/json

```http
PATCH /api/v1/carts/{id} HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 81
```

```json
{
  "data": {
    "name": "string",
    "notes": "string"
  },
  "type": "cart"
}
```

#### Response 200

##### application/json

```http
HTTP/1.1 200
Content-Type: application/json
Content-Length: 226
```

```json
{
  "data": {
    "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "name": "My New Order",
    "notes": "string",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "cart"
}
```
#### 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"
    }
  ]
}
```
#### Response 422

##### application/json

```http
HTTP/1.1 422
Content-Type: application/json
Content-Length: 241
```

```json
{
  "errors": [
    {
      "code": "invalid_parameter",
      "detail": "The specified resource could not be found",
      "source": {
        "pointer": "/data/type"
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}
```


### Deleting An Existing Cart

```http
DELETE /api/v1/carts/{id} HTTP/1.1
```

Delete an existing cart, if the cart contains any requests this action will fail, if the purge
flag is provided the cart will be deleted along with all of its requests.

The default action is to prevent accidental deletions with requests present.


__Path Parameters__

| Name | Type                 | Description |
| ---- | -------------------- | ----------- |
| id   | String(format:ulid)! | Cart ID     |

__Query Parameters__

| Name  | Type    | Description                  |
| ----- | ------- | ---------------------------- |
| purge | Boolean | [Query Desc. purge](https://docs.tychron.com/api-reference/ordering-system-reference/#desc-7) |

#### Query Desc. purge {#desc-7}

Typically a Cart cannot be removed if it has any requests still associated with it.

With the purge option, the cart and its associated requests can all be removed at once.

#### Request

```http
DELETE /api/v1/carts/{id} HTTP/1.1
Accept: application/json
```
#### Response 200

##### application/json

```http
HTTP/1.1 200
Content-Type: application/json
Content-Length: 226
```

```json
{
  "data": {
    "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "name": "My New Order",
    "notes": "string",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "cart"
}
```
#### 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"
    }
  ]
}
```
#### Response 422

##### application/json

```http
HTTP/1.1 422
Content-Type: application/json
Content-Length: 241
```

```json
{
  "errors": [
    {
      "code": "invalid_parameter",
      "detail": "The specified resource could not be found",
      "source": {
        "pointer": "/data/type"
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}
```


### Checkout Cart

```http
POST /api/v1/carts/{cart_id}/checkout HTTP/1.1
```

Finalize a given cart and process it as an order, the cart and its requests can no longer
be modified after this.


__Path Parameters__

| Name    | Type                 | Description |
| ------- | -------------------- | ----------- |
| cart_id | String(format:ulid)! | Cart ID     |

#### Request

```http
POST /api/v1/carts/{cart_id}/checkout 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"
    }
  ]
}
```
#### Response 422

##### application/json

```http
HTTP/1.1 422
Content-Type: application/json
Content-Length: 241
```

```json
{
  "errors": [
    {
      "code": "invalid_parameter",
      "detail": "The specified resource could not be found",
      "source": {
        "pointer": "/data/type"
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}
```


### List Existing Carts

```http
GET /api/v1/carts HTTP/1.1
```

Retrieve a list of carts


__Query Parameters__

| Name   | Type    | Description                    |
| ------ | ------- | ------------------------------ |
| first  | Integer | [Query Desc. first](https://docs.tychron.com/api-reference/ordering-system-reference/#desc-8)   |
| last   | Integer | [Query Desc. last](https://docs.tychron.com/api-reference/ordering-system-reference/#desc-9)    |
| after  | String  | [Query Desc. after](https://docs.tychron.com/api-reference/ordering-system-reference/#desc-10)  |
| before | String  | [Query Desc. before](https://docs.tychron.com/api-reference/ordering-system-reference/#desc-11) |

#### Query Desc. first {#desc-8}

The number of items to return starting from the 'after' cursor

#### Query Desc. last {#desc-9}

The number of items to return behind the 'before' cursor

#### Query Desc. after {#desc-10}

The cursor representing the starting point of a 'first' based paging

#### Query Desc. before {#desc-11}

The cursor representing the starting point of a 'last' based paging

#### Request

```http
GET /api/v1/carts HTTP/1.1
Accept: application/json
```
#### Response 200

##### application/json

```http
HTTP/1.1 200
Content-Type: application/json
Content-Length: 427
```

```json
{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "data": {
        "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "name": "My New Order",
        "notes": "string",
        "updated_at": "2021-08-13T04:08:44.762841Z"
      },
      "type": "cart"
    }
  ]
}
```
#### 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 Cart

```http
GET /api/v1/carts/{id} HTTP/1.1
```

Lookup cart by id


__Path Parameters__

| Name | Type                 | Description |
| ---- | -------------------- | ----------- |
| id   | String(format:ulid)! | Cart ID     |

#### Request

```http
GET /api/v1/carts/{id} HTTP/1.1
Accept: application/json
```
#### Response 200

##### application/json

```http
HTTP/1.1 200
Content-Type: application/json
Content-Length: 226
```

```json
{
  "data": {
    "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "name": "My New Order",
    "notes": "string",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "cart"
}
```
#### 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/number-inventory.md  
Next chapter: https://docs.tychron.com/api-reference/cart-requests.md  
Complete reference in one file: https://docs.tychron.com/llms-full.txt