Aller au contenu principal
API docs by Redocly

Rokt Catalog API (1.0.1)

Rokt Catalog Support: roktcatalogsupport@rokt.com

Introduction

The Rokt Catalog API is the REST interface to Rokt Catalog, the dropship and marketplace platform that lets Partners (retailers) sell products supplied by Brands without holding inventory. Brands use it to publish products and variants, receive orders, and record fulfillments; Partners use it to browse the products they are approved to sell, create and manage orders, quote shipping and tax at checkout, and handle refunds and returns. All requests go to the production base URL https://api.shopcanal.com/platform. There is no separate sandbox: test against the designated test Brand accounts from a separate test Partner login, as described in the Environments guide.

Authentication

Every request carries two headers: X-CANAL-APP-ID (your Application ID) and X-CANAL-APP-TOKEN (your API Access Token). Both are generated when your account is created; find them in the Developer tab under Settings > API Credentials after you log in to the Rokt Catalog app. Treat the token as a secret: keep it server-side and never ship it in a browser or mobile app. See the Authentication guide.

Roles, pagination, and support

The endpoint descriptions below come from the API code, which uses the older names for the two roles: [Storefront Only] means the endpoint is for Partner integrations and [Supplier Only] means it is for Brand integrations. The Brand integrations and Partner integrations groups in the sidebar list the endpoints each role uses; a resource that both roles call appears in both groups. List endpoints use cursor-based pagination (cursor query parameter, next and previous URLs in the response) and accept an ordering parameter where noted. Errors return a JSON body: authentication and permission errors carry a detail field, and most other errors carry a message and, where relevant, a detail field with more information. For the step-by-step integration flow, start with the Rokt Catalog integration guides and the Catalog API overview; for anything else, contact roktcatalogsupport@rokt.com.

Products

The Products endpoints give access to every product you have permission to sell on your Partner storefront, and let Brands create, update, reorder, and delete the products they supply. To get permission to sell specific products, send proposals to Brands in the Rokt Catalog app; once a Brand approves a proposal, its products become available through these endpoints.

List products

[Storefront Only] Retrieve a paginated list of products accessible to your Storefront through your established Rokt Catalog connections.

This endpoint returns products from Suppliers with whom you have an active and approved partnership. It includes products you might have already added/linked to your Storefront platform, as well as other products listed by those Suppliers that are available to you based on your connection terms.

You can filter the results to view products exclusively from one Supplier by providing their Catalog supplier_id (UUID) as a query parameter.

Results are returned using cursor-based pagination (PlatformPagination). Available ordering fields include created_at, updated_at, and title. The default order is -created_at.

Authorizations:
(platformAppIdplatformAppToken)
query Parameters
ordering
string

Which field to use when ordering the results.

cursor
string

The pagination cursor value.

supplier_id
string <uuid>

Filter products by the Catalog ID of a specific connected Supplier.

qa_review_complete
boolean

Filter products by whether they have been reviewed and approved.

Responses

Response samples

Content type
application/json
{
  • "next": "http://api.example.org/accounts/?cursor=cD00ODY%3D",
  • "previous": "http://api.example.org/accounts/?cursor=cj0xJnA9NDg3",
  • "results": [
    ]
}

Create a product

[Supplier Only] Create a new product listing within your Rokt Catalog Supplier account. This makes the product manageable through Catalog and potentially available to your connected Storefront partners.

The request body must conform to the PushProductSerializer structure. Key fields include:

title (string, required), body_html (string, product description), product_type (string), vendor (string), tags (string, comma-separated), and a list of variants (required, at least one).

Each object in the variants list requires price (decimal string), sku (string), inventory_quantity (integer), and option values (option1, option2, option3). compare_at_price (decimal string) is optional for sale pricing.

You can also include a list of images, each with a src (URL) and optional position.

Successfully creating a product (HTTP 201 Created) makes it visible in your Catalog dashboard. Its availability to Storefronts depends on its listing status (supplier_has_listed_on_canal flag on variants) and the terms established with each partner.

The response body contains the full details of the newly created product and its variants, including their assigned Catalog IDs (UUIDs), using the ProductSerializer.

Authorizations:
(platformAppIdplatformAppToken)
Request Body schema:
required
title
required
string
body_html
string
required
Array of objects (PushProductVariant)
permalink
string
handle
string
image_src
string
Array of objects (Image)
product_type
string
tags
string
vendor
string
shopify_taxonomy
string or null
is_listed
boolean
Default: true
status
string
Default: "active"
Enum: "active" "draft" "archived"
  • active - active
  • draft - draft
  • archived - archived

Responses

Request samples

Content type
{
  • "title": "string",
  • "body_html": "string",
  • "variants": [
    ],
  • "permalink": "string",
  • "handle": "string",
  • "image_src": "string",
  • "images": [
    ],
  • "product_type": "string",
  • "tags": "string",
  • "vendor": "string",
  • "shopify_taxonomy": "string",
  • "is_listed": true,
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "shop": {
    },
  • "variants": [
    ],
  • "body_html": "string",
  • "handle": "string",
  • "image_src": "string",
  • "images": [
    ],
  • "options": null,
  • "product_type": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "published_at": "2019-08-24T14:15:22Z",
  • "status": "active",
  • "title": "string",
  • "vendor": "string",
  • "tags": "string",
  • "permalink": "http://example.com",
  • "number_of_reviews": -2147483648,
  • "star_rating": 0.1
}

Retrieve a product

[Storefront Only] Retrieve comprehensive details for a single product, identified by its Rokt Catalog ID (UUID) in the URL path.

Access is restricted: this endpoint only returns data for products sourced from Suppliers with whom your Storefront has an active and approved partnership connection.

The response (ExternalProductSerializer) includes all product-level information (title, description, vendor, etc.), a list of associated images, and a list of variants.

Crucially, the variant information includes pricing (price, compare_at_price) and inventory_quantity that are specific to your connection with the Supplier, reflecting any agreed-upon terms or markups managed by Catalog.

If the provided product ID is invalid, or if the product belongs to a Supplier you are not actively connected with, a 404 Not Found error is returned.

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "shop": {
    },
  • "variants": [
    ],
  • "body_html": "string",
  • "handle": "string",
  • "image_src": "string",
  • "images": [
    ],
  • "options": [
    ],
  • "product_type": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "published_at": "2019-08-24T14:15:22Z",
  • "status": "active",
  • "title": "string",
  • "vendor": "string",
  • "tags": "string",
  • "permalink": "http://example.com",
  • "number_of_reviews": -2147483648,
  • "star_rating": 0.1,
  • "product_type_category": "string",
  • "customer_charge_amount": {
    }
}

Update a product

[Supplier Only] Update attributes of an existing product listing, identified by its Rokt Catalog ID (UUID) in the URL path.

This endpoint is used for modifying product-level details. Provide the fields you wish to change in the request body (e.g., title, body_html, product_type, vendor, tags).

Important: To modify variant-specific details like price, SKU, inventory, or options, you must use the dedicated /variants/{variant_id}/ endpoint. Updates to variants are not supported here.

Changes made to product-level fields via this endpoint (like updating the description) are automatically synchronized to any connected Storefronts that are currently selling this product. This synchronization process runs asynchronously in the background.

A successful update returns 200 OK with the complete, updated product details (including all variants) using the ProductSerializer.

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string
Request Body schema:
required
body_html
string or null <= 60000 characters
handle
string or null <= 258 characters
image_src
string or null <= 1043 characters
Array of objects (Image)
options
any

Product options (for example size or color) and their values, or null when the product has none.

product_type
string or null <= 1044 characters
published_at
string or null <date-time>
status
string (Status2eaEnum)
Enum: "active" "draft" "archived" "unlisted"
  • active - active
  • draft - draft
  • archived - archived
  • unlisted - unlisted
title
required
string <= 1029 characters
vendor
string or null <= 227 characters
tags
string or null <= 63750 characters
permalink
string or null <uri> <= 2000 characters
number_of_reviews
integer or null [ -2147483648 .. 2147483647 ]
star_rating
number or null <double>

Responses

Request samples

Content type
{
  • "body_html": "string",
  • "handle": "string",
  • "image_src": "string",
  • "images": [
    ],
  • "options": null,
  • "product_type": "string",
  • "published_at": "2019-08-24T14:15:22Z",
  • "status": "active",
  • "title": "string",
  • "vendor": "string",
  • "tags": "string",
  • "permalink": "http://example.com",
  • "number_of_reviews": -2147483648,
  • "star_rating": 0.1
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "shop": {
    },
  • "variants": [
    ],
  • "body_html": "string",
  • "handle": "string",
  • "image_src": "string",
  • "images": [
    ],
  • "options": null,
  • "product_type": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "published_at": "2019-08-24T14:15:22Z",
  • "status": "active",
  • "title": "string",
  • "vendor": "string",
  • "tags": "string",
  • "permalink": "http://example.com",
  • "number_of_reviews": -2147483648,
  • "star_rating": 0.1
}

Partially update a product

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string
Request Body schema:
body_html
string or null <= 60000 characters
handle
string or null <= 258 characters
image_src
string or null <= 1043 characters
Array of objects (Image)
options
any

Product options (for example size or color) and their values, or null when the product has none.

product_type
string or null <= 1044 characters
published_at
string or null <date-time>
status
string (Status2eaEnum)
Enum: "active" "draft" "archived" "unlisted"
  • active - active
  • draft - draft
  • archived - archived
  • unlisted - unlisted
title
string <= 1029 characters
vendor
string or null <= 227 characters
tags
string or null <= 63750 characters
permalink
string or null <uri> <= 2000 characters
number_of_reviews
integer or null [ -2147483648 .. 2147483647 ]
star_rating
number or null <double>

Responses

Request samples

Content type
{
  • "body_html": "string",
  • "handle": "string",
  • "image_src": "string",
  • "images": [
    ],
  • "options": null,
  • "product_type": "string",
  • "published_at": "2019-08-24T14:15:22Z",
  • "status": "active",
  • "title": "string",
  • "vendor": "string",
  • "tags": "string",
  • "permalink": "http://example.com",
  • "number_of_reviews": -2147483648,
  • "star_rating": 0.1
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "shop": {
    },
  • "variants": [
    ],
  • "body_html": "string",
  • "handle": "string",
  • "image_src": "string",
  • "images": [
    ],
  • "options": null,
  • "product_type": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "published_at": "2019-08-24T14:15:22Z",
  • "status": "active",
  • "title": "string",
  • "vendor": "string",
  • "tags": "string",
  • "permalink": "http://example.com",
  • "number_of_reviews": -2147483648,
  • "star_rating": 0.1
}

Delete a product

[Supplier Only] Permanently remove a product listing, identified by its Rokt Catalog ID (UUID) in the URL path, from the Catalog platform.

Warning: This action is irreversible. Ensure you intend to delete this product permanently.

You can only delete products that are directly owned by your Supplier account. Attempting to delete a product belonging to another shop will result in a 403 Forbidden error.

Effect on Storefronts: When a product is deleted, Catalog automatically pauses the corresponding product listings on any connected Storefronts that were actively selling it. An asynchronous task is initiated to inform these Storefronts about the product's removal.

A successful deletion returns an HTTP 204 No Content status with an empty response body.

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "detail": null
}

Reorder product variants

[Supplier Only] Update the display sequence of variants for a specific product. The product is identified by its Rokt Catalog ID (UUID) in the URL path.

The request body must contain a field named variant_order, which is a list of Catalog variant IDs (UUIDs) sorted in the desired display order (0-indexed).

Requirement: The variant_order list must include the IDs of all currently existing variants for the specified product. Omitting or adding incorrect IDs will result in a validation error (400 Bad Request).

This reordering affects how variants are presented within the Catalog platform (e.g., in the Supplier dashboard). It may also influence the display order on connected Storefronts if their integration respects the position attribute of the variants.

A successful update returns 200 OK with the full product details (ProductSerializer), reflecting the new position values for each variant.

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string
Request Body schema:
required
variant_order
required
Array of strings <uuid> [ items <uuid > ]

Responses

Request samples

Content type
{
  • "variant_order": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "shop": {
    },
  • "variants": [
    ],
  • "body_html": "string",
  • "handle": "string",
  • "image_src": "string",
  • "images": [
    ],
  • "options": null,
  • "product_type": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "published_at": "2019-08-24T14:15:22Z",
  • "status": "active",
  • "title": "string",
  • "vendor": "string",
  • "tags": "string",
  • "permalink": "http://example.com",
  • "number_of_reviews": -2147483648,
  • "star_rating": 0.1
}

Resync a product

Resynchronize a retailer (Shopkeep) product with its origin supplier product.

If fields_to_resync is provided, only those fields will be updated; otherwise all fields are resynced.

On success, returns the updated product data. If the resync is queued to run asynchronously (e.g. due to rate limits), returns a message indicating the resync has started.

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string
Request Body schema:
fields_to_resync
Array of strings (FieldsToResyncEnum)
Items Enum: "images" "product_title" "description" "tags" "variants" "vendor" "permalink"

Responses

Request samples

Content type
{
  • "fields_to_resync": [
    ]
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "status": "string",
  • "shopify_product": {
    }
}

List upsell products

[Storefront Only] Retrieve a paginated list of active products that are eligible for upselling.

This endpoint returns products from Suppliers with whom you have an active and approved partnership.

Products must meet the following criteria:

  1. Have status='active',

  2. Have at least one variant that is connected to a supplier variant, listed on Catalog, and not paused for selling,

  3. Have passed ads eligibility checks,

  4. Have at least one available variant in a non-deleted product set,

Authorizations:
(platformAppIdplatformAppToken)
query Parameters
ordering
string

Which field to use when ordering the results.

cursor
string

The pagination cursor value.

supplier_id
string <uuid>

Filter products by the Catalog ID of a specific connected Supplier.

Responses

Response samples

Content type
application/json
{
  • "next": "http://api.example.org/accounts/?cursor=cD00ODY%3D",
  • "previous": "http://api.example.org/accounts/?cursor=cj0xJnA9NDg3",
  • "results": [
    ]
}

Variants

Variants are the purchasable options of a product (size, color, SKU, price, inventory). Brands add, update, list, and remove variants for their own products; Partners receive variant data on the product and through the product/create and product/update webhooks.

List variants

[Supplier Only] Retrieve a paginated list of all product variants associated with all products owned by your Supplier account.

This endpoint provides a flat list of variant details, independent of their parent products. Use this if you need to query or manage variants across your entire catalog.

Results are returned using cursor-based pagination (PlatformPagination). Available ordering fields include created_at, updated_at, price, and compare_at_price. The default order is -created_at.

