Canto variants API
The variants API from Canto — 4 operation(s) for variants.
OpenAPI Specification
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 \n<b>Key Capabilities</b><br />\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 \n<b>API Design</b>\n- The PIM API adheres to <b>RESTful principles</b>, supporting standard HTTP methods (GET, POST, PUT, PATCH, DELETE).\n- JSON is the default payload format for both requests and responses.\n\n<b>HTTP Status Code Conventions</b><br />\nBelow are general HTTP codes applicable across most endpoints:<br />\n- <b>200, 201, 204</b> – Successful operations (retrieval, creation, update, deletion).\n- <b>400</b> – Bad request. Input payloads did not conform to the expected schema or required parameters were missing.\n- <b>401 / 403</b> – Authentication or authorization failed.\n- <b>404</b> – The route or resource was not found.\n- <b>409</b> – Conflict in resource state (e.g., duplicate product identifier).\n- <b>429</b> - Too many requests. See Rate Limits below.\n- <b>500</b> – An unexpected server error occurred.\n- <b>502 / 503 / 504</b> – Infrastructure issues such as load balancer, service unavailability, or timeouts.\n\n<b>API Rate Limits</b><br />\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\n<b>PIM API Rate Limit:</b> 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:
# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/canto/refs/heads/main/openapi/canto-variants-api-openapi.yml