Recurly lets you record shipping costs and methods on subscriptions and one-time purchases, so shipping fees appear as recurring line items on invoices — complete with tax calculations and refund support. Configure your shipping methods once, then apply them across your billing workflows.

Available on all Recurly plans

1Definition 2Key details 3Configure shipping methods 4Add shipping to a subscription 5Add shipping to a one-time purchase

Site requirementsShipping fees require the Credit Invoices, Only Bill What Changed, and Subscription Billing Terms features to be enabled on your site. Recurly sites created after July 26, 2018 have these features enabled by default. Contact [email protected] if you need to enable them.

Definition

Shipping fees in Recurly let you record the cost and method of shipping on a subscription or one-time purchase. Unlike ecommerce, where shipping is a one-time charge per order, subscriptions are long-lived — Recurly handles recurring shipping fees automatically, billing the same shipping cost each renewal period alongside your subscription charges.

Key details

How shipping appears on invoices

Shipping appears as a line item on the invoice, always positioned after any subscription or one-time charges. Tax on the shipping fee (where applicable) is included in the tax estimate and reflected on the invoice.

Changing the shipping fee or method

If you change a shipping fee immediately (mid-cycle), Recurly issues a full refund for the original shipping amount and its tax, then generates a new charge invoice for the updated amount and its tax. To avoid generating multiple separate charge and credit invoices, make shipping fee changes at the next renewal rather than immediately.

Refunding shipping fees

When refunding an invoice that includes a shipping fee, you can either refund the full shipping amount or exclude the shipping fee from the refund. Partial shipping fee refunds are not supported. Any refund of a shipping fee also refunds the associated tax amount.

To refund shipping in the Admin Console, navigate to the invoice and select Invoice Actions → Refund Invoice.

Coupons and shipping fees

Coupons don't apply to shipping fees. To discount a shipping fee, pass the discounted amount directly in your API call or Admin Console entry for the subscription or one-time charge.

Exporting shipping data

Shipping information is available in the following exports:

Adjustments
Subscriptions
Subscriptions — Churned

Taxation on shipping fees

Shipping is taxable in some jurisdictions and not in others. Recurly works with Avalara and Vertex to handle shipping tax calculations.

If you use multiple shipping addresses on one invoice, the VAT number from the billing address is used. If you need VAT reverse charges applied, use only one shipping address per invoice.

Avalara tax codes

For merchants using Recurly's built-in Avalara integration, you can specify a tax code per shipping method. The following options are available:

Tax option	Use case
Common Carrier FOB Destination	A common carrier (e.g., USPS or FedEx) where title passes to the customer upon delivery.
Common Carrier FOB Origin	A common carrier where title passes to the customer when the item ships.
Non Common Carrier FOB Destination	A private delivery company where title passes to the customer upon delivery.
Non Common Carrier FOB Origin	A private delivery company where title passes to the customer when the item ships.
Delivery by Company Vehicle Before Passage of Title	Your own delivery vehicle and staff; you retain ownership of the goods until delivery.
Delivery by Company Vehicle After Passage of Title	Your own delivery vehicle and staff; title passes to the customer before delivery.
Non-Taxable	Shipping costs that are not subject to tax.

Merchants with their own Avalara or Vertex account can specify an exact tax code per shipping method for more precise compliance control.

International shipping and customs

Recurly computes sales tax on shipping fees for both domestic and international shipments. For international shipments, customs fees and duties are typically collected and remitted by your carrier. Recurly doesn't provide the ability to communicate customs fees or duties to customers — contact your shipping provider to discuss how to handle this in your workflow.

Configure shipping methods

Navigate to Configuration → Shipping to set up and manage shipping methods. Recurly creates a default shipping method automatically when you enable shipping.

If you use only one shipping method or don't display the method name to customers, no further configuration is needed. Configure additional methods if you use multiple carriers or want to show customers which method is used to ship their items.

Rename a shipping method

If you're changing shipping providers, rename the existing shipping method rather than deleting and recreating it. This ensures active subscriptions using that method are automatically migrated to the new name.

Delete a shipping method

Use caution when deleting shipping methodsActive subscriptions using a deleted shipping method will renew without any shipping method applied. Only delete a shipping method if it was created by mistake. This action cannot be undone and may result in data loss.

