Apply Square-Defined Discounts to Orders

Applies to: Orders APIOrders API | Catalog APICatalog API

Learn how to apply preconfigured discounts to an order.

Overview

Pricing options configured for an order affect the way an order's price is calculated. For more information, see Square applies taxes and discountsSquare applies taxes and discounts. Use the pricing option to have Square apply discounts based on pricing rules you defined in the catalog.

First, create the products you want to sell. Define discounts on these items by creating a pricing rule. Using the Catalog API, do the following:

Create two products (CatalogItemCatalogItem objects). For this exercise, coffee and tea items are created.
Create a pricing rule that offers a 10% discount on these products:
- Create a product set (CatalogProductSetCatalogProductSet object) consisting of the coffee and tea items. The pricing rule you create is applied by Square to items in the product set.
- Create a discount (CatalogDiscountCatalogDiscount object) that defines the percentage discount (10%).
- Create a pricing rule (CatalogPricingRuleCatalogPricingRule object) that identifies the discount and the product set to which the discount applies.

You then create example orders to explore how the Square-applied discounts affect the order's pricing calculation:

Create an order for the coffee and tea items. In the request, specify the pricing option (OrderPricingOptionsOrderPricingOptions) to request a Square-applied discount. The discount applies to all line items in the order.
Create an order to explore how the pricing list (OrderLineItemPricingBlocklistsOrderLineItemPricingBlocklists) is used to block Square from applying the discount to specific line items.
Update the order to remove the Square-applied discount from specific line items. You can explore how to use fields_to_clear in UpdateOrderUpdateOrder to remove discounts from specific line items.

For more information, see How pricing rule-based discounts workHow pricing rule-based discounts work.

1. Create two products for sale

Call BatchUpsertCatalogObjectsBatchUpsertCatalogObjects to create two CatalogItem objects (coffee and tea items).

Batch upsert catalog objects

Copy

Verify the response. Note the following information:

You need the item IDs to create a product set.
You need the item variation IDs to place an order.

The following is an example response fragment:

Copy

Expand

{
  "objects": [
    {
      "type": "ITEM",
    },
    {
      "type": "ITEM",
    }
  ],
  "id_mappings": [
    {
      "client_object_id": "#my-coffee",
      "object_id": "A7AMURM7GOAIKXPOIEYRHQBL"
    },
    {
      "client_object_id": "#my-tea",
      "object_id": "L2T4V6U5HZTXUVLDTXV5NHLO"
    },
    {
      "client_object_id": "#small-hot-coffee",
      "object_id": "TUC4Z3GUU7FSMVGOHKHZRW7N"
    },
    {
      "client_object_id": "#small-hot-tea",
      "object_id": "FJRIZ2O4AI4EMCA6KP5FLDAJ"
    }
  ]
}

2. Create a rule-based discount for the products

This step configures the products with a rule-based discount. The pricing rule you create applies to a product set. Therefore, you first create a product set consisting of the coffee and tea items:

Create a CatalogProductSetCatalogProductSet object to which the rule applies.
Create a CatalogDiscountCatalogDiscount object that defines a percentage-based discount.
Create a CatalogPricingRuleCatalogPricingRule object that identifies the discount and the product set to which the discount applies.

Call BatchUpsertCatalogObjectsBatchUpsertCatalogObjects to create all these items in a single request. Update the code by providing the IDs of the coffee and tea items for the product set.

Batch upsert catalog objects

Copy

The following is an example response fragment:

Copy

Expand

