Canal variants API

openapi: 3.2.0
info:
  title: Rokt Catalog csv Variants API
  version: 1.0.1
  description: Integrate with Rokt Catalog
servers:
- url: https://api.shopcanal.com/platform
  description: Rokt Catalog Storefront Public API
tags:
- name: variants
paths:
  /variants/:
    get:
      operationId: variants_list
      description: '

        **[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`.


        '
      parameters:
      - name: ordering
        required: false
        in: query
        description: Which field to use when ordering the results.
        schema:
          type: string
      - name: cursor
        required: false
        in: query
        description: The pagination cursor value.
        schema:
          type: string
      tags:
      - variants
      security:
      - platformAppId: []
        platformAppToken: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedVariantList'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
    post:
      operationId: variants_create
      description: '

        **[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).


        '
      tags:
      - variants
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVariant'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreateVariant'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreateVariant'
        required: true
      security:
      - platformAppId: []
        platformAppToken: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
  /variants/{id}/:
    get:
      operationId: variants_retrieve
      description: '

        **[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.


        '
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
      tags:
      - variants
      security:
      - platformAppId: []
        platformAppToken: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Variant'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
    put:
      operationId: variants_update
      description: '

        **[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.


        '
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
      tags:
      - variants
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Variant'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Variant'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Variant'
        required: true
      security:
      - platformAppId: []
        platformAppToken: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
    patch:
      operationId: variants_partial_update
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
      tags:
      - variants
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedVariant'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PatchedVariant'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PatchedVariant'
      security:
      - platformAppId: []
        platformAppToken: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Variant'
          description: ''
    delete:
      operationId: variants_destroy
      description: '

        **[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.


        '
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
      tags:
      - variants
      security:
      - platformAppId: []
        platformAppToken: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
components:
  schemas:
    Shop:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        email:
          type:
          - string
          - 'null'
          readOnly: true
        phone:
          type:
          - string
          - 'null'
          maxLength: 128
        name:
          type: string
          maxLength: 129
        description:
          type:
          - string
          - 'null'
          maxLength: 6144
        myshopify_domain:
          type: string
          maxLength: 128
        province:
          type:
          - string
          - 'null'
          maxLength: 122
        country:
          type: string
          maxLength: 64
        domain:
          type:
          - string
          - 'null'
          maxLength: 128
        display_domain:
          type:
          - string
          - 'null'
          readOnly: true
        privacy_policy_url:
          type:
          - string
          - 'null'
          format: uri
          maxLength: 500
        terms_of_service_url:
          type:
          - string
          - 'null'
          format: uri
          maxLength: 500
      required:
      - country
      - display_domain
      - email
      - id
      - myshopify_domain
      - name
    Status2eaEnum:
      enum:
      - active
      - draft
      - archived
      - unlisted
      type: string
      description: '* `active` - active

        * `draft` - draft

        * `archived` - archived

        * `unlisted` - unlisted'
    Image:
      type: object
      properties:
        id:
          type: string
        position:
          type: integer
        src:
          type: string
          format: uri
        display_src:
          type:
          - string
          - 'null'
          format: uri
        width:
          type: integer
        height:
          type: integer
        canal_variant_ids:
          type: array
          items:
            type: string
          readOnly: true
        variant_ids:
          type: array
          items:
            type: string
        origin_supplier_image_id:
          type:
          - string
          - 'null'
          format: uuid
      required:
      - canal_variant_ids
      - src
    Product:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        shop:
          allOf:
          - $ref: '#/components/schemas/Shop'
          readOnly: true
        variants:
          type: array
          items:
            $ref: '#/components/schemas/Variant'
          readOnly: true
        body_html:
          type:
          - string
          - 'null'
          maxLength: 60000
        handle:
          type:
          - string
          - 'null'
          maxLength: 258
        image_src:
          type:
          - string
          - 'null'
          maxLength: 1043
        images:
          type: array
          items:
            $ref: '#/components/schemas/Image'
        options: {}
        product_type:
          type:
          - string
          - 'null'
          maxLength: 1044
        updated_at:
          type: string
          format: date-time
          readOnly: true
        published_at:
          type:
          - string
          - 'null'
          format: date-time
        status:
          $ref: '#/components/schemas/Status2eaEnum'
        title:
          type: string
          maxLength: 1029
        vendor:
          type:
          - string
          - 'null'
          maxLength: 227
        tags:
          type:
          - string
          - 'null'
          maxLength: 63750
        permalink:
          type:
          - string
          - 'null'
          format: uri
          maxLength: 2000
        number_of_reviews:
          type:
          - integer
          - 'null'
          maximum: 2147483647
          minimum: -2147483648
        star_rating:
          type:
          - number
          - 'null'
          format: double
      required:
      - id
      - shop
      - title
      - updated_at
      - variants
    Error:
      type: object
      properties:
        message:
          type: string
        detail: {}
    InventoryPolicyEnum:
      enum:
      - continue
      - deny
      type: string
      description: '* `continue` - continue

        * `deny` - deny'
    Variant:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        shop:
          allOf:
          - $ref: '#/components/schemas/Shop'
          readOnly: true
        inventory_policy:
          type:
          - string
          - 'null'
          maxLength: 123
        inventory_quantity:
          type:
          - integer
          - 'null'
          maximum: 2147483647
          minimum: -2147483648
        inventory_item_cost:
          type: number
          format: double
        option1:
          type:
          - string
          - 'null'
          maxLength: 255
        option2:
          type:
          - string
          - 'null'
          maxLength: 256
        option3:
          type:
          - string
          - 'null'
          maxLength: 257
        position:
          type: integer
          readOnly: true
        price:
          type: string
          format: decimal
          pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
          description: The price of the variant to be sold at.
        compare_at_price:
          type:
          - string
          - 'null'
          maxLength: 128
        origin_supplier_currency:
          type:
          - string
          - 'null'
          readOnly: true
        title:
          type: string
        sku:
          type:
          - string
          - 'null'
          readOnly: true
        upc:
          type:
          - string
          - 'null'
          maxLength: 253
        grams:
          type:
          - number
          - 'null'
          format: double
        weight:
          type:
          - number
          - 'null'
          format: double
        weight_unit:
          type:
          - string
          - 'null'
          maxLength: 3
        pause_selling:
          type: boolean
        origin_supplier_id:
          type:
          - string
          - 'null'
          readOnly: true
        origin_supplier_name:
          type:
          - string
          - 'null'
          readOnly: true
        available_for_ordering:
          type: boolean
          readOnly: true
        supplier_sku:
          type:
          - string
          - 'null'
          readOnly: true
        is_exclusive_offer:
          type: boolean
          description: An exclusive offer is a variant that is discounted lower than the variant's actual price on the supplier's website.
          readOnly: true
        sup_price:
          type:
          - string
          - 'null'
          description: The connected supplier variant's price, sourced from the supplier directly.
          readOnly: true
        sup_compare_at_price:
          type:
          - string
          - 'null'
          description: The connected supplier variant's compare-at price, sourced from the supplier directly.
          readOnly: true
      required:
      - available_for_ordering
      - id
      - is_exclusive_offer
      - origin_supplier_currency
      - origin_supplier_id
      - origin_supplier_name
      - position
      - price
      - shop
      - sku
      - sup_compare_at_price
      - sup_price
      - supplier_sku
      - title
    CreateVariant:
      type: object
      properties:
        title:
          type: string
        price:
          type: string
          format: decimal
          pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
          description: The price of the variant to be sold at.
        compare_at_price:
          type:
          - string
          - 'null'
          format: decimal
          pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
          description: 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:
          $ref: '#/components/schemas/InventoryPolicyEnum'
        inventory_quantity:
          type: integer
        option1:
          type: string
        option2:
          type: string
        option3:
          type: string
        sku:
          type: string
        position:
          type: integer
        image_src:
          type: string
        weight:
          type: number
          format: double
        weight_unit:
          type: string
        product_id:
          type: string
          format: uuid
      required:
      - inventory_policy
      - inventory_quantity
      - option1
      - price
      - product_id
    PatchedVariant:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        shop:
          allOf:
          - $ref: '#/components/schemas/Shop'
          readOnly: true
        inventory_policy:
          type:
          - string
          - 'null'
          maxLength: 123
        inventory_quantity:
          type:
          - integer
          - 'null'
          maximum: 2147483647
          minimum: -2147483648
        inventory_item_cost:
          type: number
          format: double
        option1:
          type:
          - string
          - 'null'
          maxLength: 255
        option2:
          type:
          - string
          - 'null'
          maxLength: 256
        option3:
          type:
          - string
          - 'null'
          maxLength: 257
        position:
          type: integer
          readOnly: true
        price:
          type: string
          format: decimal
          pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
          description: The price of the variant to be sold at.
        compare_at_price:
          type:
          - string
          - 'null'
          maxLength: 128
        origin_supplier_currency:
          type:
          - string
          - 'null'
          readOnly: true
        title:
          type: string
        sku:
          type:
          - string
          - 'null'
          readOnly: true
        upc:
          type:
          - string
          - 'null'
          maxLength: 253
        grams:
          type:
          - number
          - 'null'
          format: double
        weight:
          type:
          - number
          - 'null'
          format: double
        weight_unit:
          type:
          - string
          - 'null'
          maxLength: 3
        pause_selling:
          type: boolean
        origin_supplier_id:
          type:
          - string
          - 'null'
          readOnly: true
        origin_supplier_name:
          type:
          - string
          - 'null'
          readOnly: true
        available_for_ordering:
          type: boolean
          readOnly: true
        supplier_sku:
          type:
          - string
          - 'null'
          readOnly: true
        is_exclusive_offer:
          type: boolean
          description: An exclusive offer is a variant that is discounted lower than the variant's actual price on the supplier's website.
          readOnly: true
        sup_price:
          type:
          - string
          - 'null'
          description: The connected supplier variant's price, sourced from the supplier directly.
          readOnly: true
        sup_compare_at_price:
          type:
          - string
          - 'null'
          description: The connected supplier variant's compare-at price, sourced from the supplier directly.
          readOnly: true
    PaginatedVariantList:
      type: object
      required:
      - results
      properties:
        next:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?cursor=cD00ODY%3D"
        previous:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?cursor=cj0xJnA9NDg3
        results:
          type: array
          items:
            $ref: '#/components/schemas/Variant'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
    platformAppId:
      type: apiKey
      in: header
      name: X-CANAL-APP-ID
    platformAppToken:
      type: apiKey
      in: header
      name: X-CANAL-APP-TOKEN