Retrieving Subscription Info with Stripe Metadata

In this topic, you will learn how to retrieve subscription information associated with Stripe custom metadata using the Stripe API.

Overview

Brightcove is adding custom metadata to Stripe subscriptions that will allow you to identify the viewer's device type used when creating the subscription. You can query the Stripe API to search for subscriptions associated with the custom metadata. You can also add webhooks to listen for Stripe events.

This topic will show you how to do the following:

  • Use the Stripe API to search for specific metadata in any subscription/purchase to return a list
  • Create a webhook to listen for Stripe events

Prerequisites

To use the Stripe API as shown in this topic, you will need the following:

  • Stripe account
  • Postman or another API platform

    You can use the API platform of your choice to interact with the Stripe API, but for these examples, we will use Postman.

Understanding the Stripe API

Base URL

The base URL for the Stripe API is:

https://api.stripe.com

Authentication

Requests are authenticated with your API key in the Authorization header:

Authorization: Bearer {api_key}

API collection

The Stripe API Collection is hosted within Stripe's Postman public workspace. This allows you to fork from the public workspace into yours.

If you don't want to fork the collection from the public workspace, you can import it from the stripe-postman GitHub repository.

Creating a Postman environment

You can use the API platform of your choice to interact with the Stripe API, but for these examples, we will use Postman.

  1. Login or create an account with Postman.
  2. Either fork the environment template within the Postman Stripe public workspace, or create a new envionment within Postman. We'll create a new environment.

  3. In your workspace, click New.

    create new

  4. In the dialog, select Environment.

    select environment

  5. Add your secret key as an environment variable and click Save.

    create secret key variable
  6. Click Add tab icon to open a new tab.

  7. In the request dialog, do the following:

    • Select Authorization
    • For Type, select Bearer Token
    • For Token, enter {{secret_key}}

    If your environment is set up correctly, you should see your secret key value when you mouse over the secret_key variable.

    mouse over key variable
  8. Click Save.
  9. In the dialog, do the following:
    • Add a Request name
    • Choose or create a new collection
    • Click Save
    save request

  10. You are now ready to create a GET request to the Stripe API.

    Environment created

Searching subscriptions with metadata

In this section, you will use the Stripe API to search for subscriptions that have custom metadata.

Custom metadata

Name Value
device_type Values:
  • androidtv
  • firetv
  • lgtv
  • nettv
  • operatv
  • panasonic
  • samsung

Steps

  1. Return to the Postman environment that you created in the previous section.

  2. For the GET request, paste in the following into the Request URL. Use the device type value of your choice.

    https://api.stripe.com/v1/subscriptions/search?query=metadata["device_type"]:"samsung"

    Get Samsung subscriptions
  3. Click Send.

  4. If you get the following error with your GET request,

    Stripe API version error

    make sure that you are using the current version of the Stripe API. You can do this by adding the following header:

    • KEY is "Stripe-version"
    • VALUE is "2020-08-27" (or latest version)
    Stripe version header

Response

The API response should contain subscriptions with metadata for Samsung:yes.

Notice that the response contains the following:

"metadata": {
    "Samsung": "yes"
},

API response

Your response should look similar to this:

