Suppliers

GET/suppliers

List suppliers

Get a paginated list of suppliers for the current merchant. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. Deleted suppliers are excluded.

Optional attributes

Name
q
Type
string
Description
Search language filter. Supported fields: `name` (string), `uuid` (uuid). Substring matches require at least 3 characters. Clauses can be combined with `AND` / `OR`. Example: `name~"acme"`
Name
sorts
Type
array<Sort>
Description
Sort the results. Example: `sorts[0][field]=name&sorts[0][order]=1`
Name
page
Type
integer
Description
The page number to retrieve (1-indexed) 1
Name
per_page
Type
integer
Description
The number of suppliers per page 25

Request

GET/suppliers

curl -G https://YOUR_DOMAIN/api/suppliers \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Loading response...

POST/suppliers

Create a supplier

Create a supplier for the current merchant. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422.

Required attributes

Name
name
Type
string
Description
The name of the supplier Acme Wholesale
Name
default_currency
Type
string
Description
The ISO 4217 currency code used to pre-fill new cost tiers for this supplier's items USD

Request

POST/suppliers

curl -X POST https://YOUR_DOMAIN/api/suppliers \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Wholesale",
    "default_currency": "USD"
}'

Loading response...

GET/suppliers/{supplier_uuid}

Get a supplier

Get a single supplier by its UUID. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. Deleted suppliers are returned with `is_deleted` set to true.

Required attributes

Name
supplier_uuid
Type
string
Description
The UUID of the supplier

Request

GET/suppliers/{supplier_uuid}

curl -G https://YOUR_DOMAIN/api/suppliers/{supplier-uuid} \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Loading response...

PUT/suppliers/{supplier_uuid}

Update a supplier

Update a supplier's details. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. Only the properties present in the request body are changed; omitted properties are left as they are. Deleted suppliers cannot be updated and return a 404.

Required attributes

Name
supplier_uuid
Type
string
Description
The UUID of the supplier

Optional attributes

Name
name
Type
string
Description
The name of the supplier Acme Wholesale
Name
default_currency
Type
string
Description
The ISO 4217 currency code used to pre-fill new cost tiers for this supplier's items USD

Request

PUT/suppliers/{supplier_uuid}

curl -X PUT https://YOUR_DOMAIN/api/suppliers/{supplier-uuid} \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Wholesale",
    "default_currency": "USD"
}'

Loading response...

DELETE/suppliers/{supplier_uuid}

Delete a supplier

Delete a supplier. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. The supplier is soft deleted: it disappears from the list endpoint and is still readable on the detail endpoint with `is_deleted` set to true. Deleting an already deleted supplier returns a 404.

Required attributes

Name
supplier_uuid
Type
string
Description
The UUID of the supplier

Request

DELETE/suppliers/{supplier_uuid}

curl -X DELETE https://YOUR_DOMAIN/api/suppliers/{supplier-uuid} \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

GET/suppliers/{supplier_uuid}/items

List supplier items

Get a paginated list of items for a supplier. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. A supplier outside the narrated account returns a 404. Deleted items are excluded.

Required attributes

Name
supplier_uuid
Type
string
Description
The UUID of the supplier

Optional attributes

Name
q
Type
string
Description
Search language filter. Supported fields: `sku` (string), `description` (string). Substring matches require at least 3 characters. Clauses can be combined with `AND` / `OR`. Example: `sku~"widget"`
Name
product_uuid
Type
string
Description
Filter items linked to this product
Name
sorts
Type
array<Sort>
Description
Sort the results. Example: `sorts[0][field]=sku&sorts[0][order]=1`
Name
page
Type
integer
Description
The page number to retrieve (1-indexed) 1
Name
per_page
Type
integer
Description
The number of items per page 25

Request

GET/suppliers/{supplier_uuid}/items

curl -G https://YOUR_DOMAIN/api/suppliers/{supplier-uuid}/items \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Loading response...

POST/suppliers/{supplier_uuid}/items

Create a supplier item

Create a catalogue item for a supplier. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. A supplier outside the narrated account returns a 404. `sku` must be unique among the supplier's items that have not been deleted. `product_uuid`, when present, must reference a non-deleted product owned by the same merchant.

