Generate a hosted page URL with POST /api/v2/hosted_pages/checkout_new_for_items; supply subscription_items[0][item_price_id] and customer[email]; the response contains the hosted_page url
Redirect the customer to the hosted page URL; Chargebee handles payment collection, SCA, and subscription creation
Configure the redirect_url on the hosted page request to specify where Chargebee sends the customer after successful checkout; the redirect includes a hosted_page_id query parameter
After redirect, verify the checkout outcome server-side with GET /api/v2/hosted_pages/HOSTED_PAGE_ID; confirm state=succeeded before provisioning access
Listen for subscription_created webhook to asynchronously provision entitlements; validate the webhook payload using the Chargebee-provided webhook password header
For a returning subscriber, use POST /api/v2/hosted_pages/checkout_existing_for_items with the existing subscription_id to allow plan upgrades/downgrades via hosted page
Known gotchas
Hosted page URLs are time-limited (default 1 hour from generation); redirecting a customer to an expired URL returns a 'Page not found' error — regenerate fresh URLs close to the time of use
The checkout_new and checkout_new_for_items endpoints are different — checkout_new uses the legacy plan-addon model while checkout_new_for_items uses the current item-price model; check which product catalog version (v1 or v2) your Chargebee site uses
Do not rely solely on the redirect URL callback for provisioning — network issues can prevent the redirect; always use the subscription_created webhook as the authoritative provisioning trigger
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp