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

# Checkout Optionals

> Add-on services for buy and sell checkout quotes

Checkout **optionals** (also called addons) are optional services you can attach to a buy or sell quote — such as vault shipping, instant payout, or an insured overnight shipping label. Each quote response includes an `optionals[]` array showing what's available, whether each optional is selected, and whether you're eligible.

## Response Fields

Every optional in `optionals[]` includes:

| Field            | Description                                                          |
| ---------------- | -------------------------------------------------------------------- |
| `id`             | Unique ID to pass in `selectedOptionalIds`                           |
| `title`          | Display name (e.g. "Instant Payout")                                 |
| `description`    | What this optional does                                              |
| `fee`            | Fee in cents. On sell quotes, fees are negative (they reduce payout) |
| `selected`       | Whether this optional is currently selected on the quote             |
| `enabled`        | Whether you are eligible to select this optional                     |
| `disabledReason` | Why this optional is unavailable (when `enabled` is false)           |
| `disclaimer`     | Optional object with `label` and `url` for terms                     |

When `enabled` is false, read `disabledReason` for the specific eligibility issue rather than guessing.

## Built-in Optionals

### Vault Shipping (`vault_shipping`) — Buy

Ship purchased items to your Pure vault instead of a street address. When selected and eligible, vault shipping **waives standard shipping fees**.

Eligibility (enforced by the checkout engine):

* Buy-side only
* Organization must have vault shipping enabled
* Limited to a small number of line items per quote
* Silver products are not eligible

When vault shipping is selected, `shipping` is optional on execute — fulfillment goes to your vault.

### Instant Payout (`instant_payout`) — Sell

Receive your payout immediately instead of waiting for standard settlement. The fee reduces your total payout (returned as a negative `fee` on sell quotes).

Eligibility:

* Sell-side only
* Requires sufficient instant payout credit (check `GET /execution/payout-methods/v1`)
* Minimum subtotal threshold applies — if below the threshold, `enabled` will be false with a `disabledReason`

If credit is insufficient at execute time, you'll receive **422** with `errorCode: "instant_payout_insufficient_credit"`.

### Overnight Label (`overnight_label`) — Sell

Provides an insured overnight shipping label for items you ship to Pure. The fee reduces your payout.

Eligibility:

* Sell-side only
* Fee may be waived on high-value subtotals — check `enabled` and `fee` on the quote for your specific order

## Catalog Endpoints

In addition to `optionals[]` embedded in quote responses, dedicated catalog endpoints return the full optional list with resolver metadata:

| Side | Endpoint                                           |
| ---- | -------------------------------------------------- |
| Buy  | `GET /execution/v2/buy/quotes/:quoteId/optionals`  |
| Sell | `GET /execution/v2/sell/quotes/:quoteId/optionals` |

These endpoints return:

* `optionals[]` — same shape as quote responses
* `partial` — `true` when one or more addon resolvers failed and the catalog is degraded
* `errors[]` — per-addon resolver failures when `partial` is true

Use the catalog endpoint when building a UI that lets users browse add-ons without refreshing the full quote.

## Selecting Optionals

Pass `selectedOptionalIds` as a string array when creating or refreshing a quote:

```bash theme={null}
# Create a buy quote with vault shipping
curl -X POST https://api.collectpure.com/execution/v2/buy/quotes \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{ "listingId": "LISTING_UUID", "quantity": 1 }],
    "paymentMethod": "pm_XXXXX",
    "selectedOptionalIds": ["vault_shipping"]
  }'
```

To refresh with different selections on GET, pass `selectedOptionalIds` as a **repeatable query param**:

```bash theme={null}
curl "https://api.collectpure.com/execution/v2/sell/quotes/QUOTE_ID?selectedOptionalIds=instant_payout&selectedOptionalIds=overnight_label" \
  -H "x-api-key: YOUR_API_KEY"
```

Pass the same `selectedOptionalIds` on execute to confirm your selections.

<Warning>
  v1 sell GET quotes accept comma-separated `selectedOptionalIds`. v2 uses
  repeatable array params — do not comma-join IDs on v2 GET requests.
</Warning>

## Fee Reconciliation (Sell)

Sell execute validates optional fees haven't drifted since the quote. Pass `expectedOptionalFees` — a map of optional ID to fee in cents from the quote:

```json theme={null}
{
  "expectedOptionalFees": {
    "instant_payout": -5000,
    "overnight_label": -2500
  }
}
```

If a fee no longer matches, execute returns **422** with `errorCode: "optional_fee_mismatch"`. Refresh the quote and retry with updated values.

Buy execute does not require `expectedOptionalFees` — optional fees are reconciled through the quote session directly.

## Related Guides

* [Execution - Buy](/api-reference/execution-buy) — buy quote flow with vault shipping
* [Execution - Sell](/api-reference/execution-sell) — sell quote flow with instant payout and overnight label