{
  "object": "search_result",
  "data": [
      {
          "id": "sub_1L3jAgFzWFPFNFjqFpyUF8XY",
          "object": "subscription",
          "application": null,
          "application_fee_percent": null,
          "automatic_tax": {
              "enabled": false
          },
          "billing_cycle_anchor": 1653581061,
          "billing_thresholds": null,
          "cancel_at": null,
          "cancel_at_period_end": false,
          "canceled_at": null,
          "collection_method": "charge_automatically",
          "created": 1653581061,
          "current_period_end": 1656259461,
          "current_period_start": 1653581061,
          "customer": "cus_LlFcWXPXftQibf",
          "days_until_due": null,
          "default_payment_method": null,
          "default_source": null,
          "default_tax_rates": [],
          "description": null,
          "discount": null,
          "ended_at": null,
          "items": {
              "object": "list",
              "data": [
                  {
                      "id": "si_LlFgWbs9lqlwOF",
                      "object": "subscription_item",
                      "billing_thresholds": null,
                      "created": 1653581062,
                      "metadata": {},
                      "plan": {
                          "id": "price_1L3j69FzWFPFNFjqpEIV4RMb",
                          "object": "plan",
                          "active": true,
                          "aggregate_usage": null,
                          "amount": 100,
                          "amount_decimal": "100",
                          "billing_scheme": "per_unit",
                          "created": 1653580781,
                          "currency": "eur",
                          "interval": "month",
                          "interval_count": 1,
                          "livemode": false,
                          "metadata": {},
                          "nickname": null,
                          "product": "prod_LlFbyvOQ6dpLXF",
                          "tiers_mode": null,
                          "transform_usage": null,
                          "trial_period_days": null,
                          "usage_type": "licensed"
                      },
                      "price": {
                          "id": "price_1L3j69FzWFPFNFjqpEIV4RMb",
                          "object": "price",
                          "active": true,
                          "billing_scheme": "per_unit",
                          "created": 1653580781,
                          "currency": "eur",
                          "livemode": false,
                          "lookup_key": null,
                          "metadata": {},
                          "nickname": null,
                          "product": "prod_LlFbyvOQ6dpLXF",
                          "recurring": {
                              "aggregate_usage": null,
                              "interval": "month",
                              "interval_count": 1,
                              "trial_period_days": null,
                              "usage_type": "licensed"
                          },
                          "tax_behavior": "unspecified",
                          "tiers_mode": null,
                          "transform_quantity": null,
                          "type": "recurring",
                          "unit_amount": 100,
                          "unit_amount_decimal": "100"
                      },
                      "quantity": 1,
                      "subscription": "sub_1L3jAgFzWFPFNFjqFpyUF8XY",
                      "tax_rates": []
                  }
              ],
              "has_more": false,
              "total_count": 1,
              "url": "/v1/subscription_items?subscription=sub_1L3jAgFzWFPFNFjqFpyUF8XY"
          },
          "latest_invoice": "in_1L3jAgFzWFPFNFjq8YFoU6R3",
          "livemode": false,
          "metadata": {
              "Samsung": "yes"
          },
          "next_pending_invoice_item_invoice": null,
          "pause_collection": null,
          "payment_settings": {
              "payment_method_options": null,
              "payment_method_types": null,
              "save_default_payment_method": "off"
          },
          "pending_invoice_item_interval": null,
          "pending_setup_intent": null,
          "pending_update": null,
          "plan": {
              "id": "price_1L3j69FzWFPFNFjqpEIV4RMb",
              "object": "plan",
              "active": true,
              "aggregate_usage": null,
              "amount": 100,
              "amount_decimal": "100",
              "billing_scheme": "per_unit",
              "created": 1653580781,
              "currency": "eur",
              "interval": "month",
              "interval_count": 1,
              "livemode": false,
              "metadata": {},
              "nickname": null,
              "product": "prod_LlFbyvOQ6dpLXF",
              "tiers_mode": null,
              "transform_usage": null,
              "trial_period_days": null,
              "usage_type": "licensed"
          },
          "quantity": 1,
          "schedule": null,
          "start_date": 1653581061,
          "status": "active",
          "test_clock": null,
          "transfer_data": null,
          "trial_end": null,
          "trial_start": null
      }
  ],
  "has_more": false,
  "next_page": null,
  "url": "/v1/subscriptions/search"

Using Stripe webhooks

Your Brightcove Beacon app can listen for events on your Stripe account, and you can use webhooks to enable Stripe to push real-time notifications to your app, or you can use a webhook as an endpoint.

For details, see the Stripe Use incoming webhooks reference.

Notice that each response contains the following:

"metadata": {
    "Samsung": "yes"
},

Events

Here are some events you can listen for:

customer.subscription.created

A Stripe webhook can listen for the customer.subscription.created event.

API response

Your response should look similar to this:

{
  "object": {
    "id": "sub_1L3jAgFzWFPFNFjqFpyUF8XY",
    "object": "subscription",
    "application": null,
    "application_fee_percent": null,
    "automatic_tax": {
      "enabled": false
    },
    "billing": "charge_automatically",
    "billing_cycle_anchor": 1653581061,
    "billing_thresholds": null,
    "cancel_at": null,
    "cancel_at_period_end": false,
    "canceled_at": null,
    "collection_method": "charge_automatically",
    "created": 1653581061,
    "current_period_end": 1656259461,
    "current_period_start": 1653581061,
    "customer": "cus_LlFcWXPXftQibf",
    "days_until_due": null,
    "default_payment_method": null,
    "default_source": null,
    "default_tax_rates": [
    ],
    "description": null,
    "discount": null,
    "ended_at": null,
    "invoice_customer_balance_settings": {
      "consume_applied_balance_on_void": true
    },
    "items": {
      "object": "list",
      "data": [
        {
          "id": "si_LlFgWbs9lqlwOF",
          "object": "subscription_item",
          "billing_thresholds": null,
          "created": 1653581062,
          "metadata": {
          },
          "plan": {
            "id": "price_1L3j69FzWFPFNFjqpEIV4RMb",
            "object": "plan",
            "active": true,
            "aggregate_usage": null,
            "amount": 100,
            "amount_decimal": "100",
            "billing_scheme": "per_unit",
            "created": 1653580781,
            "currency": "eur",
            "interval": "month",
            "interval_count": 1,
            "livemode": false,
            "metadata": {
            },
            "name": "Beacon Metadata",
            "nickname": null,
            "product": "prod_LlFbyvOQ6dpLXF",
            "statement_descriptor": null,
            "tiers": null,
            "tiers_mode": null,
            "transform_usage": null,
            "trial_period_days": null,
            "usage_type": "licensed"
          },
          "price": {
            "id": "price_1L3j69FzWFPFNFjqpEIV4RMb",
            "object": "price",
            "active": true,
            "billing_scheme": "per_unit",
            "created": 1653580781,
            "currency": "eur",
            "livemode": false,
            "lookup_key": null,
            "metadata": {
            },
            "nickname": null,
            "product": "prod_LlFbyvOQ6dpLXF",
            "recurring": {
              "aggregate_usage": null,
              "interval": "month",
              "interval_count": 1,
              "trial_period_days": null,
              "usage_type": "licensed"
            },
            "tax_behavior": "unspecified",
            "tiers_mode": null,
            "transform_quantity": null,
            "type": "recurring",
            "unit_amount": 100,
            "unit_amount_decimal": "100"
          },
          "quantity": 1,
          "subscription": "sub_1L3jAgFzWFPFNFjqFpyUF8XY",
          "tax_rates": [
          ]
        }
      ],
      "has_more": false,
      "total_count": 1,
      "url": "/v1/subscription_items?subscription=sub_1L3jAgFzWFPFNFjqFpyUF8XY"
    },
    "latest_invoice": "in_1L3jAgFzWFPFNFjq8YFoU6R3",
    "livemode": false,
    "metadata": {
      "Samsung": "yes"
    },
    "next_pending_invoice_item_invoice": null,
    "pause_collection": null,
    "payment_settings": {
      "payment_method_options": null,
      "payment_method_types": null,
      "save_default_payment_method": "off"
    },
    "pending_invoice_item_interval": null,
    "pending_setup_intent": null,
    "pending_update": null,
    "plan": {
      "id": "price_1L3j69FzWFPFNFjqpEIV4RMb",
      "object": "plan",
      "active": true,
      "aggregate_usage": null,
      "amount": 100,
      "amount_decimal": "100",
      "billing_scheme": "per_unit",
      "created": 1653580781,
      "currency": "eur",
      "interval": "month",
      "interval_count": 1,
      "livemode": false,
      "metadata": {
      },
      "name": "Beacon Metadata",
      "nickname": null,
      "product": "prod_LlFbyvOQ6dpLXF",
      "statement_descriptor": null,
      "tiers": null,
      "tiers_mode": null,
      "transform_usage": null,
      "trial_period_days": null,
      "usage_type": "licensed"
    },
    "quantity": 1,
    "schedule": null,
    "start": 1653581061,
    "start_date": 1653581061,
    "status": "active",
    "tax_percent": null,
    "test_clock": null,
    "transfer_data": null,
    "trial_end": null,
    "trial_start": null
  },
  "previous_attributes": {
    "metadata": {
      "Samsung": null
    }
  }
}

customer.subscription.updated

A Stripe webhook can listen for the customer.subscription.updated event.

API response

Your response should look similar to this:

{
  "object": {
    "id": "sub_1L3jAgFzWFPFNFjqFpyUF8XY",
    "object": "subscription",
    "application": null,
    "application_fee_percent": null,
    "automatic_tax": {
      "enabled": false
    },
    "billing": "charge_automatically",
    "billing_cycle_anchor": 1653581061,
    "billing_thresholds": null,
    "cancel_at": null,
    "cancel_at_period_end": false,
    "canceled_at": null,
    "collection_method": "charge_automatically",
    "created": 1653581061,
    "current_period_end": 1656259461,
    "current_period_start": 1653581061,
    "customer": "cus_LlFcWXPXftQibf",
    "days_until_due": null,
    "default_payment_method": null,
    "default_source": null,
    "default_tax_rates": [
    ],
    "description": null,
    "discount": null,
    "ended_at": null,
    "invoice_customer_balance_settings": {
      "consume_applied_balance_on_void": true
    },
    "items": {
      "object": "list",
      "data": [
        {
          "id": "si_LlFgWbs9lqlwOF",
          "object": "subscription_item",
          "billing_thresholds": null,
          "created": 1653581062,
          "metadata": {
          },
          "plan": {
            "id": "price_1L3j69FzWFPFNFjqpEIV4RMb",
            "object": "plan",
            "active": true,
            "aggregate_usage": null,
            "amount": 100,
            "amount_decimal": "100",
            "billing_scheme": "per_unit",
            "created": 1653580781,
            "currency": "eur",
            "interval": "month",
            "interval_count": 1,
            "livemode": false,
            "metadata": {
            },
            "name": "Beacon Metadata",
            "nickname": null,
            "product": "prod_LlFbyvOQ6dpLXF",
            "statement_descriptor": null,
            "tiers": null,
            "tiers_mode": null,
            "transform_usage": null,
            "trial_period_days": null,
            "usage_type": "licensed"
          },
          "price": {
            "id": "price_1L3j69FzWFPFNFjqpEIV4RMb",
            "object": "price",
            "active": true,
            "billing_scheme": "per_unit",
            "created": 1653580781,
            "currency": "eur",
            "livemode": false,
            "lookup_key": null,
            "metadata": {
            },
            "nickname": null,
            "product": "prod_LlFbyvOQ6dpLXF",
            "recurring": {
              "aggregate_usage": null,
              "interval": "month",
              "interval_count": 1,
              "trial_period_days": null,
              "usage_type": "licensed"
            },
            "tax_behavior": "unspecified",
            "tiers_mode": null,
            "transform_quantity": null,
            "type": "recurring",
            "unit_amount": 100,
            "unit_amount_decimal": "100"
          },
          "quantity": 1,
          "subscription": "sub_1L3jAgFzWFPFNFjqFpyUF8XY",
          "tax_rates": [
          ]
        }
      ],
      "has_more": false,
      "total_count": 1,
      "url": "/v1/subscription_items?subscription=sub_1L3jAgFzWFPFNFjqFpyUF8XY"
    },
    "latest_invoice": "in_1L3jAgFzWFPFNFjq8YFoU6R3",
    "livemode": false,
    "metadata": {
      "Samsung": "yes"
    },
    "next_pending_invoice_item_invoice": null,
    "pause_collection": null,
    "payment_settings": {
      "payment_method_options": null,
      "payment_method_types": null,
      "save_default_payment_method": "off"
    },
    "pending_invoice_item_interval": null,
    "pending_setup_intent": null,
    "pending_update": null,
    "plan": {
      "id": "price_1L3j69FzWFPFNFjqpEIV4RMb",
      "object": "plan",
      "active": true,
      "aggregate_usage": null,
      "amount": 100,
      "amount_decimal": "100",
      "billing_scheme": "per_unit",
      "created": 1653580781,
      "currency": "eur",
      "interval": "month",
      "interval_count": 1,
      "livemode": false,
      "metadata": {
      },
      "name": "Beacon Metadata",
      "nickname": null,
      "product": "prod_LlFbyvOQ6dpLXF",
      "statement_descriptor": null,
      "tiers": null,
      "tiers_mode": null,
      "transform_usage": null,
      "trial_period_days": null,
      "usage_type": "licensed"
    },
    "quantity": 1,
    "schedule": null,
    "start": 1653581061,
    "start_date": 1653581061,
    "status": "active",
    "tax_percent": null,
    "test_clock": null,
    "transfer_data": null,
    "trial_end": null,
    "trial_start": null
  },
  "previous_attributes": {
    "metadata": {
      "Samsung": null
    }
  }
}

Limitations

There are some limitations when using the Stripe API:

  • Quoting Stripe - "Don’t use search in read-after-write flows where strict consistency is necessary. Under normal operating conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up to an hour behind during outages. Search functionality is not available to merchants in India."
'