Catalog API

Overview

The Rokt Catalog API is the REST API that Brands and Partners use to integrate with Rokt Catalog: Brands publish the products they make available to Partners, and Partners sell those products from their own storefront, create connected orders, calculate shipping and tax, and track fulfillments, refunds, and returns.

All requests are made to the Production base URL:

https://api.shopcanal.com/platform

Every endpoint, request body, and response schema is documented in the interactive API reference. This page explains how to authenticate, which resources each integration uses, and what each resource is for. For the step-by-step integration guides, see Rokt Catalog integration guides.

Authentication

Required Credentials

The Rokt Catalog API uses a combination of an Application ID and API Access Token to authenticate requests. For all REST Admin API requests, you need to include the following as headers in the requests:

• x-canal-app-id: Application ID
• x-canal-app-token: API Access Token

Obtaining App ID and API Token

Your Application ID and API Access Token are both automatically generated for you when your account is created. You can find these values in the Developer tab in Settings under API Credentials after you log into your account in the Rokt Catalog App.

See the Authentication guide for the same steps in the integration guides.

Environments

The Rokt Catalog API operates in a single environment: Production. For partners integrating with Catalog, both initial setup and testing are performed within the Production environment. To safely test your integration without affecting your live data or operations, you use designated test brand accounts provided by Catalog. This allows you to develop and test using real API endpoints and functionality while ensuring your testing activities do not impact live brands or orders.

To keep your test activities separate from your main account, we recommend using a separate login for testing purposes (e.g., partner+dev@example.com).

Using the Production Environment for Testing

• API Endpoint: All API calls are made to the Production endpoint: https://api.shopcanal.com.
• Test Brands: During testing, you are connected only to Catalog's designated test brands.
• Test Orders: Any orders placed with test brands are for testing purposes only and do not result in actual transactions or fulfillments.
• Test Payment Methods: Use test payment methods as directed by Catalog to prevent real monetary transactions during testing.

Getting Started with Testing

1. Create a Test Partner Account: Sign up for a separate partner account using a unique email address (e.g., partner+dev@example.com). This account is used solely for development and testing purposes.
2. Obtain Your API Token: In your test partner account, navigate to Settings under API Credentials to find your API Token.
3. Access Test Products: After logging into your test partner account, you have access to pre-approved test products from Catalog's designated test brands. These products can be used to test your API implementation. If you don't see them in your test account, ask your Rokt Catalog rep and they add them for you.
4. Begin Integration: Use the API Token from your test partner account to authenticate your API calls. All API requests should be directed to the Production endpoint: https://api.shopcanal.com.

warning

• Keep test and live data separate: Use the test partner account for all development and testing activities to prevent unintended interactions with your live account.
• Avoid real transactions: During testing, use only the test brands and test payment methods provided. Do not place real orders or conduct live transactions.

Moving to Live Operations

Once you have completed your integration and testing, and are ready to go live:

1. Switch to Your Live Partner Account: Begin using your main partner account for all live operations.
2. Update API Credentials: Obtain the API Token from your live partner account's Settings under API Credentials. Replace any test credentials in your integration with your live credentials.
3. Connect with Live Brands: Start connecting with real brands and products for your marketplace.
4. Perform Final Checks: Ensure that all aspects of your integration are functioning correctly in the live environment, including product listings, ordering, payment processing, and fulfillment.

Questions and Support

If you have any questions or need assistance during setup or testing, please reach out to the Rokt Catalog support team. The Environments guide covers the same material in the integration guides.

Brand integrations

Browse Rokt Catalog API resources for Brand integrations. Brand maps to Supplier in the current endpoint docs.

Use this section to find the Rokt Catalog API resources your Brand integration uses.

Products

Create, update, and manage the products you make available to partners.

• Products overview
• Create a product
• Update a product
• Delete a product
• Reorder product variants

Variants

Add, update, list, and remove variants for your products.

• Variants overview
• Create a variant
• List variants
• Retrieve a variant
• Update a variant
• Delete a variant

