> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://customix.crisp.help/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# APIs for Developers

The **Customix Integrations API** lets you pull your personalized orders into your own systems — the print files Customix generated and everything your customers entered while personalizing, such as names, custom text, colors and chosen layouts. Reach for it when a production tool, a spreadsheet or an automation platform like Make needs your order details without anyone copying them by hand.

To get an API key, go to **Settings** in the left sidebar, open the **Integrations** tab, then click **Create key** in the **API Key** card. See [How can get Customix API key](/en/article/how-can-get-customix-api-key-h9s04f/) for the details.

> 📌 Only the store's account owner can create, reset or delete the API key, and the key is shown only once — keep a record of it right away.

> ⚠️ If the **Create key** button is locked, API access isn't included in your current plan. Upgrade to **Elite** to use it.

# 🔑 Authentication

All requests require your API key in the header:

```
Authorization: Bearer <your_api_key>
```

# 🌐 Base URL

```
https://app.customix.io/api/integrations/v1
```

# 📘 Endpoints

### 1. Get List of Orders

**Endpoint:**

```
GET /orders
```

**Description:** Fetch your personalized orders, newest first by default.

**Parameters:**

| Parameter | Type | Required | Description |
| ---- |
| `shop` | string | ✅ | Shopify store name. If your store URL is abcdef.myshopify.com, then shop=abcdef |
| `limit` | integer | ⬜ | Default is 50, maximum value is 250 |
| `created_at_min` | date | ⬜ | Show orders created at or after this date (format: 2025-01-21) |
| `created_at_max` | date | ⬜ | Show orders created at or before this date (format: 2025-01-30) |
| `order_status` | string | ⬜ | **created**: show only open orders. **paid**: show only paid orders. **fulfilled**: show only fulfilled orders. |
| `order_by` | string | ⬜ | Default is 'ordered\_at desc'. It can also be 'ordered\_at asc', 'id asc' or 'id desc' |

**Headers:**

| Header | Value |
| ---- |
| `Authorization` | Bearer API\_KEY |

**Example request:**

```
GET https://app.customix.io/api/integrations/v1/orders?shop=abcdef&limit=2
```

**Response:**

```json
{
  "data": [
    {
      "shop": "abcdef.myshopify.com",
      "order_id": 123456789,
      "order_number": "#1001",
      "currency": "USD",
      "customer": "John Doe",
      "email": "john@example.com",
      "ip": "123.123.123.123",
      "total_price": 123.45,
      "financial_status": "paid",
      "fulfillment_status": "fulfilled",
      "ordered_at": "2025-01-21 01:01:01",
      "customizations": [
        {
          "id": "01jjavmg7t7vqj5z6qvxwie14b",
          "public_customization_id": "01jjavmg7t7vqj5z6qvxwpc9kd",
          "campaign_id": "01jphjdfmtxhaio94h0wd0kv0c",
          "shopify_line_item_id": 11106133639222,
          "shopify_product_id": 11179841648222,
          "shopify_variant_id": 11191300929074,
          "platform": "shopify",
          "line_item_quantity": 1,
          "files": [
            {
              "id": "01jb3092vabc7m8qw4cdqv09we",
              "name": "default",
              "path": "https://d6opbaohxg209.cloudfront.net/temp/extracted_67d7d664c7awe/Accessory/Laptop.png"
            }
          ],
          "values": [
            { "key": "100001", "label": "Name", "type": "text-field", "value": "Emma" },
            { "key": "layout_100003", "label": "Layout", "type": "layout-swatch", "value": "Portrait" },
            { "key": "100004", "label": "Color", "type": "color-picker", "value": "#1a2b3c" }
          ]
        }
      ]
    }
  ]
}
```

**Error Responses:**

| Code | Message | Description |
| ---- |
| 401 | Unauthorized | Invalid or missing token |
| 403 | Forbidden | You do not have permission to view orders for this shop |

### 2. Get Specific Order

**Endpoint:**

```
GET /orders/{id}
```

**Description:** Fetch one order, with its print files and personalization values.

**Parameters:**

| Parameter | Type | Required | Description |
| ---- |
| `shop` | string | ✅ | Shopify store name. If your store URL is abcdef.myshopify.com, then shop=abcdef |
| `id` | integer | ✅ | Shopify order ID, in the path |

**Headers:**

| Header | Value |
| ---- |
| `Authorization` | Bearer API\_KEY |
| `Content-Type` | application/json |

**Example request:**

```
GET https://app.customix.io/api/integrations/v1/orders/123456789?shop=abcdef
```

**Response:** a single order in `data`, with the same fields as one entry of the list above:

