Brainerce
Help CenterPricingResourcesDashboard
API ReferenceEndpointsShipping

Shipping

Shipping zones group regions (countries/states) into pricing buckets, and rates define what each zone costs to ship to. The checkout flow uses these to compute shipping options for each order.

List shipping destinations

GET
/vc/{connectionId}/shipping/destinations

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

Header Parameters

originstring
curl -X GET "https://api.brainerce.com/api/vc/string/shipping/destinations" \  -H "origin: string"
{
  "worldwide": false,
  "countries": [
    {
      "code": "US",
      "name": "United States"
    }
  ],
  "regions": {
    "property1": [
      {
        "code": "US",
        "name": "United States"
      }
    ],
    "property2": [
      {
        "code": "US",
        "name": "United States"
      }
    ]
  }
}

List shipping zones with pagination

GET
/v1/shipping/zones

Authorization

AuthorizationBearer <token>

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

In: header

Query Parameters

page?number
limit?number
search?string
isActive?boolean
curl -X GET "https://api.brainerce.com/api/v1/shipping/zones?page=0&limit=0&search=string&isActive=true"
{
  "data": [
    {
      "id": "string",
      "accountId": "string",
      "storeId": "string",
      "name": "US Domestic",
      "countries": [
        "string"
      ],
      "regions": {},
      "postalCodes": {},
      "geometry": {},
      "hasGeometry": true,
      "geometryLabels": [
        "string"
      ],
      "regionIds": [
        "string"
      ],
      "salesChannelIds": [
        "string"
      ],
      "priority": 0,
      "isActive": true,
      "rateSource": "string",
      "platformSettings": {},
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z",
      "rates": [
        {
          "id": "string",
          "zoneId": "string",
          "name": "Standard Shipping",
          "description": "string",
          "type": "string",
          "rateConfig": {},
          "minDeliveryDays": 0,
          "maxDeliveryDays": 0,
          "handlingTime": 0,
          "taxStatus": "string",
          "minOrderAmount": "string",
          "maxCost": "string",
          "classCosts": {},
          "classCalculationType": "string",
          "isActive": true,
          "platformSettings": {},
          "createdAt": "2019-08-24T14:15:22Z",
          "updatedAt": "2019-08-24T14:15:22Z"
        }
      ],
      "_count": {
        "rates": 0
      },
      "ratesCount": 0
    }
  ],
  "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/shipping/zones"
}

{
  "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/shipping/zones"
}

Create a new shipping zone

Supports Idempotency-Key header for safe retries.

POST
/v1/shipping/zones

Authorization

AuthorizationBearer <token>

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

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

namestring

Display name (shown in the dashboard, never to shoppers).

countriesarray<string>

ISO 3166-1 alpha-2 country codes covered by this zone.

regions?object

Per-country region (state/province) restriction. Keyed by ISO country code; value is an array of subdivision codes. Addresses outside the listed regions do not match the zone.

Empty Object

postalCodes?object

Per-country postal-code patterns (exact, prefix 941*, or range 94100-94199). Further narrows the zone after regions.

Empty Object

geometry?object

Polygon zone definition, a hand-drawn shape ("draw on map"). GeoJSON Polygon or MultiPolygon, ring coordinates in [lng, lat] order (RFC 7946). Independent of countries/regions/postalCodes: a zone matches if the address satisfies either the country-list coverage or the polygon coverage, so both may be set on the same zone.

Empty Object

geometryLabels?array<string>

