> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cuprice.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkout Payload

> Get the price and features Cuprice hands to your checkout

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

**shareId** `string` *required*

The project's Share ID

## Query Parameters (GET)

**planId** `number` *required*

Cuprice's numeric plan ID: `cuprice_plan_id` in the checkout link, or `pricingPlans[].id` in the [Share API](https://docs.cuprice.io/api-reference/share.md). Only plans that are visible on the page are found.

**billingInterval** `string` (default: month)

`month` or `year`. Any other value counts as `month`.

**email** `string`

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

## Body Parameters (POST)

**selectedFeatures** `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`.

**featureUsageAmounts** `object`

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

**billingInterval** `string` (default: month)

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

**email** `string`

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

## Response

**payload** `object`

The plan, its features, the price breakdown, return URLs and metadata. Field by field in [Checkout Flow](https://docs.cuprice.io/payments/checkout-flow.md#the-checkout-payload).

**handoffUrl** `string`

Your checkout link with all [query parameters](https://docs.cuprice.io/payments/checkout-flow.md#query-parameters) added: the address a buyer is sent to.

**handoffMethod** `string`

`redirect` or `postMessage`, as set under **Integration > Payment**.

**paymentMode** `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

```bash theme={null}
curl "https://app.cuprice.io/api/share/YOUR_SHARE_ID/checkout-payload?planId=768&billingInterval=year"
```

```json theme={null}
{
  "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

```bash theme={null}
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:

```json theme={null}
{
  "selectedFeatures": ["Team seats", "Priority support"],
  "featureUsageAmounts": { "Team seats": 3 }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.