Coupon Redemption API

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>

$redemption = Recurly_CouponRedemption::get('1');

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()