openapi: 3.0.1 info: title: Canto PIM bulk_products_catalogs variants API description: "\n[Canto APIs](https://api.canto.com) enable seamless synchronization between the PIM + DAM and external systems that rely on accurate, up-to-date product content. \nThe API outlined here provides programmatic access to Canto’s Product Hub (PIM). The Product Hub API allows authorized systems to create, retrieve, update, and manage rich product data for use across digital channels, e-commerce platforms, and other target or source systems. \n \nKey Capabilities
\nThe Canto Product Hub API enables full product data management:\n1. Product Record Management: Create, read, update, and delete product entries including structured metadata, taxonomy, categories, and references.\n2. Attribute & Schema Configuration: Access and manage custom product attributes and classification structures\n3. Webhooks: Trigger updates or publish product datasets to downstream systems and integration pipelines.\n \nAPI Design\n- The PIM API adheres to RESTful principles, supporting standard HTTP methods (GET, POST, PUT, PATCH, DELETE).\n- JSON is the default payload format for both requests and responses.\n\nHTTP Status Code Conventions
\nBelow are general HTTP codes applicable across most endpoints:
\n- 200, 201, 204 – Successful operations (retrieval, creation, update, deletion).\n- 400 – Bad request. Input payloads did not conform to the expected schema or required parameters were missing.\n- 401 / 403 – Authentication or authorization failed.\n- 404 – The route or resource was not found.\n- 409 – Conflict in resource state (e.g., duplicate product identifier).\n- 429 - Too many requests. See Rate Limits below.\n- 500 – An unexpected server error occurred.\n- 502 / 503 / 504 – Infrastructure issues such as load balancer, service unavailability, or timeouts.\n\nAPI Rate Limits
\nRate limits are how many API calls you can make in a given time frame. If your call exceeds the pre-defined rate limit, you will run into a “429” http error-code. After which, you will need to wait until you can make another API call.\n\nPIM API Rate Limit: 5 requests/second\n" version: v1.0.1 servers: - url: https://{tenantSubdomain}.{region}/api/v1/pim/ variables: tenantSubdomain: default: demo region: enum: - canto.com - canto.global - canto.de - au.canto.com - ca.canto.com default: canto.com security: - bearerAuth: [] tags: - name: variants paths: /products/{product_id}/variants: get: tags: - variants summary: Get Product Variants description: ' List all product variants ' operationId: get_api_v1_products_product_id_variants parameters: - name: product_id in: path required: true schema: type: number responses: '200': description: Successfully fetched Product Variants headers: page-items: description: Number of items per page schema: type: integer link: description: Standard link header defined in RFC 8228. Contains links for first, last, next, and prev pages with respective `rel` attributes schema: type: string current-page: description: Current page number schema: type: integer total-count: description: Total number of items schema: type: integer total-pages: description: Total number of pages schema: type: integer content: '*/*': schema: required: - product_assets - variants type: object properties: variants: type: array description: Array of Product Variants items: type: object properties: id: type: integer description: Variant ID dimension_options: type: object properties: primary: type: object nullable: true properties: name: type: string description: Dimension name value: type: string description: Dimension value dimension_id: type: integer description: Dimension ID dimension_option_id: type: integer description: Dimension option ID secondary: type: object nullable: true properties: name: type: string description: Dimension name value: type: string description: Dimension value dimension_id: type: integer description: Dimension ID dimension_option_id: type: integer description: Dimension option ID tertiary: type: object nullable: true properties: name: type: string description: Dimension name value: type: string description: Dimension value dimension_id: type: integer description: Dimension ID dimension_option_id: type: integer description: Dimension option ID product_custom_attributes: type: array description: Array of product custom attributes items: type: object properties: name: type: string description: Attribute name value: type: string description: Attribute value data_type: type: string description: Data type of the attribute product_custom_attribute_id: type: integer description: Product custom attribute ID product_attribute_group_id: type: integer description: Product attribute group ID product_assets: type: array description: Array of product assets items: type: object properties: asset_id: type: string description: Asset ID product_ids: type: array description: Array of product IDs items: type: integer example: variants: - id: 1 dimension_options: primary: name: Size value: Small dimension_id: 1 dimension_option_id: 1 secondary: name: Color value: Red dimension_id: 2 dimension_option_id: 2 tertiary: null product_custom_attributes: - name: name value: Red Small Shirt data_type: text product_custom_attribute_id: 1 product_attribute_group_id: 1 - name: sku value: RS-S data_type: text product_custom_attribute_id: 2 product_attribute_group_id: 1 - id: 2 dimension_options: primary: name: Size value: Large dimension_id: 1 dimension_option_id: 3 secondary: name: Color value: Blue dimension_id: 2 dimension_option_id: 4 tertiary: null product_custom_attributes: - name: name value: Blue Large Shirt data_type: text product_custom_attribute_id: 3 product_attribute_group_id: 1 - name: sku value: BL-L data_type: text product_custom_attribute_id: 4 product_attribute_group_id: 1 product_assets: - asset_id: e29b41d4a7166655440000 product_ids: - 1 - 2 additionalProperties: false '401': description: User is not permitted to use the API or Authentication is invalid content: {} '500': description: Something went wrong content: {} post: tags: - variants summary: Create Product Variant description: ' Create a new product variant ' operationId: post_api_v1_products_product_id_variants parameters: - name: product_id in: path required: true schema: type: number requestBody: content: application/json: schema: required: - dimension_options[primary][dimension_option_id] type: object properties: dimension_options[primary][dimension_option_id]: type: number description: Primary Dimension Option ID dimension_options[primary][dimension_id]: type: number description: Primary Dimension ID (optional, will be inferred from dimension_option_id) dimension_options[secondary][dimension_id]: type: number description: Secondary Dimension ID (optional, will be inferred from dimension_option_id) dimension_options[secondary][dimension_option_id]: type: number description: Secondary Dimension Option ID dimension_options[tertiary][dimension_id]: type: number description: Tertiary Dimension ID (optional, will be inferred from dimension_option_id) dimension_options[tertiary][dimension_option_id]: type: number description: Tertiary Dimension Option ID product_custom_attributes: type: array description: Array of product attributes' data items: type: object properties: product_custom_attribute_id: type: string description: Attribute name value: type: string description: Attribute value multipart/form-data: schema: required: - dimension_options[primary][dimension_option_id] type: object properties: dimension_options[primary][dimension_option_id]: type: number description: Primary Dimension Option ID dimension_options[primary][dimension_id]: type: number description: Primary Dimension ID (optional, will be inferred from dimension_option_id) dimension_options[secondary][dimension_id]: type: number description: Secondary Dimension ID (optional, will be inferred from dimension_option_id) dimension_options[secondary][dimension_option_id]: type: number description: Secondary Dimension Option ID dimension_options[tertiary][dimension_id]: type: number description: Tertiary Dimension ID (optional, will be inferred from dimension_option_id) dimension_options[tertiary][dimension_option_id]: type: number description: Tertiary Dimension Option ID product_custom_attributes: type: array description: Array of product attributes' data items: type: string required: true responses: '200': description: Successfully created Product Variant content: '*/*': schema: required: - dimension_options - id - product_assets - product_custom_attributes type: object properties: id: type: integer description: Variant ID dimension_options: type: object properties: primary: type: object nullable: true properties: name: type: string description: Dimension name value: type: string description: Dimension value dimension_id: type: integer description: Dimension ID dimension_option_id: type: integer description: Dimension option ID secondary: type: object nullable: true properties: name: type: string description: Dimension name value: type: string description: Dimension value dimension_id: type: integer description: Dimension ID dimension_option_id: type: integer description: Dimension option ID tertiary: type: object nullable: true properties: name: type: string description: Dimension name value: type: string description: Dimension value dimension_id: type: integer description: Dimension ID dimension_option_id: type: integer description: Dimension option ID additionalProperties: false product_custom_attributes: type: array description: Array of product custom attributes items: type: object properties: name: type: string description: Attribute name value: type: string nullable: true description: Attribute value data_type: type: string description: Data type of the attribute (e.g. text, image) product_custom_attribute_id: type: integer description: Product custom attribute ID product_attribute_group_id: type: integer description: Product attribute group ID asset_ids: type: array description: Array of asset IDs (for image/asset type attributes) items: type: string product_assets: type: array description: Array of product assets items: type: object properties: asset_id: type: string description: Asset ID product_ids: type: array description: Array of product IDs items: type: integer example: id: 1 dimension_options: primary: name: Size value: Small dimension_id: 1 dimension_option_id: 1 secondary: name: Color value: Red dimension_id: 2 dimension_option_id: 2 tertiary: null product_custom_attributes: - name: name value: Red Small Shirt data_type: text product_custom_attribute_id: 1 product_attribute_group_id: 1 - name: sku value: RS-S data_type: text product_custom_attribute_id: 2 product_attribute_group_id: 1 - name: Description value: This is a red small shirt data_type: text product_custom_attribute_id: 3 product_attribute_group_id: 2 - name: An Image value: null data_type: image asset_ids: - abc123 - def234 product_custom_attribute_id: 4 product_attribute_group_id: 2 product_assets: - asset_id: e29b41d4a7166655440000 product_ids: - 1 - asset_id: f47ac10b58cc4372a5 product_ids: - 1 additionalProperties: false '400': description: The request parameters were invalid. References to `nil` means empty string or `null` value content: {} '401': description: User is not permitted to use the API or Authentication is invalid content: {} '422': description: Product Variant validation failed content: {} '500': description: Something went wrong content: {} /products/{product_id}/variants/{id}: get: tags: - variants summary: Get Product Variant description: ' Fetch details of a specific variant ' operationId: get_api_v1_products_product_id_variants_id parameters: - name: product_id in: path required: true schema: type: number - name: id in: path required: true schema: type: number responses: '200': description: 'Successfully fetched Product ' content: '*/*': schema: required: - dimension_options - id - product_assets - product_custom_attributes type: object properties: id: type: integer description: Variant ID dimension_options: type: object properties: primary: type: object nullable: true properties: name: type: string description: Dimension name value: type: string description: Dimension value dimension_id: type: integer description: Dimension ID dimension_option_id: type: integer description: Dimension option ID secondary: type: object nullable: true properties: name: type: string description: Dimension name value: type: string description: Dimension value dimension_id: type: integer description: Dimension ID dimension_option_id: type: integer description: Dimension option ID tertiary: type: object nullable: true properties: name: type: string description: Dimension name value: type: string description: Dimension value dimension_id: type: integer description: Dimension ID dimension_option_id: type: integer description: Dimension option ID additionalProperties: false product_custom_attributes: type: array description: Array of product custom attributes items: type: object properties: name: type: string description: Attribute name value: type: string nullable: true description: Attribute value data_type: type: string description: Data type of the attribute (e.g. text, image) product_custom_attribute_id: type: integer description: Product custom attribute ID product_attribute_group_id: type: integer description: Product attribute group ID asset_ids: type: array description: Array of asset IDs (for image/asset type attributes) items: type: string product_assets: type: array description: Array of product assets items: type: object properties: asset_id: type: string description: Asset ID product_ids: type: array description: Array of product IDs items: type: integer example: id: 1 dimension_options: primary: name: Size value: Small dimension_id: 1 dimension_option_id: 1 secondary: name: Color value: Red dimension_id: 2 dimension_option_id: 2 tertiary: null product_custom_attributes: - name: name value: Red Small Shirt data_type: text product_custom_attribute_id: 1 product_attribute_group_id: 1 - name: sku value: RS-S data_type: text product_custom_attribute_id: 2 product_attribute_group_id: 1 - name: Description value: This is a red small shirt data_type: text product_custom_attribute_id: 3 product_attribute_group_id: 2 - name: An Image value: null data_type: image asset_ids: - abc123 - def234 product_custom_attribute_id: 4 product_attribute_group_id: 2 product_assets: - asset_id: e29b41d4a7166655440000 product_ids: - 1 - asset_id: f47ac10b58cc4372a5 product_ids: - 1 additionalProperties: false '401': description: User is not permitted to use the API or Authentication is invalid content: {} '404': description: Product Variant ID not found or invalid content: {} '500': description: Something went wrong content: {} put: tags: - variants summary: Update Product Variant description: ' Update a product variant ' operationId: put_api_v1_products_product_id_variants_id parameters: - name: product_id in: path required: true schema: type: number - name: id in: path required: true schema: type: number requestBody: content: application/json: schema: required: - dimension_options[primary][dimension_option_id] type: object properties: dimension_options[primary][dimension_option_id]: type: number description: Primary Dimension Option ID dimension_options[primary][dimension_id]: type: number description: Primary Dimension ID (optional, will be inferred from dimension_option_id) dimension_options[secondary][dimension_id]: type: number description: Secondary Dimension ID (optional, will be inferred from dimension_option_id) dimension_options[secondary][dimension_option_id]: type: number description: Secondary Dimension Option ID dimension_options[tertiary][dimension_id]: type: number description: Tertiary Dimension ID (optional, will be inferred from dimension_option_id) dimension_options[tertiary][dimension_option_id]: type: number description: Tertiary Dimension Option ID product_custom_attributes: type: array description: Array of product attributes' data items: type: object properties: product_custom_attribute_id: type: number value: type: string data_type: type: string multipart/form-data: schema: required: - dimension_options[primary][dimension_option_id] type: object properties: dimension_options[primary][dimension_option_id]: type: number description: Primary Dimension Option ID dimension_options[primary][dimension_id]: type: number description: Primary Dimension ID (optional, will be inferred from dimension_option_id) dimension_options[secondary][dimension_id]: type: number description: Secondary Dimension ID (optional, will be inferred from dimension_option_id) dimension_options[secondary][dimension_option_id]: type: number description: Secondary Dimension Option ID dimension_options[tertiary][dimension_id]: type: number description: Tertiary Dimension ID (optional, will be inferred from dimension_option_id) dimension_options[tertiary][dimension_option_id]: type: number description: Tertiary Dimension Option ID product_custom_attributes: type: array description: Array of product attributes' data items: type: object properties: product_custom_attribute_id: type: number value: type: string data_type: type: string required: true responses: '200': description: Successfully updated Product Variant content: '*/*': schema: required: - dimension_options - id - product_assets - product_custom_attributes type: object properties: id: type: integer description: Variant ID dimension_options: type: object properties: primary: type: object nullable: true properties: name: type: string description: Dimension name value: type: string description: Dimension value dimension_id: type: integer description: Dimension ID dimension_option_id: type: integer description: Dimension option ID secondary: type: object nullable: true properties: name: type: string description: Dimension name value: type: string description: Dimension value dimension_id: type: integer description: Dimension ID dimension_option_id: type: integer description: Dimension option ID tertiary: type: object nullable: true properties: name: type: string description: Dimension name value: type: string description: Dimension value dimension_id: type: integer description: Dimension ID dimension_option_id: type: integer description: Dimension option ID additionalProperties: false product_custom_attributes: type: array description: Array of product custom attributes items: type: object properties: name: type: string description: Attribute name value: type: string nullable: true description: Attribute value data_type: type: string description: Data type of the attribute (e.g. text, image) product_custom_attribute_id: type: integer description: Product custom attribute ID product_attribute_group_id: type: integer description: Product attribute group ID asset_ids: type: array description: Array of asset IDs (for image/asset type attributes) items: type: string product_assets: type: array description: Array of product assets items: type: object properties: asset_id: type: string description: Asset ID product_ids: type: array description: Array of product IDs items: type: integer example: id: 1 dimension_options: primary: name: Size value: Small dimension_id: 1 dimension_option_id: 1 secondary: name: Color value: Red dimension_id: 2 dimension_option_id: 2 tertiary: null product_custom_attributes: - name: name value: Red Small Shirt data_type: text product_custom_attribute_id: 1 product_attribute_group_id: 1 - name: sku value: RS-S data_type: text product_custom_attribute_id: 2 product_attribute_group_id: 1 - name: Description value: This is a red small shirt data_type: text product_custom_attribute_id: 3 product_attribute_group_id: 2 - name: An Image value: null data_type: image asset_ids: - abc123 - def234 product_custom_attribute_id: 4 product_attribute_group_id: 2 product_assets: - asset_id: e29b41d4a7166655440000 product_ids: - 1 - asset_id: f47ac10b58cc4372a5 product_ids: - 1 additionalProperties: false '401': description: User is not permitted to use the API or Authentication is invalid content: {} '404': description: Product Variant ID not found or invalid content: {} '422': description: Product Variant validation failed content: {} '500': description: Something went wrong content: {} delete: tags: - variants summary: Delete Product Variant description: ' Remove a product variant ' operationId: delete_api_v1_products_product_id_variants_id parameters: - name: product_id in: path required: true schema: type: number - name: id in: path required: true schema: type: number responses: '204': description: Successfully Deleted Product Variant content: {} '401': description: User is not permitted to use the API or Authentication is invalid content: {} '404': description: Product Variant ID not found or invalid content: {} '500': description: Something went wrong content: {} patch: tags: - variants summary: Update Product Variant description: ' Update a product variant ' operationId: patch_api_v1_products_product_id_variants_id parameters: - name: product_id in: path required: true schema: type: number - name: id in: path required: true schema: type: number requestBody: content: application/json: schema: required: - dimension_options[primary][dimension_option_id] type: object properties: dimension_options[primary][dimension_option_id]: type: number description: Primary Dimension Option ID dimension_options[primary][dimension_id]: type: number description: Primary Dimension ID (optional, will be inferred from dimension_option_id) dimension_options[secondary][dimension_id]: type: number description: Secondary Dimension ID (optional, will be inferred from dimension_option_id) dimension_options[secondary][dimension_option_id]: type: number description: Secondary Dimension Option ID dimension_options[tertiary][dimension_id]: type: number description: Tertiary Dimension ID (optional, will be inferred from dimension_option_id) dimension_options[tertiary][dimension_option_id]: type: number description: Tertiary Dimension Option ID product_custom_attributes: type: array description: Array of product attributes' data items: type: object properties: product_custom_attribute_id: type: number value: type: string data_type: type: string multipart/form-data: schema: required: - dimension_options[primary][dimension_option_id] type: object properties: dimension_options[primary][dimension_option_id]: type: number description: Primary Dimension Option ID dimension_options[primary][dimension_id]: type: number description: Primary Dimension ID (optional, will be inferred from dimension_option_id) dimension_options[secondary][dimension_id]: type: number description: Secondary Dimension ID (optional, will be inferred from dimension_option_id) dimension_options[secondary][dimension_option_id]: type: number description: Secondary Dimension Option ID dimension_options[tertiary][dimension_id]: type: number description: Tertiary Dimension ID (optional, will be inferred from dimension_option_id) dimension_options[tertiary][dimension_option_id]: type: number description: Tertiary Dimension Option ID product_custom_attributes: type: array description: Array of product attributes' data items: type: object properties: product_custom_attribute_id: type: number value: type: string data_type: type: string required: true responses: '200': description: Successfully updated Product Variant content: '*/*': schema: required: - dimension_options - id - product_assets - product_custom_attributes type: object properties: id: type: integer description: Variant ID dimension_options: type: object properties: primary: type: object nullable: true properties: name: type: string description: Dimension name value: type: string description: Dimension value dimension_id: type: integer description: Dimension ID dimension_option_id: type: integer description: Dimension option ID secondary: type: object nullable: true properties: name: type: string description: Dimension name value: type: string description: Dimension value dimension_id: type: integer description: Dimension ID dimension_option_id: type: integer description: Dimension option ID tertiary: type: object nullable: true properties: name: type: string description: Dimension name value: type: string description: Dimension value dimension_id: type: integer description: Dimension ID dimension_option_id: type: integer description: Dimension option ID additionalProperties: false product_custom_attributes: type: array description: Array of product custom attributes items: type: object properties: name: type: string description: Attribute name value: type: string nullable: true description: Attribute value data_type: type: string description: Data type of the attribute (e.g. text, image) product_custom_attribute_id: type: integer description: Product custom attribute ID product_attribute_group_id: type: integer description: Product attribute group ID asset_ids: type: array description: Array of asset IDs (for image/asset type attributes) items: type: string product_assets: type: array description: Array of product assets items: type: object properties: asset_id: type: string description: Asset ID product_ids: type: array description: Array of product IDs items: type: integer example: id: 1 dimension_options: primary: name: Size value: Small dimension_id: 1 dimension_option_id: 1 secondary: name: Color value: Red dimension_id: 2 dimension_option_id: 2 tertiary: null product_custom_attributes: - name: name value: Red Small Shirt data_type: text product_custom_attribute_id: 1 product_attribute_group_id: 1 - name: sku value: RS-S data_type: text product_custom_attribute_id: 2 product_attribute_group_id: 1 - name: Description value: This is a red small shirt data_type: text product_custom_attribute_id: 3 product_attribute_group_id: 2 - name: An Image value: null data_type: image asset_ids: - abc123 - def234 product_custom_attribute_id: 4 product_attribute_group_id: 2 product_assets: - asset_id: e29b41d4a7166655440000 product_ids: - 1 - asset_id: f47ac10b58cc4372a5 product_ids: - 1 additionalProperties: false '401': description: User is not permitted to use the API or Authentication is invalid content: {} '404': description: Product Variant ID not found or invalid content: {} '422': description: Product Variant validation failed content: {} '500': description: Something went wrong content: {} /products/{product_id}/variants/{variant_id}/assets: post: tags: - variants summary: Add Assets to Variant description: Add between 1 and 50 assets to a variant operationId: post_api_v1_products_product_id_variants_variant_id_assets parameters: - name: product_id in: path required: true schema: type: string - name: variant_id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - asset_ids properties: asset_ids: type: array description: Array of Asset ID Strings minItems: 1 maxItems: 50 items: type: string responses: '201': description: Successfully added assets to variant content: {} '401': description: User is not permitted to use the API or Authentication is invalid content: {} '404': description: Product ID or Variant ID was not found or invalid content: {} '422': description: At least 1 and no more than 50 Asset IDs are required content: {} '500': description: Something went wrong content: {} delete: tags: - variants summary: Remove Multiple Assets from Variant description: Remove at least 1 and no more than 50 assets from a variant operationId: delete_api_v1_products_product_id_variants_variant_id_assets parameters: - name: product_id in: path required: true schema: type: string - name: variant_id in: path required: true schema: type: string - name: asset_ids in: query required: true schema: type: string description: Comma-separated list of Asset IDs (e.g., ?asset_ids=1,2,3) responses: '204': description: Successfully removed assets from variant content: {} '401': description: User is not permitted to use the API or Authentication is invalid content: {} '404': description: Product ID or Variant ID was not found or invalid content: {} '422': description: At least 1 and no more than 50 Asset IDs are required content: {} '500': description: Something went wrong content: {} /products/{product_id}/variants/{variant_id}/assets/{id}: delete: tags: - variants summary: Remove Single Asset from a Variant description: Remove a single asset from a variant operationId: delete_api_v1_products_product_id_variants_variant_id_assets_id parameters: - name: product_id in: path required: true schema: type: string - name: variant_id in: path required: true schema: type: string - name: id in: path required: true schema: type: string description: Asset ID responses: '204': description: Successfully removed asset from variant content: {} '401': description: User is not permitted to use the API or Authentication is invalid content: {} '404': description: Product ID was not found or invalid content: {} '422': description: No matching assets found content: {} '500': description: Something went wrong content: {} components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: AccessToken x-original-swagger-version: '2.0'