```json
{
  "data": {
    "shop": "abcdef.myshopify.com",
    "order_id": 123456789,
    "order_number": "#1001",
    "customizations": [
      {
        "id": "01jjavmg7t7vqj5z6qvxwie14b",
        "public_customization_id": "01jjavmg7t7vqj5z6qvxwpc9kd",
        "line_item_quantity": 1,
        "files": [
          { "id": "01jb3092vabc7m8qw4cdqv09we", "name": "default", "path": "https://d6opbaohxg209.cloudfront.net/temp/extracted_67d7d664c7awe/Accessory/Laptop.png" }
        ],
        "values": [
          { "key": "100001", "label": "Name", "type": "text-field", "value": "Emma" }
        ]
      }
    ]
  }
}
```

(Shortened here — the real response includes every field shown in the list example.)

**Error Responses:**

| Code | Message | Description |
| ---- |
| 401 | Unauthorized | Invalid or missing token |
| 403 | Forbidden | You do not have permission to view this order |
| 404 | Not Found | Order not found |

### 3. Get Specific Order's Customization

**Endpoint:**

```
GET /orders/{order_id}/customizations/{public_customization_id}
```

**Description:** Retrieve one customization of an order.

**Parameters:**

| Parameter | Type | Required | Description |
| ---- |
| `shop` | string | ✅ | Shopify store name. If your store URL is abcdef.myshopify.com, then shop=abcdef |
| `order_id` | integer | ✅ | Shopify order ID, in the path |
| `public_customization_id` | string | ✅ | The customization's `public_customization_id`, in the path. It is in the order response, and on the order in Shopify as the `_cm-customization-id` item property |

**Headers:**

| Header | Value |
| ---- |
| `Authorization` | Bearer API\_KEY |
| `Content-Type` | application/json |

**Example request:**

```
GET https://app.customix.io/api/integrations/v1/orders/123456789/customizations/01jjavmg7t7vqj5z6qvxwpc9kd?shop=abcdef
```

**Response:** the customization on its own, not wrapped in `data`:

```json
{
  "id": "01jjavmg7t7vqj5z6qvxwie14b",
  "public_customization_id": "01jjavmg7t7vqj5z6qvxwpc9kd",
  "campaign_id": "01jphjdfmtxhaio94h0wd0kv0c",
  "shopify_line_item_id": 11106133639222,
  "shopify_product_id": 11179841648222,
  "shopify_variant_id": 11191300929074,
  "platform": "shopify",
  "line_item_quantity": 1,
  "files": [
    {
      "id": "01jb3092vabc7m8qw4cdqv09we",
      "name": "default",
      "path": "https://d6opbaohxg209.cloudfront.net/temp/extracted_67d7d664c7awe/Accessory/Laptop.png"
    }
  ],
  "values": [
    { "key": "100001", "label": "Name", "type": "text-field", "value": "Emma" },
    { "key": "layout_100003", "label": "Layout", "type": "layout-swatch", "value": "Portrait" }
  ]
}
```

**Error Responses:**

| Code | Message | Description |
| ---- |
| 401 | Unauthorized | Invalid or missing token |
| 403 | Forbidden | You do not have permission to view this customization |
| 404 | Not Found | Order not found, or Customization not found |

# 🖊️ Customization Values

Every customization includes **values** — one entry for each personalization field saved with the order, the same details you see as item properties on the order in Shopify. Each entry has:

* **key**: the field's identifier in your template. It stays the same from order to order for the same field of the same template, so use it to map fields in your integration.
* **label**: the option name your customers saw, for example "Name". It can be empty on older orders.
* **type**: the kind of option, for example `text-field`, `color-picker`, `font-swatch`, `image-swatch`, `layout-swatch`, `date-picker` or `file-upload`.
* **value**: what your customer chose or entered, always as text.

How **value** reads for each kind of option:

* **Text**: exactly what your customer typed.
* **Color picker**: the color code your customer picked.
* **Font, image, color and stroke swatches**: the value of the swatch your customer picked.
* **Layout swatches**: the name of the layout your customer picked, as it was named when they placed the order.
* **Date and time pickers**: the date or time your customer picked.
* **File and vector uploads**: a link to the file your customer uploaded.
* **Palettes and word cloud fonts**: the colors or fonts your customer picked, separated by commas.
* Options that have no text form, such as map styles, locations or Spotify tracks, come back with an empty value — use the print files for those.

> 📌 If a customer edits their personalization after ordering, the API returns the latest version. The values keep the same order every time you fetch an order.

# ⚠️ Common Error Codes

| Code | Description |
| ---- |
| 400 | Bad Request |
| 401 | Unauthorized — invalid or missing API key |
| 403 | Forbidden — no permission for this shop, or API access is not available on your current plan |
| 404 | Not Found |
| 422 | Missing shop name — the `shop` parameter is required |
| 500 | Internal Server Error |

# 📌 Notes

* All responses are in **JSON**.
* Rate limit: `2 requests/second`.
* Contact admin@customix.io for questions.