Skip to main content
The Buy Execution API lets you programmatically purchase precious metals on the Pure marketplace. It follows a quote-then-execute pattern using resource-style v2 routes: create a quote, optionally inspect or select checkout optionals, then execute.
Quote and execute endpoints require an Admin API key (stytch_admin). Payment methods use Member access (stytch_member). See Authentication for the full role split.

​
How It Works

1

Get a Quote

POST /execution/v2/buy/quotes with your items and payment method. You receive a quoteId, pricing breakdown, and optionals[]. Quotes expire in 60 seconds.
2

Review Optionals (Optional)

Inspect optionals[] on the quote response, or call GET /execution/v2/buy/quotes/:quoteId/optionals for the full catalog. Pass selectedOptionalIds when creating or refreshing a quote to select add-ons like vault shipping.
3

Preview a Promotion (Optional)

POST /execution/v2/buy/quotes/:quoteId/promotion-preview to see how a promotion code affects pricing. Promotions are applied at execute time, not at quote creation.
4

Execute the Buy

POST /execution/v2/buy/quotes/:quoteId/execute with expectedTotal from the quote, your payment method, shipping (unless using vault shipping), and any selected optionals. Pure verifies the current total does not exceed expectedTotal.

​
Endpoints

All v2 buy routes require stytch_admin. Payment methods require stytch_member.

​
Quotes

Quotes are pricing snapshots that include accurate fees based on the payment method you provide. Each quote includes:
  • Line items with per-item pricing and availability status
  • Fees (processing, shipping, etc.) — calculated for your chosen payment method
  • Optionals — add-on services such as vault shipping (see Optionals)
  • Total in cents — pass this as expectedTotal when executing
  • Expiration timestamp — quotes expire in 60 seconds
When creating a quote, provide paymentMethod as 'wire_transfer' or a Stripe payment method ID (pm_... or ba_...). This ensures the quoted total matches what you’ll be charged at execution time. To refresh pricing on the same items, call GET /execution/v2/buy/quotes/:quoteId. Pass optional query params paymentMethod and selectedOptionalIds (repeatable array param, e.g. ?selectedOptionalIds=vault_shipping).
Quotes can contain multiple items (up to 50 per quote). Each item is a listing ID and quantity pair. Listing IDs must be unique within a quote.

​
Payment Methods

Before executing a buy, retrieve your organization’s Stripe payment methods:
Each method includes an id — pass this Stripe payment method ID as paymentMethod when creating quotes and executing. You can also use 'wire_transfer' directly. The response also includes defaultPaymentMethodId and card or bank account details per method.
Pass the Stripe id (pm_... or ba_...) as paymentMethod — not the legacy paymentMethod type label (stripe, stripe_ach) returned alongside it in the list response.
If the organization has not completed Stripe onboarding, this endpoint returns 422 with "Organization does not have a Stripe customer configured". Payment methods are also gated by the execution organization allowlist — see Access and Roles.

​
Optionals and Vault Shipping

Buy quotes include an optionals[] array. The built-in buy optional is vault shipping (vault_shipping), which ships items to your Pure vault and waives standard shipping fees when eligible. Select optionals by passing selectedOptionalIds when creating or refreshing a quote. See the Optionals guide for eligibility rules, response fields, and the dedicated catalog endpoint. When vault shipping is selected, shipping is optional on execute — fulfillment goes to your vault instead of a street address.

​
Promotions

Promotion codes are not accepted when creating a quote. To preview a promotion:
Pass promotionCode on execute to apply the promotion at checkout.

​
Price Protection

When executing, pass expectedTotal — the total value from the quote response. Pure rejects the order with 409 Conflict if the current total exceeds your expectedTotal. This guarantees you are never charged more than the price you agreed to. If you receive a 409, create a new quote to get updated pricing and retry.

​
Sweep

Pass sweep: true on execute to sweep any remaining balance after a partial fill. Useful when a multi-item quote partially completes and you want to capture the rest in a follow-up charge.

​
Access and Roles

All execution routes (v1 and v2) are gated by an organization allowlist. If your organization is not allowlisted, every execution request returns 403 Forbidden regardless of API key permissions. Contact support to request access.

​
Trading Halts

If trading is halted, execute may return 409 with errorCode: "system_check_failed". Poll GET /execution/v2/trading-status to check buy/sell availability before submitting orders.

​
Error Handling

Error responses include error, code (HTTP status), suggestion, and optionally a machine-readable errorCode string. Partial completions are possible — if some items in a multi-item quote succeed but others fail, you’ll receive a "partial" status with the order IDs for the items that were processed. The execute response includes counterpartyOrderIds — the sell-side order IDs created as counterparties to your buy.
Use the Sandbox Environment to test the full buy flow without using real money.

​
Legacy v1 (Deprecated)

v1 buy endpoints remain available but are deprecated. Migrate to the v2 routes below. v2 adds optionals catalog, promotion preview, counterpartyOrderIds on execute, sweep, and improved error codes. v1 does not support selectedOptionalIds on create or promotion preview.