priceblocs v0.0.11

PriceBlocs beta

PriceBlocs makes it easy for developers to add in payments and billing management to their products through a set of context hooks and components.

• Getting Started
• Workflow
• API

Getting started

• API Keys - Sign up for PriceBlocs and get your publishable API keys.
• Test mode - Enable test mode from within the app to use test Stripe resources for local development.
• Install - Add priceblocs to your project

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

Install

• PriceBlocs is available via npm

npm i --save 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 HOC
  • Pass an api_key and a set of `prices
    • Additional checkout and customer configuration options can also be passed
• Present
  • Access your fetched data via context hooks and use it to present purchase 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 live Stripe resources and checkout
  • prices: set of prices you want to show to customers (live)
• 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 keys should be used for client side requests - they can perform read but not write operations to Stripe
• 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 go throught the Stripe onboarding prompts within the app

import { PriceBlocs } from 'priceblocs'

export default () => {
  const props = {
    api_key: 'PB_pk_test_oYQN',
    prices: ['p_123', 'p_456'],
  }

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

Props

Present

• 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, update and initiate checkout

import { usePriceBlocsContext, getActiveProductPrice } from 'priceblocs'

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>
  )
}

Checkout

• Use the checkout function from context to start a checkout session by passing a single price or collection of prices as an argument

const { checkout } = usePriceBlocsContext()

// Single price
<button onClick={() => checkout(price.id)}>Buy Now</button>
// Price collection
<button onClick={() => checkout({prices: [price.id]})}>Buy Now</button>

Billing

• Use the billing function from context to start a new Stripe billing portal session
• 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 customer parameter into the billing call

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>

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>

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

Form API

Form presentation API