Authorizations:
(platformAppIdplatformAppToken)
query Parameters
ordering
string

Which field to use when ordering the results.

cursor
string

The pagination cursor value.

Responses

Response samples

Content type
application/json
{
  • "next": "http://api.example.org/accounts/?cursor=cD00ODY%3D",
  • "previous": "http://api.example.org/accounts/?cursor=cj0xJnA9NDg3",
  • "results": [
    ]
}

Create a variant

[Supplier Only] Add a new variant to an existing product within your Rokt Catalog Supplier account.

The request body must conform to the CreateVariantSerializer structure, requiring the product_id (UUID) of the parent product and the full details of the new variant (including price, sku, inventory_quantity, option1, etc.).

Upon successful creation, the new variant is added to the specified product. By default, it will be assigned the next available position (typically appearing last in the variant list, unless explicitly reordered later using the /products/{product_id}/reorder_variants/ endpoint).

Synchronization: This addition is automatically propagated asynchronously to connected Storefronts that are selling the parent product.

A successful creation returns 201 Created with the full details of the parent product (ProductSerializer), now including the newly added variant and its assigned Catalog ID (UUID).

Authorizations:
(platformAppIdplatformAppToken)
Request Body schema:
required
title
string
price
required
string <decimal> ^-?\d{0,10}(?:\.\d{0,2})?$

The price of the variant to be sold at.

compare_at_price
string or null <decimal> ^-?\d{0,10}(?:\.\d{0,2})?$

The original price of the product from before the sale price. Should be greater than "price". If you elect to not allow sale price passthrough, Connected Storefronts will sell items at this price.

inventory_policy
required
string (InventoryPolicyEnum)
Enum: "continue" "deny"
  • continue - continue
  • deny - deny
inventory_quantity
required
integer
option1
required
string
option2
string
option3
string
sku
string
position
integer
image_src
string
weight
number <double>
weight_unit
string
product_id
required
string <uuid>

Responses

Request samples

Content type
{
  • "title": "string",
  • "price": "string",
  • "compare_at_price": "string",
  • "inventory_policy": "continue",
  • "inventory_quantity": 0,
  • "option1": "string",
  • "option2": "string",
  • "option3": "string",
  • "sku": "string",
  • "position": 0,
  • "image_src": "string",
  • "weight": 0.1,
  • "weight_unit": "string",
  • "product_id": "0d012afa-f885-4e65-aeca-37e27701e2d1"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "shop": {
    },
  • "variants": [
    ],
  • "body_html": "string",
  • "handle": "string",
  • "image_src": "string",
  • "images": [
    ],
  • "options": null,
  • "product_type": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "published_at": "2019-08-24T14:15:22Z",
  • "status": "active",
  • "title": "string",
  • "vendor": "string",
  • "tags": "string",
  • "permalink": "http://example.com",
  • "number_of_reviews": -2147483648,
  • "star_rating": 0.1
}

Retrieve a variant

[Supplier Only] Retrieve the full details for a specific product variant, identified by its Rokt Catalog ID (UUID) provided in the URL path.

This endpoint returns data only for variants that belong to products owned by your Supplier account.

The response (VariantSerializer) includes all attributes of the variant, such as price, SKU, inventory, options, weight, timestamps, and its parent product ID.

If the provided variant ID is invalid or belongs to a product owned by another shop, a 404 Not Found error is returned.

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "shop": {
    },
  • "inventory_policy": "string",
  • "inventory_quantity": -2147483648,
  • "inventory_item_cost": 0.1,
  • "option1": "string",
  • "option2": "string",
  • "option3": "string",
  • "position": 0,
  • "price": "string",
  • "compare_at_price": "string",
  • "origin_supplier_currency": "string",
  • "title": "string",
  • "sku": "string",
  • "upc": "string",
  • "grams": 0.1,
  • "weight": 0.1,
  • "weight_unit": "str",
  • "pause_selling": true,
  • "origin_supplier_id": "string",
  • "origin_supplier_name": "string",
  • "available_for_ordering": true,
  • "supplier_sku": "string",
  • "is_exclusive_offer": true,
  • "sup_price": "string",
  • "sup_compare_at_price": "string"
}

Update a variant

[Supplier Only] Update attributes of a specific product variant, identified by its Rokt Catalog ID (UUID) in the URL path.

Provide the fields you wish to change in the request body using the VariantSerializer structure (partial updates are allowed). Common updatable fields include price, compare_at_price, sku, inventory_quantity, option1, option2, option3, weight, weight_unit, etc.

Synchronization: Changes to critical attributes like price and inventory are automatically propagated to connected Storefronts that are selling this variant. This synchronization occurs asynchronously.

Pricing Update: When updating price or compare_at_price, the system also updates the associated variant listing's default price, considering the shop's feature flags for sale price syncing.

A successful update returns 200 OK with the full details of the parent product (ProductSerializer), reflecting the changes made to the specific variant.

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string
Request Body schema:
required
inventory_policy
string or null <= 123 characters
inventory_quantity
integer or null [ -2147483648 .. 2147483647 ]
inventory_item_cost
number <double>
option1
string or null <= 255 characters
option2
string or null <= 256 characters
option3
string or null <= 257 characters
price
required
string <decimal> ^-?\d{0,10}(?:\.\d{0,2})?$

The price of the variant to be sold at.

compare_at_price
string or null <= 128 characters
title
required
string
upc
string or null <= 253 characters
grams
number or null <double>
weight
number or null <double>
weight_unit
string or null <= 3 characters
pause_selling
boolean

Responses

Request samples

Content type
{
  • "inventory_policy": "string",
  • "inventory_quantity": -2147483648,
  • "inventory_item_cost": 0.1,
  • "option1": "string",
  • "option2": "string",
  • "option3": "string",
  • "price": "string",
  • "compare_at_price": "string",
  • "title": "string",
  • "upc": "string",
  • "grams": 0.1,
  • "weight": 0.1,
  • "weight_unit": "str",
  • "pause_selling": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "shop": {
    },
  • "variants": [
    ],
  • "body_html": "string",
  • "handle": "string",
  • "image_src": "string",
  • "images": [
    ],
  • "options": null,
  • "product_type": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "published_at": "2019-08-24T14:15:22Z",
  • "status": "active",
  • "title": "string",
  • "vendor": "string",
  • "tags": "string",
  • "permalink": "http://example.com",
  • "number_of_reviews": -2147483648,
  • "star_rating": 0.1
}

Partially update a variant

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string
Request Body schema:
inventory_policy
string or null <= 123 characters
inventory_quantity
integer or null [ -2147483648 .. 2147483647 ]
inventory_item_cost
number <double>
option1
string or null <= 255 characters
option2
string or null <= 256 characters
option3
string or null <= 257 characters
price
string <decimal> ^-?\d{0,10}(?:\.\d{0,2})?$

The price of the variant to be sold at.

compare_at_price
string or null <= 128 characters
title
string
upc
string or null <= 253 characters
grams
number or null <double>
weight
number or null <double>
weight_unit
string or null <= 3 characters
pause_selling
boolean

Responses

Request samples

Content type
{
  • "inventory_policy": "string",
  • "inventory_quantity": -2147483648,
  • "inventory_item_cost": 0.1,
  • "option1": "string",
  • "option2": "string",
  • "option3": "string",
  • "price": "string",
  • "compare_at_price": "string",
  • "title": "string",
  • "upc": "string",
  • "grams": 0.1,
  • "weight": 0.1,
  • "weight_unit": "str",
  • "pause_selling": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "shop": {
    },
  • "inventory_policy": "string",
  • "inventory_quantity": -2147483648,
  • "inventory_item_cost": 0.1,
  • "option1": "string",
  • "option2": "string",
  • "option3": "string",
  • "position": 0,
  • "price": "string",
  • "compare_at_price": "string",
  • "origin_supplier_currency": "string",
  • "title": "string",
  • "sku": "string",
  • "upc": "string",
  • "grams": 0.1,
  • "weight": 0.1,
  • "weight_unit": "str",
  • "pause_selling": true,
  • "origin_supplier_id": "string",
  • "origin_supplier_name": "string",
  • "available_for_ordering": true,
  • "supplier_sku": "string",
  • "is_exclusive_offer": true,
  • "sup_price": "string",
  • "sup_compare_at_price": "string"
}

Delete a variant

[Supplier Only] Permanently remove a specific product variant, identified by its Rokt Catalog ID (UUID) in the URL path, from its parent product.

Warning: This action is irreversible.

Constraint: You cannot delete the last remaining variant of a product using this endpoint. If you need to remove the product entirely, use the /products/{product_id}/ delete endpoint instead.

Synchronization: Deleting a variant automatically triggers an asynchronous update (emitting a PRODUCT_UPDATE webhook) to propagate this change to connected Storefronts, effectively removing the variant from their listings.

Position Update: The position attribute of the remaining variants on the parent product will be automatically recalculated and updated to maintain a contiguous sequence.

A successful deletion returns 200 OK with the full details of the parent product (ProductSerializer), reflecting the variant's removal and the updated positions of the remaining variants.

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "shop": {
    },
  • "variants": [
    ],
  • "body_html": "string",
  • "handle": "string",
  • "image_src": "string",
  • "images": [
    ],
  • "options": null,
  • "product_type": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "published_at": "2019-08-24T14:15:22Z",
  • "status": "active",
  • "title": "string",
  • "vendor": "string",
  • "tags": "string",
  • "permalink": "http://example.com",
  • "number_of_reviews": -2147483648,
  • "star_rating": 0.1
}

Fulfillments

The Fulfillments endpoints give access to the latest shipping information for Brand orders placed through your Partner storefront. Brands create and update fulfillment (shipment) records; Partners list and retrieve them to show tracking to their customers. Note: only Rokt Catalog Brand products should appear in these fulfillments.

List fulfillments

Retrieve a paginated list of fulfillment records associated with the authenticated store, reflecting its role in the order process.

  • If called by a Storefront: Returns fulfillments created by connected Suppliers for orders originating from the Storefront. This allows the Storefront to track shipments for items their customers ordered.

  • If called by a Supplier: Returns fulfillments created by this Supplier for orders they received from connected Storefronts.

Results (FulfillmentSerializer) include tracking details when present, status, associated line items, and timestamps.

Pagination is cursor-based (PlatformPagination). Ordering is available on created_at and updated_at, defaulting to -created_at.

Authorizations:
(platformAppIdplatformAppToken)
query Parameters
ordering
string

Which field to use when ordering the results.

cursor
string

The pagination cursor value.

Responses

Response samples

Content type
application/json
{
  • "next": "http://api.example.org/accounts/?cursor=cD00ODY%3D",
  • "previous": "http://api.example.org/accounts/?cursor=cj0xJnA9NDg3",
  • "results": [
    ]
}

Create a fulfillment

[Supplier Only] Create a fulfillment record for items in an order received from a connected Storefront.

The request body (CreateFulfillmentSerializer) must specify:

order_id (UUID of the Supplier's Rokt Catalog order record) and a list of line_items.

Each object in line_items needs the Catalog id (UUID) of the Supplier's line item record and the quantity being fulfilled.

For physical shipments, include tracking information (tracking_company, tracking_numbers, tracking_urls) when available. For digital/email fulfillment with no shipment, omit the tracking fields.

Process:

  1. Validation: Checks if the order exists, belongs to the Supplier, is a connected order, and if the provided line items are valid. Returns 400 Bad Request or 404 Not Found on failure.

  2. Create Supplier Fulfillment: Creates the fulfillment record associated with the Supplier's order in Catalog. Considers feature flags to determine if the notify_customer flag should be set during downstream sync.

  3. Sync to Storefront: Triggers a synchronization process. This attempts to create or update the corresponding fulfillment record on the original Storefront's order (e.g., via Shopify API), including tracking information when present.

  4. Webhook: Emits a FULFILLMENT_UPDATE webhook event containing details of the Supplier's newly created fulfillment record.

A successful creation returns 201 Created with the details of the Supplier's fulfillment record (FulfillmentSerializer).

Authorizations:
(platformAppIdplatformAppToken)
Request Body schema:
required
name
required
string
service
required
string
shipment_status
required
string (ShipmentStatusEnum)
Enum: "label_printed" "label_purchased" "attempted_delivery" "ready_for_pickup" "confirmed" "in_transit" "out_for_delivery" "delivered" "failure"
  • label_printed - label_printed
  • label_purchased - label_purchased
  • attempted_delivery - attempted_delivery
  • ready_for_pickup - ready_for_pickup
  • confirmed - confirmed
  • in_transit - in_transit
  • out_for_delivery - out_for_delivery
  • delivered - delivered
  • failure - failure
status
required
string (Status406Enum)
Enum: "pending" "open" "success" "cancelled" "error" "failure"
  • pending - pending
  • open - open
  • success - success
  • cancelled - cancelled
  • error - error
  • failure - failure
tracking_company
string or null
tracking_numbers
Array of strings or null
tracking_urls
Array of strings or null
order_id
required
string <uuid>
required
Array of objects (LineItem)

Responses

Request samples

Content type
{
  • "name": "string",
  • "service": "string",
  • "shipment_status": "label_printed",
  • "status": "pending",
  • "tracking_company": "string",
  • "tracking_numbers": [
    ],
  • "tracking_urls": [
    ],
  • "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
  • "line_items": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
  • "shop": {
    },
  • "line_items": [
    ],
  • "service": "string",
  • "shipment_status": "string",
  • "status": "string",
  • "tracking_company": "string",
  • "tracking_numbers": [
    ],
  • "tracking_urls": [
    ]
}

Retrieve a fulfillment

Retrieve the full details for a specific fulfillment record, identified by its Rokt Catalog ID (UUID) in the URL path.

Access is restricted to fulfillments associated with the authenticated store (request.shop). This means:

  • Storefronts can retrieve details of fulfillments created by their Suppliers for their orders.

  • Suppliers can retrieve details of fulfillments they created.

The response (FulfillmentSerializer) includes the fulfillment status (e.g., 'fulfilled', 'cancelled'), optional tracking_company, optional tracking_numbers, optional tracking_urls, the list of line_items included in this fulfillment (with quantities), and relevant timestamps.

If the fulfillment ID is invalid or not associated with an order linked to your store, a 404 Not Found error is returned.

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
  • "shop": {
    },
  • "line_items": [
    ],
  • "service": "string",
  • "shipment_status": "string",
  • "status": "string",
  • "tracking_company": "string",
  • "tracking_numbers": [
    ],
  • "tracking_urls": [
    ]
}

Update a fulfillment

