Create Max Uses Per Shopper Promotion Codes
You can set number of uses allowed per shopper (including account user) for the promotion code. The limitation can also include guest shoppers. Guest shopper usages are being tracked by the cart with email. See Cart with email API
POST Create Max Uses Per Shopper Promotion Codes
https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/codes
Parameters
Path parameters
| Name | Required | Type | Description |
|---|---|---|---|
promotionID | Required | string | The unique identifier of the rule promotion. |
Headers
| Name | Required | Type | Description |
|---|---|---|---|
Authorization | Required | string | The Bearer token required to get access to the API. |
Body
See Promotion Codes object for all other fields.
| Name | Required | Type | Description |
|---|---|---|---|
max_uses_per_shopper | Optional | object | Object for setting max uses per shopper. Only include this object, when you want to set limit per shopper. |
max_uses_per_shopper.max_uses | Optional | integer | Sets max number of times the code can be used by a shopper. NOTE: This can not be set with per_application consume unit. |
max_uses_per_shopper.includes_guests | Optional | boolean | The flag to include guest shoppers for the discount with max use restriction. If this field is provided, the max_uses value is required. If not provided, then the default will be false.
|
Set max uses limit for all shoppers (registered, guests and accounts)
The following example configures the promotion code to allow a maximum of one use per shopper, including guest shoppers with an email associated with their cart.
Request Example
curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/codes \
-H "Authorization: Bearer XXXX" \
-H "Content-Type: application/json" \
-d $ {
"data":{
"type": "promotion_codes",
"codes": [
{
"code": "one_per_shopper",
"consume_unit": "per_checkout",
"max_uses_per_shopper": {
"includes_guests": true,
"max_uses":1
}
}
]
}
}
Response Example
201 Created
{
"data": [
{
"id": "8a1c73bc-7c15-41c3-a3ed-a0aa398c3984",
"code": "one_per_shopper",
"max_uses_per_shopper": {
"max_uses": 1,
"includes_guests": true
},
"consume_unit": "per_checkout"
}
]
}
Set max uses limit for the promotion code and max use per shoppers (registered, guests and accounts)
For example, the following promotion code configuration allows a total of 10 uses, with a maximum of 1 use per shopper. This means up to 10 different shoppers can use the code.
Request Example
curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/codes \
-H "Authorization: Bearer XXXX" \
-H "Content-Type: application/json" \
-d $ {
"data":{
"type": "promotion_codes",
"codes": [
{
"code": "one_time_use",
"consume_unit": "per_checkout",
"uses": 10,
"max_uses_per_shopper": {
"includes_guests": true,
"max_uses": 1
}
}
]
}
}
Response Example
201 Created
{
"data": [
{
"id": "0f977e65-30bb-485a-90de-0ad5f5455b7f",
"code": "one_time_use",
"uses": 10,
"max_uses": 10,
"max_uses_per_shopper": {
"max_uses": 1,
"includes_guests": true
},
"consume_unit": "per_checkout"
}
]
}
Set max uses limit for specific shopper
To limit the maximum usage for a specific shopper, there are two approaches. In the examples below, the identified shopper can only use the promotion code once across all checkouts when the cart is checked out with the matching customer ID.
Use uses and user with customerID value.
- Account user ID is currently not supported.
Request Example
curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/codes \
-H "Authorization: Bearer XXXX" \
-H "Content-Type: application/json" \
-d $ {
"data":{
"type": "promotion_codes",
"codes": [
{
"code": "one_per_shopper",
"consume_unit": "per_checkout",
"uses": 1,
"user": "{{customerID}}",
}
]
}
}
Response Example
201 Created
{
"data": [
{
"id": "8a1c73bc-7c15-41c3-a3ed-a0aa398c3984",
"code": "one_per_shopper",
"uses": 1,
"max_uses": 1,
"user": "5abb8d4e-57c0-459b-91d5-c4e6f77e9c5e",
"consume_unit": "per_checkout"
}
]
}
Use user with customerID value and max_uses_per_shopper.max_uses
Request Example
curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/codes \
-H "Authorization: Bearer XXXX" \
-H "Content-Type: application/json" \
-d $ {
"data":{
"type": "promotion_codes",
"codes": [
{
"code": "one_per_shopper",
"consume_unit": "per_checkout",
"user": "{{customerID}}",
"max_uses_per_shopper": {
"includes_guests": false,
"max_uses":1
}
}
]
}
}
Response Example
201 Created
{
"data": [
{
"id": "8a1c73bc-7c15-41c3-a3ed-a0aa398c3984",
"code": "one_per_shopper",
"user": "5abb8d4e-57c0-459b-91d5-c4e6f77e9c5e",
"max_uses_per_shopper": {
"max_uses": 1,
"includes_guests": false
},
"consume_unit": "per_checkout"
}
]
}
When the shopper has consumed all the usages, and attempts to use the same promotion code again, the following cart response message will return.
{
"messages": [
{
"source": {
"type": "promotion",
"id": "38861a5c-81bb-43bc-8934-e30cde108579",
"code": "one_per_shopper"
},
"title": "Fully Consumed",
"description": "You've already fully consumed this promotion code"
}
]
}
Errors
When the request body includes max_uses_per_shopper.includes_guests, the max_uses field must also be provided with a value. Otherwise, an error will be returned.
{
"errors": [
{
"status": 400,
"source": "data.codes.0.max_uses_per_shopper",
"title": "missing_dependency",
"detail": "Has a dependency on max_uses"
}
]
}
When setting max_uses_per_shopper.max_uses with consume unit per_application, the following error will return.
{
"errors": [
{
"status": 422,
"source": "",
"title": "Unsupported consume unit",
"detail": "Consume unit 'per_application' is not supported when using 'max_uses_per_shopper' features."
}
]
}