Recurly

Adjustments API

Table of Contents

List an account's adjustments

Lists all charges and credits issued for a given account.

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

Query Parameters

Parameter Default Description
type all The type of adjustment to return: "charge" or "credit"
state all The state of the adjustments to return: "pending" or "invoiced".
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

Response

Status: 200 OK
Content-Type: application/xml; charset=utf-8
X-Records: 123
Link: <https://your-subdomain.recurly.com/v2/accounts/100/adjustments?cursor=1304958672>; rel="next"
ETag: "0d34d4e5faed7fb1b577bafbb5bb71f9"
<?xml version="1.0" encoding="UTF-8"?>
<adjustments type="array">
  <adjustment href="https://your-subdomain.recurly.com/v2/adjustments/626db120a84102b1809909071c701c60" type="charge">
    <account href="https://your-subdomain.recurly.com/v2/accounts/100"/>
    <invoice href="https://your-subdomain.recurly.com/v2/invoices/1108"/>
    <subscription href="https://your-subdomain.recurly.com/v2/subscriptions/17caaca1716f33572edc8146e0aaefde"/>
    <uuid>626db120a84102b1809909071c701c60</uuid>
    <state>invoiced</state>
    <description>One-time Charged Fee</description>
    <accounting_code nil="nil"/>
    <product_code>basic</product_code>
    <origin>debit</origin>
    <unit_amount_in_cents type="integer">2000</unit_amount_in_cents>
    <quantity type="integer">1</quantity>
    <original_adjustment_uuid>2cc95aa62517e56d5bec3a48afa1b3b9</original_adjustment_uuid> <!-- Only shows if adjustment is a credit created from another credit. -->
    <discount_in_cents type="integer">0</discount_in_cents>
    <tax_in_cents type="integer">180</tax_in_cents>
    <total_in_cents type="integer">2180</total_in_cents>
    <currency>USD</currency>
    <taxable type="boolean">false</taxable>
    <tax_exempt type="boolean">false</tax_exempt>
    <tax_code nil="nil"/>
    <start_date type="datetime">2011-08-31T03:30:00Z</start_date>
    <end_date nil="nil"/>
    <created_at type="datetime">2011-08-31T03:30:00Z</created_at>
  </adjustment>
  <!-- Continued... -->
</adjustments>
$adjustments = Recurly_AdjustmentList::get('account_code');
foreach ($adjustments as $adjustment) {
  print "Adjustment: $adjustment\n";
}
The client library will automatically fetch the next page of the results. There may be a slight delay when fetching the next page.
account = Recurly::Account.find('1')
account.adjustments.find_each do |adjustment|
  puts "Adjustment: #{adjustment.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
account = Account.get('1')
adjustments = account.adjustments()
while adjustments:
    for adjustment in adjustments:
        print 'Adjustment: %s' % adjustment
    try:
        adjustments = adjustments.next_page()
    except PageError:
        adjustments = ()

#client version 2.1.6+
account = Account.get('1')
for adjustment in account.adjustments():
    print 'Adjustment: %s' % adjustment
using System.Linq;

var account = Accounts.Get("1");
var adjustments = account.GetAdjustments();
while (adjustments.Any())
{
	foreach (var adjustment in adjustments)
		Console.WriteLine("Adjustment: " + adjustment);
	adjustments = adjustments.Next;
}

Get an Adjustment

Returns information about a single adjustment.

GET https://:subdomain.recurly.com/v2/adjustments/:uuid

Query Parameters

Parameter Default Description
type credits and charges The type of adjustment to return: "charge" or "credit"
state active The state of the adjustments to return: "pending" or "invoiced".
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.

Example

Response

