Take a tour Sandbox Signup
Toggle Mobile Navigation
  • Content

Changelog

v2999-01-01

Warning: This is the experimental version and represents the edge of the API. It’s not meant to be used in production as we may push breaking changes here at any moment. Please choose a GA version from https://recurly.com/developers/api/index.html

Added support for custom fields on plans to the plans create, show, delete, index and update endpoints:

  • Changed POST /plans/{plan_id} PUT /plans/{plan_id} GET /plans GET /plans/{plan_id} DELETE /plans/{plan_id}
    • Added existing CustomField component to endpoints

Added support for custom fields on plans to the custom_field_definitions show and index endpoints:

  • Changed GET /custom_field_definitions GET /custom_field_definitions/{custom_field_definition_id}
    • Added plan to existing RelatedTypeEnum component

Added support for External Resource Tracking:

  • Added new endpoint GET /sites/{site_id}/external_subscriptions
  • Added new endpoint GET /sites/{site_id}/accounts/{account_id}/external_subscriptions
  • Added new endpoint GET /sites/{site_id}/external_subscriptions/{external_subscription_id}
  • Added new endpoint POST /sites/{site_id}/external_subscriptions
  • Added new endpoint GET /sites/:site_id/external_products
  • Added new endpoint GET /sites/{site_id}/external_products/{external_product_id}

Added support for ramp pricing on the subscription change and preview endpoints:

  • Changed POST /subscriptions/{subscription_id}/change and POST /sites/{site_id}/subscriptions/{subscription_id}/change
    • Added SubscriptionRampInterval and SubscriptionRampIntervalResponse component
  • Changed POST /subscriptions/uuid-{subscription_uuid}/change/preview and POST /sites/{site_id}/subscriptions/uuid-{subscription_uuid}/change/preview
    • Added SubscriptionRampInterval and SubscriptionRampIntervalResponse component

Added support for ramp pricing on the purchases create and preview endpoints:

  • Changed POST /purchases/ and POST /sites/{site_id}/purchases
    • Added SubscriptionRampInterval component
  • Changed POST /purchases/preview and POST /sites/{site_id}/purchases/preview
    • Added SubscriptionRampInterval component

Added support for new subscription change timeframe:

  • Changed SubscriptionChangeCreate timeframe enum options
    • Removed renewal
    • Added term_end

v2022-01-01

Warning: This is the candidate version and represents the next major version to be released. It’s not meant to be used in production as we may push breaking changes here at any moment. Please choose a GA version from https://recurly.com/developers/api/index.html

Added support for custom fields on plans to the plans create, show, delete, index and update endpoints:

  • Changed POST /plans/{plan_id} PUT /plans/{plan_id} GET /plans GET /plans/{plan_id} DELETE /plans/{plan_id}
    • Added existing CustomField component to endpoints

Added support for custom fields on plans to the custom_field_definitions show and index endpoints:

  • Changed GET /custom_field_definitions GET /custom_field_definitions/{custom_field_definition_id}
    • Added plan to existing RelatedTypeEnum component

Added support for ramp pricing on the Plans endpoints:

  • Changed GET /plans and GET /sites/{site_id}/plans/{plan_id}
    • Added PlanRampInterval component to the response
  • Changed GET /plans/{plan_id} GET /sites/{site_id}/plans/{plan_id}
    • Added PlanRampInterval component to the response

Added support for ramp pricing on the subscription change and preview endpoints:

  • Changed POST /subscriptions/{subscription_id}/change and POST /sites/{site_id}/subscriptions/{subscription_id}/change
    • Added SubscriptionRampInterval and SubscriptionRampIntervalResponse component
  • Changed POST /subscriptions/uuid-{subscription_uuid}/change/preview and POST /sites/{site_id}/subscriptions/uuid-{subscription_uuid}/change/preview
    • Added SubscriptionRampInterval and SubscriptionRampIntervalResponse component

Added support for ramp pricing on the purchases create and preview endpoints:

  • Changed POST /purchases/ and POST /sites/{site_id}/purchases
    • Added SubscriptionRampInterval component
  • Changed POST /purchases/preview and POST /sites/{site_id}/purchases/preview
    • Added SubscriptionRampInterval component
  • Changed POST /sites/{site_id}/plans/{plan_id}/add_ons
    • Changed the type of usage_percentage attribute from float to string
  • Changed PUT /sites/{site_id}/plans/{plan_id}/add_ons/{add_on_id}
    • Changed the type of usage_percentage attribute from float to string
  • Changed GET /sites/{site_id}/plans/{plan_id}/add_ons
    • Changed the type of usage_percentage attribute from float to string
  • Changed GET /sites/{site_id}/plans/{plan_id}/add_ons/{add_on_id}
    • Changed the type of usage_percentage attribute from float to string

v2021-02-25 - Current GA Version

Added support for custom fields on plans to the plans create, show, delete, index and update endpoints:

  • Changed POST /plans/{plan_id} PUT /plans/{plan_id} GET /plans GET /plans/{plan_id} DELETE /plans/{plan_id}
    • Added existingCustomField component to endpoints

Added support for custom fields on plans to the custom_field_definitions show and index endpoints:

  • Changed GET /custom_field_definitions GET /custom_field_definitions/{custom_field_definition_id}
    • Added plan to existing RelatedTypeEnum component

Added support for Entitlements

  • Added new endpoint GET accounts/{account_id}/entitlements

Invoice request format has changed:

  • Added dunning_events_count and final_dunning_event

Added verify_cvv endpoint to billing_info

  • Added POST /accounts/{account_id}/billing_info/verify_cvv

Added support for ramp pricing on the subscription change and preview endpoints:

  • Changed POST /subscriptions/{subscription_id}/change and POST /sites/{site_id}/subscriptions/{subscription_id}/change
    • Added SubscriptionRampInterval and SubscriptionRampIntervalResponse component
  • Changed POST /subscriptions/uuid-{subscription_uuid}/change/preview and POST /sites/{site_id}/subscriptions/uuid-{subscription_uuid}/change/preview
    • Added SubscriptionRampInterval and SubscriptionRampIntervalResponse component

