Nepotistic Pontifex Maximus
    Have ideas to improve npm?Join in the discussion! »


    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






    Unpacked Size

    68.1 kB

    Total Files


    Last publish


    • avatar