Checkout Payload

Returns the checkout payload for a plan, or for a custom selection of features: the price for the chosen billing interval, the features with their limits, and the full link to your checkout. The pricing page calls this endpoint when a buyer clicks a plan. Your server can call it too, to price a purchase without trusting the query string. No authentication.

Endpoints

GET  /api/share/{shareId}/checkout-payload   (a plan on the page)
POST /api/share/{shareId}/checkout-payload   (a custom plan)

Path Parameters

The project’s Share ID

Query Parameters (GET)

number

required

Cuprice’s numeric plan ID: cuprice_plan_id in the checkout link, or pricingPlans[].id in the Share API. Only plans that are visible on the page are found.

string

default:"month"

month or year. Any other value counts as month.

string

Buyer email to carry through to the payload and the checkout link.

Body Parameters (POST)

array

required

The chosen features, as objects with a name that matches a feature in the project, for example [{ "name": "API calls" }]. Names that match no feature are left out of the price and of features.

object

Amounts for limit and usage-based features, keyed by feature name, for example { "API calls": 10000 }.

string

default:"month"

month or year. The custom plan card on the pricing page always sends month.

string

Buyer email to carry through to the payload and the checkout link.

Response

object

The plan, its features, the price breakdown, return URLs and metadata. Field by field in Checkout Flow.

string

Your checkout link with all query parameters added: the address a buyer is sent to.

string

redirect or postMessage, as set under Integration > Payment.

string

Always handoff.

Errors

Status	`error`	When
400	`Online checkout isn't set up for this page yet. Contact the company to sign up.`	The project has no checkout link. The body also has `"code": "CHECKOUT_NOT_CONFIGURED"` and still carries `payload`.
400	`planId is required`	GET without a numeric `planId`.
400	`selectedFeatures is required`	POST with an empty or missing `selectedFeatures`.
404	`Project not found`	No project has this Share ID.
404	`Plan not found`	The plan does not belong to this project or is hidden on the page.

Example: a plan

curl "https://app.cuprice.io/api/share/YOUR_SHARE_ID/checkout-payload?planId=768&billingInterval=year"

{
  "payload": {
    "plan": {
      "id": 768,
      "externalPlanId": "starter",
      "name": "Starter",
      "interval": "year",
      "currency": "USD",
      "amount": 182.4,
      "isFree": false,
      "isCustom": false
    },
    "features": [
      { "id": 2278, "name": "Pricing pages", "included": true, "limit": null },
      { "id": 2279, "name": "Team seats", "included": true, "limit": 5 }
    ],
    "customPlan": null
  },
  "handoffUrl": "https://yourapp.com/billing/checkout?plan_id=starter&external_plan_id=starter&cuprice_plan_id=768&...",
  "handoffMethod": "redirect",
  "paymentMode": "handoff"
}

The response is trimmed. features entries also carry featureType, multiplier, basePrice and a pricing object.

Example: a custom plan

curl -X POST "https://app.cuprice.io/api/share/YOUR_SHARE_ID/checkout-payload" \
  -H "Content-Type: application/json" \
  -d '{
    "selectedFeatures": [{ "name": "Team seats" }, { "name": "Priority support" }],
    "featureUsageAmounts": { "Team seats": 3 },
    "billingInterval": "month"
  }'

The response has the same shape. payload.plan.id is 0, payload.plan.isCustom is true, and payload.customPlan holds the selection:

{
  "selectedFeatures": ["Team seats", "Priority support"],
  "featureUsageAmounts": { "Team seats": 3 }
}

Overview

Public Endpoints

API v1 — Projects

API v1 — Features

API v1 — Plans

API v1 — Plan Features

API v1 — Subscriptions

Checkout Payload

Endpoints

Path Parameters

Query Parameters (GET)

Body Parameters (POST)

Response

Errors

Example: a plan

Example: a custom plan

​Endpoints

​Path Parameters

​Query Parameters (GET)

​Body Parameters (POST)

​Response

​Errors

​Example: a plan

​Example: a custom plan

Endpoints

Path Parameters

Query Parameters (GET)

Body Parameters (POST)

Response

Errors

Example: a plan

Example: a custom plan