Elastic Path · Schema
Price Books Introduction
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:
CommerceHeadless CommerceComposable CommerceeCommerceB2BProductsCatalogsOrdersPromotionsSubscriptionsPayments
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://raw.githubusercontent.com/api-evangelist/elastic-path/main/json-schema/pricebooks.json",
"title": "Price Books Introduction",
"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:",
"version": "26.0529.7665911",
"$defs": {
"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"
},
"error-response-pricebooks": {
"type": "object",
"title": "ErrorResponse",
"description": "This is a json-api style error response",
"properties": {
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/error-pricebooks"
},
"x-go-name": "Errors"
}
},
"additionalProperties": false,
"x-go-name": "ErrorResponse"
},
"error-prices": {
"type": "object",
"title": "ApiError",
"description": "This is a json-api style part of an error response",
"properties": {
"detail": {
"type": "string",
"example": "The price 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"
},
"error-response-prices": {
"type": "object",
"title": "ErrorResponse",
"description": "This is a json-api style Error response",
"properties": {
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/error-prices"
},
"x-go-name": "Errors"
}
},
"additionalProperties": false,
"x-go-name": "ErrorResponse"
},
"error-modifiers": {
"type": "object",
"title": "ApiError",
"description": "This is a json-api style part of an error response",
"properties": {
"detail": {
"type": "string",
"example": "The modifier 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"
},
"error-response-modifiers": {
"type": "object",
"title": "ErrorResponse",
"description": "This is a json-api style error response",
"properties": {
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/error-modifiers"
},
"x-go-name": "Errors"
}
},
"additionalProperties": false,
"x-go-name": "ErrorResponse"
},
"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"
}
},
"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"
}
},
"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 can",
"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).\nTimezones can be specified for both standard and `rrule` based sales.\nBy default, `valid_from` and `valid_to` are interpreted as UTC. Specifying a `tzid` applies that timezone to both the start and end dates.\n",
"example": "Europe/London",
"x-go-name": "Timezone",
"nullable": true
}
},
"x-go-name": "Schedule",
"nullable": true
},
"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"
}
}
},
"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"
},
"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"
}
}
}
},
"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"
},
"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-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"
},
"pricebook-create-data": {
"type": "object",
"title": "PricebookCreateData",
"properties": {
"data": {
"$ref": "#/components/schemas/pricebook-create"
}
},
"required": [
"data"
],
"additionalProperties": false,
"x-go-name": "PricebookCreateData",
"example": {
"data": {
"attributes": {
"external_ref": "an-external-ref",
"description": "This is a test price book",
"name": "Standard Price Book"
},
"type": "pricebook"
}
}
},
"pricebook-update-data": {
"type": "object",
"title": "PricebookCreateData",
"properties": {
"data": {
"$ref": "#/components/schemas/pricebook-update"
}
},
"required": [
"data"
],
"additionalProperties": false,
"x-go-name": "PricebookUpdateData"
},
"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"
},
"pricebook-replicate-data": {
"type": "object",
"title": "PricebookReplicateData",
"description": "Json-api style data object containing a price book to be replicated.",
"properties": {
"data": {
"$ref": "#/components/schemas/pricebook-replicate"
}
},
"required": [
"data"
],
"additionalProperties": false,
"x-go-name": "PricebookReplicateData"
},
"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
},
"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"
},
"job": {
"type": "object",
"title": "Job",
"description": "Top level entity in the jobs domain model. It contains a job details.",
"properties": {
"id": {
"type": "string",
"example": "0dd4e7de-006f-460f-a43e-a581f375cedc",
"x-go-name": "ID"
},
"attributes": {
"type": "object",
"properties": {
"created_at": {
"type": "string",
"format": "date-time",
"example": "2020-09-22T09:00:00Z",
"x-go-name": "CreatedAt"
},
"updated_at": {
"type": "string",
"example": "2020-09-22T09:00:00Z",
"format": "date-time",
"x-go-name": "UpdatedAt"
},
"started_at": {
"type": "string",
"format": "date-time",
"example": "2020-09-22T09:00:00Z",
"x-go-name": "StartedAt",
"nullable": true
},
"completed_at": {
"type": "string",
"example": "2020-09-22T09:00:00Z",
"format": "date-time",
"x-go-name": "CompletedAt",
"nullable": true
},
"type": {
"type": "string",
"example": "pricebook-import",
"x-go-name": "Type"
},
"status": {
"type": "string",
"example": "pending",
"x-go-name": "Status"
}
},
"required": [
"created_at",
"updated_at",
"type",
"status"
]
},
"meta": {
"type": "object",
"properties": {
"x_request_id": {
"type": "string",
"example": "2d70776e-c2b0-4446-84e6-d08a24edfca4",
"x-go-name": "XRequestID"
}
},
"required": [
"x_request_id"
]
}
},
"required": [
"id",
"attributes",
"meta"
],
"additionalProperties": false,
"x-go-name": "Job"
},
"job-data": {
"type": "object",
"title": "JobData",
"description": "Json-api style data object containing a job.",
"properties": {
"data": {
"$ref": "#/components/schemas/job"
}
},
"required": [
"data"
],
"additionalProperties": false,
"x-go-name": "JobData"
},
"page-meta-no-counts": {
"type": "object",
"description": "Contains the results for the entire collection.",
"title": "PageMeta",
"properties": {
"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
}
}
}
}
},
"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
}
}
}
}
},
"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"
},
"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",
"example": "a-external-ref",
"x-go-name": "External Ref",
"nullable": true
},
"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": {
"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"
},
"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 co",
"example": {
"cost_of_goods": "42.0",
"charge_type": "credit card"
},
"additionalProperties": {
"type": "string",
"nullable": true
# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/elastic-path/refs/heads/main/json-schema/pricebooks.json