サブスクアプリ Bold Subscription v2 の API を利用してみる


[Shopify Advent Calendar 2021](https://qiita.com/advent-calendar/2021/shopify) 21日目の記事です。

Shopify のサブスク用アプリである [Bold Subscription V2 の API](https://developer.boldcommerce.com/default/documentation/subscriptions) の使い方やできることを紹介します。

[Bold Subscription](https://apps.shopify.com/bold-subscriptions?locale=ja) って何？っていう人は、こちらの「[Shopify のサブスク(定期購入) アプリ Bold Subscription を利用する](https://qiita.com/kumatronik/items/f69a7692bac681795493)」を先にご覧ください。

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

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

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

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

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


# Bold Subscription API でできること

Bold Subscription API でできることをざっと紹介します。その他にもたくさんありますので、知りたい方は、[API Doc]((https://developer.boldcommerce.com/default/documentation/subscriptions)) をご覧ください。

- サブスク情報の一覧を取得する
- 特定のサブスク注文情報を取得する
- 特定のサブスク注文の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 のアカウントを作成する**

1. [Bold Account Center アカウント作成画面](https://apps.boldapps.net/accounts/welcome) にアクセスします。
1. 右の `Create a new organization of your own` を選択します。
   ![Create a new organization (1).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/46003/4f894be7-7247-6c9d-b736-a56c20b2a81c.png)
1. 自身の名前、組織名、メアド、パスワードを入力し、**Create account** を押します。。
   ![Account Center Sign Up Organization.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/46003/db6b305e-fa02-2c64-e13a-b150184a9075.png)
1. **Platform** で `ShopifyP を選択し、**Store URL** に Bold Subscription を導入しているShopify ストアのURLを設定します。(そうすることで、ここで作成する Bold アカウントとShopifyに導入しているアプリとを紐づけます。)
   ![Add your first store.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/46003/cef23f2c-8e02-2c38-346d-510cfcf178e2.png)
1. Shopify ストアとの接続検証確認を求められるので、**Verify store** を押します。
   ![Verify Store.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/46003/45df4958-42a8-8ede-fbdd-b1fb995cf664.png)
1. 以上でアカウントの登録は完了です。

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

1. 1で作成したアカウントにアクセスします。
1. 画面左メニューの **Developer Settings** を押します。
   ![スクリーンショット_2021-12-18_17_17_42.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/46003/aff8c56e-0638-3ef8-763b-8cec64659620.png)
1. **Create API access token** を押します。
   ![スクリーンショット_2021-12-18_17_20_42.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/46003/da2c93dd-c5a0-6980-83f2-be21b8a47f34.png)
1. トークン(キー)名を入力し、APIで利用する権限にチェックします。今回は、Subscription API の利用なので、一番下の Subscriptions の **Read & Write** にチェックします。どの項目をチェックするかは、やりたいことによるので、できるだけ必要最低限の項目にチェックしてください。事前に API Doc をみて、どのAPIを使うかを知った上で選択すると良いと思います。
   ![スクリーンショット 2021-12-18 17.20.23.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/46003/21c9d426-426d-c68f-9447-4c2b66c28fb1.png)
1. **Create** ボタンを押すと、API キーは生成されます。この画面で **Shared Secret** と **API アクセストークン**が表示されますので、必ずメモしておいてください。この画面を閉じると、二度と確認することはできません。
   ![スクリーンショット_2021-12-18_17_26_09.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/46003/5bfee504-6d9d-a2cb-b67b-8a80a21ab55e.png)
1. 画面下のチェックボックスにチェックし、**Done** を押します。これで、API キーの作成は終わりました。

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

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

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

参考: [公式: Bold アカウントの作り方 (英語)](https://support.boldcommerce.com/hc/en-us/articles/360060353652-Create-Connect-a-Bold-Account)

## Subscription API 呼び出し準備

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

```shell
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 を通して取得します。

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

Response 

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

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

これで、ようやく Subscription API の呼び出し準備が整いました。あとは、[API Doc](https://developer.boldcommerce.com/default/documentation/subscription-builder) をみながら、呼び出したい API を利用するだけです。

## サンプルコード


### ショップ情報の取得

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

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

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


Response


```json
{
  "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 で確認してください。

### サブスク一覧の取得

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

[API: List subscriptions](https://developer.boldcommerce.com/default/documentation/subscriptions#/Subscriptions/getSubscriptions)

### サブスク個別情報の取得

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

[API: Get subscription](https://developer.boldcommerce.com/default/documentation/subscriptions#/Subscriptions/listSubscriptions)

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

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

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

[API: List subscription orders](https://developer.boldcommerce.com/default/documentation/subscriptions#/Subscriptions/listSubscriptionOrders)


### 次回配送日の変更

```shell
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](https://developer.boldcommerce.com/default/documentation/subscriptions#/Subscriptions/updateSubscriptionNextOrderDate)

### 商品のスワップ

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

```shell
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](https://developer.boldcommerce.com/default/documentation/subscriptions#/Subscriptions/swapSubscriptionProduct)


### 定期頻度の更新

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

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

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

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

Response

```json
{
  "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](https://developer.boldcommerce.com/default/documentation/subscriptions#/Subscriptions/listSubscriptionIntervals)

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

```shell
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](https://developer.boldcommerce.com/default/documentation/subscriptions#/Subscriptions/updateSubscriptionInterval)

---

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