# shopcanal Documentation > Rokt Catalog is a startup in the e-commerce space. Rokt Catalog is a dropship & marketplace platform that provides quality curation and strategic tools built to sell complementary 3rd party products, without additional inventory. Rokt Catalog helps power marketplaces, mini collections, product drops and more. There is a storefront side and supplier-side. Suppliers can list their products into Rokt Catalog's network, for them to be dropshipped to customers of Storefronts. (Storefronts are the ones who host the frontend on which the customer would buy the product, then Rokt Catalog forwards the order onto the Suppliers, who will ship the product straight to the customer) ## Guides - [Getting Started](https://docs.shopcanal.com/docs/getting-started.md) - [Environments](https://docs.shopcanal.com/docs/environments.md) - [Webhooks](https://docs.shopcanal.com/docs/webhooks-1.md) - [Partner Onboarding](https://docs.shopcanal.com/docs/retailer-onboarding.md) - [Brand Onboarding](https://docs.shopcanal.com/docs/supplier-onboarding.md) - [Engineering Checklist: Marketplace](https://docs.shopcanal.com/docs/supplier-engineering-checklist.md): Complete checklist for integrating with the Rokt Catalog Brand API, covering authentication, products, webhooks, fulfillments, and inventory sync. - [Shoppable Ads Supplier Integration Guide](https://docs.shopcanal.com/docs/shoppable-ads-supplier-integration-guide.md) - [Catalog Ingestion via API](https://docs.shopcanal.com/docs/catalog-ingestion.md) - [Calculating Tax & Shipping for Shoppable Ads](https://docs.shopcanal.com/docs/calculating-tax-shipping-for-shoppable-ads.md) - [Order Management](https://docs.shopcanal.com/docs/order-management.md) - [Back to Help Center](https://docs.shopcanal.com/docs/back-to-help-center.md) ## API Reference - [Brand](https://docs.shopcanal.com/reference/brand.md): Browse Canal API resources for Brand integrations. Brand maps to Supplier in the current endpoint docs. - [Partner](https://docs.shopcanal.com/reference/partner.md): Browse Canal API resources for Partner integrations. Partner maps to Storefront in the current endpoint docs. - [/csv/download_shopkeep_line_items/](https://docs.shopcanal.com/reference/csv_download_shopkeep_line_items_retrieve.md) - [/csv/download_unfulfilled_supplier_line_items/](https://docs.shopcanal.com/reference/csv_download_unfulfilled_supplier_line_items_retrieve.md) - [/csv/product/template/](https://docs.shopcanal.com/reference/csv_product_template_retrieve.md) - [fulfillments](https://docs.shopcanal.com/reference/fulfillments.md) - [/fulfillments/](https://docs.shopcanal.com/reference/fulfillments_list.md): 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, status, associated line items, and timestamps. Pagination is cursor-based (`PlatformPagination`). Ordering is available on `created_at` and `updated_at`, defaulting to `-created_at`. - [/fulfillments/](https://docs.shopcanal.com/reference/fulfillments_create.md): **[Supplier Only]** Create a fulfillment (shipment 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), tracking information (`tracking_company`, `tracking_number`, `tracking_url`), 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 in this specific shipment. **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), pushing the tracking information. 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`). - [/fulfillments/{id}/](https://docs.shopcanal.com/reference/fulfillments_retrieve.md): 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'), `tracking_company`, `tracking_number`(s), `tracking_url`(s), 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. - [/fulfillments/{id}/](https://docs.shopcanal.com/reference/fulfillments_update.md): **[Supplier Only]** Update the tracking information for 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: `tracking_company`, `tracking_number`, and/or `tracking_url`. 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. 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`). - [/fulfillments/{id}/](https://docs.shopcanal.com/reference/fulfillments_partial_update.md) - [/markets/prices/import/](https://docs.shopcanal.com/reference/markets_prices_import_create.md) - [/max-shipping-rates/](https://docs.shopcanal.com/reference/max_shipping_rates_create.md): **[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). - [orders](https://docs.shopcanal.com/reference/orders.md) - [/orders/](https://docs.shopcanal.com/reference/orders_list.md): **[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`. - [/orders/](https://docs.shopcanal.com/reference/orders_create.md): **[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`. - [/orders/{id}/](https://docs.shopcanal.com/reference/orders_retrieve.md): **[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. - [/orders/{id}/cancel/](https://docs.shopcanal.com/reference/orders_cancel_create.md): **[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. - [/orders/create_or_get/](https://docs.shopcanal.com/reference/orders_create_or_get_create.md): **[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. - [products](https://docs.shopcanal.com/reference/products.md) - [/products/](https://docs.shopcanal.com/reference/products_list.md): **[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`. - [/products/](https://docs.shopcanal.com/reference/products_create.md): **[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`. - [/products/{id}/](https://docs.shopcanal.com/reference/products_retrieve.md): **[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. - [/products/{id}/](https://docs.shopcanal.com/reference/products_update.md): **[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`. - [/products/{id}/](https://docs.shopcanal.com/reference/products_partial_update.md) - [/products/{id}/](https://docs.shopcanal.com/reference/products_destroy.md): **[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. - [/products/{id}/reorder_variants/](https://docs.shopcanal.com/reference/products_reorder_variants_create.md): **[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 `ID`s (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. - [/products/{id}/resync/](https://docs.shopcanal.com/reference/products_resync_create.md): 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. - [refunds](https://docs.shopcanal.com/reference/refunds.md) - [/refunds/](https://docs.shopcanal.com/reference/refunds_list.md): 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`. - [/refunds/](https://docs.shopcanal.com/reference/refunds_create.md): 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 shops like SHEIN). **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. - [/refunds/{id}/](https://docs.shopcanal.com/reference/refunds_retrieve.md): 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. - [shipping-rates](https://docs.shopcanal.com/reference/shipping-rates.md) - [/shipping-rates/](https://docs.shopcanal.com/reference/shipping_rates_create.md): **[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_id`s 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. - [/shops/](https://docs.shopcanal.com/reference/shops_list.md): **[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. - [/shops/](https://docs.shopcanal.com/reference/shops_create.md): **[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. - [/shops/{id}/](https://docs.shopcanal.com/reference/shops_retrieve.md): **[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. - [/variants/](https://docs.shopcanal.com/reference/variants_list.md): **[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`. - [/variants/](https://docs.shopcanal.com/reference/variants_create.md): **[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). - [/variants/{id}/](https://docs.shopcanal.com/reference/variants_retrieve.md): **[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. - [/variants/{id}/](https://docs.shopcanal.com/reference/variants_update.md): **[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. - [/variants/{id}/](https://docs.shopcanal.com/reference/variants_partial_update.md) - [/variants/{id}/](https://docs.shopcanal.com/reference/variants_destroy.md): **[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. - [webhooks](https://docs.shopcanal.com/reference/webhooks.md) - [/webhooks/](https://docs.shopcanal.com/reference/webhooks_list.md): 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`). - [/webhooks/](https://docs.shopcanal.com/reference/webhooks_create.md): 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). - [/webhooks/{id}/](https://docs.shopcanal.com/reference/webhooks_retrieve.md): 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. - [/webhooks/{id}/](https://docs.shopcanal.com/reference/webhooks_update.md): 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`). - [/webhooks/{id}/](https://docs.shopcanal.com/reference/webhooks_partial_update.md) - [/webhooks/{id}/](https://docs.shopcanal.com/reference/webhooks_destroy.md): 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. - [/returns/](https://docs.shopcanal.com/reference/returns_list.md): 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`. - [/returns/](https://docs.shopcanal.com/reference/returns_create.md): **[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`). - [/returns/{id}/](https://docs.shopcanal.com/reference/returns_retrieve.md) - [/returns/{id}/close/](https://docs.shopcanal.com/reference/returns_close_create.md): **[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'. - [/returns/{id}/update_tracking/](https://docs.shopcanal.com/reference/returns_update_tracking_create.md): **[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. - [/orders/v1/initialize-order/](https://docs.shopcanal.com/reference/orders_v1_initialize_order_create.md): **[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.