[Supplier Only] Update an existing fulfillment record created by your Supplier account. Identify the fulfillment by its Rokt Catalog ID (UUID) in the URL path.

The request body (UpdateFulfillmentSerializer) should contain the fields to update, such as tracking_company, tracking_numbers, and/or tracking_urls for physical shipments. Tracking fields are optional and can be omitted for digital/email fulfillments with no shipment. Partial updates are allowed (only include the fields you want to change).

Process:

  1. Update Supplier Fulfillment: Updates the specified fields on the Supplier's fulfillment record in Catalog.

  2. Sync to Storefront: Triggers a synchronization process. This attempts to update the corresponding fulfillment record on the original Storefront's order (e.g., via Shopify API) with the new tracking information when present.

  3. Webhook: Emits a FULFILLMENT_UPDATE webhook event containing details of the Supplier's updated fulfillment record. If the sync to the Storefront also resulted in an update to the Storefront's fulfillment record in Catalog, a separate FULFILLMENT_UPDATE event for the Storefront's fulfillment might also be emitted (depending on the sync logic).

A successful update returns 200 OK with the updated details of the Supplier's fulfillment record (FulfillmentSerializer).

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string
Request Body schema:
required
name
required
string
service
required
string
shipment_status
required
string (ShipmentStatusEnum)
Enum: "label_printed" "label_purchased" "attempted_delivery" "ready_for_pickup" "confirmed" "in_transit" "out_for_delivery" "delivered" "failure"
  • label_printed - label_printed
  • label_purchased - label_purchased
  • attempted_delivery - attempted_delivery
  • ready_for_pickup - ready_for_pickup
  • confirmed - confirmed
  • in_transit - in_transit
  • out_for_delivery - out_for_delivery
  • delivered - delivered
  • failure - failure
status
required
string (Status406Enum)
Enum: "pending" "open" "success" "cancelled" "error" "failure"
  • pending - pending
  • open - open
  • success - success
  • cancelled - cancelled
  • error - error
  • failure - failure
tracking_company
string or null
tracking_numbers
Array of strings or null
tracking_urls
Array of strings or null

Responses

Request samples

Content type
{
  • "name": "string",
  • "service": "string",
  • "shipment_status": "label_printed",
  • "status": "pending",
  • "tracking_company": "string",
  • "tracking_numbers": [
    ],
  • "tracking_urls": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
  • "shop": {
    },
  • "line_items": [
    ],
  • "service": "string",
  • "shipment_status": "string",
  • "status": "string",
  • "tracking_company": "string",
  • "tracking_numbers": [
    ],
  • "tracking_urls": [
    ]
}

Partially update a fulfillment

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string
Request Body schema:
name
string <= 255 characters
order_id
string <uuid>
object (Shop)
Array of objects (LineItemRead)
service
string or null <= 258 characters
shipment_status
string or null <= 32 characters
status
string or null <= 32 characters
tracking_company
string or null <= 257 characters
tracking_numbers
Array of strings or null[ items <= 128 characters ]
tracking_urls
Array of strings or null[ items <= 256 characters ]

Responses

Request samples

Content type
{
  • "name": "string",
  • "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
  • "shop": {
    },
  • "line_items": [
    ],
  • "service": "string",
  • "shipment_status": "string",
  • "status": "string",
  • "tracking_company": "string",
  • "tracking_numbers": [
    ],
  • "tracking_urls": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
  • "shop": {
    },
  • "line_items": [
    ],
  • "service": "string",
  • "shipment_status": "string",
  • "status": "string",
  • "tracking_company": "string",
  • "tracking_numbers": [
    ],
  • "tracking_urls": [
    ]
}

Refunds

The Refunds endpoints allow the Partner to initiate refunds for Brand products that were bought through the Partner storefront. Brands can also create refunds for orders they received, and both roles can list and retrieve refunds.

List refunds

Retrieve a paginated list of refund records associated with the authenticated store, reflecting its role in the order process.

  • If called by a Storefront: Returns refund records linked to orders originating from the Storefront. This includes refunds initiated by the Storefront and refunds initiated by connected Suppliers for those orders.

  • If called by a Supplier: Returns refund records linked to orders received by the Supplier from connected Storefronts. This includes refunds initiated by the Supplier and refunds initiated by the originating Storefronts for those orders.

The response (RefundSerializer, paginated) includes details for each refund, such as the calculated total_refunded_amount, currency, the list of refund_line_items (with quantities and amounts), associated order_id, and timestamps.

Pagination is cursor-based (PlatformPagination). Ordering is available on created_at and updated_at, defaulting to -created_at.

Authorizations:
(platformAppIdplatformAppToken)
query Parameters
ordering
string

Which field to use when ordering the results.

cursor
string

The pagination cursor value.

Responses

Response samples

Content type
application/json
{
  • "next": "http://api.example.org/accounts/?cursor=cD00ODY%3D",
  • "previous": "http://api.example.org/accounts/?cursor=cj0xJnA9NDg3",
  • "results": [
    ]
}

Create a refund

Initiate a refund for specific quantities of line items within a Rokt Catalog order. This endpoint handles refund requests originating from both Storefronts and Suppliers.

Request Body (RefundCreateSerializer):

  • order_id (UUID, required): The Catalog ID of the order to be refunded.

  • line_items (list, required): A list of objects, each specifying:

    • id (UUID, required): The Catalog ID of the line item to refund.

    • quantity (integer, required): The quantity of this line item to refund.

  • should_refund_shipping (boolean, optional, Storefront only): If true, attempts to refund the original shipping cost associated with the Storefront order.

  • extra_amount (decimal string, optional, restricted use): Allows refunding an additional amount beyond line items/shipping (currently restricted to specific approved shops).

Process & Permissions:

  1. Identify Initiator: Determines if the request comes from the Storefront or the Supplier by checking the order's relationships.

  2. Lock Order: Acquires a lock on the order record to prevent concurrent modifications.

  3. Validate Quantities: Checks if the requested quantity for each line item exceeds the currently refundable quantity (original quantity minus previously refunded quantity). If validation fails, returns 400 Bad Request with error_code: ITEMS_ALREADY_REFUNDED and details of affected items.

  4. Storefront-Initiated Refund:

    • Permission Check: Verifies the Storefront has the required scope (write_sk_refunds). Returns 403 Forbidden if missing.

    • Dispatch: Calculates refund amounts, creates the refund record for the Storefront in Catalog, and asynchronously triggers tasks to create corresponding refund records on the connected Supplier(s)' systems (e.g., via Shopify API).

    • Error Handling: If downstream Supplier refund creation fails, returns 400 Bad Request with error_code: SUPPLIER_REFUND_FAILED.

  5. Supplier-Initiated Refund:

    • Permission Check: Implicitly requires the write_refunds scope.

    • Create Supplier Refund: Creates the refund record for the Supplier in Catalog.

    • Dispatch to Storefront: If the Supplier order originated from a Storefront with integration settings, synchronously attempts to create a corresponding refund record on the Storefront's order in Catalog.

    • Error Handling: If downstream Storefront refund creation fails, returns 400 Bad Request with error_code: SK_REFUND_FAILED.

  6. Extra Amount: If extra_amount is provided and valid, creates an associated record (restricted use).

Response: On success, returns 201 Created with the details of the primary refund record created (either the Storefront's or the Supplier's) using RefundSerializer. The serializer might include details about failed downstream refunds in the failed_to_create_refund_line_items field for Storefront-initiated refunds.

Authorizations:
(platformAppIdplatformAppToken)
Request Body schema:
required
order_id
required
string <uuid>
required
Array of objects (LineItem)
should_refund_shipping
boolean
extra_amount
string <decimal> ^-?\d{0,8}(?:\.\d{0,4})?$

Only available to select retailers.

Responses

Request samples

Content type
{
  • "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
  • "line_items": [
    ],
  • "should_refund_shipping": true,
  • "extra_amount": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "order_id": "string",
  • "amount": {
    },
  • "note": "string",
  • "duties": null,
  • "restock": true,
  • "processed_at": "2019-08-24T14:15:22Z",
  • "refund_line_items": [
    ],
  • "shipping_refund_amount": "string",
  • "failed_to_create_refund_line_items": "string"
}

Retrieve a refund

Retrieve the full details for a specific refund record, identified by its Rokt Catalog ID (UUID) in the URL path.

Access is restricted to refunds associated with orders linked to the authenticated store (request.shop).

The response (RefundSerializer) includes the total_refunded_amount, currency, the list of refund_line_items (specifying the exact items, quantities, and subtotal refunded), the associated order_id, note (if any), processed_at timestamp, and other relevant details.

If the refund ID is invalid or the refund is not associated with an order linked to your store, a 404 Not Found error is returned.

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "order_id": "string",
  • "amount": {
    },
  • "note": "string",
  • "duties": null,
  • "restock": true,
  • "processed_at": "2019-08-24T14:15:22Z",
  • "refund_line_items": [
    ],
  • "shipping_refund_amount": "string",
  • "failed_to_create_refund_line_items": "string"
}

Returns

Partners create return requests for items purchased in a Rokt Catalog order and add tracking for the return shipment; Brands review the return requests they receive and close them once the returned items have been processed. Closing a return does not create a refund: use the Refunds endpoints for that.

List returns

Retrieve a paginated list of return requests associated with the authenticated store, reflecting its role.

  • If called by a Storefront: Returns ReturnRequest records initiated by this Storefront for orders placed on their platform.

  • If called by a Supplier: Returns ReturnRequest records received from connected Storefronts for orders the Supplier fulfilled.

Filtering: You can filter the list by status using a query parameter (e.g., ?status=OPEN or ?status=CLOSED).

Response (ReturnSerializer, paginated): Includes details for each return request: id, name, rma, associated order_id, status ('OPEN' or 'CLOSED'), return_line_items (with quantities, reasons), reverse_deliveries (tracking info), and timestamps.

Pagination is cursor-based (PlatformPagination). Ordering is available on created_at and updated_at, defaulting to -created_at.

Authorizations:
(platformAppIdplatformAppToken)
query Parameters
ordering
string

Which field to use when ordering the results.

cursor
string

The pagination cursor value.

status
string
Enum: "closed" "open"

Filter returns by status

Responses

Response samples

Content type
application/json
{
  • "next": "http://api.example.org/accounts/?cursor=cD00ODY%3D",
  • "previous": "http://api.example.org/accounts/?cursor=cj0xJnA9NDg3",
  • "results": [
    ]
}

Create a return

[Storefront Only] Initiate a return process for items purchased in a Rokt Catalog-facilitated order.

Request Body (ReturnCreateSerializer):

  • order_id (UUID, required): The Catalog ID of the original Storefront order containing the items to be returned.

  • name (string, required): A unique identifier for this return request (e.g., your system's RMA number).

  • rma (string, optional): An alternative return merchandise authorization identifier.

  • return_line_items (list, required): A list of objects, each specifying:

    • line_item_id (UUID, required): The Catalog ID of the Storefront's line item record to be returned.

    • quantity (integer, required): The quantity of this line item being returned.

    • return_reason (string, optional): A code or description for the return reason.

    • customer_note (string, optional): Any notes provided by the customer.

  • reverse_deliveries (list, optional): Allows providing initial return shipping tracking information (see ReverseDeliveryCreateSerializer) within the same request.

Process:

  1. Validation: Checks if the order and line items exist, belong to the Storefront, and if the requested return quantities are valid (e.g., not exceeding fulfilled quantity). Acquires a lock on the order.

  2. Create Storefront Return Request: Creates the primary return request record associated with the Storefront's order in Rokt Catalog.

  3. Create Initial Tracking (Optional): If reverse_deliveries are provided, creates associated return tracking records.

  4. Dispatch to Suppliers (Async): Triggers an asynchronous task to create corresponding return request records for each relevant Supplier involved in the returned line items. These Supplier return requests are linked back to the Storefront's request.

Error Handling: Returns 400 Bad Request for validation errors (e.g., invalid quantity, bad IDs). Returns 500 Internal Server Error for unexpected issues.

Response: On success, returns 201 Created with the details of the newly created Storefront return request (ReturnSerializer).

Authorizations:
(platformAppIdplatformAppToken)
Request Body schema:
required
order_id
required
string <uuid>
required
Array of objects (CreateReturnLineItem)
required
object (ReverseDeliveryCreate)
name
string or null
rma
string

Responses

Request samples

Content type
{
  • "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
  • "return_line_items": [
    ],
  • "tracking": {},
  • "name": "string",
  • "rma": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "order": "93b532b3-a125-4cd2-9b71-9996b1e164ce",
  • "return_line_items": [
    ],
  • "status": "canceled",
  • "name": "string",
  • "total_return_line_items": -32768,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "tracking": [
    ],
  • "rma": "string"
}

Retrieve a return

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "order": "93b532b3-a125-4cd2-9b71-9996b1e164ce",
  • "return_line_items": [
    ],
  • "status": "canceled",
  • "name": "string",
  • "total_return_line_items": -32768,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "tracking": [
    ],
  • "rma": "string"
}

Close a return

[Supplier Only] Mark a return request that your Supplier account received from a Storefront as 'CLOSED'.

Identify the return request by its Rokt Catalog ID (UUID) provided in the URL path.

Use Case: This endpoint should typically be called by the Supplier once they have received the physical returned items from the customer/Storefront and completed their internal processing (inspection, restocking, etc.).

Action: Sets the status field of the Supplier's return request record in Catalog to CLOSED.

Important Limitation: This action only updates the status of the Supplier's return record. It does not automatically update the status of the original Storefront's return request, nor does it trigger any notifications or refunds. Subsequent actions, such as initiating a refund using the /refunds/ endpoint, might be required based on the agreed return policy and workflow.

Permissions: Requires the request to be authenticated as the Supplier associated with the return request. Attempting to close a return belonging to another shop results in 403 Forbidden.

A successful update returns 200 OK with the updated details of the Supplier's return request (ReturnSerializer), showing the status as 'CLOSED'.

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string
Request Body schema:
required
order
required
string <uuid>
required
Array of objects (ReturnLineItem)
status
string (Status602Enum)
Enum: "canceled" "closed" "declined" "open" "requested"
  • canceled - canceled
  • closed - closed
  • declined - declined
  • open - open
  • requested - requested
name
string or null <= 501 characters
total_return_line_items
required
integer [ -32768 .. 32767 ]

The sum of all return line item quantities for the return.

required
Array of objects (ReverseDelivery)
rma
string or null <= 501 characters

"Return merchandise authorization" -- used as reference number for SK to SUP comms

Responses

Request samples

