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

> Programmatically sell precious metals through the Pure marketplace

The Sell Execution API lets you programmatically sell precious metals on the Pure marketplace. It follows the same **quote-then-execute** pattern as buying: you request a quote to preview pricing, then execute it to finalize the order. Instead of purchasing listings, you sell into existing buy offers on the marketplace.

## How It Works

<Steps>
  <Step title="Check Payout Methods">
    Call the payout methods endpoint to see your organization's payout
    configuration and instant payout credit availability.
  </Step>

  <Step title="Get a Sell Quote">
    Send your items (offer IDs or product+variant pairs) to the sell quote
    endpoint. You'll receive a `quoteId`, pricing breakdown, and available
    **optionals** (e.g. instant payout). Quotes expire in **60 seconds**.
  </Step>

  <Step title="Select Optionals (Optional)">
    If you want add-on services like instant payout, call the GET quote endpoint
    with `selectedOptionalIds` to see updated pricing with the optional fees
    included.
  </Step>

  <Step title="Execute the Sell">
    Send your `quoteId`, the `total` from the quote as `expectedTotal`, and any
    selected optional IDs. Pure verifies the current total is not less than your
    `expectedTotal` — if the payout has decreased, the request is rejected with
    a `409`.
  </Step>
</Steps>

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

    You->>Pure API: GET /execution/payout-methods/v1
    Pure API-->>You: payoutMethod + instant payout credit info

    You->>Pure API: POST /execution/sell/quote/v1 (items)
    Pure API-->>You: quoteId + pricing + optionals (expires in 60s)

    Note over You: Review pricing and optionals

    You->>Pure API: POST /execution/sell/v1 (quoteId + expectedTotal + optionals)
    Pure API->>Pure API: Verify total ≥ expectedTotal
    Pure API-->>You: orderId + sellOrderIds (or 409 if payout decreased)
```

## Sell Quotes

Sell quotes are **pricing snapshots** that expire in 60 seconds. Each sell quote includes:

* **Line items** with per-item pricing and availability status
* **Offers** matched to each line item (the buy offers you're selling into)
* **Fees** (processing, shipping, etc.)
* **Optionals** — add-on services like instant payout, with eligibility and fee info
* **Total** in cents — pass this as `expectedTotal` when executing

Items in a sell quote can be specified by:

* **Offer ID** — sell directly into a specific buy offer (`offerId` + `quantity`)
* **Product + Variant** — let Pure match the best available offers (`productId` + `variantId` + `quantity`)

To refresh pricing or toggle optionals, call `GET /execution/sell/quote/v1` with your `quoteId` and optional `selectedOptionalIds`.

## Optionals (Instant Payout)

Sell quotes include an `optionals` array showing available add-on services. Each optional has:

| 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 if selected                               |
| `selected`       | Whether currently selected                             |
| `enabled`        | Whether the seller is eligible                         |
| `disabledReason` | Why this optional is unavailable (if not eligible)     |
| `disclaimer`     | Object with `label` and `url` for the optional's terms |

To select an optional:

1. Include its `id` in `selectedOptionalIds` when creating or refreshing a quote
2. The response will show the optional as `selected: true` and the `total` will reflect the fee
3. Pass the same `selectedOptionalIds` when executing the sell order

<Info>
  Check your instant payout eligibility and available credit using `GET
      /execution/payout-methods/v1` before selecting the instant payout optional.
</Info>

## Payout Methods

Before selling, check your payout configuration:

```bash theme={null}
curl -X GET https://api.collectpure.com/execution/payout-methods/v1 \
  -H "x-api-key: YOUR_API_KEY"
```

The response includes:

* `payoutMethod` — your configured payout method (`electronic_check`, `teller_ach`, or `wire_transfer`)
* `electronicCheckName` / `electronicCheckEmail` — payee details for e-check payouts
* `instantPayout` — your credit limit, outstanding balance, and available credit for instant payouts

## Listing Adjustments

When selling items that you also have listed on the marketplace, you can pass:

* `adjustListings: true` — automatically decrements your active listings for the same products
* `confirmListingMismatch: true` — skips the error when your sell quantity is less than listed quantity

## Price Protection

When executing a sell, you must pass `expectedTotal` — the `total` value from the quote. Pure will reject the order with a **409 Conflict** if the current total is **less than** your `expectedTotal`. This guarantees your payout is never less than what you agreed to.

## Error Handling

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

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