Billflow Configuration API for customizing Billflow UI elements
Custom elements are possible starting in Billflow v4 beta. This page describes what is available for customization and how it works with examples.
Customizable UI elements
If the out of the box UI elements or text does not fully fit what you need, we've got you covered. This is the list of customizable UIs within the Billflow embeds.
This is how you would create the structure and pass it into the Billflow configuration in the embed code. For each customElement mentioned, refer to the Custom element API section.
/*** You would pass this custom elements object into billflowSettings* with your embed code like the code fragment below.** windows.billflowSettings = {* billing_page_id: 'xxxxxxxxxxxxxx',* options: {* customElements,* }*/constcustomElements= { elements: { pricing: { // define all customizable elements within the pricing table view here tiers: [ { name:"Basic",// your tier name to be customized highlighted: { element: customHighlightedBasic // your custom element for this tier's highlight }, select: { element: customSelectBasic // your custom element for select button for this tier. }, prices: [ { id:"price_1jw91203djejd23",// your Stripe price id displayed in this tier. element: customPrice // your custom element for price item in the table. } ] } ] }, checkout: { // define all customizable elements within the checkout view here prices: [ { id:"price_1jw91203djejd23",// your Stripe price id displayed in this checkout form. description: { element: customDescription,// your custom element for this price description }, price: { element: customPriceDisplay,// your custom element for this price display } } ] } }}
Custom element API
The interface to this custom element api is the same for each element level as follows:
{ type:"div",// Required, the element wrapping element type. props: {},// Optional, the props you'd like to pass to the wrapping element, such as className. render: (props) => { // Optional instead of children, allows you to return HTML with dynamic values.// prop are based on the current element being customized, // data properties would be for example, the Stripe price// object if customzing a price item.console.log("Log the props to see what's available to you", props)const { unit_amount } = props return`<div>${unit_amount} per month</div>` }, children:"Static Text"// Optional instead of render, if you simply want to customize it with static text.}
Examples
There are times when you want to customize the pricing information in the pricing table or even add extra elements to it. We will show you how to do it with the following examples.
Embed: Loader
Pricing: Pricing Items
This section describes how you can customize the Pricing Items like the following example.
To customize a pricing item, you will first create a custom pricing item element like this.
/** Create the custom pricing item */constCustomBasicPrice= { id:"price_HDa0zWHKXsY2sb",// replace with your own Stripe price id element: { type:"div",render: (props) => {// props is the price object in this caseconst { currency,unit_amount,priceRenderer } = props;constprice=priceRenderer({amount: unit_amount ,currency})return`<div>${price} <span>/ mo.</span> <i>Send up to 100,000 emails/mo before overages apply.</i> </div>`; } }}
The id specifies the Stripe price item to customize within the tier.
The element is the custom element you will create.
Element properties
type
Required
string
a valid html type
props
Optional
object
any valid props for the html element, such as class, id, etc.
render
Required
function
a render function that will return the custom content as a string, basic html tags are will work.
Stripe price object is passed to this function from Billflow, you can use the values to create the custom element.
Then you can pass the CustomBasicPrice to the config options.
/** Add the custom pricing item element to Billflow Config options like this. */{ billing_page_id:"5GNX3vmderQxoquHKUPe", options: { elements: { pricing: { tiers: [ { name:"Basic", prices: [ CustomBasicPrice ] } ] } } }}
This section describes how you can customize the Select Plan Button like the following example.
To customize a Select Plan Button, you will first create a custom element like this.
/** Create the custom Enterprise tier button */constCustomEnterpriseButton= { element: { type:"button",// element type props: { // any valid props that Reactjs acceptsonClick: (e) => {e.preventDefault();alert("Trigger a custom action, such as open intercom.") }, id:"custom-button", className:"custom-button sc-csTbgd kglWtV bf-button __full _3NM6Cu2g7QjO6j4WSEYBGp _1RTkeWIbayZ7rSk_0XZ-hN", href:"#" }, children:"Contact Us"// the child element to be rendered in the custom element. } }
Then you can pass the CustomEnterpriseTier to the config options.
/** Add the custom Enterprise tier button element to Billflow Config options like this. */{ billing_page_id:"5GNX3vmderQxoquHKUPe", options: { elements: { pricing: { tiers: [ { name:"Enterprise",// the sb_tier name you want to customize select: CustomEnterpriseButton // customizing the select button for the Custom tier } ] } } }}
This section describes how you can customize the Price Description within the checkout view like the following example.
To customize a price description, you will first create a custom element like this.
constCustomPriceDescription= {"id":"price_HDa0zWHKXsY2sb","description": {"element": {"type":"div","props": {"className":"__custom-description" },"render": (props) => {return`<div> <div>Workflow: First 5 images</div> <div>Explanation of Isolation</div> </div>` } } }}
Then you can pass the CustomPriceDescription to the config options.
/** Add the CustomPriceDescription element to Billflow Config options like this. */{ billing_page_id:"TMXnsJS2S7odVGyIW5Qc", options: { elements: { checkout: { prices: [ CustomPriceDescription,// the custom price description element created above ] } } }}
This section describes how you can customize the Price within the checkout view like the following example.
To customize a checkout price, you will first create a custom element like this.
constCustomCheckoutPrice= { id:"price_HDa0zWHKXsY2sb",// replace with your own Stripe price id price: { element: { type:"div", props: { className:"__custom-amount" },render: (props) => {const { unit_amount,currency,formatters } = props;constamount=formatters.price({ amount: unit_amount, currency });return`<div> <div>${amount} / mo.</div> <div>additional images</div> </div>`; } } }};
Then you can pass the CustomCheckoutPrice to the config options.
/** Add the CustomCheckoutPrice element to Billflow Config options like this. */{ billing_page_id:"TMXnsJS2S7odVGyIW5Qc",// replace with your own billing page id options: { elements: { checkout: { prices: [ CustomCheckoutPrice,// the custom checout price ] } } }}