Content type
{
  • "order": "93b532b3-a125-4cd2-9b71-9996b1e164ce",
  • "return_line_items": [
    ],
  • "status": "canceled",
  • "name": "string",
  • "total_return_line_items": -32768,
  • "tracking": [],
  • "rma": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "order": "93b532b3-a125-4cd2-9b71-9996b1e164ce",
  • "return_line_items": [
    ],
  • "status": "canceled",
  • "name": "string",
  • "total_return_line_items": -32768,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "tracking": [
    ],
  • "rma": "string"
}

Update return tracking

[Storefront Only] Add or update the tracking information for the shipment returning items back to the Supplier(s). Identify the specific return request using its Rokt Catalog ID (UUID) in the URL path.

Request Body (ReverseDeliveryCreateSerializer):

  • carrier_name (string, optional): Name of the shipping carrier (e.g., 'USPS', 'FedEx').

  • tracking_number (string, optional): The tracking number for the return shipment.

  • tracking_url (string, optional): A direct URL to track the shipment.

  • shipping_label_file_url (string, optional): URL to a downloadable shipping label file (e.g., PDF).

  • shipping_label_created_at (datetime string, optional): Timestamp when the label was created.

Process:

  1. Validation: Checks if the return request exists and belongs to the Storefront.

  2. Create Storefront Return Tracking: Creates a return tracking record containing the provided tracking/label info and associates it with the Storefront's return request.

  3. Sync to Suppliers (Sync): This synchronously attempts to add the same return tracking information to the corresponding return request records on the Supplier side(s).

Response: Returns 200 OK with the updated details of the Storefront's return request (ReturnSerializer), now including the added return tracking information.

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string
query Parameters
ordering
string

Which field to use when ordering the results.

cursor
string

The pagination cursor value.

Request Body schema:
carrier_name
string or null <= 100 characters
tracking_number
string or null <= 100 characters
tracking_url
string or null <uri> <= 200 characters
shipping_label_file_url
string or null <uri> <= 1279 characters

Responses

Request samples

Content type
{}

Response samples

Content type
application/json
{
  • "next": "http://api.example.org/accounts/?cursor=cD00ODY%3D",
  • "previous": "http://api.example.org/accounts/?cursor=cj0xJnA9NDg3",
  • "results": [
    ]
}

Webhooks

Register and manage webhook subscriptions so Rokt Catalog can notify your application when products, orders, and fulfillments change. See the Webhooks guide for the available topics, payloads, and delivery behavior.

List webhooks

Retrieve a paginated list of all webhook subscriptions currently registered and active for the authenticated application (identified by the API credentials used in the request).

The response (RegisteredWebhookSerializer, paginated) includes the unique Rokt Catalog ID (UUID), the subscribed topic, and the target address (URL) for each registered webhook.

Results are returned using cursor-based pagination (PlatformPagination).

Authorizations:
(platformAppIdplatformAppToken)
query Parameters
cursor
string

The pagination cursor value.

Responses

Response samples

Content type
application/json
{}

Create a webhook

Register a new endpoint URL to receive notifications (webhooks) from Rokt Catalog when specific events occur related to your store.

The request body (CreateUpdateWebhookSerializer) requires:

topic: A string representing the event type you want to subscribe to (e.g., product/update, order/cancel, fulfillment/update). See Catalog documentation for the full list of available topics.

address: The HTTPS URL of your application's endpoint that will receive the webhook POST requests from Catalog.

Process: Catalog validates the topic and creates a webhook subscription record associated with your application's integration settings. When an event matching the topic occurs for a resource linked to your store (e.g., an order associated with your shop is cancelled), Catalog will send an HTTP POST request containing the relevant event payload (JSON format) to the registered address.

A successful registration returns 201 Created with the details of the new subscription (RegisteredWebhookSerializer), including its unique Catalog ID (UUID).

Authorizations:
(platformAppIdplatformAppToken)
Request Body schema:
required
topic
required
string
address
required
string

Responses

Request samples

Content type
{
  • "topic": "string",
  • "address": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "topic": "order/create",
  • "address": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z"
}

Retrieve a webhook

Retrieve the details for a single, specific webhook subscription, identified by its Rokt Catalog ID (UUID) provided in the URL path.

Access is restricted to subscriptions belonging to the authenticated application.

The response (RegisteredWebhookSerializer) includes the id, topic, and address.

If the provided ID is invalid or does not correspond to a webhook registered by your application, a 404 Not Found error is returned.

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "topic": "order/create",
  • "address": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z"
}

Update a webhook

Update the configuration of an existing webhook subscription. Identify the subscription by its Rokt Catalog ID (UUID) in the URL path.

The request body (CreateUpdateWebhookSerializer) can include the new topic and/or address you want to set. Partial updates are allowed (only include the fields you want to change).

Validation: If provided, the topic must be one of the valid WEBHOOK_TOPICS.

A successful update returns 200 OK with the complete, updated details of the webhook subscription (RegisteredWebhookSerializer).

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string
Request Body schema:
required
topic
required
string
address
required
string

Responses

Request samples

Content type
{
  • "topic": "string",
  • "address": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "topic": "order/create",
  • "address": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z"
}

Partially update a webhook

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string
Request Body schema:
topic
string (TopicEnum)
Enum: "order/create" "order/update" "order/cancel" "product/create" "product/update" "fulfillment/create" "fulfillment/update"
  • order/create - order/create
  • order/update - order/update
  • order/cancel - order/cancel
  • product/create - product/create
  • product/update - product/update
  • fulfillment/create - fulfillment/create
  • fulfillment/update - fulfillment/update
address
string <= 512 characters

Responses

Request samples

Content type
{
  • "topic": "order/create",
  • "address": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "topic": "order/create",
  • "address": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z"
}

Delete a webhook

Permanently remove an existing webhook subscription, identified by its Rokt Catalog ID (UUID) in the URL path.

Access is restricted to subscriptions belonging to the authenticated application.

Once deleted, Catalog will immediately stop sending notifications for the associated topic to the registered address.

Warning: This action is irreversible. To resume receiving notifications, you must create a new subscription.

A successful deletion returns an HTTP 200 OK status with an empty response body.

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "detail": null
}

CSV

CSV downloads: the product import template, and line-item exports for Partners and Brands. These endpoints back the upload and export flows in the Rokt Catalog app and expect a signed-in app session; use the Products and Variants endpoints with the API headers for programmatic catalog changes.

Download Partner line items CSV

Backs the corresponding flow in the Rokt Catalog app and expects a signed-in app session; the API headers alone do not authenticate this operation.

Authorizations:
(platformAppIdplatformAppToken)

Responses

Download unfulfilled Brand line items CSV

Backs the corresponding flow in the Rokt Catalog app and expects a signed-in app session; the API headers alone do not authenticate this operation.

Authorizations:
(platformAppIdplatformAppToken)

Responses

Download the product CSV template

Backs the corresponding flow in the Rokt Catalog app and expects a signed-in app session; the API headers alone do not authenticate this operation.

Authorizations:
(platformAppIdplatformAppToken)

Responses

Markets

Import market-specific prices for your products. These endpoints back the upload and export flows in the Rokt Catalog app and expect a signed-in app session; use the Products and Variants endpoints with the API headers for programmatic catalog changes.

Import market prices

Backs the corresponding flow in the Rokt Catalog app and expects a signed-in app session; the API headers alone do not authenticate this operation.

Authorizations:
(platformAppIdplatformAppToken)

Responses

Orders

The Orders endpoints give access to every order containing Brand products that was purchased from your Partner storefront. Note: only Rokt Catalog Brand products should appear in these orders.

Order creation example

curl https://api.shopcanal.com/platform/orders/ \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'x-canal-app-id: xxxx-xxxx-xxxx-xxxx' \
  --header 'x-canal-app-token: your_api_access_token' \
  --data '{
    "line_items": [
      {
        "variant_id": "0f9e8d7c-6b5a-4433-8211-000000000001",
        "quantity": 1
      }
    ],
    "shipping_address": {
      "name": "John Doe",
      "address1": "123 Your St",
      "address2": "",
      "city": "San Francisco",
      "province": "California",
      "province_code": "CA",
      "country": "United States of America",
      "country_code": "USA",
      "zip": "94111",
      "phone": "123-456-7890"
    },
    "customer": {
      "email": "john.doe@example.com",
      "first_name": "John",
      "last_name": "Doe"
    }
  }'

List orders

[Storefront Only] Retrieve a paginated list of orders recorded in Rokt Catalog that originated from your Storefront and contain items sourced from Catalog Suppliers.

This provides your Storefront's view of these cross-shop orders.

Results are returned using cursor-based pagination (PlatformPagination). Available ordering fields are created_at and updated_at. The default order is -created_at.

Authorizations:
(platformAppIdplatformAppToken)
query Parameters
ordering
string

Which field to use when ordering the results.

cursor
string

The pagination cursor value.

Responses

Response samples

Content type
application/json
{
  • "next": "http://api.example.org/accounts/?cursor=cD00ODY%3D",
  • "previous": "http://api.example.org/accounts/?cursor=cj0xJnA9NDg3",
  • "results": [
    ]
}

Create an order

[Storefront Only] Record a new customer order placed on your external platform (e.g., your Shopify store) that contains items sourced from Rokt Catalog Suppliers.

The request body (OrderCreateSerializer) must include:

order_name (your unique identifier for this order), currency, email, customer_locale, shipping_address (full address object), billing_address (optional), and a list of line_items.

Each object in line_items requires the Catalog variant_id (UUID of the Storefront's variant record, which links to the Supplier variant) and quantity.

Process:

  1. Validation: Checks if input variants are valid, active, and listed by the supplier. If variants are paused or unlisted, returns 422 Unprocessable Entity. Basic format validation returns 400 Bad Request.

  2. Locking: Acquires a temporary lock based on customer name/phone to prevent duplicate order creation during concurrent requests. If lock fails, returns 503 Service Unavailable.

  3. Storefront Order Creation: Creates the primary order record in Catalog representing the Storefront's view of the order.

  4. Supplier Order Dispatch: Based on the Storefront's order_forwarding_delay setting:

    • If delay > 0: Schedules an asynchronous task to forward order details to relevant Suppliers after the delay. Returns 202 Accepted with the created Storefront order data.

    • If delay == 0: Synchronously attempts to dispatch orders to Suppliers. If successful, returns 201 Created with Storefront order data. If dispatch fails (e.g., Supplier API issue), attempts to cancel any partially created Supplier orders and raises an error (likely resulting in a 500 Internal Server Error response).

Error Handling: Catches various exceptions, including dispatch errors, database connection issues, and general exceptions, logging them and potentially returning 500 Internal Server Error.

Authorizations:
(platformAppIdplatformAppToken)
Request Body schema:
required
required
Array of objects (CreateOrderLineItem)
object (OrderCreateCustomer)
order_name
string
total_tax
string <decimal> ^-?\d{0,8}(?:\.\d{0,4})?$
Array of objects (OrderNoteAttribute)

This field is useful for passing customization options for Supplier products that support customization (gift messages, logos, custom text). Example: {"name": "Variant 1 Custom Text", "value": ""}

required
object (Address)
object (Address)

Responses

Request samples

Content type
{
  • "line_items": [
    ],
  • "customer": {
    },
  • "order_name": "string",
  • "total_tax": "string",
  • "note_attributes": [
    ],
  • "shipping_address": {
    },
  • "billing_address": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "remote_rid": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "shop": {
    },
  • "customer": {
    },
  • "email": "user@example.com",
  • "total_price": "string",
  • "currency": "string",
  • "name": "string",
  • "line_items": [
    ],
  • "fulfillments": [
    ],
  • "billing_address": null,
  • "shipping_address": null,
  • "shipping_lines": [
    ],
  • "cancelled_at": "2019-08-24T14:15:22Z",
  • "refunds": [
    ],
  • "connected_supplier_order_numbers": [
    ],
  • "cancel_reason": "string",
  • "note_attributes": [
    ],
  • "returns": [
    ]
}

Retrieve an order

[Storefront Only] Retrieve the full details for a specific Rokt Catalog order, identified by its Catalog ID (UUID) in the URL path.

This endpoint provides the Storefront's perspective on the order. Access is restricted to orders associated with the authenticated Storefront (request.shop).

The response (OrderSerializer) includes comprehensive information: customer details (email, customer_locale), shipping_address, billing_address, currency, order_name, line_items (with Catalog variant IDs and quantities), overall fulfillment_status, financial_status, cancelled_at timestamp (if applicable), calculated totals (total_price, subtotal_price, etc.), and potentially links or references to the corresponding connected orders created on the Supplier side.

If the provided order ID is invalid or the order does not belong to your Storefront, a 404 Not Found error is returned.

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "remote_rid": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "shop": {
    },
  • "customer": {
    },
  • "email": "user@example.com",
  • "total_price": "string",
  • "currency": "string",
  • "name": "string",
  • "line_items": [
    ],
  • "fulfillments": [
    ],
  • "billing_address": null,
  • "shipping_address": null,
  • "shipping_lines": [
    ],
  • "cancelled_at": "2019-08-24T14:15:22Z",
  • "refunds": [
    ],
  • "connected_supplier_order_numbers": [
    ],
  • "cancel_reason": "string",
  • "note_attributes": [
    ],
  • "returns": [
    ]
}

Cancel an order

[Storefront Only] Cancel a Rokt Catalog order associated with your Storefront.

Identify the order to be cancelled by its Catalog ID (UUID) provided in the URL path.

Process:

  1. Update Storefront Order: Sets the cancelled_at field on the Storefront's order record in Catalog to the current timestamp.

  2. Cancel Supplier Orders: Triggers an asynchronous operation. This attempts to cancel the corresponding order(s) that were previously dispatched to the relevant Supplier(s)' external platforms (e.g., calling the Shopify API to cancel the order on the Supplier's store).

  3. Webhook: Emits an ORDER_CANCEL webhook event containing the details of the cancelled Storefront order.

Permissions: Requires valid platform integration settings for the Storefront. If settings are missing, returns 403 Forbidden.

A successful cancellation returns 200 OK with the updated Storefront order details (OrderSerializer), including the cancelled_at timestamp.

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "remote_rid": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "shop": {
    },
  • "customer": {
    },
  • "email": "user@example.com",
  • "total_price": "string",
  • "currency": "string",
  • "name": "string",
  • "line_items": [
    ],
  • "fulfillments": [
    ],
  • "billing_address": null,
  • "shipping_address": null,
  • "shipping_lines": [
    ],
  • "cancelled_at": "2019-08-24T14:15:22Z",
  • "refunds": [
    ],
  • "connected_supplier_order_numbers": [
    ],
  • "cancel_reason": "string",
  • "note_attributes": [
    ],
  • "returns": [
    ]
}