Required attributes

Name
supplier_uuid
Type
string
Description
The UUID of the supplier
Name
sku
Type
string
Description
The supplier's own identifier for this item. Unique among the supplier's items that have not been deleted. ACME-WIDGET-001
Name
costs.*.minimum_order_quantity
Type
integer
Description
100
Name
costs.*.cost
Type
object
Description
Name
costs.*.cost.amount
Type
number
Description
12.37
Name
costs.*.cost.currency
Type
string
Description
USD
Name
identifiers.*.type
Type
string
Description
UPC
Name
identifiers.*.value
Type
string
Description
123456789012

Optional attributes

Name
description
Type
string
Description
A description of the item Blue widget, bulk pack of 10
Name
product_uuid
Type
string
Description
The UUID of the product this supplier item is linked to. Must be a non-deleted product owned by the same merchant. 1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4
Name
costs
Type
array<Cost>
Description
Quantity-break cost tiers for this item. Minimum order quantities must be unique within the payload.
Name
identifiers
Type
array<Identifier>
Description
Typed barcode identifiers for this item. The combination of type and value must be unique within the payload.

Request

POST/suppliers/{supplier_uuid}/items

curl -X POST https://YOUR_DOMAIN/api/suppliers/{supplier-uuid}/items \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "ACME-WIDGET-001",
    "description": "Blue widget, bulk pack of 10",
    "product_uuid": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4",
    "costs": [
        {
            "minimum_order_quantity": 100,
            "cost": {
                "amount": 12.37,
                "currency": "USD"
            }
        }
    ],
    "identifiers": [
        {
            "type": "UPC",
            "value": "123456789012"
        }
    ]
}'

Loading response...

GET/suppliers/{supplier_uuid}/items/{supplier_item_uuid}

Get a supplier item

Get a single supplier item by its UUID, including its cost tiers and identifiers. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. A supplier or item outside the narrated account returns a 404. Deleted items are returned with `is_deleted` set to true.

Required attributes

Name
supplier_uuid
Type
string
Description
The UUID of the supplier
Name
supplier_item_uuid
Type
string
Description
The UUID of the supplier item

Request

GET/suppliers/{supplier_uuid}/items/{supplier_item_uuid}

curl -G https://YOUR_DOMAIN/api/suppliers/{supplier-uuid}/items/{supplier-item-uuid} \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Loading response...

PUT/suppliers/{supplier_uuid}/items/{supplier_item_uuid}

Update a supplier item

Update a supplier item's own attributes (`sku`, `description`, `product_uuid`). Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. A supplier or item outside the narrated account returns a 404. Only the properties present in the request body are changed; omitted properties are left as they are. Cost tiers and identifiers are managed separately: costs are append-only via `POST .../costs` and `DELETE .../costs/{supplier_item_cost_uuid}`, and identifiers are set-replaced via `PUT .../identifiers`.

Required attributes

Name
supplier_uuid
Type
string
Description
The UUID of the supplier
Name
supplier_item_uuid
Type
string
Description
The UUID of the supplier item

Optional attributes

Name
sku
Type
string
Description
The supplier's own identifier for this item. Unique among the supplier's items that have not been deleted. ACME-WIDGET-001
Name
description
Type
string
Description
A description of the item Blue widget, bulk pack of 10
Name
product_uuid
Type
string
Description
The UUID of the product this supplier item is linked to. Must be a non-deleted product owned by the same merchant. 1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4

Request

PUT/suppliers/{supplier_uuid}/items/{supplier_item_uuid}

curl -X PUT https://YOUR_DOMAIN/api/suppliers/{supplier-uuid}/items/{supplier-item-uuid} \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "ACME-WIDGET-001",
    "description": "Blue widget, bulk pack of 10",
    "product_uuid": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4"
}'

Loading response...

DELETE/suppliers/{supplier_uuid}/items/{supplier_item_uuid}

Delete a supplier item

Delete a supplier item. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. A supplier or item outside the narrated account returns a 404. The item is soft deleted: it disappears from the list endpoint and is still readable on the detail endpoint with `is_deleted` set to true, and frees its `sku` for reuse. Deleting an already deleted item returns a 404.

Required attributes

