Skip to main content

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.

​
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

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: 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

ParameterRequiredDescription
customer_idYesThe customer’s unique identifier
typeYesMust be "deposit"
line_itemsYesArray of existing product references or inline dynamic products
subscription_data.intervalYesBilling interval: day, week, month, or year
subscription_data.interval_countYesNumber of intervals between charges
experienceNo"web" or "webview"
return_urlNoWhere 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

ParameterRequiredDescription
line_items[].product_idYes for existing productsSoap product ID for an existing product. Use with quantity.
line_items[].nameYes for inline productsProduct name to create and display in checkout.
line_items[].price_centsYes for inline productsUnit price in cents. Must be at least 1. Subscription line items snapshot this price when the subscription is created.
line_items[].quantityYesNumber of units to purchase each billing interval. Must be at least 1.
line_items[].skuRequired when dedup is trueStable merchant SKU used with price_cents to find an existing product for this business.
line_items[].urlNoProduct image URL shown in checkout where supported.
line_items[].dedupNoWhen 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.