Create or get an order

[Storefront Only] Safely create or retrieve a Catalog order using your Storefront's unique order identifier (order_name) to ensure idempotency.

Behavior:

  1. Check Existing: The system first queries for an existing active (non-cancelled) order associated with your shop that matches the provided order_name.

  2. Return Existing: If exactly one such active order is found, the endpoint immediately returns 200 OK with the details of that existing order (OrderSerializer). This prevents duplicate creation.

  3. Handle Duplicates: If multiple active orders are found with the same order_name (which indicates a potential issue), it returns a 400 Bad Request validation error.

  4. Create New: If no active order with the given order_name is found, the endpoint proceeds to call the standard create method (the /orders/ POST endpoint logic) using the entire request payload.

Payload Requirement: Even though this endpoint might retrieve an existing order, you must provide the full order creation payload (identical to the standard /orders/ create request) in the request body. This payload is used only if a new order needs to be created.

Use Case: This endpoint is ideal for scenarios where order creation requests might be retried (e.g., due to network issues). It guarantees that submitting the same request multiple times will result in only one Catalog order being created.

Responses & Errors: If creating a new order, the responses (201 Created, 202 Accepted) and potential errors (400, 422, 500, 503) are identical to those of the standard create endpoint.

Authorizations:
(platformAppIdplatformAppToken)
Request Body schema:
required
required
Array of objects (CreateOrderLineItem)
object (OrderCreateCustomer)
order_name
string
total_tax
string <decimal> ^-?\d{0,8}(?:\.\d{0,4})?$
Array of objects (OrderNoteAttribute)

This field is useful for passing customization options for Supplier products that support customization (gift messages, logos, custom text). Example: {"name": "Variant 1 Custom Text", "value": ""}

required
object (Address)
object (Address)

Responses

Request samples

Content type
{
  • "line_items": [
    ],
  • "customer": {
    },
  • "order_name": "string",
  • "total_tax": "string",
  • "note_attributes": [
    ],
  • "shipping_address": {
    },
  • "billing_address": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "remote_rid": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "shop": {
    },
  • "customer": {
    },
  • "email": "user@example.com",
  • "total_price": "string",
  • "currency": "string",
  • "name": "string",
  • "line_items": [
    ],
  • "fulfillments": [
    ],
  • "billing_address": null,
  • "shipping_address": null,
  • "shipping_lines": [
    ],
  • "cancelled_at": "2019-08-24T14:15:22Z",
  • "refunds": [
    ],
  • "connected_supplier_order_numbers": [
    ],
  • "cancel_reason": "string",
  • "note_attributes": [
    ],
  • "returns": [
    ]
}

Create and charge an order

[Storefront Only] Create a new order with immediate payment processing.

This endpoint combines order creation and payment processing in a single request.

The request body follows the same structure as the standard order creation endpoint, with additional payment fields.

Process:

  1. Validation: Checks if input variants are valid, active, and listed by the supplier. If variants are paused or unlisted, returns 422 Unprocessable Entity. Basic format validation returns 400 Bad Request.

  2. Payment Processing: Processes the payment with a third party payment service provider.

  3. Storefront Order Creation: Creates the primary order record in Catalog representing the Storefront's view of the order.

  4. Supplier Order Dispatch: Schedules an asynchronous task to forward order details to relevant Suppliers. Returns 202 Accepted with the created Storefront order data.

Responses & Errors:

Response: Returns the created order details on success, or payment/validation errors on failure.

Error Handling: Catches various exceptions, including dispatch errors, database connection issues, and general exceptions, logging them and potentially returning 500 Internal Server Error. If payment fails, will not continue with order creation.

Authorizations:
(platformAppIdplatformAppToken)
Request Body schema:
required
required
Array of objects (CreateOrderLineItem)
object (OrderCreateCustomer)
order_name
string
total_tax
string <decimal> ^-?\d{0,8}(?:\.\d{0,4})?$
Array of objects (OrderNoteAttribute)

This field is useful for passing customization options for Supplier products that support customization (gift messages, logos, custom text). Example: {"name": "Variant 1 Custom Text", "value": ""}

partner_name
string
required
object (OrderShippingDetails)
ppu_transaction_id
required
string

The Post Purchase Upsell session id for the tax calculation. This matches the tax calculation request.

required
object

This field is the response from the vault. It is used to charge the customer.

Responses

Request samples

Content type
{
  • "line_items": [
    ],
  • "customer": {
    },
  • "order_name": "string",
  • "total_tax": "string",
  • "note_attributes": [
    ],
  • "partner_name": "string",
  • "shipping_details": {
    },
  • "ppu_transaction_id": "string",
  • "payment_details": {
    }
}

Response samples

Content type
application/json
{
  • "confirmation_details": {
    },
  • "line_items": [
    ],
  • "customer": {
    },
  • "shipping_address": {
    },
  • "display_metadata": {
    },
  • "payment_details": {
    }
}

Initialize an order

[Storefront Only] Create a new order and receive a Stripe PaymentIntent client secret for frontend payment confirmation.

This endpoint allows Storefronts to initiate order creation and receive a Stripe client_secret, which must be passed to the Stripe frontend payment element (such as Stripe Elements) to collect payment authorization from the customer.

The request payload mirrors the standard post purchase upsell order creation structure, but payment details are not required.

Process:

  1. Validation: Ensures input variants are valid, active, and listed by the supplier. If variants are paused, unlisted, or invalid, returns 422 Unprocessable Entity. If the input data format is invalid, returns 400 Bad Request.

  2. Stripe PaymentIntent Creation: Generates a Stripe PaymentIntent and returns its client_secret. The client secret must be used with the Stripe frontend integration to complete payment.

  3. Order Creation: Creates the primary Storefront order record in Catalog, associated with the PaymentIntent.

  4. Supplier Dispatch: After payment confirmation from the frontend, supplier orders are asynchronously dispatched.

Responses & Errors:

Response: On success, returns order details and the Stripe client_secret for the PaymentIntent. The frontend must use this secret to proceed with payment authorization.

Error Handling: Returns specific errors for failed validation, payment intent creation issues, or unexpected exceptions (such as dispatch or database failures). If payment intent creation fails, order creation will not proceed.

Authorizations:
(platformAppIdplatformAppToken)
Request Body schema:
required
required
Array of objects (CreateOrderLineItem)
object (OrderCreateCustomer)
order_name
string
total_tax
string <decimal> ^-?\d{0,8}(?:\.\d{0,4})?$
Array of objects (OrderNoteAttribute)

This field is useful for passing customization options for Supplier products that support customization (gift messages, logos, custom text). Example: {"name": "Variant 1 Custom Text", "value": ""}

partner_name
string
required
object (OrderShippingDetails)
ppu_transaction_id
required
string

The Post Purchase Upsell session id for the tax calculation. This matches the tax calculation request.

object

This field is the response from the vault. It is used to charge the customer.

Responses

Request samples

Content type
{
  • "line_items": [
    ],
  • "customer": {
    },
  • "order_name": "string",
  • "total_tax": "string",
  • "note_attributes": [
    ],
  • "partner_name": "string",
  • "shipping_details": {
    },
  • "ppu_transaction_id": "string",
  • "payment_details": {
    }
}

Response samples

Content type
application/json
{
  • "confirmation_details": {
    },
  • "line_items": [
    ],
  • "customer": {
    },
  • "shipping_address": {
    },
  • "display_metadata": {
    },
  • "payment_details": {
    }
}

Products

The Products endpoints give access to every product you have permission to sell on your Partner storefront, and let Brands create, update, reorder, and delete the products they supply. To get permission to sell specific products, send proposals to Brands in the Rokt Catalog app; once a Brand approves a proposal, its products become available through these endpoints.

List products

[Storefront Only] Retrieve a paginated list of products accessible to your Storefront through your established Rokt Catalog connections.

This endpoint returns products from Suppliers with whom you have an active and approved partnership. It includes products you might have already added/linked to your Storefront platform, as well as other products listed by those Suppliers that are available to you based on your connection terms.

You can filter the results to view products exclusively from one Supplier by providing their Catalog supplier_id (UUID) as a query parameter.

Results are returned using cursor-based pagination (PlatformPagination). Available ordering fields include created_at, updated_at, and title. The default order is -created_at.

Authorizations:
(platformAppIdplatformAppToken)
query Parameters
ordering
string

Which field to use when ordering the results.

cursor
string

The pagination cursor value.

supplier_id
string <uuid>

Filter products by the Catalog ID of a specific connected Supplier.

qa_review_complete
boolean

Filter products by whether they have been reviewed and approved.

Responses

Response samples

Content type
application/json
{
  • "next": "http://api.example.org/accounts/?cursor=cD00ODY%3D",
  • "previous": "http://api.example.org/accounts/?cursor=cj0xJnA9NDg3",
  • "results": [
    ]
}

Create a product

[Supplier Only] Create a new product listing within your Rokt Catalog Supplier account. This makes the product manageable through Catalog and potentially available to your connected Storefront partners.

The request body must conform to the PushProductSerializer structure. Key fields include:

title (string, required), body_html (string, product description), product_type (string), vendor (string), tags (string, comma-separated), and a list of variants (required, at least one).

Each object in the variants list requires price (decimal string), sku (string), inventory_quantity (integer), and option values (option1, option2, option3). compare_at_price (decimal string) is optional for sale pricing.

You can also include a list of images, each with a src (URL) and optional position.

Successfully creating a product (HTTP 201 Created) makes it visible in your Catalog dashboard. Its availability to Storefronts depends on its listing status (supplier_has_listed_on_canal flag on variants) and the terms established with each partner.

The response body contains the full details of the newly created product and its variants, including their assigned Catalog IDs (UUIDs), using the ProductSerializer.

Authorizations:
(platformAppIdplatformAppToken)
Request Body schema:
required
title
required
string
body_html
string
required
Array of objects (PushProductVariant)
permalink
string
handle
string
image_src
string
Array of objects (Image)
product_type
string
tags
string
vendor
string
shopify_taxonomy
string or null
is_listed
boolean
Default: true
status
string
Default: "active"
Enum: "active" "draft" "archived"
  • active - active
  • draft - draft
  • archived - archived

Responses

Request samples

Content type
{
  • "title": "string",
  • "body_html": "string",
  • "variants": [
    ],
  • "permalink": "string",
  • "handle": "string",
  • "image_src": "string",
  • "images": [
    ],
  • "product_type": "string",
  • "tags": "string",
  • "vendor": "string",
  • "shopify_taxonomy": "string",
  • "is_listed": true,
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "shop": {
    },
  • "variants": [
    ],
  • "body_html": "string",
  • "handle": "string",
  • "image_src": "string",
  • "images": [
    ],
  • "options": null,
  • "product_type": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "published_at": "2019-08-24T14:15:22Z",
  • "status": "active",
  • "title": "string",
  • "vendor": "string",
  • "tags": "string",
  • "permalink": "http://example.com",
  • "number_of_reviews": -2147483648,
  • "star_rating": 0.1
}

Retrieve a product

[Storefront Only] Retrieve comprehensive details for a single product, identified by its Rokt Catalog ID (UUID) in the URL path.

Access is restricted: this endpoint only returns data for products sourced from Suppliers with whom your Storefront has an active and approved partnership connection.

The response (ExternalProductSerializer) includes all product-level information (title, description, vendor, etc.), a list of associated images, and a list of variants.

Crucially, the variant information includes pricing (price, compare_at_price) and inventory_quantity that are specific to your connection with the Supplier, reflecting any agreed-upon terms or markups managed by Catalog.

If the provided product ID is invalid, or if the product belongs to a Supplier you are not actively connected with, a 404 Not Found error is returned.

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "shop": {
    },
  • "variants": [
    ],
  • "body_html": "string",
  • "handle": "string",
  • "image_src": "string",
  • "images": [
    ],
  • "options": [
    ],
  • "product_type": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "published_at": "2019-08-24T14:15:22Z",
  • "status": "active",
  • "title": "string",
  • "vendor": "string",
  • "tags": "string",
  • "permalink": "http://example.com",
  • "number_of_reviews": -2147483648,
  • "star_rating": 0.1,
  • "product_type_category": "string",
  • "customer_charge_amount": {
    }
}

Update a product

[Supplier Only] Update attributes of an existing product listing, identified by its Rokt Catalog ID (UUID) in the URL path.

This endpoint is used for modifying product-level details. Provide the fields you wish to change in the request body (e.g., title, body_html, product_type, vendor, tags).

Important: To modify variant-specific details like price, SKU, inventory, or options, you must use the dedicated /variants/{variant_id}/ endpoint. Updates to variants are not supported here.

Changes made to product-level fields via this endpoint (like updating the description) are automatically synchronized to any connected Storefronts that are currently selling this product. This synchronization process runs asynchronously in the background.

A successful update returns 200 OK with the complete, updated product details (including all variants) using the ProductSerializer.

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string
Request Body schema:
required
body_html
string or null <= 60000 characters
handle
string or null <= 258 characters
image_src
string or null <= 1043 characters
Array of objects (Image)
options
any

Product options (for example size or color) and their values, or null when the product has none.

product_type
string or null <= 1044 characters
published_at
string or null <date-time>
status
string (Status2eaEnum)
Enum: "active" "draft" "archived" "unlisted"
  • active - active
  • draft - draft
  • archived - archived
  • unlisted - unlisted
title
required
string <= 1029 characters
vendor
string or null <= 227 characters
tags
string or null <= 63750 characters
permalink
string or null <uri> <= 2000 characters
number_of_reviews
integer or null [ -2147483648 .. 2147483647 ]
star_rating
number or null <double>

Responses

Request samples

Content type
{
  • "body_html": "string",
  • "handle": "string",
  • "image_src": "string",
  • "images": [
    ],
  • "options": null,
  • "product_type": "string",
  • "published_at": "2019-08-24T14:15:22Z",
  • "status": "active",
  • "title": "string",
  • "vendor": "string",
  • "tags": "string",
  • "permalink": "http://example.com",
  • "number_of_reviews": -2147483648,
  • "star_rating": 0.1
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "shop": {
    },
  • "variants": [
    ],
  • "body_html": "string",
  • "handle": "string",
  • "image_src": "string",
  • "images": [
    ],
  • "options": null,
  • "product_type": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "published_at": "2019-08-24T14:15:22Z",
  • "status": "active",
  • "title": "string",
  • "vendor": "string",
  • "tags": "string",
  • "permalink": "http://example.com",
  • "number_of_reviews": -2147483648,
  • "star_rating": 0.1
}