{
  "objects": [
    {
      "type": "PRODUCT_SET",
      "id": "2TFKNV52NE4OUL4TQ36JXDUX",
        "product_ids_any": [
          "A7AMURM7GOAIKXPOIEYRHQBL",
          "L2T4V6U5HZTXUVLDTXV5NHLO"
        ]
      }
    },
    {
      "type": "DISCOUNT",
      "id": "NQGJHG7AJJKMMW4ZCBBJJ4RG",
      "discount_data": {
        "name": "10% discount",
        "discount_type": "FIXED_PERCENTAGE",
        "percentage": "10.0"
      }
    },
    {
      "type": "PRICING_RULE",
      "pricing_rule_data": {
        "name": "PRICINGRULE10PCCOFFEEDISCOUNT",
        "discount_id": "NQGJHG7AJJKMMW4ZCBBJJ4RG",
        "match_products_id": "2TFKNV52NE4OUL4TQ36JXDUX",
        "application_mode": "AUTOMATIC"
      }
    }
  ],
  "id_mappings": [
    {
      "client_object_id": "#ProductSetID",
      "object_id": "2TFKNV52NE4OUL4TQ36JXDUX"
    },
    {
      "client_object_id": "#DiscountID",
      "object_id": "NQGJHG7AJJKMMW4ZCBBJJ4RG"
    },
    {
      "client_object_id": "#my-first-pricing-rule1",
      "object_id": "TL3AYTOI4DB4HYTL2WK3QJ6J"
    }
  ]
}

3. Test Square-applied discounts

Now you're ready to create orders and explore Square-applied discounts using pricing options.

3.1 Create an order with Square-applied discounts enabled

Call CreateOrderCreateOrder to create an order for a cup of coffee. The request includes the pricing_options with auto_apply_discounts enabled. Make sure you provide the variation ID of the small coffee in the request.

Create order

Copy

In the response, notice how pricing calculations are affected by the Square's application of the discounts configured for the items. For example:

The line item includes applied_discounts, which identifies the applied discount.
The order includes discounts, which provides details about the applied discount.

The following is an example response fragment:

Copy

Expand

{
  "order":{
    "id":"5FLV8dgGYHgRdrE4XOR9W8RMxh4F",
    "location_id":"7WQ0KXC8ZSD90",
    "line_items":[
      {
        "uid":"PpAcZ9GNazqgGpy99BHbUC",
        "catalog_object_id":"TUC4Z3GUU7FSMVGOHKHZRW7N",
        "quantity":"1",
        "name":"8 oz coffee",
        "variation_name":"",
        "base_price_money":{
          "amount":300,
          "currency":"USD"
        },
        "total_discount_money":{
          "amount":30,
          "currency":"USD"
        },
        "applied_discounts":[
          {
            "uid":"ApDUTXKYyDukeiA98cG6mD",
            "discount_uid":"a5nircWuDBWzPBh797O5SD",
            "applied_money":{
              "amount":30,
              "currency":"USD"
            }
          }
        ],
        "item_type":"ITEM"
      }
    ],
    "discounts":[
      {
        "uid":"a5nircWuDBWzPBh797O5SD",
        "catalog_object_id":"NQGJHG7AJJKMMW4ZCBBJJ4RG",
        "name":"10% discount",
        "percentage":"10.0",
        "applied_money":{
          "amount":30,
          "currency":"USD"
        },
        "type":"FIXED_PERCENTAGE",
        "scope":"LINE_ITEM",
        "pricing_rule_id":"TL3AYTOI4DB4HYTL2WK3QJ6J"
      }
    ],
    "total_money":{
      "amount":270,
      "currency":"USD"
    },
    "pricing_options":{
      "auto_apply_discounts":true
    }
  }
}

3.2 Update an order to remove previously applied discounts

You can call UpdateOrderUpdateOrder to remove discounts applied to specific line items. Add fields_to_clear to identify the line items and discounts you want to remove. Update the preceding order by removing the discount applied to the line item. Make sure you provide the order ID, location ID, line item ID, and ID of the discount you want to remove.

Update order

Copy

In the response, review the pricing calculation updates. For example:

The line item includes pricing_blocklists, which shows the discount that's blocked from being applied by Square.
The line item shows no discount and the order pricing is updated accordingly.

Copy

Expand

