---
title: 購入画面の API
description: メールアドレスを固定した購入画面を、サーバーから作る。
---

購入画面の API はアプリのサーバーから購入画面の URL を作ります。購入画面のメールアドレスはアプリにログインしている人のものに固定されます。機能フラグの商品を売るときに使い、購入者限定ページの商品でも使えます。

## 使いどころ

- 機能フラグの商品を、アプリにログインしている人のメールアドレスで買ってもらうとき。
- 購入者限定ページの商品でも、同じようにメールアドレスを固定して売れます。
- 購入画面のメールアドレスは変更できません。そのため、購入の記録のメールアドレスと、機能フラグの照会で使うメールアドレスが一致します。

公開の [購入リンク](/features/checkout/links) でも購入できますが、サーバーで購入画面を作る方法を勧めます。

## 商品IDを確かめる

購入画面を作るには、商品ID（`prd_` で始まる値）が要ります。

- 購入者限定ページの商品：管理画面の商品詳細にある「プロダクトID」タブで確かめます。
- 機能フラグの商品：商品詳細には「プロダクトID」タブがありません。商品詳細の「アプリとつなぐ」にある組み込みプロンプトに、商品IDが書かれています。
- 外部 API：商品一覧（`GET /products`）の `id` が商品IDです。スコープは `products:read` です。

## 作り方

1. **購入画面を作る**

    アプリのサーバーで、商品IDとログイン中のメールアドレスを渡して、購入画面を作ります。

2. **URL を本人に渡す**

    返った URL を本人に渡します。URL は30分で失効します。

3. **失効したら作り直す**

    失効したら、もう一度作り直します。

失効した URL をお客様が開くと、購入画面には「購入画面の有効期限が切れました」と表示され、支払いに進めません。カードの認証などで購入画面の外へ移ったあと、決済に失敗して戻ったときも、お客様には「お支払いを確認できませんでした」と表示され、同じ URL ではやり直せません。購入画面の中でカードが拒否されたときは、そのまま別のカードで支払えます。どちらの画面にもボタンは無く、アプリに戻ってもう一度進むよう案内が出ます。アプリのサーバーで購入画面を作り直してください。

SDK（`@nulogic/cozeni-sdk/next`）では `createCheckout()` を使います。

```ts app/api/checkout/route.ts
import { createCheckout } from "@nulogic/cozeni-sdk/next";

const PRODUCT_ID = "prd_...";

export async function POST() {
  // アプリのログイン情報から取る
  const email = await loginEmail(); // アプリ側のログイン処理に置き換える
  const { url, expiresAt } = await createCheckout({
    productId: PRODUCT_ID,
    email,
  });
  // expiresAt は作成から30分後
  return Response.redirect(url, 303);
}
```

`createCheckout()` は `checkoutId`・`url`・`expiresAt` を返します。`url` は Cozeni の購入画面の URL で、購入の試行を指す値を含みます。メールアドレスは URL に含まれません。

:::caution
URL はログイン中の本人にだけ渡します。URL の購入画面では作るときに渡したメールアドレスで購入されます。ログや分析のツールに URL を残さないでください。
:::

メールアドレスは前後の空白を除いて小文字に揃えて保存されます。

API で作る場合は、`POST /checkout/sessions` に `product_id` と `email` を送ります。仕様は [購入画面を作成](/api-reference/checkout/external-create-checkout-session) を参照してください。

## 失敗したとき

失敗は `CozeniError` として投げられます。`code` で分岐できます。

| `code` | HTTP | 意味 | 扱い |
| --- | --- | --- | --- |
| `already_purchased` | 409 | そのメールアドレスで購入済み | 購入画面へ進めず、購入済みとして扱う |
| `creator_not_ready` | 409 | 販売の準備が整っていない | [売上の受け取り](/features/payouts) を確認する |
| `product_archived` | 410 | 商品がアーカイブ済み | 商品の状態を確認する |
| `checkout_link_disabled` | 410 | 商品の購入リンクが無効 | 管理画面で状態を確認する |
| `product_not_found` | 404 | 商品がない、他の販売者の商品、または標準の購入リンクが無い商品 | 商品IDを確認する |
| `sandbox_recipient_not_allowed` | 422 | サンドボックスで、管理画面のサインインに使うメールアドレス以外を指定した | 管理画面のサインインに使うメールアドレスで試す |
| `rate_limited` | 429 | 呼び出し回数の上限を超えた | `Retry-After` の秒数をおいてから再試行する |

:::note
`creator_not_ready` の応答には、対応すべき内容の一覧（`blockers`）は付きません。管理画面の「セットアップ」で状態を確認してください。
:::

## 必要なスコープ

- `checkouts:write`（管理画面の表示名は「購入画面を作る」）

:::note
このスコープは CLI のキーや導入用の初期設定には含まれません。管理画面の「開発者設定」で選んで発行してください。
:::

## 次に読むページ

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

機能フラグの組み込み全体。自分のアプリに限定機能を作ります。

**[購入者限定ページ](/features/benefits/gated-page)**

自分のサイトに限定ページを作る。

**[購入リンク](/features/checkout/links)**

商品ごとに1本ある、購入画面を開くための URL。

**[支払い方法](/features/checkout/payment-methods)**

購入画面で使える支払い方法。
