Price Books

The Price Books API can be used to create, update and query Price Books and Price Book Products.

Price Books are a feature in Lightspeed Retail (X-Series) that enable you to offer special pricing and loyalty amounts on specific Products. These can be restricted to a certain customer groups or a specific outlets, enabling you to have sophisticated pricing strategies for your store. You can also automate the start and end dates of sales, which makes it easy to plan and set up in advance.

Price Books have the potential to impact a retailer's revenue, so we recommend thoroughly reviewing Running Sales using Price Books.

Price Books or Promotions?

Price Books cover a very similar purpose to the Promotions API, and in nearly all cases Promotions are the preferred feature.

Promotions define rules to update prices across a group of products, and they can be easily configured to adapt to changes in retail price.
Price Books are static, so when a Product price changes, Price Books need to be changed explicitly.
Not only that, but Price Books naturally carry more data, and can affect the performance of the system when overused.

The Price Books API can still be considered useful for synchronizing prices from an external system. If an integrator is linking Lightspeed Retail (X-Series) to something like an ERP system with sophisticated price modelling, then the Promotions API may not support your use case.

A General guideline for Price Books and Promotions in Lightspeed Retail (X-Series):

Use Promotions OR Price Books to reward your customers by setting up Customer Groups for staff, VIPs, local business, and offering them bargains.
Use Promotions for discounts across product ranges or store-wide sales.
Use Price Books for setting a particular price point on a Product for a particular Customer Groups and/or Outlets.

Entities

This API is designed around two entities - Price Books, and Price Book Products. A Price Book contains multiple Price Book Products.

Price Books typically specify Customer Groups [or all customers], Outlets [or all outlets], and a date range.
Price Book Products normally have multiple entries per Price Book. Price Book Products will always have a Retail Price and a Product id. You can also specify Loyalty Values for each entry. To set up tiered pricing, you can add multiple Price Book Products for the same Product id, but you should vary the min_units and max_units for each entry.
Customer Groups can be managed using the Customer Groups API

Recommended Workflows

Retrieving Price Books
Creating and Updating Price Books
Creating and Updating Price Book Product Entries

Note: You may not create/update/delete more than 100 entities within a single API call.

Retrieving Price Book Information

Listing Price Books (GET)

The GET /api/3.0/price_books endpoint will provide you with a list of all the current Price Books on the system. This should return a payload which looks as follows:

{
  "data": [
    {
        "outlets": [
          {
            "id": "06326976-9d65-11ed-fa40-1347e4b4ae6d",
            "name": "Main Outlet",
            "default_tax_id": "06326976-9d65-11ed-fa40-134a7a8a729f",
            "currency": "CAD",
            "display_prices": "exclusive",
            "time_zone": "America/Montreal",
            "physical_suburb": "Ville-Marie",
            "physical_city": "Montréal",
            "physical_postcode": "H2Y 1A6",
            "physical_state": "Québec",
            "email": "",
            "deleted_at": null,
            "latitude": "45.5121974",
            "longitude": "-73.5532286",
            "version": 28498806059,
            "physical_address_1": "700 Rue Saint-Antoine E",
            "physical_address_2": "",
            "physical_country_id": "CA",
            "attributes": [
              {
                "key": "low_stock_warning",
                "value": "1"
              }
            ],
            "currency_symbol": "$"
          },
          ...
        ],
        "customer_groups": [
          {
            "id": "06326976-9d65-11ed-fa40-1347e4ab160b",
            "name": "All Customers",
            "group_id": "1111111111",
            "retailer_id": "06326976-9d65-11ed-fa40-1347e4a95bd5",
            "version": 23775369886,
            "created_at": "2022-08-03T16:18:21+00:00",
            "updated_at": "2022-08-03T16:18:21+00:00",
            "deleted_at": null
          }
        ],
        "name": "General Price Book (All Products)",
        "id": "06326976-9d65-11ed-fa40-1347e4acc32d",
        "type": "BASE",
        "version": 23775369891,
        "created_at": "2022-08-03T16:18:21+00:00",
        "updated_at": "2022-08-03T16:18:21+00:00",
        "deleted_at": null,
        "restrict_to_platform_key": "0",
        "restrict_to_platform_label": "All platforms",
        "valid_from": null,
        "valid_to": null
    },
    ...
  ],
  "version": {
    "min": 23775369891,
    "max": 29552319748
  }
}

