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    

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

The Account Summary, which appears on the right of the Account Details page. It shows shipping addresses and provides a link to the "manage addresses" page where you can create, edit and delete shipping addresses.

The Account Summary, which appears on the right of the Account Details page. It shows shipping addresses and provides a link to the "manage addresses" page where you can create, edit and delete shipping addresses.

The Shipping Addresses page showing two shipping addresses, their associated subscriptions, the billing and account addresses, plus ways to create a new shipping address, or edit or delete one of the existing shipping addresses.

The Shipping Addresses page showing two shipping addresses, their associated subscriptions, the billing and account addresses, plus ways to create a new shipping address, or edit or delete one of the existing shipping addresses.

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

The New Subscription page showing the shipping address drop-down and the Summary section on the right which shows the estimated taxes based on the selected shipping address.

The New Subscription page showing the shipping address drop-down and the Summary section on the right which shows the estimated taxes based on the selected shipping address.

The Account Details page showing subscriptions, the shipping address associated with each subscription, and the estimated taxes which are based on the shipping address (when applicable).

The Account Details page showing subscriptions, the shipping address associated with each subscription, and the estimated taxes which are based on the shipping address (when applicable).

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:

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.

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.

Shipping Addresses


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.