Directory
DevelopersSupportContact usBook demo
Start typing to search…

Widget API

Comprehensive reference for the Recurly Commerce storefront widget API, including endpoints, full JSON payload examples, and configuration details.

Overview

Prerequisites & limitations

  • Requires a live Recurly Commerce integration on Shopify with storefront widget enabled.
  • Only available for stores using Recurly Commerce Subscription Offers.

Definition

The Widget API provides RESTful endpoints and JSON payloads that expose:

  1. Product details and selling plan groups.
  2. Individual selling plan definitions (frequency, pricing, discounts, gifting).
  3. Store theme and widget styling settings.

Key benefits

  • Dynamic storefront integration: Retrieve up-to-date subscription options directly in your theme.
  • Full subscription context: Access discounts, cadence, and gifting rules without additional API calls.
  • Customizable appearance: Pull theme settings to ensure widget styles match your storefront.

Key details

Links

Liquid objects

Recurly Commerce data is available in standard Shopify Liquid objects:

Product details

Fetch the subscription metadata for a product:

GET https://subs.api.tryprive.com/stores/${storeUrl}/products/${productId}/new

Selling plan groups

Represents a selling mode (e.g. “Subscribe & save” or “Pre-paid”).

{
    "productId": "gid://shopify/Product/7604549058805",
    "hasVariantLevel": false,
    "selling_plan_groups": [
        {
            "requires_selling_plan": true,
            "id": "gid://shopify/SellingPlanGroup/628818165",
            "type": "PREPAID_SUBSCRIPTION_ONLY",
            "variants": [],
            "selling_plans": [
                {
                    "variants": null,
                    "specialDiscountActive": true,
                    "specialDiscount": 12,
                    "discountType": "QUANTITY",
                    "specialDiscountModifier": null,
                    "numberOfOrders": 3,
                    "shippingDiscount": null,
                    "specialDiscountType": "QUANTITY",
                    "sellingPlanGroupId": "gid://shopify/SellingPlanGroup/628818165",
                    "sellingPlanId": "3192750325",
                    "discount": 4,
                    "discountModifier": "PERCENTAGE",
                    "optionOrder": null,
                    "deliveryCadenceCount": 2,
                    "deliveryCadenceUnit": "MONTH",
                    "billingCadenceCount": 12,
                    "billingCadenceUnit": "MONTH",
                    "type": "PREPAID_SUBSCRIPTION_ONLY",
                    "name": "Delivery every 2 months, prepay every 12 months - 4% off",
                    "nameOverride": "Name Custom Discount",
                    "visibility": null,
                    "isDefault": false,
                    "discountCode": null,
                    "optionType": "PREPAID_SUBSCRIPTION_ONLY",
                    "giftOptions": null
                },
                {
                    "variants": null,
                    "specialDiscountActive": true,
                    "specialDiscount": 12,
                    "discountType": "QUANTITY",
                    "specialDiscountModifier": null,
                    "numberOfOrders": 3,
                    "shippingDiscount": null,
                    "specialDiscountType": "QUANTITY",
                    "sellingPlanGroupId": "gid://shopify/SellingPlanGroup/628818165",
                    "sellingPlanId": "3192881397",
                    "discount": 15,
                    "discountModifier": "PERCENTAGE",
                    "optionOrder": null,
                    "deliveryCadenceCount": 1,
                    "deliveryCadenceUnit": "MONTH",
                    "billingCadenceCount": 12,
                    "billingCadenceUnit": "MONTH",
                    "type": "PREPAID_SUBSCRIPTION_ONLY",
                    "name": "Delivery every 1 month, prepay every 12 months - 15% off",
                    "nameOverride": "1m X 12 months",
                    "visibility": null,
                    "isDefault": false,
                    "discountCode": null,
                    "optionType": "PREPAID_SUBSCRIPTION_ONLY",
                    "giftOptions": null
                },
                {
                    "variants": null,
                    "specialDiscountActive": true,
                    "specialDiscount": 12,
                    "discountType": "QUANTITY",
                    "specialDiscountModifier": null,
                    "numberOfOrders": 3,
                    "shippingDiscount": null,
                    "specialDiscountType": "QUANTITY",
                    "sellingPlanGroupId": "gid://shopify/SellingPlanGroup/628818165",
                    "sellingPlanId": "3193012469",
                    "discount": 24,
                    "discountModifier": "PERCENTAGE",
                    "optionOrder": null,
                    "deliveryCadenceCount": 3,
                    "deliveryCadenceUnit": "MONTH",
                    "billingCadenceCount": 6,
                    "billingCadenceUnit": "MONTH",
                    "type": "PREPAID_SUBSCRIPTION_ONLY",
                    "name": "Delivery every 3 months, prepay every 6 months - 24% off",
                    "nameOverride": null,
                    "visibility": null,
                    "isDefault": false,
                    "discountCode": null,
                    "optionType": "PREPAID_SUBSCRIPTION_ONLY",
                    "giftOptions": null
                }
            ]
        }
    ]
}

