Join us for the "JavaScript Supply Chain Security" tech talk, presented by VP of Security, Adam Baldwin. 6/20 at 10am PT.Sign up here »


2.0.3 • Public • Published

stripe-chainable Build Status npm package Coverage Status

Syntactic sugar for stripe-node

  .charges(function(err, charges) {
    // 'nuff said
  .since(new Date(2015, 0, 1))
  .please(function(err, balance) {
    // What he said


We believe the folks over at Stripe built an awesome API, but found it a bit lacking when it came to generating boring detailed reports. With that in mind, we designed a set of intuitive methods for crafting beautiful queries.

Indeed, stripe-chainable is intentionally limited in scope and very much complementary to Stripe's module. In fact, it focuses on a single operation: retrieving exactly the bunch of objects you're looking for.


npm install stripe-chainable or yarn add stripe-chainable


Exactly the same as, well, Stripe.

var stripe = require('stripe-chainable')(key[, version]);

Your key goes straight to Stripe's module, not even an internal reference is kept.



Akin to assertion frameworks, stripe-chainable provides keywords to build queries in plain English.

  • and(): pure sugar

  • of(): pure sugar

  • that(): pure sugar

  • since(date): alias for from(), except date is mandatory

  • until([date]): alias for to()

  • entire(): alias for all()

  • for([string]): alias for setAccount() and used for setting customer id, charge id and purpose

  • find([number]): sugar allowing to set a limit

  • last(number): limits results to this value

  • all(): queries the Stripe API until all the objects are returned

  • are(string): sets a status

  • type(string): sets an event type

  • available(): tells the following time-based methods to set available_on instead of created

  • before([mixed]): may be called with a date or used as a synonym for ending_before

  • after([mixed]): may be called with a date or used as a synonym for starting_after

  • from([date]): may be called with a date (inclusive)

  • to([date]): may be called with a date (inclusive)

  • now(): chain with to(), until()

  • include(key): sets the include[] key, Stripe only makes total_count available at the moment

  • setAccount(acct_id): sets the account id to use (for Stripe Connect users)

  • history(): use the Balance history API for this query, in conjuction with one of:

    • charges()
    • refunds()
    • adjustments()
    • applicationFees()
    • applicationFeeRefunds()
    • transfers()
    • transferFailures()
  • The following may be used to set context or execute the query in that context:

    • charges()
    • customers()
    • plans()
    • subcriptions()
    • coupons()
    • invoices()
    • invoiceItems()
    • transfers()
    • applicationFees()
    • accounts()
    • events()
    • bitcoinReceivers()
    • fileUploads()

For executing, a callback must be supplied and an optional progress callback is available as well

  • charges([progress, ]callback)

With the following signatures:

  • progress(current, total)
  • callback(err, objects)

It's often clearer to set context early in a sentence and execute later. These methods may be used for executing a chain:

  • please([progress, ]callback)

Supported objects

  • Charges
    • customer set with for('cus_id'))
  • Customers
  • Plans
  • Coupons
  • Invoices
  • Invoice items
    • customer set with for('cus_id')
  • Applications fees
    • charge set with for('ch_id')
  • Accounts
    • Note: Stripe does not support filtering on this object
  • Events
  • File uploads

Partially supported objects

  • Refunds
    • Strictly through Balance history (refunds().history())
  • Disputes
    • Strictly through adjustments with Balance history (adjustments().history())
  • Transfers
    • status set with are('status'), list of statuses
    • date and recipient are not supported at the moment
  • Balance history (through the history() method)
    • available_on set by preceding time-based methods (from(), to(), etc) by available()
    • type set through object context methods (charges(), refunds(), etc)
    • source set with for('ch_id')
    • currency and transfer are not supported at the moment
  • Bitcoin receivers
    • active, filled and uncaptured_funds are not supported at the moment

Currently unsupported objects

  • Cards
  • Subscriptions
  • Discounts
  • Transfer reversals
  • Application fee refunds
  • Balance
  • Tokens

Objects deprecated by Stripe are unsupported

  • Recipients


Yes, that's feature. Without an s.

The Stripe API limits the number of objects returned to 100. Fair enough, but what if you need more?

  .charges(function(err, charges) {
    // They're all here, automatically queried and concatenated.

Wait, what?

All methods return this, making it possible to chain anything with (almost) anything. Here are a few examples.


  .since(new Date(2015, 0, 1))
    function(current, total) {"%d / %d", current, total);
    function(err, charges) {
      // All charges in 2015 up until now
  .after(new Date(2014, 11, 31))
  .please(function(err, customers) {
    // Last 50 customers created after December 31st 2014
  .please(function(err, transfers) {
    // All pending transfers


  .from(new Date(2015, 3, 1))
  .please(function(err, balance) {
    // Self-explanatory
  .from(new Date(2015, 4, 1))
    function(progress, total) {"%d / %d", progress, total);
    function(err, charges) {
      // Self-explanatory

Does it work?

Yes, according to mocha, chai, sinon and istanbul.

npm install
npm test

Can I use?

Yes, stripe-chainable is MIT licensed.


npm i stripe-chainable

Downloadsweekly downloads









last publish


  • avatar
Report a vulnerability