Getting Started

Installing

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:

{
  // ...
  "recurly" : "^3.1.1"
  // ...
}

Creating a client

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)

Operations

All operations are async and return promises (except the list* methods which return Pagers). 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
  }
}

Creating Resources

For creating or updating resources, pass a json object to one of the create or update methods. 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 && 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)
  }
}

Pagination

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)

Efficiently Fetch the First or Last Resource

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

Counting Resources

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

Error Handling

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('Failed validation', err.params)
    } 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)
    }
  }
}

HTTP Metadata

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

Webhooks

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>verena@example.com</email>
        <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.

Extends BaseClient

Client (apiKey)

parameter type description
apiKey string The private api key.

Instance Members

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:

  • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)
  • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.
  • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.
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.

Returns

Pager<Site> : A list of sites.

Examples

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 .

Returns

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:

  • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)
  • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.
  • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.
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.

Returns

Pager<Account> : A list of the site's accounts.

Examples

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}

Returns

Promise<Account> : An account.

Examples

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 .

Returns

Promise<Account> : An account.

Examples

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}

Returns

Promise<Account> : An account.

Examples

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 .

Returns

Promise<Account> : An account.

Examples

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 .

Returns

Promise<AccountAcquisition> : An account's acquisition data.

Examples

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}

Returns

Promise<AccountAcquisition> : An account's updated acquisition data.

Examples

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 .

Returns

Promise<Empty> : Acquisition data was succesfully deleted.

Examples

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 .

Returns

Promise<Account> : An account.

Examples

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 .

Returns

Promise<AccountBalance> : An account's balance.

Examples

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 .

Returns

Promise<BillingInfo> : An account's billing information.

Examples

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}

Returns

Promise<BillingInfo> : Updated billing information.

Examples

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 .

Returns

Promise<Empty> : Billing information deleted

Examples

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:

  • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)
  • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.
  • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.
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.

Returns

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 .

Returns

Promise<CouponRedemption> : An active coupon redemption on an account.

Examples

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}

Returns

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 .

Returns

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.

Returns

Pager<CreditPayment> : A list of the account's credit payments.

Examples

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:

  • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)
  • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.
  • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.
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:
  • type=charge, only charge invoices will be returned.
  • type=credit, only credit invoices will be returned.
  • type=non-legacy, only charge and credit invoices will be returned.
  • type=legacy, only legacy invoices will be returned.

Returns

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}

Returns

Promise<InvoiceCollection> : Returns the new invoices.

Examples

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}

Returns

Promise<InvoiceCollection> : Returns the invoice previews.

Examples

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:

  • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)
  • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.
  • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.
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.

Returns

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}

Returns

Promise<LineItem> : Returns the new line item.

Examples

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:

  • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)
  • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.
  • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

Returns

Pager<AccountNote> : A list of an account's notes.

Examples

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.

Returns

Promise<AccountNote> : An account note.

Examples

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:

  • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)
  • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.
  • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.
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.

Returns

Pager<ShippingAddress> : A list of an account's shipping addresses.

Examples

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}

Returns

Promise<ShippingAddress> : Returns the new shipping address.

Examples

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.

Returns

Promise<ShippingAddress> : A shipping address.

Examples

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}

Returns

Promise<ShippingAddress> : The updated shipping address.

Examples

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.

Returns

Promise<Empty> : Shipping address deleted.

Examples

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:

  • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)
  • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.
  • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.
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.
  • When state=active, state=canceled, state=expired, or state=future, subscriptions with states that match the query and only those subscriptions will be returned.
  • When state=in_trial, only subscriptions that have a trial_started_at date earlier than now and a trial_ends_at date later than now will be returned.
  • When state=live, only subscriptions that are in an active, canceled, or future state or are in trial will be returned.

Returns

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:

  • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)
  • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.
  • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.
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.

Returns

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:

  • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)
  • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.
  • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.
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.

Returns

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:

  • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)
  • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.
  • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.
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.

Returns

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:

  • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)
  • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.
  • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.
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.

Returns

Pager<Coupon> : A list of the site's coupons.

Examples

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}

Returns

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 .

Returns

Promise<Coupon> : A coupon.

Examples

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}

Returns

Promise<Coupon> : The updated 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:

  • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)
  • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.
  • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.
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.

Returns

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.

Returns

Pager<CreditPayment> : A list of the site's credit payments.

Examples

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 .

Returns

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:

  • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)
  • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.
  • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.
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.

Returns

Pager<CustomFieldDefinition> : A list of the site's custom field definitions.

Examples

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

Returns

Promise<CustomFieldDefinition> : An custom field definition.

Examples

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:

  • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)
  • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.
  • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.
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.

Returns

Pager<Item> : A list of the site's items.

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}

Returns

Promise<Item> : A new item.

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 .

Returns

Promise<Item> : An item.

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}

Returns

Promise<Item> : The updated item.

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 .

Returns

