---
title: 購入者の状態
description: メールアドレスから、お客様に付いている機能フラグを照会する。
---

購入者の状態は、お客様が今どの機能フラグを持っているかを、1回の照会で返すものです。アプリのサーバーで、限定機能を開くかどうかと、上限などの設定値を決めるために使います。

購入者の状態の API にメールアドレスを渡すと、そのお客様に付いている機能フラグと設定値が返ります。機能フラグの商品を使うアプリで、機能の API ごとに権利を確かめるときに使います。

## 状態に含まれるもの

状態に含まれる権利は、今は機能フラグだけです。応答の形は次のとおりです。

```json
{
  "customer_id": "…",
  "feature_flags": [
    {
      "product_id": "…",
      "benefit_id": "…",
      "granted_at": "…",
      "metadata": { "daily_messages": 500 }
    }
  ]
}
```

| 項目 | 内容 |
| --- | --- |
| `customer_id` | このクリエイターのお客様としての ID です。機能フラグが1つ以上あるときだけ入り、無ければ `null` です。 |
| `feature_flags` | 付与されている（剥奪されていない）機能フラグの一覧です。商品ごとに1件で、付与された日時の古い順に並びます。購入者限定ページの権利は含みません。 |
| `feature_flags[].product_id` | 商品の ID です。 |
| `feature_flags[].benefit_id` | 商品の種類の設定の ID です。 |
| `feature_flags[].granted_at` | いま有効な権利のうち、いちばん古い付与の日時です。外れた権利は数えないため、全額返金のあとに同じ商品を買い直すと、買い直したときの日時になります。初回の購入日時としては使わないでください。 |
| `feature_flags[].metadata` | 商品に設定した設定値です。 |

`benefit_id` は商品の種類の設定（API では benefit）の ID です。1つの商品に1つあります。詳しくは [商品の種類の概要](/features/benefits) を参照してください。

機能フラグが無いときも、成功の応答になります。`customer_id` は `null`、`feature_flags` は空の配列です。この照会は機能フラグの権利だけを返します。購入の有無をこの API で判定することはできません。

設定値（`metadata`）には次の決まりがあります。

- 50件までです。キーは1〜40字の英数字、`_`、`-` です。
- 値は文字列（1〜500字）、数値、真偽値のいずれかです。
- 管理画面と API の応答にそのまま表示されます。URL や API キーなどの秘密の値は入れないでください。

SDK の関数では、項目の名前が camelCase になります（`customerId`、`featureFlags`、`productId`、`benefitId`、`grantedAt`、`metadata`）。

## 照会する

`POST /customers/state` を自分のサーバーから呼びます。スコープは `customers:read` です。メールアドレスは URL ではなく本文で送ります。

```json
{
  "email": "buyer@example.com"
}
```

SDK では次の関数で呼びます。Next.js では `@nulogic/cozeni-sdk/next` から読み込みます。

- `getCustomerState({ email })`：付いている機能フラグをすべて返します。
- `hasFeatureFlag({ email, productId })`：特定の商品の機能フラグだけを確かめます。無ければ `{ granted: false, metadata: {} }` を返します。

応答の形は [状態に含まれるもの](#状態に含まれるもの) を見てください。API のリファレンスは [購入者の状態を取得](/api-reference/customer/external-get-customer-state) を見てください。

## キャッシュと再照会

- 照会の結果は最大60秒までキャッシュしてかまいません。キャッシュは自分のサーバーのメモリに置きます。
- 付与されている（`granted: true`）結果だけをキャッシュします。付与されていない結果をキャッシュすると、お客様が購入した直後の60秒間、購入済みなのに未購入と判定されます。
- 機能フラグが剥奪された場合は、キャッシュの期限である60秒以内に反映されます。
- 購入直後は、権利ができるまで数秒かかることがあります。見つからないときは、2秒おきに最大3回など、回数を限って照会し直します。

メールアドレスをログや外部の保存先、分析の仕組みに出さないでください。

## 前提

:::caution
機能フラグを使う前に、アプリのログインでメールアドレスの本人確認を済ませてください。Cozeni の購入画面では、メールアドレスは確認していません。確認していないメールアドレスでアカウントを作れると、ほかの人の購入をそのアカウントで使えてしまいます。
:::

機能を使えるかどうかを自分のサーバーで判定してください。画面で隠すだけでは、機能の API を直接呼ばれると使えてしまいます。

## レート制限

照会の API の呼び出し回数は管理の API とは別の枠で数えます。キーごとに600回/分が上限です。超えると、`429` の `rate_limited` が返り、`Retry-After` で待つ秒数が分かります。SDK は自動で再送しません。詳しくは [レート制限](/api-reference/rate-limits) を見てください。

## 次に読むページ

**[機能フラグ](/features/benefits/feature-flags)**

機能フラグの商品の作り方と、設定値の使い方を説明します。

**[Next.js](/integrate/sdk/nextjs)**

`createCheckout`、`getCustomerState`、`hasFeatureFlag` のコード例があります。

**[JavaScript / TypeScript](/integrate/sdk/javascript)**

Next.js 以外のサーバーで、管理のクライアントから照会します。

**[購入者の状態を取得](/api-reference/customer/external-get-customer-state)**

照会の API のリファレンスです。
