Overview

This guide shows you how to use the V3 Subscriptions endpoint or Purchases endpoint to create new subscriptions using a targeted backup_gateway_code and ensuring continuity between the gateway running the verification for the signup transaction, and the eventual gateway that will handle the renewal. This is not a necessary step unless you absolutely want the same gateway_code for both transactions.

In order for continuous routing to occur for both the verification on the signup transaction and continuously on the subscription using the v3/subscriptions endpoint you will need to place gateway_code in the subscriptions call body twice. To ensure a targeted failover to another gateway if your preferred gateway is in failover, you will apply a backup_gateway_code in the billing_info object.

Prerequisites & limitations

• Familiarity with Recurly’s API and basic REST concepts
• Completed the Quickstart Guide
• You have a backup gateway that has similar or identical payment method and currency support.
• You have two different gateways enabled (not just different accounts on the same gateway). For example, two different Adyen accounts will not suffice. You must have, for example, Adyen and Braintree, enabled. If Adyen is down, Braintree can act as backup.

Definition

Creating Subscriptions refers to the process of generating new customer accounts alongside subscriptions in a single, consolidated call to the Recurly Subscription endpoint. This streamlines checkout experiences by bundling all required resources into one request.

Processing continuity refers to the process of ensuring the entire subscription lifecycle occurs on a single gateway instance in your Recurly site, instead of allowing dynamic gateway routing to occur.

Targeted failover refers to the process of ensuring the signup transaction does not encounter errors due to a downstream provider outage. Targeting refers to using a specific gateway code instead of allowing Recurly's failover system to choose.

Creating Subscriptions

Step 1: Generate a Subscription Request

Use a supported library, Recurly.js or our APIs with raw card or billing payment information.

Send a request to the createsubscription endpoint on Recurly’s API, including:

• Customer account data (e.g., code, name, billing info, phone number, email address, tax ID/tax type)
• Subscriptions (with plan codes)
• Gateway Code in two places:
  • Once at the top-level subscription (which controls the renewal behavior) and again at the billing info level (controls the verification behavior).
• Backup Gateway Code in one place:
  • Only at the billing info level (controls the verification or signup purchase behavior). Backup gateway codes only apply to CIT (customer-initiated) transactions.

There are other fields available in our documentation. Below is a hyper-specific example to show the gateway_code placement and backup_gateway_code placement specifically.

{
    "currency": "USD",
    "plan_code": "example_plan_1", // Plan Code referencing a Free Trial
    "account": {
        "code": "new_account_1",
        "billing_info": {
            "token_id": "rjs-token", // Only send if using Recurly.js
            "gateway_code": "your-gateway-code", // Controls the current purchase / verification
            "backup_gateway_code": "your-backup-gateway-code" // Controls the current purchase / verification if the primary gateway_code is in failover
        }
    },
    "gateway_code": "your-gateway-code" // Controls Renewals
}

Step 2: Process the subscription response

A successful purchase returns an InvoiceCollection, which contains any charge or credit invoices generated by the request.

Step 3: Verify and finish

After a successful purchase, you can confirm the details via the Recurly Admin UI or by calling Recurly’s API to list your new account, subscription, or invoice.

Next steps

Now that you can create new subscriptions, explore other payment method guides that may suite your needs including MOTO and Combining Subscriptions and One Time Payments.