API resource

Store orders and customers

Read and manage the store's orders in one format for every platform (line items with prices, discounts and tax, shipping, billing details, payment status, refunds), refund, edit or cancel an order, create draft orders and send their invoice, and look up customers. Needs the orders and customers permissions the merchant approves on the store (see Get a store). Pick the store with accountId.

List orders

GET/v1/commerce/orders

Works on: Shopify, WooCommerce

The store's orders in one format for every platform, with what an invoice needs. Needs orders.read. Each order includes: - line items with unit prices, discounts and tax per line - shipping and fee lines - billing details - payment status and refunds ### Ordering and syncing Newest order first. With updatedAfter, oldest change first, so a sync can page forward from its last seen updatedAt. Start each sync a few minutes before the last updatedAt you saw and drop duplicates by id, since an order edited while you page can shift the list.

Query parameters

accountIdstringrequired

Connected store account id.

limitinteger

cursorstring

createdAfterstring

createdBeforestring

updatedAfterstring

Only orders changed after this time, oldest change first.

customerIdstring

Only this customer's orders (customer.id on an order, or id from the customers endpoints).

emailstring

Only orders placed with this email. Shopify only; WooCommerce answers 400 platform_not_supported.

numberstring

The order number a buyer quotes, with or without the "#" (number on an order). Shopify only; on WooCommerce the number is the order id, so read GET /v1/commerce/orders/{orderId} (this filter answers 400 platform_not_supported).

curl "https://creatoros-production-5658.up.railway.app/v1/commerce/orders?accountId=acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "orders": [
    {
      "id": "string",
      "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H",
      "platform": "shopify",
      "number": "#1001",
      "status": "pending_payment",
      "platformStatus": "string",
      "paymentStatus": {},
      "platformPaymentStatus": "string",
      "currency": "EUR",
      "taxesIncluded": true,
      "createdAt": "2026-10-10T00:00:00.000Z",
      "updatedAt": "2026-10-10T00:00:00.000Z",
      "paidAt": "2026-10-10T00:00:00.000Z",
      "cancelledAt": "2026-10-10T00:00:00.000Z",
      "cancelReason": "string",
      "subtotal": {
        "amount": "19.90",
        "currency": "USD"
      },
      "discountTotal": {
        "amount": "19.90",
        "currency": "USD"
      },
      "shippingTotal": {
        "amount": "19.90",
        "currency": "USD"
      },
      "taxTotal": {
        "amount": "19.90",
        "currency": "USD"
      },
      "total": {
        "amount": "19.90",
        "currency": "USD"
      },
      "refundedTotal": {
        "amount": "19.90",
        "currency": "USD"
      },
      "discountCodes": [
        "string"
      ],
      "paymentMethods": [
        "string"
      ],
      "customer": {
        "id": "string",
        "email": "string",
        "phone": "string",
        "firstName": "string",
        "lastName": "string"
      },
      "billingAddress": {
        "firstName": "string",
        "lastName": "string",
        "company": "string",
        "phone": "string",
        "line1": "string",
        "line2": "string",
        "city": "string",
        "region": "string",
        "postalCode": "string",
        "countryCode": "string"
      },
      "shippingAddress": {
        "firstName": "string",
        "lastName": "string",
        "company": "string",
        "phone": "string",
        "line1": "string",
        "line2": "string",
        "city": "string",
        "region": "string",
        "postalCode": "string",
        "countryCode": "string"
      },
      "buyerNote": "string",
      "attribution": {
        "ready": true,
        "firstVisit": {},
        "lastVisit": {},
        "customAttributes": []
      },
      "lineItems": [
        {}
      ],
      "shippingLines": [
        {}
      ],
      "feeLines": [
        {}
      ],
      "taxLines": [
        {}
      ],
      "refunds": [
        {}
      ],
      "fulfillments": [
        {}
      ],
      "platformData": {}
    }
  ],
  "nextCursor": "string"
}

Get an order

GET/v1/commerce/orders/{orderId}

Works on: Shopify, WooCommerce

