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.

Subscription Adjustments

Subscription adjustments are created in any subscription billing event:

  • Sign-up
  • Immediate downgrade/upgrade
  • Renewal
  • Refund
  • Final invoice (usage-based billing)

Subscription adjustments are created for the products in your customer's subscription:

  • Setup fee (only on first invoice)
  • Plan fee
  • Add-on fees

Proration

Immediate subscription changes (downgrade or upgrade) will prorate both charges and credits. To learn why we prorate and how it is calculated, read about Changing Subscriptions.

Custom Adjustments

Custom adjustments are created for various reasons:

  • Purchase of a one-time product
  • Purchase of professional services
  • Recreate a previously incorrect invoice
  • Issue a service credit
  • Issue an external gift card credit (API only)

Custom adjustment charges and credits created on an existing account using the Admin UI or adjustments API and are not billed until you either post a one-off invoice or the adjustment is picked up on the next subscription billing event:

  • Post a separate invoice
  • Automatically picked up on the invoice of a new subscription added to the account
  • Automatically picked up on the next renewal of an existing subscription on the account
    Note: custom charges will not be picked up on an immediate subscription change invoice.
    Custom adjustments that are uninvoiced will affect the customer's account balance.

Custom adjustment charges created on a new or existing account using the purchases API will
be billed immediately and an invoice is automatically generated if the transaction is successful.

  • Automatically collected
  • If transaction fails, purchase request is rolled back and invoice and/or account is not created.
  • One or many adjustments in a purchase request equates to a single transaction to the gateway

Create a Custom Charge or Credit

To create a custom charge via the API, use the purchase endpoint. Learn more here

To charge or credit an account in the Admin UI, go to the customer's account and click the Add Charge or Add Credit button above the Charges and Credits table. Adding a charge or 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 charge or 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 adjustment. This is a required field.

Quantity

Enter the quantity of the adjustment. 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 adjustment 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

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.

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 Charges and Credits

As long as there is at least one uninvoiced charge on an account, you can invoice the account. 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 and credits on an account in different currencies, you will see an option to generate an invoice per currency.

Issuing Credits and Credit Payments

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 the 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

Adjustments: Charges & Credits

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