Subscription Checkout

Overview

A subscription checkout creates a recurring deposit flow for a customer. Subscription checkouts are deposit-only and require line_items plus subscription_data. Every Soap API request is authenticated with a bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Your API key is in the Soap Dashboard under the Developers section. It looks like key_.... Requests with a missing or invalid API key return 422 — never 401 — with a JSON error field, usually {"error": "API key not found."}. Branch on the status code rather than the message: GET /api/v1/device_pings/latest_geo_check does not yet return the same wording. Never expose your API key in client-side code — it is server-side only. 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

Create a checkout session with type: "deposit".
Include line_items for the subscription product.
Include subscription_data with the billing interval and interval count.
The customer is redirected to the Soap-hosted checkout page.
The checkout and its subscription record are created by the API call itself (the response already carries subscription.id); the customer’s payment at the hosted page attaches the payment method used for renewals.

API Request

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.

curl -X POST 'https://api-sandbox.paywithsoap.com/api/v1/checkouts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 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"`, `"webview"`, or `"iframe"`. Use `"iframe"` when embedding the checkout — see Embedded Checkout.
`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

Back to Create Checkout

View the full API reference for creating checkouts.

API Documentation

API Endpoints

Webhooks

Testing

Subscription Checkout

Overview

How It Works

API Request

Key Parameters

Line Items

Line Item Parameters

When to Use

Back to Create Checkout

​Overview

​How It Works

​API Request

​Key Parameters

​Line Items

​Line Item Parameters

​When to Use

Back to Create Checkout

Overview

How It Works

API Request

Key Parameters

Line Items

Line Item Parameters

When to Use