---
title: "Request an instant quote"
description: "POST /request-instant-quote: Returns the delivered price of one product for a quantity and a US ZIP code."
url: https://docs.tryflume.ai/api/request-instant-quote
updated: 2026-11-11
---

# Request an instant quote

> POST /request-instant-quote: Returns the delivered price of one product for a quantity and a US ZIP code.

Returns the delivered price of one product for a quantity and a US ZIP code.

```http
POST https://sandbox-api.tryflume.ai/partner/v1/request-instant-quote
```

- The response lists one price per shipping option, cheapest first. Freight and sales tax are included.
- `search_session_uuid` must be the search that returned the product.
- The call can take up to 60 seconds. Set your HTTP read timeout to 75 seconds.
- `READY`: `quote` holds the prices, valid until `valid_until`.
- `FAILED`: read `failure_reason`. `TEMPORARILY_UNAVAILABLE` can mean the quote is still pricing. Poll `GET /quotes/{quote_uuid}`.
- A shipping option is priced only when the quantity reaches its `minimum_order_sqft`.
- Daily limit: 200 instant quotes per partner.

## Request

### Headers

| Header | Required | Description |
|---|---|---|
| `X-Flume-Partner-Key` | Yes | Your partner key. |
| `X-Flume-User-Token` | Yes | The access token of the user you call for. |
| `Idempotency-Key` | No | One value per user action, 1 to 255 characters. A UUID works well. A retry with the same value returns the first response. |

### Body (`application/json`)

| Field | Type | Required | Description |
|---|---|---|---|
| `sku_uuid` | string (UUID) | Yes | The product to price. |
| `quantity_sqft` | integer | Yes | The quantity, as a whole number of square feet. 1 to 10,000,000. |
| `destination_zip` | string | Yes | The US delivery ZIP code, as 5 digits. 5 digits. |
| `search_session_uuid` | string (UUID) | Yes | The search that returned this product. Use the id from the page that listed it. Searches do not expire, so a later quote can send the same id. |

### Sample

**curl**

```sh
curl -X POST "https://sandbox-api.tryflume.ai/partner/v1/request-instant-quote" \
  -H "X-Flume-Partner-Key: $FLUME_PARTNER_KEY" \
  -H "X-Flume-User-Token: $FLUME_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "sku_uuid": "7f3c2a91-4b0e-4c8d-9a21-1f6b2d5e7c30",
  "quantity_sqft": 6000,
  "destination_zip": "22102",
  "search_session_uuid": "5f0c1d2e-8a7b-4c3d-9e1f-2a3b4c5d6e7f"
}'
```

**Python**

```python
import os

import requests

headers = {
    "X-Flume-Partner-Key": os.environ["FLUME_PARTNER_KEY"],
    "X-Flume-User-Token": os.environ["FLUME_USER_TOKEN"],
}

response = requests.post(
    "https://sandbox-api.tryflume.ai/partner/v1/request-instant-quote",
    headers=headers,
    json={
        "sku_uuid": "7f3c2a91-4b0e-4c8d-9a21-1f6b2d5e7c30",
        "quantity_sqft": 6000,
        "destination_zip": "22102",
        "search_session_uuid": "5f0c1d2e-8a7b-4c3d-9e1f-2a3b4c5d6e7f",
    },
    timeout=75,
)
response.raise_for_status()
print(response.json())
```

**Node.js**

```js
const response = await fetch("https://sandbox-api.tryflume.ai/partner/v1/request-instant-quote", {
  method: "POST",
  headers: {
    "X-Flume-Partner-Key": process.env.FLUME_PARTNER_KEY,
    "X-Flume-User-Token": process.env.FLUME_USER_TOKEN,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "sku_uuid": "7f3c2a91-4b0e-4c8d-9a21-1f6b2d5e7c30",
    "quantity_sqft": 6000,
    "destination_zip": "22102",
    "search_session_uuid": "5f0c1d2e-8a7b-4c3d-9e1f-2a3b4c5d6e7f"
  }),
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());
```

## Returns (200)

Every field is always present. A field with no value is `null`.

