@priceblocs/react-priceblocs-js v0.10.0

React PriceBlocs JS beta

PriceBlocs makes it easy for developers to get started with in-app payments and billing through a set of functional components.

In just a few lines of code you'll be able to:

• Show products and prices
• Initiate checkouts
• Enable billing managment

Everything you need to get started with in-app payments, with less server side code.

• Getting Started
• Workflow
• API
• Examples

Getting started

• API Keys
  • Sign up for PriceBlocs and get your publishable API keys.
• Development
  • Enable test mode within your PriceBlocs settings tab so that you can use Stripe test mode resources in local development.
• Install
  • Add @priceblocs/react-priceblocs-js to your project

Our first set of components and hooks are compatible with React, examples of which you can see below.

Install

• The @priceblocs/react-priceblocs-js functional components are available via npm:

npm i --save @priceblocs/react-priceblocs-js

Quick start

Single price

The quickest way to get started is with a single price:

1. Wrap any part of your app with an authenticated PriceBlocs component. To authenticate, pass your PriceBlocs api_key prop:
   1. In Production: use your live publishable PriceBlocs api key and live Stripe price id (i.e. where livemode is true)
   2. In Development: use your test publishable PriceBlocs api key and test Stripe price id (i.e.where livemode is false)
2. Attach the checkout function to any click handler
3. Pass any price id to the checkout call

import { PriceBlocs } from '@priceblocs/react-priceblocs-js'

export default () => {
  const isProd = process.env.NODE_ENV === 'production'
  const apiKey = isProd ? 'PB_pk_live_*' : 'PB_pk_test_*'
  const price = isProd ? 'price_123' : 'price_456'

  return (
    <PriceBlocs api_key={apiKey}>
      {({ loading, values, checkout }) => {
        if (loading || !values) {
          return null
        }
        return <button onClick={() => checkout(price)}>Buy Now</button>
      }}
    </PriceBlocs>
  )
}

Display product metadata

If you need to display product metadata to the user (e.g name and description) then you can pass one or more prices to the functional component and on initialization. The products associated with the prices will be fetched and the made available via the values object for use within your UI.

import { PriceBlocs } from '@priceblocs/react-priceblocs-js'

export default () => {
  const props =
    process.env.NODE_ENV === 'production'
      ? {
          api_key: 'PB_pk_live_*',
          prices: ['price_123'],
        }
      : {
          api_key: 'PB_pk_test_*',
          prices: ['price_456'],
        }

  return (
    <PriceBlocs {...props}>
      {({ loading, values, checkout }) => {
        if (loading || !values) {
          return null
        }
        /**
         * 1. Destructure products from values
         * 2. Use product attributes
         */
        const { products } = values
        const { name, prices } = products[0]
        const { id } = prices[0]
        return <button onClick={() => checkout(id)}>{`Buy ${name}`}</button>
      }}
    </PriceBlocs>
  )
}

Workflow

There are 3 steps to adding prices and checkout to your app:

• Setup
  • Wrap any part of your app with an authenticated PriceBlocs component
  • Pass an api_key and a set of prices
    • Additional checkout and customer configuration options can also be passed
• Presentation
  • Access your fetched data via context hooks and use it to present product options to your customers
• Checkout
  • Attach the checkout function to any of your price CTA actions to initiate a new checkout session

Setup

• Import PriceBlocs and initialize it with both:
  • api_key: your PriceBlocs publishable API key
    • Use your PB_pk_live_* API key for live Stripe resources and checkout
    • Use your PB_pk_test_* API key for test Stripe resources and checkout
  • prices: set of prices you want to show to customers
• You can also pass additional checkout configuration options like a customer id / email

API keys

• Your PriceBlocs account can have both live and test API key sets
• Each set of API keys has both a public and secret key
• Only public (publishable) keys should be used for client side requests
• Only livemode: true keys can initiate live Stripe checkout charges

• Your connected Stripe account must have charges_enabled in order to initiate a checkout session
  • To achieve this, you will need to complete Stripe's business verification onboarding process

import { PriceBlocs } from '@priceblocs/react-priceblocs-js'

export default () => {
  const props =
    process.env.NODE_ENV === 'production'
      ? {
          api_key: 'PB_pk_live_*',
          prices: ['price_123'],
        }
      : {
          api_key: 'PB_pk_test_*',
          prices: ['price_456'],
        }

  return (
    <PriceBlocs {...props}>
      {({ loading, values }) => {
        if (loading) {
          return <YourLoader />
        } else if (values && values.products && values.products.length > 0) {
          return <YourPricingTable />
        }
        return null
      }}
    </PriceBlocs>
  )
}

Props

Query props

• An optional query object can be passed to fetch associated collections and expand responses
• For example if you wanted to fetch all of a customers invoices, you could pass that parameter within the customer associations array like below.
• To expand part of the customer response itself, you can pass parameters which align to Stripe's customer expand parameters. Read more here about expanding Stripe responses.

