Elastic Path Import a Price Book and Prices API

You can create and update product price books and prices in bulk, at both organization and store level, using the Price Book Import API. This is useful, for example, if you have a promotion and want to update 50,000 product prices. Rather than having to go to each price book and manually edit 50,000 prices, you can use the Price Book Import API to bulk update all your product prices at the same time, including setting different prices for different currencies.You can create/update:- price books.- prices. - sales pricing for products and product bundles with SKUs. - volume pricing (tiers).The following are not supported by the Price Book Import API:- price modifiers- SKUless bundles- Bundle sale pricesThe API uses a [JSONL](https://jsonlines.org/) file. The JSONL file can be compressed to a GZIP file. Here is an [example of a JSONL file](/assets/example_file_all.jsonl).A file can include up to 50,000 objects. If you have more than 50,000 objects, then you must create a separate file, and import each file, one at a time.### Characteristics of Price Book ImportThe Price Book Import API reads the entire file and then creates/updates the price book objects. This means the price book objects can be in any order in the file.Price book imports are asynchronous. When you send a request to the price book import API, it triggers an asynchronous job to create/update the price books and product prices. You can see the status of a job using Get a job.Jobs are processed one at a time. You can continue to send price book import requests, but those jobs are queued. In other words, Commerce looks for any jobs that have a status of PENDING and starts the job with the earliest created date. This process is repeated until all jobs are processed. See [Jobs](/docs/api/pxm/products/jobs).The API works on a "best endeavours" approach. In other words, the API does its best to create/update the price book objects based on the file that you provide. You can then use the results of the job to understand what objects the API created/updated and to troubleshoot any errors. See [Price Book Import API Results](#price-book-import-api-results).Price book imports are processed sequentially in the order that you send your import API requests.### Price Book Import Unique IdentifiersThe API uses unique identifiers to identify the objects to be created/updated.You must provide either an `id` or an `external_ref`. You may have both, but you must have at least one.- If you supply an `id` then the ID must exist for the object to be updated. If the ID does not exist, this causes an error.- If you supply an `external_ref` then the API checks if the external reference exists and updates the object. If the external reference does not exist, the API creates a new object with the external reference you have specified.#### Price Book Unique IdentifiersThe following table describes the unique identifiers you must provide, depending on whether you are creating or updating a price book.| Action | Unique Identifiers || --- | --- || Creating | Unique price book name.`external_ref` for the price book. || Updating | `id` and/or `external_ref` for the price book. |#### Price Unique IdentifiersThe following table describes the unique identifiers you must provide, depending on whether you are creating or updating a price. | Action | Unique Identifiers | | --- | --- | | Creating | The product SKU that the price belongs to.`id` and/or `external_ref` for the price book where you want to create the new price.`external_ref` for the price. The `external_ref` for a price must be unique within a price book. However, you can have duplicate price external references across multiple price books. | | Updating | The product SKU that the price belongs to.`pricebook_external_ref` for the price book where you want to update the new price.`id` and/or `external_ref` for the price. The `external_ref` for a price must be unique within a price book. However, you can have duplicate price external references across multiple price books. | ### Price Book Import File You can create/update price book objects using [Import a Price](/docs/api/pxm/pricebooks/import-a-price-book-and-prices). The API uses a [JSONL](https://jsonlines.org/) file. The JSONL file can be compressed to a GZIP file. Here is an [example of a JSONL file](/assets/example_file_all.jsonl). A file can include up to 50,000 objects. If you have more than 50,000 objects, then you must create a separate file, and import each file, one at a time. - The `pricebook` Object - The attributes you can specify for a `pricebook` object are the attributes you specify when [creating a pricebook](/docs/api/pxm/pricebooks/create-pricebook). - The `product-price` Object - The attributes you can specify for a `product-price` object are the attributes you specify when [adding a price to a price book](/docs/api/pxm/pricebooks/create-product-price). Once your import file is created, use the [import a price book and prices API to import](/docs/api/pxm/pricebooks/import-pricebook) the file. ### Importing product prices with custom attributes There are two types of custom attributes a price can have `shopper_attributes` and `admin_attributes`. When importing product prices with custom attributes, you can import a price with: - up to 100 `admin_attributes` - up to 100 `shopper_attributes` Ensure that a price adheres to these limits for custom attributes. ### Price Book Import API Results The API works on a "best endeavours" approach. In other words, the API does its best to create/update the price book objects based on the file that you provide. If there are any errors, then the import is aborted and the job fails with an error. You can then use the job results to understand what objects the API created/updated until the import failed and to troubleshoot any errors. Once you have fixed any errors, you can then use the [**import a price**](/docs/api/pxm/pricebooks/import-pricebook) endpoint to send the request again. The following table describes the import messages reported by the API. | Import Message | Description | | --- | --- | | import price book_id: '%v' belongs to Organization", price book.ID))"import price book external_ref: '%v' belongs to Organization", *price book.ExternalRef) | This group of messages tells you that these imported objects belong to an organization. | matched price with pricebook_id - had different external_refmatched price with pricebook_id - belongs to different price bookmatched price with pricebook_id - price_id not foundmatched price with pricebook_id - price_id belongs to an organization.matched price with pricebook_id - duplicate external_ref detectedmatched price with pricebook_id - duplicate SKU detected - required SKU. | This group of messages is telling you that the price was updated but there is an issue with another attribute that requires fixing. | The following table describes the import errors reported by the API. | Error | Description | | --- | --- | | error processing gzip fileerror processing object '%v' invalid json provided | This group of errors indicates that there is a problem with the JSONL file. You must fix the problems with the file and try the import again. | | duplicate price book Id '%s' in imported price booksmissing attributes for price bookinvalid type for external_ref for price bookmissing attributes for pricemissing sku for pricemissing sku for priceinvalid type for external_ref for priceinvalid type for sku for pricemissing price book_id/price book_external_ref for priceprice book id(s) not foundprice book external ref(s) not foundprice book id not found:duplicate external ref foundprice Ids not foundprice book external refs not found | This group of errors indicates that there is some information missing from the objects you are trying to create/update. |