The Coupon Cookbook

Overview

Everyone loves a good coupon, and this guide will walk you through the programmatic process of creating coupons and processing them when your customers are ready to redeem them. With Recurly API, you can generate single coupon codes that can be mass distributed to many customers or you can generate many unique coupons that can allow for individual delivery and tracking.

Before continuing with this guide, it’s recommended that you’ve taken a look at the Quickstart Guide and the Subscription Management Guide.

Estimated Completion time

30 minutes

Step 1: Coupon Creation

Create a single coupon for mass distribution

The Create Coupon endpoint is used to create a single coupon code that can be distributed en masse to many customers. The endpoint allows you to specify a name for the coupon (for internal tracking), as well as other properties such as the maximum number of redemptions (overall or by customer account), an external code (used by your customers for redemption), and a discount type (e.g. 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 at your disposal. Take a look at the reference documentation for more information.

Step 2: Coupon Redemption

You can allow your customers to apply coupons to an initial purchase or to their account. In latter case, the coupon discount will be applied to a future billing event associated with the account.

Redeem with Purchase

To redeem one or many coupons as part of a new purchase, call 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 to an Account

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

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, and much more.