Assign and Manage Coupons

The Retail Digital Commerce UI allows merchandisers to assign only a single coupon or coupon batch to each promotion. However, you can use the Retail Digital Commerce Admin API to associate multiple promotions with a coupon or coupon batch.

This section applies to Open Storefront Framework (OSF).

This section describes how to use the Retail Digital Commerce Admin API to associate multiple promotions with a coupon or coupon batch.

Assign Multiple Promotions to a Coupon or Coupon Batch

You must use the Retail Digital Commerce Admin API to assign multiple promotions to a coupon or coupon batch. You cannot perform these tasks on the Marketing tab in the administration interface.

You can assign promotions to a new coupon or batch when you create it or you can update an existing coupon or batch so that it applies to multiple promotions:

To assign multiple promotions to a coupon when you create it, issue a POST request to /ccadmin/v1/claimables.
To assign multiple promotions to a coupon batch when you create it, issue a POST request to /ccadmin/v1/couponBatches.
To associate promotions with an existing coupon, issue a PUT request to /ccadmin/v1/claimables/{id}.
To associate promotions with an existing coupon batch, issue a PUT request to /ccadmin/v1/couponBatches/{id}.

Keep the following points in mind when assigning promotions to coupons and coupon batches:

The promotions you want to assign to a coupon or coupon batch must already exist; simply specifying a promotion ID when you create or update a coupon or coupon batch does not automatically create the promotion.
To assign additional promotions to an existing coupon or coupon batch that already has promotions assigned to it, include both the new promotions and the existing promotions in the PUT request. To replace the existing promotions with new promotions, include only the new promotions in the PUT request.
Each coupon or coupon batch has a startDate property that specifies the date and time the coupon or batch is available for use, for example, to be associated with shopper profiles. You can specify a start date when you create a coupon or coupon batch. By default, if a newly-created coupon or batch is associated with only one promotion, its startDate value is the same as the startDate value of the promotion. If a coupon or batch is associated with multiple promotions, the value of its startDate property is null.

You can change the value of the startDate for a coupon or coupon batch with a PUT request to /ccadmin/v1/claimables/{id} or /ccadmin/v1/couponBatches/{id}.

Note:

If you update a promotion, either through the Marketing tab in the administration interface or with the Admin API, the value of the startDate property of any coupons or batches associated with the updated promotion is automatically reset to the startDate value of the updated promotion. If you update a promotion whose child coupons have a different startDate value than the promotion itself, remember to reset the startDate value of each child coupon or batch to avoid unexpected behavior.

The following example creates a new coupon that applies to two promotions:

POST /ccadmin/v1/claimables HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access_token>

{
   "promotions":[{"repositoryId":"promo10001"},{"repositoryId":"promo10003"}],
   "id": "MYSALE",
   "maxUses": "3"
}

If the coupon is created successfully, the response body returned includes the ID for the new coupon:

{
  "repositoryId": "MYSALE"
}

The following example shows a sample request that adds four promotions to an existing coupon batch.

PUT /ccadmin/v1/couponBatches/{SAVE2a462ON50} HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access_token>

{
"promotions": [
   {"repositoryId": "promo10001"},
   {"repositoryId": "promo10002"},
   {"repositoryId": "promo10003"},
   {"repositoryId": "promo10006"}]
}

The following shows the response body returned:

{
  "id": "SAVE2a462ON50",
  "numberOfCoupons": 100,
  "maxUses": 8,
  "numberClaimed": 0,
  "prefix": "Summer Sale",
  "promotions": [
    {"repositoryId": "promo10001"},
    {"repositoryId": "promo10002"},
    {"repositoryId": "promo10003"},
    {"repositoryId": "promo10006"}
  ],
  "uses": 0,
  "repositoryId": "SAVE2a462ON50"
}

Remove a Coupon or Coupon Batch from a Promotion

You remove a coupon or coupon batch from one or more promotions by issuing a DELETE request:

To remove a coupon from one or more promotions, issue a DELETE request to /ccadmin/v1/claimables/{id}.
To remove a coupon batch from one or more promotions, issue a DELETE request to /ccadmin/v1/couponBatches/{id}.

The body of the request must include the IDs for the promotions to remove the coupon from. If the coupon is still associated with one or more promotions after you issue the DELETE request, it is not deleted but is no longer associated with the promotions you specified in the request body. If the coupon is no longer associated with any promotions, it is deleted. If you remove all a promotion’s coupons and do not add another, shoppers will never be able to claim the promotion; it is automatically disabled until you associate it with at least one coupon or coupon batch and then re-enable it in one of the following ways:

With the API: Issue a PUT request to either /ccadmin/v1/promotions/{id} whose body includes "enabled": true.
In the UI: On the Marketing tab, click the name of the promotion and on its details page, select the Enabled checkbox.

The following example removes the coupon FreeSummer from the promotion whose ID is promo10001:

DELETE /ccadmin/v1/claimables/FreeSummer?promotionId=promo10001

The following example removes the coupon batch SAVE4e49eON50 from the promotion whose ID is promo10007:

DELETE /ccadmin/v1/couponBatches/SAVE4e49eON50?promotionId=promo10007