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 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.
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/verena/adjustments?cursor=1304958672>; rel="next"
ETag: "0d34d4e5faed7fb1b577bafbb5bb71f9"
<?xml version="1.0" encoding="UTF-8"?>
<adjustments type="array">
  <adjustment type="charge" href="https://your-subdomain.recurly.com/v2/adjustments/626db120a84102b1809909071c701c60">
    <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>
    <description>One-time Charged Fee</description>
    <accounting_code nil="nil"></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>
    <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>
    <tax_exempt type="boolean">false</tax_exempt>
    <start_date type="datetime">2011-08-31T03:30:00Z</start_date>
    <end_date nil="nil"></end_date>
    <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

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.
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/adjustments/626db120a84102b1809909071c701c60?cursor=1304958672>; rel="next"
ETag: "0d34d4e5faed7fb1b577bafbb5bb71f9"
<?xml version="1.0" encoding="UTF-8"?>
  <adjustment type="charge" href="https://your-subdomain.recurly.com/v2/adjustments/626db120a84102b1809909071c701c60">
    <account href="https://your-subdomain.recurly.com/v2/accounts/100"/>
    <invoice href="https://your-subdomain.recurly.com/v2/invoices/1108"/>
    <uuid>626db120a84102b1809909071c701c60</uuid>
    <description>One-time Charged Fee</description>
    <accounting_code nil="nil"></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>
    <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>
    <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>special</type>
        <tax_rate type="float">0.015</tax_rate>
        <tax_in_cents type="integer">30</tax_in_cents>
      </tax_detail>
    </tax_details>
    <start_date type="datetime">2011-08-31T03:30:00Z</start_date>
    <end_date nil="nil"></end_date>
    <created_at type="datetime">2011-08-31T03:30:00Z</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

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.

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/945a4cb9afd64300b97b138407a51aef
<?xml version="1.0" encoding="UTF-8"?>
<adjustment type="credit" href="https://your-subdomain.recurly.com/v2/adjustments/626db120a84102b1809909071c701c60">
  <account href="https://your-subdomain.recurly.com/v2/accounts/1"/>
  <uuid>626db120a84102b1809909071c701c60</uuid>
  <description>Charge for extra bandwidth</description>
  <accounting_code>bandwidth</accounting_code>
  <origin>charge</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>
  <tax_exempt type="boolean">false</tax_exempt>
  <product_code>basic</product_code>
  <start_date type="datetime">2011-08-31T03:30:00Z</start_date>
  <end_date nil="nil"></end_date>
  <created_at type="datetime">2011-08-31T03:30:00Z</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.find('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)
RecurlyCharge.ChargeAccount("1", 5000, "Charge for extra bandwidth");

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 type="credit" href="https://your-subdomain.recurly.com/v2/adjustments/626db120a84102b1809909071c701c60">
  <account href="https://your-subdomain.recurly.com/v2/accounts/100"/>
  <uuid>626db120a84102b1809909071c701c60</uuid>
  <description>Refund for being a great customer</description>
  <accounting_code nil="nil"></accounting_code>
  <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>
  <tax_exempt type="boolean">false</tax_exempt>
  <product_code>basic</product_code>
  <start_date type="datetime">2011-08-31T03:30:00Z</start_date>
  <end_date nil="nil"></end_date>
  <created_at type="datetime">2011-08-31T03:30:00Z</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)

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