gatsby-source-stripe

Source plugin for pulling in data from the Stripe API. Current with Stripe API version 2020-08-27.

This plugin is a source plugin, so it brings in your Stripe data. Use cases for this Stripe source plugin:

• Create an ecommerce store. This plugin allows you to bring your product and SKU data into your Gatsby site at build time to be used with Stripe Checkout.
• Create various dashboards around customers, invoices, etc. Use this plugin to bring in any of the data types listed below.

Do you use this plugin in your Gatsby project? Let us know and we can add it here as an example!

Check out the CHANGELOG for past and upcoming updates.

Install

npm install gatsby-source-stripe

or

yarn add gatsby-source-stripe

How to use

NOTE: You must be using Gatsby version 4.0.0 or greater.

In the plugin options objects' array, specify the object types you would like to get data for. For example, if you'd like to get the lists of data for your Skus and Products, your objects array would look like this: ['Product', 'Sku'].

Additionally, only include your Stripe secret key via a .env file that is not version-controlled. We don't want your key ending up in your version-controlled source code! For enhanced security, you can also create a restricted API key in your Stripe Developer Dashboard. Since this plugin only ever sources data, you can restrict All core resources to Read only, and even turn off access to certain resources that you know you don't use.

Enable downloading files associated with your Stripe Skus and Products by setting downloadFiles to true.

Example:

// In your gatsby-config.js
plugins: [
  {
    resolve: `gatsby-source-stripe`,
    options: {
      objects: ['Balance', 'BalanceTransaction', 'Product', 'ApplicationFee', 'Sku', 'Subscription'],
      secretKey: 'stripe_secret_key_here',
      downloadFiles: true,
    }
  }
]

Supported List of Types

Below is a table with a list of the Stripe types supported in the options' objects array, as well as what Stripe API method the type maps to, and any other additional notes.

| Type | Stripe API Method | Notes | | --- | --- | --- | | Balance | stripe.balance.retrieve() | Not iterable | | BalanceTransaction | stripe.balanceTransactions.list() | None | | Charge | stripe.charges.list() | None | | Customer | stripe.customers.list() | None | | Dispute | stripe.disputes.list() | None | | Event | stripe.events.list() | None | | File | stripe.files.list() | None | | FileLink | stripe.fileLinks.list() | None | | PaymentIntent | stripe.paymentIntents.list() | None | | Payout | stripe.payouts.list() | None | | Product | stripe.products.list() | None | | Refund | stripe.refunds.list() | None | | Coupon | stripe.coupons.list() | None | | Invoice | stripe.invoices.list() | None | | InvoiceItem | stripe.invoiceItems.list() | None | | Plan | stripe.plans.list() | None | | Subscription | stripe.subscriptions.list() | None | | Account | stripe.accounts.list() | None | | ApplicationFee | stripe.applicationFees.list() | None | | CountrySpec | stripe.countrySpecs.list() | None | | TopUp | stripe.topUps.list() | None | | Transfer | stripe.transfers.list() | None | | IssuingAuthorization | stripe.issuing.authorizations.list() | Issuing is in closed beta. Can only get data if you have access to the beta. | | IssuingCardholder | stripe.issuing.cardholders.list() | Issuing is in closed beta. Can only get data if you have access to the beta. | | IssuingCard | stripe.issuing.cards.list() | Issuing is in closed beta. Can only get data if you have access to the beta. | | IssuingDispute | stripe.issuing.disputes.list() | Issuing is in closed beta. Can only get data if you have access to the beta. | | IssuingTransaction | stripe.issuing.transactions.list() | Issuing is in closed beta. Can only get data if you have access to the beta. | | TerminalLocation | stripe.terminal.locations.list() | None | | TerminalReader | stripe.terminal.readers.list() | None | | Order | stripe.orders.list() | None | | OrderReturn | stripe.orderReturns.list() | None | | Sku | stripe.skus.list() | None | | SigmaScheduledQueryRun | stripe.sigma.ScheduledQueryRuns.list() | Only works with live secret keys, not test keys | | WebhookEndpoint | stripe.webhookEndpoints.list() | None | | CreditNote | stripe.creditNotes.list() | None | | Review | stripe.reviews.list() | None | | Session | stripe.checkout.sessions.list() | None | | Price | stripe.prices.list() | None | | TaxRate | stripe.taxRates.list() | None | | SetupIntent | stripe.setupIntents.list() | None | | PromotionCode | stripe.promotionCodes.list() | None | | SubscriptionSchedule | stripe.subscriptionSchedules.list() | None | | EarlyFraudWarning | stripe.radar.earlyFraudWarnings.list() | None |

