(New) Use Klaviyo's Coupons API

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.

🚧

Note that our 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_id

  The unique coupon ID in an external point-of-sale (POS) system where you generate the coupon.

• description

  An coupon description (optional).

A coupon code has the following:

• unique_code

  The code that can be used by a shopper to apply a discount to their purchase.

• expires_at

  A code expiration datetime, when it may no longer be used to claim the discount (optional).

• status

  The current coupon code status, one of ASSIGNED_TO_PROFILE,DELETING,PROCESSING,UNASSIGNED,VERSION_NOT_ACTIVE

• relationships

  • coupon

    The coupon with which the code is associated.

  • profile

    The 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 than coupons manually uploaded via Klaviyo’s UI. A manually uploaded coupon may have an expiration date, while an API coupon is a related resource of a coupon code which may have an expiration date, per the data model discussed above. 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:

• an uploaded coupon has a set expiration date, but its related coupon codes do not have a set expiration date.
• an uploaded coupon 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

• Getting started with coupon codes in Klaviyo
• How to use unique coupon codes in SMS and MMS messages
• JSON:API relationships
• JSON:API filtering