Shipping Addresses

Feature overview

With Recurly's shipping addresses, you can track the physical delivery address for individual subscriptions, and facilitate the fulfillment of any shipments you need to make.

Shipping addresses are tied to the account (your customer). Each account can have up to 20 different shipping addresses, and if you have enabled multiple subscriptions per account, you can associate different shipping addresses to each subscription.

When a subscription is associated with a shipping address, taxes will be based on the shipping address (if applicable), and the invoice will display the shipping address.

Combined with a full set of API endpoints, webhooks, email parameters, and information in our exports, Recurly's support for shipping addresses will enable you to successfully manage your physical shipments.

Create, edit and delete shipping addresses

The Admin Console allows you to do everything you need to do to manage shipping addresses on your accounts.

On the account detail page, you will see

• Summary information about shipping addresses on the account, along with a "Manage addresses" link that will take you to a page where you can create, edit and delete shipping addresses
• Summary information about shipping addresses on each active subscription

You can also manage shipping addresses using the Recurly API. For more information, please refer to the API documentation

Shipping addresses and subscriptions

Once you have defined a shipping address, you can associate the address with a subscription. This will result in:

• The shipping address will be displayed on the invoice
• The shipping address will be used for tax calculation purposes (if applicable)

You can also manage the relationship between a subscription and a shipping address using the Recurly API. For more information, please refer to the API documentation

Activity log

Changes related to shipping addresses will also appear in the Activity Log associated with each account. For example, when a shipping address is updated, the old and new information will appear in the Activity Log, along with information about who made the change and which subscription was affected (if applicable).

Email parameters

You can add information about a subscription's shipping address in email communications with your customers. The following email parameters are available:

Shipping Address fields

{{subscription_has_shipping_address?}}

Returns true is the subscription has a shipping address.

{{subscription_shipping_nickname}}

{{subscription_shipping_first_name}}

{{subscription_shipping_last_name}}

{{subscription_shipping_address1}}

{{subscription_shipping_address2}}

{{subscription_shipping_city}}

{{subscription_shipping_state}}

{{subscription_shipping_zip}}

{{subscription_shipping_country}}

{{subscription_shipping_phone}}

{{subscription_shipping_email}}

{{subscription_shipping_vat_number}}

{{subscription_full_shipping_address}}

The shipping address (street 1, street 2, city, state, postal code, country) in one string, separated by commas.

Exports

Shipping address information is now included on both the Invoice - Summary and Subscriptions exports.

Integration updates

Webhooks / Push Notifications

🚧

May require integration updates

Due to new attributes in our subscription webhooks and APIs, enabling shipping addresses on your site may break your existing integration. Review the examples below to see the new changes.

When certain changes are made to a shipping address, we will issue a webhook notification. This will help you keep your other business systems, in sync with the data in Recurly. There are webhook notifications specific to shipping addresses, and we have added shipping address information to existing subscription webhook notifications.

Our subscription webhooks will now include additional attributes about usage-based add-ons. This may break your integration, so be sure to update it accordingly.

New webhook notifications are sent whenever:

• A new shipping address is created
• An existing shipping address is edited
• An existing shipping address is deleted

In addition, the subscription webhook notifications have been updated to include information about shipping addresses when applicable.

The subscription webhook notifications will include the following information about the shipping address:

• Address ID
• Nickname
• First name
• Last name
• Company name
• VAT number
• Street1
• Street2
• City
• State
• ZIP
• Country
• Email
• Phone

For more information, please refer to the Webhooks documentation.

Versioning

New attributes and resources for this feature are versioned on 2.4. Please use the header X-Api-Version: 2.4

Client libraries

If you use one of the Recurly client libraries, you will need to update your version. Let us know which one you are using so we can make sure we are prioritizing the right ones.

• Ruby version 2.7.2 - See https://github.com/recurly/recurly-client-ruby/pull/259
• Python version 2.4.1 - See https://github.com/recurly/recurly-client-python/pull/183 and https://github.com/recurly/recurly-client-python/pull/185
• PHP version 2.7.0 - https://github.com/recurly/recurly-client-php/pull/269
• .NET - https://github.com/recurly/recurly-client-net/pull/174

Recurly.js

Recurly.js has been updated to support shipping addresses so that you can use the pricing module to use shipping address to estimate the taxes correctly. If you need the Recurly.js pricing module to fully deploy shipping addresses, please let us know.

Recurly API

You can also use the Recurly API to manage your shipping addresses. There are API endpoints to create new shipping addresses, edit or delete shipping addresses, and associate shipping addresses with subscriptions. For complete information about the APIs, please refer to the Recurly Developer Documentation.

• Create account: You can pass in up to 20 account shipping addresses along with the request to create a new account. Just use the nested "shipping_address" object.
• List shipping addresses: allows merchants to list all existing shipping addresses for an existing account
• Show shipping address: allows merchants to retrieve the details about an existing shipping address for an existing account
• Create shipping address: allows merchants to create new shipping addresses for an existing account
• Update shipping address: allows merchants to edit an existing shipping address for an existing account
• Delete shipping address: allows merchants to delete an existing shipping address for an existing account
• Create shipping address on a subscription: allows merchants to create a new shipping address for, or associate an existing shipping address with, a new or existing subscription. Please note that you cannot update an existing shipping address with this API endpoint.
• Display shipping address on an invoice: allows merchants to view the shipping address as part of the invoice information
• Create shipping address on a subscription preview: allows merchants to preview creating a new shipping address for, or associate an existing shipping address with, a new subscription
• Create / update shipping address on a subscription update preview: allows merchants to preview creating a new shipping address for, or associate an existing shipping address with, a new subscription

Features that are not yet included in the Shipping Address

Amazon Pay

We plan on adding a feature to let you save the address that your customers enter during their Amazon Pay checkout flow to the Recurly shipping address fields.

Hosted Payment Page and Hosted Account Management Page

We do not currently have a way for your customers to use the Hosted Payment Page or the Hosted Account Management to manage their own shipping addresses. If you are interested in this feature, please let us know.