> ## 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.

# Execution - Buy

> Programmatically buy precious metals through the Pure marketplace

The Buy Execution API lets you programmatically purchase precious metals on the Pure marketplace. It follows a **quote-then-execute** pattern: you request a quote to preview pricing, then execute it to finalize the order.

## How It Works

<Steps>
  <Step title="Get a Quote">
    Send your desired items and **payment method** to the quote endpoint. You'll
    receive a `quoteId` along with a full pricing breakdown — line items, fees,
    and total. The payment method is needed so the quote includes accurate
    payment-method-specific fees. Quotes expire in **30 seconds**.
  </Step>

  <Step title="Review Pricing">
    Inspect the quote response to confirm line items, fees, and total. If
    needed, call the GET endpoint with your `quoteId` to refresh pricing at
    current spot rates — this also resets the 30-second expiration window.
  </Step>

  <Step title="Execute the Buy">
    Send your `quoteId`, the `total` from the quote as `expectedTotal`, your
    payment method, and shipping address to the execute endpoint. Pure verifies
    the current total does not exceed your `expectedTotal` — if the price has
    increased, the request is rejected with a `409` so you are never charged
    more than you agreed to.
  </Step>
</Steps>

```mermaid theme={null}
sequenceDiagram
    participant You
    participant Pure API

    You->>Pure API: POST /execution/buy/quote/v1 (items + paymentMethod)
    Pure API-->>You: quoteId + pricing (expires in 30s)

    Note over You: Review pricing

    You->>Pure API: POST /execution/buy/v1 (quoteId + expectedTotal + shipping)
    Pure API->>Pure API: Verify total ≤ expectedTotal
    Pure API-->>You: orderId + sellOrderIds (or 409 if price increased)
```

## 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
* **Total** in cents — pass this as `expectedTotal` when executing
* **Expiration timestamp** — quotes expire in 30 seconds

When creating a quote, you must provide a `paymentMethod`. This ensures the quoted total matches what you'll be charged at execution time.

If you need different items, create a new quote. If you need refreshed pricing on the same items, call `GET /execution/buy/quote/v1` with your `quoteId` — this returns a fresh pricing snapshot and a new 30-second window.

<Info>
  Quotes can contain **multiple items** (up to 50 per quote). Each item is a
  listing ID and quantity pair.
</Info>

## Price Protection

When executing a buy, you must pass `expectedTotal` — the `total` value from the quote response. Pure will reject the order with a **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.

## Payment Methods

Before executing a buy, you'll need a valid Stripe payment method. Use the **List Payment Methods** endpoint to retrieve your organization's payment methods. Each method includes:

* `id` — the Stripe payment method ID to pass when executing
* `paymentMethod` — the payment method type (`stripe_ach`, `stripe`, or `wire_transfer`) to pass when executing
* `isDefault` — whether this is your organization's default

## Error Handling

| Status | Meaning                                                         | What to Do                                                  |
| ------ | --------------------------------------------------------------- | ----------------------------------------------------------- |
| `404`  | Quote not found or expired                                      | Create a new quote                                          |
| `409`  | Price increased beyond `expectedTotal`                          | Create a new quote to get updated pricing, then retry       |
| `410`  | Quote has expired                                               | Create a new quote                                          |
| `422`  | Validation failed (listing unavailable, insufficient inventory) | Check the error message and adjust your request             |
| `500`  | Processing failed                                               | Retry with a new quote. If `unrecoverable`, contact support |

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.

<Tip>
  Use the [Sandbox Environment](/api-reference/execution-sandbox) to test the
  full buy flow without using real money.
</Tip>