(New) Use Klaviyo's Coupons API
Learn how to automate coupon code uploads.
Klaviyo's Coupons API allows you to create and retrieve API-generated 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.
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 optional coupon description.
A coupon code has the following:
-
unique_codeThe code that can be used by a shopper to apply a discount to their purchase.
-
expires_atThe code expiration datetime, when it may no longer be used to claim the discount.
-
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."
Additional resources
Updated 3 months ago