Skip to main content

Commerce Product Import

The Commerce Product Import is a utility in the Integrations Hub in Commerce Manager that enables you to import Commerce product data from one Commerce store to another. The Commerce Product Import utility can import:

  • Product data files of any size.
  • Product variations.
  • Any media files available with products.
  • Localized product names and descriptions.
caution

You cannot import bundles using the Product Import integration.

For more information, watch a video.

An example of how product data is imported using a Product Import integration is described below.

  1. Create a JSON file with the product data you want to import. You can have more than one JSON file, depending on your requirements. See Product Import Integration File Format.

  2. Configure a Product Import integration in the store where you want to import the product data. This creates the webhooks that consumes the message and JSON files when you send the API request to import the product data.

  3. In Postman, run POST {{gzip-file-url-handler-webhook-url}} request. As part of the request, you must supply the Gzip file URLs for the JSON files you want to process as part of the import. See Using Product Import Integration Files.

    • The Product Import integration processes your Gzip files.
    • The products are imported to the store.

Product Import Integration File Format

The data that you provide to the Product Import Integration must conform to JSON Lines text format and conform to the following product model. The Product Import JSON Schema can be used to validate that your individual product objects are in the correct format.

NameTypeDescription
namearrayAn array of names represented as locale objects.
descriptionarrayAn array of descriptions represented as locale objects.
skustringThe unique stock keeping unit of the product.
slugstringA 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.
productTypestringAlways: product.
statusstringThe status for the product, either draft or live.
commodityTypestringThe commodity type, either physical or digital.
mediaobjectThe media available with this product, for example, images. See media object.
mpnstringThe manufacturer part number of the product.
attributesobjectThe attributes defined for a product. See attributes object.
variationobjectThe variations defined for a product. See variation object.

The locales Object

Locales must be specified for product names and descriptions. You can have as many localized names and descriptions as needed.

NameTypeDescription
localestringA 2-character ISO 639-1 locale code that specifies the language of the associated value.
valuestringThe localized value.

The media object

NameTypeDescription
typestringThe type of resource object. For example, main_image or file.
urlstringThe URL of the resource.

The attributes object

NameTypeDescription
templateSlugstringSpecifies a unique slug identifier for the attribute.
templateAttributesobjectThe attributes you want to import. See templateAttributes object.

The templateAttributes object

NameTypeDescription
fieldSlugstringThe slug that contains the attribute you wish to create an entry for.
typestringSpecifies the type of field. Values can be date, string, boolean, float or integer.
valuestringThe value of the field.

The variation object

NameTypeDescription
variantSlugstringA label for the variation 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.
optionNameobjectThe options available for this variation.

Example Product Objects

Example 1 - Product with a Single Template

{
name: [
{
locale: "en",
value: "en-name",
},
],
description: [
{
locale: "en",
value: "en-description",
},
],
slug: "slug",
sku: "sku",
productType: "product",
status: "draft",
commodityType: "digital",
mpn: "mpn",
attributes: [
{
templateSlug: "products(ps)",
templateAttributes: [
{
fieldSlug: "dateAttribute",
type: "date",
value: "2021-05-28T15:59:48.790Z",
},
{
fieldSlug: "integerAttribute",
type: "integer",
value: 1,
},
{
fieldSlug: "stringAttribute",
type: "string",
value: "dolore pariatur enim cillum",
},
],
},
],
}

Example 2 - Product with One Variant

{
name: [
{
locale: "en",
value: "en-name",
},
],
slug: "slug",
sku: "sku",
productType: "product",
status: "draft",
commodityType: "digital",
skuProducts: [
{
slug: "skuSlug",
sku: "skuSku",
productType: "sku",
name: [
{
locale: "skuLocale",
value: "skuName",
},
],
status: "live",
commodityType: "digital",
variation: [
{
variantSlug: "variantSlug1",
optionName: "optionName",
},
],
},
],
}

Using Product Import Integration Files

To invoke the product import, you must invoke the webhook created when you configure the Product Import integration and supply the Gzip file URLs as part of the payload. See Importing your Product Data. We recommend that URLs are signed with an expiration date. See Sharing objects using presigned URLs.

Body

NameRequiredTypeDescription
gzipFileUrlsRequiredstringThe Gzip file URls for the JSON files you want to import in the format https://{path}/products.jsonl.gz where path is the path to your Gzip file. You can specify more than one. We recommend aligning the number of products per file with the pageSize, as processing each page requires rereading the file.
fileIndexOptionalintegerThe zero based index of the gzip file to start with. The default is zero. This is useful to restart processing in case of failure.
pageOptionalintegerThe number of pages handled during import.
PageSizeOptionalintegerThe number of products to process from a given file in a paged manner. The default is 500 and the upper limit depends on the number of custom attributes, files and variations. Tuning may be required to find the optimal page size.

