Recurly

Coupon Redemption API

Table of Contents

Redeem a coupon before or after a subscription

Most coupons are redeemed during a new subscription. This endpoint allows you to 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.

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

Redemption Attributes

Parameter Description
account_code Account code to apply redemption Required
currency Currency for the redemption Required

Example

Request

Accept-Type: application/xml
Content-Type: application/xml; charset=utf-8
<redemption>
  <account_code>1</account_code>
  <currency>USD</currency>
</redemption>

Response

Status: 201 Created
Content-Type: application/xml; charset=utf-8
Location: https://your-subdomain.recurly.com/v2/accounts/1/redemption
<?xml version="1.0" encoding="UTF-8"?>
<redemption href="https://your-subdomain.recurly.com/v2/accounts/1/redemption">
  <coupon href="https://your-subdomain.recurly.com/v2/coupons/special"/>
  <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
  <single_use type="boolean">false</single_use>
  <total_discounted_in_cents type="integer">0</total_discounted_in_cents>
  <currency>USD</currency>
  <created_at type="datetime">2011-06-27T12:34:56Z</created_at>
</redemption>
$coupon = Recurly_Coupon::get('special');
$redemption = $coupon->redeemCoupon('1', 'USD');
account = Recurly::Account.find('1')
coupon = Recurly::Coupon.find('special')
redemption = coupon.redeem(account)
coupon = Coupon.get('special')
redemption = Redemption(account_code='1', currency='USD')
redemption = coupon.redeem(redemption)

Lookup a coupon redemption on an account

Lookup information about the 'active' coupon redemption on an account

GET https://:subdomain.recurly.com/v2/accounts/:account_code/redemption

Attributes

Parameter Description
single_use True if the coupon is valid for one use only
total_discounted_in_cents Total amount saved by the coupon
currency Currency of the redemption
state State of the redemption
created_at Date the coupon was redeemed

Example

Response

Status: 200 OK
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<redemption href="https://your-subdomain.recurly.com/v2/accounts/1/redemption">
  <coupon href="https://your-subdomain.recurly.com/v2/coupons/special"/>
  <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
  <single_use type="boolean">false</single_use>
  <total_discounted_in_cents type="integer">0</total_discounted_in_cents>
  <currency>USD</currency>
  <state>active</state>
  <created_at type="datetime">2011-06-27T12:34:56Z</created_at>
</redemption>
$account = Recurly_Account::get('1');
if ($account->redemption) {
  $redemption = $account->redemption->get());
}
account = Recurly::Account.find('1')
redemption = account.redemption
account = Account.get('1')
redemption = account.redemption()

Remove a coupon from an account

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.

DELETE https://:subdomain.recurly.com/v2/accounts/:account_code/redemption

Example

$redemption = Recurly_CouponRedemption::get('account_code');
$redemption->delete();
account = Recurly::Account.find('1')
redemption = account.redemption
redemption.destroy
account = Account.get('1')
redemption = account.redemption()
redemption.delete()

Lookup a coupon redemption on an invoice

Lookup information about a coupon redemption applied to an invoice

GET https://:subdomain.recurly.com/v2/invoices/:invoice_number/redemption

Attributes

Parameter Description
single_use True if the coupon is valid for one use only
total_discounted_in_cents Total amount saved by the coupon
currency Currency of the redemption
state State of the redemption
created_at Date the coupon was redeemed

Example

Response

Status: 200 OK
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<redemption href="https://your-subdomain.recurly.com/v2/accounts/1/redemption">
  <coupon href="https://your-subdomain.recurly.com/v2/coupons/special"/>
  <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
  <single_use type="boolean">true</single_use>
  <total_discounted_in_cents type="integer">0</total_discounted_in_cents>
  <currency>USD</currency>
  <state>inactive</state>
  <created_at type="datetime">2011-06-27T12:34:56Z</created_at>
</redemption>
$invoice = Recurly_Invoice::get('1');
if($invoice->redemption) {
  $redemption = $invoice->redemption->get();
}
invoice = Recurly::Invoice.find('1')
redemption = invoice.redemption
invoice = Invoice.get('1')
redemption = invoice.redemption()