Skip to main content
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: 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: 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:
To refresh with different selections on GET, pass selectedOptionalIds as a repeatable query param:
Pass the same selectedOptionalIds on execute to confirm your selections.
v1 sell GET quotes accept comma-separated selectedOptionalIds. v2 uses repeatable array params — do not comma-join IDs on v2 GET requests.

​
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:
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.