Status: 200 OK
Content-Type: application/xml; charset=utf-8
X-Records: 123
Link: <https://your-subdomain.recurly.com/v2/adjustments/626db120a84102b1809909071c701c60?cursor=1304958672>; rel="next"
ETag: "0d34d4e5faed7fb1b577bafbb5bb71f9"
<?xml version="1.0" encoding="UTF-8"?>
  <adjustment href="https://your-subdomain.recurly.com/v2/adjustments/626db120a84102b1809909071c701c60" type="charge">
    <account href="https://your-subdomain.recurly.com/v2/accounts/100"/>
    <invoice href="https://your-subdomain.recurly.com/v2/invoices/1108"/>
    <uuid>626db120a84102b1809909071c701c60</uuid>
    <state>invoiced</state>
    <description>One-time Charged Fee</description>
    <accounting_code/>
    <product_code>basic</product_code>
    <origin>debit</origin>
    <unit_amount_in_cents type="integer">2000</unit_amount_in_cents>
    <quantity type="integer">1</quantity>
    <original_adjustment_uuid>2cc95aa62517e56d5bec3a48afa1b3b9</original_adjustment_uuid> <!-- Only shows if adjustment is a credit created from another credit. -->
    <discount_in_cents type="integer">0</discount_in_cents>
    <tax_in_cents type="integer">175</tax_in_cents>
    <total_in_cents type="integer">2175</total_in_cents>
    <currency>USD</currency>
    <taxable type="boolean">false</taxable>
    <tax_type>usst</tax_type>
    <tax_region>CA</tax_region>
    <tax_rate type="float">0.0875</tax_rate>
    <tax_exempt type="boolean">false</tax_exempt>
    <tax_details type="array">
      <tax_detail>
        <name>california</name>
        <type>state</type>
        <tax_rate type="float">0.065</tax_rate>
        <tax_in_cents type="integer">130</tax_in_cents>
      </tax_detail>
      <tax_detail>
        <name>san mateo county</name>
        <type>county</type>
        <tax_rate type="float">0.01</tax_rate>
        <tax_in_cents type="integer">20</tax_in_cents>
      </tax_detail>
      <tax_detail>
        <name>sf municipal tax</name>
        <type>city</type>
        <tax_rate type="float">0.0</tax_rate>
        <tax_in_cents type="integer">0</tax_in_cents>
      </tax_detail>
      <tax_detail>
        <name nil="nil"/>
        <type>special</type>
        <tax_rate type="float">0.0125</tax_rate>
        <tax_in_cents type="integer">25</tax_in_cents>
      </tax_detail>
    </tax_details>
    <start_date type="datetime">2015-02-04T23:13:07Z</start_date>
    <end_date nil="nil"/>
    <created_at type="datetime">2015-02-04T23:13:07Z</created_at>
  </adjustment>
$adjustments = Recurly_AdjustmentList::get('account_code');
foreach ($adjustments as $adjustment) {
  print "Adjustment: $adjustment\n";
}
The client library will automatically fetch the next page of the results. There may be a slight delay when fetching the next page.
account = Recurly::Account.find('1')
account.adjustments.find_each do |adjustment|
  puts "Adjustment: #{adjustment.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
account = Account.get('1')
adjustments = account.adjustments()
while adjustments:
    for adjustment in adjustments:
        print 'Adjustment: %s' % adjustment
    try:
        adjustments = adjustments.next_page()
    except PageError:
        adjustments = ()

#client version 2.1.6+
account = Account.get('1')
for adjustment in account.adjustments():
    print 'Adjustment: %s' % adjustment
var adjustment = Adjustments.Get("123456789");
Console.WriteLine("Adjustment: " + adjustment);

Create a charge or credit

Creates a one-time charge on an account. Charges are not invoiced or collected immediately. Non-invoiced charges will automatically be invoices when the account's subscription renews, or you trigger a collection by posting an invoice. Charges may be removed from an account if they have not been invoiced.

POST https://:subdomain.recurly.com/v2/accounts/:account_code/adjustments

Adjustment Attributes

Parameter Description
account_code Account code Required
currency Currency, 3-letter ISO code Required
unit_amount_in_cents Positive amount for a charge, negative amount for a credit. Max 10000000. Required
description Description of the adjustment for the invoice
quantity Quantity, defaults to 1
accounting_code Accounting code. Max of 20 characters.
tax_exempt true exempts tax on the charge, false applies tax on the charge. If not defined, then defaults to the Plan and Site settings. This attribute does not work for credits (negative adjustments). Credits are always post-tax. Pre-tax discounts should use the Coupons feature.
tax_code Optional field for EU VAT merchants and Avalara AvaTax Pro merchants. If you are using Recurly's EU VAT feature, you can use values of 'unknown', 'physical', or 'digital'. If you have your own AvaTax account configured, you can use Avalara tax codes to assign custom tax rules.

Charge Example

Request

Location: https://your-subdomain.recurly.com/v2/accounts/1/adjustments
Accept: application/xml
Content-Type: application/xml; charset=utf-8
<adjustment>
  <description>Charge for extra bandwidth</description>
  <unit_amount_in_cents>5000</unit_amount_in_cents>
  <currency>USD</currency>
  <quantity>1</quantity>
  <accounting_code>bandwidth</accounting_code>
  <tax_exempt>false</tax_exempt>
</adjustment>

Response

Status: 201 Created
Content-Type: application/xml; charset=utf-8
Location: https://your-subdomain.recurly.com/v2/adjustments/626db120a84102b1809909071c701c60
<?xml version="1.0" encoding="UTF-8"?>
<adjustment href="https://your-subdomain.recurly.com/v2/adjustments/626db120a84102b1809909071c701c60" type="charge">
  <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
  <uuid>626db120a84102b1809909071c701c60</uuid>
  <state>pending</state>
  <description>Charge for extra bandwidth</description>
  <accounting_code>bandwidth</accounting_code>
  <product_code nil="nil"/>
  <origin>debit</origin>
  <unit_amount_in_cents type="integer">5000</unit_amount_in_cents>
  <quantity type="integer">1</quantity>
  <discount_in_cents type="integer">0</discount_in_cents>
  <tax_in_cents type="integer">0</tax_in_cents>
  <total_in_cents type="integer">5000</total_in_cents>
  <currency>USD</currency>
  <taxable type="boolean">false</taxable>
  <tax_exempt type="boolean">false</tax_exempt>
  <start_date type="datetime">2015-02-04T23:54:06Z</start_date>
  <end_date nil="nil"/>
  <created_at type="datetime">2015-02-04T23:54:06Z</created_at>
