Recurly

Coupons API

Coupons allow to offer your customers a discount on their subscription. Coupons can be configured in a variety of discounts, as described in our coupons overview. This page describes how to use the API and our client libraries to redeem a coupon during a subscription, lookup an account's existing coupon, redeem a coupon before or after a subscription, and completely remove a redeemed coupon from an account.

List active coupons

Returns a list of all the coupons.

GET https://:subdomain.recurly.com/v2/coupons

Query Parameters

Parameter Default Description
state all The state of coupons to return: "redeemable", "expired", or "maxed_out".
cursor Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.
per_page 50 Number of records to return per page, up to a maximum of 200.

Example

Status: 200 OK
Content-Type: application/xml; charset=utf-8
X-Records: 64
Link: <https://your-subdomain.recurly.com/v2/coupons?cursor=1304958672>; rel="next"
ETag: "c370705eec5b09c0dd6f60d226da68f6"
<?xml version="1.0" encoding="UTF-8"?>
<coupons type="array">
  <coupon href="https://your-subdomain.recurly.com/v2/coupons/special">
    <redemptions href="https://your-subdomain.recurly.com/v2/coupons/special/redemptions"/>
    <coupon_code>special</coupon_code>
    <name>Special 10% off</name>
    <state>redeemable</state>
    <discount_type>percent</discount_type>
    <discount_percent type="integer">10</discount_percent>
    <redeem_by_date type="datetime">2014-01-01T07:00:00Z</redeem_by_date>
    <single_use type="boolean">true</single_use>
    <applies_for_months nil="nil"></applies_for_months>
    <max_redemptions type="integer">10</max_redemptions>
    <applies_to_all_plans type="boolean">false</applies_to_all_plans>
    <created_at type="datetime">2011-04-10T07:00:00Z</created_at>
    <plan_codes type="array">
      <plan_code>gold</plan_code>
      <plan_code>platinum</plan_code>
    </plan_codes>
    <a name="redeem" href="https://your-subdomain.recurly.com/v2/coupons/special/redeem" method="post"/>
  </coupon>
  <!-- Continued... -->
</coupons>

$coupons = Recurly_CouponList::get();
foreach ($coupons as $coupon) {
  print "Coupon: $coupon\n";
}
The client library will automatically fetch the next page of the results. There may be a slight delay when fetching the next page. 
Recurly::Coupon.find_each do |coupon|
  puts "Coupon: #{coupon.inspect}"
end
The client library will automatically fetch the next page of the results. There may be a slight delay when fetching the next page. 
#client version <= 2.1.5
coupons = Coupon.all()
while coupons:
    for coupon in coupons:
        print 'Coupon: %s' % coupon
    try:
        coupons = coupons.next_page()
    except PageError:
        coupons = ()

#client version 2.1.6+
for coupon in Coupon.all():
    print 'Coupon: %s' % coupon

Lookup a coupon

Returns information about an active coupon.

GET https://:subdomain.recurly.com/v2/coupons/:coupon_code

Example

Status: 200 OK
Content-Type: application/xml; charset=utf-8
ETag: "b2b8cb271080534189ba41d7058177cc"
<?xml version="1.0" encoding="UTF-8"?>
<coupon href="https://your-subdomain.recurly.com/v2/coupons/special">
  <redemptions href="https://your-subdomain.recurly.com/v2/coupons/special/redemptions"/>
  <coupon_code>special</coupon_code>
  <name>Special 10% off</name>
  <state>redeemable</state>
  <hosted_description>10% off coupon</hosted_description>
  <discount_type>percent</discount_type>
  <discount_percent type="integer">10</discount_percent>
  <redeem_by_date type="datetime">2014-01-01T07:00:00Z</redeem_by_date>
  <single_use type="boolean">true</single_use>
  <applies_for_months nil="nil"></applies_for_months>
  <max_redemptions type="integer">10</max_redemptions>
  <applies_to_all_plans type="boolean">false</applies_to_all_plans>
  <created_at type="datetime">2011-04-10T07:00:00Z</created_at>
  <plan_codes type="array">
    <plan_code>gold</plan_code>
    <plan_code>platinum</plan_code>
  </plan_codes>
  <a name="redeem" href="https://your-subdomain.recurly.com/v2/coupons/special/redeem" method="post"/>
</coupon>

try {
  $coupon = Recurly_Coupon::get('special');
  print "Coupon: $coupon\n";
} catch (Recurly_NotFoundError $e) {
  print "Coupon does not exist";
}

coupon = Recurly::Coupon.find('special')

coupon = Coupon.get('special')

Create coupon

Creates a new coupon. Please note: coupons cannot be updated after being created.

POST https://:subdomain.recurly.com/v2/coupons

Coupon Attributes

Parameter Description
coupon_code Unique code to identify and redeem the coupon. This code may only contain the following characters: [a-z A-Z 0-9 @ - _ .]. Max of 50 characters. Required
name Coupon name Required
hosted_description Description of the coupon on the hosted payment pages
invoice_description Description of the coupon on the invoice
redeem_by_date Last date to redeem the coupon, defaults to no date
single_use If true, the coupon applies to the first invoice only
applies_for_months Number of months after redemption that the coupon is valid, defaults to no date
max_redemptions Maximum number of accounts that may use the coupon before it can no longer be redeemed
applies_to_all_plans The coupon is valid for all plans if true, defaults to true
discount_type "percent" or "dollars" Required
discount_percent Discount percentage if discount_type is "percent"
discount_in_cents Mapping of discount amounts by currency if discount_type is "dollars". Max 10000000.
plan_codes Array of plan_codes the coupon applies to, if applies_to_all_plans is false

