Import a Price Book and Prices

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 prices

The API uses a JSONL file. The JSONL file can be compressed to a GZIP file. Here is an example of a JSONL file.

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 Import

The 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.

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 imports are processed sequentially in the order that you send your import API requests.

Price Book Import Unique Identifiers

The 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 Identifiers

The 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 Identifiers

The 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.

The API uses a JSONL file. The JSONL file can be compressed to a GZIP file. Here is an example of a JSONL file.

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.

• 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.

  Once your import file is created, use the import a price book and prices API to import the file.

  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 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_ref matched price with pricebook_id - belongs to different price book matched price with pricebook_id - price_id not found matched price with pricebook_id - price_id belongs to an organization. matched price with pricebook_id - duplicate external_ref detected matched 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 file error 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 books missing attributes for price book invalid type for external_ref for price book missing attributes for price missing sku for price missing sku for price invalid type for external_ref for price invalid type for sku for price missing price book_id/price book_external_ref for price price book id(s) not found price book external ref(s) not found price book id not found: duplicate external ref found price Ids not found price 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.

📄️ Import a Price

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.