Hybrid example (One-time, subscribe & save, prepaid)

{
    "productId": "gid://shopify/Product/7604549058805",
    "hasVariantLevel": false,
    "selling_plan_groups": [
        {
            "requires_selling_plan": false,
            "id": "gid://shopify/SellingPlanGroup/633340149",
            "type": "ONETIME_AND_SUBSCRIPTION_AND_PREPAID",
            "variants": [],
            "selling_plans": [
                {
                    "variants": null,
                    "specialDiscountActive": false,
                    "specialDiscount": null,
                    "discountType": "NONE",
                    "specialDiscountModifier": null,
                    "numberOfOrders": null,
                    "shippingDiscount": null,
                    "specialDiscountType": "NONE",
                    "sellingPlanGroupId": "gid://shopify/SellingPlanGroup/633340149",
                    "sellingPlanId": "3203006709",
                    "discount": 10,
                    "discountModifier": "PERCENTAGE",
                    "optionOrder": 1,
                    "deliveryCadenceCount": 3,
                    "deliveryCadenceUnit": "WEEK",
                    "billingCadenceCount": 3,
                    "billingCadenceUnit": "WEEK",
                    "type": "ONETIME_AND_SUBSCRIPTION_AND_PREPAID",
                    "name": "Delivery every 3 weeks - 10% off",
                    "nameOverride": null,
                    "visibility": null,
                    "isDefault": false,
                    "discountCode": null,
                    "optionType": "ONETIME_AND_SUBSCRIPTION",
                    "giftOptions": null
                },
                {
                    "variants": null,
                    "specialDiscountActive": false,
                    "specialDiscount": null,
                    "discountType": "NONE",
                    "specialDiscountModifier": null,
                    "numberOfOrders": null,
                    "shippingDiscount": null,
                    "specialDiscountType": "NONE",
                    "sellingPlanGroupId": "gid://shopify/SellingPlanGroup/633340149",
                    "sellingPlanId": "3203039477",
                    "discount": 15,
                    "discountModifier": "PERCENTAGE",
                    "optionOrder": 2,
                    "deliveryCadenceCount": 12,
                    "deliveryCadenceUnit": "WEEK",
                    "billingCadenceCount": 12,
                    "billingCadenceUnit": "WEEK",
                    "type": "ONETIME_AND_SUBSCRIPTION_AND_PREPAID",
                    "name": "Delivery every 12 weeks - 15% off",
                    "nameOverride": null,
                    "visibility": null,
                    "isDefault": false,
                    "discountCode": null,
                    "optionType": "ONETIME_AND_SUBSCRIPTION",
                    "giftOptions": null
                },
                {
                    "variants": null,
                    "specialDiscountActive": false,
                    "specialDiscount": null,
                    "discountType": "NONE",
                    "specialDiscountModifier": null,
                    "numberOfOrders": null,
                    "shippingDiscount": null,
                    "specialDiscountType": "NONE",
                    "sellingPlanGroupId": "gid://shopify/SellingPlanGroup/633340149",
                    "sellingPlanId": "3203072245",
                    "discount": 12,
                    "discountModifier": "PERCENTAGE",
                    "optionOrder": 3,
                    "deliveryCadenceCount": 4,
                    "deliveryCadenceUnit": "WEEK",
                    "billingCadenceCount": 4,
                    "billingCadenceUnit": "WEEK",
                    "type": "ONETIME_AND_SUBSCRIPTION_AND_PREPAID",
                    "name": "Delivery every 4 weeks - 12% off",
                    "nameOverride": null,
                    "visibility": null,
                    "isDefault": false,
                    "discountCode": null,
                    "optionType": "ONETIME_AND_SUBSCRIPTION",
                    "giftOptions": null
                },
                {
                    "variants": null,
                    "specialDiscountActive": false,
                    "specialDiscount": null,
                    "discountType": "NONE",
                    "specialDiscountModifier": null,
                    "numberOfOrders": null,
                    "shippingDiscount": null,
                    "specialDiscountType": "NONE",
                    "sellingPlanGroupId": "gid://shopify/SellingPlanGroup/633340149",
                    "sellingPlanId": "3203105013",
                    "discount": 15,
                    "discountModifier": "PERCENTAGE",
                    "optionOrder": 4,
                    "deliveryCadenceCount": 1,
                    "deliveryCadenceUnit": "MONTH",
                    "billingCadenceCount": 6,
                    "billingCadenceUnit": "MONTH",
                    "type": "ONETIME_AND_SUBSCRIPTION_AND_PREPAID",
                    "name": "Delivery every 1 month, prepay every 6 months - 15% off",
                    "nameOverride": null,
                    "visibility": null,
                    "isDefault": false,
                    "discountCode": null,
                    "optionType": "PREPAID_SUBSCRIPTION_ONLY",
                    "giftOptions": null
                },
                {
                    "variants": null,
                    "specialDiscountActive": false,
                    "specialDiscount": null,
                    "discountType": "NONE",
                    "specialDiscountModifier": null,
                    "numberOfOrders": null,
                    "shippingDiscount": null,
                    "specialDiscountType": "NONE",
                    "sellingPlanGroupId": "gid://shopify/SellingPlanGroup/633340149",
                    "sellingPlanId": "3203137781",
                    "discount": 20,
                    "discountModifier": "PERCENTAGE",
                    "optionOrder": 5,
                    "deliveryCadenceCount": 2,
                    "deliveryCadenceUnit": "MONTH",
                    "billingCadenceCount": 6,
                    "billingCadenceUnit": "MONTH",
                    "type": "ONETIME_AND_SUBSCRIPTION_AND_PREPAID",
                    "name": "Delivery every 2 months, prepay every 6 months - 20% off",
                    "nameOverride": null,
                    "visibility": null,
                    "isDefault": false,
                    "discountCode": null,
                    "optionType": "PREPAID_SUBSCRIPTION_ONLY",
                    "giftOptions": null
                }
            ]
        }
    ]
}

Store theme

Retrieve widget styling and copy overrides for the active theme:

GET https://subs.api.tryprive.com/stores/${storeUrl}/settings?themeId=<theme_id>
{
    "currency": "USD",
    "money_format": "${{amount}} USD",
    "multilocation": true,
    "widget_settings": {
        "elements": {
            "buttonPrice": "not-existing-tag"
        },
        "customCss": null,
        "onetimeFirst": false,
        "onetimeCopy": null,
        "subscribeCopy": "Discount Subscription",
        "prepaidCopy": "Prepaid Subscription",
        "subOptionCopy": null,
        "styling": {
            "bgColor": null,
            "borders": null,
            "accentColor": "#000000",
            "quantityStyle": null,
            "bgColorOnSelection": "#dbe4ff",
            "deliveryEveryStyle": null,
            "purchaseOptionsStyle": null,
            "selectedOptionsStyle": {
                "color": "#000000",
                "fontSize": "1",
                "fontWeight": "bold"
            }
        },
        "rank": null
    }
}

Updated about 9 hours ago