Create Customer Group Discounts

Applies to: Catalog API | Customer Groups API | Customers API

Learn how to use a pricing rule to make customers in selected customer groups eligible to receive specified discounts to matched products.

In addition to using CatalogPricingRule to have a discount automatically applied to specified products sold to any buyer, you can use it to have the discount automatically applied to customers belonging to one or more customer groups. This second use case is referred to as customer group discounts.

To set up customer group discounts, you must provide a means to accept input from the seller to determine which groups of customers can receive what type of discounts to which product sets. When the decision is finalized, you can proceed to create or update a pricing rule to configure the discount and eligibility of specific customers.

In general, the programming workflow involves the following steps:

• Use the Customer Groups API to get the ID of a customer group containing customers eligible for receiving discounts. If the customer group hasn't been created, you must call the Customer Groups API to create the group. If necessary, you also need to call the Customers API to create customer profiles for targeted customers and add the customers to the newly created customer group.
• Use the Catalog API and call the UpsertCatalogObject endpoint to create or update an existing CatalogDiscount object to configure the planned discount.
• Use the Catalog API and call the UpsertCatalogObject endpoint to create or update an existing CatalogProductSet object to include the products to which the discount applies.
• Use the Catalog API and call the UpsertCatalogObject endpoint to create or update an existing CatalogPricingRule object to set up the rule to have the specified discount automatically applied to matched products when an eligible customer orders a matched product item.

If the targeted customers are already members of an existing customer group, you can call the ListCustomerGroups endpoint of the Customer Groups API to retrieve available groups, examine the result to extract the customer group of interest, and obtain the group ID.

The successful response might look similar to the following:

{
   "groups":[
      {
         "id":"6B8DE9B3-9AF2-4CDA-9938-D1A5BC5D87E0",
         "name":"Students",
         "created_at":"2021-02-24T14:32:07.334Z",
         "updated_at":"2021-02-24T14:35:45Z"
      }
   ]
}

In this example, the seller has only one customer group named Students. The group ID is 6B8DE9B3-9AF2-4CDA-9938-D1A5BC5D87E0. Make note of the group ID. You need it later to configure customer group discounts.

If the targeted customers don't belong to any known customer group, you can call the Customer Groups API CreateCustomerGroup endpoint to create a new customer group and then call AddGroupToCustomer to make selected customers members of the group. Make sure to note the group ID before proceeding.

For a new promotional campaign, you must create a new discount as represented by a CatalogDiscount object. To do so, call the UpsertCatalogObject endpoint, or its batched version, of the Catalog API.

The successful response is similar to the following output:

{
   "catalog_object":{
      "type":"DISCOUNT",
      "id":"BY676RE3HE5UWOUDCM6ISM5Z",
      "updated_at":"2021-03-17T19:46:30.624Z",
      "version":1614714390624,
      "is_deleted":false,
      "present_at_all_locations":true,
      "discount_data":{
         "name":"Student Discount",
         "discount_type":"FIXED_PERCENTAGE",
         "percentage":"10.0"
      }
   },
   "id_mappings":[
      {
         "client_object_id":"#StudentDiscount",
         "object_id":"BY676RE3HE5UWOUDCM6ISM5Z"
      }
   ]
}

In this example, the newly created CatalogDiscount object encapsulates a discount off the sale price by 10%. Make note of the returned CatalogDiscount object ID (BY676RE3HE5UWOUDCM6ISM5Z). You need it to configure the pricing rule later.

If you want to use an existing discount object, you can call the SearchCatalogObjects endpoint to retrieve the discount object. In any case, make note of the ID of the returned CatalogDiscount object.

The following example shows how to create a new product set to apply a discount to. The product set includes any product for sale by the seller.

The "all_products": true attribute makes the resulting product set to include all products in the seller's catalog.

The successful response looks similar to the following output:

{
   "catalog_object":{
      "type":"PRODUCT_SET",
      "id":"MRNVLLYM77NZJNP3FMIJMGCX",
      "updated_at":"2021-03-17T19:50:49.076Z",
      "version":1614714649076,
      "is_deleted":false,
      "present_at_all_locations":true,
      "product_set_data":{
         "name":"All Product Set",
         "all_products":true
      }
   },
   "id_mappings":[
      {
         "client_object_id":"#AllProductSet",
         "object_id":"MRNVLLYM77NZJNP3FMIJMGCX"
      }
   ]
}

Make note of the returned CatalogProductSet object ID (MRNVLLYM77NZJNP3FMIJMGCX). You need it to configure the pricing rule later.

With the discount, product sets, and customer groups in hand (as referenced by their respective IDs), it's time to set up a pricing rule to automatically apply the discount to the products sold to the members of a customer group. You can do so by creating a new CatalogPricingRule object or updating an existing one.

The following example shows creating a pricing rule object to apply a fixed discount to any product sold to customers in any of the specified customer groups.

To create a pricing rule, call the UpsertCatalogObject endpoint to create a CatalogPricingRule object, with a rule to have a specific discount applied to a specified product set purchased by members of specified customer groups.

The discount, product set, and customer groups are all referenced by their respective IDs.

The successful REST API response is similar to the following output:

{
   "catalog_object":{
      "type":"PRICING_RULE",
      "id":"5SUNA6NKIYPKFZZBEJZKZ243",
      "updated_at":"2021-03-17T19:53:20.43Z",
      "version":1614714800430,
      "is_deleted":false,
      "present_at_all_locations":true,
      "pricing_rule_data":{
         "name":"Student Discount Pricing Rule",
         "discount_id":"BY676RE3HE5UWOUDCM6ISM5Z",
         "match_products_id":"MRNVLLYM77NZJNP3FMIJMGCX",
         "customer_group_ids_any":[
            "6B8DE9B3-9AF2-4CDA-9938-D1A5BC5D87E0"
         ]
      }
   },
   "id_mappings":[
      {
         "client_object_id":"#StudentDiscountPricingRule",
         "object_id":"5SUNA6NKIYPKFZZBEJZKZ243"
      }
   ]
}

The resulting pricing rule is automatically applied to itemized products in a shopping cart when a matched customer places an order of any of the seller's product. For example, when an eligible customer orders a $5.00 latte, this pricing rule reduces the charge by $0.50. The customer pays only $4.50 for the drink at the cash register or checkout.