Create Checkout Session

Create a Stripe checkout session for a public self-serve plan.

This endpoint requires an authenticated account with billing permission, but it does not require an active subscription. Read GET /v1/account/plans, explain the exact recurring price, billing interval and quantity, and get customer approval before creating checkout. Never collect payment details in chat.

Request example

1234567curl -X POST https://api.v2.dealmachine.com/v1/checkout \
  -H "Authorization: Bearer dm_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "price_id": "price_xxx_monthly",
    "quantity": 1
  }'

Response example

1234567{
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_123",
  "session_id": "cs_test_123",
  "expires_at": "2026-06-17T19:00:00.000Z",
  "payment_status": "pending",
  "next_step": "Complete payment on Stripe, then check account and usage before retrying paid work."
}

Request Body

Field	Type	Required	Description
`price_id`	string	Yes	Stripe price ID from `GET /v1/plans`
`quantity`	number	No	Seat quantity. Defaults to `1`.

Use the stripe_price_ids.monthly or stripe_price_ids.annual value returned by GET /v1/plans.

Guardrails

POST /v1/checkout only accepts public self-serve prices returned by GET /v1/plans.

Rule	Behavior
Scale plans	Rejected. Scale is sales-managed and not self-serve.
Private offer plans	Rejected unless they become public in the shared plan catalog.
Unknown Stripe prices	Rejected with `invalid_price_id`.
Quantity above plan max	Rejected with `invalid_request`.
More than 60,000 monthly data credits	Rejected with `invalid_request`.

Billing mutation endpoints share a daily organization-level rate limit. When exceeded, the API returns 429 billing_rate_limited.

Response Fields

Field	Type	Description
`checkout_url`	string	Stripe-hosted checkout URL
`session_id`	string	Stripe checkout session ID
`expires_at`	string	ISO 8601 timestamp when the session expires

Complete payment before retrying

The returned URL is a Stripe-hosted checkout page. Stripe may offer Link and other enabled payment methods. Creating a session does not charge the customer or activate a subscription. Canceled, incomplete and failed payment attempts leave paid operations locked.

After the customer pays, check GET /v1/account for paid access and GET /v1/usage for available credits. Retry the approved operation only after those checks allow it. Do not repeatedly create checkout sessions while waiting for billing to update.

MCP uses dealmachine_checkout with confirmed=true; the CLI previews the plan with dm checkout --price-id <id> and requires --yes to create the session.