Partially update a product

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string
Request Body schema:
body_html
string or null <= 60000 characters
handle
string or null <= 258 characters
image_src
string or null <= 1043 characters
Array of objects (Image)
options
any

Product options (for example size or color) and their values, or null when the product has none.

product_type
string or null <= 1044 characters
published_at
string or null <date-time>
status
string (Status2eaEnum)
Enum: "active" "draft" "archived" "unlisted"
  • active - active
  • draft - draft
  • archived - archived
  • unlisted - unlisted
title
string <= 1029 characters
vendor
string or null <= 227 characters
tags
string or null <= 63750 characters
permalink
string or null <uri> <= 2000 characters
number_of_reviews
integer or null [ -2147483648 .. 2147483647 ]
star_rating
number or null <double>

Responses

Request samples

Content type
{
  • "body_html": "string",
  • "handle": "string",
  • "image_src": "string",
  • "images": [
    ],
  • "options": null,
  • "product_type": "string",
  • "published_at": "2019-08-24T14:15:22Z",
  • "status": "active",
  • "title": "string",
  • "vendor": "string",
  • "tags": "string",
  • "permalink": "http://example.com",
  • "number_of_reviews": -2147483648,
  • "star_rating": 0.1
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "shop": {
    },
  • "variants": [
    ],
  • "body_html": "string",
  • "handle": "string",
  • "image_src": "string",
  • "images": [
    ],
  • "options": null,
  • "product_type": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "published_at": "2019-08-24T14:15:22Z",
  • "status": "active",
  • "title": "string",
  • "vendor": "string",
  • "tags": "string",
  • "permalink": "http://example.com",
  • "number_of_reviews": -2147483648,
  • "star_rating": 0.1
}

Delete a product

[Supplier Only] Permanently remove a product listing, identified by its Rokt Catalog ID (UUID) in the URL path, from the Catalog platform.

Warning: This action is irreversible. Ensure you intend to delete this product permanently.

You can only delete products that are directly owned by your Supplier account. Attempting to delete a product belonging to another shop will result in a 403 Forbidden error.

Effect on Storefronts: When a product is deleted, Catalog automatically pauses the corresponding product listings on any connected Storefronts that were actively selling it. An asynchronous task is initiated to inform these Storefronts about the product's removal.

A successful deletion returns an HTTP 204 No Content status with an empty response body.

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "detail": null
}

Reorder product variants

[Supplier Only] Update the display sequence of variants for a specific product. The product is identified by its Rokt Catalog ID (UUID) in the URL path.

The request body must contain a field named variant_order, which is a list of Catalog variant IDs (UUIDs) sorted in the desired display order (0-indexed).

Requirement: The variant_order list must include the IDs of all currently existing variants for the specified product. Omitting or adding incorrect IDs will result in a validation error (400 Bad Request).

This reordering affects how variants are presented within the Catalog platform (e.g., in the Supplier dashboard). It may also influence the display order on connected Storefronts if their integration respects the position attribute of the variants.

A successful update returns 200 OK with the full product details (ProductSerializer), reflecting the new position values for each variant.

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string
Request Body schema:
required
variant_order
required
Array of strings <uuid> [ items <uuid > ]

Responses

Request samples

Content type
{
  • "variant_order": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "shop": {
    },
  • "variants": [
    ],
  • "body_html": "string",
  • "handle": "string",
  • "image_src": "string",
  • "images": [
    ],
  • "options": null,
  • "product_type": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "published_at": "2019-08-24T14:15:22Z",
  • "status": "active",
  • "title": "string",
  • "vendor": "string",
  • "tags": "string",
  • "permalink": "http://example.com",
  • "number_of_reviews": -2147483648,
  • "star_rating": 0.1
}

Resync a product

Resynchronize a retailer (Shopkeep) product with its origin supplier product.

If fields_to_resync is provided, only those fields will be updated; otherwise all fields are resynced.

On success, returns the updated product data. If the resync is queued to run asynchronously (e.g. due to rate limits), returns a message indicating the resync has started.

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string
Request Body schema:
fields_to_resync
Array of strings (FieldsToResyncEnum)
Items Enum: "images" "product_title" "description" "tags" "variants" "vendor" "permalink"

Responses

Request samples

Content type
{
  • "fields_to_resync": [
    ]
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "status": "string",
  • "shopify_product": {
    }
}

List upsell products

[Storefront Only] Retrieve a paginated list of active products that are eligible for upselling.

This endpoint returns products from Suppliers with whom you have an active and approved partnership.

Products must meet the following criteria:

  1. Have status='active',

  2. Have at least one variant that is connected to a supplier variant, listed on Catalog, and not paused for selling,

  3. Have passed ads eligibility checks,

  4. Have at least one available variant in a non-deleted product set,

Authorizations:
(platformAppIdplatformAppToken)
query Parameters
ordering
string

Which field to use when ordering the results.

cursor
string

The pagination cursor value.

supplier_id
string <uuid>

Filter products by the Catalog ID of a specific connected Supplier.

Responses

Response samples

Content type
application/json
{
  • "next": "http://api.example.org/accounts/?cursor=cD00ODY%3D",
  • "previous": "http://api.example.org/accounts/?cursor=cj0xJnA9NDg3",
  • "results": [
    ]
}

Shops

Shops are the Brand accounts connected to your Partner storefront. List your active connections, retrieve a connected Brand, or request new connections by Brand contact email.

List shops

[Storefront Only] Retrieve a paginated list of Supplier shops with whom your Storefront has an active and approved partnership connection.

This endpoint provides essential details for each connected Supplier, such as their name, Rokt Catalog ID, contact information, and domain.

Use this to get an overview of your current Supplier network within Catalog.

You can filter this list to find a specific Supplier by providing their canal_contact_email using the email query parameter (ensure proper URL encoding if the email contains special characters like '+').

Results are returned using cursor-based pagination, ordered by updated_at descending by default. Standard ordering fields like created_at and name are also available.

Authorizations:
(platformAppIdplatformAppToken)
query Parameters
cursor
string

The pagination cursor value.

email
string <email>

Filter by the Supplier's primary contact email address.

Responses

Response samples

Content type
application/json
{}

Create shop connections

[Storefront Only] Initiate partnership connection requests with one or more existing Rokt Catalog Suppliers by specifying their primary contact email addresses.

In the request body, provide a list of strings under the key canal_contact_emails.

For each email address that corresponds to an active Catalog Supplier shop, Catalog will record your request to connect, initially in a pending state.

The Supplier must then approve this request (usually through the Catalog web application) for the connection to become active.

Once approved, the Supplier will appear in your 'My Suppliers' list within the Catalog app, and you will gain access to view and potentially sell their products based on the agreed terms.

This endpoint returns a 201 Created status along with the details (using ShopSerializer) of the Supplier shops for which pending connection requests were successfully created. It does not wait for Supplier approval. If an email does not match an active Supplier, no request is created for that email.

Authorizations:
(platformAppIdplatformAppToken)
Request Body schema:
required
canal_contact_emails
required
Array of strings <email> [ items <email > ]

Responses

Request samples

Content type
{
  • "canal_contact_emails": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "string",
  • "phone": "string",
  • "name": "string",
  • "description": "string",
  • "myshopify_domain": "string",
  • "province": "string",
  • "country": "string",
  • "domain": "string",
  • "display_domain": "string",
  • "privacy_policy_url": "http://example.com",
  • "terms_of_service_url": "http://example.com"
}

Retrieve a shop

[Storefront Only] Retrieve the full profile details for a specific Supplier shop, identified by its unique Rokt Catalog ID (UUID) provided in the URL path.

Access is restricted: this endpoint will only return data if an active and approved partnership connection exists between your Storefront and the specified Supplier.

The response includes comprehensive details like shop name, ID, contact info, address, configured settings (if applicable), etc.

If the provided ID is invalid, does not correspond to a Supplier shop, or if no approved connection exists, a 404 Not Found error will be returned.

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "string",
  • "phone": "string",
  • "name": "string",
  • "description": "string",
  • "myshopify_domain": "string",
  • "province": "string",
  • "country": "string",
  • "domain": "string",
  • "display_domain": "string",
  • "privacy_policy_url": "http://example.com",
  • "terms_of_service_url": "http://example.com"
}

Shipping rates

The Shipping Rates endpoints allow the Partner to determine how much to charge for shipping Brand products that are bought through the Partner storefront. Rokt Catalog charges the Partner this amount for shipping and passes it to the Brand. An empty list is returned when the line items cannot be shipped to the given location.

Calculate shipping rates

[Storefront Only] Calculate available shipping options and their estimated costs for a given destination address and a set of line items containing products sourced from Rokt Catalog Suppliers.

This endpoint is typically used during the checkout process after the customer has provided their shipping address.

Request Body (ShippingQuerySerializer):

  • shipping_address (object, required): The destination address, including fields like address1, city, province_code, country_code, zip. name and phone are optional but recommended.

  • line_items (list, required): A list of objects, each specifying:

    • variant_id (UUID, required): The Rokt Catalog ID of the Storefront's variant record.

    • quantity (integer, required): The quantity of this variant.

