The Reference Docs Developer Hub

Welcome to the Reference Docs developer hub. You'll find comprehensive guides and documentation to help you start working with Reference Docs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Adjustments: Charges & Credits

Adjustments are the charge and credit line items on your customer's invoices.

Most charge and credit adjustments are created automatically by the Recurly system when there is a subscription billing event. Merchants can manually or programmatically create custom charges and credits on customer accounts that can be billed separately or included with the next subscription invoice.

Adjustments

Adjustments are created in any subscription billing event:

  • Sign-up (setup fee, plan fee, add-on fees)
  • Immediate downgrade/upgrade resulting in a prorated credit and/or charge.
  • Start of new billing period
  • Refund
  • Final invoice (usage-based billing)

Custom charge adjustments are created for various reasons:

  • Purchase of a one-time product
  • Purchase of professional services
  • Recreate a previously incorrect invoice

Custom credit adjustments are also created for various reasons:

  • Issue a service credit
  • Issue an external gift card credit (API only)

Creating Charges

There are a few ways to create a custom charges using Recurly. Using the API, you can use the Purchases endpoint or the Adjustment endpoint or you can use the Admin UI.

Creating Charges Using Purchases

The most recommended method of creating custom charges and also subscription charges, is by using the purchases endpoint in our API.

Purchases supports the most common billing scenarios, such as:

  • creating custom one-time charge(s)
  • creating subscription charges (plan fee, add-on fee, setup fee)
  • creating a combination of subscription charges (such as plan fee and add-on fees) and one-time charges
  • signing up new customers to subscriptions and/or one-time products

All charges are combined into a single total transaction that gets sent to your payment gateway. If transaction is successful, an invoice is created immediately. If transaction fails, an invoice is not created. If account details were passed in, the account will not be created.

If you choose this method, you will have the following options using the API:

Currency

Specify the currency for the purchase. Only a single currency can be specified in a purchase and will apply to entire purchase.

Adjustment

Using the Adjustment object, you can specify any number of custom charges in an array. Required field is a unit amount in cents. You can also include the following per custom charge: add-on code, product code, accounting code, description, quantity, revenue schedule type, tax exempt, tax code, start date, end date.

Subscription

Using the Subscription object, you can include an array of Subscriptions or a single subscription in the purchase. Required if there are no adjustments (custom charges).

Gift Card

Include a gift card with a redemption code to apply to a purchase

Customer Notes

Optional notes field. This will default to the Customer Notes text specified on the Invoice Settings page in your Recurly admin.

Coupon Codes

You can include a list of coupon codes to apply to the purchase. See Multiple Coupons Per Account for more information on how they will apply.

Shipping Address

Specify a shipping address per one-time charge and/or subscription. Find out more here.

To more about our all in one endpoint, click here.

Creating charges using Adjustments endpoint or Admin UI

The other two methods to create charges is through the Admin UI or using the Adjustments endpoint.

There are a few caveats for creating charges using the Admin UI or the Adjustments endpoint:

  • creating a custom one-time charge will require an existing customer account or creating a customer account beforehand
  • custom one-time charges will not be billed until you post a one-off invoice or the charge is picked up on the next subscription billing event (e.g a new subscription billing cycle or adding a subscription to the account).
    • This however, is useful if you want to create a charge on a customer's account and do not want the customer to be charged until their next invoice.
  • Custom charges will not be picked up on an immediate subscription change invoice
  • Uninvoiced adjustments will affect the customer's account balance.

To charge an account in the Admin UI, go to the customer's account and click the Add Charge button above the Charges and Credits table. Adding a charge will leave it uninvoiced on the account until you post an invoice or the next subscription billing event picks it up.

When creating a charge, you will have the following options:

Currency

If you are collecting payment in multiple currencies on your Recurly site, you will see a dropdown for selecting the currency of the charge.

Amount

Enter the per quantity amount of the custom charge. This is a required field.

Quantity

Enter the quantity of the custom charge. This number will be multiplied by the amount to create the adjustment's subtotal before any discounts or taxes.

Description

Enter in a description of the custom charge that will be shown on the invoice line item.

Product Code

Enter in a product code or SKU that can be viewed in your exports and help you connect this revenue to the correct product or service. You can put in an existing plan code or add-on code in Recurly, or a custom code.

Accounting Code

Enter in an accounting code that can be viewed in your exports and help you reconcile your revenue to the correct ledger.

Timeframe

