Overview

This guide shows you how to use the Purchase endpoint to create new accounts, add subscriptions or one-time charges, and securely capture payment details. We’ll also illustrate how to integrate Recurly.js for secure tokenization.

Prerequisites & limitations

Familiarity with Recurly’s API and basic REST concepts
Completed the Quickstart Guide
Optional usage of Recurly.js to reduce PCI compliance scope

Definition

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

Creating Purchases

Step 1: Generate a BillingInfo token

Use Recurly.js to embed secure payment fields in your front-end code. This library collects customer card data and returns a token (rjs_token_id) representing the payment details. You’ll use this token when making your purchase request to Recurly.

Step 2: Create a purchase request

Send a request to the create_purchase method on Recurly’s API, including:

Customer account data (e.g., code, name, billing info)
Subscriptions (with plan codes)
Optional one-time line items or charges

Below are example calls in different languages:

purchase = {
  currency: "USD",
  account: {
    code: "bdumonde",
    first_name: "Benjamin",
    last_name: "Du Monde",
    billing_info: {
      token_id: rjs_token_id
    },
  },
  subscriptions: [
    { plan_code: "coffee-monthly" }
  ]
}

invoice_collection = @client.create_purchase(body: purchase)

let purchaseReq = {
  currency: 'USD',
  account: {
    code: 'bdumonde',
    firstName: 'Benjamin',
    lastName: 'Du Monde',
    billingInfo: {
      tokenId: rjsTokenId
    }
  },
  subscriptions: [
    { planCode: 'coffee-monthly' }
  ]
}
let invoiceCollection = await client.createPurchase(purchaseReq)

purchase = {
    "currency": "USD",
    "account": {
        "code": "bdumonde",
        "first_name": "Benjamin",
        "last_name": "Du Monde",
        "billing_info": {"token_id": rjs_token_id},
    },
    "subscriptions": [{"plan_code": "coffee-monthly"}],
}
invoice_collection = client.create_purchase(purchase)

PurchaseCreate purchase = new PurchaseCreate();
purchase.setCurrency("USD");

AccountPurchase account = new AccountPurchase();
account.setCode("bdumonde");
account.setFirstName("Benjamin");
account.setLastName("Du Monde");
purchase.setAccount(account);

BillingInfoCreate billing = new BillingInfoCreate();
billing.setTokenId(rjsTokenId);
account.setBillingInfo(billing);

List<SubscriptionPurchase> subs = new ArrayList<>();
SubscriptionPurchase sub = new SubscriptionPurchase();
sub.setPlanCode("coffee-monthly");
subs.add(sub);
purchase.setSubscriptions(subs);

InvoiceCollection collection = client.createPurchase(purchase);

var purchaseReq = new PurchaseCreate()
{
    Currency = "USD",
    Account = new AccountPurchase()
    {
        Code = "bdumonde",
        FirstName = "Benjamin",
        LastName = "Du Monde",
        BillingInfo = new BillingInfoCreate()
        {
            TokenId = rjsTokenId
        }
    },
    Subscriptions = new List<SubscriptionPurchase>()
    {
        new SubscriptionPurchase() { PlanCode = "coffee-monthly" }
    }
};

InvoiceCollection collection = client.CreatePurchase(purchaseReq);

Tip: Many more parameters are available. See the Create Purchase reference to learn more.

Step 3: Process the purchase response

A successful purchase returns an InvoiceCollection, which contains any charge or credit invoices generated by the request. If the purchase fails, you’ll receive an error response indicating what went wrong.

invoice = invoice_collection.charge_invoice
puts "Created Invoice #{invoice}"

let invoice = invoiceCollection.chargeInvoice
console.log('Created Invoice:', invoice)

invoice = invoice_collection.charge_invoice
print("Created Invoice %s" % invoice)

Invoice invoice = collection.getChargeInvoice();
System.out.println("Created Charge Invoice with Id: " + invoice.getId());

Invoice invoice = collection.ChargeInvoice;
Console.WriteLine($"Created Invoice with Number: {invoice.Number}");

Step 4: 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 accounts, subscriptions, and one-time payments, explore the Subscription Management guide to learn how to modify subscriptions after the initial purchase.