Shipping addresses per purchase


New Feature: Shipping Address(es) per Purchase

This feature enables shipping address support for purchases created in our API using the v2/purchases endpoint. This will allow you to:

  • Assign a shipping address to a purchase
  • Tax all line items based on an account address
  • Assign a shipping address per line item in a purchase
  • Tax line items based on a line item shipping address

Please contact [email protected] to have this feature enabled on your site.

If you are an existing customer, you must have "Only Bill What Changed" enabled on your site first. See for more information.

Shipping Addresses per Purchase

We recently launched the ability to assign a shipping address to a purchase (which can include subscriptions and one time charges). Additionally, when using the purchase endpoint in our API, you can also specify different shipping addresses per line item. For example, if you have the multiple subscriptions feature enabled, you can specify different shipping addresses for each subscription and/or custom charge(s)

It's a great feature for B2C physical goods businesses that allow customers to ship their products to more than one address (e.g customer wants to send products to friends). It can also be useful for B2B businesses who have customers that need to be taxed based on multiple locations.

Using the API

The purchase endpoint in our API supports the following shipping address functionality:

  • Apply a new shipping address for a purchase
  • This top level address will apply to all line items (subscriptions and one time charges) in a purchase
  • If multiple new shipping addresses are provided, the last address in the API request will be applied to the purchase
  • any subscriptions in the purchase will be associated with the shipping address applied
    • Apply a new or existing shipping addresses per line item
  • A new shipping address or existing shipping address ID can be specified per line item (subscription or charge)
  • If both a shipping address ID and new shipping address are provided for the same subscription or charge, an error will be returned.


Duplicate shipping addresses

If a new address is specified either at the purchase level or line-item level, and the exact address already exists on the account, Recurly will ensure that the duplicate address will not be added to the account. It is also suggested that you reference the shipping_id if the shipping address already exists.

Invoice Display

We've updated the invoice display in order to handle invoices with multiple shipping addresses so that it is clear to the customer of which shipping address is associated with which line item(s).


Lisa purchases three monthly Kale Krate subscriptions. One box is for her sister Sarah, the second box is for her mother Shirley, and the third box is for herself. She also decides to purchase a blender (a one-time product) for her friend, Bill. All four of the family members live in different states. With the new shipping address functionality, the invoice will contain multiple shipping addresses associated with their correlated subscriptions and charge(s) adjustments The Kale Krate and the blender will be shipped to their respective person's address.


  • Address at the top of line item table for each shipping address and its associated line items
  • if a line item(s) does not have a shipping address and inherits the billing address as its taxable address, this billing address will be specified at the top of the table with the associated line-items
    • Shipped To section will include special note (the Shipping Address Count will not include billing or account addresses)

This is the invoice display for a multiple shipping address purchase example, outlined above.


Is there a limit on shipping addresses allowed on an account?

Yes. We will still enforce the existing rule of 20 allowed shipping addresses per customer account. This applies to shipping addresses created in the API (via purchase endpoint or shipping address endpoints) and the Admin UI. Also keep in mind that Recurly can only render up to 500 line items in an invoice.


If taxes are enabled on your site, with this feature, an invoice can have more than one tax rate. We will tax each line item based on it's associated shipping address. If a line item does not have a shipping address specified, it will be taxed based on the billing address or the account address if your tax settings are configured as such. If you are using manual collection for your invoices, the subscription charge and/or one time charge adjustment will be taxed based on account address.

Please see Tax Invoices for more information.


Multiple Tax Rate Invoice and Open Amount Refunds

Until you have the Credit Invoices feature enabled on your site, open amount refunds will not succeed on invoices where there are multiple tax rates. This is due to existing behavior, where a line-item specific tax rate can't be applied. Credit Invoices resolves this issue, and thus must be enabled on your site.


With this feature, an invoice can have more than one shipping address associated with it since each subscription(s) charge and/or one time charge(s) adjustment could have different addresses. We recommend that you reference the Adjustments - Export to determine the shipping address associated with a line item.

Adjustments Export
We have added new columns for expanded shipping_address fields. This will be useful in determining the shipping address associated with each subscription and/or one time charge adjustment.

  • ship_address_name
  • ship_address_line1
  • ship_address_line2
  • ship_address_city
  • ship_address_state
  • ship_address_zip
  • ship_address_country
  • ship_address_phone

Invoice - Summary Export
For shipping addresses created using the purchase endpoint, there will be a new shipping_address_count field. This is a count of the number of shipping addresses created on an invoice. The shipping_address field will never be set for invoices created in the purchase endpoint, as there can be more than one shipping address per invoice. This shipping_address field will only be populated for invoices created using the subscriptions endpoint. You can reference the shipping_address_count field to determine if there is more than 1 address and use the Line Items export to identify each shipping address.