Select the timeframe that will show on the invoice line item. This can be one specific date or a date range. Note that the dates have a time associated with them that will reflect the time zone you have set to your Recurly user profile. All customer invoices are in UTC, so if you create an adjustment while logged in with a different time zone than UTC, your dates will be different on the invoice viewed by the customer.

  • Charge Date / Start Date - Will be 00:00:00 time for the date you selected in the time zone of your user profile
  • End Date - Will be 23:59:59 time for the date you selected in the time zone of your user profile

Any invoice you preview or download while logged in will reflect your user profile time zone, while the customer will receive the invoice in UTC.

Also note that charges with a date range are proratable if the refund date is between the start and end date.

Tax Options (Charges)

If you have enabled taxes, you will see the option to collect taxes on the Add Charge page. This option is enabled by default and sets the charge to taxable. If the customer is located in a taxable region, they will receive tax on the charge at time of invoice. If you have enabled EU VAT you will see the option to select a Tax Type. If you have connected your own Avalara AvaTax account, you will see the option to enter a Tax Code.

Invoice Custom Charges

Creating charges through the Admin UI or the adjustments endpoint will not invoice the charges immediately. After creating the custom charge, in the Admin UI you will see a yellow banner at the top of the account with a Generate Invoice link. Click Generate Invoice to preview the invoice before posting it.

Once the invoice is posted, Recurly will automatically collect on the invoice during our next automatic bill run (typically at the top of every hour). You will see the account's balance go back to $0.00 when this charge is successfully processed. Posting an automatic collection invoice will not require a successful transaction from the customer. If the transaction declines, the invoice will become past due and will go into the Dunning cycle.

If there are uninvoiced charges on an account in different currencies, you will see an option to generate an invoice per currency.

Issuing Credits

In the business scenarios where you may need to issue a service credit or an external gift card (API only) you can use either the Adjustment endpoint or the Admin UI.

Create credit using Admin UI

To credit an account in the Admin UI, go to the customer's account and click the Add Credit button above the Charges and Credits table. Adding a credit will leave it uninvoiced on the account until you post an invoice or the next subscription billing event picks it up.

When creating a credit, you will have the following options:

Currency

If you are collecting payment in multiple currencies on your Recurly site, you will see a dropdown for selecting the currency of the adjustment.

Amount

Enter the per quantity amount of the credit. This is a required field.

Quantity

Enter the quantity of the credit. This number will be multiplied by the amount to create the credit's subtotal before any discounts or taxes.

Description

Enter in a description of the credit that will be shown on the invoice line item.

Product Code

Enter in a product code or SKU that can be viewed in your exports and help you connect this revenue to the correct product or service. You can put in an existing plan code or add-on code in Recurly, or a custom code.

Accounting Code

Enter in an accounting code that can be viewed in your exports and help you reconcile your revenue to the correct ledger.

Timeframe

Select the timeframe that will show on the invoice line item. This can be one specific date or a date range. Note that the dates have a time associated with them that will reflect the time zone you have set to your Recurly user profile. All customer invoices are in UTC, so if you create an adjustment while logged in with a different time zone than UTC, your dates will be different on the invoice viewed by the customer.

  • Charge Date / Start Date - Will be 00:00:00 time for the date you selected in the time zone of your user profile
  • End Date - Will be 23:59:59 time for the date you selected in the time zone of your user profile

Any invoice you preview or download while logged in will reflect your user profile time zone, while the customer will receive the invoice in UTC.

Tax Options (Credits)

Custom credits are not taxable or discountable and Recurly will not reverse a tax or discount amount. This is due to the fact that the custom credit does not have an original charge to reference. Tax and discounts would only be reversed if they were applied on a related charge. If you need to reverse tax or discounts, we recommend you issue a Line Item Refund instead.

Invoice Custom Credits

After adding custom credits to an account, they will be applied to the next invoice event. If you're generating an invoice manually from the Admin UI and there are uninvoiced credits on an account in different currencies, you will see an option to generate an invoice per currency.

Issued credits in an immediate subscription change or a custom credit adjustment will always be included after charge line items on the invoice. Issued credits will always be used to pay for any charges on the invoice. If there is a remaining credit balance, the invoice will be zeroed out and a new remainder credit created that links back to the original credit. This new uninvoiced credit represents the outstanding credit balance for the original credit adjustment and will be picked up as payment on the next invoice.

Note that both issued credits and credit payments are included as line items on an invoice and will affect the subtotal and total of the invoice. If a remainder credit is picked up as payment, the full credit amount will be applied to the invoice and any remainder amount carried over as a new remainder credit linked to the previous remainder credit.

Credits are always applied to invoices in a specific order:

  1. Any Recurly generated prorated credits due to an immediate subscription change
  2. Any uninvoiced custom credits that have yet to be issued on an invoice
  3. Any uninvoiced remainder credits started with the oldest credit