Overview

This guide shows you how to use the V3 Subscriptions endpoint to create new subscriptions using the free trial and ensuring continuity between the gateway running the verification for the free trial, 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 free trial and continuously on the subscription using the v3/subscriptions endpoint you will need to place gateway_code in the subscriptions call body twice.

Prerequisites & limitations

• Familiarity with Recurly’s API and basic REST concepts
• Completed the Quickstart Guide
• You have a free trial plan or coupon code
• A gateway that supports free trials

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.

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).

There are other fields available in our documentation. Below is a hyper-specific example to show the 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
        }
    },
    "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.