Get an instant quote

POST /request-instant-quote returns the delivered price of one product for a quantity and a US ZIP code. You get one price per shipping option, cheapest first.

Before you begin

A sku_uuid and the search_session_uuid of the search that returned it. See Find products by photo.
The product has price_on_request: false.

1. Request the quote

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"
}'

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())

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());

Field	Rule
`sku_uuid`	Must be a result of the search you name
`search_session_uuid`	One of this user's searches. Searches do not expire
`quantity_sqft`	A whole number of square feet, 1 to 10,000,000
`destination_zip`	A 5-digit US ZIP code
`Idempotency-Key` header	Required. One per click

Set your HTTP read timeout to 75 seconds. The call holds for up to 60 seconds while Flume prices.

2. Read the answer

{
  "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"
      }
    ]
  }
}

The call returns 200 whether or not it priced. Read status.

`status`	`failure_reason`	Meaning	Do this
`READY`	`null`	`quote` holds the prices	Show the options
`FAILED`	`TEMPORARILY_UNAVAILABLE`	Still pricing, or a temporary problem	Poll. See step 3
`FAILED`	`NOT_QUOTABLE`	No price for this product, quantity and ZIP	Offer a sales request
`FAILED`	`REGION_RESTRICTED`	The product cannot be sold to that state	Ask for another ZIP, or offer sales
`FAILED`	`INCORRECT_DESTINATION`	The ZIP code does not exist	Ask for the ZIP again

quote_uuid is set on every answer.

3. Poll while it is still pricing

Call GET /quotes/{quote_uuid} until status is READY or the reason changes.

curl -X GET "https://sandbox-api.tryflume.ai/partner/v1/quotes/9c1e4b7a-2f3d-4e5b-8a6c-7d8e9f0a1b2c" \
  -H "X-Flume-Partner-Key: $FLUME_PARTNER_KEY" \
  -H "X-Flume-User-Token: $FLUME_USER_TOKEN"

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.get(
    "https://sandbox-api.tryflume.ai/partner/v1/quotes/9c1e4b7a-2f3d-4e5b-8a6c-7d8e9f0a1b2c",
    headers=headers,
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://sandbox-api.tryflume.ai/partner/v1/quotes/9c1e4b7a-2f3d-4e5b-8a6c-7d8e9f0a1b2c", {
  method: "GET",
  headers: {
    "X-Flume-Partner-Key": process.env.FLUME_PARTNER_KEY,
    "X-Flume-User-Token": process.env.FLUME_USER_TOKEN,
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log(await response.json());

Poll every 12 seconds for the first 2 minutes.
Then every 30 seconds until 5 minutes.
Then stop and offer a sales request.
Polling uses no daily limit.
Do not retry POST /request-instant-quote instead. A retry counts against your daily quote limit again.

4. Show the options

Each entry in quote.options is one way to ship.

Field	Meaning
`source`	`US_WAREHOUSE` or `OVERSEAS_DIRECT`
`ships_from_country`	Two-letter country code, or `null`
`lead_time_min_days`, `lead_time_max_days`	Delivery window in days
`quantity_sqft`	The quantity priced
`price_per_sqft`	Delivered price per square foot, before tax
`subtotal`	Delivered price, before tax
`sales_tax`	Sales tax, or `null`
`total`	Including sales tax

Money is a decimal string in USD: "38400.00". Do not parse it as a float.
Show the figures as given. Do not add them up again.
Prices hold until quote.valid_until. That is 30 days after the quote is priced today. Always read the field. Do not compute it.
An option appears only when the quantity reaches its minimum order.

Handle the errors

You get	Do this
`400` `IDEMPOTENCY_KEY_REQUIRED`	Send the `Idempotency-Key` header
`400` `BELOW_MINIMUM_ORDER`	Raise the quantity. The message states the minimum
`400` `NOT_INSTANTLY_QUOTABLE`	Offer a sales request
`404` `SESSION_NOT_FOUND`	Use one of this user's searches
`404` `NOT_FOUND`	Check `sku_uuid`
`409` `IDEMPOTENCY_IN_PROGRESS`	Wait 2 seconds, then retry with the same key
`422` `SKU_NOT_IN_SEARCH`	Use the `search_session_uuid` of the page that returned the product
`429` `RATE_LIMITED`	Wait `Retry-After` seconds
`429` `DAILY_LIMIT_REACHED`	This user's own daily limit is used up (only when Flume set one). Tell the user when it resets: `details.reset_at`. Other users are not affected

Retry safely

A network error: retry with the same Idempotency-Key. You get the original answer.
A new click: use a new key.
See Idempotency.