openapi: 3.0.1
info:
  title: Canto PIM bulk_products_catalogs import_settings 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: import_settings
  description: "        API endpoints for configuring how CSV imports should be processed.\n        This includes:\n        - Mapping CSV headers to product attributes\n        - Configuring how product variations should be handled\n        - Setting up category and type assignments\n"
paths:
  /import_settings:
    post:
      tags:
      - import_settings
      summary: Configure import mappings and variation formats
      description: "    Creates or retrieves channel template and format settings based on provided mappings.\n\n    This endpoint helps configure how CSV data will be imported by:\n    1. Mapping CSV headers to product attributes\n    2. Defining how variations should be grouped\n    3. Specifying dimension and option columns\n\n    Returns IDs needed for the actual import process.\n"
      operationId: post_api_v1_import_settings
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                custom_attribute_mappings[header_name]:
                  type: number
                  description: Key is CSV header, value is product custom attribute ID
                variation_formatting[group_by][columns]:
                  type: array
                  description: Column headers to group by
                  items:
                    type: string
                variation_formatting[group_by][parent_key]:
                  type: string
                  description: Column header for parent SKU
                variation_formatting[group_by][child_key]:
                  type: string
                  description: Column header for child SKU reference
                variation_formatting[dimensions][primary][dimension]:
                  type: string
                  description: Dimension column header
                variation_formatting[dimensions][primary][dimension_option]:
                  type: string
                  description: Dimension option column header
                variation_formatting[dimensions][secondary][dimension]:
                  type: string
                  description: Dimension column header
                variation_formatting[dimensions][secondary][dimension_option]:
                  type: string
                  description: Dimension option column header
                variation_formatting[dimensions][tertiary][dimension]:
                  type: string
                  description: Dimension column header
                variation_formatting[dimensions][tertiary][dimension_option]:
                  type: string
                  description: Dimension option column header
          multipart/form-data:
            schema:
              type: object
              properties:
                custom_attribute_mappings[header_name]:
                  type: number
                  description: Key is CSV header, value is product custom attribute ID
                variation_formatting[group_by][columns]:
                  type: array
                  description: Column headers to group by
                  items:
                    type: string
                variation_formatting[group_by][parent_key]:
                  type: string
                  description: Column header for parent SKU
                variation_formatting[group_by][child_key]:
                  type: string
                  description: Column header for child SKU reference
                variation_formatting[dimensions][primary][dimension]:
                  type: string
                  description: Dimension column header
                variation_formatting[dimensions][primary][dimension_option]:
                  type: string
                  description: Dimension option column header
                variation_formatting[dimensions][secondary][dimension]:
                  type: string
                  description: Dimension column header
                variation_formatting[dimensions][secondary][dimension_option]:
                  type: string
                  description: Dimension option column header
                variation_formatting[dimensions][tertiary][dimension]:
                  type: string
                  description: Dimension column header
                variation_formatting[dimensions][tertiary][dimension_option]:
                  type: string
                  description: Dimension option column header
      responses:
        '200':
          description: Template and format IDs for use in import
          content:
            '*/*':
              schema:
                required:
                - channel_format_id
                - channel_template_id
                type: object
                properties:
                  channel_template_id:
                    type: number
                    description: ID of the configured channel template
                  channel_format_id:
                    type: number
                    description: ID of the configured format
                additionalProperties: false
        '404':
          description: Template or format not found
          content: {}
        '422':
          description: Invalid mapping configuration
          content: {}
        '500':
          description: Internal server error
          content: {}
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: AccessToken
x-original-swagger-version: '2.0'