Added support for ramp pricing on the purchases create and preview endpoints:

  • Changed POST /purchases/ and POST /sites/{site_id}/purchases
    • Added SubscriptionRampInterval component
  • Changed POST /purchases/preview and POST /sites/{site_id}/purchases/preview
    • Added SubscriptionRampInterval component

Added support to create BillingInfo with card_type

  • Added card_type to create BillingInfoCreate.

Support username on PaymentMethod

  • Added username to PaymentMethod.

Added support for usage_timeframe on usage add ons

  • Changed POST /sites/{site_id}/plans/{plan_id}/add_ons
    • Added usage_timeframe
  • Changed GET /sites/{site_id}/plans/{plan_id}/add_ons
    • Added usage_timeframe
  • Changed GET /sites/{site_id}/plans/{plan_id}/add_ons/{add_on_id}
    • Added usage_timeframe
  • Changed GET /subscriptions/{subscription_id}
    • Added subscription_add_on.usage_timeframe

Support Percentage Tiers on Subscription usage add ons

  • Changed POST /sites/{site_id}/subscriptions
    • Added percentage_tiers array
    • Added subscriptions.add_ons.percentage_tiers.usage_percentage
    • Added subscriptions.add_ons.percentage_tiers.ending_amount
    • Removed subscriptions.add_ons.tiers when add on has tiers with usage percentage.
  • Changed POST /sites/{site_id}/subscriptions/{subscription_id}/change and
  • Changed POST /sites/{site_id}/subscriptions/{subscription_id}/change/preview
    • Added percentage_tiers array
    • Added subscriptions.add_ons.percentage_tiers.usage_percentage
    • Added subscriptions.add_ons.percentage_tiers.ending_amount
    • Removed subscriptions.add_ons.tiers when add on has tiers with usage percentage.
  • Changed POST /sites/{site_id}/purchases
    • Added percentage_tiers array
    • Added subscriptions.add_ons.percentage_tiers.usage_percentage
    • Added subscriptions.add_ons.percentage_tiers.ending_amount
    • Removed subscriptions.add_ons.tiers when add on has tiers with usage percentage.
  • Changed POST /sites/{site_id}/purchases/preview
    • Added percentage_tiers array
    • Added subscriptions.add_ons.percentage_tiers.usage_percentage
    • Added subscriptions.add_ons.percentage_tiers.ending_amount
    • Removed subscriptions.add_ons.tiers when add on has tiers with usage percentage.

Support Percentage Tiers on usage

  • Changed GET /usage/{usage_id}
    • Removed usage_percentage attribute from tiers objects
    • Added percentage_tiers array
    • Changed to only have tiers array when regular tiered addons

Support Multicurrency Percentage Tiers on usage add ons

  • Changed GET /sites/{site_id}/plans/{plan_id}/add_ons and
  • Changed GET /sites/{site_id}/plans/{plan_id}/add_ons/{add_on_id}
  • Changed POST /sites/{site_id}/plans/{plan_id}/add_ons
  • Changed POST /sites/{site_id}/plans
  • Changed PUT /sites/{site_id}/plans/{plan_id}/add_ons/{add_on_id}
    • Added percentage_tiers array
      • Added percentage_tiers.currency
      • Added percentage_tiers.tiers array
        • Added percentage_tiers.tiers.ending_amount
        • Added percentage_tiers.tiers.usage_percentage
    • Remove tiers.usage_percentage

Support Percentage Tiers on subscription add ons

  • Changed GET /sites/{site_id}/subscriptions
  • Changed GET /sites/{site_id}/subscriptions/{subscription_id}/change
  • Changed GET /sites/{site_id}/subscriptions/{subscription_id}
  • Changed GET /sites/{site_id}/accounts/{account_id}/subscriptions
    • Removed usage_percentage attribute from tiers objects
    • Added percentage_tiers array to tiered_usage_percentage_add_ons
    • Changed to only have tiers array when regular tiered addons

Support Pending Purchases.

  • Added new endpoint POST /purchases/pending to create Pending Purchases.
  • Added field external_hpp_type to support Adyen HPP Payments.
  • Added 'adyen' as valid external_hpp_type.
  • Added field online_banking_payment_type to support Online Banking Payments.
  • Added ideal and sofort as valid online_banking_payment_type.

Support becs as a payment method type for non-credit card based billing info.

  • Added becs as a valid non-credit card payment method type.

SubscriptionCreate request format has changed:

  • Added gateway_code.

SubscriptionUpdate request format has changed:

  • Added gateway_code.

Subscription response format has changed:

  • Added gateway_code.

Added tax information to Subscription response

  • Added the fields tax, tax_info and total.

Updated the response for POST /subscriptions/{subscription_id}/change.

  • Responding with 204 No Content when the subscription has a pending change, and a change is submitted which matches the subscription as it currently exists.

Support Argentina tax identifiers

  • Added Argentine cuit tax identifier to billing_info.

Split Address schema

  • Removed first_name and last_name from Address schema, since not all endpoints accept these properties.
  • Created AddressWithName schema that includes first_name and last_name and extends the Address schema.

Updated the response for the generate_unique_coupon_codes endpoint.

  • Previous versions of the API would return a 201 Created response with a Location header containing a list_unique_coupon_codes endpoint.
  • The updated response contains a JSON payload with the query parameters to use for a list_unique_coupon_codes request.

Added support for invoice customization

  • AccountCreate request format
    • Added invoice_template_id
  • AccountUpdate request format
    • Added invoice_template_id
  • Added GET /invoice_templates
  • Added GET /invoice_templates/{invoice_template_id}
  • Added GET /invoice_templates/{invoice_template_id}/accounts

Added support for precision pricing on subscription changes:

  • SubscriptionChangeCreate format
    • Added add_ons.unit_amount_decimal
    • Added add_ons.tiers.unit_amount_decimal
  • SubscriptionChange response format
    • Added add_ons.unit_amount_decimal
    • Added add_ons.tiers.unit_amount_decimal

Added support for precision pricing on invoice line items

  • Changes LineItem response format
    • Added unit_amount_decimal

Added support for precision pricing on subscription add-ons:

  • SubscriptionAddOnCreate request format
    • Added unit_amount_decimal
  • SubscriptionAddOn response format
    • Added unit_amount_decimal

Added support for precision pricing on usage:

  • Changes Usage response format
    • Added unit_amount_decimal
    • Added tiers.unit_amount_decimal