Expanding Objects

Expanding all Stripe objects is tricky, as some objects have a lot of nested sub-objects to expand! We've tried to auto-expand as much of the top-level objects as possible. You can peruse a list of what is expanded per object in the stripeObjects.json file. If we're missing something that you'd like expanded, please create an issue!

Auto-pagination

NOTE: Due to stripe-node's autopagination recommendations this plugin has been tested against v10.13.0 and later. If you experience any issues with earlier versions of Node, please first consider upgrading your Node version. Otherwise, file an issue and we'll try to resolve!

All list responses are fully paginated.

Downloading Files

Setting downloadFiles: true in the plugin configuration enables downloading of images on Sku and Product objects. A Gatsby File node is created for each downloaded file, and references are placed on the localFiles field of their Stripe nodes.

You can give these File nodes to plugins like gatsby-image to create responsive images and/or gatsby-transformer-sharp to process images at build.

How to query with Skus

NOTE: For the example below, be sure that you actually have products with SKUs in your Stripe account, otherwise you will get an error saying: Cannot query field "allStripeSku" on type "Query". With the update to Prices API, the Sku/Order API is now deprecated. If you have an account that uses Prices, see How to query with Prices.

Below is an example query for fetching all your Stripe SKUs. Note that the localFiles will not be there if you didn't specify downloadFiles: true in the plugin options.

{
  allStripeSku {
    edges {
      node {
        id,
        active,
        localFiles {
          id
        }
        product {
          id
        }
      }
    }
  }
}

Just replace "Sku" with any of the types used in your config objects array.

You can also query for a specific Stripe object like this:

{
  stripeCustomer(id: { eq: "customer_id_here" }) {
    id,
    name
  }
}

When using GraphiQL, click on "Docs" in the top-right corner of the screen to explore all of the Stripe data being brought in, including their schemas. Additionally, check out Gatsby's handy GraphQL Reference for information about filtering, sorting, etc.

How to query with Prices

NOTE: With the update to Prices API, the Sku/Order API is now deprecated. If you still have an account that uses Skus, see How to query with Skus.

Below is an example query for fetching all Stripe Prices.

{
allStripePrice {
    edges {
      node {
        id,
        object,
        active,
        billing_scheme,
        product,
        type,
        livemode,
        unit_amount,
        unit_amount_decimal,
        currency
      }
    }
  }
}  

You can add or remove any of the nodes to query for what you need.

Gotchas

This section outlines common questions and issues that other user's have run into and how they were resolved.

"My Subscription objects aren't showing up in my GraphQL results"

This issue comes up when trying to get back all SKU for your account, expecting that products of type service will also be present. As Subscriptions (products of type service) don't have SKUs, they won't show up in the SKU results. To get back those, you must also query for Product objects.

Thus, for those who have Subscription products, we recommend you have an objects array like below.

// In your gatsby-config.js
plugins: [
  {
    resolve: `gatsby-source-stripe`,
    options: {
      objects: ['Sku', 'Product'],
      secretKey: 'stripe_secret_key_here',
      downloadFiles: true,
    }
  }
]

Develop

Would you like to help maintain this project? We would love your help! Checkout issues and look for tags labeled help wanted. Also please check out our CODE OF CONDUCT and our CONTRIBUTING documents.

To set up the project locally, follow these steps:

1. Fork the repo and pull it down locally. For ease of testing, we recommend pulling it into an existing Gatsby project, in a plugins directory.
2. Add the plugin, with options, to gatsby-config.js.
3. Install dependencies by running npm install in the project directory.
4. Run npm run build in the console, to transpile the code for testing and running in your project.
5. Hack away!

Included is an ESLint config to help check the correctness of your changes of your code, and a prettier config to format it. Use them with the corresponding plugins for your editor of choice, or run the tools from the command line with npm run lint and npm run format. Don't forget to format your changes with prettier before submitting a PR!