One order with every line item, tax line and refund. Needs orders.read.

Path parameters

orderIdstringrequired

Platform-native order id.

Query parameters

accountIdstringrequired

Connected store account id.

curl "https://creatoros-production-5658.up.railway.app/v1/commerce/orders/123?accountId=acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "order": {
    "id": "string",
    "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H",
    "platform": "shopify",
    "number": "#1001",
    "status": "pending_payment",
    "platformStatus": "string",
    "paymentStatus": {},
    "platformPaymentStatus": "string",
    "currency": "EUR",
    "taxesIncluded": true,
    "createdAt": "2026-10-10T00:00:00.000Z",
    "updatedAt": "2026-10-10T00:00:00.000Z",
    "paidAt": "2026-10-10T00:00:00.000Z",
    "cancelledAt": "2026-10-10T00:00:00.000Z",
    "cancelReason": "string",
    "subtotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "discountTotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "shippingTotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "taxTotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "total": {
      "amount": "19.90",
      "currency": "USD"
    },
    "refundedTotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "discountCodes": [
      "string"
    ],
    "paymentMethods": [
      "string"
    ],
    "customer": {
      "id": "string",
      "email": "string",
      "phone": "string",
      "firstName": "string",
      "lastName": "string"
    },
    "billingAddress": {
      "firstName": "string",
      "lastName": "string",
      "company": "string",
      "phone": "string",
      "line1": "string",
      "line2": "string",
      "city": "string",
      "region": "string",
      "postalCode": "string",
      "countryCode": "string"
    },
    "shippingAddress": {
      "firstName": "string",
      "lastName": "string",
      "company": "string",
      "phone": "string",
      "line1": "string",
      "line2": "string",
      "city": "string",
      "region": "string",
      "postalCode": "string",
      "countryCode": "string"
    },
    "buyerNote": "string",
    "attribution": {
      "ready": true,
      "firstVisit": {
        "occurredAt": "2026-10-10T00:00:00.000Z",
        "landingUrl": "string",
        "referrerUrl": "string",
        "source": "instagram",
        "sourceType": "string",
        "utm": {}
      },
      "lastVisit": {
        "occurredAt": "2026-10-10T00:00:00.000Z",
        "landingUrl": "string",
        "referrerUrl": "string",
        "source": "instagram",
        "sourceType": "string",
        "utm": {}
      },
      "customAttributes": [
        {}
      ]
    },
    "lineItems": [
      {
        "id": "string",
        "productId": "8214569812345",
        "variantId": "string",
        "sku": "string",
        "title": "string",
        "variantTitle": "string",
        "quantity": 0,
        "unitPrice": {},
        "subtotal": {},
        "discountTotal": {},
        "total": {},
        "taxLines": []
      }
    ],
    "shippingLines": [
      {
        "id": "string",
        "title": "string",
        "amount": {},
        "discountTotal": {},
        "taxLines": []
      }
    ],
    "feeLines": [
      {
        "id": "string",
        "title": "string",
        "amount": {},
        "discountTotal": {},
        "taxLines": []
      }
    ],
    "taxLines": [
      {
        "title": "TVA 20%",
        "ratePercent": 0,
        "amount": {}
      }
    ],
    "refunds": [
      {
        "id": "string",
        "createdAt": "2026-10-10T00:00:00.000Z",
        "note": "string",
        "amount": {},
        "lineItems": []
      }
    ],
    "fulfillments": [
      {
        "id": "string",
        "carrierName": "string",
        "trackingNumber": "string",
        "trackingUrl": "string",
        "deliveryStatus": "pending",
        "platformDeliveryStatus": "string",
        "estimatedDeliveryAt": "2026-10-10T00:00:00.000Z",
        "inTransitAt": "2026-10-10T00:00:00.000Z",
        "deliveredAt": "2026-10-10T00:00:00.000Z"
      }
    ],
    "platformData": {}
  }
}

Update an order's shipping address

PATCH/v1/commerce/orders/{orderId}

Works on: Shopify, WooCommerce

