Create Volume Discounts

Applies to: Catalog API

Learn how to create discounts based on the number of products, such as "Buy One Get One Free" or "10% Off Three or More Items".

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.

Because this example uses a BOGO discount for customers to buy two beers and get one free pizza, you must have Beer and Pizza CatalogCategory objects created in your catalog. To create them, follow this example.

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.

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:

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:

{
  "catalog_object": {
    "type": "DISCOUNT",
    "id": "FJYAGNWCJSX42774FCLQZ25Z",
    "updated_at": "2023-02-27T17:58:25.27Z",
    "version": 1591034305270,
    "is_deleted": false,
    "present_at_all_locations": true,
    "discount_data": {
      "name": "Buy one get one free",
      "discount_type": "FIXED_PERCENTAGE",
      "percentage": "100.0"
    }
  },
  "id_mappings": [
    {
      "client_object_id": "#bogoDiscount",
      "object_id": "FJYAGNWCJSX42774FCLQZ25Z"
    }
  ]
}

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.

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.

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

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

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:

{
  "catalog_object": {
    "type": "PRODUCT_SET",
    "id": "NS5Z4ZNTUPVESPT6JBJWU3IZ",
    "updated_at": "2023-02-27T18:23:30.461Z",
    "version": 1591035810461,
    "is_deleted": false,
    "present_at_all_locations": true,
    "product_set_data": {
      "product_ids_any": [
        "GXFTT46M3RCBR6LV54HKALC6"
      ],
      "quantity_exact": 2
    }
  },
  "id_mappings": [
    {
      "client_object_id": "#AnyTwoBeers",
      "object_id": "NS5Z4ZNTUPVESPT6JBJWU3IZ"
    }
  ]
}

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.

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"
}

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:

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.

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

{
  "catalog_object": {
    "type": "PRODUCT_SET",
    "id": "WSPNQO56GCYDCFSQWXS534TS",
    "updated_at": "2023-02-27T22:28:04.545Z",
    "version": 1591050484545,
    "is_deleted": false,
    "present_at_all_locations": true,
    "product_set_data": {
      "product_ids_any": [
        "HYEST56N3RDBR6LV57AGALC5"
      ],
      "quantity_exact": 1
    }
  },
  "id_mappings": [
    {
      "client_object_id": "#OneFreePizza",
      "object_id": "WSPNQO56GCYDCFSQWXS534TS"
    }
  ]
}

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

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.

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

{
  "catalog_object": {
    "type": "PRODUCT_SET",
    "id": "QONA975IOCAD73204NQER02G",
    "updated_at": "2023-02-27T22:29:04.545Z",
    "version": 1591050484545,
    "is_deleted": false,
    "present_at_all_locations": true,
    "product_set_data": {
        "product_ids_all": [
          "NS5Z4ZNTUPVESPT6JBJWU3IZ",
          "WSPNQO56GCYDCFSQWXS534TS"
      ],
      "quantity_exact": 1
    }
  },
  "id_mappings": [
    {
      "client_object_id": "#MatchProductSet",
      "object_id": "QONA975IOCAD73204NQER02G"
    }
  ]
}

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

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:

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

The successful response returns a payload similar to the following:

{
  "objects": [
    {
      "type": "DISCOUNT",
      "id": "FJYAGNWCJSX42774FCLQZ25Z",
      "updated_at": "2023-02-27T23:40:44.326Z",
      "version": 1591054844326,
      "is_deleted": false,
      "present_at_all_locations": true,
      "discount_data": {
        "name": "\"Buy one get one free\"",
        "discount_type": "FIXED_PERCENTAGE",
        "percentage": "100.0"
      }
    },
    {
      "type": "PRODUCT_SET",
      "id": "NS5Z4ZNTUPVESPT6JBJWU3IZ",
      "updated_at": "2023-02-27T23:40:44.326Z",
      "version": 1591054844326,
      "is_deleted": false,
      "present_at_all_locations": true,
      "product_set_data": {
        "product_ids_any": [
          "GXFTT46M3RCBR6LV54HKALC6"
        ],
        "quantity_exact": 2
      }
    },
    {
      "type": "PRODUCT_SET",
      "id": "WSPNQO56GCYDCFSQWXS534TS",
      "updated_at": "2023-02-27T23:40:44.326Z",
      "version": 1591054844326,
      "is_deleted": false,
      "present_at_all_locations": true,
      "product_set_data": {
        "product_ids_any": [
          "HYEST56N3RDBR6LV57AGALC5"
        ],
        "quantity_exact": 1
      }
    },
    {
      "type": "PRODUCT_SET",
      "id": "QONA975IOCAD73204NQER02G",
      "updated_at": "2023-02-27T22:29:04.545Z",
      "version": 1591050484545,
      "is_deleted": false,
      "present_at_all_locations": true,
      "product_set_data": {
        "product_ids_all": [
          "NS5Z4ZNTUPVESPT6JBJWU3IZ",
          "WSPNQO56GCYDCFSQWXS534TS"
        ],
        "quantity_exact": 1
      }
    }
  ],
  "id_mappings": [
    {
      "client_object_id": "#BOGODiscount",
      "object_id": "FJYAGNWCJSX42774FCLQZ25Z"
    },
    {
      "client_object_id": "#AnyTwoBeers",
      "object_id": "NS5Z4ZNTUPVESPT6JBJWU3IZ"
    },
    {
      "client_object_id": "#OneFreePizza",
      "object_id": "WSPNQO56GCYDCFSQWXS534TS"
    },
    {
      "client_object_id": "#MatchProductSet",
      "object_id": "QONA975IOCAD73204NQER02G"
    }
  ]
}

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

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.

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

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.

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

{
  "catalog_object": {
    "type": "PRICING_RULE",
    "id": "7MZW6RTZ2FSDDPPJLLAQ3WF4",
    "updated_at": "2023-02-27T20:04:28.467Z",
    "version": 1591056268467,
    "is_deleted": false,
    "present_at_all_locations": true,
    "pricing_rule_data": {
      "name": "BOGO Rule for Buy Two Beers and Get One Free Pizza",
      "discount_id": "FJYAGNWCJSX42774FCLQZ25Z",
      "match_products_id": "QONA975IOCAD73204NQER02G",
      "exclude_products_id": "NS5Z4ZNTUPVESPT6JBJWU3IZ",
      "application_mode": "AUTOMATIC"
    }
  },
  "id_mappings": [
    {
      "client_object_id": "#BOGOPricingRule",
      "object_id": "7MZW6RTZ2FSDDPPJLLAQ3WF4"
    }
  ]
}

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