Create coupons in bulk via API

If you're a developer, you can create coupon codes in bulk via our API. We've added a special mutation that will create several coupon codes based on an existing coupon, and they'll be grouped together in your Dashboard for easy management.

In this help doc:

• Using the GraphQL API Explorer.
• Create a base coupon.
• Find the base coupon's ID.
• Example mutation to create coupon codes in bulk.
• Bulk coupon code requirements and troubleshooting.
• Managing your bulk coupon codes in the Dashboard.
• Need more help?

Using the GraphQL API Explorer

You can make requests to our API in all the regular ways you're used to, but the easiest method is through our GraphQL API Explorer, which can be accessed straight from your Dashboard by going to Settings → Integrate → Custom Apps.

Queries and mutations that you execute in the API Explorer will work just the same as requests that come from elsewhere, so you can generate your coupons in bulk just by using the API Explorer.

Create a base coupon

Next, you'll want to create a base coupon.

All your new coupons will inherit the same settings as this base coupon, and they'll be grouped under it in your Dashboard.

Find the base coupon's ID

From the Edit coupon page, take note of the coupon's ID. You'll find it under the label Coupon ID for generating bulk coupon codes.

Example mutation to create coupon codes in bulk

Now you're ready to go to the API Explorer and run your mutation. Keep your coupon's ID handy, we're about to use it.

This is the format we need to follow for this mutation:

mutation {
  createCoupons(discountId: YOURCOUPONID, coupons: [{ code: "NEWCOUPONCODE1"}, { code: "NEWCOUPONCODE2"}, { code: "NEWCOUPONCODE3" }]) {
    coupons {
      code
    }
    errors {
      key
      messages {
        attribute
        message
      }
    }
  }
}

You should replace YOURCOUPONID with the coupon ID you copied before, and also replace NEWCOUPONCODEX with the coupon codes you'd like to create.

Here's an example mutation that creates 3 codes from a base coupon with the ID 24:

mutation {
  createCoupons(discountId: 24, coupons: [{ code: "membersonly1"}, { code: "membersonly2"}, { code: "membersonly3" }]) {
    coupons {
      code
    }
    errors {
      key
      messages {
        attribute
        message
      }
    }
  }
}

Bulk coupon code requirements and troubleshooting

If your coupon codes were created successfully, the result will show the successfully created codes inside the coupons array, and errors will show an empty array.

{
  "data": {
    "createCoupons": {
      "coupons": [
        {
          "code": "membersonly1"
        },
        {
          "code": "membersonly2"
        },
        {
          "code": "membersonly3"
        }
      ],
      "errors": []
    }
  }
}

Now, here's an example result in which some coupons failed to be created, while others succeeded:

{
  "data": {
    "createCoupons": {
      "coupons": [
        {
          "code": "membersonly4"
        },
        {
          "code": "membersonly5"
        },
        {
          "code": "membersonly6"
        }
      ],
      "errors": [
        {
          "key": "membersonly_7",
          "messages": [
            {
              "attribute": "code",
              "message": "Code is invalid."
            }
          ]
        },
        {
          "key": "membersonly1",
          "messages": [
            {
              "attribute": "code",
              "message": "Code is taken."
            }
          ]
        }
      ]
    }
  }
}

To troubleshoot a result like this, we should look at the error messages and then review our request again to make sure that the following requirements are met by all of our requested coupon codes:

• Maximum 255 characters
• Contains no symbols or spaces
• The code doesn't already exist

Note that coupon codes are case-insensitive, so mycouponZ will fail to be created if mycouponz already exists, and vice versa.

Here are some valid and invalid examples for a base coupon with the code membersonly:

• ✅ membersonly1
• ✅ membersonly987
• ✅ membersonlyA
• ✅ membersonlyxyz
• ✅ summersale (The new code doesn't need to resemble the base coupon code)
• ❌ membersonly_1 (Symbols aren't allowed)
• ❌ membersonly (Already exists - this is the same code as the base coupon!)
• ❌ MembersOnly (Already exists - uppercase/lowercase doesn't make a difference)

If some of your coupon codes were created successfully and others failed, there's no need to resubmit the ones that were successful, those have already been created. Fix the issues with the failed ones and resubmit only those.

Managing your bulk coupon codes in the Dashboard

After creating some bulk coupon codes, you'll see how many coupon codes are based off of it when you edit the base coupon.

Related help doc:

• Create a coupon.