Listing the Products in a Particular Price Book (GET)

The endpoint GET /api/2.0/price_books/:price_book_id/products will provide you with a list of the Price Book Products for the given Price Book id.

{
    "data": [
        {
            "product_id": "0242ac11-0002-11ea-f95f-52e4a4d6cc35",
            "price_book_id": "0242ac19-002c-11ea-e229-671ea4b40c53",
            "id": "0242ac19-002c-11ea-e229-671ea8c67f50",
            "loyalty_value": 1,
            "max_units": 10,
            "created_at": "2020-03-16T00:39:56+00:00",
            "updated_at": "2020-03-16T00:40:00+00:00"
        },
        ...
    ],
    "version": {
        "max": 155956,
        "min": 155956
    }
}

Listing Price Book Product entries for a given Product

The endpoint /api/2.0/products/:product_id/products will provide you with a list of the Price Book Products for the given Product. You can use the returned price_book_ids to retrieve information about the Price Books.

Creating and Updating Price Books

Creating Price Books (POST)

To create a Price Book using the /api/3.0/price_books endpoint you need to provide at least the name, list of Customer Groups and list of Outlets for the Price Book.

The Price Book body should have the following form. You do not need to provide the id or deleted at columns - they are display here for completeness.

{
    "data": {
        "id":                     string: The id of the Price Book (auto-generated)
        "name":                   string: Price Book name
        "customer_group_ids":     array: Customer Group IDs
        "outlet_ids":             array: Outlet IDs
        "valid_from":             string: The date when the Price Book becomes active
        "valid_to":               string: The date when the Price Book becomes inactive
        "restrict_to_platform":   string: Whether it's in store (1), ecommerce (2), or both (0)
        "deleted_at":             string: When the Price Book was deleted (auto-generated)
    }
}

This will return the generated Price Book details as follows:

{
    "data": {
        "customer_group_ids": ["28020918-a068-aae4-11e9-cad0d053ea28"],
        "outlet_ids": ["06326976-9d65-11ed-fa40-1347e4b4ae6d"],
        "id": "0242ac19-002c-11ea-e229-670ccb477df1",
        "name": "Test Price Book"
    }
}

Updating Price Books (PUT)

To update a Price Book use the /api/3.0/price_books/:price_book_id endpoint. The name and the list of Customer Groups may not be blank.

{
    "data": {
        "customer_group_ids": ["28020918-a068-aae4-11e9-cad0d053ea28"],
        "outlet_ids": ["06326976-9d65-11ed-fa40-1347e4b4ae6d"],
        "id": "0242ac19-002c-11ea-e229-670ccb477df1",
        "name": "Updated Test Price Book"
    }
}

Deleting Price Books (DELETE)

To delete a Price Book use the DELETE /api/2.0/price_books/:price_book_id endpoint. Only the Price Book id is required.

If you wish to delete a Price Book you do not need to delete the Price Book Products first - this will happen automatically.

{
    "data": {
        "customer_group_ids": ["28020918-a068-aae4-11e9-cad0d053ea28"],
        "outlet_ids": ["06326976-9d65-11ed-fa40-1347e4b4ae6d"],
        "id": "0242ac19-002c-11ea-e229-670ccb477df1",
        "name": "Updated Test Price Book"
    }
}

Creating and Updating Price Book Product Entries

It is important to note that 'Price Book Products' are not unique per Product and Price Book combination. A Product can appear multiple times in the same Price Book, with different values for min_units and max_units. This enables you to restrict the number of items a customer can buy at a discounted rate, or require a minimum amount purchased to receive the rate ('tiered' pricing).

Creating Price Book Products (POST)

