This library is published on npm under the name recurly
.
We recommend installing via the command line:
npm install recurly --save-prod
Or manually insert the dependency into the dependencies
section of your package.json
:
Note: We do try to strictly follow SemVer so locking to a major version should be safe.
{
// ...
"recurly" : "^3.5.0"
// ...
}
Note: When upgrading, view the CHANGELOG to see what's changed.
A client object represents a connection to the Recurly API. The client implements
each operation
that can be performed in the API as a method.
To initialize a client, you only need an API key which can be obtained on the API Credentials Page.
const recurly = require('recurly')
// You should store your API key somewhere safe
// and not in plain text if possible
const myApiKey = '<myapikey>'
const client = new recurly.Client(myApiKey)
Note: to import using typescript:
import * as recurly from "recurly";
All operations are async
and return promises (except the list*
methods which return Pager
s).
You can handle the promises directly with then
and catch
or use await:
client.getAccount('code-benjamin')
.then(account => console.log(account.id))
.catch(err => console.log(err.msg))
async function myFunc () {
try {
let account = await client.getAccount('code-benjamin')
} catch (err) {
// handle err from client
}
}
For creating or updating resources, pass a plain object to one of the create or update methods.
Note: Keep in mind that the API accepts snake-cased keys but this library expects camel-cased keys. We do the translation for you so this library can conform to js style standards.
try {
const acctReq = {
code: 'new-account-code',
firstName: 'Benjamin',
lastName: 'Du Monde'
}
const account = await client.createAccount(acctReq)
} catch (err) {
if (err instanceof recurly.errors.ValidationError) {
// If the request was not valid, you may want to tell your user
// why. You can find the invalid params and reasons in err.params
console.log('Failed validation:', err.params)
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error:', err)
}
}
All list*
methods on the client return a Pager
. They
are not async
because they are lazy and do not make any
network requests until they are iterated over. There are
two methods on Pager
that return async iterators each
and eachPage
:
each
will give you an iterator over each item that matches your query.eachPage
will give you an iterator over each page that is returned. The result is an array of resources.async function eachAccount (accounts) {
try {
for await (const acct of accounts.each()) {
console.log(acct.id)
}
} catch (err) {
// err is bubbled up from recurly client
}
}
async function eachPageOfAccounts (accounts) {
try {
for await (const page of accounts.eachPage()) {
page.forEach(acct => console.log(acct.id))
}
} catch (err) {
// err is bubbled up from recurly client
}
}
const accounts = client.listAccounts({
beginTime: '2018-12-01T00:00:00Z',
sort: 'updated_at'
})
eachAccount(accounts)
// or
eachPageOfAccounts(accounts)
The Pager class implements a first
method which allows you to fetch just the first or last resource from the server.
On top of being a convenient abstraction, this is implemented efficiently by only asking the server for the 1 item you want.
const accounts = client.listAccounts({
beginTime: '2018-12-01T00:00:00Z',
subscriber: true,
order: 'desc'
})
const firstAccount = await accounts.first()
If you want to fetch the last account in this scenario, invert the order from desc
to asc
const accounts = client.listAccounts({
beginTime: '2018-12-01T00:00:00Z',
subscriber: true,
order: 'asc'
})
const lastAccount = await accounts.first()
The Pager class implements a count
method which allows you to count the resources the pager would return.
It does so by calling the endpoint with HEAD
and parsing and returning the Recurly-Total-Records
header. This
method respects any filtering parameters you apply to the pager, but the sorting parameters will have no effect.
const accounts = client.listAccounts({
beginTime: '2018-12-01T00:00:00Z',
subscriber: true
})
const count = await accounts.count()
// => 573
This library currently throws 1 primary class of exceptions, recurly.ApiError. The ApiError comes in a few flavors which help you determine what to do next. To see a full list, view the api_errors module.
try {
const expiredSub = await client.terminateSubscription(subId, { refund: 'full' })
} catch (err) {
if (err) {
if (err.getResponse()) {
const requstId = err.getResponse().requestId
console.log('Request Id useful for support:', requestId)
}
if (err instanceof recurly.errors.ValidationError) {
// If the request was not valid, you may want to tell your user
// why. You can find the invalid params and reasons in err.params
console.log('Failed validation:', err.params)
} else if (err instanceof recurly.errors.NotFoundError) {
console.log('Subscription not found:', err)
} else if (err instanceof recurly.ApiError) {
console.log('generic API error:', err)
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error:', err)
}
}
}
Sometimes you might want to get some additional information about the underlying HTTP request and response. Instead of
returning this information directly and forcing the programmer to unwrap it, we inject this metadata into the top level
resource that was returned. You can access the response by calling getResponse()
on any Resource.
Warning: Do not log or render whole requests or responses as they may contain PII or sensitive data.
const account = await client.getAccount("code-benjamin")
const response = account.getResponse()
response.rateLimitRemaining // 1985
response.requestId // "0av50sm5l2n2gkf88ehg"
response.request.path // "/sites/subdomain-mysite/accounts/code-benjamin"
response.request.body // null
This also works on Empty responses:
const result = await client.removeLineItem("a959576b2b10b012")
const response = result.getResponse()
And it can be captured on exceptions through the ApiError object:
try {
const account = await client.getAccount(account_id)
} catch (err) {
if (err instanceof recurly.errors.NotFoundError) {
// You can also get the Response here
const response = err.getResponse()
} else {
console.log('Unknown Error:', err)
}
}
Recurly can send webhooks to any publicly accessible server. When an event in Recurly triggers a webhook (e.g., an account is opened), Recurly will attempt to send this notification to the endpoint(s) you specify. You can specify up to 10 endpoints through the application. All notifications will be sent to all configured endpoints for your site.
See our product docs to learn more about webhooks and see our dev docs to learn about what payloads are available.
Although our API is now JSON, our webhook payloads are still formatted as XML for the time being. This library is not yet responsible for handling webhooks. If you do need webhooks, we recommend using a simple XML to Plain Object parser such as xml2js.
const parseString = require('xml2js').parseString
const xml = `
<?xml version="1.0" encoding="UTF-8"?>
<new_account_notification>
<account>
<account_code>1</account_code>
<username nil="true"></username>
<EMAIL_ADDRESS><first_name>Verena</first_name>
<last_name>Example</last_name>
<company_name nil="true"></company_name>
</account>
</new_account_notification>
`;
parseString(xml, function (err, result) {
const code = result.new_account_notification.account[0].account_code[0];
console.log('New account created with code:', code);
})
You can do this without dependencies, but you'll need to heed warnings about security concerns. Read more about the security implications of parsing untrusted XML in this OWASP cheatsheet.
Client
(apiKey)
| parameter | type | description |
|---|---|---|
apiKey |
string | The private api key. |
listSites
(params)
List sites
API docs: https://developers.recurly.com/api/v2019-10-10#operation/list_sites
| parameter | type | description |
|---|---|---|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.ids | Array<string> | Filter results by their IDs. Up to 200 IDs can be passed at once using
commas as separators, e.g.
ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6
.
Important notes:
|
| params.limit | number | Limit number of records 1-200. |
| params.order | string | Sort order. |
| params.sort | string | Sort field. You
really
only want to sort by
updated_at
in ascending
order. In descending order updated records will move behind the cursor and could
prevent some records from being returned.
|
Pager<Site>
:
A list of sites.
const sites = client.listSites({ limit: 200 })
for await (const site of sites.each()) {
console.log(site.subdomain)
}
getSite
(siteId)
Fetch a site
API docs: https://developers.recurly.com/api/v2019-10-10#operation/get_site
| parameter | type | description |
|---|---|---|
siteId |
string | Site ID or subdomain. For ID no prefix is used e.g.
e28zov4fw0v2
. For subdomain use prefix
subdomain-
, e.g.
subdomain-recurly
.
|
Promise<Site>
:
A site.
listAccounts
(params)
List a site's accounts
API docs: https://developers.recurly.com/api/v2019-10-10#operation/list_accounts
| parameter | type | description |
|---|---|---|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.ids | Array<string> | Filter results by their IDs. Up to 200 IDs can be passed at once using
commas as separators, e.g.
ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6
.
Important notes:
|
| params.limit | number | Limit number of records 1-200. |
| params.order | string | Sort order. |
| params.sort | string | Sort field. You
really
only want to sort by
updated_at
in ascending
order. In descending order updated records will move behind the cursor and could
prevent some records from being returned.
|
| params.beginTime | Date | Filter by begin_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.endTime | Date | Filter by end_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.email | string | Filter for accounts with this exact email address. A blank value will return accounts with both
null
and
""
email addresses. Note that multiple accounts can share one email address.
|
| params.subscriber | boolean | Filter for accounts with or without a subscription in the
active
,
canceled
, or
future
state.
|
| params.pastDue | string | Filter for accounts with an invoice in the
past_due
state.
|
Pager<Account>
:
A list of the site's accounts.
const accounts = client.listAccounts({ limit: 200 })
for await (const account of accounts.each()) {
console.log(account.code)
}
createAccount
(body)
Create an account
API docs: https://developers.recurly.com/api/v2019-10-10#operation/create_account
| parameter | type | description |
|---|---|---|
body |
AccountCreate | The object representing the JSON request to send to the server. It should conform to the schema of {AccountCreate} |
Promise<Account>
:
An account.
try {
const accountCreate = {
code: accountCode,
firstName: 'Benjamin',
lastName: 'Du Monde',
address: {
street1: '900 Camp St',
city: 'New Orleans',
region: 'LA',
postalCode: '70115',
country: 'US'
}
}
const account = await client.createAccount(accountCreate)
console.log('Created Account: ', account.code)
} catch (err) {
if (err instanceof recurly.errors.ValidationError) {
// If the request was not valid, you may want to tell your user
// why. You can find the invalid params and reasons in err.params
console.log('Failed validation', err.params)
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
getAccount
(accountId)
Fetch an account
API docs: https://developers.recurly.com/api/v2019-10-10#operation/get_account
| parameter | type | description |
|---|---|---|
accountId |
string | Account ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-bob
.
|
Promise<Account>
:
An account.
try {
const account = await client.getAccount(accountId)
console.log('Fetched account: ', account.code)
} catch (err) {
if (err instanceof recurly.errors.NotFoundError) {
// If the request was not found, you may want to alert the user or
// just return null
console.log('Resource Not Found')
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
updateAccount
(accountId, body)
Modify an account
API docs: https://developers.recurly.com/api/v2019-10-10#operation/update_account
| parameter | type | description |
|---|---|---|
accountId |
string | Account ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-bob
.
|
body |
AccountUpdate | The object representing the JSON request to send to the server. It should conform to the schema of {AccountUpdate} |
Promise<Account>
:
An account.
try {
const accountUpdate = {
firstName: 'Aaron',
lastName: 'Du Monde'
}
const account = await client.updateAccount(accountId, accountUpdate)
console.log('Updated account: ', account)
} catch (err) {
if (err instanceof recurly.errors.ValidationError) {
// If the request was not valid, you may want to tell your user
// why. You can find the invalid params and reasons in err.params
console.log('Failed validation', err.params)
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
deactivateAccount
(accountId)
Deactivate an account
API docs: https://developers.recurly.com/api/v2019-10-10#operation/deactivate_account
| parameter | type | description |
|---|---|---|
accountId |
string | Account ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-bob
.
|
Promise<Account>
:
An account.
try {
const account = await client.deactivateAccount(accountId)
console.log('Deleted account: ', account.code)
} catch (err) {
if (err && err.type === 'not-found') {
// If the request was not found, you may want to alert the user or
// just return null
console.log('Resource Not Found')
}
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
throw err
}
getAccountAcquisition
(accountId)
Fetch an account's acquisition data
API docs: https://developers.recurly.com/api/v2019-10-10#operation/get_account_acquisition
| parameter | type | description |
|---|---|---|
accountId |
string | Account ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-bob
.
|
Promise<AccountAcquisition>
:
An account's acquisition data.
try {
const acquisition = await client.getAccountAcquisition(accountId)
console.log('Fetched account acquisition: ', acquisition.id)
} catch (err) {
if (err instanceof recurly.errors.NotFoundError) {
// If the request was not found, you may want to alert the user or
// just return null
console.log('Resource Not Found')
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
updateAccountAcquisition
(accountId, body)
Update an account's acquisition data
API docs: https://developers.recurly.com/api/v2019-10-10#operation/update_account_acquisition
| parameter | type | description |
|---|---|---|
accountId |
string | Account ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-bob
.
|
body |
AccountAcquisitionUpdatable | The object representing the JSON request to send to the server. It should conform to the schema of {AccountAcquisitionUpdatable} |
Promise<AccountAcquisition>
:
An account's updated acquisition data.
try {
const acquisitionUpdate = {
campaign: "big-event-campaign",
channel: "social_media",
subchannel: "twitter"
}
const accountAcquisition = await client.updateAccountAcquisition(accountId, acquisitionUpdate)
console.log('Edited Account Acquisition: ', accountAcquisition)
} catch (err) {
if (err instanceof recurly.errors.ValidationError) {
// If the request was not valid, you may want to tell your user
// why. You can find the invalid params and reasons in err.params
console.log('Failed validation', err.params)
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
removeAccountAcquisition
(accountId)
Remove an account's acquisition data
API docs: https://developers.recurly.com/api/v2019-10-10#operation/remove_account_acquisition
| parameter | type | description |
|---|---|---|
accountId |
string | Account ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-bob
.
|
Promise<Empty>
:
Acquisition data was succesfully deleted.
try {
await client.removeAccountAcquisition(accountId)
console.log('Removed account acquisition from account: ', accountId)
} catch (err) {
if (err instanceof recurly.errors.NotFoundError) {
// If the request was not found, you may want to alert the user or
// just return null
console.log('Resource Not Found')
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
reactivateAccount
(accountId)
Reactivate an inactive account
API docs: https://developers.recurly.com/api/v2019-10-10#operation/reactivate_account
| parameter | type | description |
|---|---|---|
accountId |
string | Account ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-bob
.
|
Promise<Account>
:
An account.
try {
const account = await client.reactivateAccount(accountId)
console.log('Reactivated account: ', account.code)
} catch (err) {
if (err && err.type === 'not_found') {
// If the request was not found, you may want to alert the user or
// just return null
console.log('Resource Not Found')
}
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
throw err
}
getAccountBalance
(accountId)
Fetch an account's balance and past due status
API docs: https://developers.recurly.com/api/v2019-10-10#operation/get_account_balance
| parameter | type | description |
|---|---|---|
accountId |
string | Account ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-bob
.
|
Promise<AccountBalance>
:
An account's balance.
try {
const balance = await client.getAccountBalance(accountId)
console.log('Fetched account balance: ', balance.balances)
} catch (err) {
if (err instanceof recurly.errors.NotFoundError) {
// If the request was not found, you may want to alert the user or
// just return null
console.log('Resource Not Found')
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
getBillingInfo
(accountId)
Fetch an account's billing information
API docs: https://developers.recurly.com/api/v2019-10-10#operation/get_billing_info
| parameter | type | description |
|---|---|---|
accountId |
string | Account ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-bob
.
|
Promise<BillingInfo>
:
An account's billing information.
try {
const billingInfo = await client.getBillingInfo(accountId)
console.log('Fetched Billing Info: ', billingInfo.id)
} catch (err) {
if (err instanceof recurly.errors.NotFoundError) {
// If the request was not found, you may want to alert the user or
// just return null
console.log('Resource Not Found')
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
updateBillingInfo
(accountId, body)
Set an account's billing information
API docs: https://developers.recurly.com/api/v2019-10-10#operation/update_billing_info
| parameter | type | description |
|---|---|---|
accountId |
string | Account ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-bob
.
|
body |
BillingInfoCreate | The object representing the JSON request to send to the server. It should conform to the schema of {BillingInfoCreate} |
Promise<BillingInfo>
:
Updated billing information.
try {
const billingInfoUpdate = {
firstName: 'Aaron',
lastName: 'Du Monde',
}
const billingInfo = await client.updateBillingInfo(accountId, billingInfoUpdate)
console.log('Updated billing info: ', billingInfo.id)
} catch (err) {
if (err instanceof recurly.errors.ValidationError) {
// If the request was not valid, you may want to tell your user
// why. You can find the invalid params and reasons in err.params
console.log('Failed validation', err.params)
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
removeBillingInfo
(accountId)
Remove an account's billing information
API docs: https://developers.recurly.com/api/v2019-10-10#operation/remove_billing_info
| parameter | type | description |
|---|---|---|
accountId |
string | Account ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-bob
.
|
Promise<Empty>
:
Billing information deleted
try {
client.removeBillingInfo(accountId)
console.log('Removed billing info from account: ', accountId)
} catch (err) {
if (err instanceof recurly.errors.NotFoundError) {
// If the request was not found, you may want to alert the user or
// just return null
console.log('Resource Not Found')
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
listAccountCouponRedemptions
(accountId, params)
Show the coupon redemptions for an account
API docs: https://developers.recurly.com/api/v2019-10-10#operation/list_account_coupon_redemptions
| parameter | type | description |
|---|---|---|
accountId |
string | Account ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-bob
.
|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.ids | Array<string> | Filter results by their IDs. Up to 200 IDs can be passed at once using
commas as separators, e.g.
ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6
.
Important notes:
|
| params.sort | string | Sort field. You
really
only want to sort by
updated_at
in ascending
order. In descending order updated records will move behind the cursor and could
prevent some records from being returned.
|
| params.beginTime | Date | Filter by begin_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.endTime | Date | Filter by end_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
Pager<CouponRedemption>
:
A list of the the coupon redemptions on an account.
getActiveCouponRedemption
(accountId)
Show the coupon redemption that is active on an account
API docs: https://developers.recurly.com/api/v2019-10-10#operation/get_active_coupon_redemption
| parameter | type | description |
|---|---|---|
accountId |
string | Account ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-bob
.
|
Promise<CouponRedemption>
:
An active coupon redemption on an account.
try {
const redemption = await client.getActiveCouponRedemption(accountId)
console.log('Fetched coupon redemption: ', redemption.id)
} catch (err) {
if (err instanceof recurly.errors.NotFoundError) {
// If the request was not found, you may want to alert the user or
// just return null
console.log('Resource Not Found')
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
createCouponRedemption
(accountId, body)
Generate an active coupon redemption on an account
API docs: https://developers.recurly.com/api/v2019-10-10#operation/create_coupon_redemption
| parameter | type | description |
|---|---|---|
accountId |
string | Account ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-bob
.
|
body |
CouponRedemptionCreate | The object representing the JSON request to send to the server. It should conform to the schema of {CouponRedemptionCreate} |
Promise<CouponRedemption>
:
Returns the new coupon redemption.
removeCouponRedemption
(accountId)
Delete the active coupon redemption from an account
API docs: https://developers.recurly.com/api/v2019-10-10#operation/remove_coupon_redemption
| parameter | type | description |
|---|---|---|
accountId |
string | Account ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-bob
.
|
Promise<CouponRedemption>
:
Coupon redemption deleted.
listAccountCreditPayments
(accountId, params)
List an account's credit payments
API docs: https://developers.recurly.com/api/v2019-10-10#operation/list_account_credit_payments
| parameter | type | description |
|---|---|---|
accountId |
string | Account ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-bob
.
|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.limit | number | Limit number of records 1-200. |
| params.order | string | Sort order. |
| params.sort | string | Sort field. You
really
only want to sort by
updated_at
in ascending
order. In descending order updated records will move behind the cursor and could
prevent some records from being returned.
|
| params.beginTime | Date | Filter by begin_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.endTime | Date | Filter by end_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
Pager<CreditPayment>
:
A list of the account's credit payments.
const payments = client.listAccountCreditPayments(accountId, { limit: 200 })
for await (const payment of payments.each()) {
console.log(payment.uuid)
}
listAccountInvoices
(accountId, params)
List an account's invoices
API docs: https://developers.recurly.com/api/v2019-10-10#operation/list_account_invoices
| parameter | type | description |
|---|---|---|
accountId |
string | Account ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-bob
.
|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.ids | Array<string> | Filter results by their IDs. Up to 200 IDs can be passed at once using
commas as separators, e.g.
ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6
.
Important notes:
|
| params.limit | number | Limit number of records 1-200. |
| params.order | string | Sort order. |
| params.sort | string | Sort field. You
really
only want to sort by
updated_at
in ascending
order. In descending order updated records will move behind the cursor and could
prevent some records from being returned.
|
| params.beginTime | Date | Filter by begin_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.endTime | Date | Filter by end_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.type | string | Filter by type when:
|
Pager<Invoice>
:
A list of the account's invoices.
createInvoice
(accountId, body)
Create an invoice for pending line items
API docs: https://developers.recurly.com/api/v2019-10-10#operation/create_invoice
| parameter | type | description |
|---|---|---|
accountId |
string | Account ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-bob
.
|
body |
InvoiceCreate | The object representing the JSON request to send to the server. It should conform to the schema of {InvoiceCreate} |
Promise<InvoiceCollection>
:
Returns the new invoices.
try {
let invoiceCreate = {
currency: 'USD',
collectionMethod: 'automatic'
}
let invoiceCollection = await client.createInvoice(accountId, invoiceCreate)
console.log('Created Invoice')
console.log('Charge Invoice: ', invoiceCollection.chargeInvoice)
console.log('Credit Invoices: ', invoiceCollection.creditInvoices)
} catch (err) {
if (err instanceof recurly.errors.ValidationError) {
// If the request was not valid, you may want to tell your user
// why. You can find the invalid params and reasons in err.params
console.log('Failed validation', err.params)
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
previewInvoice
(accountId, body)
Preview new invoice for pending line items
API docs: https://developers.recurly.com/api/v2019-10-10#operation/preview_invoice
| parameter | type | description |
|---|---|---|
accountId |
string | Account ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-bob
.
|
body |
InvoiceCreate | The object representing the JSON request to send to the server. It should conform to the schema of {InvoiceCreate} |
Promise<InvoiceCollection>
:
Returns the invoice previews.
try {
const collection = await client.previewInvoice(accountId, {
currency: "USD",
collectionMethod: "automatic"
})
console.log(`Previewed invoice due at ${collection.chargeInvoice.dueAt}`)
console.log(collection.chargeInvoice)
console.log(collection.creditInvoices)
} catch(err) {
if (err instanceof recurly.errors.ValidationError) {
// If the request was not valid, you may want to tell your user
// why. You can find the invalid params and reasons in err.params
console.log('Failed validation', err.params)
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
listAccountLineItems
(accountId, params)
List an account's line items
API docs: https://developers.recurly.com/api/v2019-10-10#operation/list_account_line_items
| parameter | type | description |
|---|---|---|
accountId |
string | Account ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-bob
.
|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.ids | Array<string> | Filter results by their IDs. Up to 200 IDs can be passed at once using
commas as separators, e.g.
ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6
.
Important notes:
|
| params.limit | number | Limit number of records 1-200. |
| params.order | string | Sort order. |
| params.sort | string | Sort field. You
really
only want to sort by
updated_at
in ascending
order. In descending order updated records will move behind the cursor and could
prevent some records from being returned.
|
| params.beginTime | Date | Filter by begin_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.endTime | Date | Filter by end_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.original | string | Filter by original field. |
| params.state | string | Filter by state field. |
| params.type | string | Filter by type field. |
Pager<LineItem>
:
A list of the account's line items.
createLineItem
(accountId, body)
Create a new line item for the account
API docs: https://developers.recurly.com/api/v2019-10-10#operation/create_line_item
| parameter | type | description |
|---|---|---|
accountId |
string | Account ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-bob
.
|
body |
LineItemCreate | The object representing the JSON request to send to the server. It should conform to the schema of {LineItemCreate} |
Promise<LineItem>
:
Returns the new line item.
try {
let lineItemReq = {
currency: 'USD',
unitAmount: 1000,
type: 'charge' // choose "credit" for a credit
}
let lineItem = await client.createLineItem(accountId, lineItemReq)
console.log('Created Line Item: ', lineItem.uuid)
} catch (err) {
if (err instanceof recurly.errors.ValidationError) {
// If the request was not valid, you may want to tell your user
// why. You can find the invalid params and reasons in err.params
console.log('Failed validation', err.params)
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
listAccountNotes
(accountId, params)
Fetch a list of an account's notes
API docs: https://developers.recurly.com/api/v2019-10-10#operation/list_account_notes
| parameter | type | description |
|---|---|---|
accountId |
string | Account ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-bob
.
|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.ids | Array<string> | Filter results by their IDs. Up to 200 IDs can be passed at once using
commas as separators, e.g.
ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6
.
Important notes:
|
Pager<AccountNote>
:
A list of an account's notes.
const notes = client.listAccountNotes(accountId, { limit: 200 })
for await (const note of notes.each()) {
console.log(note.message)
}
getAccountNote
(accountId, accountNoteId)
Fetch an account note
API docs: https://developers.recurly.com/api/v2019-10-10#operation/get_account_note
| parameter | type | description |
|---|---|---|
accountId |
string | Account ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-bob
.
|
accountNoteId |
string | Account Note ID. |
Promise<AccountNote>
:
An account note.
try {
console.log(accountId)
const note = await client.getAccountNote(accountId, accountNoteId)
console.log('Fetched account note: ', note.message)
} catch (err) {
if (err instanceof recurly.errors.NotFoundError) {
// If the request was not found, you may want to alert the user or
// just return null
console.log('Resource Not Found')
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
listShippingAddresses
(accountId, params)
Fetch a list of an account's shipping addresses
API docs: https://developers.recurly.com/api/v2019-10-10#operation/list_shipping_addresses
| parameter | type | description |
|---|---|---|
accountId |
string | Account ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-bob
.
|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.ids | Array<string> | Filter results by their IDs. Up to 200 IDs can be passed at once using
commas as separators, e.g.
ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6
.
Important notes:
|
| params.limit | number | Limit number of records 1-200. |
| params.order | string | Sort order. |
| params.sort | string | Sort field. You
really
only want to sort by
updated_at
in ascending
order. In descending order updated records will move behind the cursor and could
prevent some records from being returned.
|
| params.beginTime | Date | Filter by begin_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.endTime | Date | Filter by end_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
Pager<ShippingAddress>
:
A list of an account's shipping addresses.
const addresses = client.listShippingAddresses(accountId, { limit: 200 })
for await (const address of addresses.each()) {
console.log(address.street1)
}
createShippingAddress
(accountId, body)
Create a new shipping address for the account
API docs: https://developers.recurly.com/api/v2019-10-10#operation/create_shipping_address
| parameter | type | description |
|---|---|---|
accountId |
string | Account ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-bob
.
|
body |
ShippingAddressCreate | The object representing the JSON request to send to the server. It should conform to the schema of {ShippingAddressCreate} |
Promise<ShippingAddress>
:
Returns the new shipping address.
try {
const shippingAddressCreate = {
firstName: 'Aaron',
lastName: 'Du Monde',
street1: '900 Camp St.',
city: 'New Orleans',
region: 'LA',
postalCode: '70115',
country: 'US'
}
const address = await client.createShippingAddress(accountId, shippingAddressCreate)
console.log('Created shipping address: ', address.street1)
} catch (err) {
if (err instanceof recurly.errors.ValidationError) {
// If the request was not valid, you may want to tell your user
// why. You can find the invalid params and reasons in err.params
console.log('Failed validation', err.params)
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
getShippingAddress
(accountId, shippingAddressId)
Fetch an account's shipping address
API docs: https://developers.recurly.com/api/v2019-10-10#operation/get_shipping_address
| parameter | type | description |
|---|---|---|
accountId |
string | Account ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-bob
.
|
shippingAddressId |
string | Shipping Address ID. |
Promise<ShippingAddress>
:
A shipping address.
try {
const address = await client.getShippingAddress(accountId, shippingAddressId)
console.log('Fetched shipping address: ', address.street1)
} catch (err) {
if (err instanceof recurly.errors.NotFoundError) {
// If the request was not found, you may want to alert the user or
// just return null
console.log('Resource Not Found')
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
updateShippingAddress
(accountId, shippingAddressId, body)
Update an account's shipping address
API docs: https://developers.recurly.com/api/v2019-10-10#operation/update_shipping_address
| parameter | type | description |
|---|---|---|
accountId |
string | Account ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-bob
.
|
shippingAddressId |
string | Shipping Address ID. |
body |
ShippingAddressUpdate | The object representing the JSON request to send to the server. It should conform to the schema of {ShippingAddressUpdate} |
Promise<ShippingAddress>
:
The updated shipping address.
try {
const shadUpdate = {
firstName: "Benjamin",
lastName: "Du Monde"
}
const address = await client.updateShippingAddress(accountId, shippingAddressId, shadUpdate)
console.log('Updated shipping address: ', address.street1)
} catch (err) {
if (err instanceof recurly.errors.ValidationError) {
// If the request was not valid, you may want to tell your user
// why. You can find the invalid params and reasons in err.params
console.log('Failed validation', err.params)
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
removeShippingAddress
(accountId, shippingAddressId)
Remove an account's shipping address
API docs: https://developers.recurly.com/api/v2019-10-10#operation/remove_shipping_address
| parameter | type | description |
|---|---|---|
accountId |
string | Account ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-bob
.
|
shippingAddressId |
string | Shipping Address ID. |
Promise<Empty>
:
Shipping address deleted.
try {
await client.removeShippingAddress(accountId, shippingAddress.id)
console.log('Removed shipping address: ', shippingAddress.street1)
} catch (err) {
if (err instanceof recurly.errors.NotFoundError) {
// If the request was not found, you may want to alert the user or
// just return null
console.log('Resource Not Found')
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
listAccountSubscriptions
(accountId, params)
List an account's subscriptions
API docs: https://developers.recurly.com/api/v2019-10-10#operation/list_account_subscriptions
| parameter | type | description |
|---|---|---|
accountId |
string | Account ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-bob
.
|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.ids | Array<string> | Filter results by their IDs. Up to 200 IDs can be passed at once using
commas as separators, e.g.
ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6
.
Important notes:
|
| params.limit | number | Limit number of records 1-200. |
| params.order | string | Sort order. |
| params.sort | string | Sort field. You
really
only want to sort by
updated_at
in ascending
order. In descending order updated records will move behind the cursor and could
prevent some records from being returned.
|
| params.beginTime | Date | Filter by begin_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.endTime | Date | Filter by end_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.state | string | Filter by state.
|
Pager<Subscription>
:
A list of the account's subscriptions.
listAccountTransactions
(accountId, params)
List an account's transactions
API docs: https://developers.recurly.com/api/v2019-10-10#operation/list_account_transactions
| parameter | type | description |
|---|---|---|
accountId |
string | Account ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-bob
.
|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.ids | Array<string> | Filter results by their IDs. Up to 200 IDs can be passed at once using
commas as separators, e.g.
ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6
.
Important notes:
|
| params.limit | number | Limit number of records 1-200. |
| params.order | string | Sort order. |
| params.sort | string | Sort field. You
really
only want to sort by
updated_at
in ascending
order. In descending order updated records will move behind the cursor and could
prevent some records from being returned.
|
| params.beginTime | Date | Filter by begin_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.endTime | Date | Filter by end_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.type | string | Filter by type field. The value
payment
will return both
purchase
and
capture
transactions.
|
| params.success | string | Filter by success field. |
Pager<Transaction>
:
A list of the account's transactions.
listChildAccounts
(accountId, params)
List an account's child accounts
API docs: https://developers.recurly.com/api/v2019-10-10#operation/list_child_accounts
| parameter | type | description |
|---|---|---|
accountId |
string | Account ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-bob
.
|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.ids | Array<string> | Filter results by their IDs. Up to 200 IDs can be passed at once using
commas as separators, e.g.
ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6
.
Important notes:
|
| params.limit | number | Limit number of records 1-200. |
| params.order | string | Sort order. |
| params.sort | string | Sort field. You
really
only want to sort by
updated_at
in ascending
order. In descending order updated records will move behind the cursor and could
prevent some records from being returned.
|
| params.beginTime | Date | Filter by begin_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.endTime | Date | Filter by end_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.email | string | Filter for accounts with this exact email address. A blank value will return accounts with both
null
and
""
email addresses. Note that multiple accounts can share one email address.
|
| params.subscriber | boolean | Filter for accounts with or without a subscription in the
active
,
canceled
, or
future
state.
|
| params.pastDue | string | Filter for accounts with an invoice in the
past_due
state.
|
Pager<Account>
:
A list of an account's child accounts.
listAccountAcquisition
(params)
List a site's account acquisition data
API docs: https://developers.recurly.com/api/v2019-10-10#operation/list_account_acquisition
| parameter | type | description |
|---|---|---|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.ids | Array<string> | Filter results by their IDs. Up to 200 IDs can be passed at once using
commas as separators, e.g.
ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6
.
Important notes:
|
| params.limit | number | Limit number of records 1-200. |
| params.order | string | Sort order. |
| params.sort | string | Sort field. You
really
only want to sort by
updated_at
in ascending
order. In descending order updated records will move behind the cursor and could
prevent some records from being returned.
|
| params.beginTime | Date | Filter by begin_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.endTime | Date | Filter by end_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
Pager<AccountAcquisition>
:
A list of the site's account acquisition data.
listCoupons
(params)
List a site's coupons
API docs: https://developers.recurly.com/api/v2019-10-10#operation/list_coupons
| parameter | type | description |
|---|---|---|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.ids | Array<string> | Filter results by their IDs. Up to 200 IDs can be passed at once using
commas as separators, e.g.
ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6
.
Important notes:
|
| params.limit | number | Limit number of records 1-200. |
| params.order | string | Sort order. |
| params.sort | string | Sort field. You
really
only want to sort by
updated_at
in ascending
order. In descending order updated records will move behind the cursor and could
prevent some records from being returned.
|
| params.beginTime | Date | Filter by begin_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.endTime | Date | Filter by end_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
Pager<Coupon>
:
A list of the site's coupons.
const coupons = client.listCoupons({ limit: 200 })
for await (const coupon of coupons.each()) {
console.log(coupon.code)
}
createCoupon
(body)
Create a new coupon
API docs: https://developers.recurly.com/api/v2019-10-10#operation/create_coupon
| parameter | type | description |
|---|---|---|
body |
CouponCreate | The object representing the JSON request to send to the server. It should conform to the schema of {CouponCreate} |
Promise<Coupon>
:
A new coupon.
getCoupon
(couponId)
Fetch a coupon
API docs: https://developers.recurly.com/api/v2019-10-10#operation/get_coupon
| parameter | type | description |
|---|---|---|
couponId |
string | Coupon ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-10off
.
|
Promise<Coupon>
:
A coupon.
try {
const coupon = await client.getCoupon(couponId)
console.log('Fetched coupon: ', coupon.code)
} catch (err) {
if (err instanceof recurly.errors.NotFoundError) {
// If the request was not found, you may want to alert the user or
// just return null
console.log('Resource Not Found')
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
updateCoupon
(couponId, body)
Update an active coupon
API docs: https://developers.recurly.com/api/v2019-10-10#operation/update_coupon
| parameter | type | description |
|---|---|---|
couponId |
string | Coupon ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-10off
.
|
body |
CouponUpdate | The object representing the JSON request to send to the server. It should conform to the schema of {CouponUpdate} |
Promise<Coupon>
:
The updated coupon.
deactivateCoupon
(couponId)
Expire a coupon
API docs: https://developers.recurly.com/api/v2019-10-10#operation/deactivate_coupon
| parameter | type | description |
|---|---|---|
couponId |
string | Coupon ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-10off
.
|
Promise<Coupon>
:
The expired Coupon
listUniqueCouponCodes
(couponId, params)
List unique coupon codes associated with a bulk coupon
API docs: https://developers.recurly.com/api/v2019-10-10#operation/list_unique_coupon_codes
| parameter | type | description |
|---|---|---|
couponId |
string | Coupon ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-10off
.
|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.ids | Array<string> | Filter results by their IDs. Up to 200 IDs can be passed at once using
commas as separators, e.g.
ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6
.
Important notes:
|
| params.limit | number | Limit number of records 1-200. |
| params.order | string | Sort order. |
| params.sort | string | Sort field. You
really
only want to sort by
updated_at
in ascending
order. In descending order updated records will move behind the cursor and could
prevent some records from being returned.
|
| params.beginTime | Date | Filter by begin_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.endTime | Date | Filter by end_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
Pager<UniqueCouponCode>
:
A list of unique coupon codes that were generated
listCreditPayments
(params)
List a site's credit payments
API docs: https://developers.recurly.com/api/v2019-10-10#operation/list_credit_payments
| parameter | type | description |
|---|---|---|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.limit | number | Limit number of records 1-200. |
| params.order | string | Sort order. |
| params.sort | string | Sort field. You
really
only want to sort by
updated_at
in ascending
order. In descending order updated records will move behind the cursor and could
prevent some records from being returned.
|
| params.beginTime | Date | Filter by begin_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.endTime | Date | Filter by end_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
Pager<CreditPayment>
:
A list of the site's credit payments.
const payments = client.listCreditPayments({ limit: 200 })
for await (const payment of payments.each()) {
console.log(payment.uuid)
}
getCreditPayment
(creditPaymentId)
Fetch a credit payment
API docs: https://developers.recurly.com/api/v2019-10-10#operation/get_credit_payment
| parameter | type | description |
|---|---|---|
creditPaymentId |
string | Credit Payment ID or UUID. For ID no prefix is used e.g.
e28zov4fw0v2
. For UUID use prefix
uuid-
, e.g.
uuid-123457890
.
|
Promise<CreditPayment>
:
A credit payment.
listCustomFieldDefinitions
(params)
List a site's custom field definitions
API docs: https://developers.recurly.com/api/v2019-10-10#operation/list_custom_field_definitions
| parameter | type | description |
|---|---|---|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.ids | Array<string> | Filter results by their IDs. Up to 200 IDs can be passed at once using
commas as separators, e.g.
ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6
.
Important notes:
|
| params.limit | number | Limit number of records 1-200. |
| params.order | string | Sort order. |
| params.sort | string | Sort field. You
really
only want to sort by
updated_at
in ascending
order. In descending order updated records will move behind the cursor and could
prevent some records from being returned.
|
| params.beginTime | Date | Filter by begin_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.endTime | Date | Filter by end_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.relatedType | string | Filter by related type. |
Pager<CustomFieldDefinition>
:
A list of the site's custom field definitions.
const definitions = client.listCustomFieldDefinitions({ limit: 200 })
for await (const definition of definitions.each()) {
console.log(definition.displayName)
}
getCustomFieldDefinition
(customFieldDefinitionId)
Fetch an custom field definition
API docs: https://developers.recurly.com/api/v2019-10-10#operation/get_custom_field_definition
| parameter | type | description |
|---|---|---|
customFieldDefinitionId |
string | Custom Field Definition ID |
Promise<CustomFieldDefinition>
:
An custom field definition.
try {
const definition = await client.getCustomFieldDefinition(definitionId)
console.log('Fetched custom field definition: ', definition.displayName)
} catch (err) {
if (err instanceof recurly.errors.NotFoundError) {
// If the request was not found, you may want to alert the user or
// just return null
console.log('Resource Not Found')
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
listItems
(params)
List a site's items
API docs: https://developers.recurly.com/api/v2019-10-10#operation/list_items
| parameter | type | description |
|---|---|---|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.ids | Array<string> | Filter results by their IDs. Up to 200 IDs can be passed at once using
commas as separators, e.g.
ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6
.
Important notes:
|
| params.limit | number | Limit number of records 1-200. |
| params.order | string | Sort order. |
| params.sort | string | Sort field. You
really
only want to sort by
updated_at
in ascending
order. In descending order updated records will move behind the cursor and could
prevent some records from being returned.
|
| params.beginTime | Date | Filter by begin_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.endTime | Date | Filter by end_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.state | string | Filter by state. |
Pager<Item>
:
A list of the site's items.
const items = client.listItems({ limit: 200 })
for await (const item of items.each()) {
console.log(item.code)
}
createItem
(body)
Create a new item
API docs: https://developers.recurly.com/api/v2019-10-10#operation/create_item
| parameter | type | description |
|---|---|---|
body |
ItemCreate | The object representing the JSON request to send to the server. It should conform to the schema of {ItemCreate} |
Promise<Item>
:
A new item.
try {
const itemCreate = {
code: itemCode,
name: "Item Name",
description: "Item Description",
external_sku: "a35JE-44",
accounting_code: "item-code-127",
revenue_schedule_type: "at_range_end",
custom_fields: [{
name: "custom-field-1",
value: "Custom Field 1 value"
}]
}
const item = await client.createItem(itemCreate)
console.log('Created Item: ', item.code)
} catch (err) {
if (err instanceof recurly.errors.ValidationError) {
// If the request was not valid, you may want to tell your user
// why. You can find the invalid params and reasons in err.params
console.log('Failed validation', err.params)
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
getItem
(itemId)
Fetch an item
API docs: https://developers.recurly.com/api/v2019-10-10#operation/get_item
| parameter | type | description |
|---|---|---|
itemId |
string | Item ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-red
.
|
Promise<Item>
:
An item.
try {
const item = await client.getItem(itemId)
console.log('Fetched item: ', item.code)
} catch (err) {
if (err instanceof recurly.errors.NotFoundError) {
// If the request was not found, you may want to alert the user or
// just return null
console.log('Resource Not Found')
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
updateItem
(itemId, body)
Update an active item
API docs: https://developers.recurly.com/api/v2019-10-10#operation/update_item
| parameter | type | description |
|---|---|---|
itemId |
string | Item ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-red
.
|
body |
ItemUpdate | The object representing the JSON request to send to the server. It should conform to the schema of {ItemUpdate} |
Promise<Item>
:
The updated item.
try {
const itemUpdate = {
name: 'New Item Name',
description: 'New Item Description'
}
const item = await client.updateItem(itemId, itemUpdate)
console.log('Updated item: ', item)
} catch (err) {
if (err instanceof recurly.errors.ValidationError) {
// If the request was not valid, you may want to tell your user
// why. You can find the invalid params and reasons in err.params
console.log('Failed validation', err.params)
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
deactivateItem
(itemId)
Deactivate an item
API docs: https://developers.recurly.com/api/v2019-10-10#operation/deactivate_item
| parameter | type | description |
|---|---|---|
itemId |
string | Item ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-red
.
|
Promise<Item>
:
An item.
try {
const item = await client.deactivateItem(itemId)
console.log('Deleted item: ', item.code)
} catch (err) {
if (err && err.type === 'not-found') {
// If the request was not found, you may want to alert the user or
// just return null
console.log('Resource Not Found')
}
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
throw err
}
reactivateItem
(itemId)
Reactivate an inactive item
API docs: https://developers.recurly.com/api/v2019-10-10#operation/reactivate_item
| parameter | type | description |
|---|---|---|
itemId |
string | Item ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-red
.
|
Promise<Item>
:
An item.
try {
const item = await client.reactivateItem(itemId)
console.log('Reactivated item: ', item.code)
} catch (err) {
if (err && err.type === 'not_found') {
// If the request was not found, you may want to alert the user or
// just return null
console.log('Resource Not Found')
}
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
throw err
}
listInvoices
(params)
List a site's invoices
API docs: https://developers.recurly.com/api/v2019-10-10#operation/list_invoices
| parameter | type | description |
|---|---|---|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.ids | Array<string> | Filter results by their IDs. Up to 200 IDs can be passed at once using
commas as separators, e.g.
ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6
.
Important notes:
|
| params.limit | number | Limit number of records 1-200. |
| params.order | string | Sort order. |
| params.sort | string | Sort field. You
really
only want to sort by
updated_at
in ascending
order. In descending order updated records will move behind the cursor and could
prevent some records from being returned.
|
| params.beginTime | Date | Filter by begin_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.endTime | Date | Filter by end_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.type | string | Filter by type when:
|
Pager<Invoice>
:
A list of the site's invoices.
const invoices = client.listInvoices({ limit: 200 })
for await (const invoice of invoices.each()) {
console.log(invoice.number)
}
getInvoice
(invoiceId)
Fetch an invoice
API docs: https://developers.recurly.com/api/v2019-10-10#operation/get_invoice
| parameter | type | description |
|---|---|---|
invoiceId |
string | Invoice ID or number. For ID no prefix is used e.g.
e28zov4fw0v2
. For number use prefix
number-
, e.g.
number-1000
.
|
Promise<Invoice>
:
An invoice.
try {
const invoice = await client.getInvoice(invoiceId)
console.log('Fetched Invoice: ', invoice.number)
} catch (err) {
if (err instanceof recurly.errors.NotFoundError) {
// If the request was not found, you may want to alert the user or
// just return null
console.log('Resource Not Found')
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
putInvoice
(invoiceId, body)
Update an invoice
API docs: https://developers.recurly.com/api/v2019-10-10#operation/put_invoice
| parameter | type | description |
|---|---|---|
invoiceId |
string | Invoice ID or number. For ID no prefix is used e.g.
e28zov4fw0v2
. For number use prefix
number-
, e.g.
number-1000
.
|
body |
InvoiceUpdatable | The object representing the JSON request to send to the server. It should conform to the schema of {InvoiceUpdatable} |
Promise<Invoice>
:
An invoice.
try {
const invoiceUpdate = {
customerNotes: "New notes",
termsAndConditions: "New terms and conditions"
}
const invoice = await client.putInvoice(invoiceId, invoiceUpdate)
console.log('Edited invoice: ', invoice.number)
} catch(err) {
if (err instanceof recurly.errors.ValidationError) {
// If the request was not valid, you may want to tell your user
// why. You can find the invalid params and reasons in err.params
console.log('Failed validation', err.params)
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
getInvoicePdf
(invoiceId)
Fetch an invoice as a PDF
API docs: https://developers.recurly.com/api/v2019-10-10#operation/get_invoice_pdf
| parameter | type | description |
|---|---|---|
invoiceId |
string | Invoice ID or number. For ID no prefix is used e.g.
e28zov4fw0v2
. For number use prefix
number-
, e.g.
number-1000
.
|
Promise<BinaryFile>
:
An invoice as a PDF.
try {
const invoice = await client.getInvoicePdf(invoiceId)
console.log('Fetched Invoice: ', invoice)
const filename = `${downloadDirectory}/nodeinvoice-${invoiceId}.pdf`
await fs.writeFile(filename, invoice.data, 'binary', (err) => {
// throws an error, you could also catch it here
if (err) throw err;
// success case, the file was saved
console.log('Saved Invoice PDF to', filename)
})
} catch (err) {
if (err instanceof recurly.errors.NotFoundError) {
// If the request was not found, you may want to alert the user or
// just return null
console.log('Resource Not Found')
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
collectInvoice
(invoiceId, params)
Collect a pending or past due, automatic invoice
API docs: https://developers.recurly.com/api/v2019-10-10#operation/collect_invoice
| parameter | type | description |
|---|---|---|
invoiceId |
string | Invoice ID or number. For ID no prefix is used e.g.
e28zov4fw0v2
. For number use prefix
number-
, e.g.
number-1000
.
|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.body | InvoiceCollect | The object representing the JSON request to send to the server. It should conform to the schema of {InvoiceCollect} |
Promise<Invoice>
:
The updated invoice.
try {
const invoice = await client.collectInvoice(invoiceId)
console.log('Collected invoice: ', invoice.number)
} catch (err) {
if (err instanceof recurly.errors.ValidationError) {
// If the request was not valid, you may want to tell your user
// why. You can find the invalid params and reasons in err.params
console.log('Failed validation', err.params)
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
failInvoice
(invoiceId)
Mark an open invoice as failed
API docs: https://developers.recurly.com/api/v2019-10-10#operation/fail_invoice
| parameter | type | description |
|---|---|---|
invoiceId |
string | Invoice ID or number. For ID no prefix is used e.g.
e28zov4fw0v2
. For number use prefix
number-
, e.g.
number-1000
.
|
Promise<Invoice>
:
The updated invoice.
try {
const invoice = await client.failInvoice(invoiceId)
console.log('Failed invoice: ', invoice.number)
} catch (err) {
if (err instanceof recurly.errors.ValidationError) {
// If the request was not valid, you may want to tell your user
// why. You can find the invalid params and reasons in err.params
console.log('Failed validation', err.params)
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
markInvoiceSuccessful
(invoiceId)
Mark an open invoice as successful
API docs: https://developers.recurly.com/api/v2019-10-10#operation/mark_invoice_successful
| parameter | type | description |
|---|---|---|
invoiceId |
string | Invoice ID or number. For ID no prefix is used e.g.
e28zov4fw0v2
. For number use prefix
number-
, e.g.
number-1000
.
|
Promise<Invoice>
:
The updated invoice.
try {
const invoice = await client.markInvoiceSuccessful(invoiceId)
console.log(`Marked invoice #${invoice.number} successful`)
} catch(err) {
if (err instanceof recurly.errors.ValidationError) {
// If the request was not valid, you may want to tell your user
// why. You can find the invalid params and reasons in err.params
console.log('Failed validation', err.params)
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
reopenInvoice
(invoiceId)
Reopen a closed, manual invoice
API docs: https://developers.recurly.com/api/v2019-10-10#operation/reopen_invoice
| parameter | type | description |
|---|---|---|
invoiceId |
string | Invoice ID or number. For ID no prefix is used e.g.
e28zov4fw0v2
. For number use prefix
number-
, e.g.
number-1000
.
|
Promise<Invoice>
:
The updated invoice.
try {
const invoice = await client.reopenInvoice(invoiceId)
console.log('Reopened invoice: ', invoice.number)
} catch (err) {
if (err instanceof recurly.errors.NotFoundError) {
// If the request was not found, you may want to alert the user or
// just return null
console.log('Resource Not Found')
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
voidInvoice
(invoiceId)
Void a credit invoice.
API docs: https://developers.recurly.com/api/v2019-10-10#operation/void_invoice
| parameter | type | description |
|---|---|---|
invoiceId |
string | Invoice ID or number. For ID no prefix is used e.g.
e28zov4fw0v2
. For number use prefix
number-
, e.g.
number-1000
.
|
Promise<Invoice>
:
The updated invoice.
listInvoiceLineItems
(invoiceId, params)
List an invoice's line items
API docs: https://developers.recurly.com/api/v2019-10-10#operation/list_invoice_line_items
| parameter | type | description |
|---|---|---|
invoiceId |
string | Invoice ID or number. For ID no prefix is used e.g.
e28zov4fw0v2
. For number use prefix
number-
, e.g.
number-1000
.
|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.ids | Array<string> | Filter results by their IDs. Up to 200 IDs can be passed at once using
commas as separators, e.g.
ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6
.
Important notes:
|
| params.limit | number | Limit number of records 1-200. |
| params.order | string | Sort order. |
| params.sort | string | Sort field. You
really
only want to sort by
updated_at
in ascending
order. In descending order updated records will move behind the cursor and could
prevent some records from being returned.
|
| params.beginTime | Date | Filter by begin_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.endTime | Date | Filter by end_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.original | string | Filter by original field. |
| params.state | string | Filter by state field. |
| params.type | string | Filter by type field. |
Pager<LineItem>
:
A list of the invoice's line items.
listInvoiceCouponRedemptions
(invoiceId, params)
Show the coupon redemptions applied to an invoice
API docs: https://developers.recurly.com/api/v2019-10-10#operation/list_invoice_coupon_redemptions
| parameter | type | description |
|---|---|---|
invoiceId |
string | Invoice ID or number. For ID no prefix is used e.g.
e28zov4fw0v2
. For number use prefix
number-
, e.g.
number-1000
.
|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.ids | Array<string> | Filter results by their IDs. Up to 200 IDs can be passed at once using
commas as separators, e.g.
ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6
.
Important notes:
|
| params.sort | string | Sort field. You
really
only want to sort by
updated_at
in ascending
order. In descending order updated records will move behind the cursor and could
prevent some records from being returned.
|
| params.beginTime | Date | Filter by begin_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.endTime | Date | Filter by end_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
Pager<CouponRedemption>
:
A list of the the coupon redemptions associated with the invoice.
refundInvoice
(invoiceId, body)
Refund an invoice
API docs: https://developers.recurly.com/api/v2019-10-10#operation/refund_invoice
| parameter | type | description |
|---|---|---|
invoiceId |
string | Invoice ID or number. For ID no prefix is used e.g.
e28zov4fw0v2
. For number use prefix
number-
, e.g.
number-1000
.
|
body |
InvoiceRefund | The object representing the JSON request to send to the server. It should conform to the schema of {InvoiceRefund} |
Promise<Invoice>
:
Returns the new credit invoice.
try {
const invoiceRefund = {
creditCustomerNotes: "Notes on credits",
type: "amount", // could also be "line_items"
amount: 100
}
const invoice = await client.refundInvoice(invoiceId, invoiceRefund)
console.log('Refunded invoice: ', invoice.number)
} catch(err) {
if (err instanceof recurly.errors.ValidationError) {
// If the request was not valid, you may want to tell your user
// why. You can find the invalid params and reasons in err.params
console.log('Failed validation', err.params)
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
listLineItems
(params)
List a site's line items
API docs: https://developers.recurly.com/api/v2019-10-10#operation/list_line_items
| parameter | type | description |
|---|---|---|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.ids | Array<string> | Filter results by their IDs. Up to 200 IDs can be passed at once using
commas as separators, e.g.
ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6
.
Important notes:
|
| params.limit | number | Limit number of records 1-200. |
| params.order | string | Sort order. |
| params.sort | string | Sort field. You
really
only want to sort by
updated_at
in ascending
order. In descending order updated records will move behind the cursor and could
prevent some records from being returned.
|
| params.beginTime | Date | Filter by begin_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.endTime | Date | Filter by end_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.original | string | Filter by original field. |
| params.state | string | Filter by state field. |
| params.type | string | Filter by type field. |
Pager<LineItem>
:
A list of the site's line items.
const lineItems = client.listLineItems({ limit: 200 })
for await (const item of lineItems.each()) {
console.log(`Item ${item.id} for ${item.amount}`)
}
getLineItem
(lineItemId)
Fetch a line item
API docs: https://developers.recurly.com/api/v2019-10-10#operation/get_line_item
| parameter | type | description |
|---|---|---|
lineItemId |
string | Line Item ID. |
Promise<LineItem>
:
A line item.
try {
const lineItem = await client.getLineItem(lineItemId)
console.log('Fetched line item: ', lineItem.uuid)
} catch (err) {
if (err instanceof recurly.errors.NotFoundError) {
// If the request was not found, you may want to alert the user or
// just return null
console.log('Resource Not Found')
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
removeLineItem
(lineItemId)
Delete an uninvoiced line item
API docs: https://developers.recurly.com/api/v2019-10-10#operation/remove_line_item
| parameter | type | description |
|---|---|---|
lineItemId |
string | Line Item ID. |
Promise<Empty>
:
Line item deleted.
try {
await client.removeLineItem(lineItemId)
console.log('Removed line item: ', lineItemId)
} catch (err) {
if (err instanceof recurly.errors.NotFoundError) {
// If the request was not found, you may want to alert the user or
// just return null
console.log('Resource Not Found')
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
listPlans
(params)
List a site's plans
API docs: https://developers.recurly.com/api/v2019-10-10#operation/list_plans
| parameter | type | description |
|---|---|---|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.ids | Array<string> | Filter results by their IDs. Up to 200 IDs can be passed at once using
commas as separators, e.g.
ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6
.
Important notes:
|
| params.limit | number | Limit number of records 1-200. |
| params.order | string | Sort order. |
| params.sort | string | Sort field. You
really
only want to sort by
updated_at
in ascending
order. In descending order updated records will move behind the cursor and could
prevent some records from being returned.
|
| params.beginTime | Date | Filter by begin_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.endTime | Date | Filter by end_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.state | string | Filter by state. |
Pager<Plan>
:
A list of plans.
const plans = client.listPlans({ limit: 200 })
for await (const plan of plans.each()) {
console.log(plan.code)
}
createPlan
(body)
Create a plan
API docs: https://developers.recurly.com/api/v2019-10-10#operation/create_plan
| parameter | type | description |
|---|---|---|
body |
PlanCreate | The object representing the JSON request to send to the server. It should conform to the schema of {PlanCreate} |
Promise<Plan>
:
A plan.
try {
const planCreate = {
name: 'Monthly Coffee Subscription',
code: planCode,
currencies: [
{
currency: 'USD',
unitAmount: 10000
}
]
}
const plan = await client.createPlan(planCreate)
console.log('Created Plan: ', plan.code)
} catch (err) {
if (err instanceof recurly.errors.ValidationError) {
// If the request was not valid, you may want to tell your user
// why. You can find the invalid params and reasons in err.params
console.log('Failed validation', err.params)
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
getPlan
(planId)
Fetch a plan
API docs: https://developers.recurly.com/api/v2019-10-10#operation/get_plan
| parameter | type | description |
|---|---|---|
planId |
string | Plan ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-gold
.
|
Promise<Plan>
:
A plan.
try {
const plan = await client.getPlan(planId)
console.log('Fetched plan: ', plan.code)
} catch (err) {
if (err instanceof recurly.errors.NotFoundError) {
// If the request was not found, you may want to alert the user or
// just return null
console.log('Resource Not Found')
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
updatePlan
(planId, body)
Update a plan
API docs: https://developers.recurly.com/api/v2019-10-10#operation/update_plan
| parameter | type | description |
|---|---|---|
planId |
string | Plan ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-gold
.
|
body |
PlanUpdate | The object representing the JSON request to send to the server. It should conform to the schema of {PlanUpdate} |
Promise<Plan>
:
A plan.
try {
const planUpdate = {
name: 'New monthly coffee subscription'
}
const plan = await client.updatePlan(planId, planUpdate)
console.log('Updated plan: ', plan.code)
} catch (err) {
if (err instanceof recurly.errors.ValidationError) {
// If the request was not valid, you may want to tell your user
// why. You can find the invalid params and reasons in err.params
console.log('Failed validation', err.params)
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
removePlan
(planId)
Remove a plan
API docs: https://developers.recurly.com/api/v2019-10-10#operation/remove_plan
| parameter | type | description |
|---|---|---|
planId |
string | Plan ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-gold
.
|
Promise<Plan>
:
Plan deleted
try {
const plan = await client.removePlan(planId)
console.log('Removed plan: ', plan.code)
} catch (err) {
if (err instanceof recurly.errors.NotFoundError) {
// If the request was not found, you may want to alert the user or
// just return null
console.log('Resource Not Found')
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
listPlanAddOns
(planId, params)
List a plan's add-ons
API docs: https://developers.recurly.com/api/v2019-10-10#operation/list_plan_add_ons
| parameter | type | description |
|---|---|---|
planId |
string | Plan ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-gold
.
|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.ids | Array<string> | Filter results by their IDs. Up to 200 IDs can be passed at once using
commas as separators, e.g.
ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6
.
Important notes:
|
| params.limit | number | Limit number of records 1-200. |
| params.order | string | Sort order. |
| params.sort | string | Sort field. You
really
only want to sort by
updated_at
in ascending
order. In descending order updated records will move behind the cursor and could
prevent some records from being returned.
|
| params.beginTime | Date | Filter by begin_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.endTime | Date | Filter by end_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.state | string | Filter by state. |
Pager<AddOn>
:
A list of add-ons.
createPlanAddOn
(planId, body)
Create an add-on
API docs: https://developers.recurly.com/api/v2019-10-10#operation/create_plan_add_on
| parameter | type | description |
|---|---|---|
planId |
string | Plan ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-gold
.
|
body |
AddOnCreate | The object representing the JSON request to send to the server. It should conform to the schema of {AddOnCreate} |
Promise<AddOn>
:
An add-on.
getPlanAddOn
(planId, addOnId)
Fetch a plan's add-on
API docs: https://developers.recurly.com/api/v2019-10-10#operation/get_plan_add_on
| parameter | type | description |
|---|---|---|
planId |
string | Plan ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-gold
.
|
addOnId |
string | Add-on ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-gold
.
|
Promise<AddOn>
:
An add-on.
updatePlanAddOn
(planId, addOnId, body)
Update an add-on
API docs: https://developers.recurly.com/api/v2019-10-10#operation/update_plan_add_on
| parameter | type | description |
|---|---|---|
planId |
string | Plan ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-gold
.
|
addOnId |
string | Add-on ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-gold
.
|
body |
AddOnUpdate | The object representing the JSON request to send to the server. It should conform to the schema of {AddOnUpdate} |
Promise<AddOn>
:
An add-on.
removePlanAddOn
(planId, addOnId)
Remove an add-on
API docs: https://developers.recurly.com/api/v2019-10-10#operation/remove_plan_add_on
| parameter | type | description |
|---|---|---|
planId |
string | Plan ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-gold
.
|
addOnId |
string | Add-on ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-gold
.
|
Promise<AddOn>
:
Add-on deleted
listAddOns
(params)
List a site's add-ons
API docs: https://developers.recurly.com/api/v2019-10-10#operation/list_add_ons
| parameter | type | description |
|---|---|---|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.ids | Array<string> | Filter results by their IDs. Up to 200 IDs can be passed at once using
commas as separators, e.g.
ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6
.
Important notes:
|
| params.limit | number | Limit number of records 1-200. |
| params.order | string | Sort order. |
| params.sort | string | Sort field. You
really
only want to sort by
updated_at
in ascending
order. In descending order updated records will move behind the cursor and could
prevent some records from being returned.
|
| params.beginTime | Date | Filter by begin_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.endTime | Date | Filter by end_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.state | string | Filter by state. |
Pager<AddOn>
:
A list of add-ons.
getAddOn
(addOnId)
Fetch an add-on
API docs: https://developers.recurly.com/api/v2019-10-10#operation/get_add_on
| parameter | type | description |
|---|---|---|
addOnId |
string | Add-on ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-gold
.
|
Promise<AddOn>
:
An add-on.
listShippingMethods
(params)
List a site's shipping methods
API docs: https://developers.recurly.com/api/v2019-10-10#operation/list_shipping_methods
| parameter | type | description |
|---|---|---|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.ids | Array<string> | Filter results by their IDs. Up to 200 IDs can be passed at once using
commas as separators, e.g.
ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6
.
Important notes:
|
| params.limit | number | Limit number of records 1-200. |
| params.order | string | Sort order. |
| params.sort | string | Sort field. You
really
only want to sort by
updated_at
in ascending
order. In descending order updated records will move behind the cursor and could
prevent some records from being returned.
|
| params.beginTime | Date | Filter by begin_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.endTime | Date | Filter by end_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
Pager<ShippingMethod>
:
A list of the site's shipping methods.
getShippingMethod
(id)
Fetch a shipping method
API docs: https://developers.recurly.com/api/v2019-10-10#operation/get_shipping_method
| parameter | type | description |
|---|---|---|
id |
string | Shipping Method ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-usps_2-day
.
|
Promise<ShippingMethod>
:
A shipping_method.
listSubscriptions
(params)
List a site's subscriptions
API docs: https://developers.recurly.com/api/v2019-10-10#operation/list_subscriptions
| parameter | type | description |
|---|---|---|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.ids | Array<string> | Filter results by their IDs. Up to 200 IDs can be passed at once using
commas as separators, e.g.
ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6
.
Important notes:
|
| params.limit | number | Limit number of records 1-200. |
| params.order | string | Sort order. |
| params.sort | string | Sort field. You
really
only want to sort by
updated_at
in ascending
order. In descending order updated records will move behind the cursor and could
prevent some records from being returned.
|
| params.beginTime | Date | Filter by begin_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.endTime | Date | Filter by end_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.state | string | Filter by state.
|
Pager<Subscription>
:
A list of the site's subscriptions.
const subscriptions = client.listSubscriptions({ limit: 200 })
for await (const subscription of subscriptions.each()) {
console.log(subscription.uuid)
}
createSubscription
(body)
Create a new subscription
API docs: https://developers.recurly.com/api/v2019-10-10#operation/create_subscription
| parameter | type | description |
|---|---|---|
body |
SubscriptionCreate | The object representing the JSON request to send to the server. It should conform to the schema of {SubscriptionCreate} |
Promise<Subscription>
:
A subscription.
try {
let subscriptionReq = {
planCode: planCode,
currency: `USD`,
account: {
code: accountCode
}
}
let sub = await client.createSubscription(subscriptionReq)
console.log('Created subscription: ', sub.uuid)
} catch (err) {
if (err instanceof recurly.errors.ValidationError) {
// If the request was not valid, you may want to tell your user
// why. You can find the invalid params and reasons in err.params
console.log('Failed validation', err.params)
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
getSubscription
(subscriptionId)
Fetch a subscription
API docs: https://developers.recurly.com/api/v2019-10-10#operation/get_subscription
| parameter | type | description |
|---|---|---|
subscriptionId |
string | Subscription ID or UUID. For ID no prefix is used e.g.
e28zov4fw0v2
. For UUID use prefix
uuid-
, e.g.
uuid-123457890
.
|
Promise<Subscription>
:
A subscription.
try {
const subscription = await client.getSubscription(subscriptionId)
console.log('Fetched subscription: ', subscription.uuid)
} catch (err) {
if (err instanceof recurly.errors.NotFoundError) {
// If the request was not found, you may want to alert the user or
// just return null
console.log('Resource Not Found')
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
modifySubscription
(subscriptionId, body)
Modify a subscription
API docs: https://developers.recurly.com/api/v2019-10-10#operation/modify_subscription
| parameter | type | description |
|---|---|---|
subscriptionId |
string | Subscription ID or UUID. For ID no prefix is used e.g.
e28zov4fw0v2
. For UUID use prefix
uuid-
, e.g.
uuid-123457890
.
|
body |
SubscriptionUpdate | The object representing the JSON request to send to the server. It should conform to the schema of {SubscriptionUpdate} |
Promise<Subscription>
:
A subscription.
try {
const update = {
termsAndConditions: "Some new terms and conditions",
customerNotes: "Some new customer notes"
}
const subscription = await client.modifySubscription(subscriptionId, update)
console.log('Modified subscription: ', subscription.uuid)
} catch(err) {
if (err instanceof recurly.errors.ValidationError) {
// If the request was not valid, you may want to tell your user
// why. You can find the invalid params and reasons in err.params
console.log('Failed validation', err.params)
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
terminateSubscription
(subscriptionId, params)
Terminate a subscription
API docs: https://developers.recurly.com/api/v2019-10-10#operation/terminate_subscription
| parameter | type | description |
|---|---|---|
subscriptionId |
string | Subscription ID or UUID. For ID no prefix is used e.g.
e28zov4fw0v2
. For UUID use prefix
uuid-
, e.g.
uuid-123457890
.
|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.refund | string | The type of refund to perform:
|
Promise<Subscription>
:
An expired subscription.
try {
const subscription = await client.terminateSubscription(subscriptionId)
console.log('Terminated subscription: ', subscription.uuid)
} catch (err) {
if (err instanceof recurly.errors.ValidationError) {
// If the request was not valid, you may want to tell your user
// why. You can find the invalid params and reasons in err.params
console.log('Failed validation', err.params)
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
cancelSubscription
(subscriptionId, params)
Cancel a subscription
API docs: https://developers.recurly.com/api/v2019-10-10#operation/cancel_subscription
| parameter | type | description |
|---|---|---|
subscriptionId |
string | Subscription ID or UUID. For ID no prefix is used e.g.
e28zov4fw0v2
. For UUID use prefix
uuid-
, e.g.
uuid-123457890
.
|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.body | SubscriptionCancel | The object representing the JSON request to send to the server. It should conform to the schema of {SubscriptionCancel} |
Promise<Subscription>
:
A canceled or failed subscription.
try {
let expiredSub = await client.cancelSubscription(subscriptionId)
console.log('Canceled Subscription: ', expiredSub.uuid)
} catch (err) {
if (err instanceof recurly.errors.ValidationError) {
// If the request was not valid, you may want to tell your user
// why. You can find the invalid params and reasons in err.params
console.log('Failed validation', err.params)
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
reactivateSubscription
(subscriptionId)
Reactivate a canceled subscription
API docs: https://developers.recurly.com/api/v2019-10-10#operation/reactivate_subscription
| parameter | type | description |
|---|---|---|
subscriptionId |
string | Subscription ID or UUID. For ID no prefix is used e.g.
e28zov4fw0v2
. For UUID use prefix
uuid-
, e.g.
uuid-123457890
.
|
Promise<Subscription>
:
An active subscription.
try {
const subscription = await client.reactivateSubscription(subscriptionId)
console.log('Reactivated subscription: ', subscription.uuid)
} catch(err) {
if (err instanceof recurly.errors.ValidationError) {
// If the request was not valid, you may want to tell your user
// why. You can find the invalid params and reasons in err.params
console.log('Failed validation', err.params)
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
pauseSubscription
(subscriptionId, body)
Pause subscription
API docs: https://developers.recurly.com/api/v2019-10-10#operation/pause_subscription
| parameter | type | description |
|---|---|---|
subscriptionId |
string | Subscription ID or UUID. For ID no prefix is used e.g.
e28zov4fw0v2
. For UUID use prefix
uuid-
, e.g.
uuid-123457890
.
|
body |
SubscriptionPause | The object representing the JSON request to send to the server. It should conform to the schema of {SubscriptionPause} |
Promise<Subscription>
:
A subscription.
resumeSubscription
(subscriptionId)
Resume subscription
API docs: https://developers.recurly.com/api/v2019-10-10#operation/resume_subscription
| parameter | type | description |
|---|---|---|
subscriptionId |
string | Subscription ID or UUID. For ID no prefix is used e.g.
e28zov4fw0v2
. For UUID use prefix
uuid-
, e.g.
uuid-123457890
.
|
Promise<Subscription>
:
A subscription.
convertTrial
(subscriptionId)
Convert trial subscription
API docs: https://developers.recurly.com/api/v2019-10-10#operation/convert_trial
| parameter | type | description |
|---|---|---|
subscriptionId |
string | Subscription ID or UUID. For ID no prefix is used e.g.
e28zov4fw0v2
. For UUID use prefix
uuid-
, e.g.
uuid-123457890
.
|
Promise<Subscription>
:
A subscription.
getSubscriptionChange
(subscriptionId)
Fetch a subscription's pending change
API docs: https://developers.recurly.com/api/v2019-10-10#operation/get_subscription_change
| parameter | type | description |
|---|---|---|
subscriptionId |
string | Subscription ID or UUID. For ID no prefix is used e.g.
e28zov4fw0v2
. For UUID use prefix
uuid-
, e.g.
uuid-123457890
.
|
Promise<SubscriptionChange>
:
A subscription's pending change.
try {
const change = await client.getSubscriptionChange(subscriptionId)
console.log('Fetched subscription change: ', change.id)
} catch (err) {
if (err instanceof recurly.errors.NotFoundError) {
// If the request was not found, you may want to alert the user or
// just return null
console.log('Resource Not Found')
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
createSubscriptionChange
(subscriptionId, body)
Create a new subscription change
API docs: https://developers.recurly.com/api/v2019-10-10#operation/create_subscription_change
| parameter | type | description |
|---|---|---|
subscriptionId |
string | Subscription ID or UUID. For ID no prefix is used e.g.
e28zov4fw0v2
. For UUID use prefix
uuid-
, e.g.
uuid-123457890
.
|
body |
SubscriptionChangeCreate | The object representing the JSON request to send to the server. It should conform to the schema of {SubscriptionChangeCreate} |
Promise<SubscriptionChange>
:
A subscription change.
try {
const subscriptionChangeCreate = {
planCode: newPlanCode,
timeframe: 'now'
}
const change = await client.createSubscriptionChange(subscriptionId, subscriptionChangeCreate)
console.log('Created subscription change: ', change.id)
} catch (err) {
if (err instanceof recurly.errors.ValidationError) {
// If the request was not valid, you may want to tell your user
// why. You can find the invalid params and reasons in err.params
console.log('Failed validation', err.params)
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
removeSubscriptionChange
(subscriptionId)
Delete the pending subscription change
API docs: https://developers.recurly.com/api/v2019-10-10#operation/remove_subscription_change
| parameter | type | description |
|---|---|---|
subscriptionId |
string | Subscription ID or UUID. For ID no prefix is used e.g.
e28zov4fw0v2
. For UUID use prefix
uuid-
, e.g.
uuid-123457890
.
|
Promise<Empty>
:
Subscription change was deleted.
try {
await client.removeSubscriptionChange(subscriptionId)
console.log('Removed subscription change: ', subscriptionId)
} catch (err) {
if (err instanceof recurly.errors.NotFoundError) {
// If the request was not found, you may want to alert the user or
// just return null
console.log('Resource Not Found')
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
listSubscriptionInvoices
(subscriptionId, params)
List a subscription's invoices
API docs: https://developers.recurly.com/api/v2019-10-10#operation/list_subscription_invoices
| parameter | type | description |
|---|---|---|
subscriptionId |
string | Subscription ID or UUID. For ID no prefix is used e.g.
e28zov4fw0v2
. For UUID use prefix
uuid-
, e.g.
uuid-123457890
.
|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.ids | Array<string> | Filter results by their IDs. Up to 200 IDs can be passed at once using
commas as separators, e.g.
ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6
.
Important notes:
|
| params.limit | number | Limit number of records 1-200. |
| params.order | string | Sort order. |
| params.sort | string | Sort field. You
really
only want to sort by
updated_at
in ascending
order. In descending order updated records will move behind the cursor and could
prevent some records from being returned.
|
| params.beginTime | Date | Filter by begin_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.endTime | Date | Filter by end_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.type | string | Filter by type when:
|
Pager<Invoice>
:
A list of the subscription's invoices.
listSubscriptionLineItems
(subscriptionId, params)
List a subscription's line items
API docs: https://developers.recurly.com/api/v2019-10-10#operation/list_subscription_line_items
| parameter | type | description |
|---|---|---|
subscriptionId |
string | Subscription ID or UUID. For ID no prefix is used e.g.
e28zov4fw0v2
. For UUID use prefix
uuid-
, e.g.
uuid-123457890
.
|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.ids | Array<string> | Filter results by their IDs. Up to 200 IDs can be passed at once using
commas as separators, e.g.
ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6
.
Important notes:
|
| params.limit | number | Limit number of records 1-200. |
| params.order | string | Sort order. |
| params.sort | string | Sort field. You
really
only want to sort by
updated_at
in ascending
order. In descending order updated records will move behind the cursor and could
prevent some records from being returned.
|
| params.beginTime | Date | Filter by begin_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.endTime | Date | Filter by end_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.original | string | Filter by original field. |
| params.state | string | Filter by state field. |
| params.type | string | Filter by type field. |
Pager<LineItem>
:
A list of the subscription's line items.
listSubscriptionCouponRedemptions
(subscriptionId, params)
Show the coupon redemptions for a subscription
API docs: https://developers.recurly.com/api/v2019-10-10#operation/list_subscription_coupon_redemptions
| parameter | type | description |
|---|---|---|
subscriptionId |
string | Subscription ID or UUID. For ID no prefix is used e.g.
e28zov4fw0v2
. For UUID use prefix
uuid-
, e.g.
uuid-123457890
.
|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.ids | Array<string> | Filter results by their IDs. Up to 200 IDs can be passed at once using
commas as separators, e.g.
ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6
.
Important notes:
|
| params.sort | string | Sort field. You
really
only want to sort by
updated_at
in ascending
order. In descending order updated records will move behind the cursor and could
prevent some records from being returned.
|
| params.beginTime | Date | Filter by begin_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.endTime | Date | Filter by end_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
Pager<CouponRedemption>
:
A list of the the coupon redemptions on a subscription.
listTransactions
(params)
List a site's transactions
API docs: https://developers.recurly.com/api/v2019-10-10#operation/list_transactions
| parameter | type | description |
|---|---|---|
params |
Object
= {}
|
The optional url parameters for this request. |
| params.ids | Array<string> | Filter results by their IDs. Up to 200 IDs can be passed at once using
commas as separators, e.g.
ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6
.
Important notes:
|
| params.limit | number | Limit number of records 1-200. |
| params.order | string | Sort order. |
| params.sort | string | Sort field. You
really
only want to sort by
updated_at
in ascending
order. In descending order updated records will move behind the cursor and could
prevent some records from being returned.
|
| params.beginTime | Date | Filter by begin_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.endTime | Date | Filter by end_time when
sort=created_at
or
sort=updated_at
.
Note:
this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
|
| params.type | string | Filter by type field. The value
payment
will return both
purchase
and
capture
transactions.
|
| params.success | string | Filter by success field. |
Pager<Transaction>
:
A list of the site's transactions.
const transactions = client.listTransactions({ limit: 200 })
for await (const transaction of transactions.each()) {
console.log(transaction.uuid)
}
getTransaction
(transactionId)
Fetch a transaction
API docs: https://developers.recurly.com/api/v2019-10-10#operation/get_transaction
| parameter | type | description |
|---|---|---|
transactionId |
string | Transaction ID or UUID. For ID no prefix is used e.g.
e28zov4fw0v2
. For UUID use prefix
uuid-
, e.g.
uuid-123457890
.
|
Promise<Transaction>
:
A transaction.
try {
const transaction = await client.getTransaction(transactionId)
console.log('Fetched transaction: ', transaction.uuid)
} catch (err) {
if (err instanceof recurly.errors.NotFoundError) {
// If the request was not found, you may want to alert the user or
// just return null
console.log('Resource Not Found')
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
getUniqueCouponCode
(uniqueCouponCodeId)
Fetch a unique coupon code
API docs: https://developers.recurly.com/api/v2019-10-10#operation/get_unique_coupon_code
| parameter | type | description |
|---|---|---|
uniqueCouponCodeId |
string | Unique Coupon Code ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-abc-8dh2-def
.
|
Promise<UniqueCouponCode>
:
A unique coupon code.
deactivateUniqueCouponCode
(uniqueCouponCodeId)
Deactivate a unique coupon code
API docs: https://developers.recurly.com/api/v2019-10-10#operation/deactivate_unique_coupon_code
| parameter | type | description |
|---|---|---|
uniqueCouponCodeId |
string | Unique Coupon Code ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-abc-8dh2-def
.
|
Promise<UniqueCouponCode>
:
A unique coupon code.
reactivateUniqueCouponCode
(uniqueCouponCodeId)
Restore a unique coupon code
API docs: https://developers.recurly.com/api/v2019-10-10#operation/reactivate_unique_coupon_code
| parameter | type | description |
|---|---|---|
uniqueCouponCodeId |
string | Unique Coupon Code ID or code. For ID no prefix is used e.g.
e28zov4fw0v2
. For code use prefix
code-
, e.g.
code-abc-8dh2-def
.
|
Promise<UniqueCouponCode>
:
A unique coupon code.
createPurchase
(body)
Create a new purchase
API docs: https://developers.recurly.com/api/v2019-10-10#operation/create_purchase
| parameter | type | description |
|---|---|---|
body |
PurchaseCreate | The object representing the JSON request to send to the server. It should conform to the schema of {PurchaseCreate} |
Promise<InvoiceCollection>
:
Returns the new invoices
try {
let purchaseReq = {
currency: 'USD',
account: {
code: accountCode,
firstName: 'Benjamin',
lastName: 'Du Monde',
billingInfo: {
tokenId: rjsTokenId
}
},
subscriptions: [
{ planCode: planCode },
]
}
let invoiceCollection = await client.createPurchase(purchaseReq)
console.log('Created Charge Invoice: ', invoiceCollection.chargeInvoice)
console.log('Created Credit Invoices: ', invoiceCollection.creditInvoices)
} catch (err) {
if (err instanceof recurly.errors.ValidationError) {
// If the request was not valid, you may want to tell your user
// why. You can find the invalid params and reasons in err.params
console.log('Failed validation', err.params)
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
previewPurchase
(body)
Preview a new purchase
API docs: https://developers.recurly.com/api/v2019-10-10#operation/preview_purchase
| parameter | type | description |
|---|---|---|
body |
PurchaseCreate | The object representing the JSON request to send to the server. It should conform to the schema of {PurchaseCreate} |
Promise<InvoiceCollection>
:
Returns preview of the new invoices
try {
let purchaseReq = {
currency: 'USD',
account: {
firstName: 'Benjamin',
lastName: 'Du Monde',
code: accountCode,
billingInfo: {
tokenId: rjsTokenId
}
},
subscriptions: [
{ planCode: planCode },
]
}
let invoiceCollection = await client.previewPurchase(purchaseReq)
console.log('Preview Charge Invoice: ', invoiceCollection.chargeInvoice)
console.log('Preview Credit Invoices: ', invoiceCollection.creditInvoices)
} catch (err) {
if (err instanceof recurly.errors.ValidationError) {
// If the request was not valid, you may want to tell your user
// why. You can find the invalid params and reasons in err.params
console.log('Failed validation', err.params)
} else {
// If we don't know what to do with the err, we should
// probably re-raise and let our web framework and logger handle it
console.log('Unknown Error: ', err)
}
}
()
This file is automatically created by Recurly's OpenAPI generation process and thus any edits you make by hand will be lost. If you wish to make a change to this file, please create a Github issue explaining the changes you need and we will usher them to the appropriate places.
()
This file is automatically created by Recurly's OpenAPI generation process and thus any edits you make by hand will be lost. If you wish to make a change to this file, please create a Github issue explaining the changes you need and we will usher them to the appropriate places.
Pager
(client, path, params)
The class responsible for pagination.
| parameter | type | description |
|---|---|---|
client |
Client | |
path |
string | |
params |
Object |
eachPage
()
Returns an async iterator over each page of results.
each
()
Returns an async iterator over each resource in results.
count
()
Count the number of resources that match this Pager's filters
Number
:
The count of resources
first
()
Return only the first item. This is efficient because it tells
the server to only return 1 item. You can also use this method
to get the last resource by inverting the order
parameter.
Object
:
The first resource in the list
getCompiledSchema
()
Holds a cached copy of the compiled Schema object for this Resource.
cast
(v)
Can cast a plain js Object to a Resource of this class type
| parameter | type | description |
|---|---|---|
v |
Object | The plain js Object to cast |
Empty
()
A special resource for an empty response
()
This file is automatically created by Recurly's OpenAPI generation process and thus any edits you make by hand will be lost. If you wish to make a change to this file, please create a Github issue explaining the changes you need and we will usher them to the appropriate places.
Account
()
Account
Type: Object
| property | type | description |
|---|---|---|
| address | Address | |
| billTo | string | : An enumerable describing the billing behavior of the account, specifically whether the account is self-paying or will rely on the parent account to pay. |
| billingInfo | BillingInfo | |
| ccEmails | string | : Additional email address that should receive account correspondence. These should be separated only by commas. These CC emails will receive all emails that the
email
field also receives.
|
| code | string | : The unique identifier of the account. This cannot be changed once the account is created. |
| company | string | |
| createdAt | Date | : When the account was created. |
| customFields | Array<CustomField> | : The custom fields will only be altered when they are included in a request. Sending an empty array will not remove any existing values. To remove a field send the name with a null or empty value. |
| deletedAt | Date | : If present, when the account was last marked inactive. |
| string | : The email address used for communicating with this customer. The customer will also use this email address to log into your hosted account management pages. This value does not need to be unique. | |
| exemptionCertificate | string | : The tax exemption certificate number for the account. If the merchant has an integration for the Vertex tax provider, this optional value will be sent in any tax calculation requests for the account. |
| firstName | string | |
| hasActiveSubscription | boolean | : Indicates if the account has an active subscription. |
| hasCanceledSubscription | boolean | : Indicates if the account has a canceled subscription. |
| hasFutureSubscription | boolean | : Indicates if the account has a future subscription. |
| hasLiveSubscription | boolean | : Indicates if the account has a subscription that is either active, canceled, future, or paused. |
| hasPastDueInvoice | boolean | : Indicates if the account has a past due invoice. |
| hasPausedSubscription | boolean | : Indicates if the account has a paused subscription. |
| hostedLoginToken | string | : The unique token for automatically logging the account in to the hosted management pages. You may automatically log the user into their hosted management pages by directing the user to:
https://{subdomain}.recurly.com/account/{hosted_login_token}
.
|
| id | string | |
| lastName | string | |
| object | string | : Object type |
| parentAccountId | string | : The UUID of the parent account associated with this account. |
| preferredLocale | string | : Used to determine the language and locale of emails sent on behalf of the merchant to the customer. |
| shippingAddresses | Array<ShippingAddress> | : The shipping addresses on the account. |
| state | string | : Accounts can be either active or inactive. |
| taxExempt | boolean | : The tax status of the account.
true
exempts tax on the account,
false
applies tax on the account.
|
| updatedAt | Date | : When the account was last changed. |
| username | string | : A secondary value for the account. |
| vatNumber | string | : The VAT number of the account (to avoid having the VAT applied). This is only used for manually collected invoices. |
()
This file is automatically created by Recurly's OpenAPI generation process and thus any edits you make by hand will be lost. If you wish to make a change to this file, please create a Github issue explaining the changes you need and we will usher them to the appropriate places.
AccountAcquisition
()
AccountAcquisition
Type: Object
| property | type | description |
|---|---|---|
| account | AccountMini | : Account mini details |
| campaign | string | : An arbitrary identifier for the marketing campaign that led to the acquisition of this account. |
| channel | string | : The channel through which the account was acquired. |
| cost | AccountAcquisitionCost | : Account balance |
| createdAt | Date | : When the account acquisition data was created. |
| id | string | |
| object | string | : Object type |
| subchannel | string | : An arbitrary subchannel string representing a distinction/subcategory within a broader channel. |
| updatedAt | Date | : When the account acquisition data was last changed. |
()
This file is automatically created by Recurly's OpenAPI generation process and thus any edits you make by hand will be lost. If you wish to make a change to this file, please create a Github issue explaining the changes you need and we will usher them to the appropriate places.
AccountAcquisitionCost
()
AccountAcquisitionCost
Type: Object
| property | type | description |
|---|---|---|
| amount | number | : The amount of the corresponding currency used to acquire the account. |
| currency | string | : 3-letter ISO 4217 currency code. |
()
This file is automatically created by Recurly's OpenAPI generation process and thus any edits you make by hand will be lost. If you wish to make a change to this file, please create a Github issue explaining the changes you need and we will usher them to the appropriate places.
AccountBalance
()
AccountBalance
Type: Object
| property | type | description |
|---|---|---|
| account | AccountMini | : Account mini details |
| balances | Array<AccountBalanceAmount> | |
| object | string | : Object type |
| pastDue | boolean |
()
This file is automatically created by Recurly's OpenAPI generation process and thus any edits you make by hand will be lost. If you wish to make a change to this file, please create a Github issue explaining the changes you need and we will usher them to the appropriate places.
AccountBalanceAmount
()
AccountBalanceAmount
Type: Object
| property | type | description |
|---|---|---|
| amount | number | : Total amount the account is past due. |
| currency | string | : 3-letter ISO 4217 currency code. |
()
This file is automatically created by Recurly's OpenAPI generation process and thus any edits you make by hand will be lost. If you wish to make a change to this file, please create a Github issue explaining the changes you need and we will usher them to the appropriate places.
AccountMini
()
AccountMini
Type: Object
| property | type | description |
|---|---|---|
| billTo | string | |
| code | string | : The unique identifier of the account. |
| company | string | |
| string | : The email address used for communicating with this customer. | |
| firstName | string | |
| id | string | |
| lastName | string | |
| object | string | : Object type |
| parentAccountId | string |
()
This file is automatically created by Recurly's OpenAPI generation process and thus any edits you make by hand will be lost. If you wish to make a change to this file, please create a Github issue explaining the changes you need and we will usher them to the appropriate places.
AccountNote
()
AccountNote
Type: Object
| property | type | description |
|---|---|---|
| accountId | string | |
| createdAt | Date | |
| id | string | |
| message | string | |
| object | string | : Object type |
| user | User |
()
This file is automatically created by Recurly's OpenAPI generation process and thus any edits you make by hand will be lost. If you wish to make a change to this file, please create a Github issue explaining the changes you need and we will usher them to the appropriate places.
AddOn
()
AddOn
Type: Object
| property | type | description |
|---|---|---|
| accountingCode | string | : Accounting code for invoice line items for this add-on. If no value is provided, it defaults to add-on's code. |
| code | string | : The unique identifier for the add-on within its plan. |
| createdAt | Date | : Created at |
| currencies | Array<AddOnPricing> | : Add-on pricing |
| defaultQuantity | number | : Default quantity for the hosted pages. |
| deletedAt | Date | : Deleted at |
| displayQuantity | boolean | : Determines if the quantity field is displayed on the hosted pages for the add-on. |
| externalSku | string | : Optional, stock keeping unit to link the item to other inventory systems. |
| id | string | : Add-on ID |
| item | ItemMini | : Just the important parts. |
| name | string | : Describes your add-on and will appear in subscribers' invoices. |
| object | string | : Object type |
| optional | boolean | : Whether the add-on is optional for the customer to include in their purchase on the hosted payment page. If false, the add-on will be included when a subscription is created through the Recurly UI. However, the add-on will not be included when a subscription is created through the API. |
| planId | string | : Plan ID |
| revenueScheduleType | string | : When this add-on is invoiced, the line item will use this revenue schedule. If
item_code
/
item_id
is part of the request then
revenue_schedule_type
must be absent in the request as the value will be set from the item.
|
| state | string | : Add-ons can be either active or inactive. |
| taxCode | string | : Used by Avalara, Vertex, and Recurly’s EU VAT tax feature. The tax code values are specific to each tax system. If you are using Recurly’s EU VAT feature you can use
unknown
,
physical
, or
digital
.
|
| updatedAt | Date | : Last updated at |
()
This file is automatically created by Recurly's OpenAPI generation process and thus any edits you make by hand will be lost. If you wish to make a change to this file, please create a Github issue explaining the changes you need and we will usher them to the appropriate places.
AddOnMini
()
AddOnMini
Type: Object
| property | type | description |
|---|---|---|
| accountingCode | string | : Accounting code for invoice line items for this add-on. If no value is provided, it defaults to add-on's code. |
| code | string | : The unique identifier for the add-on within its plan. |
| externalSku | string | : Optional, stock keeping unit to link the item to other inventory systems. |
| id | string | : Add-on ID |
| itemId | string | : Item ID |
| name | string | : Describes your add-on and will appear in subscribers' invoices. |
| object | string | : Object type |
()
This file is automatically created by Recurly's OpenAPI generation process and thus any edits you make by hand will be lost. If you wish to make a change to this file, please create a Github issue explaining the changes you need and we will usher them to the appropriate places.
AddOnPricing
()
AddOnPricing
Type: Object
| property | type | description |
|---|---|---|
| currency | string | : 3-letter ISO 4217 currency code. |
| unitAmount | number | : Unit price |
()
This file is automatically created by Recurly's OpenAPI generation process and thus any edits you make by hand will be lost. If you wish to make a change to this file, please create a Github issue explaining the changes you need and we will usher them to the appropriate places.
Address
()
Address
Type: Object
| property | type | description |
|---|---|---|
| city | string | : City |
| country | string | : Country, 2-letter ISO code. |
| firstName | string | : First name |
| lastName | string | : Last name |
| phone | string | : Phone number |
| postalCode | string | : Zip or postal code. |
| region | string | : State or province. |
| street1 | string | : Street 1 |
| street2 | string | : Street 2 |
()
This file is automatically created by Recurly's OpenAPI generation process and thus any edits you make by hand will be lost. If you wish to make a change to this file, please create a Github issue explaining the changes you need and we will usher them to the appropriate places.
BillingInfo
()
BillingInfo
Type: Object
| property | type | description |
|---|---|---|
| accountId | string | |
| address | Address | |
| company | string | |
| createdAt | Date | : When the billing information was created. |
| firstName | string | |
| fraud | FraudInfo | : Most recent fraud result. |
| id | string | |
| lastName | string | |
| object | string | : Object type |
| paymentMethod | PaymentMethod | |
| updatedAt | Date | : When the billing information was last changed. |
| updatedBy | BillingInfoUpdatedBy | |
| valid | boolean | |
| vatNumber | string | : Customer's VAT number (to avoid having the VAT applied). This is only used for automatically collected invoices. |
()
This file is automatically created by Recurly's OpenAPI generation process and thus any edits you make by hand will be lost. If you wish to make a change to this file, please create a Github issue explaining the changes you need and we will usher them to the appropriate places.
BillingInfoUpdatedBy
()
BillingInfoUpdatedBy
Type: Object
| property | type | description |
|---|---|---|
| country | string | : Country of IP address, if known by Recurly. |
| ip | string | : Customer's IP address when updating their billing information. |
()
This file is automatically created by Recurly's OpenAPI generation process and thus any edits you make by hand will be lost. If you wish to make a change to this file, please create a Github issue explaining the changes you need and we will usher them to the appropriate places.
BinaryFile
()
BinaryFile
Type: Object
| property | type | description |
|---|---|---|
| data | string |
()
This file is automatically created by Recurly's OpenAPI generation process and thus any edits you make by hand will be lost. If you wish to make a change to this file, please create a Github issue explaining the changes you need and we will usher them to the appropriate places.
Coupon
()
Coupon
Type: Object
| property | type | description |
|---|---|---|
| appliesToAllPlans | boolean | : The coupon is valid for all plans if true. If false then
plans
and
plans_names
will list the applicable plans.
|
| appliesToNonPlanCharges | boolean | : The coupon is valid for one-time, non-plan charges if true. |
| code | string | : The code the customer enters to redeem the coupon. |
| couponType | string | : Whether the coupon is "single_code" or "bulk". Bulk coupons will require a
unique_code_template
and will generate unique codes through the
/generate
endpoint.
|
| createdAt | Date | : Created at |
| discount | CouponDiscount | : Details of the discount a coupon applies. Will contain a
type
property and one of the following properties:
percent
,
fixed
,
trial
.
|
| duration | string | :
|
| expiredAt | Date | : The date and time the coupon was expired early or reached its
max_redemptions
.
|