Assign and manage coupons
The Commerce UI allows merchandisers to assign only a single coupon or coupon batch to each promotion. However, you can use the Oracle Commerce Admin API to associate multiple promotions with a coupon or coupon batch.
This section describes how to use the Oracle 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 Oracle 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 thePUT
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, itsstartDate
value is the same as thestartDate
value of the promotion. If a coupon or batch is associated with multiple promotions, the value of itsstartDate
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