Orders

Orders represent completed purchases. They carry items, customer, shipping/billing addresses, totals, payment status, and fulfillment status. Use these endpoints to list/get orders, mark as fulfilled, cancel, and issue refunds. Draft orders (created via the API) let you build orders programmatically without going through the storefront checkout flow.

List guest order downloads

Returns download links for a guest order. No token: the order is identified by matching email and orderNumber for this store. A pair that matches nothing answers 404. A pair that matches an order of another channel of the same store answers 200 with an empty list.

Authorization

X-Sales-Channel-Origin<token>

For /api/vc/{connectionId}/* routes the connectionId (vc_*) is in the URL path — not a header. Live-mode requests must also send a matching Origin header.

In: header

Path Parameters

connectionIdstring

Sales channel ID (vc_*), the canonical salesChannelId. connectionId is the deprecated name of the same value and is still the literal path segment.

Header Parameters

originstring

Origin of the storefront page making the call, for example https://shop.example.com. Required: a request with no Origin header is refused with 403. On a LIVE channel its host must equal the channel's registered domain (or one of its subdomains) or match an allowed origin. A TEST channel with no domain accepts any origin; once a domain is set it is matched as on LIVE.

X-SDK-Version?string

Version of the calling SDK (the Brainerce SDK sends it automatically). Informational: it is recorded on the channel and never changes the response.

Request Body

emailstring

Email used at checkout.

Formatemail

orderNumberstring

Human-readable order number from the order confirmation.

curl -X POST "https://api.brainerce.com/api/vc/string/orders/guest/downloads" \
  -H "origin: string" \
  -H "X-SDK-Version: string" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "orderNumber": "1042"
  }'

curl -X POST "https://api.brainerce.com/api/vc/string/orders/guest/downloads" \  -H "origin: string" \  -H "X-SDK-Version: string" \  -H "Content-Type: application/json" \  -d '{    "email": "[email protected]",    "orderNumber": "1042"  }'

[
  {
    "productName": "Wallpaper pack",
    "fileName": "wallpapers.zip",
    "downloadUrl": "https://api.brainerce.com/api/stores/clst_abc/downloads/eyJ...",
    "downloadsUsed": 0,
    "downloadLimit": 5,
    "expiresAt": "2026-01-15T10:30:00.000Z"
  }
]

{
  "statusCode": 400,
  "code": "VALIDATION_FAILED",
  "message": "name should not be empty, price must be a positive number",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/orders/guest/downloads"
}

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key does not have the required scope: products:write",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/orders/guest/downloads"
}

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/orders/guest/downloads"
}

{
  "statusCode": 429,
  "code": "RATE_LIMITED",
  "message": "Too many requests",
  "details": {
    "retryAfterSeconds": 12
  },
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/orders/guest/downloads"
}

Create order

Creates an order directly from the items, with no server-side cart. For storefronts that handle payment themselves. At most 50 lines. Products must be active and published to this channel; prices and stock are resolved on the server, never taken from the body.

Authorization

X-Sales-Channel-Origin<token>

For /api/vc/{connectionId}/* routes the connectionId (vc_*) is in the URL path — not a header. Live-mode requests must also send a matching Origin header.

In: header

Path Parameters

connectionIdstring

Sales channel ID (vc_*), the canonical salesChannelId. connectionId is the deprecated name of the same value and is still the literal path segment.

Header Parameters

originstring

authorization?string

Optional customer token as Bearer <token>. Present and valid: the order is linked to the customer.

X-SDK-Version?string

Version of the calling SDK (the Brainerce SDK sends it automatically). Informational: it is recorded on the channel and never changes the response.

Request Body

itemsarray<VcOrderItemInputDto>

Lines to order. The DTO accepts up to 500, but the route refuses more than 50 lines with a 400 (items must contain at most 50 entries).

Itemsitems <= 500

customerVcOrderCustomerDto

The buyer. The email is where the order confirmation goes.

shippingAddressVcOrderAddressDto

Where the order ships.

billingAddress?VcOrderAddressDto

Billing address when it differs from the shipping address.

couponCode?string

Coupon code to apply to the order.

Lengthlength <= 100

notes?string

Buyer note for the merchant.

Lengthlength <= 2000

curl -X POST "https://api.brainerce.com/api/vc/string/orders" \
  -H "origin: string" \
  -H "authorization: string" \
  -H "X-SDK-Version: string" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "productId": "clproduct_abc123",
        "quantity": 1
      }
    ],
    "customer": {
      "email": "[email protected]"
    },
    "shippingAddress": {
      "firstName": "Dana",
      "lastName": "Levi",
      "line1": "12 Herzl St",
      "city": "Tel Aviv",
      "postalCode": "6100000",
      "country": "IL"
    }
  }'

curl -X POST "https://api.brainerce.com/api/vc/string/orders" \  -H "origin: string" \  -H "authorization: string" \  -H "X-SDK-Version: string" \  -H "Content-Type: application/json" \  -d '{    "items": [      {        "productId": "clproduct_abc123",        "quantity": 1      }    ],    "customer": {      "email": "[email protected]"    },    "shippingAddress": {      "firstName": "Dana",      "lastName": "Levi",      "line1": "12 Herzl St",      "city": "Tel Aviv",      "postalCode": "6100000",      "country": "IL"    }  }'

{
  "orderId": "clord_abc123",
  "orderNumber": "ORD-20260907-0012",
  "status": "pending",
  "total": "46.96",
  "message": "Order created successfully"
}

{
  "statusCode": 400,
  "code": "VALIDATION_FAILED",
  "message": "name should not be empty, price must be a positive number",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/orders"
}

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key does not have the required scope: products:write",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/orders"
}

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/orders"
}

{
  "statusCode": 429,
  "code": "RATE_LIMITED",
  "message": "Too many requests",
  "details": {
    "retryAfterSeconds": 12
  },
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/orders"
}

List orders with pagination

Lists the store orders, newest first by default, 20 per page. Without status every order except archived is returned.

Authorization

AuthorizationBearer <token>

Admin API key (server-to-server). Issue via the dashboard at Settings → API keys. Plain-text key is shown once — store in a secret manager. Format: Authorization: Bearer brainerce_xxxxxxxxx.

In: header

Query Parameters

page?integer

1-based page number.

Default1

Range1 <= value

limit?integer

Items per page. Default 20. Maximum 100. Larger values are capped to 100.

Default20

Range1 <= value <= 100

status?string

Return only orders with this status (for example PENDING, any letter case) or a custom status label id. Several values separated by commas match any of them.

sortBy?string

Field to sort by. An unknown value falls back to createdAt.

Default"createdAt"

Value in"createdAt" | "totalAmount" | "status"

sortOrder?string

Sort direction. Default desc.

Default"desc"

Value in"asc" | "desc"

financialStatus?string

Return only orders in this payment state. Several values separated by commas match any of them.

fulfillment?string

Return only orders in this fulfillment state. unfulfilled is orders still waiting to be packed: not shipped, not finished, not cancelled.

Value in"unfulfilled" | "partial" | "fulfilled" | "shipped" | "delivered"

salesChannelId?string

Return only orders from these sales channels, by their vc_... connection id. Several ids separated by commas match any of them. An id that is not a channel of this store matches no order.

paymentMethod?string

Return only orders paid with this method as stored on the order (credit_card, paypal, cash_on_delivery, cash, bank_transfer, manual or other). Several values separated by commas match any of them.

isTestOrder?string

Test orders: include (default) lists them with the rest, exclude hides them, only lists only test orders.

Default"include"

Value in"include" | "exclude" | "only"

tag?string

Return only orders carrying at least one of these internal tags. Several tags separated by commas match any of them. The text must match the tag exactly (letter case included); a tag never contains a comma.

excludeTag?string

Hide orders carrying any of these internal tags ("not tagged with"). Several tags separated by commas.

curl -X GET "https://api.brainerce.com/api/v1/orders?page=1&limit=20&status=string&sortBy=createdAt&sortOrder=asc&financialStatus=paid&fulfillment=unfulfilled&salesChannelId=string&paymentMethod=string&isTestOrder=include&tag=VIP%2CGift&excludeTag=B2B"

curl -X GET "https://api.brainerce.com/api/v1/orders?page=1&limit=20&status=string&sortBy=createdAt&sortOrder=asc&financialStatus=paid&fulfillment=unfulfilled&salesChannelId=string&paymentMethod=string&isTestOrder=include&tag=VIP%2CGift&excludeTag=B2B"

{
  "data": [
    {
      "id": "clx1a2b3c4d5e6f7g8h9",
      "storeId": "clx1a2b3c4d5e6f7g8h9",
      "externalId": "clx1a2b3c4d5e6f7g8h9",
      "orderNumber": "ORD-20260115-0042",
      "platform": "CUSTOM",
      "sourceName": "erp-import",
      "totalAmount": "86.26",
      "subtotal": "59.80",
      "taxAmount": "11.46",
      "taxBreakdown": {
        "subtotal": 50.9,
        "shippingNet": 12.71,
        "totalTax": 11.46,
        "total": 75.1,
        "pricesIncludeTax": true,
        "taxCoverage": "full",
        "breakdown": [
          {
            "name": "VAT",
            "rate": 0.18,
            "amount": 12.45
          }
        ],
        "currency": "USD"
      },
      "shippingAmount": "15.00",
      "discountAmount": "5.00",
      "couponCode": "WELCOME10",
      "couponDiscount": "5.00",
      "coupon": {
        "title": "Welcome offer",
        "type": "PERCENTAGE",
        "value": "10.00"
      },
      "surchargeAmount": "0.00",
      "appliedSurcharges": [
        {
          "key": "handling",
          "name": "Handling fee",
          "value": "string",
          "amount": 5
        }
      ],
      "customFieldValues": {},
      "adminFieldValues": {},
      "tags": [
        "string"
      ],
      "ruleDiscountAmount": "0.00",
      "appliedRules": [
        {
          "id": "clx1a2b3c4d5e6f7g8h9",
          "name": "Summer sale",
          "type": "ORDER_DISCOUNT",
          "discountAmount": "10.00"
        }
      ],
      "currency": "USD",
      "status": "PENDING",
      "financialStatus": "paid",
      "statusLabel": {
        "id": "clx1a2b3c4d5e6f7g8h9",
        "name": "Packing",
        "color": "#3B82F6",
        "canonicalStatus": "PROCESSING",
        "isSystem": true
      },
      "notes": "Leave at the door",
      "paymentMethod": "card",
      "isTestOrder": true,
      "customer": {
        "email": "[email protected]",
        "name": "Dana Cohen"
      },
      "shippingAddress": {
        "firstName": "Dana",
        "lastName": "Cohen",
        "name": "Dana Cohen",
        "company": "Acme Ltd",
        "line1": "Herzl 12",
        "line2": "Apt 4",
        "city": "Tel Aviv",
        "state": "Center District",
        "country": "IL",
        "postalCode": "6578301",
        "phone": "+972501234567"
      },
      "billingAddress": {
        "firstName": "Dana",
        "lastName": "Cohen",
        "name": "Dana Cohen",
        "company": "Acme Ltd",
        "line1": "Herzl 12",
        "line2": "Apt 4",
        "city": "Tel Aviv",
        "state": "Center District",
        "country": "IL",
        "postalCode": "6578301",
        "phone": "+972501234567"
      },
      "items": [
        {
          "productId": "clx1a2b3c4d5e6f7g8h9",
          "variantId": "clx1a2b3c4d5e6f7g8h9",
          "sku": "TSHIRT-BLK-M",
          "name": "Classic T-Shirt",
          "quantity": 2,
          "price": "29.90",
          "unitPrice": "29.90",
          "totalPrice": "59.80",
          "image": "https://cdn.example.com/products/tshirt.jpg"
        }
      ],
      "createdAt": "2019-08-24T14:15:22Z",
      "syncWarning": "Sync failed",
      "paymentStatus": "CAPTURED",
      "paymentProviderType": "card",
      "paymentProviderName": "Stripe",
      "paymentId": "clx1a2b3c4d5e6f7g8h9",
      "paymentExternalId": "clx1a2b3c4d5e6f7g8h9",
      "paymentAmount": "86.26",
      "paymentCurrency": "ILS",
      "paymentRefundedAmount": "0.00",
      "invoiceUrl": "https://invoices.example.com/INV-1042.pdf",
      "invoiceNumber": "INV-1042",
      "numberOfPayments": 1,
      "paymentCapabilities": {
        "refund": true,
        "manualRefundUrl": "https://dashboard.provider.example.com/payments"
      },
      "refunds": [
        {
          "id": "clx1a2b3c4d5e6f7g8h9",
          "amount": "29.90",
          "reason": "Damaged in transit",
          "status": "COMPLETED",
          "type": "partial",
          "source": "PLATFORM",
          "createdAt": "2019-08-24T14:15:22Z",
          "creditNoteNumber": "CN-1042",
          "creditNoteUrl": "https://invoices.example.com/CN-1042.pdf",
          "taxAmount": "4.56",
          "netAmount": "25.34",
          "shippingAmount": "0.00",
          "shippingTaxAmount": "0.00",
          "taxBreakdown": [
            {
              "name": "string",
              "rate": 0,
              "amount": "string",
              "taxClassId": "string"
            }
          ]
        }
      ],
      "tenders": [
        {
          "id": "clx1a2b3c4d5e6f7g8h9",
          "type": "GIFT_CARD",
          "amountBase": "50.00",
          "currencyBase": "ILS",
          "giftCard": {
            "id": "clx1a2b3c4d5e6f7g8h9",
            "codeLast4": "K7QX"
          }
        }
      ],
      "isRead": true,
      "downloadMeta": {
        "files": [
          {
            "fileId": "clx1a2b3c4d5e6f7g8h9",
            "productId": "clx1a2b3c4d5e6f7g8h9",
            "productName": "Photo pack",
            "fileName": "photos.zip",
            "downloadsUsed": 1,
            "downloadLimit": 3,
            "expiresAt": "2019-08-24T14:15:22Z"
          }
        ]
      },
      "trackingNumber": "1Z999AA10123456784",
      "trackingUrl": "https://carrier.example.com/track/1Z999AA10123456784",
      "carrier": "ups",
      "shippingSelection": {
        "carrier": "ups",
        "service": "ground",
        "methodName": "Standard shipping",
        "amount": "15.00"
      },
      "deliveryType": "shipping",
      "pickupLocationData": {
        "name": "Main store",
        "line1": "Herzl 12",
        "line2": "Apt 4",
        "city": "Tel Aviv",
        "region": "Center District",
        "postalCode": "6578301",
        "country": "IL",
        "phone": "+972501234567",
        "rateName": "Store pickup"
      },
      "shippingPickupPoint": {}
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 137,
    "totalPages": 7
  }
}

{
  "statusCode": 400,
  "code": "VALIDATION_FAILED",
  "message": "name should not be empty, price must be a positive number",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/orders"
}

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/orders"
}

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key does not have the required scope: products:write",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/orders"
}

{
  "statusCode": 429,
  "code": "RATE_LIMITED",
  "message": "Too many requests",
  "details": {
    "retryAfterSeconds": 12
  },
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/store"
}

Create a new order

Creates an order. The order is always created as PENDING, whatever is sent: later status changes go through payment and fulfillment or PATCH /v1/orders/{id}. Honors Idempotency-Key header: retries with the same key return the original response. See /docs/api/idempotency.

Authorization

AuthorizationBearer <token>

In: header

Header Parameters

Idempotency-Key?string

Client-supplied key (a UUID v4 is the recommended form, max 255 characters) that makes this mutation safe to retry.

Replay window: 24 hours. The first response for a key is cached; a retry inside the window with the same request body returns the original status and body without re-running the handler.
Reusing a key with a different body returns 409 Conflict with code: "IDEMPOTENCY_KEY_REUSED". The request fingerprint (method + path + body hash) is compared against the stored one; a mismatch is refused rather than served the old response.
Keys are scoped to the calling credential and store — two API keys may safely use the same key value.
Error responses are cached too, so a retry of a request that failed validation returns the same 400 immediately.
Sending this header on a GET returns 400 with code: "IDEMPOTENCY_KEY_NOT_SUPPORTED" — GETs are already idempotent.
Support is per-route and this parameter is the authoritative signal: a key sent to a route that does not declare it is accepted and silently ignored.

See /docs/api/idempotency.

Lengthlength <= 255

Request Body

itemsarray<CreateOrderItemDto>

Line items being purchased (maximum 500)

Itemsitems <= 500

customer?CreateOrderCustomerDto

Customer details for the order. Optional for guest orders.

customerId?string

Existing Brainerce customer ID (mutually exclusive with customer)

Lengthlength <= 128

externalId?string

External system identifier for this order (idempotency aid for migrations).

Lengthlength <= 128

status?string

Initial order status. Most callers should NOT set this, because the system manages status transitions through the payment + fulfillment pipeline. Setting to a paid-looking status (e.g. SHIPPED, DELIVERED) without going through payment will be rejected: the controller currently forces the status to PENDING on creation regardless of caller input, to prevent payment-bypass.

currency?string

Currency code (ISO-4217). Defaults to the store currency.

Lengthlength <= 3

discountAmount?number

Total discount amount applied

couponCode?string

Applied coupon code (snapshot)

Lengthlength <= 100

shippingAmount?number

Shipping amount

taxAmount?number

Tax amount

paymentMethod?string

Payment method identifier

Lengthlength <= 50

notes?string

Free-form notes attached to the order

Lengthlength <= 2000

sourceName?string

Source name (e.g. "web", "pos", "import")

Lengthlength <= 100

shippingAddress?object

Optional shipping address. line1, city, country and postalCode are required when an address is sent.

billingAddress?object

Optional billing address. line1, city, country and postalCode are required when an address is sent.

curl -X POST "https://api.brainerce.com/api/v1/orders" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "productId": "prd_01H...",
        "quantity": 1,
        "price": 19.99
      }
    ]
  }'

curl -X POST "https://api.brainerce.com/api/v1/orders" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "items": [      {        "productId": "prd_01H...",        "quantity": 1,        "price": 19.99      }    ]  }'

{
  "id": "clx1a2b3c4d5e6f7g8h9",
  "storeId": "clx1a2b3c4d5e6f7g8h9",
  "externalId": "clx1a2b3c4d5e6f7g8h9",
  "orderNumber": "ORD-20260115-0042",
  "platform": "CUSTOM",
  "sourceName": "erp-import",
  "totalAmount": "86.26",
  "subtotal": "59.80",
  "taxAmount": "11.46",
  "taxBreakdown": {
    "subtotal": 50.9,
    "shippingNet": 12.71,
    "totalTax": 11.46,
    "total": 75.1,
    "pricesIncludeTax": true,
    "taxCoverage": "full",
    "breakdown": [
      {
        "name": "VAT",
        "rate": 0.18,
        "amount": 12.45
      }
    ],
    "currency": "USD"
  },
  "shippingAmount": "15.00",
  "discountAmount": "5.00",
  "couponCode": "WELCOME10",
  "couponDiscount": "5.00",
  "coupon": {
    "title": "Welcome offer",
    "type": "PERCENTAGE",
    "value": "10.00"
  },
  "surchargeAmount": "0.00",
  "appliedSurcharges": [
    {
      "key": "handling",
      "name": "Handling fee",
      "value": "string",
      "amount": 5
    }
  ],
  "customFieldValues": {},
  "adminFieldValues": {},
  "tags": [
    "string"
  ],
  "ruleDiscountAmount": "0.00",
  "appliedRules": [
    {
      "id": "clx1a2b3c4d5e6f7g8h9",
      "name": "Summer sale",
      "type": "ORDER_DISCOUNT",
      "discountAmount": "10.00"
    }
  ],
  "currency": "USD",
  "status": "PENDING",
  "financialStatus": "paid",
  "statusLabel": {
    "id": "clx1a2b3c4d5e6f7g8h9",
    "name": "Packing",
    "color": "#3B82F6",
    "canonicalStatus": "PROCESSING",
    "isSystem": true
  },
  "notes": "Leave at the door",
  "paymentMethod": "card",
  "isTestOrder": true,
  "customer": {
    "email": "[email protected]",
    "name": "Dana Cohen"
  },
  "shippingAddress": {
    "firstName": "Dana",
    "lastName": "Cohen",
    "name": "Dana Cohen",
    "company": "Acme Ltd",
    "line1": "Herzl 12",
    "line2": "Apt 4",
    "city": "Tel Aviv",
    "state": "Center District",
    "country": "IL",
    "postalCode": "6578301",
    "phone": "+972501234567"
  },
  "billingAddress": {
    "firstName": "Dana",
    "lastName": "Cohen",
    "name": "Dana Cohen",
    "company": "Acme Ltd",
    "line1": "Herzl 12",
    "line2": "Apt 4",
    "city": "Tel Aviv",
    "state": "Center District",
    "country": "IL",
    "postalCode": "6578301",
    "phone": "+972501234567"
  },
  "items": [
    {
      "productId": "clx1a2b3c4d5e6f7g8h9",
      "variantId": "clx1a2b3c4d5e6f7g8h9",
      "sku": "TSHIRT-BLK-M",
      "name": "Classic T-Shirt",
      "quantity": 2,
      "price": "29.90",
      "unitPrice": "29.90",
      "totalPrice": "59.80",
      "image": "https://cdn.example.com/products/tshirt.jpg"
    }
  ],
  "createdAt": "2019-08-24T14:15:22Z",
  "syncWarning": "Sync failed",
  "paymentStatus": "CAPTURED",
  "paymentProviderType": "card",
  "paymentProviderName": "Stripe",
  "paymentId": "clx1a2b3c4d5e6f7g8h9",
  "paymentExternalId": "clx1a2b3c4d5e6f7g8h9",
  "paymentAmount": "86.26",
  "paymentCurrency": "ILS",
  "paymentRefundedAmount": "0.00",
  "invoiceUrl": "https://invoices.example.com/INV-1042.pdf",
  "invoiceNumber": "INV-1042",
  "numberOfPayments": 1,
  "paymentCapabilities": {
    "refund": true,
    "manualRefundUrl": "https://dashboard.provider.example.com/payments"
  },
  "refunds": [
    {
      "id": "clx1a2b3c4d5e6f7g8h9",
      "amount": "29.90",
      "reason": "Damaged in transit",
      "status": "COMPLETED",
      "type": "partial",
      "source": "PLATFORM",
      "createdAt": "2019-08-24T14:15:22Z",
      "creditNoteNumber": "CN-1042",
      "creditNoteUrl": "https://invoices.example.com/CN-1042.pdf",
      "taxAmount": "4.56",
      "netAmount": "25.34",
      "shippingAmount": "0.00",
      "shippingTaxAmount": "0.00",
      "taxBreakdown": [
        {
          "name": "string",
          "rate": 0,
          "amount": "string",
          "taxClassId": "string"
        }
      ]
    }
  ],
  "tenders": [
    {
      "id": "clx1a2b3c4d5e6f7g8h9",
      "type": "GIFT_CARD",
      "amountBase": "50.00",
      "currencyBase": "ILS",
      "giftCard": {
        "id": "clx1a2b3c4d5e6f7g8h9",
        "codeLast4": "K7QX"
      }
    }
  ],
  "isRead": true,
  "downloadMeta": {
    "files": [
      {
        "fileId": "clx1a2b3c4d5e6f7g8h9",
        "productId": "clx1a2b3c4d5e6f7g8h9",
        "productName": "Photo pack",
        "fileName": "photos.zip",
        "downloadsUsed": 1,
        "downloadLimit": 3,
        "expiresAt": "2019-08-24T14:15:22Z"
      }
    ]
  },
  "trackingNumber": "1Z999AA10123456784",
  "trackingUrl": "https://carrier.example.com/track/1Z999AA10123456784",
  "carrier": "ups",
  "shippingSelection": {
    "carrier": "ups",
    "service": "ground",
    "methodName": "Standard shipping",
    "amount": "15.00"
  },
  "deliveryType": "shipping",
  "pickupLocationData": {
    "name": "Main store",
    "line1": "Herzl 12",
    "line2": "Apt 4",
    "city": "Tel Aviv",
    "region": "Center District",
    "postalCode": "6578301",
    "country": "IL",
    "phone": "+972501234567",
    "rateName": "Store pickup"
  },
  "shippingPickupPoint": {}
}

{
  "statusCode": 400,
  "code": "VALIDATION_FAILED",
  "message": "name should not be empty, price must be a positive number",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/orders"
}

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/orders"
}

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key does not have the required scope: products:write",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/orders"
}

{
  "statusCode": 429,
  "code": "RATE_LIMITED",
  "message": "Too many requests",
  "details": {
    "retryAfterSeconds": 12
  },
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/store"
}

Get a single order by ID

Returns one order of this store with its line items, addresses, tax breakdown and refunds.

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

idstring

Order ID

curl -X GET "https://api.brainerce.com/api/v1/orders/string"

curl -X GET "https://api.brainerce.com/api/v1/orders/string"

{
  "id": "clx1a2b3c4d5e6f7g8h9",
  "storeId": "clx1a2b3c4d5e6f7g8h9",
  "externalId": "clx1a2b3c4d5e6f7g8h9",
  "orderNumber": "ORD-20260115-0042",
  "platform": "CUSTOM",
  "sourceName": "erp-import",
  "totalAmount": "86.26",
  "subtotal": "59.80",
  "taxAmount": "11.46",
  "taxBreakdown": {
    "subtotal": 50.9,
    "shippingNet": 12.71,
    "totalTax": 11.46,
    "total": 75.1,
    "pricesIncludeTax": true,
    "taxCoverage": "full",
    "breakdown": [
      {
        "name": "VAT",
        "rate": 0.18,
        "amount": 12.45
      }
    ],
    "currency": "USD"
  },
  "shippingAmount": "15.00",
  "discountAmount": "5.00",
  "couponCode": "WELCOME10",
  "couponDiscount": "5.00",
  "coupon": {
    "title": "Welcome offer",
    "type": "PERCENTAGE",
    "value": "10.00"
  },
  "surchargeAmount": "0.00",
  "appliedSurcharges": [
    {
      "key": "handling",
      "name": "Handling fee",
      "value": "string",
      "amount": 5
    }
  ],
  "customFieldValues": {},
  "adminFieldValues": {},
  "tags": [
    "string"
  ],
  "ruleDiscountAmount": "0.00",
  "appliedRules": [
    {
      "id": "clx1a2b3c4d5e6f7g8h9",
      "name": "Summer sale",
      "type": "ORDER_DISCOUNT",
      "discountAmount": "10.00"
    }
  ],
  "currency": "USD",
  "status": "PENDING",
  "financialStatus": "paid",
  "statusLabel": {
    "id": "clx1a2b3c4d5e6f7g8h9",
    "name": "Packing",
    "color": "#3B82F6",
    "canonicalStatus": "PROCESSING",
    "isSystem": true
  },
  "notes": "Leave at the door",
  "paymentMethod": "card",
  "isTestOrder": true,
  "customer": {
    "email": "[email protected]",
    "name": "Dana Cohen"
  },
  "shippingAddress": {
    "firstName": "Dana",
    "lastName": "Cohen",
    "name": "Dana Cohen",
    "company": "Acme Ltd",
    "line1": "Herzl 12",
    "line2": "Apt 4",
    "city": "Tel Aviv",
    "state": "Center District",
    "country": "IL",
    "postalCode": "6578301",
    "phone": "+972501234567"
  },
  "billingAddress": {
    "firstName": "Dana",
    "lastName": "Cohen",
    "name": "Dana Cohen",
    "company": "Acme Ltd",
    "line1": "Herzl 12",
    "line2": "Apt 4",
    "city": "Tel Aviv",
    "state": "Center District",
    "country": "IL",
    "postalCode": "6578301",
    "phone": "+972501234567"
  },
  "items": [
    {
      "productId": "clx1a2b3c4d5e6f7g8h9",
      "variantId": "clx1a2b3c4d5e6f7g8h9",
      "sku": "TSHIRT-BLK-M",
      "name": "Classic T-Shirt",
      "quantity": 2,
      "price": "29.90",
      "unitPrice": "29.90",
      "totalPrice": "59.80",
      "image": "https://cdn.example.com/products/tshirt.jpg"
    }
  ],
  "createdAt": "2019-08-24T14:15:22Z",
  "syncWarning": "Sync failed",
  "paymentStatus": "CAPTURED",
  "paymentProviderType": "card",
  "paymentProviderName": "Stripe",
  "paymentId": "clx1a2b3c4d5e6f7g8h9",
  "paymentExternalId": "clx1a2b3c4d5e6f7g8h9",
  "paymentAmount": "86.26",
  "paymentCurrency": "ILS",
  "paymentRefundedAmount": "0.00",
  "invoiceUrl": "https://invoices.example.com/INV-1042.pdf",
  "invoiceNumber": "INV-1042",
  "numberOfPayments": 1,
  "paymentCapabilities": {
    "refund": true,
    "manualRefundUrl": "https://dashboard.provider.example.com/payments"
  },
  "refunds": [
    {
      "id": "clx1a2b3c4d5e6f7g8h9",
      "amount": "29.90",
      "reason": "Damaged in transit",
      "status": "COMPLETED",
      "type": "partial",
      "source": "PLATFORM",
      "createdAt": "2019-08-24T14:15:22Z",
      "creditNoteNumber": "CN-1042",
      "creditNoteUrl": "https://invoices.example.com/CN-1042.pdf",
      "taxAmount": "4.56",
      "netAmount": "25.34",
      "shippingAmount": "0.00",
      "shippingTaxAmount": "0.00",
      "taxBreakdown": [
        {
          "name": "string",
          "rate": 0,
          "amount": "string",
          "taxClassId": "string"
        }
      ]
    }
  ],
  "tenders": [
    {
      "id": "clx1a2b3c4d5e6f7g8h9",
      "type": "GIFT_CARD",
      "amountBase": "50.00",
      "currencyBase": "ILS",
      "giftCard": {
        "id": "clx1a2b3c4d5e6f7g8h9",
        "codeLast4": "K7QX"
      }
    }
  ],
  "isRead": true,
  "downloadMeta": {
    "files": [
      {
        "fileId": "clx1a2b3c4d5e6f7g8h9",
        "productId": "clx1a2b3c4d5e6f7g8h9",
        "productName": "Photo pack",
        "fileName": "photos.zip",
        "downloadsUsed": 1,
        "downloadLimit": 3,
        "expiresAt": "2019-08-24T14:15:22Z"
      }
    ]
  },
  "trackingNumber": "1Z999AA10123456784",
  "trackingUrl": "https://carrier.example.com/track/1Z999AA10123456784",
  "carrier": "ups",
  "shippingSelection": {
    "carrier": "ups",
    "service": "ground",
    "methodName": "Standard shipping",
    "amount": "15.00"
  },
  "deliveryType": "shipping",
  "pickupLocationData": {
    "name": "Main store",
    "line1": "Herzl 12",
    "line2": "Apt 4",
    "city": "Tel Aviv",
    "region": "Center District",
    "postalCode": "6578301",
    "country": "IL",
    "phone": "+972501234567",
    "rateName": "Store pickup"
  },
  "shippingPickupPoint": {}
}

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/orders/{id}"
}

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key does not have the required scope: products:write",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/orders/{id}"
}

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/orders/{id}"
}

{
  "statusCode": 429,
  "code": "RATE_LIMITED",
  "message": "Too many requests",
  "details": {
    "retryAfterSeconds": 12
  },
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/store"
}

Update an order

Changes the order status. Moves that are not allowed answer 400 (for example out of CANCELLED or REFUNDED), SHIPPED, COMPLETED and FULFILLED need a paid order, and PAID needs a captured payment. Without status the order is returned unchanged. Supports Idempotency-Key header for safe retries.

Replay window: 24 hours. The first response for a key is cached; a retry inside the window with the same request body returns the original status and body without re-running the handler.
Reusing a key with a different body returns 409 Conflict with code: "IDEMPOTENCY_KEY_REUSED". The request fingerprint (method + path + body hash) is compared against the stored one; a mismatch is refused rather than served the old response.
Keys are scoped to the calling credential and store — two API keys may safely use the same key value.
Error responses are cached too, so a retry of a request that failed validation returns the same 400 immediately.
Sending this header on a GET returns 400 with code: "IDEMPOTENCY_KEY_NOT_SUPPORTED" — GETs are already idempotent.
Support is per-route and this parameter is the authoritative signal: a key sent to a route that does not declare it is accepted and silently ignored.

See /docs/api/idempotency.

Lengthlength <= 255

Request Body

status?string

New order status. Compared case-insensitively.

Value in

"DRAFT" | "PENDING" | "PROCESSING" | "ON_HOLD" | "PAID" | "SHIPPED" | "DELIVERED" | "COMPLETED" | "FULFILLED" | "CANCELLED" | "REFUNDED" | "PARTIALLY_REFUNDED"

curl -X PATCH "https://api.brainerce.com/api/v1/orders/string" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  -d '{}'

curl -X PATCH "https://api.brainerce.com/api/v1/orders/string" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{}'

{
  "id": "clx1a2b3c4d5e6f7g8h9",
  "storeId": "clx1a2b3c4d5e6f7g8h9",
  "externalId": "clx1a2b3c4d5e6f7g8h9",
  "orderNumber": "ORD-20260115-0042",
  "platform": "CUSTOM",
  "sourceName": "erp-import",
  "totalAmount": "86.26",
  "subtotal": "59.80",
  "taxAmount": "11.46",
  "taxBreakdown": {
    "subtotal": 50.9,
    "shippingNet": 12.71,
    "totalTax": 11.46,
    "total": 75.1,
    "pricesIncludeTax": true,
    "taxCoverage": "full",
    "breakdown": [
      {
        "name": "VAT",
        "rate": 0.18,
        "amount": 12.45
      }
    ],
    "currency": "USD"
  },
  "shippingAmount": "15.00",
  "discountAmount": "5.00",
  "couponCode": "WELCOME10",
  "couponDiscount": "5.00",
  "coupon": {
    "title": "Welcome offer",
    "type": "PERCENTAGE",
    "value": "10.00"
  },
  "surchargeAmount": "0.00",
  "appliedSurcharges": [
    {
      "key": "handling",
      "name": "Handling fee",
      "value": "string",
      "amount": 5
    }
  ],
  "customFieldValues": {},
  "adminFieldValues": {},
  "tags": [
    "string"
  ],
  "ruleDiscountAmount": "0.00",
  "appliedRules": [
    {
      "id": "clx1a2b3c4d5e6f7g8h9",
      "name": "Summer sale",
      "type": "ORDER_DISCOUNT",
      "discountAmount": "10.00"
    }
  ],
  "currency": "USD",
  "status": "PENDING",
  "financialStatus": "paid",
  "statusLabel": {
    "id": "clx1a2b3c4d5e6f7g8h9",
    "name": "Packing",
    "color": "#3B82F6",
    "canonicalStatus": "PROCESSING",
    "isSystem": true
  },
  "notes": "Leave at the door",
  "paymentMethod": "card",
  "isTestOrder": true,
  "customer": {
    "email": "[email protected]",
    "name": "Dana Cohen"
  },
  "shippingAddress": {
    "firstName": "Dana",
    "lastName": "Cohen",
    "name": "Dana Cohen",
    "company": "Acme Ltd",
    "line1": "Herzl 12",
    "line2": "Apt 4",
    "city": "Tel Aviv",
    "state": "Center District",
    "country": "IL",
    "postalCode": "6578301",
    "phone": "+972501234567"
  },
  "billingAddress": {
    "firstName": "Dana",
    "lastName": "Cohen",
    "name": "Dana Cohen",
    "company": "Acme Ltd",
    "line1": "Herzl 12",
    "line2": "Apt 4",
    "city": "Tel Aviv",
    "state": "Center District",
    "country": "IL",
    "postalCode": "6578301",
    "phone": "+972501234567"
  },
  "items": [
    {
      "productId": "clx1a2b3c4d5e6f7g8h9",
      "variantId": "clx1a2b3c4d5e6f7g8h9",
      "sku": "TSHIRT-BLK-M",
      "name": "Classic T-Shirt",
      "quantity": 2,
      "price": "29.90",
      "unitPrice": "29.90",
      "totalPrice": "59.80",
      "image": "https://cdn.example.com/products/tshirt.jpg"
    }
  ],
  "createdAt": "2019-08-24T14:15:22Z",
  "syncWarning": "Sync failed",
  "paymentStatus": "CAPTURED",
  "paymentProviderType": "card",
  "paymentProviderName": "Stripe",
  "paymentId": "clx1a2b3c4d5e6f7g8h9",
  "paymentExternalId": "clx1a2b3c4d5e6f7g8h9",
  "paymentAmount": "86.26",
  "paymentCurrency": "ILS",
  "paymentRefundedAmount": "0.00",
  "invoiceUrl": "https://invoices.example.com/INV-1042.pdf",
  "invoiceNumber": "INV-1042",
  "numberOfPayments": 1,
  "paymentCapabilities": {
    "refund": true,
    "manualRefundUrl": "https://dashboard.provider.example.com/payments"
  },
  "refunds": [
    {
      "id": "clx1a2b3c4d5e6f7g8h9",
      "amount": "29.90",
      "reason": "Damaged in transit",
      "status": "COMPLETED",
      "type": "partial",
      "source": "PLATFORM",
      "createdAt": "2019-08-24T14:15:22Z",
      "creditNoteNumber": "CN-1042",
      "creditNoteUrl": "https://invoices.example.com/CN-1042.pdf",
      "taxAmount": "4.56",
      "netAmount": "25.34",
      "shippingAmount": "0.00",
      "shippingTaxAmount": "0.00",
      "taxBreakdown": [
        {
          "name": "string",
          "rate": 0,
          "amount": "string",
          "taxClassId": "string"
        }
      ]
    }
  ],
  "tenders": [
    {
      "id": "clx1a2b3c4d5e6f7g8h9",
      "type": "GIFT_CARD",
      "amountBase": "50.00",
      "currencyBase": "ILS",
      "giftCard": {
        "id": "clx1a2b3c4d5e6f7g8h9",
        "codeLast4": "K7QX"
      }
    }
  ],
  "isRead": true,
  "downloadMeta": {
    "files": [
      {
        "fileId": "clx1a2b3c4d5e6f7g8h9",
        "productId": "clx1a2b3c4d5e6f7g8h9",
        "productName": "Photo pack",
        "fileName": "photos.zip",
        "downloadsUsed": 1,
        "downloadLimit": 3,
        "expiresAt": "2019-08-24T14:15:22Z"
      }
    ]
  },
  "trackingNumber": "1Z999AA10123456784",
  "trackingUrl": "https://carrier.example.com/track/1Z999AA10123456784",
  "carrier": "ups",
  "shippingSelection": {
    "carrier": "ups",
    "service": "ground",
    "methodName": "Standard shipping",
    "amount": "15.00"
  },
  "deliveryType": "shipping",
  "pickupLocationData": {
    "name": "Main store",
    "line1": "Herzl 12",
    "line2": "Apt 4",
    "city": "Tel Aviv",
    "region": "Center District",
    "postalCode": "6578301",
    "country": "IL",
    "phone": "+972501234567",
    "rateName": "Store pickup"
  },
  "shippingPickupPoint": {}
}

{
  "statusCode": 400,
  "code": "VALIDATION_FAILED",
  "message": "name should not be empty, price must be a positive number",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/orders/{id}"
}

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/orders/{id}"
}

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key does not have the required scope: products:write",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/orders/{id}"
}

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/orders/{id}"
}

{
  "statusCode": 429,
  "code": "RATE_LIMITED",
  "message": "Too many requests",
  "details": {
    "retryAfterSeconds": 12
  },
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/store"
}

Default1

Range1 <= value

limit?integer

Items per page. Default 20. Maximum 100. Larger values are capped to 100.

Default20

Range1 <= value <= 100

curl -X GET "https://api.brainerce.com/api/v1/customers/string/orders?page=1&limit=20"

curl -X GET "https://api.brainerce.com/api/v1/customers/string/orders?page=1&limit=20"

{
  "data": [
    {
      "id": "clx1a2b3c4d5e6f7g8h9",
      "externalId": "clx1a2b3c4d5e6f7g8h9",
      "orderNumber": "#1001",
      "status": "PENDING",
      "totalAmount": "86.26",
      "currency": "USD",
      "subtotal": "59.80",
      "discountAmount": "5.00",
      "couponCode": "WELCOME10",
      "couponDiscount": "5.00",
      "ruleDiscountAmount": "0.00",
      "appliedDiscounts": [
        {}
      ],
      "shippingAmount": "15.00",
      "taxAmount": "11.46",
      "shippingAddress": {
        "firstName": "string",
        "lastName": "string",
        "name": "string",
        "company": "string",
        "line1": "string",
        "line2": "string",
        "city": "string",
        "state": "string",
        "country": "string",
        "postalCode": "string",
        "phone": "string"
      },
      "billingAddress": {
        "firstName": "string",
        "lastName": "string",
        "name": "string",
        "company": "string",
        "line1": "string",
        "line2": "string",
        "city": "string",
        "state": "string",
        "country": "string",
        "postalCode": "string",
        "phone": "string"
      },
      "items": [
        {
          "productId": "clx1a2b3c4d5e6f7g8h9",
          "variantId": "clx1a2b3c4d5e6f7g8h9",
          "sku": "TSHIRT-BLK-M",
          "name": "Classic T-Shirt",
          "quantity": 2,
          "price": "29.90",
          "unitPrice": "29.90",
          "totalPrice": "59.80",
          "image": "https://cdn.example.com/products/tshirt.jpg",
          "customizations": {},
          "modifiers": [
            {
              "modifierId": "clx1a2b3c4d5e6f7g8h9",
              "groupId": "clx1a2b3c4d5e6f7g8h9",
              "groupName": "Toppings",
              "name": "Extra cheese",
              "priceDelta": "5.00",
              "freeApplied": true,
              "effectivePrice": "5.00"
            }
          ]
        }
      ],
      "paymentMethod": "card",
      "financialStatus": "paid",
      "fulfillmentStatus": "unfulfilled",
      "trackingNumber": "1Z999AA10123456784",
      "trackingUrl": "https://carrier.example.com/track/1Z999AA10123456784",
      "carrier": "ups",
      "shippedAt": "2019-08-24T14:15:22Z",
      "deliveredAt": "2019-08-24T14:15:22Z",
      "statusHistory": [
        {}
      ],
      "platform": "CUSTOM",
      "createdAt": "2019-08-24T14:15:22Z",
      "notes": "Leave at the door",
      "hasDownloads": true,
      "invoiceUrl": "https://invoices.example.com/INV-1042.pdf",
      "invoiceNumber": "INV-1042"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 137,
    "totalPages": 7
  }
}

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/customers/{id}/orders"
}

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key does not have the required scope: products:write",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/customers/{id}/orders"
}

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/customers/{id}/orders"
}

{
  "statusCode": 429,
  "code": "RATE_LIMITED",
  "message": "Too many requests",
  "details": {
    "retryAfterSeconds": 12
  },
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/store"
}

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default