Added support for tiered_usage_percentage add ons on Usage:

  • Changes Usage response format
    • Added tiers.usage_percentage
    • Added tiers.ending_quantity

Added support for precision pricing on plan add-ons:

  • PlanCreate request:
    • Added add_ons.currencies.unit_amount_decimal
    • Added add_ons.tiers.currencies.unit_amount_decimal
  • AddOnCreate request:
    • Added currencies.unit_amount_decimal
    • Added tiers.currencies.unit_amount_decimal
  • AddOnUpdate request:
    • Added currencies.unit_amount_decimal
    • Added tiers.currencies.unit_amount_decimal
  • AddOn response format updates:
    • Added currencies.unit_amount_decimal
    • Added tiers.currencies.unit_amount_decimal

Updated the Invoice schema to no longer return a page of LineItems.

  • The line_items in the response now contains an array of the first 200 line items associated with the invoice.
  • The has_more_line_items boolean flag has been added to indicate if there are more LineItems that can be requested using the list_invoice_line_items endpoint.

Updated the Coupon schema to accommodate scenarios where a UniqueCouponCode is being returned. Previously, the UniqueCouponCode data would be merged into the Coupon data.

  • Added unique_coupon_code to replace the merged UniqueCouponCode data.
  • Removed redeemed_at which was added in v2019-10-10 for when a UniqueCouponCode’s data was being merged with the Coupon.

Changed the SubscriptionChangeCreate functionality:

  • If the add_ons parameter is omitted your existing add-ons will be maintained. In previous versions, omitting this parameter would remove the existing add-ons for a subscription.

Moving all enum types to the schemas section for the purpose of code generation.

Added support for creating, updating and deleting Shipping Methods:

  • Added POST /sites/{site_id}/shipping_methods
  • Added PUT /sites/{site_id}/shipping_methods/{shipping_method_id}
  • Added DELETE /sites/{site_id}/shipping_methods/{shipping_method_id}
  • Fixed the parameter name in GET /sites/{site_id}/shipping_methods/{shipping_method_id} which was previously {id} (Breaking change)

Stricter validation of limit query parameter: In previous versions, the API will quietly truncate the value to MIN or MAX for you. Now, sending a limit greater than the MAX value (200) will result in a validation exception. And sending a limit less than the MIN value (1) will result in a validation exception.

  • Changed the operation preview_subscription_change:
    • Changed the response object property from subscription_change_preview to subscription_change (the same as the response for create_subscription_change)

Added support for multiple active coupon redemptions

  • Changed GET /sites/{site_id}/accounts/{account_id}/coupon_redemptions/active
    • Now responds with CouponRedemptionList

Changed POST /sites/{site_id}/coupons:

  • Now enforce discount_type enum, limiting values to fixed, percentage, or free_trial
  • Now limit discount_percent, free_trial_unit, free_trial_amount, and currencies to matching discount types

Removed plans_names from coupon responses:

  • Changed /sites/{site_id}/coupons
  • Changed /sites/{site_id}/coupons/{coupon_id}
  • Changed /sites/{site_id}/accounts/{account_id}/coupon_redemptions
  • Changed /sites/{site_id}/accounts/{account_id}/coupon_redemptions/active

Added support for redeeming multiple coupons on a subscription

  • Changed POST /sites/{site_id}/subscriptions
  • Now accepts coupon_codes (plural) and not coupon_code (singular)

Added support for state filtering on coupon redemptions endpoint

  • Added state filter to GET /sites/{site_id}/accounts/{account_id}/coupon_redemptions

Added support for pricing tiers for usage percentage type add ons

  • Changed POST /sites/{site_id}/plans/{plan_id}/add_ons
    • Added tiers.usage_percentage
    • Made tiers.currencies no longer a required attribute
  • Changed PUT /sites/{site_id}/plans/{plan_id}/add_ons/{add_on_id}
    • Added tiers.usage_percentage
    • Made tiers.currencies no longer a required attribute
  • Changed GET /sites/{site_id}/plans/{plan_id}/add_ons
    • Added tiers.usage_percentage
  • Changed GET /sites/{site_id}/plans/{plan_id}/add_ons/{add_on_id}
    • Added tiers.usage_percentage

Added support for subscriptions add-ons pricing tiers for usage percentage type add ons

  • Changed POST /sites/{site_id}/subscriptions
    • Added add_ons.tiers.usage_percentage
  • Changed GET /sites/{site_id}/subscriptions
    • Added add_ons.tiers.usage_percentage
  • Changed GET /sites/{site_id}/subscriptions/{subscription_id}
    • Added add_ons.tiers.usage_percentage
  • Changed POST /sites/{site_id}/purchases
    • Added subscriptions.add_ons.tiers.usage_percentage
  • Changed POST /sites/{site_id}/purchases/preview
    • Added subscriptions.add_ons.tiers.usage_percentage

Added invoice templates to account responses

  • Changed GET /accounts
    • Added invoice_template
  • Changed GET /accounts/{account_id}
    • Added invoice_template
  • Changed GET /accounts/{account_id}/accounts
    • Added invoice_template

v2019-10-10

Added support for custom fields on plans to the plans create, show, delete, index and update endpoints:

  • Changed POST /plans/{plan_id} PUT /plans/{plan_id} GET /plans GET /plans/{plan_id} DELETE /plans/{plan_id}
    • Added existing CustomField component to endpoints

Added support for custom fields on plans to the custom_field_definitions, show and index endpoints:

  • Changed GET /custom_field_definitions GET /custom_field_definitions/{custom_field_definition_id}
    • Added plan to the related_type param

Added support for the Decimal Quantity feature to LineItem when the Decimal Quantity feature is enabled:

  • Changed LineItem response format:
    • Added quantity_decimal
    • Added refunded_quantity_decimal
  • Changed LineItemRefund request format:
    • Added quantity_decimal
  • Changed UsageCreate request:
    • Allow up to nine decimal places for amount field

Added support for ramp pricing on the subscription change and preview endpoints:

  • Changed POST /subscriptions/{subscription_id}/change and POST /sites/{site_id}/subscriptions/{subscription_id}/change
    • Added SubscriptionRampInterval and SubscriptionRampIntervalResponse component
  • Changed POST /subscriptions/uuid-{subscription_uuid}/change/preview and POST /sites/{site_id}/subscriptions/uuid-{subscription_uuid}/change/preview
    • Added SubscriptionRampInterval and SubscriptionRampIntervalResponse component

