Manage coupons with the Coupons API
Learn how to automate coupon code uploads.
Klaviyo's Coupons API allows you to create and manage coupons and coupon codes. After you follow this guide, you should be able to create your first coupon code, upload coupon codes, and check for coupon code availability via API.
The Coupons API does not support Shopify coupon creation, or access to Shopify coupons created via Klaviyo’s UI. Access to other uploaded coupons via Klaviyo’s UI is supported.
In the Klaviyo application, you can view coupons under Content > Coupons. On this page, you can navigate to the API Coupons tab to view coupons added via API.
Data model
A coupon can be linked to a number of unique coupon codes. A coupon code gets its value from a single coupon, which can also be applied to other coupon codes. For example, a coupon containing a description for 50% off can be assigned to a limitless number of coupon codes. Each code uses the relationships object which associates it to a defined coupon and profile. For more information on relationships, refer to our JSON:API relationships guide.
A coupon has the following:
-
external_idThe unique coupon ID in an external point-of-sale (POS) system where you generate the coupon.
-
descriptionAn coupon description (optional).
A coupon code has the following:
-
unique_codeThe code that can be used by a shopper to apply a discount to their purchase.
-
expires_atA code expiration datetime, when it may no longer be used to claim the discount (optional).
-
statusThe current coupon code status, one of
ASSIGNED_TO_PROFILE,DELETING,PROCESSING,UNASSIGNED,VERSION_NOT_ACTIVE -
relationships-
couponThe coupon with which the code is associated.
-
profileThe Klaviyo profile the code has been assigned to, set when a profile is sent the coupon code in a campaign or flow message.
-
Note that a coupon may have many coupon codes attached to it, but a coupon code may be associated with only one coupon.
Common use cases
Create a coupon and upload codes
Follow the examples below to get started creating coupons and uploading coupon codes for your email and SMS messages.
Example API call to create a coupon
Here is an example on how to create a coupon using the Create Coupon endpoint:
curl --request POST \
--url https://a.klaviyo.com/api/coupons/ \
--header 'Authorization: Klaviyo-API-Key your-private-api-key' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'revision: 2023-08-15.pre' \
--data '
{
"data": {
"type": "coupon",
"attributes": {
"external_id": "10OFF",
"description": "10% off for purchases over $50"
}
}
}
'
Example API call to upload coupon codes
After a coupon is created, we can make a call to the Spawn Coupon Code Bulk Create Job endpoint to upload coupon codes as shown in the example below:
curl --request POST \
--url https://a.klaviyo.com/api/coupon-code-bulk-create-jobs/ \
--header 'Authorization: Klaviyo-API-Key your-private-api-key' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'revision: 2023-08-15.pre' \
--data '
{
"data": {
"type": "coupon-code-bulk-create-job",
"attributes": {
"coupon-codes": {
"data": [
{
"type": "coupon-code",
"attributes": {
"unique_code": "ASD325FHK324UJDOI2M3JNES99",
"expires_at": "2024-04-20T00:00:00Z"
},
"relationships": {
"coupon": {
"data": {
"type": "coupon",
"id": "10OFF"
}
}
}
},
{
"type": "coupon-code",
"attributes": {
"unique_code": "AFD35FHK324UJDOI2M3JNES10",
"expires_at": "2024-04-20T00:00:00Z"
},
"relationships": {
"coupon": {
"data": {
"type": "coupon",
"id": "10OFF"
}
}
}
},
...
]
}
}
}
'
A maximum of 500 coupons can be active in an account at once. There is currently no limit on the amount of coupon codes an account can create.
Check for coupon code availability
You can filter coupon codes by coupon ID, status, and expiration date to monitor coupon usage and determine whether to create additional coupons.
We do not track whether a coupon code has been redeemed within Klaviyo. This data should reside in your external system.
Example request and response
In the following example, we make a request to filter unassigned coupon codes with the id 10OFF that expire at 12:00 AM on April 20, 2024 or later:
curl --request GET \
--url 'https://a.klaviyo.com/api/coupon-codes?filter=and(equals(coupon.id,"10OFF"),equals(status,"UNASSIGNED"),greater-or-equal(expires_at,2024-04-20T00:00:00Z))' \
--header 'Authorization: Klaviyo-API-Key your-private-api-key' \
--header 'accept: application/json' \
--header 'revision: 2023-08-15.pre'
{
"data": [
{
"type": "coupon-code",
"id": "10OFF-ASD325FHK324UJDOI2M3JNES99",
"attributes": {
"unique_code": "ASD325FHK324UJDOI2M3JNES99",
"expiration": "2024-07-17T18:26:59+00:00",
"status": "UNASSIGNED"
},
"relationships": {
"coupon": {
"data": {
"type": "coupon",
"id": "10OFF"
},
"links": {
"self": "https://a.klaviyo.com/api/coupon-codes/10OFF-ASD325FHK324UJDOI2M3JNES99/relationships/coupon/",
"related": "https://a.klaviyo.com/api/coupon-codes/10OFF-ASD325FHK324UJDOI2M3JNES99/coupon/"
}
},
"profile": {
"data": {
"type": "profile",
"id": "ABC123050345034"
},
"links": {
"self": "https://a.klaviyo.com/api/coupon-codes/10OFF-ASD325FHK324UJDOI2M3JNES99/relationships/profile/",
"related": "https://a.klaviyo.com/api/coupon-codes/10OFF-ASD325FHK324UJDOI2M3JNES99/profile/"
}
}
},
"links": {
"self": "https://a.klaviyo.com/api/coupon-codes/10OFF-ASD325FHK324UJDOI2M3JNES99/"
}
},
...
]
}
Use coupon codes in messages
Refer to our guide on how to use unique coupon codes in SMS and MMS messages to learn how. Use the external_id of your coupon as the “CouponName."
Common error cases
Coupons created via API look different from coupons manually uploaded via Klaviyo’s UI. A manually uploaded coupon may have an expiration date, while an API coupon is related to a coupon code which may have an expiration date. If you want to modify an expiration date of a manually uploaded coupon via API, you must do this via UI. You may create coupon codes for a manually uploaded coupon, but their expiration dates must match the expiration date set in the UI.
Because our Coupons API allows you to create coupon codes for existing, manually uploaded coupons, we have special error handling to prevent expiration-related conflicts.
A 409 conflict error is returned if a coupon that was created via UI:
- has a set expiration date, but its related coupon codes do not have a set expiration date.
- has a set expiration date, but its related coupon codes' expiration dates do not match.
- does not have a set expiration date, but its related coupon codes have a set expiration date.
To avoid errors, update expiration dates for parent coupons in the UI and/or update expires_at fields for related coupon codes via API as needed.
Additional resources
Updated about 1 month ago