Replaces the order's shipping address, for a buyer who asks to fix it before the order ships. Needs orders.update. Items and quantities change through POST /v1/commerce/orders/{orderId}/edits. The whole address is replaced: send every line, not only the one that changes. Fulfillments already shipped keep the address they were sent to.

Path parameters

orderIdstringrequired

Platform-native order id.

Body

accountIdstringrequired

Connected store account id.

shippingAddressobjectrequired

curl -X PATCH "https://creatoros-production-5658.up.railway.app/v1/commerce/orders/123" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H",
    "shippingAddress": {
      "firstName": "string",
      "lastName": "string",
      "company": "string",
      "phone": "string",
      "line1": "string",
      "line2": "string",
      "city": "string",
      "region": "string",
      "postalCode": "string",
      "countryCode": "string"
    }
  }'
Response 200
{
  "order": {
    "id": "string",
    "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H",
    "platform": "shopify",
    "number": "#1001",
    "status": "pending_payment",
    "platformStatus": "string",
    "paymentStatus": {},
    "platformPaymentStatus": "string",
    "currency": "EUR",
    "taxesIncluded": true,
    "createdAt": "2026-10-10T00:00:00.000Z",
    "updatedAt": "2026-10-10T00:00:00.000Z",
    "paidAt": "2026-10-10T00:00:00.000Z",
    "cancelledAt": "2026-10-10T00:00:00.000Z",
    "cancelReason": "string",
    "subtotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "discountTotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "shippingTotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "taxTotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "total": {
      "amount": "19.90",
      "currency": "USD"
    },
    "refundedTotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "discountCodes": [
      "string"
    ],
    "paymentMethods": [
      "string"
    ],
    "customer": {
      "id": "string",
      "email": "string",
      "phone": "string",
      "firstName": "string",
      "lastName": "string"
    },
    "billingAddress": {
      "firstName": "string",
      "lastName": "string",
      "company": "string",
      "phone": "string",
      "line1": "string",
      "line2": "string",
      "city": "string",
      "region": "string",
      "postalCode": "string",
      "countryCode": "string"
    },
    "shippingAddress": {
      "firstName": "string",
      "lastName": "string",
      "company": "string",
      "phone": "string",
      "line1": "string",
      "line2": "string",
      "city": "string",
      "region": "string",
      "postalCode": "string",
      "countryCode": "string"
    },
    "buyerNote": "string",
    "attribution": {
      "ready": true,
      "firstVisit": {
        "occurredAt": "2026-10-10T00:00:00.000Z",
        "landingUrl": "string",
        "referrerUrl": "string",
        "source": "instagram",
        "sourceType": "string",
        "utm": {}
      },
      "lastVisit": {
        "occurredAt": "2026-10-10T00:00:00.000Z",
        "landingUrl": "string",
        "referrerUrl": "string",
        "source": "instagram",
        "sourceType": "string",
        "utm": {}
      },
      "customAttributes": [
        {}
      ]
    },
    "lineItems": [
      {
        "id": "string",
        "productId": "8214569812345",
        "variantId": "string",
        "sku": "string",
        "title": "string",
        "variantTitle": "string",
        "quantity": 0,
        "unitPrice": {},
        "subtotal": {},
        "discountTotal": {},
        "total": {},
        "taxLines": []
      }
    ],
    "shippingLines": [
      {
        "id": "string",
        "title": "string",
        "amount": {},
        "discountTotal": {},
        "taxLines": []
      }
    ],
    "feeLines": [
      {
        "id": "string",
        "title": "string",
        "amount": {},
        "discountTotal": {},
        "taxLines": []
      }
    ],
    "taxLines": [
      {
        "title": "TVA 20%",
        "ratePercent": 0,
        "amount": {}
      }
    ],
    "refunds": [
      {
        "id": "string",
        "createdAt": "2026-10-10T00:00:00.000Z",
        "note": "string",
        "amount": {},
        "lineItems": []
      }
    ],
    "fulfillments": [
      {
        "id": "string",
        "carrierName": "string",
        "trackingNumber": "string",
        "trackingUrl": "string",
        "deliveryStatus": "pending",
        "platformDeliveryStatus": "string",
        "estimatedDeliveryAt": "2026-10-10T00:00:00.000Z",
        "inTransitAt": "2026-10-10T00:00:00.000Z",
        "deliveredAt": "2026-10-10T00:00:00.000Z"
      }
    ],
    "platformData": {}
  }
}

