Elastic Path Price Books API

openapi: 3.1.0
info:
  version: 25.1126.6886238
  x-version-timestamp: 2025-11-26 19:10:23+00:00
  title: Addresses Introduction Account Addresses Price Books API
  description: 'The Addresses API allows you to organize account addresses. Addresses are a sub-resource of `account` resources, an account can have multiple addresses, such as home, work, and neighbour.


    You can use an account address with either [client_credentials access token](/docs/api/authentication/create-an-access-token) or a combination of [implicit access token](/docs/api/authentication/create-an-access-token) and [Account Management authentication](/docs/api/accounts/post-v-2-account-members-tokens) token.

    '
  contact:
    name: Elastic Path
    url: https://www.elasticpath.com
    email: support@elasticpath.com
  license:
    url: https://elasticpath.dev
    name: MIT
servers:
- url: https://useast.api.elasticpath.com
  description: US East
- url: https://euwest.api.elasticpath.com
  description: EU West
security:
- BearerToken: []
tags:
- name: Price Books
  description: "Price books contain prices for the products in your catalog. Each catalog must have one price book. In your storefront, the product prices are displayed in the currency for the selected locale. If a product in the catalog does not have a price in the price book, the product is displayed without a price. \n\nA price book can be associated with multiple catalogs.\n\nFollowing on from this, you can associate more than one price book with a catalog. Price book stacking allows you to create multiple price books for different scenarios, such as seasonal sales, business versus retail customer pricing, and reward programs. If you have multiple price books, when you create a catalog, you must configure a priority for your price books. Product prices are displayed in the catalog according to the priority of the price books. For example, you may have products that have different prices based on region. You can have a price book with the standard retail pricing and then have a second price book that has different pricing for a different region. See Create a catalog.\n\nA price book contains a list of product SKUs and the prices you want to charge for those products. If your store supports multiple locales, a price book can contain product prices in each of the supported currencies. In addition, you can configure sales and volume (tier) pricing.\n\n:::note\n\nPrice books work with products that are defined using the Product Experience Manager resource model. If your products are defined using an earlier Products resource model, you will need to migrate products to the `pcm/products` resource before you implement price books.\n\n:::\n\nYou can duplicate an existing price book and create a new price book. All products and prices associated with the price book are copied to the new price book. Based on the business requirements, you can use the same data or update the data.\n"
