openapi: 3.1.0
info:
  version: 25.1126.6886238
  x-version-timestamp: 2025-11-26 19:10:23+00:00
  title: Addresses Introduction Account Addresses Product Import/Bulk Update API
  description: 'The Addresses API allows you to organize account addresses. Addresses are a sub-resource of `account` resources, an account can have multiple addresses, such as home, work, and neighbour.


    You can use an account address with either [client_credentials access token](/docs/api/authentication/create-an-access-token) or a combination of [implicit access token](/docs/api/authentication/create-an-access-token) and [Account Management authentication](/docs/api/accounts/post-v-2-account-members-tokens) token.

    '
  contact:
    name: Elastic Path
    url: https://www.elasticpath.com
    email: support@elasticpath.com
  license:
    url: https://elasticpath.dev
    name: MIT
servers:
- url: https://useast.api.elasticpath.com
  description: US East
- url: https://euwest.api.elasticpath.com
  description: EU West
security:
- BearerToken: []
tags:
- name: Product Import/Bulk Update
  description: "```mdx-code-block\nimport ProductImport from '/docs/partials/pxm/import/import.mdx';\n\n<ProductImport />\n```\n\n#### Using Imported Main Image Files\n\nYou can use the main images that you have previously uploaded to Commerce and assign them to your products when importing products to Commerce. You can do this by adding a `main_image_id` header to your `.csv` file. The ID you provide in `main_image_id` is the ID of a file that has already been uploaded to Commerce using create a file.\n\n#### Importing Custom Data (Flows)\n\nYou can also create/update custom extension data in a `.csv` file by creating a header that includes the flow `ID` and the field `slug` in the following format: \n\ntemplate:*flowID*:*fieldSlug*.\n\nwhere:\n\n- `template` must be `template`.\n- `flowID` is the ID of the flow that contains the field whose data you want to create/update.\n- `fieldSlug` is the slug of the field whose data you want to create/update.\n\nIn the following example, for a flow with ID `82c10a02-1851-4992-8ecb-d44f2782d09b` and a field with the slug `condition`:\n\n- the header is `template:82c10a02-1851-4992-8ecb-d44f2782d09b:condition`.\n- the updated custom data is `as-new`.\n\n    | name | slug | sku | status | template:82c10a02-1851-4992-8ecb-d44f2782d09b:condition |\n    | :--- | :--- | :--- | :--- | :--- |\n    | BestEver Range | bestever-range-1a1a-30 | BE-Range-1a1a-30 | draft | as-new |\n\n#### Characteristics of CSV Import Files\n\nProduct Import uses a [**Comma Separated Values (CSV)**](#characteristics-of-csv-import-files) file to import/update products, main image files, and custom extension data. \n\n- Each row in a `.csv` file represents a product you want to create/update. \n- Each file:\n    - must not be larger than 50 megabytes. If a `.csv` file is larger than 50 megabytes, a `503 client read error` is displayed.\n    - must not have more than 50,000 rows, including the header. If a CSV file exceeds 50,000 rows, an error is displayed, and the products are not imported.\n    In other words, if you have a file with 50,000 rows that is larger than 50 megabytes, an error is displayed, and the products are not imported.\n- If you want to create/update more than 50,000 products or your `.csv` file is larger than 50 megabytes, you must have a separate `.csv` file and import each `.csv` file one at a time.\n- You can update existing products, including images, templates/flow fields, and entries. The entry in the `.csv` file must have a unique `id` and/or `external_ref` that matches the `id` and `external_ref` of the existing product you want to update. You may have both a unique `id` and `external_ref`, but you must have at least one.\n- You can add new products. For new products that you want to add, the entry in the `.csv` file must have an `external_ref` that does not match any existing products.\n\nThe following table describes the headers that are supported.\n\n| Header | Required | Description  |\n|:---- |:---------|:--|\n| id                              | Optional | A unique product ID that is generated when you create the product. The `id` is used to look up products in the `.csv` file and matches them to the products in your storefront that you want to update.                                                                                                                                                                                                       |\n| external_ref                    | Optional | A unique attribute associated with a product. This could be an external reference from a separate company system, for example. The maximum length is 2048 characters.                                                                                                                                                                                                                                         |\n| name                            | Required | The name of a product.                                                                                                                                                                                                                                                                                                                                                                                        |\n| description                     | Required | A description for a product. You can include quotes in your product description, if you want to emphasize a word, for example. To do this, put quotes around the product description. For example, \"This product description describes my \"product\" and the product \"version\".\"                                                                                                                               |\n| slug                            | Required | A label for the product that is used in the URL paths. A slug can contain any combination of letters, numbers, periods, hyphens, and underscores. NO spaces or other characters are allowed. By default, the product name is used as the slug.                                                                                                                                                                |\n| status                          | Required | The status of a product, either `Draft` or `Live`.                                                                                                                                                                                                                                                                                                                                                            |\n| commodity_type                  | Required | The commodity type, either `physical` or `digital`.                                                                                                                                                                                                                                                                                                                                                           |\n| upc_ean                         | Optional | The universal product code or european article number of the product.                                                                                                                                                                                                                                                                                                                                         |\n| mpn                             | Optional | The manufacturer part number of a product.                                                                                                                                                                                                                                                                                                                                                                    |\n| sku                             | Optional | The unique stock keeping unit of the product.                                                                                                                                                                                                                                                                                                                                                                 |\n| tags                             | Optional | The product tags used to store or assign a key word against a product. A product can have up to 20 product tags. A product tag can be up to 255 characters. See [**Product Tags**](/docs/api/pxm/products/product-tags).\n| main_image_id                   | Optional | Specifies a unique ID of a main image file for a product. You can include a `main_image_id` for your products for images that are already uploaded to Commerce. See [**Using Main Image Files**](#importing-custom-data-flows).                                                                                                                                                                                        |\n| `template:<flowID>:<fieldSlug>` | Optional | You can also specify custom extension data in the CSV by specifying the flow `ID` or `slug` and the field `name`. For example, `template:<flowSlug>:<fieldName>` format. See [**Importing Custom Data (Flows)**](#importing-custom-data-flows). |\n"