| Field | Type | Description |
|---|---|---|
| `status` | enum | `READY` or `FAILED`. |
| `failure_reason` | enum or null | With `FAILED`: why there are no prices. `TEMPORARILY_UNAVAILABLE` can mean the quote is still pricing. One of: `NOT_QUOTABLE`, `TEMPORARILY_UNAVAILABLE`, `REGION_RESTRICTED`, `INCORRECT_DESTINATION`. |
| `quote_uuid` | string (UUID) or null | The id to poll with. Send it to `GET /quotes/{quote_uuid}` while the quote is still pricing. Every response has it. |
| `quote` | object or null | The prices, with `READY`. Otherwise `null`. |
| `quote.quote_uuid` | string (UUID) | The quote's id in the user's Flume account. |
| `quote.quote_number` | string | The quote's number, as the user sees it in Flume. |
| `quote.sku_uuid` | string (UUID) | The product priced. |
| `quote.destination_zip` | string | The delivery ZIP code. |
| `quote.currency` | string | Always `USD`. Default `"USD"`. |
| `quote.created_at` | string | When the quote was priced, in UTC. |
| `quote.valid_until` | string | The prices hold until this time, in UTC. |
| `quote.options` | array of objects | One entry per shipping option, cheapest `total` first. |
| `quote.options[].source` | enum | How this option ships: `US_WAREHOUSE` or `OVERSEAS_DIRECT`. |
| `quote.options[].ships_from_country` | string or null | The 2-letter code of the country the option ships from, or `null`. |
| `quote.options[].lead_time_min_days` | integer | The shortest delivery time, in days. |
| `quote.options[].lead_time_max_days` | integer | The longest delivery time, in days. |
| `quote.options[].quantity_sqft` | string | The quantity priced, in square feet. |
| `quote.options[].price_per_sqft` | string | The delivered price per square foot, before tax. |
| `quote.options[].subtotal` | string | The delivered price, before tax. |
| `quote.options[].sales_tax` | string or null | The sales tax, or `null`. |
| `quote.options[].total` | string | The delivered price, including sales tax. |

**Response (200)**

```json
{
  "status": "READY",
  "failure_reason": null,
  "quote_uuid": "9c1e4b7a-2f3d-4e5b-8a6c-7d8e9f0a1b2c",
  "quote": {
    "quote_uuid": "9c1e4b7a-2f3d-4e5b-8a6c-7d8e9f0a1b2c",
    "quote_number": "Q-7KD2-M4PA",
    "sku_uuid": "7f3c2a91-4b0e-4c8d-9a21-1f6b2d5e7c30",
    "destination_zip": "22102",
    "currency": "USD",
    "created_at": "2026-10-16T09:14:22Z",
    "valid_until": "2026-10-23T09:14:22Z",
    "options": [
      {
        "source": "OVERSEAS_DIRECT",
        "lead_time_min_days": 90,
        "lead_time_max_days": 120,
        "ships_from_country": "ES",
        "quantity_sqft": "6000.00",
        "price_per_sqft": "6.40",
        "subtotal": "38400.00",
        "sales_tax": "3168.00",
        "total": "41568.00"
      },
      {
        "source": "US_WAREHOUSE",
        "lead_time_min_days": 14,
        "lead_time_max_days": 30,
        "ships_from_country": "US",
        "quantity_sqft": "6000.00",
        "price_per_sqft": "8.10",
        "subtotal": "48600.00",
        "sales_tax": "4009.50",
        "total": "52609.50"
      }
    ]
  }
}
```

## Errors

| Status | Code | Meaning |
|---|---|---|
| 400 | `BELOW_MINIMUM_ORDER` | The quantity is under the product's minimum order. The message states the minimum. |
| 400 | `IDEMPOTENCY_KEY_REQUIRED` | The `Idempotency-Key` header is missing. |
| 400 | `NOT_INSTANTLY_QUOTABLE` | Flume's sales team prices this product. There is no instant quote. |
| 401 | `EMBED_TOKEN_INVALID` | You sent an `Authorization` header and no `X-Flume-Partner-Key`. Flume read the call as one from its own iframe. |
| 401 | `PARTNER_KEY_INVALID` | The partner key is missing, unknown, revoked, expired, or from the other environment. On live, also a platform Flume has not enabled yet. |
| 401 | `USER_TOKEN_INVALID` | The user access token is unknown, revoked, another partner's, or replaced by a later verification. A verification in the iframe replaces it too. |
| 403 | `USER_ACCOUNT_CLOSED` | The user's email belongs to a Flume account that Flume has closed. |
| 403 | `USER_NOT_CONNECTED` | No `X-Flume-User-Token` header was sent. |
| 404 | `NOT_FOUND` | The thing does not exist, or is not this user's. A search id that is not a UUID also returns this code. |
| 404 | `SESSION_NOT_FOUND` | The search does not exist, or is another user's. |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | The first call with this key is still running. |
| 422 | `IDEMPOTENCY_KEY_REUSED` | The key was already used with a different body. |
| 422 | `SKU_NOT_IN_SEARCH` | The product was not a result of the search you named. |
| 422 | `VALIDATION_FAILED` | A field is missing, unknown or has an unusable value. `field` names it as a dotted path. Some refusals carry the detail in `details` and leave `field` empty. |
| 429 | `DAILY_LIMIT_REACHED` | This user's own daily limit of searches or instant quotes is used up. Flume sets this limit per partner account, and it is off by default. `details` holds `kind`, `limit`, `reset_at` and `retry_after_s`. |
| 429 | `RATE_LIMITED` | Today's limit for this call is used up. `Retry-After` is the number of seconds until 00:00 UTC. |
| 500 | `INTERNAL` | Something failed on Flume's side. |

Every code, with its fix: [API error codes](https://docs.tryflume.ai/api/errors.md).

Guide: [Get an instant quote](https://docs.tryflume.ai/guides/get-an-instant-quote.md).