{
  api_key: 'PB_pk_test_oYQN',
  prices: ['price_123', 'price_456'],
  customer: 'cus_123',
  query: {
    customer: {
      expand: [
        'default_source',
        'invoice_settings.default_payment_method'
      ],
      associations: [
        'invoices',
        'subscriptions',
        'cards'
      ]
    }
  }
}

• You can then access the associations and expanded properties on the related resource within the context values
• For example, customer associations and expansions are then available on the customer object

const {
  values: {
    customer: { default_source, subscriptions, invoices, cards },
  },
} = usePriceBlocsContext()

Session props

• The sessions field allows you to compose checkout sessions using multiple Stripe resources
• You can pass in one of more session inputs to generate a unique checkout id based on all of the values passed
• The id returned in the response can then be passed in any checkout action call to initiate a new Stripe Checkout session
• All of the values passed in the initial request will be used to initialize a new Checkout session
• For example, a checkout session with multiple line_items and a discount will create a new Checkout session for those items with the disount applied
• This way you can describe one or more checkout sessions from the client and then when you're ready, initiate a checkout session by just passing the checkout id

{
  sessions: [
    {
      line_items: [
        {
          price: 'price_123',
        },
      ],
      discounts: [
        {
          coupon: 'cou_123',
        },
      ],
    },
  ]
}

• The Session input aligns closely to that of the Stripe checkout api which you can see here

Shared configuration (inheritence)

• You can share session configuration options across multiple inputs by setting the field as a sibling to the sessions key.
• For example, let's say you want to apply the same discount to all of the session inputs.
• To do that you would set the discounts as a sibling to sessions like so

{
  sessions: [
    {
      line_items: [
        {
          price: 'price_123',
        },
      ],
    },
    {
      line_items: [
        {
          price: 'price_999',
        },
      ],
    },
  ],
  discounts: [
    {
      coupon: 'cou_123',
    },
  ],
}

Overrides

• However if you wanted override common configuration you would define a more specific configuration within the session input itself like below.
• Here we are sharing discount cou_123 across the first two sessions but then overriding it withing the third session by setting coupon cou_abc
• This ability to override works for every key within the configuration
• The most specific configuration wins

{
  sessions: [
    {
      line_items: [
        {
          price: 'price_123',
        },
      ],
    },
    {
      line_items: [
        {
          price: 'price_999',
        },
      ],
    },
    {
      line_items: [
        {
          price: 'price_456',
        },
      ],
      discounts: [
        {
          coupon: 'cou_abc',
        },
      ],
    },
  ],
  discounts: [
    {
      coupon: 'cou_123',
    },
  ],
}

Config props

• You can configure how the default behavior of the lib internals with the configuration object
• By default the component will fetch data from the PriceBlocs API on mount and when the customer reference changes
• You can override that configuration by passing in a config object

{
  fetch: {
    on_mount: true,
    on_customer_change: true
  }
}

• You can then access the associations and expanded properties on the related resource within the context values
• For example, customer associations and expansions are then available on the customer object

const {
  values: {
    customer: { default_source, subscriptions, invoices, cards },
  },
} = usePriceBlocsContext()

Presentation

• Once initialized, you will be able to access your fetched data via the usePriceBlocsContext context hook
• There are a variety of fields to help you:
  • present price options
  • update context values
  • initiate checkout and billing sessions
  • preview and confirm subscription updates
  • manage checkout cart and more

import {
  usePriceBlocsContext,
  getActiveProductPrice,
} from '@priceblocs/react-priceblocs-js'

const PricingTable = () => {
  const {
    values: { products },
    form: { currency, interval },
    checkout,
  } = usePriceBlocsContext()

  return (
    <div>
      <ul>
        {products.map((product, productIx) => {
          const price = getActiveProductPrice(product, { currency, interval })
          return (
            <li key={product.id}>
              <div>
                <div>{product.name}</div>
                <div>{product.description}</div>
              </div>
              <button onClick={() => checkout({ prices: [price.id] })}>
                Buy Now
              </button>
            </li>
          )
        })}
      </ul>
    </div>
  )
}

refetch

• Use the refetch function to refetch values from the API

const { refetch } = usePriceBlocsContext()

// Single price
<button onClick={() => refetch()}>Refetch</button>

checkout

• Use the checkout function from context to start a checkout session
• The simplest way is to call it with a single price id like so:

const { checkout } = usePriceBlocsContext()
// Single price
<button onClick={() => checkout(price.id)}>Buy Now</button>

• checkout accepts a variety of arguments such as:
  • single price id
  • collection of price ids
  • encrypted session id
  • full Stripe Checkout session configuration

const { checkout } = usePriceBlocsContext()

/**
 * Single price
 */
