Elastic Path Prices API

openapi: 3.2.0
info:
  title: Price Books Introduction Prices API
  version: 26.0529.7665911
  x-version-timestamp: 2026-05-29 08:15:28+00:00
  description: 'You can use the price books service to configure your product pricing. Your price books are associated with your catalogs. Creating separate price books enables you to:


    - Maintain consistent and accurate pricing across all your product listings and channels.

    - Provide competitive pricing by creating different price books for different channels. For example, different pricing for different geographical regions, based on standard of living costs.

    - Provide personalized pricing by creating personalized price books. For example, pricing for loyalty customers versus new customers.

    - Enable cross-selling and upselling by offering sales and volume pricing for your products.

    - Create price-books based on real-time adjustments such as inventory levels and market conditions.

    '
servers:
- url: https://euwest.api.elasticpath.com
  description: EU West Production Server
- url: https://useast.api.elasticpath.com
  description: US East Production Server
security:
- bearerAuth: []
tags:
- name: Prices
  description: "Price books contain prices for the products in your catalog. Use the Price Books API to create price books and add product prices to the price book.\n\n### Volume (tiers) Pricing\n\nUsing volume (tiers) pricing allows your store to offer different pricing for minimum quantities of items that your customers purchase. When a customer adds sufficient quantity of an item and meets the minimum required quantity for different pricing, all products with that item SKU are discounted in the cart. You can define the price range for different quantities of different items as in the following example:\n\n| Quantity | Price/Each |\n|:---------|:-----------|\n| 1-5      | $10.50     |\n| 6-10     | $10.00     |\n| 11-20    | $9.50      |\n| 21-50    | $8.50      |\n| 51+      | $7.90      |\n\n### Sales Pricing\n\nWith sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. \n\nYou can set a sale price for an item within a bundle so that the product is sold at the sale price when sold as part of the bundle. For example, if you have a bundle consisting of four items, you can apply a discounted price to an item within the bundle to get a bundle sales price. \n\n1. For sale prices in the same price book:\n\n    - the schedules must not be exactly the same.\n    - schedules can partially overlap. If the schedule does contain overlapping sales prices, the sale price of the smallest sale period is chosen.\n    - if you have just one sale price, without a schedule, this is effectively a permanent price. If you want to add more sale prices to the price book, you must configure a schedule for the sale price. \n\n2. Sale prices in different price books can have overlapping schedules.\n\nBoth list and sale price (or was/is prices) are available in the catalog response, enabling you to display slash pricing on your storefront, depending on your requirements.\n\n### Creating a bundle sale price\n\nYou can assign a sale price to an option in a bundle.\n\n1. In the product price book, create a sale.\n2. Specify the bundle ID that contains the option you want to provide a sale price for.\n3. Provide the sale price for the option. You can add the same sale price for the same option using an array of bundle_ids if you want to sell the product as part of different bundles.\n\n### Understanding Volume and Sale Pricing Behavior for Products\n\nIf you have configured both sale and volume pricing for your products and product bundles, the following table describes how pricing behaves in the following scenarios.\n\n| Scenario | Description |\n| --- | --- |\n| Minimum quantities for volume pricing and sale pricing | <ul><li>(With sale schedule) If you have specified a minimum quantity of five whose price is $0.99 and at the same time, you have configured a sale for the time of purchase, then when a shopper checks out with 5 or more items, the total is based on the volume pricing. In other words, $0.99 × 5 = $4.95. Additionally, if volume pricing exist for both the product price and the sale, the volume pricing for the sale takes precedence. If no volume pricing is set in the sale, the base sale price is applied, and the volume pricing for the product price will not be applied.</li><li>(With sale schedule) If a shopper's items in the cart do not meet the minimum quantity required for volume pricing, the total is calculated based on the sales price.</li><li>(Without sale schedule) If the sale is a permanent sale and volume pricing is only set for the product price, then regardless of the quantity a shopper adds to a cart, the final price is always calculated based on the base sales price. However, if volume pricing has been set for the sale, the final price will be determined by the volume tier pricing set in the sale, not the base sales price.</li></ul>\n| Two levels of volume pricing with different prices for each volume. | If you have configured two levels of volume pricing, for example, the first minimum quantity is 5 and the second minimum quantity is 10:<ul><li>When the quantity in the cart is => 5, then the price for the minimum quantity of 5 is used.</li><li>When the quantity in the cart is => 10 then the price for the minimum quantity of 10 is used.</li></ul> |\n\n### Optimizing product prices\n\nYou can add custom attributes to a product price, allowing your storefront to dynamically use these attributes in it's pricing and display logic. This enables you to optimize your pricing data, enhancing your ability to respond to market dynamics and customer preferences. Some examples of pricing optimization strategies are:\n\n- dynamic pricing - allows you to change the price of a product based on changes in customer demand, for example, raising prices during the high-demand holiday season or segment-focused, like special offers for new customers.\n- value-based pricing - allows you to offer different pricing tiers, for example, \"pro\" features cost more.\n- cost-plus pricing - allows you to set prices by adding a specific percentage to the production cost of a single unit.\n\nThere are two types of custom attributes:\n\n- `admin_attributes` - `admin_attributes` are not displayed in catalogs. This means `admin-attributes` can only be viewed by administrators. For example, you may want to add custom attributes that can automate price updates based on predefined rules, saving time and reducing human error or you might want to integrate price attributes with your other company systems, (ERP, CRM) ensuring consistency and accuracy across platforms.\n- `shopper_attributes` - `shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators.  For example, you can set prices based on customer segments, offering different prices for wholesale and retail customers or providing discounts to loyal customers. \n\nBoth `admin-attributes` and `shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys for each type of attribute.\n"