Refund an order

POST/v1/commerce/orders/{orderId}/refunds

Works on: Shopify, WooCommerce

Refunds line items, shipping or an amount of money to the buyer's original payment methods. Needs orders.refund. - Preview first with validateOnly: true: it returns what the buyer gets back and to which payments, without refunding anything. - A real refund needs an Idempotency-Key header (a UUID per refund): a retry with the same key never refunds twice. - Every amount, sent or returned, is in the currency the buyer paid in, the one refunds are made in. Send currency to have a mismatch refused instead of guessed.

Path parameters

orderIdstringrequired

Platform-native order id.

Body

accountIdstringrequired

Connected store account id.

lineItemsobject[]

shippingobject

Refund the shipping: { "full": true } for what is left of it, or { "amount": "5.00" } for part of it.

amountstring

Refund this much money instead of what the lines and shipping are worth, for a goodwill refund or a partial one. Taken from the order's payments in order, up to what each can still refund.

currencystring

The currency your amounts are in. Refused (400) unless it is the one the buyer paid in, which every refund amount uses.

notestring

Kept on the refund, visible to staff.

notifyCustomerboolean

Email the buyer about the refund.

validateOnlyboolean

Return the refund the platform would make, without refunding anything.

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/commerce/orders/123/refunds" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H"
  }'
Response 200
{
  "validateOnly": true,
  "refund": {
    "amount": {
      "amount": "19.90",
      "currency": "USD"
    },
    "maximumRefundable": {
      "amount": "19.90",
      "currency": "USD"
    },
    "subtotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "tax": {
      "amount": "19.90",
      "currency": "USD"
    },
    "shipping": {
      "amount": "19.90",
      "currency": "USD"
    },
    "lineItems": [
      {
        "lineItemId": "string",
        "quantity": 0,
        "restock": "none",
        "amount": {}
      }
    ],
    "transactions": [
      {
        "gateway": "string",
        "amount": {}
      }
    ]
  }
}

Edit an order

POST/v1/commerce/orders/{orderId}/edits

Works on: Shopify, WooCommerce

Adds products to an order and changes or removes its lines. Needs orders.edit. - Preview first with validateOnly: true: it returns the new totals and what the buyer would owe, and changes nothing. - A real edit needs an Idempotency-Key header (a UUID per edit): a retry with the same key never applies it twice. - When the edit raises the total, the buyer owes outstanding; notifyCustomer emails them the change. When it lowers it, refund the difference with the refunds endpoint.

Path parameters

orderIdstringrequired

Platform-native order id.

Body

accountIdstringrequired

Connected store account id.

addobject[]

quantitiesobject[]

notifyCustomerboolean

staffNotestring

validateOnlyboolean

Return the edited totals without changing the order.

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/commerce/orders/123/edits" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H"
  }'