const price = 'price_123'
<button onClick={() => checkout(price.id)}>Buy Now</button>
/**
 * Session id
 * - session id fetched via PriceBlocs fetchData function
 */
const sessionId = 'cs_live_123'
<button onClick={() => checkout(sessionId)}>Buy Now</button>
/**
 * Pass one or more prices to include multiple products within checkout
 */
const prices = ['price_123', 'price_456']
<button onClick={() => checkout({ prices })}>Buy Now</button>
/**
 * Pass full session configuration object
 */
const session = {
  line_items: [
    {
      price: 'price_123',
    }
  ]
}
<button onClick={() => checkout(session)}>Buy Now</button>

billing

• Use the billing function from context to start a new Stripe billing portal session for one of your customers
• A valid customer id is required to start a new session
• By default, we will use the customer in context if you have initiated PriceBlocs with a valid customer
  • Otherwise you can pass a specific customer id parameter into the billing call
• Your Stripe billing portal can be confiugred within Stripe here

const { billing } = usePriceBlocsContext()

// Use default customer if present
<button onClick={billing}>Manage billing</button>
// Provide a customer to the billing call
<button onClick={() => billing({ customer: 'cus_123' })}>Manage billing</button>

previewInvoice

• Use the previewInvoice function from context to preview what an upcoming invoice for a subscription will look like based on the items passed in the request
• To preview changes against a specific subscription, pass its id as well as a collection of items to preview

const previewData = await previewInvoice({
  subscription: 'sub-123',
  items: [
    {
      price: 'p_123',
    },
  ],
})

• The preview response will include an itemized preview for the upcoming invoice and the raw invoice itself.

Invoice preview

• The preview response includes lineItems, amountItems which describe the invoices details as well as a confirm object which can be passed in a subsequent updateSubscription request to update the associated subscription.

updateSubscription

• Use the updateSubscription function from context to update a customers subscription with the options passed.

const previewData = await updateSubscription({
  id: 'sub-123',
  items: [
    {
      id: "si_123",
      deleted: true,
      clear_usage: true,
    },
    {
      id: "si_456",
      price: "p_B_1"
    },
    {
      price: "p_A_3"
    }
  ]
  proration_data: 12345678
})

• For convenience you can pick the confirm object from the invoicePreview response and use it when calling updateSubscription.
• A proration_date timestamp is included in the preview response so that it too is available to be passed along in the request.

const response = await previewInvoice({
  subscription: 'sub-123',
  items: [
    {
      price: 'p_123',
    },
  ],
})
await updateSubscription(response.preview.confirm)

fetchUsage

• Use the fetchUsage function from context to fetch all of the usage summaries for a subscription item
• Each summary represents multiple usage records over a subscription billing period (e.g., 15 usage records in the month of September).

const previewData = await fetchUsage({
  subscription_item: 'sub-item-123',
})

• The response will include a collection of summary records as well as some aggregate totals.

Usage data

• Each usage summary record describes the amount of usage between the priod start and end date

Period

• Describes the timeframe for the usage summary

reportUsage

• Use the reportUsage function from context to report usage for a particular subscription_item
• e.g. this could be used for counting restricted API calls
• You can specify additional fields like quantity, timestamp, and action

const previewData = await fetchUsage({
  subscription_item: 'sub-item-123',
})

• Each additional field has default values if not specified

setValues

• You can use the setValues function to replace the entire values object in context
• This function is used internally on refetch
• Avoid using this function unless necessary. Calling refetch is better for most use cases.

const {
  setValues,
} = usePriceBlocsContext()

<button onClick={() => setValues({...})}>Set all values</button>

setFieldValue

• You can use the setFieldValue function to update any of the state in context
• This can be useful for updating values such as the interval or currency within the form state to assist with presentation logic
• You can pass a dot path to target nested fields for updates

const {
  setFieldValue,
} = usePriceBlocsContext()

<button onClick={() => setFieldValue('form.interval', 'month')}>Show monthly prices</button>

setError

• You can use the setError function to set the local error object

const {
  setError,
} = usePriceBlocsContext()

<button onClick={() => setError(new Error('Custom error'))}>Set error</button>

API

Context & Hooks

Utils

Constants

Schema

Values API

Product API

This shape is closely aligned to the Stripe products API

Price API

This shape is closely aligned to the Stripe prices API

Price formatting API

• We format the unit_amount of each price so you don't have to.
• This also includes formatting them for a variery of different intervals day | week | month | year
• Each formatted interval is accessible under the intervals key

Customer API

This shape is closely aligned to the Stripe customers API This object will be extended with any additional expanded attributes or associations requested via the initial query props

Form API

Form checkout API

• Object which can be used to store checkout related options like items for purchase.
• These items can be passed along in any checkout call
• These items will also be used as the default collection of prices for an preview invoice request

Form checkout item API

• Closely aligned to the Stripe SubscriptionItem API

Form presentation API

Feature Groups API

Feature API

Product Config API