Bulk unique coupons let you generate thousands — or millions — of individually unique codes under a single campaign. Each code can be targeted to a specific customer segment, tracked on its own, and reported on together, making large-scale promotions manageable without the overhead of creating codes one by one.

Available on all Recurly plans

1Definition 2Key benefits 3Key details 4Code syntax 5Creating codes 6Managing codes 7Reporting

Definition

Bulk unique coupons is a Recurly feature that lets you create a single coupon campaign made up of thousands of individually unique codes. Each code can be targeted to specific customer segments, tracked individually, and reported on as part of one unified campaign.

Key benefits

Efficiency at scale Generate up to five million unique codes in a single campaign — no need to create codes one by one.

Precision targeting Share unique codes with specific customer segments to tailor promotions to the right audience.

Insightful reporting Track redemptions and discount effectiveness grouped under one campaign so you can see what's working.

Marketing attribution Associate unique codes with specific marketing channels to identify which sources drive the most redemptions.

Limitations Campaigns exceeding 100,000 codes require an override — contact [email protected] or your account manager. The synchronous API generation endpoint returns a maximum of 200 codes per call. Maximum redemptions and redemptions per account cannot be configured in the UI for bulk unique codes — use the API. To extend the redeem-by date, add more codes through the UI; this is not possible once you've reached the 100,000-code limit, so plan ahead. Custom code templates (for example, without dashes) are only available via API.

Key details

Maximum redemptions

When Bulk unique codes is selected, the maximum redemptions field is hidden in the Recurly UI. By default, maximum redemptions are unlimited — the number of unique codes acts as the natural cap.

To set a specific maximum, use the API. If you set a maximum lower than the total number of unique codes generated, redemptions stop once the limit is reached — even if unused codes remain.

Redemptions per account

When Bulk unique codes is selected, the redemptions per account field is also hidden in the UI. By default, this is set to one — each unique code can only be redeemed once.

To allow a customer to redeem more than one unique code on their account, set redemptions per account to a higher value via the API.

Bulk coupon status

Bulk coupons appear as Expired in the UI when all unique codes have been redeemed — even though their underlying API status remains active. This is by design: it signals that the coupon can't currently be redeemed and prompts you to add more codes to restore it.

The API status stays active even with no redeemable codes, so you can hit the generate unique codes endpoint without needing to restore the coupon first. This matters for merchants who generate codes on demand at the time of a redemption request.
If the campaign contains any expired unique codes, the bulk coupon itself won't automatically expire as long as redeemable codes remain. The coupon only expires if you manually expire it, or if the max redemptions count or redeem-by date is reached.

To restore a specific unique code within a campaign, go to the bulk coupon's overview page and select Restore Code from the hover actions in that code's row.

Bulk unique code syntax

Each bulk unique code is assembled from a required prefix, a generated unique portion, and an optional suffix.

Part	Description
Required prefix	The shared identifier for the campaign. Must be unique across all redeemable coupons on your site. Supports alphanumeric characters, dashes (-), underscores (_), and plus signs (+).
Generated code format	The character type for the unique portion of each code. Options: alphabetic, alphanumeric, or numeric.
Generated code length	The character length of the generated portion. Minimum: four characters (alphabetic or alphanumeric) or six characters (numeric). Maximum: 50 characters. Does not include the prefix or suffix.
Optional suffix	A static string appended to the end of every code. Supports alphanumeric characters, dashes (-), underscores (_), and plus signs (+).
Unique code preview	A sample code reflecting your current template settings. The prefix and suffix are always separated from the generated portion by dashes — customers must enter the full code, including dashes, at redemption.

Custom templates To use a different format or remove dashes from your codes, design your own template via the API.

Creating bulk unique codes

Via the Recurly UI

Open the Coupons dashboard

Navigate to Coupons and click New Coupon.

Select Bulk unique codes

Choose Bulk unique codes as the code type.

Configure your code template

Set the total number of codes (1–100,000, numbers only — no commas), required prefix, generated code format and length, and optional suffix. Review the unique code preview before proceeding.

Configure coupon settings

Complete the remaining coupon fields following the steps in the Coupons and discounts guide.

Click Create coupon

Via the API

Once a bulk coupon template exists, you have two options for generating codes.

Asynchronous — Generate codes via one endpoint, then retrieve them via a second. Best for large batches where you don't need codes in real time.

Synchronous — Generate and receive codes immediately in the response. Limited to 200 codes per call. Best for on-demand generation as part of a real-time redemption flow.

Path: POST /coupons/code-20off/generate_sync

Request:

{
  "number_of_unique_codes": 1
}

Response:

{
  "object": "unique_coupon_code_generation",
  "unique_coupon_codes": [
    {
      "id": "yde3fqeku6ghm",
      "object": "unique_coupon_code",
      "code": "20off-kngm-def",
      "state": "redeemable",
      "bulk_coupon_id": "ywe3dlf0eef5",
      "bulk_coupon_code": "20off",
      "created_at": "2026-04-08T19:57:56Z",
      "updated_at": "2026-04-08T19:57:56Z",
      "redeemed_at": null,
      "expired_at": null
    }
  ]
}

Managing your codes

Expiring codes

You can expire an entire bulk coupon campaign or individual codes at any time from the coupon's overview page.

Invoice display

Each invoice that includes a redeemed unique code displays both the code itself and the name of the coupon campaign it belongs to, making reconciliation straightforward.

Exporting and reporting on redemptions

To generate a report of unique code redemptions for a specific time period:

Go to the Bulk Unique Codes export

Navigate to Coupons — Bulk Unique Codes in the export section.

Select your campaign and time range

Choose your bulk coupon campaign from the dropdown. Set Export on to Modified and configure your desired time range.

Download and filter the CSV

Download the CSV file. Filter out any rows without a value in the applied_at column, then sort by applied_at and remove rows with dates outside your selected time range.

For full export instructions, see the Coupons export documentation and Coupon Redemptions export documentation.

Exports reference

Export	What it contains
Coupons	Identifies bulk unique coupon campaigns. Filter by `"bulk"` under the `coupon_type` column.
Coupon redemptions	Shows which unique codes have been redeemed and by which accounts.
Coupons — Bulk unique codes	A full ledger of all unique codes in a bulk coupon campaign, including redemption details.