Request Example

{
"gzipFileUrls": [
"https://{path}/products.jsonl.gz"
],
"fileIndex": 0,
"page": 0,
"pageSize": 1000
}

Prerequisites

  1. The store that you are importing your product data set into must meet the following prerequisites:

    • The templates and attributes defined in the product data that you are importing must exist in the store that you are importing the product data into.
    • The variations defined in the product data that you are importing must exist in the store that you are importing the product data into. If the variations defined in the product data import have options, you do not need to create those options in your store. The Product Import automatically creates the options for you as part of the product import.
  2. You must have a JSON file configured that defines the product data you want to import. See Product Import Integration File Formats.

Configuring the Product Import Integration

Once you have met the Prerequistes, you are ready to configure the product import integration in Integrations Hub.

  1. In Commerce Manager, go to the store where you want to import product data.

  2. Go to COMPOSER > Integrations Hub.

  3. Under Store Management & Configuration, click Commerce Product Import. The Commerce Product Import integration guides you through the steps you need to follow to complete the integration.

  4. Click Configure. The Trigger details are displayed. Note: These fields are blank the first time you configure the integration.

    • Gzip File URL Handler - The webhook that consumes your Gzip files.
    • Page Product Loader - The webhook that processes each page of products until all pages are processed.
  5. Click Next. The Commerce Connection page is displayed.

  6. Complete the information in the Commerce Connection page. You can find this information in SYSTEM > Application Keys in Commerce Manager when logged in as a user with Seller Admin privileges. See Application Keys.

    • Client-ID - Your Commerce Client ID.
    • Client-Secret - Your Commerce Client Secret.

    The table below describes the options you can configure.

    OptionDescription
    Keep Alive FlagTurn on the Keep Alive Flag toggle if you want to specify keep alive intervals for this integration.
    Keep Alive IntervalSpecify keep alive interval for this integration. Default value is 10000.
    Throttle IntervalSpecify throttle interval for this integration. Default value is 125. This supports staying within rate limits.
    Throttle LimitSpecify throttle request limit interval for this integration. Default value is 3. This supports staying within rate limits.
    Token URLYour Commerce API Token URL. For example, https://api.motlin.com/oauth/<access_token> (EU) or https://useast.api.elasticpath.com/oauth/<access_token> (US).
  7. Click Connect.

  8. Once you have successfully connected to Commerce, you can configure the following:

    OptionDescription
    Elapsed Execution Time CutoffThe number of seconds to wait before the product import is stopped, if page processing has halted for any reason. This may need to be increased if the number of products being processed for the store is exceptionally large.
    Default Page SizeThe default page size processed when importing.
    Merge ModeWhen set, the comparison is made between the existing product and the inbound definition, with only items that have been changed. Default: false
    Log LevelFrom Log Level list, select the level of logging.
  9. Click Finish. Your integration is enabled. You must enable a Product Import integration on each store where you want to import your product data set.

Merge Mode

Default processing assumes that the inbound product record provides a full representation of the product, allowing a more efficient product loading process. However, in scenarios, where there are multiple sources of product information, it might become necessary to use the Merge Mode. When this option is selected, the product loader will load the existing product, overlaying it with the inbound product before performing any updates.

The default value is false (not enabled).

Importing your Product Data

You can perform the product import using Postman.

  1. Go to a store.
  2. Go to COMPOSER > Integrations Hub.
  3. Under Store Management & Configuration, select Commerce Product Import. You must have configured a Product Import integration before you can import any resources into this store. See Configuring the Product Import Integration.
  4. From Summary > Trigger Details, click Gzip File URL Handler to display the webhook.
  5. Select Copy to Clipboard to copy the URL.
  6. Go to Postman.
  7. Open POST {{gzip-file-url-handler-webhook-url}} where gzip-file-url-handler-webhook-url is the webhook you copied in step 5.
  8. In Body, add the list of Gzip file URLs for the JSON files you want to import. See Product Import Integration File Format.
  9. Run POST {{gzip-file-url-handler-webhook-url}}.
  10. When the import has finished, if you go to your store, you should see all the resources you just imported.

Troubleshooting the Product Import Integration

You can debug any issues in Executions. Click an execution to see the execution details. The Logs shows the output and any errors or warnings.

Select Retry to initiate an execution again.