Shopify Advent Calendar 2021 21日目の記事です。

Shopify のサブスク用アプリである Bold Subscription V2 の API の使い方やできることを紹介します。

Bold Subscription って何？っていう人は、こちらの「Shopify のサブスク(定期購入) アプリ Bold Subscription を利用する」を先にご覧ください。

サブスク用アプリで API って必要？

Shopify で定期購入を実現したいだけであれば、API を利用する必要はありません。サブスク用アプリの管理画面で設定すれば実現できます。

しかし、以下のようなことを実現したい場合は、API を提供しているサブスクアプリを選択する必要があります。

ヘッドレスコマースを採用しており、定期便の停止や配送日の変更など定期便の管理を独自の画面で行いたい
初回購入と2回目以降で別の商品を配送したい (初回はお試しサイズの商品を配送し、次回からフルサイズの製品を送りたい場合など)
別アプリからサブスクリプションの情報を取得したり、情報を変更したい

次に Bold Subscription API で何ができるのか紹介します。

Bold Subscription API でできること

Bold Subscription API でできることをざっと紹介します。その他にもたくさんありますので、知りたい方は、API Doc をご覧ください。

サブスク情報の一覧を取得する
特定のサブスク注文情報を取得する
特定のサブスク注文のShopifyの注文履歴を取得する
商品のスワップ(変更)
次回配送日の変更
配送間隔の変更
サブスク情報の更新 (配送先住所変更など)

Bold Subscription API でできないこと

サブスクリプション(購入)データの作成はできない

Bold Subscription API の利用方法

前提条件

ここ以下の作業は以下のことが終えている必要があります。以下の作業に関してはここでは説明しません。

Shopify に Bold Subscription アプリをインストール済み
Bold Subscription で商品(サブスクリプショングループ)などの設定済みで、すでに定期購入も試している

Bold Subscription API は普通の REST API です。

専用サイトで API キーの発行

Bold Subscription API を呼びだすには、API キーが必要となります。この API キーは、Bold 専用サイトで発行する必要があります。Shopify の管理画面からアクセスできる Bold 用のアプリ画面では発行できないことに注意してください。

1) Bold のアカウントを作成する