Promise<Item> : An item.

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 .

Returns

Promise<Item> : An item.

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:

  • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)
  • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.
  • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.
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:
  • type=charge, only charge invoices will be returned.
  • type=credit, only credit invoices will be returned.
  • type=non-legacy, only charge and credit invoices will be returned.
  • type=legacy, only legacy invoices will be returned.

Returns

Pager<Invoice> : A list of the site's invoices.

Examples

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 .

Returns

Promise<Invoice> : An invoice.

Examples

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}

Returns

Promise<Invoice> : An invoice.

Examples

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 .

Returns

Promise<BinaryFile> : An invoice as a PDF.

Examples

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}

Returns

Promise<Invoice> : The updated invoice.

Examples

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 .

Returns

Promise<Invoice> : The updated invoice.

Examples

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 .

Returns

Promise<Invoice> : The updated invoice.

Examples

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 .

Returns

Promise<Invoice> : The updated invoice.

Examples

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 .

Returns

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:

  • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)
  • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.
  • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.
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.

Returns

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:

  • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)
  • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.
  • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.
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.

Returns

Pager<CouponRedemption> : A list of the the coupon redemptions associated with the invoice.

listRelatedInvoices (invoiceId, params)

List an invoice's related credit or charge invoices

API docs: https://developers.recurly.com/api/v2019-10-10#operation/list_related_invoices

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 any = {}

Returns

Pager<Invoice> : A list of the credit or charge invoices associated with the invoice.

Examples

const invoices = client.listRelatedInvoices(invoiceId, { limit: 200 })

for await (const invoice of invoices.each()) {
  console.log(invoice.number)
}

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}

Returns

Promise<Invoice> : Returns the new credit invoice.

Examples

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:

  • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)
  • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.
  • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.
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.

Returns

Pager<LineItem> : A list of the site's line items.

Examples

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.

Returns

Promise<LineItem> : A line item.

Examples

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.

Returns

Promise<Empty> : Line item deleted.

Examples

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:

  • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)
  • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.
  • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.
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.

Returns

Pager<Plan> : A list of plans.

Examples

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}

Returns

Promise<Plan> : A plan.

Examples

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 .

Returns

Promise<Plan> : A plan.

Examples

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}

Returns

Promise<Plan> : A plan.

Examples

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 .

Returns

Promise<Plan> : Plan deleted

Examples

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:

  • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)
  • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.
  • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.
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.

Returns

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}

Returns

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 .

Returns

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}

Returns

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 .

Returns

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:

  • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)
  • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.
  • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.
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.

Returns

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 .

Returns

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:

  • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)
  • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.
  • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.
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.

Returns

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 .

Returns

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:

  • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)
  • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.
  • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.
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.
  • When state=active, state=canceled, state=expired, or state=future, subscriptions with states that match the query and only those subscriptions will be returned.
  • When state=in_trial, only subscriptions that have a trial_started_at date earlier than now and a trial_ends_at date later than now will be returned.
  • When state=live, only subscriptions that are in an active, canceled, or future state or are in trial will be returned.

Returns

Pager<Subscription> : A list of the site's subscriptions.

Examples

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}

Returns

Promise<Subscription> : A subscription.

Examples

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 .

Returns

Promise<Subscription> : A subscription.

Examples

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}

Returns

Promise<Subscription> : A subscription.

Examples

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:
  • full - Performs a full refund of the last invoice for the current subscription term.

  • partial - Prorates a refund based on the amount of time remaining in the current bill cycle.

  • none - Terminates the subscription without a refund.

    In the event that the most recent invoice is a $0 invoice paid entirely by credit, Recurly will apply the credit back to the customer’s account.

    You may also terminate a subscription with no refund and then manually refund specific invoices.

Returns

Promise<Subscription> : An expired subscription.

Examples

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}

Returns

Promise<Subscription> : A canceled or failed subscription.

Examples

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 .

Returns

Promise<Subscription> : An active subscription.

Examples

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}

Returns

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 .

Returns

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 .

Returns

Promise<SubscriptionChange> : A subscription's pending change.

Examples

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}

Returns

Promise<SubscriptionChange> : A subscription change.

Examples

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 .

Returns

Promise<Empty> : Subscription change was deleted.

Examples

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:

  • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)
  • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.
  • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.
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:
  • type=charge, only charge invoices will be returned.
  • type=credit, only credit invoices will be returned.
  • type=non-legacy, only charge and credit invoices will be returned.
  • type=legacy, only legacy invoices will be returned.

Returns

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:

  • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)
  • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.
  • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.
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.

Returns

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:

  • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)
  • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.
  • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.
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.

Returns

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:

  • The ids parameter cannot be used with any other ordering or filtering parameters (limit, order, sort, begin_time, end_time, etc)
  • Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request.
  • Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.
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.

Returns

Pager<Transaction> : A list of the site's transactions.

Examples

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 .

Returns

Promise<Transaction> : A transaction.

