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

Storefront

📘
Note

Accessing the CDN

CDN URL examples

Widget settings

Store Settings

Need Help? Contact Us

📘Note

Accessing the CDN

CDN URL examples

Widget settings

Store Settings

Need Help? Contact Us

📘
Note