Shipping addresses per purchase

Shipping Addresses per Purchase lets you assign a different shipping address to each line item within a single purchase — including individual subscriptions and one-time charges. Each address is displayed on the invoice alongside its associated line items, and taxes are calculated per address, making this feature well-suited for B2C businesses shipping to multiple destinations and B2B businesses with customers taxed across multiple locations.

Not included in Starter or Pro — contact Recurly Sales to upgrade

1Definition 2Key details 3Exports

Prerequisites

Contact [email protected] to have this feature enabled on your site
The Only Bill What Changed setting must be enabled on your site before activation

Definition

Shipping Addresses per Purchase is a Recurly feature that allows distinct shipping addresses to be assigned to individual subscriptions and one-time charges within a single purchase. Taxes are applied per line item based on each address, and invoices are formatted to clearly associate each shipping address with its corresponding line items.

Key details

Using the API

Shipping addresses per purchase are managed through the v2/purchases endpoint. The following behaviors apply:

A new shipping address provided at the purchase level applies to all line items in that purchase
If multiple new shipping addresses are provided at the purchase level, the last address in the request is applied
A new or existing shipping address can be specified per individual line item (subscription or one-time charge)
If both a shipping address ID and a new address are provided for the same line item, an error is returned
If a new address matches one that already exists on the account, Recurly prevents the duplicate from being added. Reference the shipping_id when the address already exists on the account

Address limit The existing limit of 20 shipping addresses per customer account applies to addresses created via the purchase endpoint, the shipping address endpoints, and the Admin UI. Invoices also render a maximum of 500 line items.

Invoice display

Invoices are formatted to clearly associate each shipping address with its corresponding line items. Each shipping address appears as a header above the group of line items associated with it. Line items without a designated shipping address inherit the billing or account address, which is shown at the top of that group.

The Shipped To section on the invoice includes a shipping address count. Billing and account addresses are not counted in this total.

Taxes

When taxes are enabled, each line item is taxed based on its associated shipping address. If a line item has no shipping address, it is taxed based on the billing address — or the account address, if your tax settings are configured to use it. For invoices using manual collection, all charges are taxed based on the account address.

For more on tax configuration, see Tax invoices.

Open amount refunds on multi-tax-rate invoices Open amount refunds will not succeed on invoices with multiple tax rates unless the Credit Invoices feature is enabled on your site. Enable Credit Invoices before attempting open amount refunds on these invoices.

Exports

Since a single invoice can have multiple shipping addresses, use the exports below to identify the address associated with each line item.

Adjustments export

New columns have been added to the Adjustments export for expanded shipping address fields:

Column	Description
`ship_address_name`	Name on the shipping address.
`ship_address_line1`	Street address line 1.
`ship_address_line2`	Street address line 2.
`ship_address_city`	City.
`ship_address_state`	State or province.
`ship_address_zip`	Postal / ZIP code.
`ship_address_country`	Country.
`ship_address_phone`	Phone number on the shipping address.

Invoice summary export

Column	Description
`shipping_address_count`	The number of distinct shipping addresses on an invoice created via the purchase endpoint. Billing and account addresses are not counted.
`shipping_address`	Only populated for invoices created via the subscriptions endpoint — never set for purchase endpoint invoices, since those can have more than one address. Use `shipping_address_count` to determine if multiple addresses are present, then reference the Line Items export for each address.