Examples

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 .

Returns

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 .

Returns

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 .

Returns

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}

Returns

Promise<InvoiceCollection> : Returns the new invoices

Examples

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}

Returns

Promise<InvoiceCollection> : Returns preview of the new invoices

Examples

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

Instance Members

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

Returns

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.

Returns

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
Extends Resource

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>
deletedAt Date : If present, when the account was last marked inactive.
email 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
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
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
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
createdAt Date : When the account acquisition data was created.
id string
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
balances Array<AccountBalanceAmount>
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
email string : The email address used for communicating with this customer.
firstName string
id string
lastName string
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
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.
id string : Add-on ID
name string : Describes your add-on and will appear in subscribers' invoices.
planId string : Plan ID
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.
id string : Add-on ID
name string : Describes your add-on and will appear in subscribers' 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.

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
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
duration string :
  • "single_use" coupons applies to the first invoice only. - "temporal" coupons will apply to invoices for the duration determined by the temporal_unit and temporal_amount attributes.
expiredAt Date : The date and time the coupon was expired early or reached its max_redemptions .
freeTrialAmount number : Sets the duration of time the free_trial_unit is for.
freeTrialUnit string : Description of the unit of time the coupon is for. Used with free_trial_amount to determine the duration of time the coupon is for.
hostedPageDescription string : This description will show up when a customer redeems a coupon on your Hosted Payment Pages, or if you choose to show the description on your own checkout page.
id string : Coupon ID
invoiceDescription string : Description of the coupon on the invoice.
maxRedemptions number : A maximum number of redemptions for the coupon. The coupon will expire when it hits its maximum redemptions.
maxRedemptionsPerAccount number : Redemptions per account is the number of times a specific account can redeem the coupon. Set redemptions per account to 1 if you want to keep customers from gaming the system and getting more than one discount from the coupon campaign.
name string : The internal name for the coupon.
plans Array<PlanMini> : A list of plans for which this coupon applies. This will be null if applies_to_all_plans=true .
plansNames Array<string> : TODO
redeemBy Date : The date and time the coupon will expire and can no longer be redeemed. Time is always 11:59:59, the end-of-day Pacific time.
redemptionResource string : Whether the discount is for all eligible charges on the account, or only a specific subscription.
state string : Indicates if the coupon is redeemable, and if it is not, why.
temporalAmount number : If duration is "temporal" than temporal_amount is an integer which is multiplied by temporal_unit to define the duration that the coupon will be applied to invoices for.
temporalUnit string : If duration is "temporal" than temporal_unit is multiplied by temporal_amount to define the duration that the coupon will be applied to invoices for.
uniqueCodeTemplate string : On a bulk coupon, the template from which unique coupon codes are generated.
uniqueCouponCodesCount number : When this number reaches max_redemptions the coupon will no longer be redeemable.
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.

CouponDiscount ()

CouponDiscount

Type: Object

property type description
currencies Array<CouponDiscountPricing> : This is only present when type=fixed .
percent number : This is only present when type=percent .
trial CouponDiscountTrial : This is only present when type=free_trial .
type 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.

CouponDiscountPricing ()

CouponDiscountPricing

Type: Object

property type description
amount number : Value of the fixed discount that this coupon applies.
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.

CouponDiscountTrial ()

CouponDiscountTrial

Type: Object

property type description
length number : Trial length measured in the units specified by the sibling unit property
unit string : Temporal unit of the free trial

()

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.

CouponMini ()

CouponMini

Type: Object

property type description
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.
discount CouponDiscount
expiredAt Date : The date and time the coupon was expired early or reached its max_redemptions .
id string : Coupon ID
name string : The internal name for the coupon.
state string : Indicates if the coupon is redeemable, and if it is not, why.

()

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.

CouponRedemption ()

CouponRedemption

Type: Object

property type description
account AccountMini : The Account on which the coupon was applied.
coupon Coupon
createdAt Date : Created at
currency string : 3-letter ISO 4217 currency code.
discounted number : The amount that was discounted upon the application of the coupon, formatted with the currency.
id string : Coupon Redemption ID
removedAt Date : The date and time the redemption was removed from the account (un-redeemed).
state string : Coupon Redemption state
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.

CouponRedemptionMini ()

CouponRedemptionMini

Type: Object

property type description
coupon CouponMini
createdAt Date : Created at
discounted number : The amount that was discounted upon the application of the coupon, formatted with the currency.
id string : Coupon Redemption ID
state string : Invoice state

()

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.

CreditPayment ()

CreditPayment

Type: Object

property type description
account AccountMini
action string : The action for which the credit was created.
amount number : Total credit payment amount applied to the charge invoice.
appliedToInvoice InvoiceMini
createdAt Date : Created at
currency string : 3-letter ISO 4217 currency code.
id string : Credit Payment ID
originalCreditPaymentId string : For credit payments with action refund , this is the credit payment that was refunded.
originalInvoice InvoiceMini
refundTransaction Transaction
updatedAt Date : Last updated at
uuid string : The UUID is useful for matching data with the CSV exports and building URLs into Recurly's UI.
voidedAt Date : Voided 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.