Bold Account Center アカウント作成画面にアクセスします。
右の Create a new organization of your own を選択します。
自身の名前、組織名、メアド、パスワードを入力し、Create account を押します。。
Platform で `ShopifyP を選択し、Store URL に Bold Subscription を導入しているShopify ストアのURLを設定します。(そうすることで、ここで作成する Bold アカウントとShopifyに導入しているアプリとを紐づけます。)
Shopify ストアとの接続検証確認を求められるので、Verify store を押します。
以上でアカウントの登録は完了です。

2) Bold アカウントにアクセスし、API キーを発行する

1で作成したアカウントにアクセスします。
画面左メニューの Developer Settings を押します。
Create API access token を押します。
トークン(キー)名を入力し、APIで利用する権限にチェックします。今回は、Subscription API の利用なので、一番下の Subscriptions の Read & Write にチェックします。どの項目をチェックするかは、やりたいことによるので、できるだけ必要最低限の項目にチェックしてください。事前に API Doc をみて、どのAPIを使うかを知った上で選択すると良いと思います。
Create ボタンを押すと、API キーは生成されます。この画面で Shared Secret と API アクセストークンが表示されますので、必ずメモしておいてください。この画面を閉じると、二度と確認することはできません。
画面下のチェックボックスにチェックし、Done を押します。これで、API キーの作成は終わりました。

ここで2つキーが作成されましたが、用途は以下となります。

Shared Secret: Bold webhook API 用のシークレット。今回は利用しない。
API access token: API 呼び出しに利用。今回利用するキー。

キーのメモを忘れたりした場合は、削除して、再度作り直してください。

参考: 公式: Bold アカウントの作り方 (英語)

Subscription API 呼び出し準備

基本的な API の呼び出し方は以下となります。

curl --request GET https://api.boldcommerce.com/subscriptions/v1/shops/{shop_identifier}/resource \
     --header 'Authorization: Bearer {api_token}'

{api_token} というのが、上記で取得した API access token そのものとなります。

上の例を見ると、API キーとは別に、shop_identifier というものが、Subscription APIの呼び出しには必要だと分かります。次にこの値を取得する方法を説明します。

ショップID の取得

専用の API を通して取得します。

curl 'https://api.boldcommerce.com/shops/v1/info' -H 'Authorization: Bearer {api_tokne}' | jq

Response

{
  "id": 58849,
  "shop_domain": "xxx.myshopify.com",
  "custom_domain": "xxxx.tokyo",
  "shop_identifier": "123456789",
  "shop_owner": "XXX",
  ... (省略)
}

"shop_identifier" がショプIDとなります。

これで、ようやく Subscription API の呼び出し準備が整いました。あとは、API Doc をみながら、呼び出したい API を利用するだけです。

サンプルコード

ショップ情報の取得

実際にはあまり使わないと思いますが、とりあえず試しに、ショップ情報を取得してみます。(何も設定していなくてもデータが取れるのため、動作確認には便利)

curl 'https://api.boldcommerce.com/subscriptions/v1/shops/{shop_identifier}/shop' -H 'Authorization: Bearer {api_token}' | jq

{shop_identifier}と {api_token} は各自で置き換えてください。

Response

{
  "shop": {
    "id": 10609,
    "shop_domain": "xxxx.myshopify.com",
    "custom_domain": "xxxx.com",
    "shop_identifier": "1234567890",
    "platform_type": "shopify",
    "timezone": "Asia/Tokyo",
    "currency": "JPY",
    "currency_format": "¥{{amount_no_decimals}}",
    "shop_owner": "Owner",
    "admin_email": "info@xxxx.com",
    "pii_redacted_at": null,
    "created_at": "2021-08-12 08:27:32",
    "updated_at": "2021-11-24 08:12:40",
    "deleted_at": null,
    "checkout_subscription_info": null
  }
}

ここからは、いくつか使いそうな API の呼び出しだけ紹介します。レスポンス例は、API Doc で確認してください。

サブスク一覧の取得

curl 'https://api.boldcommerce.com/subscriptions/v1/shops/{shop_id}/subscriptions' -H 'Authorization: Bearer {api_tokne}'

API: List subscriptions

サブスク個別情報の取得

curl 'https://api.boldcommerce.com/subscriptions/v1/shops/{shop_id}/subscriptions/{subsc_id}' -H 'Authorization: Bearer {api_tokne}'

API: Get subscription

サブスクごとの注文履歴の取得

サブスクごとの Shopify の注文履歴は、サブスク個別情報の取得には含まれないので、別途専用のAPIを呼び出す必要があります。

curl 'https://api.boldcommerce.com/subscriptions/v1/shops/{shop_id}/subscriptions/{subsc_id}/orders' -H 'Authorization: Bearer {api_key}' |jq

API: List subscription orders

次回配送日の変更

curl -X PUT 'https://api.boldcommerce.com/subscriptions/v1/shops/{shop_id}/subscriptions/{subsc_id}/next_shipping_date' -H "Content-Type: application/json" -H 'Authorization: Bearer {api_key}' -d '{"nextDate": "2021-12-04T15:00:00Z"}'

引数の nextDate は UTC で指定する必要があります。なので、**2021/12/05 (JST)**に配送なら、2021-12-04T15:00:00Z と指定する必要あり。

API: Update subscription next order datetime

商品のスワップ

商品のスワップは、同じサブスクグループ内での商品の入れ替えのため、入れ替えたい商品があらかじめサブスクグループにある必要があります。

curl -X PUT https://api.boldcommerce.com/subscriptions/v1/shops/{shop_id}/subscriptions/{subsc_id}/products_swap -H 'Authorization: Bearer {api_token}' -d '{"swap_products":[{"line_item_id":969025,"platform_product_id": "7057642811234","platform_variant_id": "40986470351234","subscription_group_id": 21234}]}'

以下の4つのパラメータを指定する必要があります。

line_item_id: スワップ元(現在サブスクになる商品)の line_item_id。これは、Get subscription API を呼び出し、そこに含まれる line_item の情報から line_item id を取得しておく必要がある。
platform_product_id: 入れ替えたい商品の Shopifyの product_id。Shopifyの商品画面のURLから知ることができる。
platform_variant_id: 入れ替えたい商品の Shopifyの variant_id。Shopifyの商品のバリエーション画面のURLから知ることができる。
subscription_group_id: 対象のサブスクグループID。これも、Get subscription API で取得できる。

API: Swap subscription product

定期頻度の更新

定期便の頻度は自由に指定できるわけではなく、サブスクグループを作成したときに設定した頻度のどれかにしか変更できません。よって、あらかじめ変更したい頻度を設定しておく必要があります。

また、指定するのは、あらかじめ設定知る頻度に対応した ID となります。そのため、頻度更新APIを呼び出す前に、指定可能なIDを知っていおく必要があります。

そのため、まずはそのIDを取得するため、定期便頻度情報取得APIを呼び出します。

curl 'https://api.boldcommerce.com/subscriptions/v1/shops/{shop_id}/subscriptions/{subsc_id}/interval' -H 'Authorization: Bearer {api_token}' |jq

Response

{
  "intervals": [
    {
      "interval_number": 1,
      "interval_type": "day",
      "week_type": "",
      "week_day": "",
      "month_type": "",
      "month_day": "",
      "month_occurrence": "",
      "month_occurrence_day": "",
      "year_type": "",
      "year_month": "",
      "year_occurrence": "",
      "year_occurrence_day": "",
      "interval_name": "1day",
      "custom_billing_rule": "",
      "buffer_days": 0,
      "buffer_time": "00:00:00",
      "id": 46018,
      "billing_rule": "DTSTART:20211003T174003Z\nRRULE:FREQ=DAILY"
    },
    ....
  ]
}

このレスポンスに含まれる id を取得しておきます。

API:List subscription intervals

上記の定期頻度情報取得 API から取得した頻度情報から変更したい頻度の id を subscriptionIntervalId パラメーターに指定します。

curl -X PUT "https://api.boldcommerce.com/subscriptions/v1/shops/{shop_id}/subscriptions/{subsc_id}/interval/{subscriptionIntervalId}" -H 'Authorization: Bearer {api_token}'

API: Update subscription interval

以上、ざっとですが、 Bold Subscript V2 の API の利用方法を紹介しました。