Adjustments: Charges & Credits

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 charge using Recurly. Using the API, you can use the Purchases endpoint or the Adjustments / Line Items endpoint, or you can use the Admin UI.

Create Charges Using Purchases Endpoint

The recommended method of creating custom charges as well as subscription charges is 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 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 the transaction is successful, an invoice is created immediately. If the transaction fails, an invoice is not created. If account details were passed in as part of the failed transaction, 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, item 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 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 learn more about our all-in-one Purchases endpoint, click here.

Create Charges Using Adjustments / Line Items Endpoint or Admin UI

The other two methods to create charges are through the Admin UI or using the Adjustments (for v2 API) or Line Items (for v3 API) endpoint.

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

Creating a custom one-time charge requires an existing customer account
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 Item/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.

Invoice Option

Specify whether you want the charge to be invoiced immediately, or picked up with the next renewal or new subscription invoice for the account. Immediate invoicing is only available on sites with the Credit Invoices feature enabled.

Charge Type

Choose whether the charge involves a specific item from your catalog, or if you will enter custom details for the charge. Item charges are only available on sites with the Credit Invoices feature enabled.

Description

For open amount charges, enter in a description of the custom charge that will be shown on the invoice line item. For item charges, this will default to the item's Name.

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.

Amount

Enter the per-quantity amount of the custom charge. This is a required field. For item charges, this will default to the item's Default Price, but can be edited.

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. Only available for open amount charges, the item's External SKU will be auto-populated in this field for item charges.

Accounting Code

Enter in an accounting code that can be viewed in your exports and help you reconcile your revenue to the correct ledger. Only available for open amount charges, the item's Accounting Code will be auto-populated in this field for item charges.

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 in 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 Collection

If you have enabled taxes, you will see the option to collect taxes for open amount charges. 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. For item charges, the item's taxation settings will be auto-populated in this field.

Invoice Custom Charges

Creating charges through the Adjustments endpoint will not invoice those charges immediately. Use the POST Invoice endpoint to generate the invoice. If the Credit Invoices feature is not enabled, creating charges through the Admin Console will not invoice the charges immediately, either. In this case, after creating the custom charge, you will see a yellow banner at the top of the account in the Admin UI with a Generate Invoice link. Click Generate Invoice to preview the invoice before posting it.

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

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.

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 Adjustments endpoint or the Admin UI.

Create Credits 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. Item credits are not available; credits of items from your catalog should be handled via refunding the original item charge, or posting an open amount credit.

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. (Note: for amounts under $1, you muster enter a leading 0. Example: enter $0.99 instead of $.99.)

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

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.

Taxation

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 to 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 charge invoice event. If the Credit Invoices feature is enabled, the credit will be invoiced on a Credit Memo immediately, and that Credit Memo will be applied to the next charge event. If the Credit Invoices feature is not enabled, adding a credit will leave it uninvoiced on the account until you post an invoice or the next subscription billing event picks it up. 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.

In an immediate subscription change or a custom credit adjustment, issued credits 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 remaining amount carried over as a new remainder credit linked to the previous remainder credit.

Credits are always applied to invoices in a specific order:

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