> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paywithsoap.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscription Checkout

> Create a recurring deposit checkout with subscription billing metadata

## Overview

A subscription checkout creates a recurring deposit flow for a customer. Subscription checkouts are deposit-only and require `line_items` plus `subscription_data`.

Subscription checkouts use the same line item formats as purchase checkouts. You can reference existing products by `product_id` or create inline dynamic products with `name`, `price_cents`, and `quantity`.

## How It Works

1. Create a checkout session with `type: "deposit"`.
2. Include `line_items` for the subscription product.
3. Include `subscription_data` with the billing interval and interval count.
4. The customer is redirected to the Soap-hosted checkout page.
5. Upon completion, Soap creates the checkout and associated subscription metadata.

## API Request

<Note>
  You can also manage products from the Soap dashboard and reference them by ID. Simply pass `line_items: [{ "product_id": "pr_XXX", "quantity": 1 }]` instead of inline product details.
</Note>

```bash theme={null}
curl -X POST 'https://api-sandbox.paywithsoap.com/api/v1/checkouts' \
--header 'Content-Type: application/json' \
--header 'Authorization: YOUR_API_KEY' \
--data '{
    "customer_id": "cus_aaN5GMMF8CFpsYMuEnN9DPFMtGQaVDQZ",
    "type": "deposit",
    "line_items": [
        {
            "name": "Premium Monthly Plan",
            "price_cents": 2999,
            "quantity": 1,
            "sku": "PREMIUM-MONTHLY",
            "url": "https://images.unsplash.com/photo-1516321318423-f06f85e504b3?auto=format&fit=crop&w=800&q=80",
            "dedup": true
        }
    ],
    "subscription_data": {
        "interval": "month",
        "interval_count": 1
    }
}'
```

## Key Parameters

| Parameter                          | Required | Description                                                     |
| ---------------------------------- | -------- | --------------------------------------------------------------- |
| `customer_id`                      | Yes      | The customer's unique identifier                                |
| `type`                             | Yes      | Must be `"deposit"`                                             |
| `line_items`                       | Yes      | Array of existing product references or inline dynamic products |
| `subscription_data.interval`       | Yes      | Billing interval: `day`, `week`, `month`, or `year`             |
| `subscription_data.interval_count` | Yes      | Number of intervals between charges                             |
| `experience`                       | No       | `"web"` or `"webview"`                                          |
| `return_url`                       | No       | Where to redirect the customer after completion                 |

## Line Items

Subscription line items can be either:

* An existing product reference with `product_id` and `quantity`.
* An inline dynamic product with `name`, `price_cents`, and `quantity`, plus optional `sku`, `url`, and `dedup`.

When `dedup` is `true`, include a stable `sku`. Soap reuses a matching product for the same business when both `sku` and `price_cents` match. If `dedup` is absent or `false`, Soap creates a new active product from the inline line item.

### Line Item Parameters

| Parameter                  | Required                        | Description                                                                                                              |
| -------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `line_items[].product_id`  | Yes for existing products       | Soap product ID for an existing product. Use with `quantity`.                                                            |
| `line_items[].name`        | Yes for inline products         | Product name to create and display in checkout.                                                                          |
| `line_items[].price_cents` | Yes for inline products         | Unit price in cents. Must be at least `1`. Subscription line items snapshot this price when the subscription is created. |
| `line_items[].quantity`    | Yes                             | Number of units to purchase each billing interval. Must be at least `1`.                                                 |
| `line_items[].sku`         | Required when `dedup` is `true` | Stable merchant SKU used with `price_cents` to find an existing product for this business.                               |
| `line_items[].url`         | No                              | Product image URL shown in checkout where supported.                                                                     |
| `line_items[].dedup`       | No                              | When `true`, Soap reuses an existing product for the same business when `sku` and `price_cents` match. Requires `sku`.   |

## When to Use

* Monthly or annual memberships
* Recurring subscription products
* Quarterly billing using `interval: "month"` and `interval_count: 3`

<Card title="Back to Create Checkout" icon="arrow-left" href="/api-reference/api-v1/checkouts/create">
  View the full API reference for creating checkouts.
</Card>