</adjustment>
$charge = new Recurly_Adjustment();
$charge->account_code = '1';
$charge->description = 'Charge for extra bandwidth';
$charge->unit_amount_in_cents = 5000; // $50.00
$charge->currency = 'USD';
$charge->quantity = 1;
$charge->accounting_code = 'bandwidth';
$charge->tax_exempt = false;
$charge->create();
account = Recurly::Account.find('1')
account.adjustments.create(
  :description          => 'Charge for extra bandwidth',
  :unit_amount_in_cents => 50_00,
  :currency             => 'USD',
  :quantity             => 1,
  :accounting_code      => 'bandwidth'
  :tax_exempt           => false
)
account = Account.get('1')
charge = Adjustment(
  description='Charge for extra bandwidth',
  unit_amount_in_cents=5000,
  currency='USD',
  quantity=1,
  accounting_code='bandwidth'
  tax_exempt=False
)
account.charge(charge)
var account = Accounts.Get("1");
var adjustment = account.NewAdjustment(
	"USD",                        // currency
	5000,                         // unit_amount_in_cents
	"Charge for extra bandwidth", // description
	1,                            // quantity
	"bandwidth",                  // accounting_code
	false);                       // tax_exempt
adjustment.Create();

Credit Example

Request

Location: https://your-subdomain.recurly.com/v2/accounts/1/adjustments
Accept: application/xml
Content-Type: application/xml; charset=utf-8
<adjustment>
  <description>Refund for being a great customer</description>
  <unit_amount_in_cents>-2000</unit_amount_in_cents>
  <currency>USD</currency>
  <quantity>1</quantity>
</adjustment>

Response

Status: 201 Created
Content-Type: application/xml; charset=utf-8
Location: https://your-subdomain.recurly.com/v2/adjustments/945a4cb9afd64300b97b138407a51aef
<?xml version="1.0" encoding="UTF-8"?>
<adjustment href="https://your-subdomain.recurly.com/v2/adjustments/945a4cb9afd64300b97b138407a51aef" type="credit">
  <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
  <uuid>945a4cb9afd64300b97b138407a51aef</uuid>
  <state>pending</state>
  <description>Refund for being a great customer</description>
  <accounting_code nil="nil"/>
  <product_code nil="nil"/>
  <origin>credit</origin>
  <unit_amount_in_cents type="integer">-2000</unit_amount_in_cents>
  <quantity type="integer">1</quantity>
  <discount_in_cents type="integer">0</discount_in_cents>
  <tax_in_cents type="integer">0</tax_in_cents>
  <total_in_cents type="integer">-2000</total_in_cents>
  <currency>USD</currency>
  <taxable type="boolean">false</taxable>
  <tax_exempt type="boolean">false</tax_exempt>
  <start_date type="datetime">2015-02-04T23:56:56Z</start_date>
  <end_date nil="nil"/>
  <created_at type="datetime">2015-02-04T23:56:56Z</created_at>
</adjustment>
$credit = new Recurly_Adjustment();
$credit->account_code = '1';
$credit->description = 'Refund for being a great customer';
$credit->unit_amount_in_cents = -2000; // Negative $20.00.
$credit->currency = 'USD';
$credit->quantity = 1;
$credit->create();
account = Recurly::Account.find('1')
account.adjustments.create(
  :description          => 'Refund for being a great customer',
  :unit_amount_in_cents => -20_00,
  :currency             => 'USD',
  :quantity             => 1
)
account = Account.get('1')
credit = Adjustment(
  description='Refund for being a great customer',
  unit_amount_in_cents=-2000,
  currency='USD',
  quantity=1
)
account.charge(credit)
var account = Accounts.Get("1");
var adjustment = account.CreateAdjustment(
	"USD",                               // currency
	-2000,                               // unit_amount_in_cents
	"Refund for being a great customer", // description
	1);                                  // quantity (default is 1)
adjustment.Create();

Delete an adjustment

Delete a non-invoiced adjustment from an account.

An adjustment may only be deleted if it has not been invoiced.
DELETE https://:subdomain.recurly.com/v2/adjustments/:uuid

Example

$adjustment = Recurly_Adjustment::get('945a4cb9afd64300b97b138407a51aef');
$adjustment->delete();
adjustment = Recurly::Adjustment.find('945a4cb9afd64300b97b138407a51aef')
adjustment.destroy
adjustment = Adjustment.get('945a4cb9afd64300b97b138407a51aef')
adjustment.delete()
var adjustment = Adjustments.Get("123456789");
adjustment.Delete()