Create Volume Discounts

Using the Catalog API to create volume discounts involves the following programming tasks, assuming any referenced CatalogCategory objects have already been created:

  • Create a CatalogDiscount object to specify a desired discount to be applied to a product category. For a half-price discount, the discount rate is 50% to be applied to a product set. For a Buy One Get One free (BOGO) discount, the discount rate is 100% to be applied to one free item for every two items purchased.
  • Create one or more CatalogProductSet objects to specify what products to apply the discount to and, if any, which part of the products to exclude from the application of the discount. For a BOGO Free discount, a free item is offered for every two items purchased. In general, BOGO Free can be extended to mean buying two items of one product while getting one free item of another product. In this topic, BOGO carries the generalized semantics. To set up a pricing rule for a BOGO Free discount, three CatalogProductSet objects are needed, as described as follows:
    • A CatalogProductSet object to contain 2 counts of a specified category.
    • A CatalogProductSet object to contain 1 count of a specified category.
    • A CatalogProductSet object to contain the above two product sets as the target of a pricing rule, with the 2-count product set excluded from the application. For a regular discount on one or more product categories, a single CatalogProductSet specifying desired categories is needed and used as the target of the pricing rule.
  • Create a CatalogPricingRule object to set up a pricing rule for the specified discount to be applied to the targeted product sets, when any specified conditions are met.

Important

Point of Sale applications must be of version 5.15 or later to take advantage of pricing rules. For questions or feedback, contact Support.

Link to section

Before you start

Because the example used here is a BOGO discount for customers to buy two beers and get one free pizza, make sure you have a Beer and Pizza CatalogCategory objects created in your catalog. If not, follow this example to create the catalog categories.

Link to section

Step 1: Set up a discount and three product sets

To create a BOGO discount rule for Buy Two Beers Get One Free Pizza, you must create following catalog objects:

  • Discount - A CatalogDiscount object, specifying the 100% discount to be applied to the targeted product sets.
  • Any Two Beers product set - A CatalogProductSet object associated with the Beer category to be included as part of the discount base. Set the quantity_exact value to 2 as the threshold of this product set to trigger the pricing rule.
  • One Free Pizza product set - A second CatalogProductSet object associated with the Pizza category to be included as part of the target of the discount. Setting the quantity_exact value to 1 for the threshold of this product set. This product set and the Any Two Beers product set together ensures that one free pizza is offered for every two beers purchased.
  • Rule-matching product set - A third CatalogProductSet object to contain the previous two product sets to match the target of the pricing rule.
  • BOGO pricing rule - A CatalogPricingRule object to contain the BOGO discount (which is 100%), matching product sets (Any Two Beers and One Free Pizza), and an excluded product set (Any Two beers). In this BOGO example, the 100% discount takes effect when the targeted product sets match the Any Two Beers product set and the One Free Pizza product set. The exclusion clause subtracts the Any Two Beers product set from the final application of the rule.

Note

Although having a net effect of 50% discount, a BOGO discount is different from a regular 50% discount in that the discount is set as 100%, certain quantity thresholds and an exclusionary condition must be met for the discount to take effect.

Link to section

Set up a discount

To set up a discount, create a CatalogDiscount object. The following example is for a Buy One Get One (BOGO) discount to offer one free pizza for every two beers purchased:

Upsert catalog object

The percentage of 100 means that a customer gets a free offer of an item.

If successful, the operation returns the payload of a 200 OK response similar to the following:

The BOGO discount logic is specified by a combination of the rule-matching product set, which references a full-price product set of two items and a discounted product set of one item and an exclusion clause to exclude the full-price items from the discount application.

Link to section

Create the Any Two Beers product set

To apply the BOGO discount to any two beers in an order, first create a CatalogProductSet object to contain two quantities of items of the Drinks category.

Link to section

Request

The following request creates the Any Two Beers product set using the UpsertCatalogObject endpoint of the Catalog API:

Upsert catalog object

The entry in the product_ids_any list, GXFTT46M3RCBR6LV54HKALC6, is the ID of the Beer category object already created in the catalog.

Link to section

Response

If the request to create Any Two Beers product set is successful, a 200 OK response is returned with a payload similar to the following:

The resulting product set is used as the fully priced product set when setting up the pricing rule for the BOGO discount.

In production code, you can call the SearchCatalogObjects endpoint to search for the Beer category using an exact query filter to match the name attribute with the Beer string value.

Search catalog objects

And then extract the Beer category ID value from the search result, as shown:

{ "objects": [ { "type": "CATEGORY", "id": "GXFTT46M3RCBR6LV54HKALC6", "updated_at": "2023-02-27T18:17:18.159Z", "version": 1591035438159, "is_deleted": false, "present_at_all_locations": true, "category_data": { "name": "Beer" } } ], "latest_time": "2023-02-27T19:27:34.968Z" }
Link to section

Create the One Free Pizza product set

Creating the One Free Pizza product set is similar to creating the Any Two Beers product set except that the quantity_exact value is set to 1, which is the default value if you don't set it explicitly. This is shown in the following examples:

Link to section

Request

Upsert catalog object

The entry in the product_ids_any list is the ID (HYEST56N3RDBR6LV57AGALC5) of the Pizza category mentioned earlier. You can call the SearchCatalogObjects endpoint with an exact_filter matching the name attribute to the Pizza value to retrieve the category instance and obtain the ID value.

Link to section

Response

The successful response returns the created product set in the payload, as shown:

The resulting product set is used as the discounted product set when setting up the pricing rule for the BOGO discount.

Link to section

Create a rule-matching product set

For the pricing engine to apply the BOGO discount previously specified, you must also create a CatalogProductSet object to contain targeted product sets to apply the discount to.

Link to section

Request

Upsert catalog object

The product_ids_all property references the Any Two Beers product set (NS5Z4ZNTUPVESPT6JBJWU3IZ) and One Free Pizza product set (WSPNQO56GCYDCFSQWXS534TS) created earlier.

Link to section

Response

The resulting rule-matching product set is referenced in the CatalogPricingRule object to set up the BOGO discount rule.

Link to section

Batch alternative to configuring discounts and product sets

As an alternative to individually configuring discounts and product sets, you can batch the operations together in a single call. To do so, follow this example:

Link to section

Request

The following example shows how to create required product sets and the discount rule in a single call:

Batch upsert catalog objects

Link to section

Response

The successful response returns a payload similar to the following:

Link to section

Step 2: Set up the BOGO pricing rule

To set up a pricing rule for the (Buy One Get One) BOGO discount to be applied to given product categories, create the CatalogPricingRule.

Link to section

Set up a pricing rule for the BOGO discount

To set up a BOGO pricing rule for the BOGO discount, create a CatalogPricingRule, object with following properties specified in the pricing_rule_data property:

  • Assign the ID of the CatalogDiscount object to the discount_id property to select the discount to apply.
  • Assign the ID of the rule-matching CatalogProductSet object to the match_products_id to specify targeted products to apply the discount to.
  • Assign the ID of the full-price CatalogProductSet object to the exclude_products_id to exclude the specified products from the discount.
Link to section

Request

The following cURL example shows how to make a REST API request to create the BOGO pricing rule:

Upsert catalog object

The pricing_rule_data shows the BOGO logic as follows:

  • Apply a 100% discount to the rule-matching product set (QONA975IOCAD73204NQER02G), which contains a any two beers purchased and a free pizza offered. This is specified by match_products_id.
  • Exclude the Two Beers product set from the rule application.
Link to section

Response

The successful response returns in a payload the result similar to the following:

The resulting discount rule is applied automatically when the specified conditions are met.