CustomField ()

CustomField

Type: Object

property type description
name string : Fields must be created in the UI before values can be assigned to them.
value string : Any values that resemble a credit card number or security code (CVV/CVC) will be rejected.

()

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.

CustomFieldDefinition ()

CustomFieldDefinition

Type: Object

property type description
createdAt Date : Created at
deletedAt Date : Definitions are initially soft deleted, and once all the values are removed from the accouts or subscriptions, will be hard deleted an no longer visible.
displayName string : Used to label the field when viewing and editing the field in Recurly's admin UI.
id string : Custom field definition ID
name string : Used by the API to identify the field or reading and writing. The name can only be used once per Recurly object type.
relatedType string : Related Recurly object type
tooltip string : Displayed as a tooltip when editing the field in the Recurly admin UI.
updatedAt Date : Last updated at
userAccess string : The access control applied inside Recurly's admin UI: - api_only - No one will be able to view or edit this field's data via the admin UI. - read_only - Users with the Customers role will be able to view this field's data via the admin UI, but editing will only be available via the API. - write - Users with the Customers role will be able to view and edit this field's data via the admin UI.

()

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.

Error ()

Error

Type: Object

property type description
message string : Message
params Array<Object> : Parameter specific errors
type string : 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.

ErrorMayHaveTransaction ()

ErrorMayHaveTransaction

Type: Object

property type description
message string : Message
params Array<Object> : Parameter specific errors
transactionError TransactionError : This is only included on errors with type=transaction .
type string : 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.

FraudInfo ()

FraudInfo

Type: Object

property type description
decision string : Kount decision
riskRulesTriggered Object : Kount rules
score number : Kount score

()

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.

Invoice ()

Invoice

Type: Object

property type description
account AccountMini
address InvoiceAddress
balance number : The outstanding balance remaining on this invoice.
closedAt Date : Date invoice was marked paid or failed.
collectionMethod string : An automatic invoice means a corresponding transaction is run using the account's billing information at the same time the invoice is created. Manual invoices are created without a corresponding transaction. The merchant must enter a manual payment transaction or have the customer pay the invoice with an automatic method, like credit card, PayPal, Amazon, or ACH bank payment.
createdAt Date : Created at
creditPayments Array<CreditPayment> : Credit payments
currency string : 3-letter ISO 4217 currency code.
customerNotes string : This will default to the Customer Notes text specified on the Invoice Settings. Specify custom notes to add or override Customer Notes.
discount number : Total discounts applied to this invoice.
dueAt Date : Date invoice is due. This is the date the net terms are reached.
id string : Invoice ID
lineItems LineItemList
netTerms number : Integer representing the number of days after an invoice's creation that the invoice will become past due. If an invoice's net terms are set to '0', it is due 'On Receipt' and will become past due 24 hours after it’s created. If an invoice is due net 30, it will become past due at 31 days exactly.
number string : If VAT taxation and the Country Invoice Sequencing feature are enabled, invoices will have country-specific invoice numbers for invoices billed to EU countries (ex: FR1001). Non-EU invoices will continue to use the site-level invoice number sequence.
origin string : The event that created the invoice.
paid number : The total amount of successful payments transaction on this invoice.
poNumber string : For manual invoicing, this identifies the PO number associated with the subscription.
previousInvoiceId string : On refund invoices, this value will exist and show the invoice ID of the purchase invoice the refund was created from.
refundableAmount number : The refundable amount on a charge invoice. It will be null for all other invoices.
shippingAddress ShippingAddress
state string : Invoice state
subscriptionIds Array<string> : If the invoice is charging or refunding for one or more subscriptions, these are their IDs.
subtotal number : The summation of charges, discounts, and credits, before tax.
tax number : The total tax on this invoice.
taxInfo TaxInfo
termsAndConditions string : This will default to the Terms and Conditions text specified on the Invoice Settings page in your Recurly admin. Specify custom notes to add or override Terms and Conditions.
total number : The final total on this invoice. The summation of invoice charges, discounts, credits, and tax.
transactions Array<Transaction> : Transactions
type string : Invoices are either charge, credit, or legacy invoices.
updatedAt Date : Last updated at
vatNumber string : VAT registration number for the customer on this invoice. This will come from the VAT Number field in the Billing Info or the Account Info depending on your tax settings and the invoice collection method.
vatReverseChargeNotes string : VAT Reverse Charge Notes only appear if you have EU VAT enabled or are using your own Avalara AvaTax account and the customer is in the EU, has a VAT number, and is in a different country than your own. This will default to the VAT Reverse Charge Notes text specified on the Tax Settings page in your Recurly admin, unless custom notes were created with the original subscription.

