a recurly v2 api client for node.js
This code is still in development. We do not have complete coverage of the API yet.
An example of typical usage:
var recurly = require'recurring'; // note function invocationrecurlysetAPIKey'your-api-key';recurlysetRateLimit400;recurlysetCachefalse;var account = ;accountid = 'account-uuid';accountfetchaccountfetchSubscriptions;subscriptions0cancelconsole.logupdatedstate; // will be 'canceled';;;recurlyAccountall// accounts is an array containing all customer accounts;recurlyPlanall// plans is an array containing all plans set up for your account;
In order to access the Recurly API you must supply your API key which can be setterFunc by calling the
var recurly = require'recurring';recurlysetAPIKey'your-api-key';
The recurly API has a rate limit policy in place that prevents excessive calls being made to the API. By default sandbox accounts have a limit of 400 requests per minute and live accounts have a limit of 1000 requests per minute. In order to help ensure that you do not exceed these limits Recurring provides a configurable rate limiter. The rate limiter can be configured by calling the
var recurly = require'recurring';recurlysetRateLimit400;
Basic in memory result caching can be enabled by calling the
setCache() method so that subsequent requests to fetch
the same data does not result in additional API calls to Recurly.
var recurly = require'recurring';recurlysetCachetrue;
The recurly result cache can be cleared by calling the
var recurly = require'recurring';recurlyclearCache;
Recurly is not consistent about how it names the ID fields for each data type. For some it's
uuid and for others
foo_code. Recurring hides this away: every data type has an
id property that sets the correct field name for Recurly.
Create an object of the given type by POSTing to Recurly.
Fetch an item of a given type from Recurly. The item must have an id.
Destroy, delete, close, cancel, or otherwise remove the specified object. Invokes http
DELETE on the item's href. The
item must have an id.
Most data types have an
update() method that changes the stored data.
Fetch a list of plans. Responds with an array of all plans.
Fetch a list of plans. Responds with an async iterator that lazy loads data from recurly in batches of 200.
var iterators = require'async-iterators';var iterator = Planiterator;iteratorsforEachAsynciteratornext;;
Fetch plan addons. Responds with a array of plan addons.
Fetch a list of accounts. Responds with an array of all accounts in the passed-in state. Defaults to 'active'.
Fetch a list of accounts. Responds with an async iterator that lazy loads data from recurly in batches of 200.
var iterators = require'async-iterators';var iterator = Accountiterator;iteratorsforEachAsynciteratornext;;
Close an account. Alias for delete.
Reopen a closed account:
Fetch billing information for an account. Responds with an BillingInfo object.
Fetch subscription information for an account. Responds with an array of subscriptions for this account.
Add/update billing information for an account.
binfo = ;binfoaccount_code = '1234';var billing_data =first_name: 'Dummy'last_name: 'User'number: '4111-1111-1111-1111'month: 1year: 2020verification_value: '123'address1: '760 Market Street'address2: 'Suite 500'city: 'San Francisco'state: 'CA'country: 'USA'zip: '94102';binfoupdatebilling_datademanderrnotexist;binfolast_fourmustequal'1111';;
Using a billing token
You can also update billing information using a recurly.js billing token in place of the raw billing information (recommended)
binfo = ;binfoaccount_code = '1234';var billing_data =token_id: 'bunYTdIdjfJJY6Z87j5NtA' // <- recurly.js billing token.;binfoupdatebilling_data;
When adding billing information to an account Recurly may ake an authorization attempt against the card which may incur
charges depending on your payment gateway. In order to prevent Recurly from making this authorization attempt, a
skipAuthorization paramater can be supplied along with the billing information.
binfo = ;binfoaccount_code = '1234';var billing_data =number: '4111-1111-1111-1111'month: 1year: 2020skipAuthorization: true // <- do not make authorization request.;binfoupdatebilling_data;
Fetch a list of subscriptions. Responds with an array of all subscriptions in the passed-in state. Defaults to 'active'.
Fetch a list of subscriptions. Responds with an async iterator that lazy loads data from recurly in batches of 200.
var iterators = require'async-iterators';var iterator = Subscriptioniterator;iteratorsforEachAsynciteratornext;;
Cancel a subscription.
Reactivate a cancelled subscription.
Postpone a subscription.
Terminate a subscription using the specific refund type. Valid refund types are 'partial', 'full', and 'none'.
Fetch a list of coupons. Responds with an array of all coupons.
Fetch a list of coupons. Responds with an async iterator that lazy loads data from recurly in batches of 200.
var iterators = require'async-iterators';var iterator = Couponiterator;iteratorsforEachAsynciteratornext;;
Redeem a coupon.
Fetch a list of transactions. Responds with an array of all transactions.
Fetch a list of transactions. Responds with an async iterator that lazy loads data from recurly in batches of 200.
var iterators = require'async-iterators';var iterator = Transactioniterator;iteratorsforEachAsynciteratornext;;
If amountInCents is omitted, the transaction is refunded in full. Responds with any errors; the transaction object is updated.
All callbacks follow the node convention of reporting any error in the first parameter. If a transaction with Recurly
succeeds but is rejected by Recurly for some reason-- inconsistent data, perhaps, or some other reason-- that err
parameter is an instance of RecurlyError. The original transaction errors reported by Recurly are available as an array of structs in the
errors parameter. For instance, here's the result of a
billing info update with an invalid, expired CC:
name: 'RecurlyError'message: '2 transaction errors'errors:field: 'billing_info.number'symbol: 'invalid'message: 'is not a valid credit card number'field: 'billing_info.number'symbol: 'expired'message: 'is expired or has an invalid expiration date'
This provides the back-end support for signing parameters for forms embedded using recurly.js. See Recurly's signature documentation for details on which parameters must be signed for each form type.
var recurly = require'recurring';var signer = 'your-private-api-key';signerset'account' account_code: 'account-id' ;var signedParameters = signertoString;
timestamp parameters are generated for you if you don't provide them. The nonce is created using node-uuid.
After Recurly handles a form submission, it posts to you a token pointing to the form results. Use a FormResponseToken object to fetch the results object represented by the token.
var recurly = require'recurring';var recurlyResponse = token 'subscription';recurlyResponseprocessif errreturn handleErrorerr;// subscription contains the new subscription data;;
Having to hint about the type of the response is clunky; TODO fix.
MIT. See accompanying LICENSE file.