Shoppable supports both dollar-off ($) and percent-off (%) promo codes. The specific terms of a promo code, including whether it can be used once or multiple times, are determined by the code itself.
Overview:
Shoppable supports both dollar-off ($) and percent-off (%) promo codes. The specific terms of a promo code, including whether it can be used once or multiple times, are determined by the code itself.
| Code Type | Description | Example |
|---|---|---|
| Dollar-Off ($) | A fixed monetary amount is deducted from the order total. | $10 off your order |
| Percent-Off (%) | A percentage of the subtotal is deducted from the order total. | 20% off your order |
Usage Options
Each promo code can be configured with one of the following usage limits:
-
One-Time Use per Email: The discount can only be used once per unique customer email address.
-
Unlimited Use: The discount can be applied multiple times by any customer, subject to the code’s active date range and other conditions set by the merchant.
General Notes
-
Only one promo code may be applied per order.
-
Promo codes must be entered at checkout before payment is submitted.
-
Expired or invalid codes will not be accepted.
- Promo codes are applied to the subtotal exclusive of any shipping, fees, and taxes.
- Promo Codes are promotions offered by you, the brand or website owner. These are not manufacturer coupons or retailer coupons.
How to Set Up a Promo Code Campaign:
All promo codes must be setup and activated by Shoppable. If you'd like to run a promo code, please reach out to your Shoppable Customer Success Manager (CSM).
Implementing Coupons on Shoppable DTC Lite:
You have full control over the coupon configuration and marketing budget, and your CSM will assist with the setup process. Decide on the below details for your campaign and provide them to your CSM.
What fields can I control during the creation of the coupons?
Coupon Configuration Controls:
couponCode
Name of code for coupon, coupon codes cannot include spaces. This is what your shoppers will enter and you'll use in your marketing of the promotion.
discountType
Type of discount applied during checkout, discountType can have only accept 2 values “fixed” dollar off and “percentage” discount.
discountValue
Amount to be discounted at checkout, for example if discountValue is 10, and discountType is “fixed” amount discount will be $10.00, if discountType is “percentage” the amount discounted will be 10%
usageType
Defines if coupons can be used once or multiple times, usageType can only accept 2 values “SINGLE_USE” for one time used and “MULTI_USE” can be used multiple times within a given date range.
startDate
Sets start date for when the coupon should be active.
expirationDate
Sets expiration date for when the coupon should no longer be active.
active
Sets a coupon to be actively applied within your checkout.
Here is an example of a created Coupon object.
{
"couponCode": "PROMO10",
"discountType": "fixed",
"discountValue": 10,
"usageType": "MULTI_USE",
"startDate": "10/30/2025",
"expirationDate": "11/01/2025",
"active": true
}
How can I check to see what coupons are active?
You can utilize Shoppable’s coupons GET endpoint call to retrieve all active coupons associated to your account:
Staging URL: https://cloud.staging.shoppable.com/coupons
Production URL: https://cloud..shoppable.com/coupons
TYPE: GET
Headers: {
Authorization: “Bearer <YOUR_TOKEN_HERE>”,
x-shoppable-secret: “<YOUR_SECRET_HERE>”
}
Response
{
"success": true,
"message": "Active coupons retrieved successfully",
"coupons": [
{
"id": "6903bb4eab0f67db02196227",
"couponCode": "10WELCOME",
"discountType": "percentage",
"discountValue": 10,
"startDate": "2025-10-30T00:00:00.000Z",
"expirationDate": "2025-11-07T00:00:00.000Z",
"createdAt": "2025-10-30T19:23:58.631Z",
"updatedAt": "2025-10-30T19:23:58.631Z"
},
{
"id": "6903e48dab0f67db02196253",
"couponCode": "PROMO10",
"discountType": "fixed",
"discountValue": 10,
"startDate": "2025-10-30T00:00:00.000Z",
"expirationDate": "2025-11-07T00:00:00.000Z",
"createdAt": "2025-10-30T22:19:57.106Z",
"updatedAt": "2025-10-30T22:19:57.106Z"
}
],
"metadata": {
"total": 2,
"returned": 2
}
}
Implementing Coupons using Shoppable API Suite
In order to use coupons with Shoppable API Suite please contact your Customer Success Manager (CSM). You have full control over the coupon configuration, and your CSM will assist with the setup process.
What fields can I control during the creation of the coupons?
Coupon Configuration Controls
couponCode
Name of code for coupon, coupon codes cannot include spaces.
discountType
Type of discount applied during checkout, discountType can have only accept 2 values “fixed” and “percentage”
discountValue
Amount to be discounted at checkout, for example if discountValue is 10, and discountType is “fixed” amount discount will be $10.00, if discountType is “percentage” the amount discounted will be 10%
usageType
Defines if coupons can be used once or multiple times, usageType can only accept 2 values “SINGLE_USE” for one time used and “MULTI_USE” can be used multiple times within a given date range.
startDate
Sets start date for when the coupon should be active.
expirationDate
Sets expiration date for when the coupon should no longer be active.
active
Sets a coupon to be actively applied within your checkout.
How can I check to see what coupons are active?
You can utilize Shoppable’s coupons GET endpoint call to retrieve all active coupons associated to your account:
Staging URL: https://cloud.staging.shoppable.com/coupons
Production URL: https://cloud..shoppable.com/coupons
TYPE: GET
Headers: {
Authorization: “Bearer <YOUR_TOKEN_HERE>”,
x-shoppable-secret: “<YOUR_SECRET_HERE>”
}
Response
{
"success": true,
"message": "Active coupons retrieved successfully",
"coupons": [
{
"id": "690852ef7e7dca7dda2156a0",
"customerId": "661e8a959e1be79d0a887ba1",
"couponCode": "SAVE10PERCENT",
"discountType": "percentage",
"discountValue": 10,
"usageType": "SINGLE_USE",
"startDate": "2025-11-03T05:00:00.000Z",
"expirationDate": "2025-11-11T05:00:00.000Z",
"createdAt": "2025-11-03T06:59:59.164Z",
"updatedAt": "2025-11-03T06:59:59.164Z"
},
{
"id": "690853167e7dca7dda2156a5",
"customerId": "661e8a959e1be79d0a887ba1",
"couponCode": "SAVE10",
"discountType": "fixed",
"discountValue": 10,
"usageType": "MULTI_USE",
"startDate": "2025-11-03T05:00:00.000Z",
"expirationDate": "2025-11-11T05:00:00.000Z",
"createdAt": "2025-11-03T07:00:38.381Z",
"updatedAt": "2025-11-03T07:00:38.381Z"
}
],
"metadata": {
"total": 2,
"returned": 2
}
}
🧾 Applying Coupons Against the Cart
Once you have retrieved your active coupons using the /coupons GET endpoint, you can apply a specific coupon to your cart subtotal using Shoppable’s /coupons/apply endpoint.
This endpoint allows you to validate a coupon, calculate the applicable discount, and return a new cart summary with the discounted subtotal.
Endpoint Details
Staging URL:
https://cloud.staging.shoppable.com/coupons/apply
Production URL:
https://cloud.shoppable.com/coupons/apply
Type: POST
Headers:
{
"Authorization": "Bearer <YOUR_TOKEN_HERE>",
"x-shoppable-secret": "<YOUR_SECRET_HERE>",
"Content-Type": "application/json"
}
BODY PAYLOAD
{
"email": "ewally24@gmail.com",
"customerId": "661e8a959e1be79d0a887ba1",
"couponCode": "SAVE10",
"usageType": "MULTI_USE",
"subtotal": 22.98
}
RESPONSE
{
"success": true,
"valid": true,
"message": "Coupon applied successfully (multi-use)",
"coupon": {
"couponCode": "SAVE10",
"discountType": "fixed",
"discountValue": 10,
"discountAmount": 10
},
"cartSummary": {
"originalSubtotal": 22.98,
"discountAmount": 10,
"updatedSubtotal": 12.98
}
}
|
Field |
Type |
Required |
Description |
|
|
string |
✅ |
Email address of the shopper applying the coupon. |
|
couponCode |
string |
✅ |
The coupon code to apply. |
|
usageType |
string |
✅ |
Defines how the coupon is used. Accepts "SINGLE_USE" or "MULTI_USE". |
|
subtotal |
number |
✅ |
The current cart subtotal before discounts are applied. |
|
customerId |
number |
✅ |
customerId associated to the customer account |
Error Responses
Coupon Not Found
{
"success": false,
"valid": false,
"message": "Coupon not found for this customer with the specified usageType)",
}
Coupon Already Used (SINGLE_USE)
{
"success": false,
"valid": false,
"message": "This coupon is not eligible or has already been used.",
}
Invalid Request Payload
{
"success": false,
"message": "subtotal is required and must be a number",
}
Invalid Request Payload
{
"success": false,
"valid": false
"message": "Internal error during coupon validation",
}
🧾 Sending Coupons to Checkout
Once you have applied your active coupon using Shoppable’s /coupons/apply endpoint, you can use the response from the /coupons/apply endpoint to retrieve the applied coupon and pass as an array with the other checkout parameters:
Checkout v6 Endpoint call with no coupons:
{
"cartDetails": {
"lineItems": [
{
"id": "62a0b5555ce2f83f392eca85-00037000004622",
"price": 12.97,
"quantity": 1
}
],
"email": "ewally24@gmail.com",
"sendConfirmationEmail": false,
"substitutionOptIn": false,
"marketingOptIn": true
},
"shippingDetails": {
"firstName": "Errol",
"lastName": "Wallace",
"address1": "93 Greeley Avenue",
"address2": "",
"city": "Staten Island",
"state": "NY",
"country": "US",
"zipCode": "10306",
"phoneNumber": "3473227263"
},
"billingDetails": {
"firstName": "Errol",
"lastName": "Wallace",
"address1": "93 Greeley Avenue",
"address2": "",
"city": "Staten Island",
"state": "NY",
"country": "US",
"zipCode": "10306"
},
"paymentToken": "pi_3SPUZ5BgoxyAByN41QLVAxDN",
"coupons": []
}
Checkout v6 Endpoint with applied coupon in Coupons array of BODY PAYLOAD
{
"cartDetails": {
"lineItems": [
{
"id": "62a0b5555ce2f83f392eca85-00037000004622",
"price": 12.97,
"quantity": 1
}
],
"email": "ewally24@gmail.com",
"sendConfirmationEmail": false,
"substitutionOptIn": false,
"marketingOptIn": true
},
"shippingDetails": {
"firstName": "Earl",
"lastName": "Williams",
"address1": "93 Green Avenue",
"address2": "",
"city": "Staten Island",
"state": "NY",
"country": "US",
"zipCode": "10301",
"phoneNumber": "3473221111"
},
"billingDetails": {
"firstName": "Earl",
"lastName": "Williams",
"address1": "93 Green Avenue",
"address2": "",
"city": "Staten Island",
"state": "NY",
"country": "US",
"zipCode": "10301"
},
"paymentToken": "pi_3SPUZ5BgoxyAByN41QLVAxDN",
"coupons": [
{
"couponId": "690852ef7e7dca7dda2156a0",
"customerId": "661e8a959e1be79d0a887ba1",
"code": "SAVE10PERCENT",
"discountType": "percentage",
"discountValue": 10,
"discountAmount": 10,
"usageType": "SINGLE_USE",
"startDate": "2025-11-03T05:00:00.000Z",
"expirationDate": "2025-11-11T05:00:00.000Z"
}
]
}
Next Step: Finalizing Checkout with Coupons
After successfully applying a coupon and confirming the new subtotal, include the coupons array in your /v6/checkout API request payload.
Shoppable’s checkout service will handle redemption tracking and update coupon status once the order completes.