Overview

Coupons and discounts are powerful tools to attract new subscribers, nurture loyalty, and boost customer satisfaction. In this guide, you’ll learn how to generate single coupon codes for mass distribution or create unique codes for individual delivery, apply coupons during checkout or directly to customer accounts, and verify coupon usage.

Prerequisites & Limitations

Familiarity with Recurly’s Quickstart Guide and Subscription Management Guide
A valid Recurly account and API key
Knowledge of RESTful APIs and JSON data structures

Definition

Coupons and Discounts refer to the promotions you create and manage in Recurly to provide flexible incentives for your customers—ranging from percentage-based deals to fixed-amount offers. These promotions can be seamlessly integrated into your checkout process or applied directly to customer accounts for ongoing or future billing events.

Step 1: Coupon creation

Create a single coupon for mass distribution

Use the Create Coupon endpoint to create a single coupon code for mass distribution to many customers. This endpoint allows you to specify various properties, such as:

Name: For internal tracking.
Maximum Redemptions: Limits the number of redemptions overall or per customer account.
External Code: Used by customers for redemption.
Discount Type: Choose between a fixed amount, percentage, etc.

coupon_create = {
  name: "Promotional Coupon",
  code: coupon_code,
  discount_type: 'fixed',
  currencies: [
    {
      currency: 'USD',
      discount: 10
    }
  ]
}
coupon = @client.create_coupon(
  body: coupon_create
)
puts "Created Coupon #{coupon}"

let createCouponReq = {
  name: 'Promotional Coupon',
  code: coupon_code,
  discount_type: 'fixed',
  currencies: [
    {
      currency: 'USD',
      discount: 10
    }
  ]
}
let coupon = await client.createCoupon(createCouponReq)

CouponCreate couponCreate = new CouponCreate();

couponCreate.setName("Promotional Coupon");
couponCreate.setCode(couponCode);

List<CouponPricing> currencies = new ArrayList<CouponPricing>();
CouponPricing couponPrice = new CouponPricing();
couponPrice.setCurrency("USD");
couponPrice.setDiscount(10.0f);
currencies.add(couponPrice);

couponCreate.setCurrencies(currencies);

Coupon coupon = client.createCoupon(couponCreate);
System.out.println("Created coupon " + coupon.getCode());

coupon_create = {
    "name": "Promotional Coupon",
    "code": coupon_code,
    "discount_type": "fixed",
    "currencies": [{"currency": "USD", "discount": 10}],
}
coupon = client.create_coupon(coupon_create)
print("Created Coupon %s" % coupon)

var createCouponReq = new CouponCreate()
{
    Name = "Promotional Coupon",
    Code = couponCode,
    DiscountType = "fixed",
    Currencies = new List<CouponPricing>()
    {
        new CouponPricing() { Currency = "USD", Discount = 10 }
    }
};
Coupon coupon = client.CreateCoupon(createCouponReq);

However, these are only a few of the coupon configurability options available. For more information, refer to the reference documentation.

Step 2: Coupon redemption

Customers can apply coupons to an initial purchase or to their account. When applied to an account, the coupon discount will be used in a future billing event.

Redeem with purchase

To redeem one or more coupons as part of a new purchase, use the Create Purchase endpoint and pass in a list of coupon codes to be applied.

purchase = {
  currency: "USD",
  account: {
    code: account_code,
    first_name: "Benjamin",
    last_name: "Du Monde",
    billing_info: {
      token_id: rjs_token_id
    },
  },
  subscriptions: [
    { plan_code: plan_code }
  ],
  coupon_codes: [
    "code_A",
    "code_B"
  ]
}
invoice_collection = @client.create_purchase(
  body: purchase
)

let purchaseReq = {
  currency: 'USD',
  account: {
    code: accountCode,
    firstName: 'Benjamin',
    lastName: 'Du Monde',
    billingInfo: {
      tokenId: rjsTokenId
    }
  },
  subscriptions: [
    { planCode: planCode },
  ],
  coupon_codes: [
    "code_A",
    "code_B"
  ]  
}
let invoiceCollection = await client.createPurchase(purchaseReq)

purchase = {
    "currency": "USD",
    "account": {
        "code": account_code,
        "first_name": "Benjamin",
        "last_name": "Du Monde",
        "billing_info": {"token_id": rjs_token_id},
    },
    "subscriptions": [{"plan_code": plan_code}],
    "coupon_codes": ["code_A", "code_B"]
}
invoice_collection = client.create_purchase(purchase)

PurchaseCreate purchase = new PurchaseCreate();
purchase.setCurrency("USD");

AccountPurchase account = new AccountPurchase();
account.setCode(accountCode);
account.setFirstName("Benjamin");
account.setLastName("Eckel");
purchase.setAccount(account);

BillingInfoCreate billing = new BillingInfoCreate();
billing.setTokenId(rjsTokenId);
account.setBillingInfo(billing);

List<SubscriptionPurchase> subscriptions = new ArrayList<SubscriptionPurchase>();
SubscriptionPurchase sub = new SubscriptionPurchase();
sub.setPlanCode(planCode);
subscriptions.add(sub);
purchase.setSubscriptions(subscriptions);

List<String> couponCodes = Arrays.asList("code_A", "code_B");
purchase.setCouponCodes(couponCodes)

InvoiceCollection collection = client.createPurchase(purchase);
System.out.println("Created ChargeInvoice with Id: " + collection.getChargeInvoice().getId())

var purchaseReq = new PurchaseCreate()
{
    Currency = "USD",
    Account = new AccountPurchase()
    {
        Code = accountCode,
        FirstName = "Benjamin",
        LastName = "Du Monde",
        BillingInfo = new BillingInfoCreate()
        {
            TokenId = rjsTokenId
        }
    },
    Subscriptions = new List<SubscriptionPurchase>()
    {
        new SubscriptionPurchase() { PlanCode = planCode }
    },
    CouponCodes = new List<string>{"code_A", "code_B"}
};
InvoiceCollection collection = client.CreatePurchase(purchaseReq);

Apply a coupon to an account

To apply a coupon to a customer account, use the Create Coupon Redemption endpoint. Provide the ID of the coupon to be redeemed along with the associated currency.

Note: that the coupon_id parameter can use either the primary key of the coupon or the code- prefix to identify the coupon. For example, the coupon_id for a coupon with the code discount123 would be code-discount123.

redemption = @client.create_coupon_redemption(
  account_id: account_id,
  body: {
    currency: 'USD',
    coupon_id: coupon_id
  }
)
puts "Created CouponRedemption #{redemption}"

let couponRedemptionReq = {
    currency: 'USD',
    coupon_id: coupon_id
}
let couponRedemption = await client.createCouponRedemption(accountID, couponRedemptionReq)

redemption_create = {"currency": "USD", "coupon_id": coupon_id}
redemption = client.create_coupon_redemption(account_id, redemption_create)
print("Created Redemption %s" % redemption)

CouponRedemptionCreate coupRedCreate = new CouponRedemptionCreate();
coupRedCreate.setCouponId(couponId);
CouponRedemption redemption = client.createCouponRedemption(accountId, coupRedCreate);
System.out.println("Created coupon redemption " + redemption.getId());

var couponRedemption = new CouponRedemptionCreate()
{
    Currency = "USD",
    CouponId = coupondId
};
CouponRedemption coupon = client.CreateCouponRedemption(accountId, couponRedemption);

Step 3: Verify and Finish

You can use the API at any time to:

Lookup a specific coupon by ID.
Obtain a list of all coupons created for your Recurly site/subdomain.
Show coupon redemptions for a specific account.
Explore many more options.