面向开发者的 API

Customix Integrations API 可让您将个性化订单拉取到您自己的系统中，包括 Customix 生成的打印文件，以及顾客在个性化过程中输入的所有内容，例如姓名、自定义文字、颜色和所选版式。当生产工具、电子表格或 Make 之类的自动化平台需要获取您的订单详情，而又不想让人工逐条复制时，就可以使用它。

要获取 API key，请在左侧边栏中进入设置，打开集成标签页，然后在 API Key 卡片中点击创建 key。详情请参阅如何获取 Customix API key。

🔑 身份验证

所有请求都需要在请求头中包含您的 API key：

Authorization: Bearer <your_api_key>

🌐 Base URL

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

📘 接口

1. 获取订单列表

接口：

GET /orders

说明：获取您的个性化订单，默认按最新的在前排序。

参数：

请求头：

请求示例：

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

响应：

{
  "data": [
    {
      "shop": "abcdef.myshopify.com",
      "order_id": 123456789,
      "order_number": "#1001",
      "currency": "USD",
      "customer": "John Doe",
      "email": "[email protected]",
      "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" }
          ]
        }
      ]
    }
  ]
}

错误响应：

2. 获取指定订单

接口：

GET /orders/{id}

说明：获取单个订单，包括其打印文件和个性化值。

参数：

请求头：

请求示例：

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

响应：在 data 中返回单个订单，其字段与上方列表中的一条记录相同：

{
  "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" }
        ]
      }
    ]
  }
}

（此处为精简版，实际响应包含列表示例中显示的所有字段。）

错误响应：

3. 获取指定订单的自定义内容

接口：

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

说明：获取订单的某一项自定义内容。

参数：

请求头：

请求示例：

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

响应：单独返回该自定义内容，不包裹在 data 中：

{
  "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" }
  ]
}

错误响应：

🖊️ 自定义内容的值

每项自定义内容都包含 values，即订单中保存的每个个性化字段各对应一条记录，与您在 Shopify 订单上看到的订单项属性相同。每条记录包含：

• key：该字段在您的模板中的标识符。对于同一模板的同一字段，它在不同订单之间保持不变，因此可用它来映射您集成中的字段。
• label：顾客看到的选项名称，例如“Name”。在较早的订单中可能为空。
• type：选项的类型，例如 text-field、color-picker、font-swatch、image-swatch、layout-swatch、date-picker 或 file-upload。
• value：顾客选择或输入的内容，始终为文本。

value 在每种选项类型中的呈现方式：

• 文本：顾客输入的原样内容。
• 颜色选择器：顾客选择的颜色代码。
• 字体、图片、颜色和描边色板：顾客所选色板的值。
• 版式色板：顾客所选版式的名称，即下单时该版式的名称。
• 日期和时间选择器：顾客选择的日期或时间。
• 文件和矢量图上传：指向顾客所上传文件的链接。
• 调色板和词云字体：顾客选择的颜色或字体，以逗号分隔。
• 没有文本形式的选项，例如地图样式、地点或 Spotify 曲目，会返回空值，请对这些选项使用打印文件。

⚠️ 常见错误代码

📌 备注

• 所有响应均为 JSON 格式。
• 速率限制：2 requests/second。
• 如有疑问，请联系 [email protected]。

更新于：14/09/2026