StripeMetadataを使用したサブスクリプション情報の取得

このトピックでは、StripeAPIを使用してStripeカスタムメタデータに関連付けられたサブスクリプション情報を取得する方法について説明します。

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.

Login or create an account with Postman.
Either fork the environment template within the Postman Stripe public workspace, or create a new envionment within Postman. We'll create a new environment.
In your workspace, click New.
In the dialog, select Environment.
Add your secret key as an environment variable and click Save.
Click to open a new tab.
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.
Click Save.
In the dialog, do the following:
- Add a Request name
- Choose or create a new collection
- Click Save
You are now ready to create a GET request to the Stripe API.

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

Return to the Postman environment that you created in the previous section.
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"
```
Click Send.
If you get the following error with your GET request,

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)

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."

Page Contents

StripeMetadataを使用したサブスクリプション情報の取得

Overview

Prerequisites

Understanding the Stripe API

Base URL

Authentication

API collection

Creating a Postman environment

Searching subscriptions with metadata

Custom metadata

Steps

Response

API response

Using Stripe webhooks

Events

customer.subscription.created

API response

customer.subscription.updated

API response

Limitations