HomeGuidesAPI Reference
ChangelogHelp CenterCommunityContact Us
Guides

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.

🚧

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.

Screen capture a API coupon created via API located in the API Coupons tab under Content > Coupons

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 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