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

Key name	Livemode	Audience	Publishable
PB_sk_live_*	true	Secret	No
PB_pk_live_*	true	Public	Yes
PB_sk_test_*	false	Secret	No
PB_pk_test_*	false	Public	Yes

• 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

Key	Required	Type	Description	Example
api_key	Yes	String	One of your PriceBlocs publishable API key	PB_pk_test_sRADszm...
prices	No	Array	Array of Stripe price ids to fetch	['price_123', 'price_456']
sessions	No	Array	Array of checkout inputs to generate session ids from	[ { line_items: [{price_id: 'price_123'}], ... } ]
success_url	No	String	Redirect location after a successful checkout	https://your-site.com/success
cancel_url	No	String	Redirect location if a user cancels their current checkout session	https://your-site.com/cancel
customer	No	String	Stripe customer id	cu_123
email	No	String	Email for your customer customer. If there is a matching customer within you Stripe account, we will use this to initiate the checkout session in the context of that customer	some.one@email.com
presentation	No	Object	Control the presentation of the response	{ order: 'desc' }
query	No	Object	Fetch associations or expand responses	{ customer: {expand: ['default_source'], associations: ['invoices'] }
values	No	Object	Values to initialize context with and prevent fetch on mount	{products: [...], ...}
config	No	Object	Initial configuration object for the lib internals. Control behavior like fetch on mount or customer change	{ fetch: { on_mount: true, on_customer_change: true }

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

Key	Type	Description
line_items	Array	One or more prices to apply to this checkout session
success_url	string	url to be redirected to after a successful checkout session
cancel_url	string	url to be redirected to when a checkout session is canceled
payment_method_types	array	array of payment method types to use at checkout time
allow_promotion_codes	boolean	whether to allow promotion codes during checkout
discounts	array	Discounts to apply to the checkout. Max 1
billing_address_collection	Object	Whether to collect billing address info
shipping_address_collection	Object	Shipping adddress configuration. Set one or more allowed countries
shipping_worldwide	boolean	Whether shipping options are worldwide
shipping_options	array	Up to 5 shipping rate options to present at checkout time
submit_type	string	Type of copy to use within checkout session
consent_collection	object	Configuration for consent collection related to marketing
after_expiration	object	Configuration for post checkout session expiration
expires_at	number	Timestamp of when to expire the session
adjustable_quantity	object	Configuration object for adjustable quantity
tax_rates	array	Array of tax ids to apply to checkout session
dynamic_tax_rates	array	Array of dynamic tax ids to apply to checkout session
automatic_tax	object	Automatic tax configuration object
client_reference_id	string	Client reference id to attach to payment
tax_id_collection	object	Tax id collection configuration object
payment_intent_data	object	Payment intent confiration object which can control capture method.
trial_period_days	number	Number of days to apply to any line_item's with a recurring price type
trial_end	number	Timestamp of when the trial ends
metadata	object	Key value pair object to attach to the checkout and any resulting subscription / payment intent records
mode	string	What mode the session should be initialized in

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

Key	Type	Description
values	Object	Core pricing resources like products and featureGroups etc.
refetch	Function	Function to refetch values from API using initial props
checkout	Function	Start a checkout session
billing	Function	Start a billing portal session for the provided customer
checkoutAdd	Function	Add a price to the form checkout items
checkoutRemove	Function	Remove a price from the form checkout items
previewInvoice	Function	Request a preview of the next invoice for the subscription
fetchUsage	Function	Fetch usage summary for a subscription line item
reportUsage	Function	Report usage summary for a subscription line item
updateSubscription	Function	Update a subscription with the a collection of updated subscription items
setFieldValue	Function	Update any of the context values
setValues	Function	Update all of the context values
ready	Boolean	True when Stripe has been initialized and consumer can initialize checkout sessions
loading	Boolean	True when fetching
isSubmitting	Boolean	True when submitting
stripe	Object	Stripe instance initialized and available for use in context
error	Error	Any errors in local state
setError	Error	Set error in local state

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.

Key	Description
preview	Itemized invoice preview including confirmation payload
invoice	The raw Stripe invoice which is being previewed

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.

Key	Description
lineItems	A collection which describing the elements of the invoice
amountItems	A collection which describes the total amounts due / credited / paid etc.
confirm	A payload which can be passed in a subscription update request to apply the previewed changes

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.

Key	Description
total_usage	Sum total of all the summary records
total_cost	Total usage multiplied by the cost per unit
unit_amount	Unit amount for the subscription item
unit_cost	Formatted cost amount for a unit amount value
data	Collection of usage summaries

Usage data

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

Key	Description
id	Summary usage record id
invoice	Id of the invoice the summary belongs to
livemode	Whether its a live or test Stripe record
period	Timestamp info for the summary
subscription_item	Subscription item id the usage summary belongs to
total_usage	Sum count of the total usage for that period

Period

• Describes the timeframe for the usage summary

Key	Description
label	Formatted timestamp for the period
start	Unix timestamp for period start
end	Unix timestamp for period end

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

Key	Description	Default
quantity	Formatted timestamp for the period	1
timestamp	Unix timestamp usage recording	Now as unix timestamp
action	Usage action type, can be 'increment' or 'set'	increment

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

Key	Type	Description
PriceBlocs	HOC	Context container
usePriceBlocsContext	Function	Context hook

Utils

Key	Type	Description
getActiveProductPrice	Function	Get the product price based on the current form values for interval and currency
getProductFeatures	Function	Get all features for the provided product
getProductsFeaturesTable	Function	Generate a feature table representation for products in context
getGoodStandingSubscriptions	Function	Filter subscriptions in context to ones with either an active	trialing status

Constants

Key	Type	Description	Example
RECURRING_INTERVALS	Object	A mapping of the 4 recurring intervals	'month'
INTERVAL_LABELS_MAP	Object	A mapping of each interval to it's label	'monthly'
INTERVAL_SHORTHAND_MAP	Object	A mapping of each interval to it's shorthand	'mo'

Schema

Values API

Key	Type	Description
products	Array	An array of products
customer	Object	A Stripe customer
form	Object	Form state values like currencies and intervals to help with presentation
featureGroups	Array	An array of feature groups

Product API

This shape is closely aligned to the Stripe products API

Key	Description
name	Name of the product
description	Description of the product
prices	Array of Stripe prices
features	Array of features associated with the product

Price API

This shape is closely aligned to the Stripe prices API

Key	Description
id	Stripe price id
unit_amount	Unit amount for the price
currency	Stripe price id
product	Stripe product id which the price belongs to
formatted	Formatted price values
symbol	Currency symbol for this price

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

Key	Description	Example
unit_amount	Formatted version of the unit amount	12000 -> $120.00
intervals	Price formatted for different intervals [day, week, month, year]. e.g a yearly price presented as a per month cost	{ day: "$0.33", week: "$2.31", month: "$10.00", year: "$120.00"}

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

Key	Present	Required	ation
id	always	ID of the Customer
email	always	Email of the Customer
invoices	conditionally	Array of this Customer's Stripe invoices
subscriptions	conditionally	Array of this Customer's Stripe subscriptions
cards	conditionally	Array of this Customer's Stripe cards

Form API

Key	Description	Example
interval	The default interval based on prices in config response	'month'
intervals	Set of intervals for prices in response	['month', 'year']
currency	The default currency based on prices in config response	'usd'
currencies	Set of intervals for prices in response	['usd','eur']
usage_types	Set of usage_types for prices in response	['licensed']
checkout	The checkout object which contains purchasable prices	{items: [{price: {id: 'price_123'}}]}
presentation	Presentation values for ationform	{interval: "month"}

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

Key	Description
items	Array of checkout items

Form checkout item API

• Closely aligned to the Stripe SubscriptionItem API

Key	Required	Description
price	yes	Object with price id
quantity	no	Quantity of price

Form presentation API

Key	Description	Example
interval	The interval presentation interval. For example 'month' will present all amounts in terms of per month pricing, so a $120 per year price will be presented as $10 per month	'month'

Feature Groups API

Key	Present	Description	Example
uuid	always	UUID for the feature group	847169d9-05bf-485f-8d01-637189e9c9a1
title	always	Title for the feature group	Analytics & Reports
features	conditionally	Array of Features included in the feature group

Feature API

Key	Description	Example
uuid	UUID of the feature group	f0ecdee3-579f-4a9f-aeba-92ff9dbaa767
title	Report generator	Analytics & Reports
description	Generate monthly financial reports	Analytics & Reports

Product Config API

Key	Type	Description	Example
enabled	boolean	UUID of the feature group	true
value	string	Value for the config	Limit 100 runs a month
tooltip	string	Optional tooltip for feature	Custom scheduling allowed