Checkout Flow

Cuprice prices the plan, hands the buyer to your checkout link, and steps out. Your checkout charges the buyer and sends them back.

Regular plans

The buyer clicks a plan on your pricing page or embed, with monthly or annual billing selected.
Cuprice builds a checkout payload for that plan from the live plan data.
Cuprice sends the buyer to your checkout link with the query parameters below. With postMessage, it fires cuprice:checkout on your page instead.
Your checkout creates the payment with your provider.
When the payment is done, your checkout sends the buyer to success_url. If they leave, it sends them to cancel_url.

Custom plans

The buyer opens the custom plan card, picks features and sets amounts for limit and usage-based features.
Cuprice prices the selection on its server.
The handoff works as for regular plans, with cuprice_custom_plan=true, cuprice_plan_id=0 and the chosen features in selected_features.

The custom plan card always sends monthly billing (interval=month).

Query parameters

Cuprice adds these to your checkout link:

Parameter	Example	Meaning
`plan_id`	`pro`	The Plan ID shown in the plan editor. Cuprice generates it from the plan name, so it changes when you rename the plan.
`external_plan_id`	`pro`	Same value as `plan_id`.
`cuprice_plan_id`	`768`	Cuprice’s numeric plan ID. It stays the same when you rename the plan. `0` for a custom plan.
`cuprice_share_id`	`YOUR_SHARE_ID`	Share ID of the page the buyer came from.
`cuprice_project_id`	`452`	Cuprice’s numeric project ID.
`cuprice_project_slug`	`my-saas`	Project slug, as used in the API v1.
`amount`	`29`	Price for the chosen interval. For annual billing it is the price of the whole year after the annual discount.
`currency`	`USD`	The project currency.
`interval`	`month`	`month` or `year`.
`plan_name`	`Pro`	Plan name as shown on the page.
`email`	`ana@example.com`	Sent only when an email was passed to the Checkout Payload request. The pricing page does not collect one.
`is_free`	`true`	Sent only for free plans.
`success_url`		Where to send the buyer after payment. See Redirect URLs.
`cancel_url`		Where to send the buyer if they leave checkout.
`cuprice_billing_interval`	`month`	Same value as `interval`.
`cuprice_custom_plan`	`true`	Custom plans only.
`selected_features`	`API calls,Storage`	Custom plans only. The chosen feature names, separated by commas.
`feature_usage`	`{"Storage":1000}`	Custom plans only, when the buyer set amounts. A JSON object of feature name to amount.

A regular monthly plan arrives like this (line breaks added):

https://yourapp.com/billing/checkout
  ?plan_id=pro
  &external_plan_id=pro
  &cuprice_plan_id=768
  &cuprice_share_id=YOUR_SHARE_ID
  &cuprice_project_id=452
  &cuprice_project_slug=my-saas
  &amount=29
  &currency=USD
  &interval=month
  &plan_name=Pro
  &success_url=https%3A%2F%2Fapp.cuprice.io%2Fshare%2FYOUR_SHARE_ID%3Fsuccess%3Dtrue%26plan%3DPro
  &cancel_url=https%3A%2F%2Fapp.cuprice.io%2Fshare%2FYOUR_SHARE_ID%3Fcanceled%3Dtrue
  &cuprice_billing_interval=month

The query string passes through the buyer’s browser, so anyone can change amount before it reaches you. Never charge the amount from the URL. Look the price up on your server: from your own price list by plan_id, or from the Checkout Payload endpoint by cuprice_plan_id and interval.

Feature names in selected_features are joined with commas, so a feature name that contains a comma cannot be split back reliably. Keep commas out of feature names, or use postMessage, whose payload carries the names as an array.

The checkout payload

The cuprice:checkout event and the Checkout Payload endpoint carry the same JSON. Trimmed example for an annual plan:

{
  "shareId": "YOUR_SHARE_ID",
  "projectId": 452,
  "projectSlug": "my-saas",
  "customer": { "email": null },
  "returnUrls": {
    "success": "https://app.cuprice.io/share/YOUR_SHARE_ID?success=true&plan=Starter",
    "cancel": "https://app.cuprice.io/share/YOUR_SHARE_ID?canceled=true"
  },
  "plan": {
    "id": 768,
    "externalPlanId": "starter",
    "name": "Starter",
    "interval": "year",
    "currency": "USD",
    "amount": 182.4,
    "isFree": false,
    "isCustom": false
  },
  "features": [
    {
      "id": 2279,
      "name": "Team seats",
      "featureType": "Limits",
      "included": true,
      "limit": 5,
      "pricing": { "model": "limits", "unitPrice": 2, "subtotal": 10 }
    }
  ],
  "pricingBreakdown": {
    "billingInterval": "year",
    "currency": "USD",
    "subtotal": 19,
    "annualDiscountEnabled": true,
    "annualDiscountPercent": 0.2,
    "annualDiscountAmount": 45.6,
    "total": 182.4
  },
  "customPlan": null,
  "metadata": {
    "cupricePlanId": "768",
    "cupriceShareId": "YOUR_SHARE_ID",
    "cupriceProjectId": "452",
    "cupriceProjectSlug": "my-saas",
    "billingInterval": "year"
  }
}

plan.amount is the price the buyer saw on the page for the chosen interval. In this example the monthly price is 19, so a year is 19 × 12 = 228, minus the 20% annual discount (45.6), which gives 182.4. Annual amounts can carry floating-point noise (a 49 plan comes out as 470.40000000000003), so round to your currency’s smallest unit before charging. The amount query parameter has the same value.
features lists what the plan includes, with each limit worked out. Feature Gating uses it to unlock features after payment.
For a custom plan, plan.isCustom is true, plan.id is 0, and customPlan holds selectedFeatures and featureUsageAmounts.
metadata holds string IDs you can copy straight into your payment provider’s metadata, so the payment can be matched back to the Cuprice plan later.

Getting Started

Embed Widget

Checkout

Feature Gating

Customization

AI Tools

Regular plans

Custom plans

Query parameters

The checkout payload

​Regular plans

​Custom plans

​Query parameters

​The checkout payload

Regular plans

Custom plans

Query parameters

The checkout payload