()

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.

InvoiceAddress ()

InvoiceAddress

Type: Object

property type description
city string : City
company string : Company
country string : Country, 2-letter ISO code.
firstName string : First name
lastName string : Last name
nameOnAccount string : Name on account
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.

InvoiceCollection ()

InvoiceCollection

Type: Object

property type description
chargeInvoice Invoice
creditInvoices Array<Invoice> : Credit 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.

InvoiceMini ()

InvoiceMini

Type: Object

property type description
id string : Invoice ID
number string : Invoice number
state string : Invoice state
type string : Invoice 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.

Item ()

Item

Type: Object

property type description
accountingCode string : Accounting code for invoice line items.
code string : Unique code to identify the item.
createdAt Date : Created at
currencies Array<Pricing> : Item Pricing
customFields Array<CustomField>
deletedAt Date : Deleted at
description string : Optional, description.
externalSku string : Optional, stock keeping unit to link the item to other inventory systems.
id string : Item ID
name string : This name describes your item and will appear on the invoice when it's purchased on a one time basis.
revenueScheduleType string : Revenue schedule type
state string : The current state of the item.
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 .
taxExempt boolean : true exempts tax on the item, false applies tax on the item.
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.

LineItem ()

LineItem

Type: Object

property type description
account AccountMini
accountingCode string : Internal accounting code to help you reconcile your revenue to the correct ledger. Line items created as part of a subscription invoice will use the plan or add-on's accounting code, otherwise the value will only be present if you define an accounting code when creating the line item.
addOnCode string : If the line item is a charge or credit for an add-on, this is its code.
addOnId string : If the line item is a charge or credit for an add-on this is its ID.
amount number : (quantity * unit_amount) - (discount + tax)
createdAt Date : When the line item was created.
creditApplied number : The amount of credit from this line item that was applied to the invoice.
creditReasonCode string : The reason the credit was given when line item is type=credit .
currency string : 3-letter ISO 4217 currency code.
description string : Description that appears on the invoice. For subscription related items this will be filled in automatically.
discount number : The discount applied to the line item.
endDate Date : If this date is provided, it indicates the end of a time range.
id string : Line item ID
invoiceId string : Once the line item has been invoiced this will be the invoice's ID.
invoiceNumber string : Once the line item has been invoiced this will be the invoice's number. If VAT taxation and the Country Invoice Sequencing feature are enabled, invoices will have country-specific invoice numbers for invoices billed to EU countries (ex: FR1001). Non-EU invoices will continue to use the site-level invoice number sequence.
itemCode string : Unique code to identify an item, when the Catalog feature is enabled.
itemId string : Available when the Catalog feature is enabled.
legacyCategory string : Category to describe the role of a line item on a legacy invoice: - "charges" refers to charges being billed for on this invoice. - "credits" refers to refund or proration credits. This portion of the invoice can be considered a credit memo. - "applied_credits" refers to previous credits applied to this invoice. See their original_line_item_id to determine where the credit first originated. - "carryforwards" can be ignored. They exist to consume any remaining credit balance. A new credit with the same amount will be created and placed back on the account.
origin string : A credit created from an original charge will have the value of the charge's origin.
originalLineItemInvoiceId string : The invoice where the credit originated. Will only have a value if the line item is a credit created from a previous credit, or if the credit was created from a charge refund.
planCode string : If the line item is a charge or credit for a plan or add-on, this is the plan's code.
planId string : If the line item is a charge or credit for a plan or add-on, this is the plan's ID.
previousLineItemId string : Will only have a value if the line item is a credit created from a previous credit, or if the credit was created from a charge refund.
productCode string : For plan-related line items this will be the plan's code, for add-on related line items it will be the add-on's code. For item-related line itmes it will be the item's external_sku .
prorationRate number : When a line item has been prorated, this is the rate of the proration. Proration rates were made available for line items created after March 30, 2017. For line items created prior to that date, the proration rate will be null , even if the line item was prorated.
quantity number : This number will be multiplied by the unit amount to compute the subtotal before any discounts or taxes.
refund boolean : Refund?
refundedQuantity number : For refund charges, the quantity being refunded. For non-refund charges, the total quantity refunded (possibly over multiple refunds).
revenueScheduleType string : Revenue schedule type
shippingAddress ShippingAddress
startDate Date : If an end date is present, this is value indicates the beginning of a billing time range. If no end date is present it indicates billing for a specific date.
state string : Pending line items are charges or credits on an account that have not been applied to an invoice yet. Invoiced line items will always have an invoice_id value.
subscriptionId string : If the line item is a charge or credit for a subscription, this is its ID.
subtotal number : quantity * unit_amount
tax number : The tax amount for the line item.
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 .
taxExempt boolean : true exempts tax on charges, false applies tax on charges. If not defined, then defaults to the Plan and Site settings. This attribute does not work for credits (negative line items). Credits are always applied post-tax. Pre-tax discounts should use the Coupons feature.
taxInfo TaxInfo
taxable boolean : true if the line item is taxable, false if it is not.
type string : Charges are positive line items that debit the account. Credits are negative line items that credit the account.
unitAmount number : Positive amount for a charge, negative amount for a credit.
updatedAt Date : When the line item was last changed.
uuid string : The UUID is useful for matching data with the CSV exports and building URLs into Recurly's UI.

