How do I use the Recurly Commerce Widget API?

The Recurly Commerce Widget API gives you access to product subscription metadata, selling plan groups, styling settings, and more. It’s designed to help you integrate subscription options into your Shopify storefront dynamically and with full control.

Requirements

• Your store must be using Recurly Commerce with an active Shopify storefront integration

• The subscription widget must be installed and enabled

What does the Widget API provide?

• Product details and selling plan groups

• Selling plan definitions (frequency, pricing, discounts, gifting)

• Widget styling and theme settings

Example: Get product subscription metadata

GET

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

Selling plan group (Prepaid example)

{
"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": [
{
"sellingPlanId": "3192750325",
"name": "Delivery every 2 months, prepay every 12 months - 4% off",
"discount": 4,
"discountModifier": "PERCENTAGE",
"deliveryCadenceCount": 2,
"deliveryCadenceUnit": "MONTH",
"billingCadenceCount": 12,
"billingCadenceUnit": "MONTH"
}
]
}
]
}

Hybrid example

{
"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": [
{
"sellingPlanId": "3203006709",
"name": "Delivery every 3 weeks - 10% off",
"discount": 10,
"discountModifier": "PERCENTAGE",
"deliveryCadenceCount": 3,
"deliveryCadenceUnit": "WEEK",
"billingCadenceCount": 3,
"billingCadenceUnit": "WEEK"
}
]
}
]
}

Example: Get store theme settings

GET

https://subs.api.tryprive.com/stores/${storeUrl}/settings?themeId=<theme_id>

Widget styling and copy overrides

{
"currency": "USD",
"money_format": "${{amount}} USD",
"multilocation": true,
"widget_settings": {
"subscribeCopy": "Discount Subscription",
"prepaidCopy": "Prepaid Subscription",
"styling": {
"accentColor": "#000000",
"bgColorOnSelection": "#dbe4ff",
"selectedOptionsStyle": {
"color": "#000000",
"fontSize": "1",
"fontWeight": "bold"
}
}
}
}

For more details, visit our Recurly Commerce Product Documentation.