Added support for ramp pricing on the purchases create and preview endpoints:

  • Changed POST /purchases/ and POST /sites/{site_id}/purchases
    • Added SubscriptionRampInterval component
  • Changed POST /purchases/preview and POST /sites/{site_id}/purchases/preview
    • Added SubscriptionRampInterval component

AccountBalanceAmount response format has changed:

  • Added processing_prepayment_amount.

Subscription response format has changed:

  • Added active_invoice_id.

Support becs as a payment method type for non-credit card based billing info.

  • Added becs as a valid non-credit card payment method type.

Support Argentina credit card Tarjeta Naranja for Worldpay

  • Added Tarjeta Naranja enum card_type to payment_method.

Added support for dunning campaigns

  • Changes PlanCreate request format:
    • Added dunning_campaign_id
  • Changes PlanUpdate request format:
    • Added dunning_campaign_id
  • Changes Plan response format:
    • Added dunning_campaign_id
  • Changes AccountUpdate request format:
    • Added dunning_campaign_id
  • Changes AccountResponse response format:
    • Added dunning_campaign_id
  • Changes AccountMini response format:
    • Added dunning_campaign_id
  • Changes Invoice response format:
    • Added dunning_campaign_id

Added support for seeing renewal preview invoices in the API

  • Added GET /sites/{site_id}/subscriptions/{subscription_id}/preview_renewal

Added new Dunning Campaigns endpoints:

  • Added GET /sites/:site_id/dunning_campaigns endpoint.
  • Added GET /sites/:site_id/dunning_campaigns/:id endpoint.

  • Added PUT /sites/:site_id/dunning_campaigns/:id/bulk_update endpoint.

  • Changes TaxInfo response format:
    • Added the tax_details array that is populated for Canadian taxes when a site has an Avalara direct or in-the-box taxes or Vertex integration:
      • tax_details.type is the tax type
      • tax_details.region is the tax region
      • tax_details.rate is the tax rate
      • tax_details.taxis the total amount charged for this tax type

Added support for backup_payment_method:

  • Changes BillingInfoCreate request format:
    • Added backup_payment_method
  • Changes BillingInfo response format:
    • Added backup_payment_method
  • Changes Transactions
    • Added backup_payment_method_used

Added support for subscription cancel timeframe options:

  • Changes SubscriptionCancel request format
    • Added timeframe

Added support for managing Measured Units via /sites/{site_id}/measured_units.

Added support for verifying an Account’s credit card Billing Info /sites/{site_id}/accounts/{account_id}/billing_info/verify

Added support for usage in plan add-on creation:

  • PlanCreate request:
    • Added add_ons.add_on_type
    • Added add_ons.usage_type
    • Added add_ons.usage_percentage
    • Added add_ons.measured_unit_id
    • Added add_ons.measured_unit_name
  • AddOnCreate request:
    • Added add_on_type
    • Added usage_type
    • Added usage_percentage
    • Added measured_unit_id
    • Added measured_unit_name
  • AddOn response format updates:
    • Added add_on_type
    • Added usage_type
    • Added usage_percentage
    • Added measured_unit_id

Added support for usage in subscription add-on creation:

  • SubscriptionAddOnCreate request format
    • Added usage_percentage
  • SubscriptionAddOn response format
    • Added add_on.add_on_type
    • Added add_on.usage_type
    • Added add_on.measured_unit_id
    • Added usage_percentage

Added support for zeroing out usage on subscription termination

  • Changes delete subscription query parameters
    • Added charge

Added support for wallet:

  • Added GET sites/{site_id}/accounts/{account_id}/billing_infos
  • Added GET sites/{site_id}/accounts/{account_id}/billing_infos/{billing_info_id}
  • Added POST /sites/:site_id/accounts/billing_infos.
  • Added DELETE sites/{site_id}/accounts/{account_id}/billing_infos/{billing_info_id}
  • Added PUT sites/{site_id}/accounts/{account_id}/billing_infos/{billing_info_id}
  • Billing Info response format changed:
    • Added primary_payment_method.
  • Changed PurchaseCreate request format:
    • Added account.billing_info_id.
  • Changed PurchaseCreate response format:
    • Added billing_info_id.
  • Changed PurchasePreview request format:
    • Added account.billing_info_id.
  • Changed PurchasePreview response format:
    • Added billing_info_id.
  • Changed SubscriptionUpdate request format:
    • Added billing_info_id.
  • Changed InvoiceCollect request format:
    • Added billing_info_id.
  • Changed Subscription response format:
    • Added billing_info_id.
  • Changed Invoice response format:
    • Added billing_info_id.
  • Changed SubscriptionCreate request format:
    • Added account.billing_info_id
  • Changed SubscriptionCreate response format:
    • Added billing_info_id

Added bulk_coupon_id and bulk_coupon_code to the UniqueCouponCode to provide a reference to the parent bulk Coupon that the UniqueCouponCode was generated for.

Added POST /sites/{site_id}/subscriptions/{subscription_id}/change/preview to preview a subscription change.

Added support for allowing any item on a subscription:

  • PlanCreate and PlanUpdate request formats have changed when the Add Items on Subscriptions feature is enabled:
    • Added allow_any_item_on_subscriptions
  • Plan response format has changed:
    • Added allow_any_item_on_subscriptions
  • SubscriptionCreate request format has changed when the Add Items on Subscriptions feature is enabled:
    • Added subscription_add_ons[].add_on_source.
  • SubscriptionAddOn response format has changed:
    • Added add_on_source.
  • SubscriptionChangeCreate request format has changed when the Add Items on Subscriptions feature is enabled:
    • Added subscription_add_ons[].add_on_source.

Added DELETE /sites/{site_id}/coupons/{coupon_id} to expire a Coupon.

Added field to Coupon response to facilitate returning Bulk Coupon information in a get_coupon response.

  • redeemed_at added to Coupon