()

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.

LineItemList ()

LineItemList

Type: Object

property type description
data Array<LineItem>
hasMore boolean : Indicates there are more results on subsequent pages.
next string : Path to subsequent page of results.

()

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.

PaymentMethod ()

PaymentMethod

Type: Object

property type description
accountType string : The bank account type. Only present for ACH payment methods.
billingAgreementId string : Billing Agreement identifier. Only present for Amazon or Paypal payment methods.
cardType string : Visa, MasterCard, American Express, Discover, JCB, etc.
expMonth number : Expiration month.
expYear number : Expiration year.
firstSix string : Credit card number's first six digits.
lastFour string : Credit card number's last four digits. Will refer to bank account if payment method is ACH.
routingNumber string : The bank account's routing number. Only present for ACH payment methods.
routingNumberBank string : The bank name of this routing number.

()

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.

Plan ()

Plan

Type: Object

property type description
accountingCode string : Accounting code for invoice line items for the plan. If no value is provided, it defaults to plan's code.
autoRenew boolean : Subscriptions will automatically inherit this value once they are active. If auto_renew is true , then a subscription will automatically renew its term at renewal. If auto_renew is false , then a subscription will expire at the end of its term. auto_renew can be overridden on the subscription record itself.
code string : Unique code to identify the plan. This is used in Hosted Payment Page URLs and in the invoice exports.
createdAt Date : Created at
currencies Array<PlanPricing> : Pricing
deletedAt Date : Deleted at
description string : Optional description, not displayed.
hostedPages PlanHostedPages : Hosted pages settings
id string : Plan ID
intervalLength number : Length of the plan's billing interval in interval_unit .
intervalUnit string : Unit for the plan's billing interval.
name string : This name describes your plan and will appear on the Hosted Payment Page and the subscriber's invoice.
setupFeeAccountingCode string : Accounting code for invoice line items for the plan's setup fee. If no value is provided, it defaults to plan's accounting code.
state string : The current state of the plan.
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 .
taxExempt boolean : true exempts tax on the plan, false applies tax on the plan.
totalBillingCycles number : Automatically terminate subscriptions after a defined number of billing cycles. Number of billing cycles before the plan automatically stops renewing, defaults to null for continuous, automatic renewal.
trialLength number : Length of plan's trial period in trial_units . 0 means no trial .
trialUnit string : Units for the plan's trial period.
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.

PlanHostedPages ()

PlanHostedPages

Type: Object

property type description
bypassConfirmation boolean : If true , the customer will be sent directly to your success_url after a successful signup, bypassing Recurly's hosted confirmation page.
cancelUrl string : URL to redirect to on canceled signup on the hosted payment pages.
displayQuantity boolean : Determines if the quantity field is displayed on the hosted pages for the plan.
successUrl string : URL to redirect to after signup on the hosted payment pages.

()

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.

PlanMini ()

PlanMini

Type: Object

property type description
code string : Unique code to identify the plan. This is used in Hosted Payment Page URLs and in the invoice exports.
id string : Plan ID
name string : This name describes your plan and will appear on the Hosted Payment Page and the subscriber's invoice.

()

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.

PlanPricing ()

PlanPricing

Type: Object

property type description
currency string : 3-letter ISO 4217 currency code.
setupFee number : Amount of one-time setup fee automatically charged at the beginning of a subscription billing cycle. For subscription plans with a trial, the setup fee will be charged at the time of signup. Setup fees do not increase with the quantity of a subscription plan.
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.

Pricing ()

Pricing

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.

Settings ()

Settings

Type: Object

property type description
acceptedCurrencies Array<string>
billingAddressRequirement string :
  • full: Full Address (Street, City, State, Postal Code and Country) - streetzip: Street and Postal Code only - zip: Postal Code only - none: No Address
defaultCurrency string : The default 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.

ShippingAddress ()

ShippingAddress

Type: Object

property type description
accountId string : Account ID
city string
company string
country string : Country, 2-letter ISO code.
createdAt Date : Created at
email string
firstName string
id string : Shipping Address ID
lastName string
nickname string
phone string
postalCode string : Zip or postal code.
region string : State or province.
street1 string
street2 string
updatedAt Date : Updated at
vatNumber 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.

ShippingMethod ()

ShippingMethod

Type: Object

