- Content
Coupons and Discounts
Overview
Everyone loves a good coupon! This guide will walk you through the programmatic process of creating and processing coupons using the Recurly API. You can generate single coupon codes for mass distribution or create many unique coupons for individual delivery and tracking.
Before continuing, it’s recommended to review the Quickstart Guide and the Subscription Management Guide.
Estimated completion time
30 minutes
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.
Ruby
Node.js
Python
Java
Dotnet
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.
Ruby
Node.js
Python
Java
Dotnet
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 thecode-
prefix to identify the coupon. For example, thecoupon_id
for a coupon with the codediscount123
would becode-discount123
.
Ruby
Node.js
Python
Java
Dotnet
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.