API v1: Coupons

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.

Read more about how Coupons work.

API v1 is deprecated. Please see our latest documentation.

Lookup an Account's Active Coupon

GET/accounts/:account_code/coupon

With a simple API call, you can lookup if a coupon is active on an account. Recurly will automatically expire and remove coupons from an account once the coupon has expired.

Response

Content-Type: application/xml; charset=utf-8

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
<?xml version="1.0"?>
<coupon>
  <account_code>account123</account_code>
  <coupon_code>50Ppercentoff</coupon_code>
  <name>50 Percent Off - VIP</name>
  <discount_in_cents type="integer"></discount_in_cents>
  <discount_percent type="integer">50</discount_percent>
  <redemption>
    <account_code>account123</account_code>
    <redeemed_at type="datetime">2010-06-28T23:27:46Z</redeemed_at>
    <total_discounted_in_cents type="integer">1200</total_discounted_in_cents>
  </redemption>
</coupon>

Code examples

PHP

1
2
3
$coupon = RecurlyCouponRedemption::getCoupon($account_code);
// or
$coupon = $account->getCoupon();

Ruby

1
coupon = Recurly::Coupon.find(account_code)

Python

1
charges = recurly.accounts.coupon(account_code=acct.account_code)

C#

1
2
3
RecurlyAccountCoupon coupon = RecurlyAccountCoupon.Get(accountCode);
// or
account.GetActiveCoupon();

Redeem a Coupon with a Subscription

POST/accounts/:account_code/subscription

Recurly allows your customers to redeem a coupon at the beginning of a subscription. Simply pass the coupon code along with the initial subscription request. The coupon will be applied to the subscription if it is applicable.

Please note: if the coupon code is specified and is invalid, the API will return a 422 error and the inline errors will describe that the coupon code is invalid or otherwise ineligible for redemption.

Request

Content-Type: application/xml; charset=utf-8
Accept: application/xml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
<?xml version="1.0"?>
<subscription>
  <plan_code>bronze</plan_code>
  <coupon_code>COUPON_CODE</coupon_code>
  <account>
    <account_code>123</account_code>
    // ...
    <billing_info>
      // ...
    </billing_info>
  </account>
</subscription>

Code examples

PHP

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
$acct = new RecurlyAccount(
  // ...
);

$subscription = new RecurlySubscription();
$subscription->plan_code = PLAN_CODE;
$subscription->coupon_code = COUPON_CODE;
$subscription->account = $acct;
$subscription->billing_info = new RecurlyBillingInfo($subscription->account->account_code);

$billing_info = $subscription->billing_info;
// ...

$sub_response = $subscription->create();

Ruby

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
account = Recurly::Account.new(
  // ...
)
account.billing_info = Recurly::BillingInfo.new(
  // ...
)

sub = Recurly::Subscription.create(
  :account_code => account.account_code,
  :plan_code => PLAN_CODE, 
  :coupon_code => COUPON_CODE,
  :account => account
)

Python

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
create_account_data = {
  // ...
  }

create_subscription_data = {
    'plan_code': PLAN_CODE,
    'coupon_code': COUPON_CODE,
    'account': {
      'account_code': self.account_code,
      // ...
        },
      },
    },
  }
create_subscription_result = recurly.accounts.subscription.create(
                               account_code=self.account_code, 
                               data=create_subscription_data
                             )

C#

1
2
3
4
5
6
7
8
9
RecurlyAccount account = new RecurlyAccount(accountCode);
// ...

RecurlySubscription subscription = new RecurlySubscription(account);
subscription.PlanCode = "gold";
subscription.Quantity = 1;
subscription.CouponCode = "coupon";

subscription.Create();

Redeem a Coupon on an Account before or after a Subscription

POST/accounts/:account_code/coupon

You may apply a coupon to an account at any time, not just during the initial subscription request. This functionality allows you redeem a coupon for a customer after their initial subscription, or in anticipation of a future subscription. When you redeem a coupon on an account, the coupon will be applied to the next subscription creation (new subscription), modification (e.g. upgrade or downgrade), or renewal.

Request

Content-Type: application/xml; charset=utf-8
Accept: application/xml

1
2
3
4
<?xml version="1.0"?>
<coupon>
  <coupon_code>50percentoff</coupon_code>
</coupon>

Code examples

PHP

1
$coupon = $account->redeemCoupon(coupon_code);

Ruby

1
2
3
4
@coupon = Recurly::Coupon.create({
  :account_code => account_code,
  :coupon_code => coupon_code
})

C#

1
2
3
RecurlyAccountCoupon coupon = RecurlyAccountCoupon.Redeem(accountCode, couponCode);
// or
account.RedeemCoupon(couponCode);

Remove a Coupon from an Account

DELETE/accounts/:account_code/coupon

Occasionally, you may want to remove a coupon from an account. Recurly will automatically remove coupons after they expire or are otherwise no longer valid for an account. If you want to remove a coupon from an account before it expires, you may use the examples below. Please note: the coupon will still count towards the "maximum redemption total" of a coupon.

Code examples

PHP

1
2
3
4
5
$coupon = RecurlyCouponRedemption::getCoupon($account_code);
$coupon->redemption->clear();
// or
$coupon = $account->getCoupon();
$coupon->redemption->clear();

Ruby

1
2
coupon = Recurly::Coupon.find(account_code)
coupon.destroy

Python

1
recurly.accounts.coupon.delete(account_code=self.account_code)

C#

1
2
3
RecurlyAccountCoupon.RemoveCoupon(accountCode);
// or
coupon.Remove();