Response 200
{
  "validateOnly": true,
  "order": {
    "id": "string",
    "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H",
    "platform": "shopify",
    "number": "#1001",
    "status": "pending_payment",
    "platformStatus": "string",
    "paymentStatus": {},
    "platformPaymentStatus": "string",
    "currency": "EUR",
    "taxesIncluded": true,
    "createdAt": "2026-10-10T00:00:00.000Z",
    "updatedAt": "2026-10-10T00:00:00.000Z",
    "paidAt": "2026-10-10T00:00:00.000Z",
    "cancelledAt": "2026-10-10T00:00:00.000Z",
    "cancelReason": "string",
    "subtotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "discountTotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "shippingTotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "taxTotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "total": {
      "amount": "19.90",
      "currency": "USD"
    },
    "refundedTotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "discountCodes": [
      "string"
    ],
    "paymentMethods": [
      "string"
    ],
    "customer": {
      "id": "string",
      "email": "string",
      "phone": "string",
      "firstName": "string",
      "lastName": "string"
    },
    "billingAddress": {
      "firstName": "string",
      "lastName": "string",
      "company": "string",
      "phone": "string",
      "line1": "string",
      "line2": "string",
      "city": "string",
      "region": "string",
      "postalCode": "string",
      "countryCode": "string"
    },
    "shippingAddress": {
      "firstName": "string",
      "lastName": "string",
      "company": "string",
      "phone": "string",
      "line1": "string",
      "line2": "string",
      "city": "string",
      "region": "string",
      "postalCode": "string",
      "countryCode": "string"
    },
    "buyerNote": "string",
    "attribution": {
      "ready": true,
      "firstVisit": {
        "occurredAt": "2026-10-10T00:00:00.000Z",
        "landingUrl": "string",
        "referrerUrl": "string",
        "source": "instagram",
        "sourceType": "string",
        "utm": {}
      },
      "lastVisit": {
        "occurredAt": "2026-10-10T00:00:00.000Z",
        "landingUrl": "string",
        "referrerUrl": "string",
        "source": "instagram",
        "sourceType": "string",
        "utm": {}
      },
      "customAttributes": [
        {}
      ]
    },
    "lineItems": [
      {
        "id": "string",
        "productId": "8214569812345",
        "variantId": "string",
        "sku": "string",
        "title": "string",
        "variantTitle": "string",
        "quantity": 0,
        "unitPrice": {},
        "subtotal": {},
        "discountTotal": {},
        "total": {},
        "taxLines": []
      }
    ],
    "shippingLines": [
      {
        "id": "string",
        "title": "string",
        "amount": {},
        "discountTotal": {},
        "taxLines": []
      }
    ],
    "feeLines": [
      {
        "id": "string",
        "title": "string",
        "amount": {},
        "discountTotal": {},
        "taxLines": []
      }
    ],
    "taxLines": [
      {
        "title": "TVA 20%",
        "ratePercent": 0,
        "amount": {}
      }
    ],
    "refunds": [
      {
        "id": "string",
        "createdAt": "2026-10-10T00:00:00.000Z",
        "note": "string",
        "amount": {},
        "lineItems": []
      }
    ],
    "fulfillments": [
      {
        "id": "string",
        "carrierName": "string",
        "trackingNumber": "string",
        "trackingUrl": "string",
        "deliveryStatus": "pending",
        "platformDeliveryStatus": "string",
        "estimatedDeliveryAt": "2026-10-10T00:00:00.000Z",
        "inTransitAt": "2026-10-10T00:00:00.000Z",
        "deliveredAt": "2026-10-10T00:00:00.000Z"
      }
    ],
    "platformData": {}
  },
  "edit": {
    "subtotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "total": {
      "amount": "19.90",
      "currency": "USD"
    },
    "outstanding": {
      "amount": "19.90",
      "currency": "USD"
    },
    "lineItems": [
      {
        "lineItemId": "string",
        "variantId": "string",
        "title": "string",
        "quantity": 0,
        "unitPrice": {}
      }
    ]
  }
}

Cancel an order

POST/v1/commerce/orders/{orderId}/cancel

Works on: Shopify, WooCommerce

Cancels an order, by default refunding it to the original payment methods and restocking it. Needs orders.cancel. The platform cancels in the background. The call waits a few seconds: 200 with cancelled: true when it finished, 202 with cancelled: false when it is still running (the commerce.order.updated webhook reports the outcome).

Path parameters

orderIdstringrequired

Platform-native order id.

Body

accountIdstringrequired

Connected store account id.

reasonstringrequired

refundboolean

Refund the payments to the original methods. Authorized payments are voided either way.

restockboolean

notifyCustomerboolean

staffNotestring

Visible to staff only.

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/commerce/orders/123/cancel" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H",
    "reason": "customer"
  }'