Added support for item-backed AddOns:

  • PlanCreate request:
    • Added add_ons.item_code, when the Catalog: Item Add-Ons feature is enabled
    • Added add_ons.item_id, when the Catalog: Item Add-Ons feature is enabled
    • The following parameters are no longer acceptable if item_code/item_id is present:
      • add_ons.code
      • add_ons.name
      • add_ons.accounting_code
      • add_ons.tax_code
      • add_ons.revenue_schedule_type
  • AddOnCreate request:
    • Added item_code, when the Catalog: Item Add-Ons feature is enabled
    • Added item_id, when the Catalog: Item Add-Ons feature is enabled
    • The following parameters are no longer acceptable if item_code/item_id is present:
      • code
      • name
      • accounting_code
      • tax_code
      • revenue_schedule_type
  • AddOnUpdate request:
    • The following parameters are no longer acceptable if an AddOn is item-backed:
      • name
      • accounting_code
      • tax_code
      • revenue_schedule_type
  • AddOn response format updates:
    • Added item:
      • Added item.id
      • Added item.object
      • Added item.state
      • Added item.name
      • Added item.description
    • Added external_sku
  • Subscription response format updates:
    • Added add_ons.add_on.item_id
    • Added add_ons.add_on.external_sku

Support for optional in AddOn

  • AddOn response format:
    • Added optional

Create convert trial endpoint for immediately converting trial subscription to fully active

  • Added PUT /sites/:site_id/subscriptions/:id/convert_trial.

Support gateway_token and gateway_code for Billing Infos

  • BillingInfoCreate request format:
    • Added gateway_token
    • Added gateway_code
  • PaymentMethod response format:
    • Added gateway_token
    • Added gateway_code

Adding fields to the Account schema to view Subscription and Invoice statuses without making multiple requests:

  • Subscription status fields:
    • has_live_subscription
    • has_active_subscription
    • has_future_subscription
    • has_canceled_subscription
    • has_paused_subscription
  • Invoice status fields:
    • has_past_due_invoice

Support external_gift_card origins for Line Items

  • Changed LineItemCreate request format:
    • Added origin.

Starting to add support for .pdf routes

  • Added GET /sites/:site_id/invoices/{invoice_id}.pdf.
  • Added BinaryFile schema

Improving the ability to work with Custom Field Definitions.

  • Added a related_type filter to the listing end point.

Added support for the Revenue Recognition feature to LineItem, when the Revenue Recognition feature is enabled

  • Changed LineItemCreate request format:
    • Added revenue_schedule_type.
  • LineItem response format:
    • Added revenue_schedule_type.

Added support for the Revenue Recognition feature to Purchase, when the Revenue Recognition feature is enabled

  • Changed PurchaseCreate request format:
    • Added line_items.revenue_schedule_type.
    • Added subscriptions.revenue_schedule_type.
    • Added subscriptions.add_ons.revenue_schedule_type.
  • Changed Purchase response format:
    • Added line_items.revenue_schedule_type.

Added support for the Revenue Recognition feature to Plan, when the Revenue Recognition feature is enabled

  • Changed PlanCreate request format:
    • Added revenue_schedule_type.
    • Added setup_fee_revenue_schedule_type.
  • Changed PlanUpdate request format:
    • Added revenue_schedule_type.
    • Added setup_fee_revenue_schedule_type.
  • Plan response format:
    • Added revenue_schedule_type.
    • Added setup_fee_revenue_schedule_type.

Added support for the Revenue Recognition feature to Subscription, when the Revenue Recognition feature is enabled

  • Changed SubscriptionCreate request format:
    • Added revenue_schedule_type.
    • Added add_ons.revenue_schedule_type.
  • Changed SubscriptionUpdate request format:
    • Added revenue_schedule_type.
    • Added add_ons.revenue_schedule_type.
  • Subscription response format:
    • Added revenue_schedule_type.
    • Added add_ons.revenue_schedule_type.

Added support for the Revenue Recognition feature to SubscriptionChange, when the Revenue Recognition feature is enabled

  • Changed SubscriptionChangeCreate request format:
    • Added revenue_schedule_type.
    • Added add_ons.revenue_schedule_type.
  • Changed SubscriptionChangeUpdate request format:
    • Added revenue_schedule_type.
    • Added add_ons.revenue_schedule_type.
  • SubscriptionChange response format:
    • Added revenue_schedule_type.
    • Added add_ons.revenue_schedule_type.

Added support for the Revenue Recognition feature to AddOn, when the Revenue Recognition feature is enabled

  • Changed AddOnCreate request format:
    • Added revenue_schedule_type.
  • Changed AddOnUpdate request format:
    • Added revenue_schedule_type.
  • AddOn response format:
    • Added revenue_schedule_type.

Added support for Items, when the Credit Invoices and Subscription Billing Terms features are enabled:

  • Added GET /sites/:site_id/items.
  • Added POST /sites/:site_id/items.
  • Added GET /sites/:site_id/items/:id.
  • Added PUT /sites/:site_id/items/:id.
  • Added PUT /sites/:site_id/items/:id/reactivate.
  • Added DELETE /sites/:site_id/items/:id.

Added support for Item to LineItem, when the Credit Invoices and Subscription Billing Terms features are enabled

  • LineItem request format updates
    • Added item_code.
    • Added item_id.
    • The following parameters are no longer acceptable if item_code/item_id is present
      • product_code
      • accounting_code
      • tax_exempt
      • tax_code
      • description
    • The following parameters can be passed in if item_code/item_id are present, to override the values on the referenced Item.
      • currency - if there are multiple currencies defined on the site. The site’s default will be used otherwise.
      • unit_amount - can be used to override the default unit_amount on the Item.
      • revenue_schedule_type - can be used to override the default revenue_schedule_type on the Item.
  • LineItem response format updates
    • Added item_code.
    • Added item_id.
    • Added external_sku.
    • product_code will be populated with item_code of the Item when an item_code or item_id is passed in the request.