Process:

  1. Identify Suppliers: Catalog determines which unique Suppliers are involved based on the variant_ids provided.

  2. Query Suppliers: For each unique Supplier, Catalog queries their integrated shipping rate provider (e.g., Shopify's API) using the provided shipping_address and the subset of line_items belonging to that Supplier.

  3. Aggregate Rates: Catalog aggregates the rates returned from all involved Suppliers. The exact aggregation logic might vary (e.g., summing costs for the same shipping service level across suppliers, presenting distinct options per supplier).

Response (ShippingRateResponseSerializer):

  • rates (list): A list of available shipping rate options. Each object contains:

    • title (string): The name of the shipping service (e.g., 'Standard Ground', 'Express Overnight').

    • price (Money object): The calculated cost for this shipping option, including amount (decimal string) and currency (string).

    • Potentially other fields depending on the Supplier's integration.

This response allows the Storefront to present the customer with accurate shipping choices and costs before finalizing the order.

Authorizations:
(platformAppIdplatformAppToken)
Request Body schema:
required
required
Array of objects (CreateOrderLineItem)
required
object (Address)

Responses

Request samples

Content type
{
  • "line_items": [
    ],
  • "shipping_address": {
    }
}

Response samples

Content type
application/json
{
  • "shipping_rates": [
    ]
}

Max shipping rates

Estimate the highest shipping cost for a set of line items before the customer has entered an address, for "Shipping from" style displays on a product page.

Estimate max shipping rates

[Storefront Only] Provide a rough, potentially overestimated shipping cost for a set of line items, useful for display before a customer provides their full address (e.g., showing 'Shipping from $X' on a product page).

Request Body (MaxShippingQuerySerializer):

  • line_items (list, required): A list of objects, each specifying:

    • variant_id (UUID, required): The Rokt Catalog ID of the Storefront's variant record.

    • quantity (integer, required): The quantity of this variant.

Process:

  1. Default Address: This endpoint ignores any address provided and instead uses a hardcoded default address (currently hardcoded to San Francisco, CA: 655 Montgomery St, 94111).

  2. Query Suppliers: It queries the relevant Suppliers for shipping rates to this default address using the provided line_items.

  3. Find Maximum: It identifies the single highest shipping rate returned across all involved Suppliers for the default address.

Response (ShippingRateResponseSerializer):

  • rates (list): Typically contains only one rate object representing the maximum cost found for the default address. The object includes title and price (Money object).

Disclaimer: This is an estimate based on a fixed location. The actual shipping cost calculated using the customer's real address via the /shipping_rates endpoint during checkout may be significantly different (higher or lower).

Authorizations:
(platformAppIdplatformAppToken)
Request Body schema:
required
required
Array of objects (CreateOrderLineItem)
Array
variant_id
required
string <uuid>
quantity
required
integer
price
string <decimal> ^-?\d{0,8}(?:\.\d{0,4})?$

Responses

Request samples

Content type
{
  • "line_items": [
    ]
}

Response samples

Content type
application/json
{
  • "shipping_rates": [
    ]
}

Tax

Calculate estimated tax lines for a set of line items and a shipping address.

Calculate tax

[Storefront Only] Calculate estimated tax lines for a set of line items and a shipping address.

Authorizations:
(platformAppIdplatformAppToken)
Request Body schema:
required
required
Array of objects (CreateOrderLineItem)
required
object

The destination address, including fields like city, province_code, country_code, zip. address1, name and phone are optional but recommended.

object

The billing address, including fields like city, province_code, country_code, zip. address1, name and phone are optional but recommended.

Responses

Request samples

Content type
{
  • "line_items": [
    ],
  • "shipping_address": {
    },
  • "billing_address": {
    }
}

Response samples

Content type
application/json
{
  • "tax_amount": "string",
  • "currency": "USD",
  • "tax_lines_per_supplier": {
    },
  • "calculation_errors": [
    ]
}

Tax and shipping

Calculate estimated tax lines and available shipping options in a single call during checkout, once the customer has provided a shipping address. See Calculating Tax and Shipping for Shoppable Ads.

Calculate tax and shipping

[Storefront Only] Calculate estimated tax lines and available shipping options and costs, given a set of line items, shipping address, and optionally a billing address.

This endpoint is typically used during the checkout process after the customer has provided their shipping address.

Request Body (TaxCalculationQuerySerializer):

  • line_items (list, required): A list of objects, each specifying:

    • variant_id (UUID, required): The Catalog ID of the Storefront's variant record.

    • quantity (integer, required): The quantity of this variant.

  • shipping_address (object, required): The destination address, including fields like address1, city, province_code, country_code, zip. name and phone are optional but recommended.

  • billing_address (object, optional): The billing address, with the same fields as shipping_address.

Process:

  1. Identify Suppliers: Catalog determines which unique Suppliers are involved based on the variant_ids provided.

  2. Query Suppliers: For each unique Supplier, Catalog queries their integrated shipping rate provider (e.g., Shopify's API) using the provided shipping_address and the subset of line_items belonging to that Supplier.

  3. Aggregate Rates: Catalog aggregates the rates returned from all involved Suppliers. The exact aggregation logic might vary (e.g., summing costs for the same shipping service level across suppliers, presenting distinct options per supplier).

  4. Tax Calculation: Catalog queries an integrated tax rate provider (e.g., Shopify's API) using the provided shipping_address and billing_address to calculate the tax line items for this order.

Response (TaxAndShippingResponseSerializer):

  • rates (list): A list of available shipping rate options. Each object contains:

    • title (string): The name of the shipping service (e.g., 'Standard Ground', 'Express Overnight').

    • price (Money object): The calculated cost for this shipping option, including amount (decimal string) and currency (string).

    • Potentially other fields depending on the Supplier's integration.

  • tax_amount (string): Total sum of the taxes applied to this order.

  • currency (string): Currency for the current order.

  • tax_lines_per_supplier: Dictionary mapping a supplier's id to a list of tax line responses.

This response allows the Storefront to present the customer with accurate shipping choices and costs before finalizing the order.

Authorizations:
(platformAppIdplatformAppToken)
Request Body schema:
required
required
Array of objects (CreateOrderLineItem)
required
object

The destination address, including fields like city, province_code, country_code, zip. address1, name and phone are optional but recommended.

object

The billing address, including fields like city, province_code, country_code, zip. address1, name and phone are optional but recommended.

Responses

Request samples

Content type
{
  • "line_items": [
    ],
  • "shipping_address": {
    },
  • "billing_address": {
    }
}

Response samples

Content type
application/json
{
  • "shipping_rates": [
    ],
  • "tax_amount": "string",
  • "currency": "USD",
  • "tax_lines_per_supplier": {
    },
  • "calculation_errors": [
    ]
}

Calculate tax and shipping (v1)

[Storefront Only] Calculate estimated tax lines and available shipping options and costs, given a set of line items, shipping address, and optionally a billing address.

This endpoint is typically used during the checkout process after the customer has provided their shipping address.

Process:

  1. Tax Calculation: Rokt Catalog queries an integrated tax rate provider (e.g., Shopify's API) using the provided shipping_address and billing_address to calculate the tax line items for this order.

  2. Shipping Calculation: Catalog queries an integrated shipping rate provider (e.g., Shopify's API) using the provided shipping_address and the subset of line_items belonging to that Supplier.

Authorizations:
(platformAppIdplatformAppToken)
Request Body schema:
required
required
Array of objects (CreateOrderLineItem)
required
object

The destination address, including fields like city, province_code, country_code, zip. address1, name and phone are optional but recommended.

object

The billing address, including fields like city, province_code, country_code, zip. address1, name and phone are optional but recommended.

ppu_transaction_id
required
string

The Post Purchase Upsell session id for the tax calculation. This will be reused at order creation time to match the tax calculation request.

Responses

Request samples

Content type
{
  • "line_items": [
    ],
  • "shipping_address": {
    },
  • "billing_address": {
    },
  • "ppu_transaction_id": "string"
}

Response samples

Content type
application/json
{
  • "line_items": [
    ],
  • "calculation_errors": [
    ],
  • "request_id": "266ea41d-adf5-480b-af50-15b940c2b846"
}

Fulfillments

The Fulfillments endpoints give access to the latest shipping information for Brand orders placed through your Partner storefront. Brands create and update fulfillment (shipment) records; Partners list and retrieve them to show tracking to their customers. Note: only Rokt Catalog Brand products should appear in these fulfillments.

List fulfillments

Retrieve a paginated list of fulfillment records associated with the authenticated store, reflecting its role in the order process.

  • If called by a Storefront: Returns fulfillments created by connected Suppliers for orders originating from the Storefront. This allows the Storefront to track shipments for items their customers ordered.

  • If called by a Supplier: Returns fulfillments created by this Supplier for orders they received from connected Storefronts.

Results (FulfillmentSerializer) include tracking details when present, status, associated line items, and timestamps.

Pagination is cursor-based (PlatformPagination). Ordering is available on created_at and updated_at, defaulting to -created_at.

Authorizations:
(platformAppIdplatformAppToken)
query Parameters
ordering
string

Which field to use when ordering the results.

cursor
string

The pagination cursor value.

Responses

Response samples

Content type
application/json
{
  • "next": "http://api.example.org/accounts/?cursor=cD00ODY%3D",
  • "previous": "http://api.example.org/accounts/?cursor=cj0xJnA9NDg3",
  • "results": [
    ]
}

Create a fulfillment

[Supplier Only] Create a fulfillment record for items in an order received from a connected Storefront.

The request body (CreateFulfillmentSerializer) must specify:

order_id (UUID of the Supplier's Rokt Catalog order record) and a list of line_items.

Each object in line_items needs the Catalog id (UUID) of the Supplier's line item record and the quantity being fulfilled.

For physical shipments, include tracking information (tracking_company, tracking_numbers, tracking_urls) when available. For digital/email fulfillment with no shipment, omit the tracking fields.

Process:

  1. Validation: Checks if the order exists, belongs to the Supplier, is a connected order, and if the provided line items are valid. Returns 400 Bad Request or 404 Not Found on failure.

  2. Create Supplier Fulfillment: Creates the fulfillment record associated with the Supplier's order in Catalog. Considers feature flags to determine if the notify_customer flag should be set during downstream sync.

  3. Sync to Storefront: Triggers a synchronization process. This attempts to create or update the corresponding fulfillment record on the original Storefront's order (e.g., via Shopify API), including tracking information when present.

  4. Webhook: Emits a FULFILLMENT_UPDATE webhook event containing details of the Supplier's newly created fulfillment record.

A successful creation returns 201 Created with the details of the Supplier's fulfillment record (FulfillmentSerializer).

Authorizations:
(platformAppIdplatformAppToken)
Request Body schema:
required
name
required
string
service
required
string
shipment_status
required
string (ShipmentStatusEnum)
Enum: "label_printed" "label_purchased" "attempted_delivery" "ready_for_pickup" "confirmed" "in_transit" "out_for_delivery" "delivered" "failure"
  • label_printed - label_printed
  • label_purchased - label_purchased
  • attempted_delivery - attempted_delivery
  • ready_for_pickup - ready_for_pickup
  • confirmed - confirmed
  • in_transit - in_transit
  • out_for_delivery - out_for_delivery
  • delivered - delivered
  • failure - failure
status
required
string (Status406Enum)
Enum: "pending" "open" "success" "cancelled" "error" "failure"
  • pending - pending
  • open - open
  • success - success
  • cancelled - cancelled
  • error - error
  • failure - failure
tracking_company
string or null
tracking_numbers
Array of strings or null
tracking_urls
Array of strings or null
order_id
required
string <uuid>
required
Array of objects (LineItem)

Responses

Request samples

Content type
{
  • "name": "string",
  • "service": "string",
  • "shipment_status": "label_printed",
  • "status": "pending",
  • "tracking_company": "string",
  • "tracking_numbers": [
    ],
  • "tracking_urls": [
    ],
  • "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
  • "line_items": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
  • "shop": {
    },
  • "line_items": [
    ],
  • "service": "string",
  • "shipment_status": "string",
  • "status": "string",
  • "tracking_company": "string",
  • "tracking_numbers": [
    ],
  • "tracking_urls": [
    ]
}

Retrieve a fulfillment

Retrieve the full details for a specific fulfillment record, identified by its Rokt Catalog ID (UUID) in the URL path.

Access is restricted to fulfillments associated with the authenticated store (request.shop). This means:

  • Storefronts can retrieve details of fulfillments created by their Suppliers for their orders.

  • Suppliers can retrieve details of fulfillments they created.

The response (FulfillmentSerializer) includes the fulfillment status (e.g., 'fulfilled', 'cancelled'), optional tracking_company, optional tracking_numbers, optional tracking_urls, the list of line_items included in this fulfillment (with quantities), and relevant timestamps.

If the fulfillment ID is invalid or not associated with an order linked to your store, a 404 Not Found error is returned.

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
  • "shop": {
    },
  • "line_items": [
    ],
  • "service": "string",
  • "shipment_status": "string",
  • "status": "string",
  • "tracking_company": "string",
  • "tracking_numbers": [
    ],
  • "tracking_urls": [
    ]
}

Update a fulfillment

[Supplier Only] Update an existing fulfillment record created by your Supplier account. Identify the fulfillment by its Rokt Catalog ID (UUID) in the URL path.

The request body (UpdateFulfillmentSerializer) should contain the fields to update, such as tracking_company, tracking_numbers, and/or tracking_urls for physical shipments. Tracking fields are optional and can be omitted for digital/email fulfillments with no shipment. Partial updates are allowed (only include the fields you want to change).

Process:

  1. Update Supplier Fulfillment: Updates the specified fields on the Supplier's fulfillment record in Catalog.

  2. Sync to Storefront: Triggers a synchronization process. This attempts to update the corresponding fulfillment record on the original Storefront's order (e.g., via Shopify API) with the new tracking information when present.

  3. Webhook: Emits a FULFILLMENT_UPDATE webhook event containing details of the Supplier's updated fulfillment record. If the sync to the Storefront also resulted in an update to the Storefront's fulfillment record in Catalog, a separate FULFILLMENT_UPDATE event for the Storefront's fulfillment might also be emitted (depending on the sync logic).

A successful update returns 200 OK with the updated details of the Supplier's fulfillment record (FulfillmentSerializer).

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string
Request Body schema:
required
name
required
string
service
required
string
shipment_status
required
string (ShipmentStatusEnum)
Enum: "label_printed" "label_purchased" "attempted_delivery" "ready_for_pickup" "confirmed" "in_transit" "out_for_delivery" "delivered" "failure"
  • label_printed - label_printed
  • label_purchased - label_purchased
  • attempted_delivery - attempted_delivery
  • ready_for_pickup - ready_for_pickup
  • confirmed - confirmed
  • in_transit - in_transit
  • out_for_delivery - out_for_delivery
  • delivered - delivered
  • failure - failure
status
required
string (Status406Enum)
Enum: "pending" "open" "success" "cancelled" "error" "failure"
  • pending - pending
  • open - open
  • success - success
  • cancelled - cancelled
  • error - error
  • failure - failure
tracking_company
string or null
tracking_numbers
Array of strings or null
tracking_urls
Array of strings or null

Responses

Request samples

Content type
{
  • "name": "string",
  • "service": "string",
  • "shipment_status": "label_printed",
  • "status": "pending",
  • "tracking_company": "string",
  • "tracking_numbers": [
    ],
  • "tracking_urls": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
  • "shop": {
    },
  • "line_items": [
    ],
  • "service": "string",
  • "shipment_status": "string",
  • "status": "string",
  • "tracking_company": "string",
  • "tracking_numbers": [
    ],
  • "tracking_urls": [
    ]
}

Partially update a fulfillment

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string
Request Body schema:
name
string <= 255 characters
order_id
string <uuid>
object (Shop)
Array of objects (LineItemRead)
service
string or null <= 258 characters
shipment_status
string or null <= 32 characters
status
string or null <= 32 characters
tracking_company
string or null <= 257 characters
tracking_numbers
Array of strings or null[ items <= 128 characters ]
tracking_urls
Array of strings or null[ items <= 256 characters ]

Responses

Request samples

Content type
{
  • "name": "string",
  • "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
  • "shop": {
    },
  • "line_items": [
    ],
  • "service": "string",
  • "shipment_status": "string",
  • "status": "string",
  • "tracking_company": "string",
  • "tracking_numbers": [
    ],
  • "tracking_urls": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
  • "shop": {
    },
  • "line_items": [
    ],
  • "service": "string",
  • "shipment_status": "string",
  • "status": "string",
  • "tracking_company": "string",
  • "tracking_numbers": [
    ],
  • "tracking_urls": [
    ]
}

Refunds

The Refunds endpoints allow the Partner to initiate refunds for Brand products that were bought through the Partner storefront. Brands can also create refunds for orders they received, and both roles can list and retrieve refunds.

List refunds

Retrieve a paginated list of refund records associated with the authenticated store, reflecting its role in the order process.

  • If called by a Storefront: Returns refund records linked to orders originating from the Storefront. This includes refunds initiated by the Storefront and refunds initiated by connected Suppliers for those orders.

  • If called by a Supplier: Returns refund records linked to orders received by the Supplier from connected Storefronts. This includes refunds initiated by the Supplier and refunds initiated by the originating Storefronts for those orders.

The response (RefundSerializer, paginated) includes details for each refund, such as the calculated total_refunded_amount, currency, the list of refund_line_items (with quantities and amounts), associated order_id, and timestamps.

Pagination is cursor-based (PlatformPagination). Ordering is available on created_at and updated_at, defaulting to -created_at.

Authorizations:
(platformAppIdplatformAppToken)
query Parameters
ordering
string

Which field to use when ordering the results.

cursor
string

The pagination cursor value.

Responses

Response samples

Content type
application/json
{
  • "next": "http://api.example.org/accounts/?cursor=cD00ODY%3D",
  • "previous": "http://api.example.org/accounts/?cursor=cj0xJnA9NDg3",
  • "results": [
    ]
}

Create a refund

Initiate a refund for specific quantities of line items within a Rokt Catalog order. This endpoint handles refund requests originating from both Storefronts and Suppliers.

Request Body (RefundCreateSerializer):

  • order_id (UUID, required): The Catalog ID of the order to be refunded.

  • line_items (list, required): A list of objects, each specifying:

    • id (UUID, required): The Catalog ID of the line item to refund.

    • quantity (integer, required): The quantity of this line item to refund.

  • should_refund_shipping (boolean, optional, Storefront only): If true, attempts to refund the original shipping cost associated with the Storefront order.

  • extra_amount (decimal string, optional, restricted use): Allows refunding an additional amount beyond line items/shipping (currently restricted to specific approved shops).

Process & Permissions:

  1. Identify Initiator: Determines if the request comes from the Storefront or the Supplier by checking the order's relationships.

  2. Lock Order: Acquires a lock on the order record to prevent concurrent modifications.

  3. Validate Quantities: Checks if the requested quantity for each line item exceeds the currently refundable quantity (original quantity minus previously refunded quantity). If validation fails, returns 400 Bad Request with error_code: ITEMS_ALREADY_REFUNDED and details of affected items.

  4. Storefront-Initiated Refund:

    • Permission Check: Verifies the Storefront has the required scope (write_sk_refunds). Returns 403 Forbidden if missing.

    • Dispatch: Calculates refund amounts, creates the refund record for the Storefront in Catalog, and asynchronously triggers tasks to create corresponding refund records on the connected Supplier(s)' systems (e.g., via Shopify API).

    • Error Handling: If downstream Supplier refund creation fails, returns 400 Bad Request with error_code: SUPPLIER_REFUND_FAILED.

  5. Supplier-Initiated Refund:

    • Permission Check: Implicitly requires the write_refunds scope.

    • Create Supplier Refund: Creates the refund record for the Supplier in Catalog.

    • Dispatch to Storefront: If the Supplier order originated from a Storefront with integration settings, synchronously attempts to create a corresponding refund record on the Storefront's order in Catalog.

    • Error Handling: If downstream Storefront refund creation fails, returns 400 Bad Request with error_code: SK_REFUND_FAILED.

  6. Extra Amount: If extra_amount is provided and valid, creates an associated record (restricted use).

Response: On success, returns 201 Created with the details of the primary refund record created (either the Storefront's or the Supplier's) using RefundSerializer. The serializer might include details about failed downstream refunds in the failed_to_create_refund_line_items field for Storefront-initiated refunds.

Authorizations:
(platformAppIdplatformAppToken)
Request Body schema:
required
order_id
required
string <uuid>
required
Array of objects (LineItem)
should_refund_shipping
boolean
extra_amount
string <decimal> ^-?\d{0,8}(?:\.\d{0,4})?$

Only available to select retailers.

Responses

Request samples

Content type
{
  • "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
  • "line_items": [
    ],
  • "should_refund_shipping": true,
  • "extra_amount": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "order_id": "string",
  • "amount": {
    },
  • "note": "string",
  • "duties": null,
  • "restock": true,
  • "processed_at": "2019-08-24T14:15:22Z",
  • "refund_line_items": [
    ],
  • "shipping_refund_amount": "string",
  • "failed_to_create_refund_line_items": "string"
}

Retrieve a refund

Retrieve the full details for a specific refund record, identified by its Rokt Catalog ID (UUID) in the URL path.

Access is restricted to refunds associated with orders linked to the authenticated store (request.shop).

The response (RefundSerializer) includes the total_refunded_amount, currency, the list of refund_line_items (specifying the exact items, quantities, and subtotal refunded), the associated order_id, note (if any), processed_at timestamp, and other relevant details.

If the refund ID is invalid or the refund is not associated with an order linked to your store, a 404 Not Found error is returned.

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "order_id": "string",
  • "amount": {
    },
  • "note": "string",
  • "duties": null,
  • "restock": true,
  • "processed_at": "2019-08-24T14:15:22Z",
  • "refund_line_items": [
    ],
  • "shipping_refund_amount": "string",
  • "failed_to_create_refund_line_items": "string"
}

Returns

Partners create return requests for items purchased in a Rokt Catalog order and add tracking for the return shipment; Brands review the return requests they receive and close them once the returned items have been processed. Closing a return does not create a refund: use the Refunds endpoints for that.

List returns

Retrieve a paginated list of return requests associated with the authenticated store, reflecting its role.

  • If called by a Storefront: Returns ReturnRequest records initiated by this Storefront for orders placed on their platform.

  • If called by a Supplier: Returns ReturnRequest records received from connected Storefronts for orders the Supplier fulfilled.

Filtering: You can filter the list by status using a query parameter (e.g., ?status=OPEN or ?status=CLOSED).

Response (ReturnSerializer, paginated): Includes details for each return request: id, name, rma, associated order_id, status ('OPEN' or 'CLOSED'), return_line_items (with quantities, reasons), reverse_deliveries (tracking info), and timestamps.

Pagination is cursor-based (PlatformPagination). Ordering is available on created_at and updated_at, defaulting to -created_at.

Authorizations:
(platformAppIdplatformAppToken)
query Parameters
ordering
string

Which field to use when ordering the results.

cursor
string

The pagination cursor value.

status
string
Enum: "closed" "open"

Filter returns by status

Responses

Response samples

Content type
application/json
{
  • "next": "http://api.example.org/accounts/?cursor=cD00ODY%3D",
  • "previous": "http://api.example.org/accounts/?cursor=cj0xJnA9NDg3",
  • "results": [
    ]
}

Create a return

[Storefront Only] Initiate a return process for items purchased in a Rokt Catalog-facilitated order.

Request Body (ReturnCreateSerializer):

  • order_id (UUID, required): The Catalog ID of the original Storefront order containing the items to be returned.

  • name (string, required): A unique identifier for this return request (e.g., your system's RMA number).

  • rma (string, optional): An alternative return merchandise authorization identifier.

  • return_line_items (list, required): A list of objects, each specifying:

    • line_item_id (UUID, required): The Catalog ID of the Storefront's line item record to be returned.

    • quantity (integer, required): The quantity of this line item being returned.

    • return_reason (string, optional): A code or description for the return reason.

    • customer_note (string, optional): Any notes provided by the customer.

  • reverse_deliveries (list, optional): Allows providing initial return shipping tracking information (see ReverseDeliveryCreateSerializer) within the same request.

Process:

  1. Validation: Checks if the order and line items exist, belong to the Storefront, and if the requested return quantities are valid (e.g., not exceeding fulfilled quantity). Acquires a lock on the order.

  2. Create Storefront Return Request: Creates the primary return request record associated with the Storefront's order in Rokt Catalog.

  3. Create Initial Tracking (Optional): If reverse_deliveries are provided, creates associated return tracking records.

  4. Dispatch to Suppliers (Async): Triggers an asynchronous task to create corresponding return request records for each relevant Supplier involved in the returned line items. These Supplier return requests are linked back to the Storefront's request.

Error Handling: Returns 400 Bad Request for validation errors (e.g., invalid quantity, bad IDs). Returns 500 Internal Server Error for unexpected issues.

Response: On success, returns 201 Created with the details of the newly created Storefront return request (ReturnSerializer).

Authorizations:
(platformAppIdplatformAppToken)
Request Body schema:
required
order_id
required
string <uuid>
required
Array of objects (CreateReturnLineItem)
required
object (ReverseDeliveryCreate)
name
string or null
rma
string

Responses

Request samples

Content type
{
  • "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
  • "return_line_items": [
    ],
  • "tracking": {},
  • "name": "string",
  • "rma": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "order": "93b532b3-a125-4cd2-9b71-9996b1e164ce",
  • "return_line_items": [
    ],
  • "status": "canceled",
  • "name": "string",
  • "total_return_line_items": -32768,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "tracking": [
    ],
  • "rma": "string"
}

Retrieve a return

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "order": "93b532b3-a125-4cd2-9b71-9996b1e164ce",
  • "return_line_items": [
    ],
  • "status": "canceled",
  • "name": "string",
  • "total_return_line_items": -32768,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "tracking": [
    ],
  • "rma": "string"
}

Close a return

[Supplier Only] Mark a return request that your Supplier account received from a Storefront as 'CLOSED'.

Identify the return request by its Rokt Catalog ID (UUID) provided in the URL path.

Use Case: This endpoint should typically be called by the Supplier once they have received the physical returned items from the customer/Storefront and completed their internal processing (inspection, restocking, etc.).

Action: Sets the status field of the Supplier's return request record in Catalog to CLOSED.

Important Limitation: This action only updates the status of the Supplier's return record. It does not automatically update the status of the original Storefront's return request, nor does it trigger any notifications or refunds. Subsequent actions, such as initiating a refund using the /refunds/ endpoint, might be required based on the agreed return policy and workflow.

Permissions: Requires the request to be authenticated as the Supplier associated with the return request. Attempting to close a return belonging to another shop results in 403 Forbidden.

A successful update returns 200 OK with the updated details of the Supplier's return request (ReturnSerializer), showing the status as 'CLOSED'.

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string
Request Body schema:
required
order
required
string <uuid>
required
Array of objects (ReturnLineItem)
status
string (Status602Enum)
Enum: "canceled" "closed" "declined" "open" "requested"
  • canceled - canceled
  • closed - closed
  • declined - declined
  • open - open
  • requested - requested
name
string or null <= 501 characters
total_return_line_items
required
integer [ -32768 .. 32767 ]

The sum of all return line item quantities for the return.

required
Array of objects (ReverseDelivery)
rma
string or null <= 501 characters

"Return merchandise authorization" -- used as reference number for SK to SUP comms

Responses

Request samples

Content type
{
  • "order": "93b532b3-a125-4cd2-9b71-9996b1e164ce",
  • "return_line_items": [
    ],
  • "status": "canceled",
  • "name": "string",
  • "total_return_line_items": -32768,
  • "tracking": [],
  • "rma": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "order": "93b532b3-a125-4cd2-9b71-9996b1e164ce",
  • "return_line_items": [
    ],
  • "status": "canceled",
  • "name": "string",
  • "total_return_line_items": -32768,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "tracking": [
    ],
  • "rma": "string"
}

Update return tracking

[Storefront Only] Add or update the tracking information for the shipment returning items back to the Supplier(s). Identify the specific return request using its Rokt Catalog ID (UUID) in the URL path.

Request Body (ReverseDeliveryCreateSerializer):

  • carrier_name (string, optional): Name of the shipping carrier (e.g., 'USPS', 'FedEx').

  • tracking_number (string, optional): The tracking number for the return shipment.

  • tracking_url (string, optional): A direct URL to track the shipment.

  • shipping_label_file_url (string, optional): URL to a downloadable shipping label file (e.g., PDF).

  • shipping_label_created_at (datetime string, optional): Timestamp when the label was created.

Process:

  1. Validation: Checks if the return request exists and belongs to the Storefront.

  2. Create Storefront Return Tracking: Creates a return tracking record containing the provided tracking/label info and associates it with the Storefront's return request.

  3. Sync to Suppliers (Sync): This synchronously attempts to add the same return tracking information to the corresponding return request records on the Supplier side(s).

Response: Returns 200 OK with the updated details of the Storefront's return request (ReturnSerializer), now including the added return tracking information.

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string
query Parameters
ordering
string

Which field to use when ordering the results.

cursor
string

The pagination cursor value.

Request Body schema:
carrier_name
string or null <= 100 characters
tracking_number
string or null <= 100 characters
tracking_url
string or null <uri> <= 200 characters
shipping_label_file_url
string or null <uri> <= 1279 characters

Responses

Request samples

Content type
{}

Response samples

Content type
application/json
{
  • "next": "http://api.example.org/accounts/?cursor=cD00ODY%3D",
  • "previous": "http://api.example.org/accounts/?cursor=cj0xJnA9NDg3",
  • "results": [
    ]
}

Webhooks

Register and manage webhook subscriptions so Rokt Catalog can notify your application when products, orders, and fulfillments change. See the Webhooks guide for the available topics, payloads, and delivery behavior.

List webhooks

Retrieve a paginated list of all webhook subscriptions currently registered and active for the authenticated application (identified by the API credentials used in the request).

The response (RegisteredWebhookSerializer, paginated) includes the unique Rokt Catalog ID (UUID), the subscribed topic, and the target address (URL) for each registered webhook.

Results are returned using cursor-based pagination (PlatformPagination).

Authorizations:
(platformAppIdplatformAppToken)
query Parameters
cursor
string

The pagination cursor value.

Responses

Response samples

Content type
application/json
{}

Create a webhook

Register a new endpoint URL to receive notifications (webhooks) from Rokt Catalog when specific events occur related to your store.

The request body (CreateUpdateWebhookSerializer) requires:

topic: A string representing the event type you want to subscribe to (e.g., product/update, order/cancel, fulfillment/update). See Catalog documentation for the full list of available topics.

address: The HTTPS URL of your application's endpoint that will receive the webhook POST requests from Catalog.

Process: Catalog validates the topic and creates a webhook subscription record associated with your application's integration settings. When an event matching the topic occurs for a resource linked to your store (e.g., an order associated with your shop is cancelled), Catalog will send an HTTP POST request containing the relevant event payload (JSON format) to the registered address.

A successful registration returns 201 Created with the details of the new subscription (RegisteredWebhookSerializer), including its unique Catalog ID (UUID).

Authorizations:
(platformAppIdplatformAppToken)
Request Body schema:
required
topic
required
string
address
required
string

Responses

Request samples

Content type
{
  • "topic": "string",
  • "address": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "topic": "order/create",
  • "address": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z"
}

Retrieve a webhook

Retrieve the details for a single, specific webhook subscription, identified by its Rokt Catalog ID (UUID) provided in the URL path.

Access is restricted to subscriptions belonging to the authenticated application.

The response (RegisteredWebhookSerializer) includes the id, topic, and address.

If the provided ID is invalid or does not correspond to a webhook registered by your application, a 404 Not Found error is returned.

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "topic": "order/create",
  • "address": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z"
}

Update a webhook

Update the configuration of an existing webhook subscription. Identify the subscription by its Rokt Catalog ID (UUID) in the URL path.

The request body (CreateUpdateWebhookSerializer) can include the new topic and/or address you want to set. Partial updates are allowed (only include the fields you want to change).

Validation: If provided, the topic must be one of the valid WEBHOOK_TOPICS.

A successful update returns 200 OK with the complete, updated details of the webhook subscription (RegisteredWebhookSerializer).

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string
Request Body schema:
required
topic
required
string
address
required
string

Responses

Request samples

Content type
{
  • "topic": "string",
  • "address": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "topic": "order/create",
  • "address": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z"
}

Partially update a webhook

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string
Request Body schema:
topic
string (TopicEnum)
Enum: "order/create" "order/update" "order/cancel" "product/create" "product/update" "fulfillment/create" "fulfillment/update"
  • order/create - order/create
  • order/update - order/update
  • order/cancel - order/cancel
  • product/create - product/create
  • product/update - product/update
  • fulfillment/create - fulfillment/create
  • fulfillment/update - fulfillment/update
address
string <= 512 characters

Responses

Request samples

Content type
{
  • "topic": "order/create",
  • "address": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "topic": "order/create",
  • "address": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z"
}

Delete a webhook

Permanently remove an existing webhook subscription, identified by its Rokt Catalog ID (UUID) in the URL path.

Access is restricted to subscriptions belonging to the authenticated application.

Once deleted, Catalog will immediately stop sending notifications for the associated topic to the registered address.

Warning: This action is irreversible. To resume receiving notifications, you must create a new subscription.

A successful deletion returns an HTTP 200 OK status with an empty response body.

Authorizations:
(platformAppIdplatformAppToken)
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "detail": null
}

CSV

CSV downloads: the product import template, and line-item exports for Partners and Brands. These endpoints back the upload and export flows in the Rokt Catalog app and expect a signed-in app session; use the Products and Variants endpoints with the API headers for programmatic catalog changes.

Download Partner line items CSV

Backs the corresponding flow in the Rokt Catalog app and expects a signed-in app session; the API headers alone do not authenticate this operation.

Authorizations:
(platformAppIdplatformAppToken)

Responses

Download unfulfilled Brand line items CSV

Backs the corresponding flow in the Rokt Catalog app and expects a signed-in app session; the API headers alone do not authenticate this operation.

Authorizations:
(platformAppIdplatformAppToken)

Responses

Download the product CSV template

Backs the corresponding flow in the Rokt Catalog app and expects a signed-in app session; the API headers alone do not authenticate this operation.

Authorizations:
(platformAppIdplatformAppToken)

Responses