Name
supplier_uuid
Type
string
Description
The UUID of the supplier
Name
supplier_item_uuid
Type
string
Description
The UUID of the supplier item

Request

DELETE/suppliers/{supplier_uuid}/items/{supplier_item_uuid}

curl -X DELETE https://YOUR_DOMAIN/api/suppliers/{supplier-uuid}/items/{supplier-item-uuid} \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

POST/suppliers/{supplier_uuid}/items/{supplier_item_uuid}/costs

Create a supplier item cost row

Appends a new price for a minimum order quantity. Costs are append-only: this always inserts a new row rather than editing an existing one, so this can be used both to add a brand-new tier and to record a price change for a tier that already exists — the tier's `current_cost` is simply whichever non-future row for that minimum order quantity has the latest `effective_at`. Set `effective_at` to a future date to schedule a price change in advance; it surfaces as `upcoming_cost` until that date arrives. Omit it (or send null) to take effect immediately. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. A supplier or item outside the narrated account returns a 404.

Required attributes

Name
supplier_uuid
Type
string
Description
The UUID of the supplier
Name
supplier_item_uuid
Type
string
Description
The UUID of the supplier item
Name
minimum_order_quantity
Type
integer
Description
100
Name
cost
Type
object
Description
Name
cost.amount
Type
number
Description
12.37
Name
cost.currency
Type
string
Description
USD

Optional attributes

Name
effective_at
Type
string
Description
The ISO 8601 datetime from which this price takes effect. Defaults to now when omitted or null; a future value schedules the price and surfaces it as `upcoming_cost` until it arrives. 2026-04-01T09:34:55.000000Z

Request

POST/suppliers/{supplier_uuid}/items/{supplier_item_uuid}/costs

curl -X POST https://YOUR_DOMAIN/api/suppliers/{supplier-uuid}/items/{supplier-item-uuid}/costs \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "minimum_order_quantity": 100,
    "cost": {
        "amount": 12.37,
        "currency": "USD"
    },
    "effective_at": "2026-04-01T09:34:55.000000Z"
}'

Loading response...

DELETE/suppliers/{supplier_uuid}/items/{supplier_item_uuid}/costs/{supplier_item_cost_uuid}

Delete a supplier item cost row

Soft deletes a single cost row by its own UUID, preserving its price history. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. A supplier, item, or cost row outside the narrated account returns a 404. Deleting the row currently in effect for a minimum order quantity does not retire the tier: the next most recent non-future row for that quantity, if any, becomes current again.

Required attributes

Name
supplier_uuid
Type
string
Description
The UUID of the supplier
Name
supplier_item_uuid
Type
string
Description
The UUID of the supplier item
Name
supplier_item_cost_uuid
Type
string
Description
The UUID of the cost row

Request

DELETE/suppliers/{supplier_uuid}/items/{supplier_item_uuid}/costs/{supplier_item_cost_uuid}

curl -X DELETE https://YOUR_DOMAIN/api/suppliers/{supplier-uuid}/items/{supplier-item-uuid}/costs/{supplier-item-cost-uuid} \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

PUT/suppliers/{supplier_uuid}/items/{supplier_item_uuid}/identifiers

Replace a supplier item's identifiers

Replaces every existing identifier for this item with exactly the identifiers present in the payload. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. A supplier or item outside the narrated account returns a 404. The combination of type and value must be unique within the payload. Send an empty array to remove every existing identifier.

Required attributes

Name
supplier_uuid
Type
string
Description
The UUID of the supplier
Name
supplier_item_uuid
Type
string
Description
The UUID of the supplier item
Name
identifiers
Type
array<Identifier>
Description
The complete set of identifiers for this item. Must always be present, even as an empty array, to clear every identifier.
Name
identifiers.*.type
Type
string
Description
UPC
Name
identifiers.*.value
Type
string
Description
123456789012

Request

PUT/suppliers/{supplier_uuid}/items/{supplier_item_uuid}/identifiers

curl -X PUT https://YOUR_DOMAIN/api/suppliers/{supplier-uuid}/items/{supplier-item-uuid}/identifiers \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "identifiers": [
        {
            "type": "UPC",
            "value": "123456789012"
        }
    ]
}'

Loading response...