Added support for Items in Purchases, when the Credit Invoices and Subscription Billing Terms features are enabled

  • Changed PurchaseCreate request format:
    • Added line_items.item_code/line_items.item_id.
    • The following parameters are no longer acceptable if line_items.item_code/line_items.item_id is present
      • line_items.product_code
      • line_items.accounting_code
      • line_items.tax_exempt
      • line_items.tax_code
      • line_items.description
    • If line_items.item_code/line_items.item_id is present, the following parameters can be passed in to override the values on the referenced Item:
      • line_items.currency - if there are multiple currencies defined on the site. The site’s default will be used otherwise.
      • line_items.unit_amount - can be used to override the default unit_amount on the Item.
      • line_items.revenue_schedule_type - can be used to override the default revenue_schedule_type on the Item.
    • Changed Purchase response format:
      • Added line_items.item_code.
      • Added line_items.item_id.
      • Added line_items.external_sku.
      • line_items.product_code will be populated with the item_code of the Item when an item_code or item_id is passed in the request.

Starting to improve support for shipping:

  • Added GET /sites/:site_id/shipping_methods/.
  • Added GET /sites/:site_id/shipping_methods/:id/. Note: this parameter name does not follow the standard and will be renamed to shipping_method_id in 2025-02-25.
  • Changes Invoice and LineItem response formats:
    • Added shipping_address.
  • Changes PurchaseCreate request format:
    • Added shipping.fees.
    • Removed shipping_address. Use shipping.address instead.
    • Removed shipping_address_id. Use shipping.address_id instead.
  • Changes Subscription request format:
    • Added shipping.address, shipping.address_id, shipping.method_id, shipping.method_code, and shipping.amount.
    • Removed shipping_address. Use shipping.address instead.
    • Removed shipping_address_id. Use shipping.address_id instead.
  • Changes SubscriptionUpdate request format:
    • Added shipping.address and shipping.address_id.
    • Removed shipping_address. Use shipping.address instead.
    • Removed shipping_address_id. Use shipping.address_id instead.
  • Changes Subscription response format:
    • Added shipping.address, shipping.method, and shipping.amount.
    • Removed shipping_address. Use shipping.address instead.
  • Changes SubscriptionChange request format:
    • Added plan_id.
    • Added shipping.amount, shipping.method_id, and shipping.method_code.
  • Changes SubscriptionChange response format:
    • Added shipping.address, shipping.method, shipping.amount.

Allow specifying when subscription cancellation takes effect:

  • Changes SubscriptionCancel request format:
    • Added new body parameter timeframe.

Accept bill_date and term_end timeframe options in subscription change requests:

  • Changes SubscriptionChangeCreate request format:
    • Changed timeframe to accept bill_date and term_end in addition to now.

A breaking change on the Coupon object:

  • Changed Coupon
    • Changed plans to now be nil instead of "all" in the case where applies_to_all_plans is true.

Fixes an inconsistency in the handling of tax codes for EU VAT merchants. Now the values passed in when assigning a tax_code will be reflected in the output and match the previously documented behavior:

  • Changes AddOn, LineItem and Plan response formats:
    • Changed tax_code values to return physical and digital and match the input values.

A breaking change with bank account info

  • Changes Transaction response format:
    • Changed object value from “ach” to “bank_account_info” for all bank account payment methods.

Allow searching for accounts by their email address:

  • Added email as a filter to the account listing operations (list_accounts and list_child_accounts).

Support PSD2 checks and specifying Mail Order & Telephone Order transactions:

  • Changes SubscriptionCreate request format:
    • Added transaction_type.
  • Changes SubscriptionChangeCreate request format:
    • Added transaction_type.
  • Changes InvoiceCollect request format:
    • Added three_d_secure_action_result_token_id.
    • Added transaction_type.
  • Changes AccountCreate request format:
    • Added transaction_type.
  • Changes AccountUpdate request format:
    • Added transaction_type.
  • Changes PurchaseCreate request format:
    • Added transaction_type.
  • Changes BillingInfoCreate request format:
    • Added transaction_type.
    • Added three_d_secure_action_result_token_id.
  • Changes the TransactionError response format:
    • Added three_d_secure_action_token_id to indicate an SCA flow is required to complete the transaction.

Support IBAN bank account fields

  • Changes BillingInfo response format:
    • Added last_two for IBAN bank account types.
  • Changes BillingInfoCreate request format: * Added iban

  • Changes PaymentMethod response format: * Added mandate_reference to indicate if a mandate exists for a payment method

  • Changes to Plan request and responses:
    • Added trial_requires_billing_info to plan responses
    • Added trial_requires_billing_info to plan create and update requests

Added state filter to Sites listing

  • Changed Transaction response:
    • Added updated_at property

Added support for the Avalara for Communications feature to Item, when the site has an AFC integration

  • Changed ItemCreate request format:
    • Added optional avalara_transaction_type.
    • Added optional avalara_service_type.
  • Changed ItemUpdate request format:
    • Added optional avalara_transaction_type.
    • Added optional avalara_service_type.
  • Item response format:
    • Added avalara_transaction_type.
    • Added avalara_service_type.

Added support for the Avalara for Communications feature to Plan, when the site has an AFC integration

  • Changed PlanCreate request format:
    • Added optional avalara_transaction_type.
    • Added optional avalara_service_type.
  • Changed PlanUpdate request format:
    • Added optional avalara_transaction_type.
    • Added optional avalara_service_type.
  • Plan response format:
    • Added avalara_transaction_type.
    • Added avalara_service_type.

Added support for the Avalara for Communications in add-on creation/updates, when the site has an AFC integration

  • Changed PlanCreate request format:
    • Added optional add_ons.avalara_transaction_type.
    • Added optional add_ons.avalara_service_type.
  • Changed AddOnCreate request format:
    • Added optional avalara_transaction_type.
    • Added optional avalara_service_type.
  • AddOn response format:
    • Added avalara_transaction_type.
    • Added avalara_service_type. * Added support for the Avalara for Communications feature to Line Items, when the site has an AFC integration
  • Changed LineItemCreate request format:
    • Added optional avalara_transaction_type.
    • Added optional avalara_service_type.
  • LineItem response format:
    • Added avalara_transaction_type.
    • Added avalara_service_type.

Added automated exports API:

  • Added GET /sites/:site_id/export_dates endpoint.
  • Added GET /sites/:site_id/export_dates/export_date/export_files endpoint.

Added support for account hierarchy on invoice line items

  • Changes LineItem response format
    • Added bill_for_account_id

v2018-08-09

Added support for Purchases

  • Added POST /sites/:site_id/purchases
  • Added POST /sites/:site_id/purchases/preview

For merchants using the Vertex tax provider:

  • Changed Account request and response format:
    • Added exemption_certificate.