paths:
  /pcm/products/import:
    post:
      summary: Import Products
      description: "\nYou can use the Product Import API to:\n\n- Add new products, including:\n\n    - main image files. See [Importing Main Image Files](/docs/api/pxm/products/product-import-bulk-update#using-imported-main-image-files).\n    - custom data. See [Importing custom data](/docs/api/pxm/products/product-import-bulk-update#importing-custom-data-flows).\n    - Make bulk updates to existing products.\n\nYou cannot use product import to:\n\n- Delete existing products.\n- Import product bundles.\n\nThe Product Import API uses a Comma Separated Values (CSV) file to import products, main image files, custom extension data, and admin and shopper attributes. Each row in a .csv file represents a product you want to create/update. See an [example file](/assets/pim_product_import_example.csv).\n\nEach file can have 50,000 rows, including the header. If a CSV file exceeds 50,000 rows, an error is displayed, and the products are not imported. A CSV file must not be larger than 50 megabytes. If a CSV file is larger than 50 megabytes, a `503 client read` error is displayed.\n\nIf you want to create/update more than 50,000 products or your CSV file is larger than 50 megabytes, you must have a separate CSV file and import each CSV file one at a time.\n\nSee [**Characteristics of CSV Files**](/docs/api/pxm/products/product-import-bulk-update#characteristics-of-csv-import-files).\n\n## Custom Attributes in CSV\n\nYou can set custom attributes on products using CSV columns with the prefixes `shopper_attributes.` or `admin_attributes.` followed by the attribute key name. For example:\n\n- `shopper_attributes.color` sets the `color` key on `shopper_attributes`.\n- `admin_attributes.cost_of_goods` sets the `cost_of_goods` key on `admin_attributes`.\n\n**Partial updates:** When updating an existing product, only the attribute keys present as columns in the CSV are affected. Attribute keys not included as columns are left unchanged.\n\n**Removing an attribute key:** To explicitly delete an attribute key from an existing product, set the cell value to `__REMOVE_ATTRIBUTE__`. This special sentinel value instructs the importer to remove that key from the product's custom attributes. An empty cell value is treated as a literal empty string, not a deletion.\n\n**New products:** For new products being created via import, any column whose value is `__REMOVE_ATTRIBUTE__` is ignored (the key is not created).\n"
      operationId: importProducts
      tags:
      - Product Import/Bulk Update
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  description: The file you want to upload. Ensure that the file format is Comma Separated Values (CSV).
                  type: string
                  format: binary
                  example: UploadFile
            examples:
              upload_image:
                summary: Upload Image
                value:
                  file: '@path/to/file'
      responses:
        '201':
          description: Import started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/single'
              examples:
                pending:
                  summary: Successful Job
                  $ref: '#/components/examples/import'
        '400':
          $ref: '#/components/responses/bad_request'
        '422':
          $ref: '#/components/responses/unprocessable_entity'
        '500':
          $ref: '#/components/responses/internal'
      parameters:
      - name: locale
        in: query
        description: "Specifies the locale to assist in parsing flow entry date values.\n\n- If a supported locale is provided, the system attempts to interpret dates using that locale's conventions. The import job fails if a date does not match one of the supported locale's formats.\n- If this parameter is omitted, or if the value provided is not on the supported list, the system proceeds using its default parsing logic. An unsupported locale is ignored and does not cause a failure.\n\n**Supported Locales and Date Formats:**\n\n**`en-US`**\n- `1/2/2006 15:04:05`\n- `01/02/2006 15:04:05`\n- `1/2/06 15:04`\n\n**`en-GB`**\n- `2/1/2006 15:04:05`\n- `02/01/2006 15:04:05`\n- `2/1/06 15:04`\n\n**`en-CA`**\n- `2/1/2006 15:04:05`\n- `02/01/2006 15:04:05`\n- `2/1/06 15:04`     \n\nAdditional locales and date formats can be added upon request.\n"
        required: false
        schema:
          type: string
          enum:
          - en-US
          - en-GB
          - en-CA
        example: en-US