property type description
code string : The internal name used identify the shipping method.
createdAt Date : Created at
deletedAt Date : Deleted at
id string : Shipping Method ID
name string : The name of the shipping method displayed to customers.
taxCode string : Used by Avalara, Vertex, and Recurly’s built-in tax feature. The tax code values are specific to each tax system. If you are using Recurly’s built-in taxes the values are: - FR – Common Carrier FOB Destination - FR022000 – Common Carrier FOB Origin - FR020400 – Non Common Carrier FOB Destination - FR020500 – Non Common Carrier FOB Origin - FR010100 – Delivery by Company Vehicle Before Passage of Title - FR010200 – Delivery by Company Vehicle After Passage of Title - NT – Non-Taxable
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.

ShippingMethodMini ()

ShippingMethodMini

Type: Object

property type description
code string : The internal name used identify the shipping method.
id string : Shipping Method ID
name string : The name of the shipping method displayed to customers.

()

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.

Site ()

Site

Type: Object

property type description
address Address
createdAt Date : Created at
deletedAt Date : Deleted at
features Array<string> : A list of features enabled for the site.
id string : Site ID
mode string : Mode
publicApiKey string : This value is used to configure RecurlyJS to submit tokenized billing information.
settings Settings
subdomain string
updatedAt Date : 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.

Subscription ()

Subscription

Type: Object

property type description
account AccountMini
activatedAt Date : Activated at
addOns Array<SubscriptionAddOn> : Add-ons
addOnsTotal number : Total price of add-ons
autoRenew boolean : Whether the subscription renews at the end of its term.
bankAccountAuthorizedAt Date : Recurring subscriptions paid with ACH will have this attribute set. This timestamp is used for alerting customers to reauthorize in 3 years in accordance with NACHA rules. If a subscription becomes inactive or the billing info is no longer a bank account, this timestamp is cleared.
canceledAt Date : Canceled at
collectionMethod string : Collection method
couponRedemptions Array<CouponRedemptionMini> : Coupon redemptions
createdAt Date : Created at
currency string : 3-letter ISO 4217 currency code.
currentPeriodEndsAt Date : Current billing period ends at
currentPeriodStartedAt Date : Current billing period started at
currentTermEndsAt Date : When the term ends. This is calculated by a plan's interval and total_billing_cycles in a term. Subscription changes with a timeframe=renewal will be applied on this date.
currentTermStartedAt Date : The start date of the term when the first billing period starts. The subscription term is the length of time that a customer will be committed to a subscription. A term can span multiple billing periods.
customFields Array<CustomField>
customerNotes string : Customer notes
expirationReason string : Expiration reason
expiresAt Date : Expires at
id string : Subscription ID
netTerms number : Integer representing the number of days after an invoice's creation that the invoice will become past due. If an invoice's net terms are set to '0', it is due 'On Receipt' and will become past due 24 hours after it’s created. If an invoice is due net 30, it will become past due at 31 days exactly.
pausedAt Date : Null unless subscription is paused or will pause at the end of the current billing period.
pendingChange SubscriptionChange
plan PlanMini
poNumber string : For manual invoicing, this identifies the PO number associated with the subscription.
quantity number : Subscription quantity
remainingBillingCycles number : The remaining billing cycles in the current term.
remainingPauseCycles number : Null unless subscription is paused or will pause at the end of the current billing period.
renewalBillingCycles number : If auto_renew=true , when a term completes, total_billing_cycles takes this value as the length of subsequent terms. Defaults to the plan's total_billing_cycles .
shipping SubscriptionShipping
state string : State
subtotal number : Estimated total, before tax.
termsAndConditions string : Terms and conditions
totalBillingCycles number : The number of cycles/billing periods in a term. When remaining_billing_cycles=0 , if auto_renew=true the subscription will renew and a new term will begin, otherwise the subscription will expire.
trialEndsAt Date : Trial period ends at
trialStartedAt Date : Trial period started at
unitAmount number : Subscription unit price
updatedAt Date : Last updated at
uuid string : The UUID is useful for matching data with the CSV exports and building URLs into Recurly's UI.

()

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.

SubscriptionAddOn ()

SubscriptionAddOn

Type: Object

property type description
addOn AddOnMini
createdAt Date : Created at
expiredAt Date : Expired at
id string : Subscription Add-on ID
quantity number : Add-on quantity
subscriptionId string : Subscription ID
unitAmount number : This is priced in the subscription's currency.
updatedAt Date : 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.

SubscriptionChange ()

SubscriptionChange

Type: Object

property type description
activateAt Date : Activated at
activated boolean : Returns true if the subscription change is activated.
addOns Array<SubscriptionAddOn> : These add-ons will be used when the subscription renews.
createdAt Date : Created at
deletedAt Date : Deleted at
id string : The ID of the Subscription Change.
plan PlanMini
quantity number : Subscription quantity
shipping SubscriptionShipping
subscriptionId string : The ID of the subscription that is going to be changed.
unitAmount number : Unit amount
updatedAt Date : 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.

SubscriptionShipping ()

SubscriptionShipping

Type: Object