To create a Price Book product using the POST /api/2.0/price_books/:price_book_id/products endpoint you need to provide at least the Price Book id, and an array of at least one Product entity containing the Product id and the retail price for the product. The list of Products associated with the given Price Book is returned.

The Price Book product body should have the following form. You do not need to provide the id, created_at, updated_at or deleted at columns - they are display here for completeness.

{
    "data": [
      {
        "id":             string: The id of the Price Book Product (auto-generated)
        "product_id":     string: The ID of the associated product
        "price_book_id":  string: The ID of the Price Book this product belongs to
        "price":          double: Retail price
        "loyalty_value":  double: Price Book defined loyalty value
        "tax_id":         string: The id for the tax rate
        "min_units":      double: The minimum number of items for which this price will be used
        "max_units":      double: The maximum number of items for which this price will be used
        "created_at":     string: Creation timestamp in UTC (auto-generated)
        "updated_at":     string: Last update timestamp in UTC (auto-generated)
        "deleted_at":     string: Deletion timestamp in UTC (auto-generated)
      }
    ]
}

This will return the generated Price Book Product details as follows:

{
    "data": [
        {
            "created_at": "2020-03-15 22:32:10",
            "id": "0242ac19-002c-11ea-e229-670ccf9ee188",
            "price_book_id": "0242ac19-002c-11ea-e229-670ccb477df1",
            "product_id": "0242ac11-0002-11ea-f95f-52e4a4d6cc35",
            "updated_at": "2020-03-15 22:32:10"
        },
        ...
    ]
}

Updating Price Book Products (PATCH)

To update a product in a Price Book using the PATCH /api/2.0/price_books/:price_book_id/products endpoint you need to provide an array of at least one Price Book Product entity containing the Price Book Product id and the retail price of the product. Each of the Price Book Product ids provided must already exist in the given Price Book. The list of Price Book Products associated with the given Price Book is returned.

{
    "data": [
        {
            "product_id": "0242ac11-0002-11ea-f95f-52e4a4d6cc35",
            "price_book_id": "0242ac19-002c-11ea-e229-671ea4b40c53",
            "id": "0242ac19-002c-11ea-e229-671ea8c67f50",
            "loyalty_value": 1,
            "max_units": 10,
            "created_at": "2020-03-16T00:39:56+00:00",
            "updated_at": "2020-03-16T00:40:00+00:00"
        },
        ...
    ]
}

Updating Price Book Products (PUT)

To update a product in a Price Book using the PUT /api/2.0/price_books/:price_book_id/products endpoint you need to provide an array of at least one Price Book Product entity containing the Price Book Product id and the retail price of the product. Each of the Price Book Product ids provided must already exist in the given Price Book. The list of Price Book Products associated with the given Price Book is returned.

{
    "data": [
        {
            "product_id": "0242ac11-0002-11ea-f95f-52e4a4d6cc35",
            "price_book_id": "0242ac19-002c-11ea-e229-671ea4b40c53",
            "id": "0242ac19-002c-11ea-e229-671ea8c67f50",
            "loyalty_value": 1,
            "max_units": 10,
            "created_at": "2020-03-16T00:39:56+00:00",
            "updated_at": "2020-03-16T00:40:00+00:00"
        },
        ...
    ]
}

Deleting Price Book Products (DELETE)

To delete one or more products from a Price Book using the DELETE /api/2.0/price_books/:price_book_id/products endpoint, you need to provide the Price Book id and an array of least one Price Book Product id. This will return a list of all the Price Book Products for the given Price Book that have not been deleted.

{
    "data": [
        {
            "product_id": "0242ac11-0002-11ea-f95f-52e4a4d6cc35",
            "price_book_id": "0242ac19-002c-11ea-e229-671ea4b40c53",
            "id": "0242ac19-002c-11ea-e229-671ea8c67f50",
            "loyalty_value": 1,
            "max_units": 10,
            "created_at": "2020-03-16T00:39:56+00:00",
            "updated_at": "2020-03-16T00:40:00+00:00"
        },
        ...
    ]
}