Storefront

Recharge lets you build your subscription widget for fully custom purchasing experience on any site. This article outlines how to access product, store and setting information from Recharge's CDN on the front end.

📘

Note

This article is only intended for Custom integration store users. The Recharge CDN files described in this article aren't yet available for other platform integrations. Support for BigCommerce and Shopify is coming soon.

Accessing the CDN

A Content Delivery Network ensures that data is reliably available to a website or service no matter where you're accessing it from. The table below outlines what Recharge data is available to you as you build a storefront.

For stores using a Custom integration, the {{external_platform_domain}} is your store’s identifier in Recharge. You can retrieve the identifier from your Recharge merchant portal. For example, if your merchant portal URL is mystore-hl.admin.rechargeapps.com, your store’s identifier is mystore-hl.

The only {{version}} currently supported is 2021-08.

Base URL: https://static.rechargecdn.com/store/{{external_platform_domain}}

File name

Contents

File Path

{product_id}.json

Contains data for specific products.

/product/{{version}}/{{external_product_id}}.json

widget_settings.json

Widget settings for a store. You can customize the subscription widget within Recharge to match the look and feel of your storefront as well as modify the text that appears to your customers.

/{{version}}/widget_settings.json

store_settings.json

Store settings including your store’s currency formatting settings as configured in Shopify or BigCommerce.

/{{version}}/store_settings.json

products.json

Combines data from all three files above.

/product/{{version}}/products.json

CDN URL examples

Platform

Domain

Identifier

custom

diapers-hl

Individual product: https://static.rechargecdn.com/store/diapers-hl/product/2021-08/4771.json

All products: https://static.rechargecdn.com/store/diapers-hl/product/2021-08/products.json

Individual product JSON example

{
    "product":
    {
        "external_product_id": "123",
        "plans":
        [
            {
                "id": 59,
                "discount_amount": "10.00",
                "discount_type": "percentage",
                "sort_order": 1,
                "charge_interval_frequency": 1,
                "interval_unit": "month",
                "order_interval_frequency": 1,
                "type": "subscription",
                "title": "Delivery every month",
                "external_plan_name": "Delivery every month",
                "external_plan_id": 17531071
            }
        ],
        "external_plan_group_id": 18736717,
        "variants":
        [
            {
                "external_variant_id": "37382314983615",
                "option_values":["Small"],
                "prices":
                [
                    {
                        "currency": "USD",
                        "compare_at_price": "40.00",
                        "unit_price": "39.95",
                        "plans":
                        [
                            {
                                "id": 59,
                                "discounted_price": "31.96",
                                "discount_value": "7.99"
                            }
                        ]
                    }
                ]
            }
        ]
    },
    "meta":
    {
        "version": "2021-08"
    }
}

Field

Type

Description

external_product_id

string

The unique identifier for the product in an e-commerce platform like Shopify, BigCommerce, or an external system used by API integrations (headless).

plans[]

array of objects

List of subscription plans for a product as configured in Recharge.

plans[].id

number

Unique identifier for the subscription plan in Recharge.

plans[].discount_amount

string

Subscribe-and-save discount amount.

plants[].discount_type

string

Subscribe-and-save discount type for the amount defined in discount_amount. Currently only percentage is supported.

plans[].sort_order

number

Sort order for the plan.

plans[].charge_interval_frequency

number

Frequency at which the subscriber will be charged.

plans[].interval_unit

string

The unit applied to charge_interval_frequency and order_interval_frequency (day, week, or month). All plans for a product have the same interval_unit.

plans[].order_interval_frequency

number

Frequency at which the subscriber will receive shipments when subscribed to this plan.

plans[].type

string

The type of plan. Possible values are subscription, prepaid, onetime.

plans[].title

string

The title of the plan as defined in Recharge.

plans[].external_plan_name

string

Only applies to Shopify Checkout Integration. Selling Plan name as defined in Shopify by Recharge.

plans[].external_plan_id

number

Only applies to Shopify Checkout Integration. Selling Plan ID as defined in Shopify.

external_plan_group_id

number

Only applies to Shopify Checkout Integration. Selling Plan Group ID as defined in Shopify.

variants[]

array of objects

List of the product's variants.

variants[].external_variant_id

string

Unique identifier for the variant in an e-commerce platform like Shopify, BigCommerce, or an external system used by by API integrations (headless).

variants[].option_values

array of strings

List of the variant's option values.

variants[].prices

array of objects

The variant's price attributes for each currency. Recharge currently only supports one currency per store.

variants[].prices[].currency

string

Three letter currency code in which prices are listed.

variants[].prices[].compare_at_price

string

The original price of the variant before an adjustment or a discount.

variants[].prices[].unit_price

string

The price for the variant after adjusting, usually for a discount.

variants[].prices[].plans[]

array of objects

Array containing the subscribe-and-save price of the variant after applying the discount_amount on the unit_price for each plan.

variants[].prices[].plans[].id

number

Unique identifier for a plan in Recharge.

variants[].prices[].plans[].discounted_price

string

Variant's subscribe-and-save price.

variants[].prices[].plans[].discount_value

string

The variant's subscribe-and-save discount value.

Widget settings

The following section contains the content available in the widget_settings.json file and an example of how the JSON data is structured.

Widget settings JSON example