Response 200
{
  "order": {
    "id": "string",
    "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H",
    "platform": "shopify",
    "number": "#1001",
    "status": "pending_payment",
    "platformStatus": "string",
    "paymentStatus": {},
    "platformPaymentStatus": "string",
    "currency": "EUR",
    "taxesIncluded": true,
    "createdAt": "2026-10-10T00:00:00.000Z",
    "updatedAt": "2026-10-10T00:00:00.000Z",
    "paidAt": "2026-10-10T00:00:00.000Z",
    "cancelledAt": "2026-10-10T00:00:00.000Z",
    "cancelReason": "string",
    "subtotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "discountTotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "shippingTotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "taxTotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "total": {
      "amount": "19.90",
      "currency": "USD"
    },
    "refundedTotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "discountCodes": [
      "string"
    ],
    "paymentMethods": [
      "string"
    ],
    "customer": {
      "id": "string",
      "email": "string",
      "phone": "string",
      "firstName": "string",
      "lastName": "string"
    },
    "billingAddress": {
      "firstName": "string",
      "lastName": "string",
      "company": "string",
      "phone": "string",
      "line1": "string",
      "line2": "string",
      "city": "string",
      "region": "string",
      "postalCode": "string",
      "countryCode": "string"
    },
    "shippingAddress": {
      "firstName": "string",
      "lastName": "string",
      "company": "string",
      "phone": "string",
      "line1": "string",
      "line2": "string",
      "city": "string",
      "region": "string",
      "postalCode": "string",
      "countryCode": "string"
    },
    "buyerNote": "string",
    "attribution": {
      "ready": true,
      "firstVisit": {
        "occurredAt": "2026-10-10T00:00:00.000Z",
        "landingUrl": "string",
        "referrerUrl": "string",
        "source": "instagram",
        "sourceType": "string",
        "utm": {}
      },
      "lastVisit": {
        "occurredAt": "2026-10-10T00:00:00.000Z",
        "landingUrl": "string",
        "referrerUrl": "string",
        "source": "instagram",
        "sourceType": "string",
        "utm": {}
      },
      "customAttributes": [
        {}
      ]
    },
    "lineItems": [
      {
        "id": "string",
        "productId": "8214569812345",
        "variantId": "string",
        "sku": "string",
        "title": "string",
        "variantTitle": "string",
        "quantity": 0,
        "unitPrice": {},
        "subtotal": {},
        "discountTotal": {},
        "total": {},
        "taxLines": []
      }
    ],
    "shippingLines": [
      {
        "id": "string",
        "title": "string",
        "amount": {},
        "discountTotal": {},
        "taxLines": []
      }
    ],
    "feeLines": [
      {
        "id": "string",
        "title": "string",
        "amount": {},
        "discountTotal": {},
        "taxLines": []
      }
    ],
    "taxLines": [
      {
        "title": "TVA 20%",
        "ratePercent": 0,
        "amount": {}
      }
    ],
    "refunds": [
      {
        "id": "string",
        "createdAt": "2026-10-10T00:00:00.000Z",
        "note": "string",
        "amount": {},
        "lineItems": []
      }
    ],
    "fulfillments": [
      {
        "id": "string",
        "carrierName": "string",
        "trackingNumber": "string",
        "trackingUrl": "string",
        "deliveryStatus": "pending",
        "platformDeliveryStatus": "string",
        "estimatedDeliveryAt": "2026-10-10T00:00:00.000Z",
        "inTransitAt": "2026-10-10T00:00:00.000Z",
        "deliveredAt": "2026-10-10T00:00:00.000Z"
      }
    ],
    "platformData": {}
  },
  "cancelled": true
}

Create a draft order

POST/v1/commerce/draft-orders

Works on: Shopify, WooCommerce

Creates a draft order for a customer, for a replacement, a phone order or a custom quote. Needs draft_orders.write. Send the buyer its checkout link with the invoice endpoint; the draft becomes an order once they pay. Amounts in the response are in the currency the buyer pays in; custom prices you send are in the store currency.

Body

accountIdstringrequired

Connected store account id.

customerIdstring

The customer it is for, from the customers endpoints.

