Create Time-Based Discounts

Applies to: Catalog API

Learn how to create discounts that apply during a specific active time period, such as a holiday sale.

Time-based discounts automatically apply during an active time period that you specify in your pricing rule. In this example, you learn how to define a Happy Hour discount to apply a 25% discount to all drinks purchased every day from 3 PM to 6 PM.

The local time is determined by the device running the Point of Sale application.

You must have a Drinks category of the CatalogCategory type created in your catalog. To create the Drinks category, follow this example.

Create a 25% discount that is applied during the Happy Hour sale. Create a product set and assign your Drink category as product_ids_any to include all available drinks. Create a time period of 1 PM – 7 PM for 50 weeks beginning May 23, 2019.

The following cURL example shows how to call the Catalog API UpsertCatalogObject endpoint to create a 25% Off Happy Hour discount:

If successful, the operation returns the configured CatalogDiscount object for the 25% off Happy Hour discount as the payload of a 200 OK response similar to the following:

{
  "catalog_object": {
    "type": "DISCOUNT",
    "id": "GAJS57APBZX445NOYMINZZUC",
    "updated_at": "2020-06-02T18:10:35.233Z",
    "version": 1591121435233,
    "is_deleted": false,
    "present_at_all_locations": true,
    "discount_data": {
      "name": "25% Off Happy Hour",
      "discount_type": "FIXED_PERCENTAGE",
      "percentage": "25.0"
    }
  },
  "id_mappings": [
    {
      "client_object_id": "#25% Off Happy Hour",
      "object_id": "GAJS57APBZX445NOYMINZZUC"
    }
  ]
}

The following cURL example shows how to call the Catalog API UpsertCatalogObject endpoint to create a CatalogProductSet object containing the Drinks category. The category ID is GXFTT46M3RCBR6LV54HKALC6.

If successful, the operation returns the created CatalogProductSet object for the Drinks category as the payload of a 200 OK response similar to the following:

{
  "catalog_object": {
    "type": "PRODUCT_SET",
    "id": "IAPA75F4ZUBMCF6IVIP7FC2E",
    "updated_at": "2020-06-02T18:17:42.589Z",
    "version": 1591121862589,
    "is_deleted": false,
    "present_at_all_locations": true,
    "product_set_data": {
      "product_ids_all": [
        "GXFTT46M3RCBR6LV54HKALC6"
      ]
    }
  },
  "id_mappings": [
    {
      "client_object_id": "#Drinks",
      "object_id": "IAPA75F4ZUBMCF6IVIP7FC2E"
    }
  ]
}

You might want to make note of the object_id value (IAPA75F4ZUBMCF6IVIP7FC2E) for future references to this object.

The following cURL example shows how to call the Catalog API UpsertCatalogObject endpoint to create a CatalogTimePeriod object containing the discount event time period:

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

{
   "catalog_object":{
      "type":"TIME_PERIOD",
      "id":"DE4AZASOM7WGFIJSBZEWEMRG",
      "updated_at":"2020-06-02T19:03:11.698Z",
      "version":1591124591698,
      "is_deleted":false,
      "present_at_all_locations":true,
      "time_period_data":{
         "event":"BEGIN:VEVENT\nDURATION:PT6H\nRRULE:FREQ=WEEKLY;COUNT=50\nDTSTART:20190523T130000\nEND:VEVENT\n"
      }
   },
   "id_mappings":[
      {
         "client_object_id":"#Happy hour time period",
         "object_id":"DE4AZASOM7WGFIJSBZEWEMRG"
      }
   ]
}

Create a pricing rule that applies the 25% discount to your Drinks product set during an active time period of 1 PM – 7 PM for 50 weeks beginning May 23, 2019.

The following cURL example shows how to call the Catalog API UpsertCatalogObject endpoint to create a CatalogPricingRule object specifying a discount (as identified by the discount_id value) to be applied to a given product (as identified by the match_products_id value) in the given time period (as identified by the time_period_ids value):

In the example:

• DE4AZASOM7WGFIJSBZEWEMRG in time_period_ids is the ID of the CatalogTimePeriod object created earlier.
• IAPA75F4ZUBMCF6IVIP7FC2E is the ID of the CatalogProductSet object created earlier.
• GAJS57APBZX445NOYMINZZUC is the ID of the CatalogDiscount object created earlier.

If successful, the operation returns the configured CatalogPricingRule object specifying the automatic application of the Happy Hour discount of 25% off drinks as the payload of a 200 OK response similar to the following:

{
  "catalog_object": {
    "type": "PRICING_RULE",
    "id": "3GULP4ZWYKLJPEU6YPFFA2MC",
    "updated_at": "2020-06-02T19:27:34.968Z",
    "version": 1591126054968,
    "is_deleted": false,
    "present_at_all_locations": true,
    "pricing_rule_data": {
      "name": "Happy Hour",
      "time_period_ids": [
        "DE4AZASOM7WGFIJSBZEWEMRG"
      ],
      "discount_id": "GAJS57APBZX445NOYMINZZUC",
      "match_products_id": "IAPA75F4ZUBMCF6IVIP7FC2E",
      "application_mode": "AUTOMATIC"
    }
  },
  "id_mappings": [
    {
      "client_object_id": "#Happy Hour",
      "object_id": "3GULP4ZWYKLJPEU6YPFFA2MC"
    }
  ]
}

You now have configured the pricing rule for the automatic discount for happy hours between 1 PM and 7 PM, lasting 50 weeks, and beginning on May 23, 2019.