Commerce Platform

Simplified Shops Ads Experiences: Enable Subscriptions

Note: Enabling subscriptions can only be completed after you finish integration work for the new simplified Shops ads experiences feature.


We offer two solutions for you to add subscriptions products into your Meta catalog. (Estimated effort <1 week)

SolutionPDP ScreenshotSuited For

1) Using Product Variants

  • Products that already represent the various subscription options as a separate product variants.

  • Products that have only one subscription option (one time, deliver every month)

2) Using Catalog Feed

  • Products that have multiple subscription options (one-time, 1month, 3months)

User Experience

PDPCartCheckout via Seller’s Website in IAB

Using Product Variants

1. Catalog Feed

Our initial lightweight setup solution models subscriptions as a variant of the one-time purchasable product and utilizes the “additional_variant_attributes” field in the feed.

Required Fields

  • id - This is the product_id that Meta will pass to you in the checkout URL.
    • each subscription plan will require a unique product ID.
    • NOTE: if subscription products do not have a different SKU on your site, your checkout URL endpoint will need to parse the subscription information out of the product_id. We suggest appending “_subscription” to the end of the original ID.
  • item_group_id - This ID needs to be the same across all of the variants (including the one-time purchase variant if applicable) so the product variants can be grouped together on the PDP.
  • additional_variant_attribute - A list of <key:value> pairs
    • key must be “subscription”, value will represent the subscription frequency (this text will be displayed to the user).
    • All variants (including the one-time purchasable variant) must set this field.
  • sale_price - Current price of the subscription product.
  • price - Price of the of the one-time purchase.

Example feed of subscription options:

idtitleitem_group_idpricesale_priceadditional_variant_attribute

razor_refill_cartridge

4-blade razor refill (one time)

razor_refill

6.99

subscription:One-time purchase

razor_refill_cartridge_every_month

4-blade razor refill (every month)

razor_refill

6.99

5.99

subscription:Deliver every month


Example of a subscription PDP


2. Checkout URL

When integrating subscription products, consider the following scenarios:

  • Subscription products with SKUs:
    • No additional changes to your custom checkout url are required.
    • Example: 
https://your-website.com/any-url?products=<product-id:1>&coupon=<promo>

  • Subscription products without SKUs:
    • Your checkout URL endpoint must parse the subscription information from the product_id.
    • Example: 
https://your-website.com/any-url?products=<product-id_subscription:1>&coupon=<promo>

Using Catalog Feed

1. Catalog Feed

A new field “subscription_plans” in the catalog is now supported. This field is a JSON encoded string with fields “requires_subscription_plan” and “plans”.

AttributeRequiredDescription
requires_subscription_plan
bool

true

If true, the product item only supports subscription purchase. One-time purchase is not supported. If false, both subscription purchase and one-time purchase are supported.

plans
list<SellingPlan>

true

A list of SellingPlan

SellingPlan object

AttributeRequiredDescription
id
string

true

The id of the subscription plan, Meta will be passing this within the checkout URL.

billing_frequency
BillingFrequency

false

The billing frequency

delivery_frequency
DeliveryFrequency

false

The delivery frequency

price_adjustment
PriceAdjustment

false

The price adjustment

BillingFrequency object

AttributeRequiredDescription
interval
string

true

Supported values: day, month, week, year

interval_count
integer

true

Frequency of billing

Example value: 1

DeliveryFrequency object

AttributeRequiredDescription
interval
string

true

Supported values: day, month, week, year

interval_count
integer

true

Frequency of delivery

Example value: 1

PriceAdjustment object

AttributeRequiredDescription
adjustment_value_type
string

true

Supported values: fixed_amount, percentage

adjustment_percent_value
float

false

The percent off for percentage type

Example value: 10

adjustment_fixed_value_amount
float

false

The amount off for fixed_amount type

Example value: 20

Example

{
 "requires_subscription_plan": true,
 "plans": [
   {
     "id": "monthly plan",
     "delivery_frequency": {
       "interval": "month",
       "interval_count": 1
     }
   },
   {
     "id": "monthly plan with 10% off",
     "delivery_frequency": {
       "interval": "month",
       "interval_count": 1
     },
     "price_adjustment": {
       "adjustment_value_type": "percentage",
       "adjustment_percent_value": 10,
       "adjustment_fixed_value_amount": null
     }
   },
   {
     "id": "monthly plan with $10 off and annual bill",
     "delivery_frequency": {
       "interval": "month",
       "interval_count": 1
     },
     "price_adjustment": {
       "adjustment_value_type": "fixed_amount",
       "adjustment_percent_value": 10,
       "adjustment_fixed_value_amount": null
     },
     "billing_frequency": {
       "interval": "year",
       "interval_count": 1
     }
   }
 ]
}

Example of the subscription PDP


2. Checkout URL

You will need to make changes to the custom checkout url that allows Meta to send a buyer to your checkout screen.

Query ParameterDescriptionExamples

products

Required.
A comma-separated list of products. For each product, the ID and quantity are separated by a colon. Commas (%2C) and colons (%3A) are escaped according to RFC 3986.

Your web server should provide an API similar to decodeURIComponent to parse these parameters.

Products with comma (,) or colon (:) characters in their ID are not supported.

products=12345%3A3%2C23456%3A1

** This example cart has the following two products:

  1. product ID 12345 with quantity 3 and
  2. product ID 23456 with quantity 1

coupon

Optional.
A single coupon code to apply at checkout. This may include an email opt-in promo code.

coupon=SUMMERSALE20

products_json

Optional.
A JSON object that contains metadata to support product-specific features such as subscriptions, customizations, etc. Braces (%257B & %257D), quotations (%2522), commas (%252C) and colons (%253A) are escaped according to RFC 3986.

Encoded example:
%257B%252212345%2522%253A%257B%2522selling_plan%2522%253A%2522plan_1%2522%257D%257D

Decoded example:
{"12345":{"selling_plan":"plan_1"}}


URL with no subscription selected

https://your-website.com/any-url?products=<product-id:1>&coupon=<promo>

URL with subscription selected::

https://your-website.com/any-url?products=<product-id:1>&coupon=<promo>&products_json=<products_json>

See Also