Listing Transactions

  • Added authorization, capture, payment and verify as options for the type filter.

Account objects have the new bill_to attribute to indicate billing behavior:

  • Added bill_to to Account object requests and responses.
  • Added bill_to and parent_account_id to AccountMini objects.

SubscriptionChange request format has changed:

  • Added plan_id.

There is now an endpoint to fetch coupon redemptions on a subscription. Redemptions are still be embedded on the subscription as well.

  • Added GET /sites/{site_id}/subscriptions/{subscription_id}/coupon_redemptions.

Site responses now have their Public API Key available:

  • Added public_api_key.

  • Changes Account object on Account Acquisition, Balance, Coupon Redemption, Credit Payment, Invoice, Line Item, Transaction, and Subscription response formats:

    • Added company.

Invoices can now be edited:

  • Added PUT /sites/:site_id/invoices/:id
  • Changed Invoice response format:
    • Added name_on_account, first_name, last_name, and company to an invoice’s address.

SubscriptionAddOns on the SubscriptionChange can now be referenced by id. Sending only the id keeps the add-on and does not change any fields.

  • Changes SubscriptionChange create request format:
    • Added subscription_add_ons[].id.

Accounts have the ability to be linked via a parent-child relationship:

  • There is now an endpoint to list child accounts:
    • Added GET /sites/{site_id}/accounts/{account_id}/accounts
  • Changed Account request format:
    • Added parent_account_code.
    • Added parent_account_id.
  • Changed Account response format:
    • Added parent_account_id.

A product code can now be set when creating line items:

  • Changed LineItemCreate request format:
    • Added product_code.

v2018-06-06

Plans and Subscriptions have now changed to support the transition to subscription terms.

  • Changes Subscription create request format:
    • Added auto_renew.
    • Added renewal_billing_cycles.
    • Added next_bill_date.
    • Removed first_renewal_date. Use next_bill_date instead.
  • Changed Subscription update request format:
    • Added next_bill_date.
    • Removed next_renewal_at. Use next_bill_date instead.
  • Changes Subscription response format:
    • Added auto_renew.
    • Added renewal_billing_cycles.
    • Added current_term_started_at.
    • Added current_term_ends_at.
    • Added total_billing_cycles.
  • Changed Plan POST and GET request and response format:
    • Added auto_renew.
  • Changed Plan PUT request:
    • interval_unit and interval_length can no longer be updated.

Accounts and Subscriptions can now have custom fields:

  • Changed Account request and response format:
    • Added custom_fields.
  • Changed Subscription request and response format:
    • Added custom_fields.

The Custom Field Definitions can now be read via the API:

  • Added GET /sites/{site_id}/custom_field_definitions
  • Added GET /sites/{site_id}/custom_field_definitions/{custom_field_definition_id}

v2018-05-10

Subscriptions can now be paused and resumed:

  • Added PUT /sites/{site_id}/subscriptions/{subscription_id}/pause
  • Added PUT /sites/{site_id}/subscriptions/{subscription_id}/resume
  • Changed Subscription response formats:
    • Added paused_at. This is the date the subscription was paused.
    • Added remaining_pause_cycles. The number of billing cycles remaining for a paused subscription.

v2018-01-24

  • Changed Line Item response format:
    • Added tax_info hash. Includes type, region, and rate. We recommend using this over invoice level tax_info since different line items may be shipped to different addresses and have different taxes applied.
  • Changed Site response format:
    • Added features array. Allows you to see if credit memos and other features are enabled on a site.
  • Changed Account request and response formats:
    • Added preferred_locale.
  • Changed Invoice response format:
    • Added balance.
    • Removed due.
  • Changed Credit Payment response format:
    • Added original_credit_payment.
    • Added refund_transaction.
  • Changed Transaction response format:
    • Added voided_by_invoice.
  • Changed Line Item response format:
    • Added original_line_item_invoice_id (reverting change in v2017-09-30).

v2017-09-30

Accounts

Changed Account Address request format:

  • Validates address fields for length.
  • When postal_code is present it must be a valid postal code for the country.

Invoices

We’ve made many changes to Invoices to support the Credit Memos feature. Invoices created prior to the feature being enabled are considered legacy invoices.

The contents of the type in previous versions have moved to the origin field. The new type field indicates if the invoice is a charge, credit or legacy invoice.

Credit and charge invoices will only have line items of a single type so the line_items format has changed from an object to a simple array. The old object keys have moved into the line items’s legacy_category field.

Changed Create and Preview Invoice request format:

  • Added charge_customer_notes.
  • Added credit_customer_notes.
  • Removed customer_notes. Use charge_customer_notes instead.

Changed Create and Preview Invoice response format:

  • Changed invoice from a single object to an invoice_collection object with a charge_invoice and array of credit_invoices. You’ll need to prefix any existing references to the response object with charge_invoice..

Changed Invoice response format:

  • Previous type field is now origin.
  • Added a new type field to support upcoming credit invoices. Existing invoices are type=legacy.
  • Changed line_items from an object with multiple arrays to a single array. Object keys have moved into the legacy_category field of the line items for invoices with type=legacy.
  • Added refundable_amount.
  • Added credit_payments.
  • Added subscription_ids.
  • Removed subscription_id. Use subscription_ids[0] instead.

Changed InvoiceRefund request format:

  • Added external_refund object for refunds settled outside Recurly.
  • Added credit_customer_notes.
  • Added all_credit and all_transaction to the refund_method enum’s options.

Listing Invoices

  • Added type filter to Invoice listing.
  • Added GET /sites/{site_id}/invoices/{invoice_id}/related_invoices
  • Added POST /sites/{site_id}/invoices/{invoice_id}/refund

Credit invoices can be voided with the void_invoice endpoint:

  • Added PUT /sites/{site_id}/invoices/{invoice_id}/void.

Line Items

Changed Line Item request format:

  • Added credit_reason_code.
  • Changed the type to now be required.

Changed Line Item response format:

  • Added legacy_category.
  • Added credit_reason_code.
  • Added proration_rate.
  • Removed original_line_item_id.
  • Removed original_line_item_invoice_id. (change reverted)

Credit Payments

Added CreditPayment object to model credit invoices being applied to a charge invoice.