paths:
  /pcm/pricebooks/{pricebookID}/prices:
    parameters:
    - name: pricebookID
      in: path
      description: The unique identifier of a price book.
      required: true
      schema:
        type: string
    post:
      tags:
      - Prices
      summary: Add a Product Price to a Price Book
      description: Price books contain prices for the products in your catalog. Use the Prices API to adds the prices for a product to a specified price book. If the prices for the product already exist in the price book, the operation fails and the existing product prices are not updated.
      operationId: createProductPrice
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/product-price-create-data'
        description: A product price with the following attributes.
        required: true
        x-examples:
          application/json:
            regular-price:
              summary: Create a Regular Price
              value:
                data:
                  type: product-price
                  attributes:
                    sku: product-r1
                    currencies:
                      USD:
                        amount: 100
                        includes_tax: false
                      GBP:
                        amount: 73
                        includes_tax: true
                      CAD:
                        amount: 127
                        includes_tax: false
            volume-price:
              summary: Create a Volume Price
              value:
                data:
                  type: product-price
                  attributes:
                    sku: product-v1
                    currencies:
                      USD:
                        amount: 100
                        includes_tax: false
                        tiers:
                          min_5:
                            minimum_quantity: 5
                            amount: 50
                      GBP:
                        amount: 73
                        includes_tax: true
                        tiers:
                          min_20:
                            minimum_quantity: 20
                            amount: 60
                      CAD:
                        amount: 127
                        includes_tax: false
                        tiers:
                          min_10:
                            minimum_quantity: 10
                            amount: 100
            sale-price:
              summary: Create Bundle Sale Price
              description: 'You can assign a sale price to an option in a bundle.


                1. In the product price book, create a sale.

                2. Specify the bundle ID that contains the option you want to provide a sale price for.

                3. Provide the sale price for the option. You can add the same sale price for the same option using an array of bundle_ids if you want to sell the product as part of different bundles.'
              value:
                data:
                  type: product-price
                  attributes:
                    sku: product-b1
                    currencies:
                      USD:
                        amount: 100
                        includes_tax: false
                      GBP:
                        amount: 73
                        includes_tax: true
                      CAD:
                        amount: 127
                        includes_tax: false
                    sales:
                      summer:
                        bundle_ids:
                        - a3cacaa9-b5bb-4096-bb6b-af41394ca850
                        schedule:
                          valid_from: '2023-12-01T12:00:00Z'
                          valid_to: '2023-12-02T12:00:00Z'
                        currencies:
                          USD:
                            amount: 90
                            includes_tax: false
                          CAD:
                            amount: 117
                            includes_tax: false
                          GBP:
                            amount: 65
                            includes_tax: true
      responses:
        '201':
          description: A product price with the following attributes.
          x-examples:
            application/json:
              volume-price:
                summary: Create a Volume Price
                value:
                  data:
                    id: ad042b07-e86d-476a-82d5-43dda1f80d03
                    attributes:
                      currencies:
                        USD:
                          amount: 100
                          includes_tax: false
                          tiers:
                            min_5:
                              minimum_quantity: 5
                              amount: 50
                        CAD:
                          amount: 127
                          includes_tax: false
                          tiers:
                            min_10:
                              minimum_quantity: 10
                              amount: 100
                        GBP:
                          amount: 73
                          includes_tax: true
                          tiers:
                            min_20:
                              minimum_quantity: 20
                              amount: 60
                      sales:
                        summer:
                          currencies:
                            USD:
                              amount: 90
                              includes_tax: false
                              tiers:
                                min_5:
                                  minimum_quantity: 5
                                  amount: 40
                            CAD:
                              amount: 117
                              includes_tax: false
                              tiers:
                                min_10:
                                  minimum_quantity: 10
                                  amount: 80
                            GBP:
                              amount: 65
                              includes_tax: true
                              tiers:
                                min_20:
                                  minimum_quantity: 20
                                  amount: 50
                      sku: product-1
                    meta:
                      owner: store
                    type: product-price
                  links:
                    self: /pcm/pricebooks/2cf0d38c-58aa-420d-8658-4385dccea609/prices/ad042b07-e86d-476a-82d5-43dda1f80d03
              sale-price:
                summary: Create Bundle Sale Price
                value:
                  data:
                    id: 76c78677-a22a-4104-8fb7-11f1cfc3b146
                    attributes:
                      sku: product-1
                      currencies:
                        USD:
                          amount: 100
                          includes_tax: false
                          tiers:
                            min_5:
                              minimum_quantity: 5
                              amount: 50
                        CAD:
                          amount: 127
                          includes_tax: false
                          tiers:
                            min_10:
                              minimum_quantity: 10
                              amount: 100
                        GBP:
                          amount: 73
                          includes_tax: true
                          tiers:
                            min_20:
                              minimum_quantity: 20
                              amount: 60
                      sales:
                        summer:
                          bundle_ids:
                          - a3cacaa9-b5bb-4096-bb6b-af41394ca850
                          currencies:
                            USD:
                              amount: 90
                              includes_tax: false
                              tiers:
                                min_5:
                                  minimum_quantity: 5
                                  amount: 40
                            CAD:
                              amount: 117
                              includes_tax: false
                              tiers:
                                min_10:
                                  minimum_quantity: 10
                                  amount: 80
                            GBP:
                              amount: 65
                              includes_tax: true
                              tiers:
                                min_20:
                                  minimum_quantity: 20
                                  amount: 50
                    type: product-price
                  links:
                    self: /pcm/pricebooks/2cf0d38c-58aa-420d-8658-4385dccea609/prices/76c78677-a22a-4104-8fb7-11f1cfc3b146
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/product-price-data'
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response-prices'
    get:
      tags:
      - Prices
      summary: Gets all Prices by Price Book ID
      description: 'Retrieves all the product prices in the specified price book.


        ### Filtering


        This endpoint supports filtering. For general syntax, see [Filtering](/guides/Getting-Started/filtering).


        | Operator | Attribute | Description | Example |

        | --- | --- | --- | --- |

        | `eq` | `external_ref`, `sku` | Checks if the values you provide matches a price. | `filter=eq(sku,some-sku)` |

        | `in` | `sku` | Checks if the values you provide are included in a product SKU. | `filter=in(sku,some-sku)'' |

        '
      operationId: getProductPrices
      parameters:
      - $ref: '#/components/parameters/filter-price'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: The product price list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/product-price-list-data'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response-prices'
  /pcm/pricebooks/{pricebookID}/prices/{priceID}:
    parameters:
    - name: pricebookID
      in: path
      description: The unique identifier of a price book.
      required: true
      schema:
        type: string
    - name: priceID
      in: path
      description: A unique identifier of a price book price.
      required: true
      schema:
        type: string
    get:
      summary: Get a Product Price by Price Book ID
      description: Retrieves a specified product price (`priceId`) in the specified price book (`id`).
      tags:
      - Prices
      operationId: getProductPriceByID
      responses:
        '200':
          description: The product price.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/product-price-data'
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response-prices'
    put:
      summary: Update a Product Price in a Price Book
      description: Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the price is not updated.
      tags:
      - Prices
      operationId: updateProductPrice
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/product-price-data'
        description: The updated product price
        required: true
      responses:
        '200':
          description: An updated product price with the following attributes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/product-price-data'
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response-prices'
    delete:
      tags:
      - Prices
      summary: Delete a Product Price from a Price Book
      description: Deletes a product price from the specified price book.
      operationId: deleteProductPrice
      responses:
        '204':
          description: A 204 response indicates that the product prices have been deleted
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response-prices'
  /pcm/pricebooks/prices:
    get:
      tags:
      - Prices
      summary: Gets all Prices
      description: 'Allows you to retrieve all prices for a product, irrespective of the different price books that include that product''s price. For example, you can filter for all prices for a specified `sku`, or filter for all prices changed before or after a given date. This will retrieve prices from all price books.


        ### Filtering


        This endpoint supports filtering. For general syntax, see [Filtering](/guides/Getting-Started/filtering).


        | Operator | Attribute | Description | Example |

        | --- | --- | --- | --- |

        | `eq` | `external_ref`, `sku`, `id` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. | `filter=eq(sku,some-sku)` |

        | `in` | `external_ref`, `sku`, `id` | In. Checks if the values are included in the specified list. If they are, the condition is true. | `filter=in(sku,some-sku)` |

        | `like` | `external_ref`, `sku` | Like. Checks if the operand contains the specified string. Wildcards are supported. | `filter=like(sku,some-sku)` |

        | `gt` | `updated_at`, `created_at` | Greater than. Checks if the value on the left of the operator is greater than the value on the right. If it is, the condition is true. | `filter=gt(updated_at,2018-04-16T10:11:59.715Z)` |

        | `lt` | `updated_at`, `created_at` | Less than. Checks if the value on the left of the operator is less than the value on the right. If it is, the condition is true. | `filter=lt(updated_at,2018-04-16T10:11:59.715Z)` |

        '
      operationId: getPrices
      parameters:
      - $ref: '#/components/parameters/filter-price'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: The price list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/price-list-data'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response-prices'
components:
  schemas:
    price-list-data:
      type: object
      title: PriceListData
      description: Json-api style array containing a list of prices.
      properties:
        meta:
          $ref: '#/components/schemas/page-meta-no-counts'
        data:
          type: array
          items:
            $ref: '#/components/schemas/product-price'
        links:
          $ref: '#/components/schemas/links-prices-new'
      required:
      - data
      additionalProperties: false
      x-go-name: PriceListData
    product-price-data:
      type: object
      title: ProductPriceData
      description: A product price with the following attributes.
      properties:
        data:
          $ref: '#/components/schemas/product-price'
        links:
          $ref: '#/components/schemas/links-price'
      required:
      - data
      additionalProperties: false
      x-go-name: ProductPriceData
    product-price-create-arg:
      type: object
      title: ProductPriceCreateArg
      properties:
        type:
          type: string
          example: product-price
          default: product-price
          enum:
          - product-price
        attributes:
          type: object
          properties:
            currencies:
              $ref: '#/components/schemas/currencies'
            sku:
              description: The product SKU that the prices belongs to.
              type: string
              minLength: 1
              example: product-sku-a
            sales:
              $ref: '#/components/schemas/sales'
            external_ref:
              description: A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.
              type:
              - string
              - 'null'
              example: a-external-ref
              x-go-name: External Ref
            admin_attributes:
              $ref: '#/components/schemas/admin-attributes'
            shopper_attributes:
              $ref: '#/components/schemas/shopper-attributes'
          required:
          - currencies
          - sku
      required:
      - type
      - attributes
      additionalProperties: false
      x-go-name: ProductPriceCreateArg
    product-price-list-data:
      type: object
      title: ProductPriceListData
      description: Json-api style array containing a list of product prices.
      properties:
        meta:
          $ref: '#/components/schemas/page-meta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/product-price'
        links:
          $ref: '#/components/schemas/links-prices'
      required:
      - data
      additionalProperties: false
      x-go-name: ProductPriceListData
    product-price:
      type: object
      title: ProductPrice
      properties:
        type:
          type: string
          example: product-price
          default: product-price
          enum:
          - product-price
        pricebook_external_ref:
          description: The unique attribute associated with the price book. This can be an external reference from a separate company system, for example. The maximum length is 2048 characters.
          type:
          - string
          - 'null'
          example: a-pricebook-external-ref
          x-go-name: Pricebook External Ref
        attributes:
          type: object
          properties:
            currencies:
              $ref: '#/components/schemas/currencies'
            sku:
              description: The product SKU that the price belongs to.
              type: string
              minLength: 1
              example: product-sku-a
            sales:
              $ref: '#/components/schemas/sales'
            external_ref:
              description: A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.
              type:
              - string
              - 'null'
              example: external-ref
              x-go-name: External Ref
            created_at:
              description: The date and time when the price was created.
              type: string
              format: date-time
              example: '2020-09-22T09:00:00Z'
              x-go-name: CreatedAt
            updated_at:
              description: The date and time when the price was last updated.
              type: string
              example: '2020-09-22T09:00:00Z'
              format: date-time
              x-go-name: UpdatedAt
            admin_attributes:
              $ref: '#/components/schemas/admin-attributes'
            shopper_attributes:
              $ref: '#/components/schemas/shopper-attributes'
          required:
          - sku
        id:
          description: The unique identifier for the product price.
          type: string
          example: a915553d-935d-4d56-870b-817b47a44a99
          x-go-name: ID
        meta:
          description: Information that provides context to other data sets.
          type: object
          properties:
            owner:
              description: The resource owner, either `organization` or `store`.
              type:
              - string
              - 'null'
              example: store
            pricebook_id:
              description: The unique identifier of the price book.
              type: string
              example: 4c45e4ec-26e0-4043-86e4-c15b9cf985a7
              x-go-name: Pricebook ID
      required:
      - type
      - attributes
      - id
      additionalProperties: false
      x-go-name: ProductPrice
    product-price-create-data:
      type: object
      title: ProductPriceCreateData
      description: A product price with the following attributes.
      properties:
        data:
          $ref: '#/components/schemas/product-price-create-arg'
      required:
      - data
      additionalProperties: false
      x-go-name: ProductPriceCreateData
    shopper-attributes:
      type: object
      description: "You can add custom attributes to a product price. For example, you can set prices based on customer segments. For instance, you can offer different prices for wholesale and retail customers or provide discounts to loyal customers. Following on from this, you might want to offer personalized offers and prices, enhancing the shopping experience.\n\n`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add an `admin_attribute`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n"
      example:
        cost_of_goods: '42.0'
        charge_type: credit card
      additionalProperties:
        type:
        - string
        - 'null'
    links-prices:
      description: Links are used to allow you to move between requests.
      type: object
      properties:
        self:
          description: Single entities use a self parameter with a link to that specific resource.
          type:
          - string
          - 'null'
          format: uri
          example: /pcm/pricebooks/4c45e4ec-26e0-4043-86e4-c15b9cf985a7/prices?filter=like(sku,*product*)
        first:
          description: Always the first page.
          type:
          - string
          - 'null'
          format: uri
        last:
          description: This is `null` if there is only one page.
          type:
          - string
          - 'null'
          format: uri
        prev:
          description: This is `null` if there is only one page.
          type:
          - string
          - 'null'
          format: uri
        next:
          description: This is `null` if there is only one page.
          type:
          - string
          - 'null'
          format: uri
    tier-price:
      type: object
      description: The name of the tier, for example, `Pencils`.
      properties:
        minimum_quantity:
          description: The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.
          type:
          - integer
          - 'null'
          format: int64
          example: '10'
          x-go-name: MinQuantity
        amount:
          description: The price for each quantity.
          type:
          - integer
          - 'null'
          format: int64
          example: '50'
          x-go-name: Amount
      x-go-name: TierPrice
    links-prices-new:
      description: Links are used to allow you to move between requests.
      type: object
      properties:
        self:
          description: Single entities use a self parameter with a link to that specific resource.
          type:
          - string
          - 'null'
          format: uri
          example: /pcm/pricebooks/prices?filter=like(sku,product)
        first:
          description: Always the first page.
          type:
          - string
          - 'null'
          format: uri
        prev:
          description: This is `null` if there is only one page.
          type:
          - string
          - 'null'
          format: uri
        next:
          description: This is `null` if there is only one page.
          type:
          - string
          - 'null'
          format: uri
    amount:
      type: object
      description: The three-letter ISO code for the currency associated with this price.
      properties:
        amount:
          description: The price in the lowest denomination for the specified currency. This is a product's list price.
          type:
          - integer
          - 'null'
          format: int64
          example: 100
          x-go-name: Amount
        include

# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/elastic-path/refs/heads/main/openapi/elastic-path-prices-api-openapi.yml