API v1: Credits

Credits reduce future payment amounts. If a user has $10 of unused account credits and her subscription renews for $25, her credit card will be charged for $15. Instead, if her subscription renews for $3, her credit card will not be charged and she will have a balance of $7 in credits.

When an account's subscription is modified in the middle of the period, Recurly generates a credit for the remainder of the current term and a prorated charge for the term for the new subscription fees.

API v1 is deprecated. Please see our latest documentation.

List an Account's Credits

GET/accounts/:account_code/credits

Lists all credits issued for a given account.

Code examples

PHP

1
2
$acct = RecurlyAccount::getAccount($user->id);
$credits = $acct->listCredits();

Ruby

1
credits = Recurly::Credit.list(acct.account_code)

Python

1
credits = recurly.accounts.credits(account_code=acct.account_code)

Credit an Account

POST/accounts/:account_code/credits

Parameters

account_code
Account's unique identifier
amount_in_cents
The credit amount in cents
start_date
If the credit represents a period of usage, this is set to the start of that period. Otherwise this is set to the created_at date.
end_date
Optional. If the credit represents a period of usage, this is the end of the period. Otherwise it can be null.
description
Description that appears on the invoice and account history.
Recurly generates a credit for a modified subscription, the start date and end date indicate the service time used to calculate the credit.using the API to create a credit, the service time is not applicable. The start date is simply set to the time when the credit is requested. See the creating credits section for the required parameters.

Request

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

1
2
3
4
5
<?xml version="1.0"?>
<credit>
  <amount_in_cents>512</amount_in_cents>
  <description>Crediting $5.12</description>
</credit>

Code examples

PHP

1
2
$acct = RecurlyAccount::getAccount($user->id);
$credit = $acct->creditAccount(9.50, 'Crediting $9.50 fee');

Ruby

1
2
3
4
5
credit = Recurly::Credit.create(
  :account_code => account.account_code,
  :amount => 5.12,
  :description => 'Crediting $5.12 fee'
)

Python

1
2
3
4
5
create_data = {
  'amount': '5.12',
  'description': 'Crediting $5.12 fee',
}
create_result = recurly.accounts.credits.create(account_code=acct.account_code, data=create_data)

C#

1
RecurlyCredit credit = RecurlyCredit.CreditAccount(acct.AccountCode, 512, "$5.12 test credit");

Response

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
<?xml version="1.0"?>
<credit type="credit">
  <id>77d2114c493e46e1b7dce2853eb75351</id>
  <account_code>123</account_code>
  <amount_in_cents type="integer">-999</amount_in_cents>
  <start_date type="datetime">2009-11-03T23:27:50-08:00</start_date>
  <end_date type="datetime"></end_date>
  <description>Crediting $9.99</description>
  <created_at type="datetime">2009-11-03T23:27:50-08:00</created_at>
</credit>