Managing Subscriptions

The Subscriptions API is set of APIs used to manage subscriptions. Learn how to use the Subscriptions API to manage your subscriptions.

note

This guide uses the command line to make requests via cURL, but you can also use a supported SDK.

Objectives

The following steps describe how to manage subscriptions using the Subscriptions API by creating an offering composed of:

• Subscription plans which are the products and services are what you want to offer in a subscription.
• Pricing options which the rules that govern your subscription, for example, delivery frequency, the quantity and any discount. You can combine and reuse pricing options for as many plans within the offering as you want.
• Features which indicates some benefit that is received as a result of having an active subscription. Features are defined separately and associated with plans within offerings

Creating a Feature

Features are optionally used to manage entitlement to benefits conferred on subscriptions to subscription offerings. They are associated with a tag that may be used to set account tags on subscribers' accounts.

The following creates a feature that will set the account tag with UUID c880c6da-ffd3-49ea-a791-27816697c64b on subscribers' accounts when their subscription is active.

curl -X POST https://useast.api.elasticpath.com/v2/subscriptions/features \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
     "data": {
       "type": "subscription_feature",
       "attributes": {
         "external_ref": "4k",
         "name": "4K video access",
         "description": "Access to HD Content.",
         "configuration": {
           "type": "access",
           "tag": "c880c6da-ffd3-49ea-a791-27816697c64b"
         }
       }
     }
 }'  

Creating an offering

Offerings can contain any combination of products and plans.

The following requests creates an offering that created the 4k Streaming plan that can be selected with the Standard with Adverts and Standard pricing options.

The Standard with Adverts pricing option has the following properties:

• the billing cycle is monthly and customers are billed on the 1st of the month.
• the plan length is 12 months and rolling. In other words, customers pay regularly and repeatedly, until the plan is cancelled.
• has a fixed price.

The Standard pricing option is the same, but has a different price. Both of these options are associated with the plan.

The 4K feature we created above is included in the offering by its external reference and configured for the plan.

curl -L 'https://euwest.api.elasticpath.com/v2/subscriptions/offerings/build' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{
}'
curl -X POST https://useast.api.elasticpath.com/v2/subscriptions/offerings/build \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
     "data": {
       "external_ref": "4koffer",
       "name": "Dohi",
       "description": "Stream TV and Movies Online."
       "features": [
         "4k"
       ],
       "plans": [
         {
           "name": "4K Streaming",
           "description": "What is 4K Streaming? Its the highest resolution available, giving excellent picture quality and crisp, clear details. 4K Streaming elevates your viewing experience to the next level.",
           "sku": "77012025"
           "external_ref": "4kplan",
         }
       ],
       "pricing_options": [
         {
          "name": "Standard with Adverts",
          "billing_interval_type": "month",
          "billing_frequency": 12,
          "plan_length": 12,
          "end_behavior": "roll",
          "can_pause": true,
          "can_resume": true,
          "can_cancel": true,
          "description": "Our Standard with Adverts plan allows you to enjoy movies and TV shows at a lower price.",
          "billing_month_day": 1,
          "fixed_price": {
            "USD": {
              "amount": 699,
            },
           "external_ref": "ads"
         },
         {
           "name": "Standard",
           "status": "active",
           "billing_interval_type": "month",
           "billing_frequency": 12,
           "plan_length": 12,
           "end_behavior": "roll",
           "can_pause": true,
           "can_resume": true,
           "can_cancel": true,
           "description": "Our Standard plan allows unlimited ad-free movies, TV shows, and mobile games.",
           "billing_month_day": 1,
           "fixed_price": {
             "USD": {
               "amount": 1599,
             },
           }
           "external_ref": "standard"
         }
       ]
       "configured_features": {
           "4kplan": {
               "4k": {
                "type": "access"
               }
           }
       },
       "pricing_option_associations": {
           "4kplan": [
             "standard", "ads"
           ]
       },
     }
 }'  

The response contains the offering.

{
    "data": {
        "attributes": {
            "created_at": "2023-11-28T15:55:29.052146375Z",
            "description": "Stream TV and Movies Online.",
            "name": "Dohi",
            "updated_at": "2023-11-28T15:55:29.052146375Z"
        },
        "id": "140ea4ad-11b0-4778-91a1-576df688c31c",
        "meta": {
            "owner": "store"
        },
        "relationships": {
            "plans": {
                "links": {
                    "related": "https://epcc-integration.global.ssl.fastly.net/v2/subscriptions/offerings/140ea4ad-11b0-4778-91a1-576df688c31c/plans"
                }
            },
            "products": {
                "links": {
                    "related": "https://epcc-integration.global.ssl.fastly.net/v2/subscriptions/offerings/140ea4ad-11b0-4778-91a1-576df688c31c/products"
                }
            }
        },
        "type": "subscription_offering"
    }
}