Overview

This guide shows you how to use the V3 Purchases 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 targeted routing to occur for the transaction using the v3/purchases endpoint you will need to place gateway_code in the billing_info object.

Prerequisites & limitations

• Familiarity with Recurly’s API and basic REST concepts
• Completed the Quickstart Guide
• You custom line items or a catalogue Id code.

Definition

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

Creating Subscriptions

Step 1: Generate a Purchase Request

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

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

• Customer account data (e.g., code, name, billing info, phone number, email address, tax ID/tax type)
• Line Items (custom or catalogue codes)
• Gateway Code in one places:
  • Once at the billing info level (controls the purchase behavior).

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

{
    "currency": "USD",
    "line_items": [{
      "unit_amount": "10.00",
      "quantity": 1,
      "description":"description",
      "type": "charge",
      "product_code":"1001"
    }],
    "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
        }
    }
}

Step 2: Process the purchase 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, transaction, or invoice.

Next steps

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