property type description
address ShippingAddress
amount number : Subscription's shipping cost
method ShippingMethodMini

()

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.

TaxInfo ()

TaxInfo

Type: Object

property type description
rate number : Rate
region string : Provides the tax region applied on an invoice. For U.S. Sales Tax, this will be the 2 letter state code. For EU VAT this will be the 2 letter country code. For all country level tax types, this will display the regional tax, like VAT, GST, or PST.
type string : Provides the tax type as "vat" for EU VAT, "usst" for U.S. Sales Tax, or the 2 letter country code for country level tax types like Canada, Australia, New Zealand, Israel, and all non-EU European countries.

()

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.

Transaction ()

Transaction

Type: Object

property type description
account AccountMini
amount number : Total transaction amount sent to the payment gateway.
avsCheck string : When processed, result from checking the overall AVS on the transaction.
billingAddress Address
collectedAt Date : Collected at, or if not collected yet, the time the transaction was created.
collectionMethod string : The method by which the payment was collected.
createdAt Date : Created at
currency string : 3-letter ISO 4217 currency code.
customerMessage string : For declined ( success=false ) transactions, the message displayed to the customer.
customerMessageLocale string : Language code for the message
cvvCheck string : When processed, result from checking the CVV/CVC value on the transaction.
gatewayApprovalCode string : Transaction approval code from the payment gateway.
gatewayMessage string : Transaction message from the payment gateway.
gatewayReference string : Transaction reference number from the payment gateway.
gatewayResponseCode string : For declined transactions ( success=false ), this field lists the gateway error code.
gatewayResponseTime number : Time, in seconds, for gateway to process the transaction.
gatewayResponseValues Object : The values in this field will vary from gateway to gateway.
id string : Transaction ID
invoice InvoiceMini
ipAddressCountry string : IP address's country
ipAddressV4 string : IP address provided when the billing information was collected: - When the customer enters billing information into the Recurly.js or Hosted Payment Pages, Recurly records the IP address. - When the merchant enters billing information using the API, the merchant may provide an IP address. - When the merchant enters billing information using the UI, no IP address is recorded.
origin string : Describes how the transaction was triggered.
originalTransactionId string : If this transaction is a refund ( type=refund ), this will be the ID of the original transaction on the invoice being refunded.
paymentGateway TransactionPaymentGateway
paymentMethod PaymentMethod
refunded boolean : Indicates if part or all of this transaction was refunded.
status string : The current transaction status. Note that the status may change, e.g. a pending transaction may become declined or success may later become void .
statusCode string : Status code
statusMessage string : For declined ( success=false ) transactions, the message displayed to the merchant.
subscriptionIds Array<string> : If the transaction is charging or refunding for one or more subscriptions, these are their IDs.
success boolean : Did this transaction complete successfully?
type string :
  • authorization – verifies billing information and places a hold on money in the customer's account. - capture – captures funds held by an authorization and completes a purchase. - purchase – combines the authorization and capture in one transaction. - refund – returns all or a portion of the money collected in a previous transaction to the customer. - verify – a $0 or $1 transaction used to verify billing information which is immediately voided.
uuid string : The UUID is useful for matching data with the CSV exports and building URLs into Recurly's UI.
voidedAt Date : Voided at
voidedByInvoice InvoiceMini

()

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.

TransactionError ()

TransactionError

Type: Object

property type description
category string : Category
code string : Code
merchantAdvice string : Merchant message
message string : Customer message
threeDSecureActionTokenId string : Returned when 3-D Secure authentication is required for a transaction. Pass this value to Recurly.js so it can continue the challenge flow.
transactionId string : Transaction ID

()

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.

TransactionPaymentGateway ()

TransactionPaymentGateway

Type: Object

property type description
id string
name string
type 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.

UniqueCouponCode ()

UniqueCouponCode

Type: Object

property type description
code string : The code the customer enters to redeem the coupon.
createdAt Date : Created at
expiredAt Date : The date and time the coupon was expired early or reached its max_redemptions .
id string : Unique Coupon Code ID
redeemedAt Date : The date and time the unique coupon code was redeemed.
state string : Indicates if the unique coupon code is redeemable or why not.
updatedAt Date : 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.

User ()

User

Type: Object

property type description
createdAt Date
deletedAt Date
email string
firstName string
id string
lastName string
timeZone string

PrimitiveProperty ()

Represents a primitive:

  • String
  • Number
  • Boolean
  • Object (plain js object)
  • Array (of primitives only)

DateProperty ()

Represents a Date in the schema

ResourceProperty (type)

Represents an embedded Resource in the schema

parameter type description
type any

ArrayProperty (type)

Represents an array of other schema properties.

parameter type description
type Property Should be Property for element type

build (typeSig)

Factory method to build a Property from a type signature. You should only create Properties through this method.

parameter type description
typeSig any

Schema (resourceType)

The class responsible a compiled schema.

parameter type description
resourceType Resource the resource type