components:
  responses:
    bad_request:
      description: Bad request. The request failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            bad-request:
              value:
                errors:
                - title: Bad Request
                  detail: Could not parse the supplied filter
                  status: '400'
    unprocessable_entity:
      description: Bad request. The request failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            failed-validation:
              value:
                errors:
                - title: Failed Validation
                  status: '422'
                  detail: <XYZ> can not be empty
    internal:
      description: Internal server error. There was a system failure in the platform.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            internal-server-error:
              value:
                errors:
                - status: '500'
                  title: Internal Server Error
                  detail: There was an internal server error, you can report with your request id.
                  request_id: 635da56d-75a1-43cd-b696-7ab119756b3a
  schemas:
    single:
      type: object
      required:
      - data
      properties:
        data:
          $ref: '#/components/schemas/job'
    error:
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            required:
            - status
            - title
            properties:
              status:
                type: string
                description: The HTTP response code of the error.
                example: '500'
              title:
                type: string
                description: A brief summary of the error.
                example: Internal server error
              detail:
                type: string
                description: Optional additional detail about the error.
                example: An internal error has occurred.
              request_id:
                type: string
                description: Internal request ID.
                example: 00000000-0000-0000-0000-000000000000
              meta:
                type: object
                description: Additional supporting meta data for the error.
                example:
                  missing_ids:
                  - e7d50bd5-1833-43c0-9848-f9d325b08be8
    job:
      type: object
      required:
      - id
      - type
      - attributes
      - meta
      properties:
        id:
          description: A unique identifier generated when a job is created.
          type: string
        type:
          description: This represents the type of resource object being returned. Always `pim-job`.
          type: string
          enum:
          - pim-job
        attributes:
          type: object
          required:
          - started_at
          - completed_at
          - created_at
          - updated_at
          - type
          - status
          properties:
            started_at:
              description: The date and time a job is started.
              type: string
              example: '2020-09-22T09:00:00.000Z'
              format: date-time
              nullable: true
            completed_at:
              type: string
              example: '2020-09-22T09:00:00.000Z'
              format: date-time
              nullable: true
              description: The date and time a job is completed.
            created_at:
              type: string
              description: The date and time a job is created.
              example: '2020-09-22T09:00:00.000Z'
              format: date-time
            updated_at:
              type: string
              description: The date and time a job is updated.
              example: '2020-09-22T09:00:00.000Z'
              format: date-time
            type:
              type: string
              description: 'The status of a job.


                * `pending` - Commerce has received the request but is currently busy processing other requests.

                * `started` - Commerce has started processing the job.

                * `success` - The job has successfully completed.

                * `failed` - The job has failed.

                '
              enum:
              - child-products
              - product-import
              - product-export
              - hierarchy-duplicate
              - pricebook-import
              - pricebook-delete
              - hierarchy-delete
              - indexing-job
            status:
              type: string
              enum:
              - pending
              - cancelled
              - cancelling
              - started
              - success
              - failed
        meta:
          type: object
          required:
          - x_request_id
          properties:
            x_request_id:
              type: string
              description: Applies to all job types. A unique request ID is generated when a job is created.
            copied_from:
              type: string
              description: Applies to `hierarchy-duplicate` job types. The ID of the original hierarchy that you duplicated.
            hierarchy_id:
              type: string
              description: Applies to `hierarchy-duplicate` job types. The duplicated hierarchy ID.
            file_locations:
              type: array
              nullable: true
              description: If the job type is `product_export`, a link to the file is created when running a job.
              items:
                type: string
            filter:
              type: string
              nullable: true
              description: The entities included in the job. For example, if the job type is `product-export`, the PXM products included in the export.
  examples:
    import:
      value:
        data:
          type: pim-job
          id: 7e1b9ba1-c844-4556-9b16-4ae3f0988b0f
          attributes:
            completed_at: null
            created_at: '2024-01-05T15:27:23.161Z'
            started_at: null
            status: pending
            type: product-import
            updated_at: '2024-01-05T15:27:23.161Z'
          meta:
            x_request_id: fad8c5c0-9546-4e0c-b68e-8a2d809891e5
  securitySchemes:
    BearerToken:
      type: http
      scheme: bearer