paths:
  /pcm/pricebooks:
    post:
      tags:
      - Price Books
      summary: Create a Price Book
      operationId: createPricebook
      description: Creates a price book. You can add the prices to the price book now or update the price book later.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/pricebook-create-data'
        description: Creates a price book with the following attributes.
        required: true
      responses:
        '201':
          description: A price book with the following attributes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pricebook-data'
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response-pricebooks'
    get:
      tags:
      - Price Books
      summary: Get all Price Books
      description: "Retrieves a list of all price books.\n\n### Filtering\n\nFiltering is supported on this endpoint. For the general syntax, see [Filtering](/guides/Getting-Started/filtering).\n\n You can filter on the following attributes and operators.\n\n | Operator | Attribute | Description | Example |\n | --- | --- | --- | --- |\n | `eq` | `external_ref` | Equals. Checks if the values you provide matches a price book. | `filter=eq(external_ref,some-external-ref)` |\n"
      operationId: getPricebooks
      parameters:
      - $ref: '#/components/parameters/filter-pricebook'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: The list of price books.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pricebook-list-data'
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response-pricebooks'
  /pcm/pricebooks/{pricebookID}:
    parameters:
    - name: pricebookID
      in: path
      description: The unique identifier of a price book.
      required: true
      schema:
        type: string
    get:
      tags:
      - Price Books
      summary: Get a Price Book by ID
      description: Retrieves the specified price book. To include prices in the response, append `?include=prices` to the path.
      operationId: getPricebookById
      parameters:
      - name: include
        in: query
        description: To include product prices in a response, add `include=prices`.
        required: false
        allowEmptyValue: true
        schema:
          type: string
          enum:
          - prices
      responses:
        '200':
          description: The price book.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pricebook-with-prices-data'
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response-pricebooks'
    put:
      tags:
      - Price Books
      summary: Update a Price Book by ID
      description: Updates the specified price book. Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the price book is not updated.
      operationId: updatePricebook
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/pricebook-update-data'
        description: An updated price book with the following attributes.
        required: true
      responses:
        '200':
          description: An updated price book with the following attributes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pricebook-data'
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response-pricebooks'
    delete:
      tags:
      - Price Books
      summary: Delete a Price Book by ID
      description: Deletes the specified price book and all prices in the price book. It does not delete the products. In addition, pricing details in the orders referring to the deleted price book are not deleted.
      operationId: deletePricebookById
      responses:
        '204':
          description: A 204 response indicates that the price book has been deleted.
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response-pricebooks'
  /pcm/pricebooks/{pricebookID}/replicate:
    parameters:
    - name: pricebookID
      in: path
      description: The unique identifier of a price book.
      required: true
      schema:
        type: string
    post:
      tags:
      - Price Books
      summary: Replicate a Price Book
      description: 'Using this endpoint, you can replicate an existing price book. This is useful because it enables you to quickly and easily create multiple price books with the same pricing structure. When you replicate an existing price book, you can specify a new name, description, and external reference for the replicated price book. Other attributes stay the same.

        '
      operationId: replicatePricebook
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/pricebook-replicate-data'
        description: A replicated price book with the following attributes.
      responses:
        '201':
          description: A replicated price book with the following attributes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pricebook-data'
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response-pricebooks'
components:
  schemas:
    pricebook-replicate:
      type: object
      title: Pricebook
      description: Price book replicate request.
      properties:
        type:
          type: string
          x-go-name: Type
          default: pricebook
          example: pricebook
          enum:
          - pricebook
        attributes:
          type: object
          properties:
            description:
              type: string
              description: A brief description outlining the purpose of a price book, such as flash sale pricing or preferred customer pricing.
              example: This is a test price book
              x-go-name: Description
              nullable: true
            name:
              type: string
              description: The name of the price book. Price books must have a unique name.
              example: pricebook-store-abc
              minLength: 1
              x-go-name: Name
              nullable: true
            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
              example: external-ref
              x-go-name: External Ref
              nullable: true
          additionalProperties: false
      required:
      - type
      - attributes
      additionalProperties: false
      x-go-name: PricebookReplicate
    links-pricebook:
      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
          format: uri
          example: /pcm/pricebooks/4c45e4ec-26e0-4043-86e4-c15b9cf985a7
          nullable: true
    page-meta:
      type: object
      description: Contains the results for the entire collection.
      title: PageMeta
      properties:
        results:
          type: object
          properties:
            total:
              description: Total number of results for the entire collection.
              type: integer
              example: 1
              nullable: true
        page:
          type: object
          properties:
            limit:
              description: The maximum number of records for all pages.
              type: integer
              example: 10
              x-omitempty: false
            offset:
              description: The current offset by number of pages.
              type: integer
              example: 0
              x-omitempty: false
            current:
              description: The current number of pages.
              type: integer
              example: 0
              x-omitempty: false
            total:
              description: The total number of records for the entire collection.
              type: integer
              example: 1
              x-omitempty: false
    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
          format: int64
          example: 100
          x-go-name: Amount
          nullable: true
        includes_tax:
          description: Whether this price includes tax.
          type: boolean
          example: false
          default: false
          x-go-name: IncludesTax
        tiers:
          type: object
          description: The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.
          additionalProperties:
            $ref: '#/components/schemas/tier-price'
    sale:
      type: object
      description: The name of the sale, such as `Summer Sale`.
      properties:
        bundle_ids:
          type: array
          description: A list of product IDs in a bundle that you want to specify a sale price for.
          items:
            type: string
            format: uuid
          x-omitempty: true
          x-go-name: BundleIDs
        schedule:
          $ref: '#/components/schemas/schedule'
        currencies:
          $ref: '#/components/schemas/currencies'
    currencies:
      type: object
      description: A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.
      example:
        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
      additionalProperties:
        $ref: '#/components/schemas/amount'
    admin-attributes:
      type: object
      description: "You can add custom attributes to a product price. 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 \n`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add a `shopper_attribute`. \n \n`admin_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
        nullable: true
    pricebook-with-prices-data:
      type: object
      title: PricebookWithPricesData
      description: Json-api style data object containing a price book and its prices.
      properties:
        data:
          $ref: '#/components/schemas/pricebook'
        links:
          $ref: '#/components/schemas/links-pricebook'
        included:
          type: array
          items:
            $ref: '#/components/schemas/product-price'
          nullable: true
      required:
      - data
      additionalProperties: false
    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
          example: a-pricebook-external-ref
          x-go-name: Pricebook External Ref
          nullable: true
        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
              example: external-ref
              x-go-name: External Ref
              nullable: true
            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
              example: store
              nullable: true
            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
    sales:
      type: object
      description: The sales price that an item is eligible for based on the price book.
      example:
        summer:
          schedule:
            valid_form: '2023-12-24T09:00:00'
            valid_to: '2023-12-25T09:00:00'
          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
      additionalProperties:
        $ref: '#/components/schemas/sale'
    error-pricebooks:
      type: object
      title: ApiError
      description: This is a json-api style part of an error response
      properties:
        detail:
          type: string
          example: The price book already exists
          x-go-name: Detail
        status:
          type: string
          example: '409'
          x-go-name: Status
        title:
          type: string
          example: conflict
          x-go-name: Title
      additionalProperties: false
      x-go-name: ApiError
    pricebook-list-data:
      type: object
      title: PricebookListData
      description: Json-api style array containing a list of price books
      properties:
        meta:
          $ref: '#/components/schemas/page-meta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/pricebook'
        links:
          $ref: '#/components/schemas/links-pricebooks'
      required:
      - data
      additionalProperties: false
      x-go-name: PricebookListData
    pricebook:
      type: object
      title: Pricebook
      description: A price book with the following attributes.
      properties:
        id:
          description: A unique identifier of a price book.
          type: string
          example: 4c45e4ec-26e0-4043-86e4-c15b9cf985a7
          x-go-name: ID
        type:
          description: Always `pricebook`.
          type: string
          x-go-name: Type
          default: pricebook
          example: pricebook
          enum:
          - pricebook
        attributes:
          type: object
          properties:
            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
              example: an-external-ref
              x-go-name: External Ref
              nullable: true
            description:
              description: A brief description that outlines the purpose of a price book, for example, flash sale pricing or preferred customer pricing.
              type: string
              example: This is a test price book
              x-go-name: Description
              nullable: true
            name:
              description: The name of a price book. Price books must have a unique name
              type: string
              example: Standard Price Book
              x-go-name: Name
              nullable: true
            created_at:
              description: The date and time when the price book 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 book was last updated.
              type: string
              example: '2020-09-22T09:00:00Z'
              format: date-time
              x-go-name: UpdatedAt
          required:
          - name
          - created_at
          - updated_at
        meta:
          type: object
          properties:
            owner:
              description: The resource owner, either `organization` or `store`.
              type: string
              example: store
              nullable: true
      required:
      - id
      - type
      - attributes
      additionalProperties: false
      x-go-name: Pricebook
    links-pricebooks:
      description: Links are used to allow you to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases.
      type: object
      properties:
        self:
          description: Single entities use a self parameter with a link to that specific resource.
          type: string
          format: uri
          example: /pcm/pricebooks/4c45e4ec-26e0-4043-86e4-c15b9cf985a7?filter=like(name,*Standard*)
          nullable: true
        first:
          description: Always the first page.
          type: string
          format: uri
          example: /pcm/pricebooks/4c45e4ec-26e0-4043-86e4-c15b9cf985a7?filter=like(name,*Standard*)&page[offset]=0&page[limit]=25
          nullable: true
        last:
          description: This is `null` if there is only one page.
          type: string
          format: uri
          example: /pcm/pricebooks/4c45e4ec-26e0-4043-86e4-c15b9cf985a7?filter=like(name,*Standard*)&page[offset]=0&page[limit]=25
          nullable: true
        prev:
          description: This is `null` if there is only one page.
          type: string
          format: uri
          example: /pcm/pricebooks/4c45e4ec-26e0-4043-86e4-c15b9cf985a7?filter=like(name,*Standard*)&page[offset]=0&page[limit]=25
          nullable: true
        next:
          description: This is `null` if there is only one page.
          type: string
          format: uri
          example: /pcm/pricebooks/4c45e4ec-26e0-4043-86e4-c15b9cf985a7?filter=like(name,*Standard*)&page[offset]=25&page[limit]=25
          nullable: true
    pricebook-data:
      type: object
      title: PricebookData
      description: A price book with the following attributes.
      properties:
        data:
          $ref: '#/components/schemas/pricebook'
        links:
          $ref: '#/components/schemas/links-pricebook'
      required:
      - data
      additionalProperties: false
      x-go-name: PricebookData
    pricebook-create:
      type: object
      title: PricebookWithoutId
      properties:
        type:
          type: string
          x-go-name: Type
          default: pricebook
          example: pricebook
          enum:
          - pricebook
        attributes:
          type: object
          properties:
            description:
              description: A brief description that describes the purpose of a price book, for example, flash sale pricing or preferred customer pricing.
              type: string
              example: This is a price book
              x-go-name: Description
              nullable: true
            name:
              description: The name of the price book. Price books must have a unique name.
              type: string
              example: pricebook-store-abc
              minLength: 1
              x-go-name: Name
            external_ref:
              description: A unique attribute that you can use to contain information from another company system, for example. The maximum length is 2048 characters.
              type: string
              example: external-ref
              x-go-name: External Ref
              nullable: true
          required:
          - name
          additionalProperties: false
      required:
      - type
      - attributes
      additionalProperties: false
      x-go-name: PricebookCreateParam
    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
          format: int64
          example: '10'
          x-go-name: MinQuantity
          nullable: true
        amount:
          description: The price for each quantity.
          type: integer
          format: int64
          example: '50'
          x-go-name: Amount
          nullable: true
      x-go-name: TierPrice
    schedule:
      type: object
      description: "The schedule of the sale. If the entire `schedule` object is omitted or `null`, the sale price is considered permanent.\n\nWhen defining a recurring sale with `rrule`, the `valid_from` and `valid_to` parameters are mandatory to set the overall start and end dates for the recurrence. A single price cannot have both a standard and a recurring (`rrule`) sale schedule.\n\nYou can use `tzid` to set the timezone of the `valid_from` and `valid_to` parameters.\n\nFor sale prices within the same price book:\n  - The schedules must not be exactly the same.\n  - Schedules and recurrence rules can partially overlap. If schedules do overlap, the sale price active during the smallest sale period is chosen.\n  - If you have a single permanent sale price (no schedule), you must configure a schedule for it before adding other sale prices to the same price book.\n\n  \nSale prices in different price books can have overlapping schedules.\n"
      properties:
        valid_from:
          description: The start date of the sale.
          type: string
          example: '2023-09-22T09:00:00Z'
          format: date-time
          x-go-name: ValidFrom
          nullable: true
        valid_to:
          description: The end date of the sale.
          type: string
          example: '2023-09-24T09:00:00Z'
          format: date-time
          x-go-name: ValidTo
          nullable: true
        rrule:
          type: string
          description: "Specifies a recurring schedule for a sale, defined using a subset of the RFC 5545 RRULE format.\nThis allows for setting up sales that automatically apply on a recurring basis, such as weekly weekend discounts.\n\n**Supported RRULE Parameters:**\n  - `FREQ`: Defines the frequency of recurrence. Supported values: `WEEKLY`.\n  - `BYDAY`: Specifies the days of the week for weekly recurrences. Supported values: `MO`, `TU`, `WE`, `TH`, `FR`, `SA`, and `SU`.\n\n  \n**Example Usage:**\n  - Weekly sale on Saturdays and Sundays: `FREQ=WEEKLY;BYDAY=SA,SU`\n"
          example: FREQ=WEEKLY;BYDAY=SA,SU
          x-go-name: RecurrenceRule
          nullable: true
        tzid:
          type: string
          description: 'Timezone based on the IANA Timezone Database (e.g., Europe/London or Europe/Paris).

            Timezones can be specified for both standard and `rrule` based sales.

            By default, `valid_from` and `valid_to` are interpreted as UTC. Specifying a `tzid` applies that timezone to both the start and end dates.

            '
          example: Europe/London
          x-go-name: Timezone
          nullable: true
      x-go-name: Schedule
      nullable: true
    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
        nullable: true
    pricebook-update:
      type: object
      title: Pricebook
      description: Updates the specified price book.
      properties:
        id:
          description: The unique identifier of a price book.
          type: string
          example: 4c45e4ec-26e0-4043-86e4-c15b9cf985a7
          x-go-name: ID
        type:
          description: Always `pricebook`.
          type: string
          x-go-name: Type
          default: pricebook
          example: pricebook
          enum:
          - pricebook
        attributes:
          type: object
          properties:
            description:
              description: A brief description that describes a price book, for example, flash sale pricing or preferred customer pricing.
              type: string
              example: This is a price book
              x-go-name: Description
              nullable: true
            name:
              description: The name of a price book. Price books must have a unique name.
              type: string
              example: pricebook-store-abc
              minLength: 1
              x-go-name: Name
              nullable: true
            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
              example: external-ref
              x-go-name: External Ref
              nullable: true
          additionalProperties: false
      required:
      - id
      - type
      - attributes
      additionalProperties: false
      x-go-name: PricebookUpdate
    pricebook-update-data:
      type: object
      title: PricebookCreateData
      properties:
        data:
          $ref: '#/components/schemas/pricebook-update'
      required:
      - data
      additionalProperties: false
      x-go-name: Pri

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