--- schema_version: "1" id: 52b649ed1579933ad9a533a3b9b9d2409f95a52f1e322a6aa0f249375e4d4378 title: Price Books collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/price-books.md canonical_url: https://developer.salesforce.com/docs/commerce/commerce-api/references/price-books source_site: developer.salesforce.com content_type: documentation content_hash: 4075afba68ed8cec39f0340182f70cee0c290955538caf7653cbff03a465a7a1 products: - B2C Commerce API - Salesforce APIs --- Price Books # Price Books [Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/price-books/price-books-oas-v1-public.yaml) ## API Overview The Price Books API provides full CRUD (Create, Read, Update, Delete) functionality for price books and price book entries within an organization. Price books in Salesforce Commerce Cloud contain the pricing information for products. They can be organized in hierarchies where one price book can inherit from another (parent) price book. Each price book is associated with a specific currency and can be assigned to one or more sites. Price book entries define the actual prices for products within a price book. Each entry carries one or more price scale tables, and each table has its own validity window and a set of quantity-based tiers (as absolute monetary amounts or percentage discounts). Entries have a composite identity of (priceBookId, productId). ### Authentication & Authorization For resource access, you must use a client ID and client secret from Account Manager to request an access token. The access token is used as a bearer token and added to the Authorization header of your API request. You must include `sfcc.price-books` (read-only access) or `sfcc.price-books.rw` (read-write access) in the client ID used to generate the token. For a full list of required permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html) For detailed setup instructions, see the Authorization for Admin APIs guide. ### Response Details #### Timeouts Admin API requests must respond within 60 seconds. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html) #### Error Handling Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html) ### Key Constraints * **Currency Immutability**: The currency code of a price book is immutable after creation. PATCH attempts to change it will be rejected. * **Parent Cycles**: Parent price book relationships that would create a cycle are rejected server-side. * **Site Assignments**: The `siteAssignments` field on a price book is read-only. Assignments are managed via the site-assignment endpoints on this API (`PUT`/`DELETE /price-books/{priceBookId}/site-assignments/{siteId}`). * **Price Tables**: The `priceTables` array in price book entries is replaced wholesale on PATCH; individual tables and their tiers cannot be updated independently. * **Price Book Type**: A price book with `type: feed_based` has its price entries sourced from an external feed pipeline. The price book container itself remains editable via this API, but price book entry write operations against a feed-based price book are rejected. ### Use Cases #### Create a Price Book Create a new price book with a specific currency. The price book ID is client-supplied and immutable, so creation uses `PUT` with the ID in the path (create-or-replace upsert); there is no `POST` collection endpoint: ```json PUT /organizations/{organizationId}/price-books/USD-list-prices { "id": "USD-list-prices", "displayName": "USD List Prices", "currencyCode": "USD", "online": true, "validFrom": "2024-01-01T00:00:00.000Z", "validTo": "2024-12-31T23:59:59.999Z" } ``` #### Add a Price to a Product Create or update a price book entry with a single amount tier: ```json PUT /organizations/{organizationId}/price-books/{priceBookId}/price-book-entries/{productId} { "productId": "product-001", "priceTables": [ { "tiers": [ { "type": "amount", "quantity": 1, "amount": { "currencyMnemonic": "USD", "value": 99.99 } } ] } ], "online": true } ``` #### Configure Tiered Pricing Set up time-scoped quantity-based pricing, mixing absolute amounts and percentage discounts: ```json PUT /organizations/{organizationId}/price-books/{priceBookId}/price-book-entries/{productId} { "productId": "product-002", "priceTables": [ { "validFrom": "2026-11-25T00:00:00.000Z", "validTo": "2026-11-28T23:59:59.999Z", "tiers": [ { "type": "amount", "quantity": 1, "amount": { "currencyMnemonic": "USD", "value": 39.99 } }, { "type": "amount", "quantity": 10, "amount": { "currencyMnemonic": "USD", "value": 34.99 } } ] }, { "validFrom": "2026-12-01T00:00:00.000Z", "tiers": [ { "type": "amount", "quantity": 1, "amount": { "currencyMnemonic": "USD", "value": 49.99 } }, { "type": "percentage", "quantity": 10, "percentage": 15.0 } ] } ], "online": true } ``` #### Find Active Price Books Search for price books that are currently active (online) and valid: ```json { "query": { "boolQuery": { "must": [ { "termQuery": { "fields": ["online"], "operator": "is", "values": [true] } } ] } } } ``` #### Search by Currency Find all price books for a specific currency: ```json { "query": { "termQuery": { "fields": ["currencyCode"], "operator": "is", "values": ["USD"] } }, "sorts": [ { "field": "displayName", "sortOrder": "asc" } ] } ``` #### Text Search Search for price books by name or description: ```json { "query": { "textQuery": { "fields": ["id", "displayName", "description"], "searchPhrase": "sale" } } } ``` ### Related Resources * [Pricing and Price Books in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_pricing_and_price_books.htm) * [Price Books for Developers in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_price_books_for_developers.htm) ### Related APIs * [Products (Admin)](https://developer.salesforce.com/docs/commerce/commerce-api/references/products?meta=Summary) — Manage products associated with price books. **Version:** 1.1.0 ## Servers * `https://{shortCode}.api.commercecloud.salesforce.com/product/price-books/v1` * `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)` ## Security * `AmOAuth2` (oauth2) OAuth 2.0 security scheme for Account Manager authentication. Required for all admin API endpoints. * OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token) * Scope sfcc.price-books: Read access to price books * Scope sfcc.price-books.rw: Read and write access to price books * OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token) ## Operations ### GET Get a list of price books. `GET /organizations/{organizationId}/price-books` Operation ID: `getPriceBooks`. Security: AmOAuth2 (sfcc.price-books, sfcc.price-books.rw). Get a paginated list of price books for the organization. Returns all price books with their basic metadata. Use the search endpoint for filtered queries. #### Parameters * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 50 (maximum). Defaults to 25. Default: `25`. Minimum: 1. Maximum: 50. * `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset. Default: `0`. Minimum: 0. #### Responses * **200** Price books retrieved successfully. Media type: `application/json`. Schema: `PriceBooks`. _Example: PriceBooksListResult_ Successful price books list retrieval Example of a paginated list of price books returned by GET /price-books. ``` { "limit": 25, "offset": 0, "total": 2, "data": [ { "id": "USD-list-prices", "displayName": "USD List Prices", "description": "Standard list prices for USD currency", "currencyCode": "USD", "online": true, "creationDate": "2024-01-01T00:00:00.000Z", "lastModified": "2024-01-15T10:30:00.000Z" }, { "id": "EUR-list-prices", "displayName": "EUR List Prices", "currencyCode": "EUR", "online": true, "creationDate": "2024-01-01T00:00:00.000Z", "lastModified": "2024-01-01T00:00:00.000Z" } ] } ``` * **400** Bad Request. Returned when a specified parameter value is invalid. Media type: `application/problem+json`. Schema: `InvalidQueryParameterErrorResponse`. _Example: InvalidQueryParameterErrorResponseExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-query-parameter", "detail": "Invalid query parameter.", "title": "Invalid Query Parameter" } ``` * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: UnauthorizedExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized", "title": "Unauthorized", "detail": "Unauthorized request" } ``` * **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: ForbiddenExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden", "title": "Forbidden", "detail": "Access to requested resource forbidden" } ``` ### GET Get a price book. `GET /organizations/{organizationId}/price-books/{priceBookId}` Operation ID: `getPriceBook`. Security: AmOAuth2 (sfcc.price-books, sfcc.price-books.rw). Get a price book by ID. Returns the price book with its metadata, including computed site assignments. The `siteAssignments` field is a read-only projection; assignments are managed via the site-assignment endpoints (PUT/DELETE /price-books/{priceBookId}/site-assignments/{siteId}). #### Parameters * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `priceBookId` (path, PriceBookId, required) The price book ID. #### Responses * **200** Price book retrieved successfully. Media type: `application/json`. Schema: `PriceBook`. _Example: PriceBookRetrieved_ Price book retrieved successfully Example of a price book returned by GET /price-books/{priceBookId}, including site assignments. ``` { "id": "USD-list-prices", "displayName": "USD List Prices", "description": "Standard list prices for USD currency", "currencyCode": "USD", "type": "standard", "parent": "base-prices", "online": true, "validFrom": "2024-01-01T00:00:00.000Z", "validTo": "2024-12-31T23:59:59.999Z", "siteAssignments": [ { "id": "RefArch", "displayName": "RefArch Store" }, { "id": "RefArchGlobal", "displayName": "RefArch Global" } ], "creationDate": "2024-01-01T00:00:00.000Z", "lastModified": "2024-01-15T10:30:00.000Z" } ``` * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: UnauthorizedExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized", "title": "Unauthorized", "detail": "Unauthorized request" } ``` * **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: ForbiddenExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden", "title": "Forbidden", "detail": "Access to requested resource forbidden" } ``` * **404** Not Found. The specified price book does not exist. Media type: `application/problem+json`. Schema: `PriceBookNotFoundErrorResponse`. _Example: PriceBookNotFoundErrorResponseExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/price-book-not-found", "detail": "The price book with ID 'USD-list-prices' was not found.", "title": "Price Book Not Found" } ``` ### PUT Create or replace a price book. `PUT /organizations/{organizationId}/price-books/{priceBookId}` Operation ID: `createOrUpdatePriceBook`. Security: AmOAuth2 (sfcc.price-books.rw). Create a new price book or replace an existing one using the information provided. When replacing an existing price book, the entire price book is replaced with the information in the request. The currency code is immutable and must match the existing value. Attempts to change the currency code will be rejected. #### Parameters * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `priceBookId` (path, PriceBookId, required) The price book ID. #### Request body (required) The price book Media type: `application/json`. Schema: `PriceBook`. _Example: CreatePriceBookRequest_ Create a new price book Example request body for creating a new price book with a currency code and validity window. Currency is immutable after creation. ``` { "id": "USD-list-prices", "displayName": "USD List Prices", "description": "Standard list prices for USD currency", "currencyCode": "USD", "online": true, "validFrom": "2024-01-01T00:00:00.000Z", "validTo": "2024-12-31T23:59:59.999Z" } ``` #### Responses * **200** Price book replaced successfully. Media type: `application/json`. Schema: `PriceBook`. _Example: PriceBookReplaced_ Price book replaced successfully Example of a price book returned after a successful replace via PUT /price-books/{priceBookId}, where the entire resource is replaced with the request body. ``` { "id": "USD-list-prices", "displayName": "USD List Prices", "description": "Standard list prices for USD currency", "currencyCode": "USD", "type": "standard", "online": true, "validFrom": "2024-01-01T00:00:00.000Z", "validTo": "2024-12-31T23:59:59.999Z", "creationDate": "2024-01-01T00:00:00.000Z", "lastModified": "2024-06-15T14:25:00.000Z" } ``` * **201** Price book created successfully. Media type: `application/json`. Schema: `PriceBook`. _Example: PriceBookCreated_ Price book created successfully Example of a price book returned after successful creation via PUT /price-books/{priceBookId}. ``` { "id": "USD-list-prices", "displayName": "USD List Prices", "description": "Standard list prices for USD currency", "currencyCode": "USD", "type": "standard", "online": true, "validFrom": "2024-01-01T00:00:00.000Z", "validTo": "2024-12-31T23:59:59.999Z", "creationDate": "2024-01-01T00:00:00.000Z", "lastModified": "2024-01-01T00:00:00.000Z" } ``` * **400** Bad Request. Returned when attempting to change an immutable field or create a parent cycle. Media type: `application/problem+json`. Schema: `CurrencyImmutableErrorResponse | ParentCycleDetectedErrorResponse`. One of: `CurrencyImmutableErrorResponse`, `ParentCycleDetectedErrorResponse`. _Example: CurrencyImmutableErrorResponseExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/currency-immutable", "detail": "The currency code of a price book cannot be changed after creation.", "title": "Currency Immutable" } ``` _Example: ParentCycleDetectedErrorResponseExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/parent-cycle-detected", "detail": "The specified parent price book would create a cycle in the price book hierarchy.", "title": "Parent Cycle Detected" } ``` * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: UnauthorizedExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized", "title": "Unauthorized", "detail": "Unauthorized request" } ``` * **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: ForbiddenExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden", "title": "Forbidden", "detail": "Access to requested resource forbidden" } ``` ### DELETE Delete a price book. `DELETE /organizations/{organizationId}/price-books/{priceBookId}` Operation ID: `deletePriceBook`. Security: AmOAuth2 (sfcc.price-books.rw). Delete a price book by ID. This operation permanently removes the price book and all its price book entries. Once deleted, the price book cannot be recovered. #### Parameters * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `priceBookId` (path, PriceBookId, required) The price book ID. #### Responses * **204** Price book deleted successfully. No content returned. * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: UnauthorizedExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized", "title": "Unauthorized", "detail": "Unauthorized request" } ``` * **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: ForbiddenExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden", "title": "Forbidden", "detail": "Access to requested resource forbidden" } ``` * **404** Not Found. The specified price book does not exist. Media type: `application/problem+json`. Schema: `PriceBookNotFoundErrorResponse`. _Example PriceBookNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/price-books/{priceBookId} 404 response._ ### PATCH Update a price book. `PATCH /organizations/{organizationId}/price-books/{priceBookId}` Operation ID: `updatePriceBook`. Security: AmOAuth2 (sfcc.price-books.rw). Update a price book with the specified information. Only the fields provided in the request body are updated. All other fields remain unchanged. The currency code is immutable and cannot be changed via PATCH. #### Parameters * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `priceBookId` (path, PriceBookId, required) The price book ID. #### Request body (required) The price book fields to update Media type: `application/json`. Schema: `PriceBook`. _Example: UpdatePriceBookRequest_ Update an existing price book Example request body for updating an existing price book. The currencyCode must match the existing value; attempts to change it are rejected. ``` { "id": "USD-list-prices", "currencyCode": "USD", "displayName": "USD List Prices - Updated", "description": "Updated standard list prices for USD currency", "online": false } ``` #### Responses * **200** Price book updated successfully. Media type: `application/json`. Schema: `PriceBook`. _Example: PriceBookUpdated_ Price book updated successfully Example of a price book returned after a successful partial update via PATCH /price-books/{priceBookId}. ``` { "id": "USD-list-prices", "displayName": "USD List Prices - Updated", "description": "Updated standard list prices for USD currency", "currencyCode": "USD", "online": false, "creationDate": "2024-01-01T00:00:00.000Z", "lastModified": "2024-06-15T14:25:00.000Z" } ``` * **400** Bad Request. Returned when attempting to change an immutable field or create a parent cycle. Media type: `application/problem+json`. Schema: `CurrencyImmutableErrorResponse | ParentCycleDetectedErrorResponse`. One of: `CurrencyImmutableErrorResponse`, `ParentCycleDetectedErrorResponse`. _Example CurrencyImmutableErrorResponseExample: same as PUT /organizations/{organizationId}/price-books/{priceBookId} 400 response._ _Example ParentCycleDetectedErrorResponseExample: same as PUT /organizations/{organizationId}/price-books/{priceBookId} 400 response._ * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: UnauthorizedExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized", "title": "Unauthorized", "detail": "Unauthorized request" } ``` * **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: ForbiddenExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden", "title": "Forbidden", "detail": "Access to requested resource forbidden" } ``` * **404** Not Found. The specified price book does not exist. Media type: `application/problem+json`. Schema: `PriceBookNotFoundErrorResponse`. _Example PriceBookNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/price-books/{priceBookId} 404 response._ ### GET Get price book entries. `GET /organizations/{organizationId}/price-books/{priceBookId}/price-book-entries` Operation ID: `getPriceBookEntries`. Security: AmOAuth2 (sfcc.price-books, sfcc.price-books.rw). Get a paginated list of price book entries for the specified price book. Returns all entries with their pricing information. Use the search endpoint for filtered queries. #### Parameters * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `priceBookId` (path, PriceBookId, required) The price book ID. * `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 50. Default: `50`. Minimum: 1. Maximum: 200. * `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset. Default: `0`. Minimum: 0. #### Responses * **200** Price book entries retrieved successfully. Media type: `application/json`. Schema: `PriceBookEntries`. _Example: PriceBookEntriesListResult_ Successful price book entries list retrieval Example of a paginated list of price book entries, showing both simple and tiered pricing. ``` { "limit": 25, "offset": 0, "total": 150, "data": [ { "productId": "product-001", "priceTables": [ { "tiers": [ { "type": "amount", "quantity": 1, "amount": { "currencyMnemonic": "USD", "value": 99.99 } } ] } ], "creationDate": "2024-01-01T00:00:00.000Z", "lastModified": "2024-01-01T00:00:00.000Z" }, { "productId": "product-002", "priceTables": [ { "validFrom": "2026-11-25T00:00:00.000Z", "validTo": "2026-11-28T23:59:59.999Z", "tiers": [ { "type": "amount", "quantity": 1, "amount": { "currencyMnemonic": "USD", "value": 39.99 } }, { "type": "amount", "quantity": 10, "amount": { "currencyMnemonic": "USD", "value": 34.99 } } ] } ], "creationDate": "2024-01-01T00:00:00.000Z", "lastModified": "2024-02-15T10:00:00.000Z" } ] } ``` * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: UnauthorizedExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized", "title": "Unauthorized", "detail": "Unauthorized request" } ``` * **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: ForbiddenExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden", "title": "Forbidden", "detail": "Access to requested resource forbidden" } ``` * **404** Not Found. The specified price book does not exist. Media type: `application/problem+json`. Schema: `PriceBookNotFoundErrorResponse`. _Example PriceBookNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/price-books/{priceBookId} 404 response._ ### GET Get a price book entry. `GET /organizations/{organizationId}/price-books/{priceBookId}/price-book-entries/{productId}` Operation ID: `getPriceBookEntry`. Security: AmOAuth2 (sfcc.price-books, sfcc.price-books.rw). Get a price book entry by product ID and price book ID. Returns the pricing information for a specific product in the price book, including tiered pricing if configured. #### Parameters * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `priceBookId` (path, PriceBookId, required) The price book ID. * `productId` (path, ProductId, required) The product ID. #### Responses * **200** Price book entry retrieved successfully. Media type: `application/json`. Schema: `PriceBookEntry`. _Example: PriceBookEntryRetrieved_ Price book entry retrieved successfully Example of a price book entry returned by GET /price-books/{priceBookId}/price-book-entries/{productId}. ``` { "productId": "product-001", "priceTables": [ { "tiers": [ { "type": "amount", "quantity": 1, "amount": { "currencyMnemonic": "USD", "value": 99.99 } } ] } ], "creationDate": "2024-01-01T00:00:00.000Z", "lastModified": "2024-01-15T10:30:00.000Z" } ``` * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: UnauthorizedExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized", "title": "Unauthorized", "detail": "Unauthorized request" } ``` * **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: ForbiddenExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden", "title": "Forbidden", "detail": "Access to requested resource forbidden" } ``` * **404** Not Found. The specified price book entry or price book does not exist. Media type: `application/problem+json`. Schema: `PriceBookEntryNotFoundErrorResponse | PriceBookNotFoundErrorResponse`. One of: `PriceBookEntryNotFoundErrorResponse`, `PriceBookNotFoundErrorResponse`. _Example PriceBookNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/price-books/{priceBookId} 404 response._ _Example: PriceBookEntryNotFoundErrorResponseExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/price-book-entry-not-found", "detail": "The price book entry for product 'apple-ipod-classic' in price book 'USD-list-prices' was not found.", "title": "Price Book Entry Not Found" } ``` ### PUT Create or replace a price book entry. `PUT /organizations/{organizationId}/price-books/{priceBookId}/price-book-entries/{productId}` Operation ID: `createOrUpdatePriceBookEntry`. Security: AmOAuth2 (sfcc.price-books.rw). Create a new price book entry or replace an existing one using the information provided. When replacing an existing entry, the entire entry is replaced with the information in the request. The priceTables array, if provided, replaces any existing tiered pricing. #### Parameters * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `priceBookId` (path, PriceBookId, required) The price book ID. * `productId` (path, ProductId, required) The product ID. #### Request body (required) The price book entry Media type: `application/json`. Schema: `PriceBookEntry`. _Example: CreatePriceBookEntryRequest_ Create or update a price book entry Example request body for creating or replacing a price book entry via PUT upsert with a single amount tier. ``` { "productId": "product-001", "priceTables": [ { "tiers": [ { "type": "amount", "quantity": 1, "amount": { "currencyMnemonic": "USD", "value": 99.99 } } ] } ] } ``` _Example: CreatePriceBookEntryWithTiersRequest_ Create a price book entry with tiered pricing Example request body creating an entry with time-scoped price tables and both absolute and percentage tiers. On PATCH, the priceTables array is replaced wholesale. ``` { "productId": "product-002", "priceTables": [ { "validFrom": "2026-11-25T00:00:00.000Z", "validTo": "2026-11-28T23:59:59.999Z", "tiers": [ { "type": "amount", "quantity": 1, "amount": { "currencyMnemonic": "USD", "value": 39.99 } }, { "type": "amount", "quantity": 10, "amount": { "currencyMnemonic": "USD", "value": 34.99 } } ] }, { "validFrom": "2026-12-01T00:00:00.000Z", "tiers": [ { "type": "amount", "quantity": 1, "amount": { "currencyMnemonic": "USD", "value": 49.99 } }, { "type": "percentage", "quantity": 10, "percentage": 15 } ] } ] } ``` #### Responses * **200** Price book entry replaced successfully. Media type: `application/json`. Schema: `PriceBookEntry`. _Example: PriceBookEntryReplaced_ Price book entry replaced successfully Example of a price book entry returned after a successful replace via PUT /price-books/{priceBookId}/price-book-entries/{productId}, where the entire entry is replaced with the request body. ``` { "productId": "product-001", "priceTables": [ { "tiers": [ { "type": "amount", "quantity": 1, "amount": { "currencyMnemonic": "USD", "value": 89.99 } } ] } ], "creationDate": "2024-01-01T00:00:00.000Z", "lastModified": "2024-06-15T14:35:00.000Z" } ``` * **201** Price book entry created successfully. Media type: `application/json`. Schema: `PriceBookEntry`. _Example: PriceBookEntryCreated_ Price book entry created successfully Example of a price book entry returned after successful creation via PUT upsert. ``` { "productId": "product-001", "priceTables": [ { "tiers": [ { "type": "amount", "quantity": 1, "amount": { "currencyMnemonic": "USD", "value": 99.99 } } ] } ], "creationDate": "2024-06-15T14:30:00.000Z", "lastModified": "2024-06-15T14:30:00.000Z" } ``` * **400** Bad Request. Returned when the request contains invalid data. Beyond generic schema validation, the following business-logic validations return distinct error types: an invalid time range (validTo before validFrom), a tier currency that does not match the price book currency, and duplicate tier quantities within a single price table. Media type: `application/problem+json`. Schema: `ValidationErrorResponse | InvalidTimeRangeErrorResponse | TierCurrencyMismatchErrorResponse | DuplicateTierQuantityErrorResponse`. One of: `ValidationErrorResponse`, `InvalidTimeRangeErrorResponse`, `TierCurrencyMismatchErrorResponse`, `DuplicateTierQuantityErrorResponse`. _Example: ValidationErrorResponseExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/validation", "detail": "The request body is malformed or contains invalid data.", "title": "Validation" } ``` _Example: InvalidTimeRangeErrorResponseExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-time-range", "detail": "The time range is invalid: 'validTo' must not be before 'validFrom'.", "title": "Invalid Time Range" } ``` _Example: TierCurrencyMismatchErrorResponseExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/tier-currency-mismatch", "detail": "The tier currency 'USD' does not match the price book currency 'USD'.", "title": "Tier Currency Mismatch" } ``` _Example: DuplicateTierQuantityErrorResponseExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/duplicate-tier-quantity", "detail": "Duplicate tier quantity '10' within a single price table. Each tier in a price table must have a distinct quantity.", "title": "Duplicate Tier Quantity" } ``` * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: UnauthorizedExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized", "title": "Unauthorized", "detail": "Unauthorized request" } ``` * **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: ForbiddenExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden", "title": "Forbidden", "detail": "Access to requested resource forbidden" } ``` * **404** Not Found. The specified price book or product does not exist. Media type: `application/problem+json`. Schema: `PriceBookNotFoundErrorResponse | ProductNotFoundErrorResponse`. One of: `PriceBookNotFoundErrorResponse`, `ProductNotFoundErrorResponse`. _Example PriceBookNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/price-books/{priceBookId} 404 response._ _Example: ProductNotFoundErrorResponseExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/product-not-found", "detail": "The product with ID 'apple-ipod-classic' was not found.", "title": "Product Not Found" } ``` * **422** Unprocessable Entity. Price book entry write operations are not supported for a `feed_based` price book, whose entries are sourced from an external feed pipeline. The price book container itself remains editable. Media type: `application/problem+json`. Schema: `FeedBasedPriceBookNotSupportedErrorResponse`. _Example: FeedBasedPriceBookNotSupportedErrorResponseExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/feed-based-price-book-not-supported", "detail": "Price book entry write operations are not supported for the feed-based price book 'USD-list-prices'. Its price entries are sourced from an external feed pipeline.", "title": "Feed Based Price Book Not Supported" } ``` ### DELETE Delete a price book entry. `DELETE /organizations/{organizationId}/price-books/{priceBookId}/price-book-entries/{productId}` Operation ID: `deletePriceBookEntry`. Security: AmOAuth2 (sfcc.price-books.rw). Delete a price book entry by product ID and price book ID. This operation permanently removes the price book entry. Once deleted, the entry is not recoverable; a subsequent PUT for the same product creates a new entry rather than restoring the deleted one. #### Parameters * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `priceBookId` (path, PriceBookId, required) The price book ID. * `productId` (path, ProductId, required) The product ID. #### Responses * **204** Price book entry deleted successfully. No content returned. * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: UnauthorizedExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized", "title": "Unauthorized", "detail": "Unauthorized request" } ``` * **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: ForbiddenExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden", "title": "Forbidden", "detail": "Access to requested resource forbidden" } ``` * **404** Not Found. The specified price book entry or price book does not exist. Media type: `application/problem+json`. Schema: `PriceBookEntryNotFoundErrorResponse | PriceBookNotFoundErrorResponse`. One of: `PriceBookEntryNotFoundErrorResponse`, `PriceBookNotFoundErrorResponse`. _Example PriceBookEntryNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/price-books/{priceBookId}/price-book-entries/{productId} 404 response._ _Example PriceBookNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/price-books/{priceBookId} 404 response._ * **422** Unprocessable Entity. Price book entry write operations are not supported for a `feed_based` price book, whose entries are sourced from an external feed pipeline. The price book container itself remains editable. Media type: `application/problem+json`. Schema: `FeedBasedPriceBookNotSupportedErrorResponse`. _Example FeedBasedPriceBookNotSupportedErrorResponseExample: same as PUT /organizations/{organizationId}/price-books/{priceBookId}/price-book-entries/{productId} 422 response._ ### PATCH Update a price book entry. `PATCH /organizations/{organizationId}/price-books/{priceBookId}/price-book-entries/{productId}` Operation ID: `updatePriceBookEntry`. Security: AmOAuth2 (sfcc.price-books.rw). Update a price book entry with the specified information. Only the fields provided in the request body are updated. All other fields remain unchanged. The priceTables array, if provided, replaces the existing tiered pricing wholesale. #### Parameters * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `priceBookId` (path, PriceBookId, required) The price book ID. * `productId` (path, ProductId, required) The product ID. #### Request body (required) The price book entry fields to update Media type: `application/json`. Schema: `PriceBookEntry`. _Example: UpdatePriceBookEntryRequest_ Update a price book entry Example partial update via PATCH; the priceTables array provided replaces the entry's existing tables wholesale. ``` { "productId": "product-001", "priceTables": [ { "tiers": [ { "type": "amount", "quantity": 1, "amount": { "currencyMnemonic": "USD", "value": 89.99 } } ] } ] } ``` #### Responses * **200** Price book entry updated successfully. Media type: `application/json`. Schema: `PriceBookEntry`. _Example PriceBookEntryUpdated: same as PUT /organizations/{organizationId}/price-books/{priceBookId}/price-book-entries/{productId} 200 response._ Price book entry updated successfully Example of a price book entry returned after a successful partial update via PATCH /price-books/{priceBookId}/price-book-entries/{productId}. _Example: PriceBookEntryUpdated_ Price book entry updated successfully Example of a price book entry returned after a successful partial update via PATCH /price-books/{priceBookId}/price-book-entries/{productId}. * **400** Bad Request. Returned when the request contains invalid data. Beyond generic schema validation, the following business-logic validations return distinct error types: an invalid time range (validTo before validFrom), a tier currency that does not match the price book currency, and duplicate tier quantities within a single price table. Media type: `application/problem+json`. Schema: `ValidationErrorResponse | InvalidTimeRangeErrorResponse | TierCurrencyMismatchErrorResponse | DuplicateTierQuantityErrorResponse`. One of: `ValidationErrorResponse`, `InvalidTimeRangeErrorResponse`, `TierCurrencyMismatchErrorResponse`, `DuplicateTierQuantityErrorResponse`. _Example InvalidTimeRangeErrorResponseExample: same as PUT /organizations/{organizationId}/price-books/{priceBookId}/price-book-entries/{productId} 400 response._ _Example TierCurrencyMismatchErrorResponseExample: same as PUT /organizations/{organizationId}/price-books/{priceBookId}/price-book-entries/{productId} 400 response._ _Example DuplicateTierQuantityErrorResponseExample: same as PUT /organizations/{organizationId}/price-books/{priceBookId}/price-book-entries/{productId} 400 response._ _Example: ValidationErrorResponseExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/validation", "detail": "The request body is malformed or contains invalid data.", "title": "Validation" } ``` * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: UnauthorizedExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized", "title": "Unauthorized", "detail": "Unauthorized request" } ``` * **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: ForbiddenExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden", "title": "Forbidden", "detail": "Access to requested resource forbidden" } ``` * **404** Not Found. The specified price book entry or price book does not exist. Media type: `application/problem+json`. Schema: `PriceBookEntryNotFoundErrorResponse | PriceBookNotFoundErrorResponse`. One of: `PriceBookEntryNotFoundErrorResponse`, `PriceBookNotFoundErrorResponse`. _Example PriceBookEntryNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/price-books/{priceBookId}/price-book-entries/{productId} 404 response._ _Example PriceBookNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/price-books/{priceBookId} 404 response._ * **422** Unprocessable Entity. Price book entry write operations are not supported for a `feed_based` price book, whose entries are sourced from an external feed pipeline. The price book container itself remains editable. Media type: `application/problem+json`. Schema: `FeedBasedPriceBookNotSupportedErrorResponse`. _Example FeedBasedPriceBookNotSupportedErrorResponseExample: same as PUT /organizations/{organizationId}/price-books/{priceBookId}/price-book-entries/{productId} 422 response._ ### GET Get price book site assignments. `GET /organizations/{organizationId}/price-books/{priceBookId}/site-assignments` Operation ID: `getPriceBookSiteAssignments`. Security: AmOAuth2 (sfcc.price-books, sfcc.price-books.rw). Get the list of sites the specified price book is assigned to. A price book resolves prices only on the sites it is assigned to, so this is the set of sites on which the book is live. The list is bounded and is not paginated. The same information is also available as the read-only `siteAssignments` field on the price book itself. #### Parameters * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `priceBookId` (path, PriceBookId, required) The price book ID. #### Responses * **200** Site assignments retrieved successfully. Media type: `application/json`. Schema: `SiteAssignments`. _Example: SiteAssignmentsListResult_ Site assignments retrieved successfully Example of the list of sites a price book is assigned to, returned by GET /price-books/{priceBookId}/site-assignments. ``` { "limit": 2, "total": 2, "data": [ { "id": "RefArch", "displayName": "RefArch Store" }, { "id": "RefArchGlobal", "displayName": "RefArch Global" } ] } ``` * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: UnauthorizedExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized", "title": "Unauthorized", "detail": "Unauthorized request" } ``` * **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: ForbiddenExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden", "title": "Forbidden", "detail": "Access to requested resource forbidden" } ``` * **404** Not Found. The specified price book does not exist. Media type: `application/problem+json`. Schema: `PriceBookNotFoundErrorResponse`. _Example PriceBookNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/price-books/{priceBookId} 404 response._ ### PUT Assign a price book to a site. `PUT /organizations/{organizationId}/price-books/{priceBookId}/site-assignments/{siteId}` Operation ID: `createOrUpdatePriceBookSiteAssignment`. Security: AmOAuth2 (sfcc.price-books.rw). Assign the specified price book to the specified site, making the book live on that site. The assignment is idempotent and fully specified by the path, so no request body is required. Returns `201 Created` when the price book was not previously assigned to the site, and `200 OK` when the assignment already existed. This is a container-level operation and is therefore permitted for both `standard` and `feed_based` price books. #### Parameters * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `priceBookId` (path, PriceBookId, required) The price book ID. * `siteId` (path, SiteId, required) The ID of the site the price book is assigned to. #### Responses * **200** The price book was already assigned to the site. Media type: `application/json`. Schema: `SiteAssignment`. _Example: SiteAssignmentUpdated_ Price book site assignment confirmed Example of a site assignment returned when the price book was already assigned to the site (200) via PUT /price-books/{priceBookId}/site-assignments/{siteId}. ``` { "id": "RefArch", "displayName": "RefArch Store" } ``` * **201** The price book was assigned to the site successfully. Media type: `application/json`. Schema: `SiteAssignment`. _Example: SiteAssignmentCreated_ Price book assigned to site successfully Example of a site assignment returned after binding a price book to a site that was not previously assigned (201) via PUT /price-books/{priceBookId}/site-assignments/{siteId}. ``` { "id": "RefArch", "displayName": "RefArch Store" } ``` * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: UnauthorizedExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized", "title": "Unauthorized", "detail": "Unauthorized request" } ``` * **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: ForbiddenExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden", "title": "Forbidden", "detail": "Access to requested resource forbidden" } ``` * **404** Not Found. The specified price book or site does not exist. Media type: `application/problem+json`. Schema: `PriceBookNotFoundErrorResponse | SiteNotFoundErrorResponse`. One of: `PriceBookNotFoundErrorResponse`, `SiteNotFoundErrorResponse`. _Example PriceBookNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/price-books/{priceBookId} 404 response._ _Example: SiteNotFoundErrorResponseExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/site-not-found", "detail": "The site with ID 'RefArch' was not found.", "title": "Site Not Found" } ``` ### DELETE Unassign a price book from a site. `DELETE /organizations/{organizationId}/price-books/{priceBookId}/site-assignments/{siteId}` Operation ID: `deletePriceBookSiteAssignment`. Security: AmOAuth2 (sfcc.price-books.rw). Remove the assignment of the specified price book from the specified site, so the book is no longer live on that site. This is a container-level operation and is therefore permitted for both `standard` and `feed_based` price books. No content is returned. #### Parameters * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `priceBookId` (path, PriceBookId, required) The price book ID. * `siteId` (path, SiteId, required) The ID of the site the price book is assigned to. #### Responses * **204** Site assignment removed successfully. No content returned. * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: UnauthorizedExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized", "title": "Unauthorized", "detail": "Unauthorized request" } ``` * **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: ForbiddenExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden", "title": "Forbidden", "detail": "Access to requested resource forbidden" } ``` * **404** Not Found. The specified price book or site does not exist. Media type: `application/problem+json`. Schema: `PriceBookNotFoundErrorResponse | SiteNotFoundErrorResponse`. One of: `PriceBookNotFoundErrorResponse`, `SiteNotFoundErrorResponse`. _Example PriceBookNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/price-books/{priceBookId} 404 response._ _Example: SiteNotFoundErrorResponseExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/site-not-found", "detail": "The site with ID 'RefArch' was not found.", "title": "Site Not Found" } ``` ### POST Search for price books. `POST /organizations/{organizationId}/price-book-search` Operation ID: `searchPriceBooks`. Security: AmOAuth2 (sfcc.price-books, sfcc.price-books.rw). Searches for price books. The query attribute specifies a complex query that can be used to narrow down the search. These are the searchable attributes: * id - String * displayName - String * description - String * currencyCode - String * parent - String * validFrom - DateTime * validTo - DateTime * online - Boolean * siteId - String The output of the query can also be sorted. These are the sortable attributes: * id - String * displayName - String * description - String * currencyCode - String * parent - String * validFrom - DateTime * validTo - DateTime * online - Boolean #### Parameters * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` #### Request body (required) The search request document Media type: `application/json`. Schema: `PriceBookSearchRequest`. _Example: PriceBookSearchRequestBody_ Basic price book search request Example of a text-query search that returns price books whose id or displayName contains "USD", sorted by id ascending. ``` { "limit": 10, "offset": 0, "query": { "textQuery": { "fields": [ "id", "displayName" ], "searchPhrase": "USD" } }, "sorts": [ { "field": "id", "sortOrder": "asc" } ] } ``` _Example: PriceBookSearchRequestWithFilter_ Price book search with term query filter Example of a boolean-query search combining term filters for currencyCode and online, sorted by displayName ascending. ``` { "limit": 25, "offset": 0, "query": { "boolQuery": { "must": [ { "termQuery": { "fields": [ "currencyCode" ], "operator": "is", "values": [ "USD" ] } }, { "termQuery": { "fields": [ "online" ], "operator": "is", "values": [ true ] } } ] } }, "sorts": [ { "field": "displayName", "sortOrder": "asc" } ] } ``` #### Responses * **200** Price books searched successfully. Media type: `application/json`. Schema: `PriceBookSearchResult`. _Example: PriceBookSearchResult_ Successful price book search result Example of a successful price book search response with pagination, sorting, and multiple hits. ``` { "limit": 3, "offset": 0, "total": 10, "query": { "textQuery": { "fields": [ "id", "displayName" ], "searchPhrase": "USD" } }, "sorts": [ { "field": "id", "sortOrder": "asc" } ], "hits": [ { "id": "USD-list-prices", "displayName": "USD List Prices", "description": "Standard list prices for USD currency", "currencyCode": "USD", "online": true, "validFrom": "2024-01-01T00:00:00.000Z", "validTo": "2024-12-31T23:59:59.999Z", "creationDate": "2024-01-01T00:00:00.000Z", "lastModified": "2024-01-15T10:30:00.000Z" }, { "id": "USD-sale-prices", "displayName": "USD Sale Prices", "description": "Promotional sale prices for USD currency", "currencyCode": "USD", "parent": "USD-list-prices", "online": true, "validFrom": "2024-06-01T00:00:00.000Z", "validTo": "2024-08-31T23:59:59.999Z", "creationDate": "2024-05-15T00:00:00.000Z", "lastModified": "2024-06-01T08:00:00.000Z" }, { "id": "USD-vip-prices", "displayName": "USD VIP Prices", "description": "Special prices for VIP customers in USD", "currencyCode": "USD", "parent": "USD-list-prices", "online": true, "creationDate": "2024-02-01T00:00:00.000Z", "lastModified": "2024-02-10T14:20:00.000Z" } ] } ``` * **400** Bad Request. Returned when the search query is malformed or contains invalid fields. Media type: `application/problem+json`. Schema: `MalformedSearchParameterErrorResponse | UnqueryableFieldErrorResponse | FieldNotSortableErrorResponse`. One of: `MalformedSearchParameterErrorResponse`, `UnqueryableFieldErrorResponse`, `FieldNotSortableErrorResponse`. _Example: MalformedSearchParameterErrorResponseExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/malformed-search-parameter", "detail": "The search query contains invalid syntax. Please check the query structure and try again.", "title": "Malformed Search Parameter" } ``` _Example: UnqueryableFieldErrorResponseExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unqueryable-field", "detail": "The field 'invalid_field' is not a searchable attribute for price books. Valid fields are: id, displayName, description, currencyCode, parent, validFrom, validTo, online, siteId.", "title": "Unqueryable Field" } ``` _Example: FieldNotSortableErrorResponseExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/field-not-sortable", "detail": "The field 'invalid_sort' is not a sortable attribute for price books. Valid sortable fields are: id, displayName, description, currencyCode, parent, validFrom, validTo, online.", "title": "Field Not Sortable" } ``` * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: UnauthorizedExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized", "title": "Unauthorized", "detail": "Unauthorized request" } ``` * **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: ForbiddenExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden", "title": "Forbidden", "detail": "Access to requested resource forbidden" } ``` ## Schemas ### OrganizationId An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). Type: `string`. Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`. ### PriceBooks Document representing a paginated list of price books. Includes all fields of `PaginatedResultBase`. * `data` (_array of PriceBook_, required) The collection of price books. Maximum items: 50. ### InvalidQueryParameterErrorResponse Returned when a specified query parameter value is invalid. Includes all fields of `ErrorResponse`. ### ErrorResponse * `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization Maximum length: 256. Example: `You do not have enough credit`. * `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5. Maximum length: 2048. Example: `NotEnoughMoney`. * `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem. Example: `Your current balance is 30, but that costs 50`. * `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5. Maximum length: 2048. Example: `/account/12345/msgs/abc`. ### PriceBookId The ID of the price book. Type: `string`. Minimum length: 1. Maximum length: 256. Example: `USD-list-prices`. ### PriceBook Document representing a price book. * `id` (_object_, required) Includes all fields of `PriceBookId`. * `displayName` (_string_) The display name of the price book. Maximum length: 256. Example: `USD List Prices`. * `description` (_string_) The detailed description of the price book. Maximum length: 4000. Example: `Standard list prices for USD currency`. * `currencyCode` (_object_, required) The currency used by the price book. This can be specified only on create. Includes all fields of `CurrencyCode`. * `type` (_string_, read-only) The price book type. 'standard' price books are fully editable via this API. For 'feed\_based' price books, the price entries are sourced from an external feed pipeline: the price book container itself (its metadata, such as displayName, description, online, and validity dates) remains editable via this API, but price book entry write operations against a feed\_based price book are rejected. This is a read-only, server-assigned attribute; price books created via this API are always 'standard'. Allowed values: `standard`, `feed_based`. Example: `standard`. * `parent` (_object_) The ID of another price book which is the base for this price book. Includes all fields of `PriceBookId`. * `validFrom` (_string (date-time)_) The validity start date and time of the price book. Example: `2024-01-01T00:00:00.000Z`. * `validTo` (_string (date-time)_) The validity end date and time of the price book. Example: `2024-12-31T23:59:59.999Z`. * `online` (_boolean_) Specifies whether the price book is online (true) or not (false). If unspecified on create, the default value is false. Example: `true`. * `siteAssignments` (_array of SiteAssignment_, read-only) The list of sites to which the price book is assigned. This is a read-only computed attribute; assignments are managed via the site-assignment endpoints on this price book (PUT/DELETE /price-books/{priceBookId}/site-assignments/{siteId}). Maximum items: 100. * `creationDate` (_string (date-time)_, read-only) The date and time the price book was created. Example: `2024-01-01T00:00:00.000Z`. * `lastModified` (_string (date-time)_, read-only) The date and time the price book was last modified. Example: `2024-01-15T10:30:00.000Z`. Additional properties: `any`. Additional Property Support This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix. Example: `c_trackingId`. ### PriceBookNotFoundErrorResponse Returned when the specified price book does not exist. Includes all fields of `ErrorResponse`. * `priceBookId` (_PriceBookId_) ### CurrencyImmutableErrorResponse Returned when attempting to change the currency code of an existing price book. Includes all fields of `ErrorResponse`. ### ParentCycleDetectedErrorResponse Returned when a price book parent relationship would create a cycle. Includes all fields of `ErrorResponse`. ### PriceBookEntries Document representing a paginated list of price book entries. Includes all fields of `PaginatedResultBase`. * `data` (_array of PriceBookEntry_, required) The collection of price book entries. Maximum items: 200. ### ProductId The id (SKU) of the product. Type: `string`. Minimum length: 1. Maximum length: 100. Example: `apple-ipod-classic`. ### PriceBookEntry Document representing a price book entry. A price book entry has a composite identity of (priceBookId, productId); there is no standalone POST endpoint, use PUT for upsert. * `productId` (_object_, required) The product ID for this price book entry. Includes all fields of `ProductId`. * `priceTables` (_array of PriceScaleTable_) The list of price scale tables for this product. Each table carries its own validity window and a set of quantity-based tiers. Multiple tables let a merchandiser define overlapping schedules (for example, Black Friday prices alongside regular prices) for the same product in the same price book. Maximum items: 10. * `creationDate` (_string (date-time)_, read-only) The date and time the price book entry was created. Example: `2024-01-01T00:00:00.000Z`. * `lastModified` (_string (date-time)_, read-only) The date and time the price book entry was last modified. Example: `2024-01-15T10:30:00.000Z`. Additional properties: `any`. Additional Property Support This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix. Example: `c_trackingId`. ### PriceBookEntryNotFoundErrorResponse Returned when the specified price book entry does not exist. Includes all fields of `ErrorResponse`. * `priceBookId` (_PriceBookId_) * `productId` (_ProductId_) ### ValidationErrorResponse Returned when the request body fails validation. Includes all fields of `ErrorResponse`. ### InvalidTimeRangeErrorResponse Returned when a time range is invalid because its end (validTo) precedes its start (validFrom); for example, a price scale table's validity window. Includes all fields of `ErrorResponse`. ### TierCurrencyMismatchErrorResponse Returned when a price scale tier specifies a currency that differs from the enclosing price book's currency. Includes all fields of `ErrorResponse`. * `tierCurrency` (_CurrencyCode_) * `priceBookCurrency` (_CurrencyCode_) ### DuplicateTierQuantityErrorResponse Returned when two or more tiers in the same price scale table declare the same quantity, which the backend keys tiers by. Includes all fields of `ErrorResponse`. * `quantity` (_integer (int32)_) The duplicated tier quantity. Minimum: 1. Maximum: 1000000. Example: `10`. ### ProductNotFoundErrorResponse Returned when the specified product does not exist. Includes all fields of `ErrorResponse`. * `productId` (_ProductId_) ### FeedBasedPriceBookNotSupportedErrorResponse Returned when attempting a price book entry write against a feed\_based price book. Includes all fields of `ErrorResponse`. * `priceBookId` (_PriceBookId_) ### SiteAssignments Document representing the list of site assignments on a price book. The list is bounded (a price book is live on a small set of sites) and is not paginated. Includes all fields of `ResultBase`. * `data` (_array of SiteAssignment_, required) The collection of sites the price book is assigned to. Maximum items: 100. ### SiteId The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites Type: `string`. Minimum length: 1. Maximum length: 32. Example: `RefArch`. ### SiteAssignment Document representing a site assignment on a price book. * `id` (_object_, required) Includes all fields of `SiteId`. * `displayName` (_string_) The display name of the site. Maximum length: 256. Example: `RefArch Store`. ### SiteNotFoundErrorResponse Returned when the site referenced by a site-assignment operation does not exist. Includes all fields of `ErrorResponse`. * `siteId` (_SiteId_) ### PriceBookSearchRequest Document representing a search request for price books. The query is a potentially complex set of expressions. Searchable attributes: * id (String) * displayName (String) * description (String) * currencyCode (String) * parent (String) * validFrom (DateTime) * validTo (DateTime) * online (Boolean) * siteId (String) Sortable attributes: * id (String) * displayName (String) * description (String) * currencyCode (String) * parent (String) * validFrom (DateTime) * validTo (DateTime) * online (Boolean) Includes all fields of `SearchRequest`. _Example_ ``` { "limit": 2, "query": { "textQuery": { "fields": [ "id", "description" ], "searchPhrase": "USD" } }, "offset": 0 } ``` ### PriceBookSearchResult Document representing a price book search result. Includes all fields of `PaginatedSearchResult`. * `hits` (_array of PriceBook_, required) The sorted array of price book search hits. The array can be empty if there are no hits. Maximum items: 200. _Example_ ``` { "limit": 2, "offset": 0, "total": 10, "query": { "textQuery": { "fields": [ "id", "displayName" ], "searchPhrase": "USD" } }, "hits": [ { "id": "USD-list-prices", "displayName": "USD List Prices", "currencyCode": "USD", "online": true }, { "id": "USD-sale-prices", "displayName": "USD Sale Prices", "currencyCode": "USD", "online": true } ] } ``` ### MalformedSearchParameterErrorResponse Returned when the search query is malformed or invalid. Includes all fields of `ErrorResponse`. ### UnqueryableFieldErrorResponse Returned when a search query uses a field that is not searchable. Includes all fields of `ErrorResponse`. * `field` (_string_) The field name that is not searchable. Maximum length: 256. Example: `invalid_field`. ### FieldNotSortableErrorResponse Returned when a search query sorts on a field that is not sortable. Includes all fields of `ErrorResponse`. * `field` (_string_) The field name that is not sortable. Maximum length: 256. Example: `invalid_sort`. ### PaginatedResultBase Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`. Includes all fields of `ResultBase`. * `offset` (_Offset_, required) ### CurrencyCode A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable. Type: `string`. Pattern: ^(\[A-Z\]\[A-Z\]\[A-Z\]|N/A)$. Example: `USD`. ### PriceScaleTable A price scale table associates a validity window with a set of quantity tiers. A single price book entry can have multiple tables to express overlapping pricing schedules for the same product. * `validFrom` (_string (date-time)_) The start of the validity window during which this price scale table applies. If omitted, the table is valid immediately. Example: `2026-11-25T00:00:00.000Z`. * `validTo` (_string (date-time)_) The end of the validity window during which this price scale table applies. If omitted, the table is valid indefinitely. Example: `2026-11-28T23:59:59.999Z`. * `tiers` (_array of PriceScaleEntry_, required) The quantity-based tiers for this table. On PUT the table is replaced wholesale; individual tiers cannot be updated independently. Minimum items: 1. Maximum items: 20. ### ResultBase Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned. * `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema. Example: `10`. * `total` (_Total_, required) ### SearchRequest Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource. * `limit` (_integer (int32)_) Maximum records to retrieve per request, not to exceed 200. Minimum: 1. Maximum: 200. Example: `10`. * `query` (_Query_, required) * `sorts` (_array of Sort_) The list of sort clauses configured for the search request. Sort clauses are optional. See the description of the search endpoint for details on the default sorting behavior that is used when explicit sorts are not passed. * `offset` (_Offset_) ### PaginatedSearchResult Document representing a generic search result. Each search resource should extend this to define what is returned in the `hits`. Includes all fields of `PaginatedResultBase`. * `query` (_Query_, required) * `sorts` (_array of Sort_) The sorting that was applied to the result. * `hits` (_array of object_) The sorted array of search hits. Can be empty. _Example_ ``` { "limit": 1, "hits": [ { "couponId": "coupon1", "creationDate": "2019-10-20T12:00:00Z", "description": "This coupon is used to give 10% off stuff.", "enabled": false, "exportedCodeCount": 0, "lastModified": "2019-10-30T04:23:59Z", "redemptionCount": 3, "redemptionLimits": { "limitPerCode": 1, "limitPerCustomer": 1, "limitPerTimeFrame": { "limit": 2, "redemptionTimeFrame": 24 } }, "singleCode": "MyCode", "systemCodesConfig": { "codePrefix": "SG", "numberOfCodes": 500000 }, "totalCodesCount": 50, "type": "single_code" } ], "query": { "textQuery": { "fields": [ "id", "description" ], "searchPhrase": "stuff" } }, "sorts": [ { "field": "couponId", "sortOrder": "desc" } ], "offset": 2, "total": 8 } ``` ### Offset The zero-based index of the first hit/data to include in the result. Type: `integer (int32)`. Default: `0`. Minimum: 0. Example: `0`. ### PriceScaleEntry A single quantity tier within a price scale table. A tier is either an absolute monetary amount or a percentage discount, discriminated by the 'type' property. Discriminator: `type` selects the concrete type. Mapping: `amount` → `PriceScaleAmount`, `percentage` → `PriceScalePercentage`. One of: `PriceScaleAmount`, `PriceScalePercentage`. ### Total The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated. Type: `integer (int32)`. Default: `0`. Minimum: 0. Example: `10`. ### Query A set of objects that define criteria used to select records. A query can contain one of the following: * `MatchAllQuery` * Matches all documents. * `TermQuery` * Matches one or more documents against one or more document fields. * `TextQuery` * Matches text against one or more fields. * `BoolQuery` * Allows construction of a logical expression of multiple queries. * `FilteredQuery` * Allows a filter to be applied to a query. * `NestedQuery` * Allows you to query on nested documents. * _Only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation._ Minimum properties: 1. Maximum properties: 1. * `boolQuery` (_BoolQuery_) * `filteredQuery` (_FilteredQuery_) * `matchAllQuery` (_MatchAllQuery_) * `nestedQuery` (_NestedQuery_) * `termQuery` (_TermQuery_) * `textQuery` (_TextQuery_) _Example_ ``` { "filteredQuery": { "query": { "textQuery": { "fields": [ "couponId" ], "searchPhrase": "disabled" } }, "filter": { "termFilter": { "field": "enabled", "operator": "is", "values": [ false ] } } } } ``` ### Sort Document representing a sort request. Each API has a different default sort configuration that can be modified in the request. * `field` (_string_, required) The name of the field to sort on. Maximum length: 256. Example: `couponId`. * `sortOrder` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (asc) is used. Allowed values: `asc`, `desc`. Default: `asc`. Example: `asc`. _Example_ ``` { "field": "couponId", "sortOrder": "desc" } ``` ### PriceScaleAmount A quantity tier priced as an absolute monetary amount. * `type` (_string_, required) Discriminator value identifying this tier as an absolute monetary amount. Allowed values: `amount`. Example: `amount`. * `quantity` (_integer (int32)_, required) The minimum quantity required for this tier. Minimum: 1. Maximum: 1000000. Example: `10`. * `amount` (_object_, required) The tier price as a Money object (amount and currency). The value must not be negative. The currency must match the enclosing price book's currency. Includes all fields of `NonNegativeMoney`. ### PriceScalePercentage A quantity tier priced as a percentage discount. * `type` (_string_, required) Discriminator value identifying this tier as a percentage discount. Allowed values: `percentage`. Example: `percentage`. * `quantity` (_integer (int32)_, required) The minimum quantity required for this tier. Minimum: 1. Maximum: 1000000. Example: `10`. * `percentage` (_number (double)_, required) The percentage discount for this tier, expressed as a number between 0 and 100. Minimum: 0. Maximum: 100. Example: `15`. ### BoolQuery A boolean query allows construction of full logical expression trees that are composed of other queries (usually term queries and text queries). A boolean query has three sets of clauses: * `must`, which combines as an `AND` operator. * `should`, which combines as an `OR` operator. * `must_not`, which combines as a `NOT` operator. If `must`, `mustNot`, or `should` appear in the same boolean query, they are combined logically using the `AND` operator. For example: ``` (must-1 AND must-1 AND ...) AND (should-1 OR should-2 OR ...) AND NOT (must_not-1 OR must_not-2 OR ...) ``` * `must` (_array of Query_) List of queries to be evaluated as an `AND` operator. * `mustNot` (_array of Query_) List of queries to be evaluated as a `NOT` operator. * `should` (_array of Query_) List of queries to be evaluated as an `OR` operator. _Example_ ``` { "must": [ { "textQuery": { "fields": [ "couponId" ], "searchPhrase": "DEAL" } }, { "textQuery": { "fields": [ "description" ], "searchPhrase": "Big bargain deal" } } ], "mustNot": [ { "termQuery": { "fields": [ "enabled" ], "operator": "is", "values": [ false ] } } ] } ``` ### FilteredQuery Allows to filter the result of a possibly complex query using a possibly complex filter. * `filter` (_Filter_, required) * `query` (_Query_, required) _Example_ ``` { "query": { "textQuery": { "fields": [ "couponId" ], "searchPhrase": "disabled" } }, "filter": { "termFilter": { "field": "enabled", "operator": "is", "values": [ false ] } } } ``` ### MatchAllQuery Matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints. ### NestedQuery Allows you to query nested documents that are part of a larger document. Say, for example, that you have a main product with variations in one big document, and you want to constrain a search to main products that have variations that match multiple constraints. A `NestedQuery` is only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation. * `path` (_string_, required) The path to the nested document. Maximum length: 2048. Example: `order.shippingAddresses`. * `query` (_Query_, required) * `scoreMode` (_string_) Indicates how scores for matching child objects affect the root parent document’s relevance score. Allowed values: `avg`, `total`, `max`, `none`. Example: `avg`. _Example_ ``` { "path": "order.shippingAddresses", "query": { "boolQuery": { "must": [ { "boolQuery": { "must": [ { "termQuery": { "fields": [ "order.shippingAddresses.firstName" ], "operator": "is", "values": [ "John" ] } } ] } }, { "boolQuery": { "must": [ { "termQuery": { "fields": [ "order.shippingAddresses.lastName" ], "operator": "is", "values": [ "Doe" ] } } ] } } ] } }, "scoreMode": "avg" } ``` ### TermQuery A term query matches one or more values against one or more document fields. A document is considered a hit if one of the values matches exactly with at least one of the given fields. The operator `is` can only take one value, while `one_of` can take multiple values. If multiple fields are specified, they are combined using a logical `OR` operator. **Limitations:** * The `greater` and `less` operators are not supported under certain conditions. Both operators are permitted unless the API documentation states otherwise. * A subset of Commerce APIs handle queries with multiple fields differently. If the query has multiple fields, the query is internally handled as a logical `OR` of `DisjointMaxQueries` (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields. * `fields` (_array of Field_, required) The document fields that the values are matched against, combined with the operator. Minimum items: 1. * `operator` (_string_, required) Returns the operator to use for the term query. Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`. * `values` (_array of string | number | boolean | integer_) The values that the fields are compared against, combined with the operator. Items: Example: `myCouponId`. ### TextQuery A text query is used to match some text (for example, a search phrase possibly consisting of multiple terms) against one or more fields. When multiple fields are provided, the phrase conceptually forms a logical `OR` over the fields. In this case, the terms of the phrase basically have to match within the text, that would result in concatenating all given fields. * `fields` (_array of Field_, required) The document fields that the search phrase matches against. Minimum items: 1. * `searchPhrase` (_string_, required) A search phrase, which can include multiple terms separated by spaces. Example: `campaign summer`. _Example_ ``` { "fields": [ "couponId" ], "searchPhrase": "limit" } ``` ### NonNegativeMoney A combination of a currency and a non-negative amount of that currency. * `currencyMnemonic` (_CurrencyCode_) * `value` (_number (double)_, required) The amount of money for the given currency. Must not be negative. Minimum: 0. Example: `1234.56`. ### Filter Contains a set of objects that define criteria used to select records. A filter can contain one of the following: * `TermFilter` * Matches records where a field (or fields) exactly matches some simple value (including `null`). * `RangeFilter` * Matches records where a field value lies within a specified range. * `Range2Filter` * Matches records in a specified range across fields. * `QueryFilter` * Matches records based on a query. * `BoolFilter` * Provides filtering of records using a set of filters combined using a logical operator. Minimum properties: 1. Maximum properties: 1. * `boolFilter` (_BoolFilter_) * `queryFilter` (_QueryFilter_) * `range2Filter` (_Range2Filter_) * `rangeFilter` (_RangeFilter_) * `termFilter` (_TermFilter_) ### Field Name of the field. Might be a custom field name prefixed with c\_. Type: `string`. Maximum length: 260. Example: `couponId`. ### BoolFilter Allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is composed of a logical operator (`AND`, `OR`, `NOT`) and a list of filters that the operator relates to. Multiple filters can be negated with a single `NOT` operator, even when the filters are combined with the `AND` operator. * `filters` (_array of Filter_) A list of filters that are logically combined by an operator. * `operator` (_string_, required) The logical operator that is used to combine the filters. Allowed values: `and`, `or`, `not`. Example: `and`. _Example_ ``` { "operator": "and", "filters": [ { "termFilter": { "field": "id", "operator": "is", "values": [ "myId" ] } }, { "termFilter": { "field": "couponId", "operator": "is", "values": [ "couponOne" ] } } ] } ``` ### QueryFilter Wraps any query and allows it to be used as a filter. * `query` (_Query_, required) ### Range2Filter Allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range. The first range (R1) is defined by a pair of attributes (`fromField` and `toField`) that specify the extent of a range, such as attributes `validFrom` and `validTo`. The second range (R2) is defined by `fromValue` and `toValue`. The filter mode specifies the method used to compare the two ranges: * `overlap`: R1 overlaps fully or partially with R2. * `containing`: R1 contains R2. * `contained`: R1 is contained in R2. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive. A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default. * `filterMode` (_string_) Compare mode: overlap, containing, or contained. Allowed values: `overlap`, `containing`, `contained`. Default: `overlap`. Example: `overlap`. * `fromField` (_object_, required) The field name of the field that starts the first range. Example: `validFrom`. Includes all fields of `Field`. Example: `validFrom`. * `fromInclusive` (_boolean_) A flag indicating if the lower bound of the second range is inclusive. To make the lower bound exclusive, set to `false`. Default: `true`. Example: `true`. * `fromValue` (_any_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended. Example: `2007-01-01T00:00:00.000Z`. * `toField` (_object_, required) The field name of the field that ends the first range. Example: `validTo`. Includes all fields of `Field`. Example: `validTo`. * `toInclusive` (_boolean_) A flag indicating if the upper bound of the second range is inclusive. To make the lower bound exclusive, set to `false`. Default: `true`. Example: `true`. * `toValue` (_any_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended. Example: `2017-01-01T00:00:00.000Z`. _Example_ ``` { "fromField": "validFrom", "toField": "validTo", "filterMode": "overlap", "fromValue": "2007-01-01T00:00:00.000Z", "toValue": "2017-01-01T00:00:00.000Z" } ``` ### RangeFilter Allows you to restrict a search result to hits that have values for a given attribute that fall within a given value range. The range filter supports several value types and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive. A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default. * `field` (_object_, required) The search field. Example: `validFrom`. Includes all fields of `Field`. Example: `validFrom`. * `from` (_string (date-time) | integer | number_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended. One of: `string (date-time)`, `integer`, `number`. * _string (date-time)_ Type: `string (date-time)`. Example: `2007-01-01T00:00:00.000Z`. * _integer_ Type: `integer`. Example: `1`. * _number_ Type: `number`. Example: `1`. * `fromInclusive` (_boolean_) A flag indicating if the lower bound of the range is inclusive. To make the lower bound exclusive, set to `false`. Default: `true`. Example: `true`. * `to` (_string (date-time) | integer | number_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended. One of: `string (date-time)`, `integer`, `number`. * _string (date-time)_ Type: `string (date-time)`. Example: `2007-01-02T00:00:00.000Z`. * _integer_ Type: `integer`. Example: `2`. * _number_ Type: `number`. Example: `2`. * `toInclusive` (_boolean_) A flag indicating if the upper bound of the range is inclusive. To make the upper bound exclusive, set to `false`. Default: `true`. Example: `true`. ### TermFilter Allows you to restrict a search result to hits that match exactly one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criteria you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only. * `field` (_object_, required) The filter field. Includes all fields of `Field`. * `operator` (_string_, required) The operator used to compare the field's values with the given values. Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`. * `values` (_array of string_) The filter values. Items: Example: `myId`. _Example_ ``` { "field": "id", "operator": "is", "values": [ "myId" ] } ```