{
  "widget_settings": {
    "active_color": "#000000",
    "background_color": "#efefef",
    "display_on": "[\"product\"]",
    "first_option": "onetime",
    "font_color": "#040404",
    "form_type": "button",
    "how_it_works": "<strong>How subscriptions work</strong><br>Products are automatically delivered on your schedule. No obligation, modify or cancel your subscription anytime.",
    "learnmore_url": "http://rechargepayments.com/subscribe-with-recharge",
    "learnmore_verbiage": "Learn more...",
    "onetime_message": "One-time purchase",
    "popup_background_color": "#606060",
    "popup_link_color": "#ffffff",
    "popup_text_color": "#e7e7e7",
    "poweredby_url": "http://rechargepayments.com/subscribe-with-recharge",
    "published": "true",
    "select_subscription_first": "false",
    "show_learnmore": "false",
    "show_poweredby": "true",
    "show_subscription_details": "true",
    "show_subscription_details_icon": "true",
    "subscribe_and_save_extended_label": "on every recurring order",
    "subscribe_message": "Subscribe &amp; save",
    "subscribe_without_discount_message": "Subscribe",
    "subscription_details_verbiage": "Subscription details",
    "translations": "{\"days\":\"Days\",\"month\":\"Month\",\"months\":\"Months\",\"week\":\"Week\",\"weeks\":\"Week\"}",
    "widget_charge_every": "Charge every",
    "widget_deliver_every": "Delivery every",
    "widget_icon": "black"
  }
}

Field

Type

Description

active_color

string

HTML Hex code used to set the text color of a selected option

background_color

string

HTML Hex code used to set the the background color of the widget

display_on

string

List of locations where the widget should be displayed

first_option

string

Indicator of the first listed purchase option

font_color

string

HTML Hex code used to set the color of the text

form_type

string

Indicates the form component type

how_it_works

string

HTML for the “How it works" section

learnmore_url

string

URL target for the "Learn More" button

learnmore_verbiage

string

display text for the learn more button

onetime_message

string

Text displayed when a customer chooses to purchase the item as a onetime purchase

popup_background_color

string

HTML Hex code used to set the background color of the popup

popup_link_color

string

HTML Hex code used to set the popup link color

popup_text_color

string

HTML Hex code used to set the popup text color

poweredby_url

string

URL target for the "Powered by" button

published

string

Boolean indicating whether the widget is published

select_subscription_first

string

Boolean indicating whether subscription option is selected by default

show_learnmore

string

Boolean indicating whether "Learn more" section is displayed

show_poweredby

string

Boolean indicating whether "Powered by" section is displayed

show_subscription_details

string

Boolean indicating whether subscription details are displayed

show_subscription_details_icon

string

Boolean indicating whether Recharge icon is displayed in subscription details

subscribe_and_save_extended_label

string

Additional display text for subscribe and save purchase option

subscribe_message

string

Text displayed when a user chooses to purchase the item as a subscription purchase item

subscribe_without_discount_message

string

Text displayed when a user chooses to purchase the item as a subscription purchase item, but no discount is offered

subscription_details_verbiage

string

Text displayed as a link to link to view subscription details

translations

string

Object containing translation options for widget verbiage

widget_charge_every

string

Display text preceding charge interval options

widget_deliver_every

string

Text preceding the available interval options for subscriptions

widget_icon

string

Color of the Recharge icon within the widget. Possible values: White(?), Black(?), white, black

Store Settings

This section outlines all data available in the store_settings.json file and an example of how the JSON data is structured.

Store settings JSON example

{
    "store_settings":
    {
        "external_platform_domain": "recharge-cameo-dev-1.mybigcommerce.com",
        "external_store_hash": "ezugzr2hlz",
        "weight_unit": "grams",
        "store_currency":
        {
            "decimal_separator": ".",
            "currency_code": "USD",
            "currency_symbol_location": "right",
            "thousands_separator": ",",
            "currency_symbol": "$",
            "zero_decimal_currency": false
        },
        "store_identifier": "test-store-sp"
    },
    "meta": {
        "version": "2021-08"
    }
}

Field

Type

Description

external_platform_domain

string

The store’s domain in Shopify or BigCommerce
Does not apply for API Integration stores

external_store_hash

string

Your store’s unique hash in BigCommerce (only applies for BigCommerce)

weight_unit

string

The weight unit for products as defined at the store level in your Shopify or BigCommerce store. For API integration stores, this defaults to grams

store_currency.decimal_separator

string

The decimal separator defined in Shopify or BigCommerce. For Shopify, this is derived from the setting under Settings > General > Store Currency > HTML without currency

For BigCommerce, this is derived from the setting under Store Settings > Currency > Default Currency > Edit.

(Not applicable to API Integration stores)

store_currency.currency_code

string

For API Integrations, the store’s currency code in Recharge

For Shopify and BigCommerce, this is the store’s default currency code in that platform

store_currency.currency_symbol_location

string

The decimal separator defined in Shopify or BigCommerce. For Shopify, this is located under Settings > General > Store Currency > HTML without currency

For BigCommerce, this is located under Store Settings > Currency > Default Currency > Edit

(Not applicable for API Integration)

store_currency.thousands_separator

string

The decimal separator defined in Shopify or BigCommerce. For Shopify, this is located under Settings > General > Store Currency > HTML without currency

For BigCommerce, this is located under Store Settings > Currency > Default Currency > Edit

(Not applicable for API Integration)

store_currency.currency_symbol

string

The decimal separator defined in Shopify or BigCommerce. For Shopify, this is located under Settings > General > Store Currency > *HTML without currency

  • For BigCommerce, this is located under Store Settings > Currency > Default Currency > Edit

store_currency.zero_decimal_currency

boolean

Indicates whether the currency supports decimal places. By default true for the following currencies that don’t support decimal places: BIF, CLP, DJF, GNF, JPY, KMF, KRW, MGA, PYG, RWF, VND, VUV, XAF, XOF, XPF

store_identifier

string

The stores unique identifier in Recharge


Need Help? Contact Us