There are new endpoints to fetch credit payments:

  • GET /sites/{site_id}/credit_payments
  • GET /sites/{site_id}/accounts/{account_id}/credit_payments
  • GET /sites/{site_id}/credit_payments/{credit_payment_id}

Transactions

One transaction can now pay for multiple subscriptions.

Changed Transaction response format:

  • Added id and type to the nested invoice object.
  • Removed invoice_id. Use invoice.id instead.
  • Added subscription_ids.
  • Removed subscription_id. Use subscription_ids[0] instead.
  • Added collection_method.
  • Added more supported values for payment_method.

Subscriptions

Changed Subscription create request format:

  • Added credit_customer_notes.

Miscellaneous

Changed Address and Shipping Address request formats:

  • When country is present it must be a valid 2 letter ISO 3166 country code.

Removed BooleanResponse – The following end points now return 204 with no content instead of 200 with BooleanResponse:

  • DELETE /sites/{site_id}/accounts/{account_id}/billing_info
  • DELETE /sites/{site_id}/accounts/{account_id}/shipping_addresses/{shipping_address_id}
  • DELETE /sites/{site_id}/subscriptions/{subscription_id}/change
  • DELETE /sites/{site_id}/line_items/{id}

v2017-01-12

  • Added new ids pagination parameter.
  • Changed Site response format:
    • Added settings.
  • Changed Account response format:
    • Billing info is no longer wrapped in an array.
  • Changed allowed parameters on POST /sites/{site_id}/accounts:
    • Added shipping_addresses.
  • Changed allowed parameters on POST /sites/{site_id}/subscriptions:
    • Added shipping_address.
    • Added shipping_address_id.
  • Changed allowed parameters on PUT /sites/{site_id}/subscriptions/{subscription_id}:
    • Added shipping_address.
    • Added shipping_address_id.
  • Changed Coupon request format:
    • Removed description, use hosted_description instead.
  • Changed Subscription response format:
    • Added expiration_reason.

v2016-12-15

  • Changed pagination parameters:
    • Added begin_time.
    • Added end_time.
    • Removed date.
    • Removed seen_id parameter.
    • Removed id value for the sort parameter; use created_at instead.
    • Changed default value of the sort parameter to created_at.
  • Changed parameters on POST /sites/{site_id}/subscriptions:
    • Added total_billing_cycles.
    • Removed billing_cycles.
  • Changed parameters on PUT /sites/{site_id}/subscriptions/{subscription_id}:
    • Added remaining_billing_cycles.
    • Removed billing_cycles.
  • Changed parameters on PUT /sites/{site_id}/accounts/{account_id}/billing_info:
    • Added currency.
  • Changed Unique Coupon Code response format:
    • Added updated_at.
  • Changed Shipping Address response format:
    • Added created_at.
    • Added updated_at.
  • Changed Account response format:
    • Added shipping_addresses.
  • Changed Subscription response format:
    • Added shipping_address.
  • Changed Line Item response format:
    • Added credit_applied.
    • Added original_line_item_invoice_id.
    • Added subtotal.
  • Changed Subscription response format:
    • Added remaining_billing_cycles.

v2016-07-27

  • Changed Line Item response format:
    • Added uuid.
  • Changed Coupon response format:
    • Added unique_code_template.
    • Removed currencies list.
    • Changed format of discount object.
  • Added PUT /sites/{site_id}/coupons/{coupon_id} to update a coupon.
  • Permitted additional parameters on POST /sites/{site_id}/coupons:
    • Added applies_to_non_plan_charges.
    • Added redemption_resource.
    • Added coupon_type.
    • Added unique_code_template.
  • Changed allowed parameters on POST /sites/{site_id}/coupons:
    • Added free_trial_unit.
    • Added free_trial_amount.
  • Added POST /sites/:site_id/coupons/:id/generate.
  • Added GET /site/:site_id/coupon/:coupon_id/unique_coupon_codes.
  • Added GET /site/:site_id/unique_coupon_codes/:unique_coupon_code_id.
  • Added DELETE /site/:site_id/unique_coupon_codes/:unique_coupon_code_id.
  • Added PUT /site/:site_id/unique_coupon_codes/:unique_coupon_code_id/restore.
  • Changed Subscription response format:
    • Added subtotal.
    • Added terms_and_conditions.
    • Added customer_notes.
    • Added bank_account_authorized_at.
    • Removed total, tax and tax_info. Use the pre-tax subtotal instead.
  • Added GET /sites/:site_id/accounts/:account_id/acquisition.
  • Added PUT /sites/:site_id/accounts/:account_id/acquisition.
  • Added DELETE /sites/:site_id/accounts/:account_id/acquisition.
  • Added GET /sites/:site_id/acquisitions.
  • Changed Transaction response format:
    • Added original_transaction_id.
  • Added GET /sites/:site_id/accounts/:account_id/shipping_addresses.
  • Added POST /sites/:site_id/accounts/:account_id/shipping_addresses.
  • Added PUT /sites/:site_id/accounts/:account_id/shipping_addresses/:shipping_address_id.
  • Added DELETE /sites/:site_id/accounts/:account_id/shipping_addresses/:shipping_address_id.

v2016-07-05 (Removed)

  • Changed Subscription response format:
    • Added coupon_redemptions list.
  • Changed Coupon Redemption response format:
    • Removed expired_at. Use removed_at instead.

v2016-04-27

  • Changed Invoice, Transaction, Subscription response formats:
    • Added account object.
    • Removed account_id. Use account.id instead.
  • Changed Line Item response format:
    • Added account object.
    • Removed account_id and account_code. Use account.id and account.code instead.

v2016-03-01

  • Added PUT /sites/{site_id}/subscriptions/{subscription_id}/cancel to cancel a subscription.
  • Added PUT /sites/{site_id}/subscriptions/{subscription_id}/reactivate to reactivate a canceled subscription.
  • Changed PUT /sites/{site_id}/subscriptions/{subscription_id} to no longer allow state parameter changes. Use the new cancel or reactivate methods instead.
  • Changed DELETE /sites/{site_id}/subscriptions/{subscription_id} to accept a refund parameter.
  • Changed Line Item response format: added account_code.
  • Changed Subscription response format: added pending_change object.

v2016-01-01 (Removed)

v2014-06-22 (Removed)