Creating Purchases

Overview

This guide is intended to walk you through the process of creating new customer accounts and purchases (subscriptions and one time payments) . Before continuing with this guide, it’s recommended that you have completed the Quickstart Guide first.

In this guide, we’ll be using the Purchase endpoint of Recurly API, a powerful, all-in-one endpoint designed to back checkout experiences. With this endpoint, you have the flexibility to create a new customer Account, and any number of subscriptions and / or one time purchases all in one step. A purchase request can contain several different resources, but we’ll focus on the first four in this guide:

• Accounts (customer information)
• BillingInfo
• Subscriptions
• One-time Charges (line items)
• Coupons
• Gift Cards

Additionally, we’ll use Recurly.js to create secure tokens to encode the customer payment information before it is sent to Recurly API. Usage of Recurly.js is optional, but recommended as a secure way to limit your PCI Compliance exposure.

Estimated Completion time

3 Hours

Step 1: Generate a BillingInfo Token

For this portion of the guide, you’ll integrate the Recurly.js library into your front end application code. Follow the steps here to include the script on your page and to create a secure token that represents the customer payment information. This token will be used in the next step when you call Recurly API to complete the purchase.

Step 2: Create a Purchase Request

Next, we’ll make a request to the purchase endpoint, passing in the customer account and billing information (using the secure token from above), along with one or more subscription plan codes. In the example below, one subscription is generated using the plan code created in the Quickstart Guide.

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: accountCode,
    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> subscriptions = new ArrayList<>();
SubscriptionPurchase sub = new SubscriptionPurchase();
sub.setPlanCode("coffee-monhtly");
subscriptions.add(sub);

purchase.setSubscriptions(subscriptions);

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

Many additional options are available to you. Take a look at the Create Purchase reference documentation to learn more.

Step 3: Process the Purchase Response

If the purchase was not successful, you’ll receive an error response indicating the type of error that was encountered. Errors could occur due to a bad request (missing or invalid parameters), or other reasons such as payment gateway failures.

If the purchase is successful, an InvoiceCollection will be returned as the response type. This object consists of any charge or credit invoices created during the purchase.

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

If the purchase was successful, you should now be able to access all associated objects that were created as a result. You can verify through the API or the admin console.

Next Steps

Now that you know how to create new accounts, subscriptions and one-time payments, take a look at the Subscription Management guide to learn more about how to manage the subscription changes after the initial purchase.