emailstring

lineItemsobject[]required

A product variant (variantId) or a custom item (title and price).

discountobject

A discount on the whole draft.

shippingobject

shippingAddressobject

Where to ship. Without one, the customer's default address is used.

notestring

tagsstring[]

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/commerce/draft-orders" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H",
    "lineItems": [
      {
        "variantId": "string",
        "title": "string",
        "price": "25.00",
        "quantity": 0,
        "taxable": true,
        "requiresShipping": true
      }
    ]
  }'
Response 200
{
  "draftOrder": {
    "id": "string",
    "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H",
    "platform": "shopify",
    "name": "#D12",
    "status": "open",
    "invoiceUrl": "string",
    "invoiceSentAt": "2026-10-10T00:00:00.000Z",
    "email": "string",
    "customerId": "string",
    "note": "string",
    "tags": [
      "string"
    ],
    "currency": "string",
    "subtotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "discountTotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "shippingTotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "taxTotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "total": {
      "amount": "19.90",
      "currency": "USD"
    },
    "lineItems": [
      {
        "id": "string",
        "productId": "8214569812345",
        "variantId": "string",
        "title": "string",
        "variantTitle": "string",
        "sku": "string",
        "quantity": 0,
        "unitPrice": {},
        "total": {}
      }
    ],
    "shippingAddress": {
      "firstName": "string",
      "lastName": "string",
      "company": "string",
      "phone": "string",
      "line1": "string",
      "line2": "string",
      "city": "string",
      "region": "string",
      "postalCode": "string",
      "countryCode": "string"
    },
    "orderId": "string",
    "createdAt": "2026-10-10T00:00:00.000Z",
    "updatedAt": "2026-10-10T00:00:00.000Z",
    "completedAt": "2026-10-10T00:00:00.000Z"
  }
}

Get a draft order

GET/v1/commerce/draft-orders/{draftOrderId}

Works on: Shopify, WooCommerce

One draft order with its status, checkout link and, once paid, the order it became. Needs draft_orders.read.

Path parameters

draftOrderIdstringrequired

Platform-native draft order id.

Query parameters

accountIdstringrequired

Connected store account id.

curl "https://creatoros-production-5658.up.railway.app/v1/commerce/draft-orders/123?accountId=acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "draftOrder": {
    "id": "string",
    "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H",
    "platform": "shopify",
    "name": "#D12",
    "status": "open",
    "invoiceUrl": "string",
    "invoiceSentAt": "2026-10-10T00:00:00.000Z",
    "email": "string",
    "customerId": "string",
    "note": "string",
    "tags": [
      "string"
    ],
    "currency": "string",
    "subtotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "discountTotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "shippingTotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "taxTotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "total": {
      "amount": "19.90",
      "currency": "USD"
    },
    "lineItems": [
      {
        "id": "string",
        "productId": "8214569812345",
        "variantId": "string",
        "title": "string",
        "variantTitle": "string",
        "sku": "string",
        "quantity": 0,
        "unitPrice": {},
        "total": {}
      }
    ],
    "shippingAddress": {
      "firstName": "string",
      "lastName": "string",
      "company": "string",
      "phone": "string",
      "line1": "string",
      "line2": "string",
      "city": "string",
      "region": "string",
      "postalCode": "string",
      "countryCode": "string"
    },
    "orderId": "string",
    "createdAt": "2026-10-10T00:00:00.000Z",
    "updatedAt": "2026-10-10T00:00:00.000Z",
    "completedAt": "2026-10-10T00:00:00.000Z"
  }
}

Send a draft order invoice

POST/v1/commerce/draft-orders/{draftOrderId}/invoice

Works on: Shopify, WooCommerce

Emails the buyer the draft's checkout link. The draft becomes an order when they pay. Needs draft_orders.write.

Path parameters

draftOrderIdstringrequired

Platform-native draft order id.

Body

accountIdstringrequired

Connected store account id.

tostring

Defaults to the draft's email.

subjectstring

customMessagestring

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/commerce/draft-orders/123/invoice" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H"
  }'