{
  "order": {
    "id": "5FLV8dgGYHgRdrE4XOR9W8RMxh4F",
    "location_id": "7WQ0KXC8ZSD90",
    "line_items": [
      {
        "uid": "PpAcZ9GNazqgGpy99BHbUC",
        "catalog_object_id": "TUC4Z3GUU7FSMVGOHKHZRW7N",
        "quantity": "1",
        "name": "8 oz coffee",
        "variation_name": "",
        "base_price_money": {
          "amount": 300,
          "currency": "USD"
        },
        "total_discount_money": {
          "amount": 0,
          "currency": "USD"
        },
        "pricing_blocklists": {
          "blocked_discounts": [
            {
              "uid": "5vcvLw4SgLJhCtxzXESzRD",
              "discount_catalog_object_id": "NQGJHG7AJJKMMW4ZCBBJJ4RG"
            }
          ]
        }
      }
    ],
  }
}

3.3 Create an order with Square-applied discounts enabled, but block specific line items

Create an order for both coffee and tea, but block one of the items from the Square-applied discount. In the following CreateOrder request:

pricing_options is specified to request Square-applied discounts.
One of the line items specifies pricing_blocklists and includes discount_catalog_object_id to block the discount from being applied.

Make sure you provide the coffee and tea item variation IDs, location ID, and the ID of the CatalogDiscount you created in step 2.

Create order

Copy

In the response, verify the pricing calculations. The discount is applied by Square to only one item. The following is an example response fragment:

Copy

Expand

{
  "order": {
    "id": "H6cee9rVqMpk72u7PBNHpXwRzb4F",
    "location_id": "7WQ0KXC8ZSD90",
    "line_items": [
      {
        "uid": "65LYqUkTc8RRpnvDCQGMFD",
        "catalog_object_id": "C4GMNPPM72TKN6ZCQ2P6I7EA",
        "quantity": "1",
        "name": "8 oz coffee",
        "variation_name": "",
        "base_price_money": {
          "amount": 300,
          "currency": "USD"
        },
        "total_discount_money": {
          "amount": 30,
          "currency": "USD"
        },
        "applied_discounts": [
          {
            "uid": "BMzT5qieOsZE6xxV9YukI",
            "discount_uid": "BQbtlz2qPEDm1Krbb8W4s",
            "applied_money": {
              "amount": 30,
              "currency": "USD"
            }
          }
        ],
      },
      {
        "uid": "DGguEBcQASRM1b4QdUNNfD",
        "catalog_object_id": "4I3XGUSLC4GYG5TV3RGYFCLE",
        "quantity": "1",
        "name": "8 oz tea",
        "variation_name": "",
        "base_price_money": {
          "amount": 200,
          "currency": "USD"
        },
        "total_discount_money": {
          "amount": 0,
          "currency": "USD"
        },
        "pricing_blocklists": {
          "blocked_discounts": [
            {
              "uid": "blocked-discount-uid1",
              "discount_catalog_object_id": "62PZMXOYOVQFAAPH6XXNGOWB"
            }
          ]
        }
      }
    ],
    "discounts": [
      {
        "uid": "BQbtlz2qPEDm1Krbb8W4s",
        "catalog_object_id": "62PZMXOYOVQFAAPH6XXNGOWB",
        "name": "10% discount",
        "percentage": "10.0",
        "applied_money": {
          "amount": 30,
          "currency": "USD"
        },
        "type": "FIXED_PERCENTAGE",
        "scope": "LINE_ITEM",
        "pricing_rule_id": "MJU7VWXVBTVDEGME7SWUTQD7"
      }
    ],
    "total_discount_money": {
      "amount": 30,
      "currency": "USD"
    },
    "total_money": {
      "amount": 470,
      "currency": "USD"
    },
    "net_amounts": {
      "total_money": {
        "amount": 470,
        "currency": "USD"
      },
      "discount_money": {
        "amount": 30,
        "currency": "USD"
      },
    },
    "pricing_options": {
      "auto_apply_discounts": true
    }
  }
}

Docs

Apply Square-Defined Discounts to Orders Beta release

On this page

Overview

1. Create two products for sale

2. Create a rule-based discount for the products

3. Test Square-applied discounts

3.1 Create an order with Square-applied discounts enabled

3.2 Update an order to remove previously applied discounts

3.3 Create an order with Square-applied discounts enabled, but block specific line items

On this page

Was this page helpful?