Discount in dollars

When specifying a discount amount as a flat amount, the currency must be specified with the amount in an array. For example:

<discount_type>dollars</discount_type>
<discount_in_cents>
  <USD>500</USD>
  <EUR>400</EUR>
  <GBP>300</GBP>
</discount_in_cents>

Discount in percentage

Percentage discounts only need to specify the discount percentage. For example:

<discount_type>percent</discount_type>
<discount_percent>10</discount_percent>

Limiting to specific plans

If a coupon applies to all plans, it will also apply to any plans created in the future. To limit a coupon to specific plans, you may specify an array of plan codes. For example:

<applies_to_all_plans>false</applies_to_all_plans>
<plan_codes>
  <plan_code>silver</plan_code>
  <plan_code>gold</plan_code>
</plan_codes>

Example

Request limited to specific plans

Accept: application/xml
Content-Type: application/xml; charset=utf-8
<coupon>
  <coupon_code>special</coupon_code>
  <name>Special 10% off</name>
  <discount_type>percent</discount_type>
  <discount_percent>10</discount_percent>
  <redeem_by_date>2014-01-01</redeem_by_date>
  <single_use>true</single_use>
  <max_redemptions>10</max_redemptions>
  <applies_to_all_plans>false</applies_to_all_plans>
  <plan_codes>
    <plan_code>gold</plan_code>
    <plan_code>platinum</plan_code>
  </plan_codes>
</coupon>

Request for $2 coupon

Accept: application/xml
Content-Type: application/xml; charset=utf-8
<coupon>
  <coupon_code>special</coupon_code>
  <name>Special $2 off coupon</name>
  <discount_type>dollars</discount_type>
  <redeem_by_date>2014-01-01</redeem_by_date>
  <single_use>true</single_use>
  <max_redemptions>10</max_redemptions>
  <applies_to_all_plans>true</applies_to_all_plans>
  <discount_in_cents>
    <USD>200</USD>
  </discount_in_cents>
</coupon>

Response

Status: 201 Created
Content-Type: application/xml; charset=utf-8
Location: https://your-subdomain.recurly.com/v2/coupons/special
<?xml version="1.0" encoding="UTF-8"?>
<coupon href="https://your-subdomain.recurly.com/v2/coupons/special">
  <redemptions href="https://your-subdomain.recurly.com/v2/coupons/special/redemptions"/>
  <coupon_code>special</coupon_code>
  <name>Special 10% off</name>
  <state>redeemable</state>
  <discount_type>percent</discount_type>
  <discount_percent type="integer">10</discount_percent>
  <redeem_by_date type="datetime">2014-01-01T07:00:00Z</redeem_by_date>
  <single_use type="boolean">true</single_use>
  <applies_for_months nil="nil"></applies_for_months>
  <max_redemptions type="integer">10</max_redemptions>
  <applies_to_all_plans type="boolean">false</applies_to_all_plans>
  <created_at type="datetime">2011-04-10T07:00:00Z</created_at>
  <plan_codes type="array">
    <plan_code>gold</plan_code>
    <plan_code>platinum</plan_code>
  </plan_codes>
  <a name="redeem" href="https://your-subdomain.recurly.com/v2/coupons/special/redeem" method="post"/>
</coupon>

$coupon = new Recurly_Coupon();
$coupon->coupon_code = 'special';
$coupon->redeem_by_date = '2014-01-01';
$coupon->single_use = true;

// $2 off...
$coupon->name = 'Special $2 off coupon';
$coupon->discount_type = 'dollars';
$coupon->discount_in_cents->addCurrency('USD',200); // $2.00 discount

// ...or 10% off.
$coupon->name = 'Special 10% off';
$coupon->discount_type = 'percent';
$coupon->discount_percent = 10;

// Limit to gold and platinum plans only.
$coupon->applies_to_all_plans = false;
$coupon->plan_codes = array('gold', 'platinum');

$coupon->create();

coupon = Recurly::Coupon.new(
  :coupon_code    => 'special',
  :redeem_by_date => Date.new(2014, 1, 1),
  :single_use     => true
)

# $2 off...
coupon.name = 'Special $2 off coupon'
coupon.discount_type = 'dollars'
coupon.discount_in_cents = 2_00

# ...or 10% off.
coupon.name = 'Special 10% off'
coupon.discount_type = 'percent'
coupon.discount_percent = 10

# Limit to gold and platinum plans only.
coupon.applies_to_all_plans = false
coupon.plan_codes = %w(gold platinum)

coupon.save

coupon = Coupon(
  coupon_code='special',
  redeem_by_date=datetime.date(2014, 1, 1),
  single_use=True
)

# $2 off...
coupon.name = 'Special $2 off coupon'
coupon.discount_type = 'dollars'
coupon.discount_in_cents = Money(200)

# ...or 10% off.
coupon.name = 'Special 10% off'
coupon.discount_type = 'percent'
coupon.discount_percent = 10

# Limit to gold and platinum plans only.
coupon.applies_to_all_plans = False
coupon.plan_codes = ['gold', 'platinum']

coupon.save()

Deactivate coupon

Deactivate the coupon so customers can no longer redeem the coupon.

DELETE https://:subdomain.recurly.com/v2/coupons/:coupon_code

Example

$coupon = Recurly_Coupon::get('special');
$coupon->delete();

coupon = Recurly::Coupon.find('special')
coupon.destroy

coupon = Coupon.get('special')
coupon.delete()