Display-only label per shape in geometry (index 0 = the Polygon, or a MultiPolygon's Nth part), e.g. the searched place name ("Tel Aviv") instead of a generic "Custom area N". Purely cosmetic; never used for matching.

regionIds?array<string>

Region restriction (PRD §25). Region IDs this zone is limited to. Empty/omitted = available for any region (default). Non-empty = the zone is only offered to checkouts whose region is in the list.

salesChannelIds?array<string>

Sales-channel restriction. SalesChannel.id values (the public vc_* connectionId also accepted). Empty/omitted = available on every channel (default). Non-empty = the zone is only offered to checkouts from a channel in the list.

priority?number

Match priority: a lower value is evaluated first. Defaults to 0.

Default0
Range0 <= value
isActive?boolean

Whether this zone participates in rate calculation. Defaults to true.

Defaulttrue
curl -X POST "https://api.brainerce.com/api/v1/shipping/zones" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "name": "United States",    "countries": [      "US",      "CA",      "MX"    ]  }'
{
  "id": "string",
  "accountId": "string",
  "storeId": "string",
  "name": "US Domestic",
  "countries": [
    "string"
  ],
  "regions": {},
  "postalCodes": {},
  "geometry": {},
  "hasGeometry": true,
  "geometryLabels": [
    "string"
  ],
  "regionIds": [
    "string"
  ],
  "salesChannelIds": [
    "string"
  ],
  "priority": 0,
  "isActive": true,
  "rateSource": "string",
  "platformSettings": {},
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "rates": [
    {
      "id": "string",
      "zoneId": "string",
      "name": "Standard Shipping",
      "description": "string",
      "type": "string",
      "rateConfig": {},
      "minDeliveryDays": 0,
      "maxDeliveryDays": 0,
      "handlingTime": 0,
      "taxStatus": "string",
      "minOrderAmount": "string",
      "maxCost": "string",
      "classCosts": {},
      "classCalculationType": "string",
      "isActive": true,
      "platformSettings": {},
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ]
}

{
  "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/shipping/zones"
}

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

{
  "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/shipping/zones"
}

Get a single shipping zone by ID

GET
/v1/shipping/zones/{zoneId}

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

zoneIdstring

Shipping Zone ID

curl -X GET "https://api.brainerce.com/api/v1/shipping/zones/string"
{
  "id": "string",
  "accountId": "string",
  "storeId": "string",
  "name": "US Domestic",
  "countries": [
    "string"
  ],
  "regions": {},
  "postalCodes": {},
  "geometry": {},
  "hasGeometry": true,
  "geometryLabels": [
    "string"
  ],
  "regionIds": [
    "string"
  ],
  "salesChannelIds": [
    "string"
  ],
  "priority": 0,
  "isActive": true,
  "rateSource": "string",
  "platformSettings": {},
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "rates": [
    {
      "id": "string",
      "zoneId": "string",
      "name": "Standard Shipping",
      "description": "string",
      "type": "string",
      "rateConfig": {},
      "minDeliveryDays": 0,
      "maxDeliveryDays": 0,
      "handlingTime": 0,
      "taxStatus": "string",
      "minOrderAmount": "string",
      "maxCost": "string",
      "classCosts": {},
      "classCalculationType": "string",
      "isActive": true,
      "platformSettings": {},
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ]
}

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

{
  "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/shipping/zones/{zoneId}"
}

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

Update a shipping zone

Supports Idempotency-Key header for safe retries.

PATCH
/v1/shipping/zones/{zoneId}

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

zoneIdstring

Shipping Zone ID

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

name?string

Display name.

countries?array<string>

ISO 3166-1 alpha-2 country codes covered by this zone.

regions?object

Per-country region restriction (subdivision codes).

Empty Object

postalCodes?object

Per-country postal-code patterns.

Empty Object

geometry?object

Polygon zone definition ("draw on map"). GeoJSON Polygon or MultiPolygon, [lng, lat] ring coordinates. Pass null to clear a previously-set polygon. Omit to leave unchanged.

Empty Object

geometryLabels?array<string>

Display-only label per shape in geometry (index 0 = the Polygon, or a MultiPolygon's Nth part). Purely cosmetic; never used for matching. Omit to leave unchanged.

regionIds?array<string>

Region restriction (PRD §25). Region IDs this zone is limited to. Empty array = available for any region. Omit to leave unchanged.

salesChannelIds?array<string>

Sales-channel restriction. SalesChannel.id values (the public vc_* connectionId also accepted). Empty array = available on every channel. Omit to leave unchanged.

priority?number

Match priority: a lower value is evaluated first.

Range0 <= value
isActive?boolean

Whether this zone participates in rate calculation.

platformSettings?object

Per-platform overrides (e.g. Shopify zone ID mapping). Keyed by platform code; value is platform-specific.

Empty Object

curl -X PATCH "https://api.brainerce.com/api/v1/shipping/zones/string" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{}'
{
  "id": "string",
  "accountId": "string",
  "storeId": "string",
  "name": "US Domestic",
  "countries": [
    "string"
  ],
  "regions": {},
  "postalCodes": {},
  "geometry": {},
  "hasGeometry": true,
  "geometryLabels": [
    "string"
  ],
  "regionIds": [
    "string"
  ],
  "salesChannelIds": [
    "string"
  ],
  "priority": 0,
  "isActive": true,
  "rateSource": "string",
  "platformSettings": {},
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "rates": [
    {
      "id": "string",
      "zoneId": "string",
      "name": "Standard Shipping",
      "description": "string",
      "type": "string",
      "rateConfig": {},
      "minDeliveryDays": 0,
      "maxDeliveryDays": 0,
      "handlingTime": 0,
      "taxStatus": "string",
      "minOrderAmount": "string",
      "maxCost": "string",
      "classCosts": {},
      "classCalculationType": "string",
      "isActive": true,
      "platformSettings": {},
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ]
}

{
  "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/shipping/zones/{zoneId}"
}

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

{
  "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/shipping/zones/{zoneId}"
}

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

Delete a shipping zone

Supports Idempotency-Key header for safe retries.

DELETE
/v1/shipping/zones/{zoneId}

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

zoneIdstring

Shipping Zone ID

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
curl -X DELETE "https://api.brainerce.com/api/v1/shipping/zones/string" \  -H "Idempotency-Key: string"
Empty

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

{
  "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/shipping/zones/{zoneId}"
}

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

Get shipping rates for a zone

GET
/v1/shipping/zones/{zoneId}/rates

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

zoneIdstring

Shipping Zone ID

curl -X GET "https://api.brainerce.com/api/v1/shipping/zones/string/rates"
[
  {
    "id": "string",
    "zoneId": "string",
    "name": "Standard Shipping",
    "description": "string",
    "type": "string",
    "rateConfig": {},
    "minDeliveryDays": 0,
    "maxDeliveryDays": 0,
    "handlingTime": 0,
    "taxStatus": "string",
    "minOrderAmount": "string",
    "maxCost": "string",
    "classCosts": {},
    "classCalculationType": "string",
    "isActive": true,
    "platformSettings": {},
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
]

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

{
  "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/shipping/zones/{zoneId}/rates"
}

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

Create a shipping rate for a zone

Supports Idempotency-Key header for safe retries.

POST
/v1/shipping/zones/{zoneId}/rates

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

zoneIdstring

Shipping Zone ID

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

namestring

Display name shown to shoppers at checkout (e.g. "Standard", "Express").

description?string

Optional short description shown alongside the rate at checkout.

typestring

Rate calculation strategy.

Value in"FLAT_RATE" | "WEIGHT_BASED" | "PRICE_BASED" | "FREE" | "LOCAL_PICKUP"
rateConfigobject

Type-specific configuration. Shape depends on type; see the DTO docs. For FLAT_RATE use { amount: number }.

Empty Object

minDeliveryDays?number

Minimum delivery time in business days (inclusive).

Range0 <= value
maxDeliveryDays?number

Maximum delivery time in business days (inclusive).

Range0 <= value
handlingTime?number

Internal handling time in business days before the package ships.

Range1 <= value
taxStatus?string

Whether the delivery charge itself is taxed. TAXABLE (the default when omitted) taxes it at the Standard rate; NONE leaves postage untaxed.

Default"TAXABLE"
Value in"TAXABLE" | "NONE"
minOrderAmount?number

Minimum cart subtotal required for this rate to be offered. Use to hide low-value carts from free shipping.

Range0 <= value
maxCost?number

Optional cap on the computed cost. Useful for WEIGHT_BASED rates to prevent runaway charges.

Range0 <= value
isActive?boolean

Whether this rate is offered. Defaults to true.

Defaulttrue
classCosts?object

Per-shipping-class cost overrides. Keyed by ShippingClass.id; value is either a flat amount or { first, additional } for first-item + each-additional pricing.

Empty Object

classCalculationType?string

How classCosts are aggregated when the cart mixes classes. per_class charges once per distinct class; per_order once for the whole order; per_item per line-item.

Value in"per_class" | "per_order" | "per_item"
curl -X POST "https://api.brainerce.com/api/v1/shipping/zones/string/rates" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "name": "Standard Shipping",    "type": "FLAT_RATE",    "rateConfig": {      "amount": 9.99    }  }'
{
  "id": "string",
  "zoneId": "string",
  "name": "Standard Shipping",
  "description": "string",
  "type": "string",
  "rateConfig": {},
  "minDeliveryDays": 0,
  "maxDeliveryDays": 0,
  "handlingTime": 0,
  "taxStatus": "string",
  "minOrderAmount": "string",
  "maxCost": "string",
  "classCosts": {},
  "classCalculationType": "string",
  "isActive": true,
  "platformSettings": {},
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

{
  "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/shipping/zones/{zoneId}/rates"
}

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

{
  "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/shipping/zones/{zoneId}/rates"
}

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

Update a shipping rate

Supports Idempotency-Key header for safe retries.

PATCH
/v1/shipping/zones/{zoneId}/rates/{rateId}

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

zoneIdstring

Shipping Zone ID

rateIdstring

Shipping Rate ID

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

name?string

Display name shown to shoppers.

description?string

Short description shown alongside the rate.

type?string

Rate calculation strategy.

Value in"FLAT_RATE" | "WEIGHT_BASED" | "PRICE_BASED" | "FREE" | "LOCAL_PICKUP"
rateConfig?object

Type-specific configuration; shape depends on type.

Empty Object

minDeliveryDays?number

Minimum delivery time in business days.

Range0 <= value
maxDeliveryDays?number

Maximum delivery time in business days.

Range0 <= value
handlingTime?number

Internal handling time in business days.

Range1 <= value
taxStatus?string

Whether shipping itself is taxable.

Value in"TAXABLE" | "NONE"
minOrderAmount?number

Minimum cart subtotal for this rate to be offered.

Range0 <= value
maxCost?number

Optional cap on the computed cost.

Range0 <= value
isActive?boolean

Whether this rate is offered.

platformSettings?object

Per-platform overrides (e.g. Shopify rate ID mapping). Keyed by platform code.

Empty Object

classCosts?object

Per-shipping-class cost overrides.

Empty Object

classCalculationType?string

How classCosts are aggregated when the cart mixes classes.

Value in"per_class" | "per_order" | "per_item"
curl -X PATCH "https://api.brainerce.com/api/v1/shipping/zones/string/rates/string" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{}'
{
  "id": "string",
  "zoneId": "string",
  "name": "Standard Shipping",
  "description": "string",
  "type": "string",
  "rateConfig": {},
  "minDeliveryDays": 0,
  "maxDeliveryDays": 0,
  "handlingTime": 0,
  "taxStatus": "string",
  "minOrderAmount": "string",
  "maxCost": "string",
  "classCosts": {},
  "classCalculationType": "string",
  "isActive": true,
  "platformSettings": {},
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

{
  "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/shipping/zones/{zoneId}/rates/{rateId}"
}

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

{
  "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/shipping/zones/{zoneId}/rates/{rateId}"
}

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/shipping/zones/{zoneId}/rates/{rateId}"
}

Delete a shipping rate

Supports Idempotency-Key header for safe retries.

DELETE
/v1/shipping/zones/{zoneId}/rates/{rateId}

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

zoneIdstring

Shipping Zone ID

rateIdstring

Shipping Rate ID

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
curl -X DELETE "https://api.brainerce.com/api/v1/shipping/zones/string/rates/string" \  -H "Idempotency-Key: string"
Empty

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

{
  "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/shipping/zones/{zoneId}/rates/{rateId}"
}

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/shipping/zones/{zoneId}/rates/{rateId}"
}

List pickup locations

GET
/vc/{connectionId}/pickup-locations

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

Header Parameters

originstring
curl -X GET "https://api.brainerce.com/api/vc/string/pickup-locations" \  -H "origin: string"
{
  "pickupLocations": [
    {
      "id": "string",
      "name": "string",
      "rateName": "string",
      "address": {
        "line1": "5 Rothschild",
        "line2": "string",
        "city": "Tel Aviv",
        "region": "string",
        "postalCode": "6688218",
        "country": "IL"
      },
      "phone": "string",
      "hours": "string",
      "instructions": "string",
      "price": "0",
      "currency": "ILS"
    }
  ]
}

Metafields

Previous Page

Tax

Next Page

On this page

No Headings