To delete a shipping method, click the three-dot menu to the right of the method and select Delete Shipping Method. You'll be prompted to type the method's name to confirm the deletion.

Add shipping to a subscription

Admin Console

Open the customer's account

Navigate to the account you want to add the subscription to, then select Account Actions → Create Subscription.

Enable shipping

Check Include Shipping and enter the shipping fee amount and shipping method.

Add a shipping address

Enter the shipping address manually, or copy it from an existing address on the account.

Add the subscription

Click Add Subscription. The shipping fee is added to the subscription cost on a recurring basis, and the tax estimate includes tax on the shipping fee.

API

Pass shipping_amount_in_cents and shipping_method_code on the subscription create or update call, along with a shipping_address block.

<subscription>
  <plan_code>gold</plan_code>
  <currency>USD</currency>
  <account>
    <account_code>34</account_code>
    <email>[email protected]</email>
    <first_name>Verena</first_name>
    <last_name>Example</last_name>
    <billing_info>
      <number>4111-1111-1111-1111</number>
      <month>12</month>
      <year>2019</year>
      <address1>123 Main St.</address1>
      <city>San Francisco</city>
      <state>CA</state>
      <zip>94105</zip>
      <country>US</country>
    </billing_info>
  </account>
  <shipping_address>
    <nickname>Work</nickname>
    <first_name>Verena</first_name>
    <last_name>Example</last_name>
    <company>Recurly Inc</company>
    <phone>555-222-1212</phone>
    <email>[email protected]</email>
    <address1>123 Main St.</address1>
    <address2>Suite 101</address2>
    <city>San Francisco</city>
    <state>CA</state>
    <zip>94105</zip>
    <country>US</country>
  </shipping_address>
  <shipping_amount_in_cents>10000</shipping_amount_in_cents>
  <shipping_method_code>foo</shipping_method_code>
  <renewal_billing_cycles>4</renewal_billing_cycles>
  <auto_renew>true</auto_renew>
</subscription>

You can also preview a subscription with shipping fees using the Subscription Preview endpoint:

<subscription>
  <plan_code>gold</plan_code>
  <currency>USD</currency>
  <account>
    <account_code>32</account_code>
    <email>[email protected]</email>
    <first_name>Verena</first_name>
    <last_name>Example</last_name>
    <billing_info>
      <number>4111-1111-1111-1111</number>
      <month>12</month>
      <year>2019</year>
      <address1>123 Main St.</address1>
      <city>San Francisco</city>
      <state>CA</state>
      <zip>94105</zip>
      <country>US</country>
    </billing_info>
  </account>
  <shipping_address>
    <nickname>Work</nickname>
    <first_name>Verena</first_name>
    <last_name>Example</last_name>
    <company>Recurly Inc</company>
    <phone>555-222-1212</phone>
    <email>[email protected]</email>
    <address1>123 Main St.</address1>
    <address2>Suite 101</address2>
    <city>San Francisco</city>
    <state>CA</state>
    <zip>94105</zip>
    <country>US</country>
  </shipping_address>
  <unit_amount_in_cents>10000</unit_amount_in_cents>
  <shipping_amount_in_cents>1299</shipping_amount_in_cents>
  <shipping_method_code>foo</shipping_method_code>
  <renewal_billing_cycles>4</renewal_billing_cycles>
  <auto_renew>true</auto_renew>
</subscription>

Add shipping to a one-time purchase

To charge a shipping fee on an invoice with only one-time purchases, use the /purchases endpoint (available from API v2.20 onwards). See the full Purchases API documentation for all available parameters.

<purchase>
  <account>
    <account_code>c442b36c-c64f-41d7-b8e1-9c04e7a6ff82</account_code>
  </account>
  <shipping_fees>
    <shipping_fee>
      <shipping_amount_in_cents>1000</shipping_amount_in_cents>
      <shipping_method_code>fedex-2-day</shipping_method_code>
      <shipping_address>
        ...
      </shipping_address>
    </shipping_fee>
  </shipping_fees>
  <adjustments>
    <adjustment>
      <product_code>foobar</product_code>
      <unit_amount_in_cents>1000</unit_amount_in_cents>
      <description>Thingy</description>
    </adjustment>
  </adjustments>
  <subscriptions>
    <subscription>
      <plan_code>plan1</plan_code>
    </subscription>
  </subscriptions>
</purchase>