Response 200
{
  "draftOrder": {
    "id": "string",
    "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H",
    "platform": "shopify",
    "name": "#D12",
    "status": "open",
    "invoiceUrl": "string",
    "invoiceSentAt": "2026-10-10T00:00:00.000Z",
    "email": "string",
    "customerId": "string",
    "note": "string",
    "tags": [
      "string"
    ],
    "currency": "string",
    "subtotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "discountTotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "shippingTotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "taxTotal": {
      "amount": "19.90",
      "currency": "USD"
    },
    "total": {
      "amount": "19.90",
      "currency": "USD"
    },
    "lineItems": [
      {
        "id": "string",
        "productId": "8214569812345",
        "variantId": "string",
        "title": "string",
        "variantTitle": "string",
        "sku": "string",
        "quantity": 0,
        "unitPrice": {},
        "total": {}
      }
    ],
    "shippingAddress": {
      "firstName": "string",
      "lastName": "string",
      "company": "string",
      "phone": "string",
      "line1": "string",
      "line2": "string",
      "city": "string",
      "region": "string",
      "postalCode": "string",
      "countryCode": "string"
    },
    "orderId": "string",
    "createdAt": "2026-10-10T00:00:00.000Z",
    "updatedAt": "2026-10-10T00:00:00.000Z",
    "completedAt": "2026-10-10T00:00:00.000Z"
  }
}

List customers

GET/v1/commerce/customers

Works on: Shopify, WooCommerce

The store's customers, most recently updated first. Needs customers.read. Find the customer behind a support ticket with email, phone or search, then read their orders with GET /v1/commerce/orders?customerId=.

Query parameters

accountIdstringrequired

Connected store account id.

limitinteger

cursorstring

emailstring

phonestring

searchstring

Free text matched against name, email and phone.

curl "https://creatoros-production-5658.up.railway.app/v1/commerce/customers?accountId=acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "customers": [
    {
      "id": "string",
      "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H",
      "platform": "shopify",
      "firstName": "string",
      "lastName": "string",
      "email": "string",
      "phone": "string",
      "ordersCount": 0,
      "totalSpent": {
        "amount": "19.90",
        "currency": "USD"
      },
      "tags": [
        "string"
      ],
      "note": "string",
      "createdAt": "2026-10-10T00:00:00.000Z",
      "updatedAt": "2026-10-10T00:00:00.000Z",
      "defaultAddress": {
        "firstName": "string",
        "lastName": "string",
        "company": "string",
        "phone": "string",
        "line1": "string",
        "line2": "string",
        "city": "string",
        "region": "string",
        "postalCode": "string",
        "countryCode": "string"
      }
    }
  ],
  "nextCursor": "string"
}

Get a customer

GET/v1/commerce/customers/{customerId}

Works on: Shopify, WooCommerce

One customer with their order count, total spent and default address. Needs customers.read.

Path parameters

customerIdstringrequired

Platform-native customer id.

Query parameters

accountIdstringrequired

Connected store account id.

curl "https://creatoros-production-5658.up.railway.app/v1/commerce/customers/123?accountId=acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "customer": {
    "id": "string",
    "accountId": "acc_Sh4Vp9Kz2Ny7Tx3Lm1Rc6Wb5Js8Df0Ga4Ue7Ki2Oq3H",
    "platform": "shopify",
    "firstName": "string",
    "lastName": "string",
    "email": "string",
    "phone": "string",
    "ordersCount": 0,
    "totalSpent": {
      "amount": "19.90",
      "currency": "USD"
    },
    "tags": [
      "string"
    ],
    "note": "string",
    "createdAt": "2026-10-10T00:00:00.000Z",
    "updatedAt": "2026-10-10T00:00:00.000Z",
    "defaultAddress": {
      "firstName": "string",
      "lastName": "string",
      "company": "string",
      "phone": "string",
      "line1": "string",
      "line2": "string",
      "city": "string",
      "region": "string",
      "postalCode": "string",
      "countryCode": "string"
    }
  }
}