Fulfillments

Create and track shipment records for connected orders.

• Fulfillments overview
• Create a fulfillment
• List fulfillments
• Retrieve a fulfillment
• Update a fulfillment

Refunds

Create and review refunds for connected orders.

• Refunds overview
• Create a refund
• List refunds
• Retrieve a refund

Returns

Review return requests from partners, track existing returns, and close them when processing is complete.

• Returns overview
• List returns
• Retrieve a return
• Close a return

Webhooks

Register and manage webhook subscriptions for your app.

• Webhooks overview
• Create a webhook
• List webhooks
• Retrieve a webhook
• Update a webhook

CSV and Markets

The CSV template, CSV export and market price import 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.

• CSV overview
• Markets overview

Partner integrations

Browse Rokt Catalog API resources for Partner integrations. Partner maps to Storefront in the current endpoint docs.

Use this section to find the Rokt Catalog API resources your Partner integration uses.

Orders

Create, list, retrieve, and cancel connected orders from your partner storefront.

• Orders overview
• Create an order
• Create or get an order
• List orders
• Retrieve an order
• Cancel an order
• Initialize an order

Products

Browse brand products you can sell and retrieve product details for your partner storefront.

• Products overview
• List products
• Retrieve a product

Shops

View and manage your brand connections.

• Shops overview
• Create shop connections
• List shops
• Retrieve a shop

Shipping rates

Calculate shipping options, estimate checkout costs, and calculate tax.

• Shipping rates overview
• Calculate shipping rates
• Estimate max shipping rates
• Calculate tax

Fulfillments

Track shipment records created for your connected orders.

• Fulfillments overview
• List fulfillments
• Retrieve a fulfillment

Refunds

Create and review refunds for connected orders.

• Refunds overview
• Create a refund
• List refunds
• Retrieve a refund

Returns

Create return requests, review existing returns, and manage return tracking.

• Returns overview
• List returns
• Retrieve a return
• Create a return
• Update return tracking

Webhooks

Register and manage webhook subscriptions for your app.

• Webhooks overview
• Create a webhook
• List webhooks
• Retrieve a webhook
• Update a webhook

Resources

Products

The Products endpoints allow you to access all the products that you have permission to sell on your Partner storefront. To get permission to sell specific products, please visit the Rokt Catalog App and send proposals to Brands. Once the Brands approve the proposals, the products are available through these endpoints.

Orders

The Orders endpoints allow you to access all the orders containing Brand products that have been 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"
    }
  }'

Fulfillments

The Fulfillments endpoints allow you to access all the latest shipping information for Rokt Catalog Brand orders placed through your Partner storefront. Note: only Rokt Catalog Brand products should appear in these fulfillments.

Refunds

The Refunds endpoints allow the Partner to initiate refunds for Rokt Catalog Brand products that were bought through the Partner storefront.

Shipping rates

The Shipping Rates endpoints allow the Partner to determine how much they should charge for shipping for Rokt Catalog Brand products that are bought through the Partner storefront. Rokt Catalog charges the Partner this amount for shipping and sends it to the Brand. The response contains a single aggregated entry in shipping_rates (code canal-shipping) whose price is the sum of each Brand's shipping charge for its items; the entry is present even when a Brand cannot ship to the destination.

Webhooks

Please see our Webhooks Guide for more details.

Pagination

List endpoints return cursor-based pages. Each list response carries a results array plus next and previous URLs (null when there is no further page); pass the cursor query parameter from those URLs to fetch the adjacent page. The Products, Variants, Orders, Fulfillments, Refunds, and Returns list endpoints also accept an ordering query parameter. Products order by created_at, updated_at, or title; Variants by created_at, updated_at, price, or compare_at_price; Orders, Fulfillments, Refunds, and Returns by created_at or updated_at. Prefix the field with - for descending order. The Shops and Webhooks list endpoints do not accept ordering.

Interactive API reference

The full request and response contract for every endpoint above, including schemas and example payloads, is in the Catalog API interactive reference.