Ecomm Purchase

Overview

An ecommerce purchase checkout allows customers to buy physical goods such as nutraceuticals, peptides, supplements, and other products. This uses line items to define what the customer is buying, with a traditional shopping cart experience. 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.

How It Works

Create Or Provide Products

You can create products in Soap ahead of time or pass inline dynamic product details directly in line_items.

Create a Checkout Session

Create a checkout session with type: "deposit" and include line_items.

Line items with sku: "shipping" or sku: "tax" are treated as special product types and are rendered in the checkout UI as you would expect (as shipping and tax line items rather than regular products).

Customer Completes Purchase

The customer is redirected to the Soap-hosted checkout page showing the cart and total, selects a payment method, and completes the purchase.

Receive Confirmation

Upon completion, a webhook is fired and the customer is redirected back to your app.

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_vi57KegYgcRqcGHqip8q6UZiqtrwMT870",
    "type": "deposit",
    "line_items": [
        {
            "name": "Peptide Starter Kit",
            "price_cents": 9999,
            "quantity": 1,
            "sku": "peptide-starter-kit",
            "url": "https://example.com/products/peptide-starter-kit.png",
            "dedup": true
        },
        {
            "name": "Shipping",
            "price_cents": 1000,
            "quantity": 1,
            "sku": "shipping",
            "dedup": true
        },
        {
            "name": "Tax",
            "price_cents": 825,
            "quantity": 1,
            "sku": "tax",
            "dedup": true
        }
    ],
    "experience": "web",
    "return_url": "https://myapp.com/orders"
}'

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
`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 Item Parameters

Each line item can reference an existing product or define a product inline.

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`.
`line_items[].quantity`	Yes	Number of units to purchase. 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

Nutraceuticals and peptide products
Supplements and wellness items
Any physical goods catalog or dynamically priced cart

← Back to Create Checkout

View the full API reference for creating checkouts.

API Documentation

API Endpoints

Webhooks

Testing

Ecomm Purchase

Overview

How It Works

API Request

Key Parameters

Line Item Parameters

When to Use

← Back to Create Checkout

​Overview

​How It Works

​API Request

​Key Parameters

​Line Item Parameters

​When to Use

← Back to Create Checkout

Overview

How It Works

API Request

Key Parameters

Line Item Parameters

When to Use