Create pricing rules to apply discounts based on the number of products (volume), a combination of items (bundle), or a specific time period (timeframe).
Docs Home
Dev Essentials
Payments Commerce Customers Staff Merchants
Partnerships
Release notes

Docs

Docs Home
Dev Essentials
Payments
Commerce
Customers
Staff
Merchants
Partnerships
Release notes
Docs
Catalog API

Automatically Apply Discounts

You can use the Square Catalog API to configure pricing rules to enable the automatic application of discounts to payments made with Square Point of Sale applications including Square for Retail, Square for Restaurants, and Square Appointments.

The discount can be a volume discount like a Buy One Get One (BOGO), a minimum order discount, or an exact quantity purchase discount. It can be a bundled discount applying to a combination of categories of purchased items. It can also be a time-based discount applied over a specified period of time, like a happy hour.

Link to section
Requirements and limitations

  • Pricing rule-based discounts are not supported in the Reader SDK or the Checkout API.

  • Pricing rules created through the Catalog API are not editable in Square Point of Sale.

Link to section
How pricing rule-based discounts work

Pricing rule-based discounts can be applied based on:

  • Specific items (or categories of items) purchased.

  • The time of day, the day of the week, or a window of a promotion.

To set pricing rules to enable the automatic application of discounts, you typically use the following types of CatalogObject instances:

  • Product Set. Represents a collection of catalog products. Product sets can be a collection of different Catalog object types, such as an ITEM, CATEGORY, or ITEM_VARIATION. You can also specify whether one or all products must be present and in what quantity.

  • Pricing Rule. Represents a set of conditions under which a discount or fixed price applies to a product set.

  • Time Period. Represents a (potentially recurring) time period. Dates and times use the iCal Date-Time Format.

Important

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

Link to section
Before you start

To follow the instructions presented in this section, you must have Drinks and Meal categories created in your catalog.

Link to section
Create a Drinks category

Follow the example to create the Drinks category. Make sure you copy the ID of the resulting CatalogObject of the CATEGORY type. You need the ID later.

Link to section
Request

Upsert Catalog Object
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
curl https://connect.squareupsandbox.com/v2/catalog/object \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "object": {
      "id": "#drinks",
      "type": "CATEGORY",
      "category_data": {
        "name": "Drinks"
      }
    }
  }'
Try in API Explorer

The "id": "#drinks" key-value pair is optional. It is required only if the Drinks category object is referenced elsewhere in the same request payload.

Link to section
Response

The successful operation returns a 200 OK response with the payload similar to the following:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
{
  "catalog_object": {
    "type": "CATEGORY",
    "id": "GXFTT46M3RCBR6LV54HKALC6",
    "updated_at": "2020-06-01T18:17:18.159Z",
    "version": 1591035438159,
    "is_deleted": false,
    "present_at_all_locations": true,
    "category_data": {
      "name": "Drinks"
    }
  },
  "id_mappings": [
    {
      "client_object_id": "#drinks",
      "object_id": "GXFTT46M3RCBR6LV54HKALC6"
    }
  ]
}

Link to section
Create a Meal category

Follow the example to create the Meal category. Make sure you copy the ID of the resulting CatalogObject of the CATEGORY type. You need the ID later.

Link to section
Request

Upsert Catalog Object
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
curl https://connect.squareupsandbox.com/v2/catalog/object \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "object": {
      "id": "#meal_category",
      "type": "CATEGORY",
      "category_data": {
        "name": "Meal"
      }
    }
  }'
Try in API Explorer

The "id": "#meal_category" key-value pair is optional. It is required only if the Meal category is referenced elsewhere in the same request payload.

Link to section
Response

The successful operation returns a 200 OK response with the payload similar to the following:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
{
  "catalog_object": {
    "type": "CATEGORY",
    "id": "GCCTVZOTCOPI246SREKXNMYX",
    "updated_at": "2020-06-02T00:15:13.884Z",
    "version": 1591056913884,
    "is_deleted": false,
    "present_at_all_locations": true,
    "category_data": {
      "name": "Meal"
    }
  },
  "id_mappings": [
    {
      "client_object_id": "#meal_category",
      "object_id": "GCCTVZOTCOPI246SREKXNMYX"
    }
  ]
}

Link to section
Related topics

On this page
We've made improvements to our docs.
Prefer the old format?