# Quotes

> List, read, create, update and delete quotes with the Public API, with request and response examples.

App: SA Request a Quote, Hide Price (Shopify app by Samita)
Source: https://docs.samita.io/sa-request-a-quote/public-api/quotes
Last updated: 2026-11-18

All paths are relative to `https://quote.samita.io/api/public/v1`. Every call sends your key in `X-SAMITA-API-KEY`. See [Authentication](https://docs.samita.io/sa-request-a-quote/public-api/authentication).

## List quotes

`GET /quotes` — permission `quotes:read`.

| Parameter | Meaning |
| --- | --- |
| limit | Quotes per page, 1 to 100. Default 50. |
| cursor | The next_cursor from the previous page. |
| status | Only quotes in these statuses. A comma-separated list such as unread,read . See Statuses . |
| updated_at_min | Only quotes changed at or after this time, such as 2026-11-01T00:00:00Z . Use it for incremental syncs. |

```bash
curl "https://quote.samita.io/api/public/v1/quotes?status=unread&limit=50" \
  -H "X-SAMITA-API-KEY: sqt_your_key_here"
```

```json
{
  "quotes": [
    {
      "id": 29238181,
      "number": 1002,
      "status": "unread",
      "customer": { "email": "lan@example.com", "name": "Lan Le" },
      "item_count": 2,
      "subtotal": "98.00",
      "currency": "USD",
      "created_at": "2026-11-18T07:21:10Z",
      "updated_at": "2026-11-18T07:21:10Z"
    }
  ],
  "page": { "has_next": true, "next_cursor": "29238181" }
}
```

A list entry is a summary. Fetch the quote to see everything. A `status` that does not exist returns `422 validation_failed` naming the valid ones.

## Read one quote

`GET /quotes/{id}` — permission `quotes:read`.

```bash
curl https://quote.samita.io/api/public/v1/quotes/29238181 \
  -H "X-SAMITA-API-KEY: sqt_your_key_here"
```

```json
{
  "quote": {
    "id": 29238181,
    "number": 1002,
    "status": "unread",
    "created_at": "2026-11-18T07:21:10Z",
    "updated_at": "2026-11-18T07:21:10Z",
    "currency": "USD",
    "customer": {
      "shopify_customer_id": null,
      "email": "lan@example.com",
      "name": "Lan Le",
      "first_name": "Lan",
      "last_name": "Le",
      "phone": "+84901234567",
      "company": "ABC Co.",
      "is_b2b": false,
      "address": null
    },
    "fields": [
      { "key": "contact_info[first_name]", "label": "First name", "value": "Lan" },
      { "key": "message", "label": "Message", "value": "Need 500 units" }
    ],
    "attachments": [
      { "field": "file", "name": "drawing.pdf", "url": "https://..." }
    ],
    "items": [
      {
        "id": 9012,
        "product_id": "8123456789012",
        "variant_id": "40512345678901",
        "title": "Trade box",
        "sku": "TB-100",
        "vendor": "Acme",
        "quantity": 500,
        "price": "49.00",
        "wished_price": null,
        "options": [ { "name": "Engraving", "value": "ACME" } ],
        "note": null,
        "image_url": "https://cdn.shopify.com/...",
        "url": "https://your-store.com/products/trade-box?variant=40512345678901"
      }
    ],
    "subtotal": "24500.00",
    "notes": [ { "body": "Called the customer", "created_at": "2026-11-18T09:02:00Z" } ],
    "tags": [],
    "draft_order_id": null
  }
}
```

| Field | Meaning |
| --- | --- |
| id , number | The id for URLs, and the quote number your team and customers see. |
| customer | Who asked. shopify_customer_id is set when the customer has an account. |
| fields | The customer's answers: the form field's key , its label and the value . |
| attachments | Files the customer uploaded, with a download url . |
| items | The line items. price is what the store charges, wished_price the price the customer proposed, if any. |
| subtotal | The sum of priced line items, or null if none has a price. |
| notes | The quote's internal notes. |
| draft_order_id | The Shopify draft order, if you converted the quote. |

A quote that does not exist, or belongs to another store, returns `404 not_found`.

## Create a quote

`POST /quotes` — permission `quotes:create`. It goes through the same path as a storefront submission: the quote gets the next number, appears in **Quote list**, and counts towards your plan's monthly quote limit.

```bash
curl https://quote.samita.io/api/public/v1/quotes \
  -H "X-SAMITA-API-KEY: sqt_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-lead-88231" \
  -d '{
    "customer": {
      "email": "lan@example.com",
      "first_name": "Lan",
      "last_name": "Le",
      "phone": "+84901234567",
      "company": "ABC Co."
    },
    "fields": {
      "contact_info[first_name]": "Lan",
      "contact_info[last_name]": "Le",
      "contact_info[email]": "lan@example.com",
      "contact_info[phone]": "+84901234567",
      "company_info[name]": "ABC Co."
    },
    "items": [
      {
        "variant_id": 40512345678901,
        "quantity": 500,
        "properties": [ { "name": "Engraving", "value": "ACME" } ]
      }
    ],
    "note": "Imported from CRM",
    "locale": "en",
    "options": { "send_notifications": false, "run_integrations": true }
  }'
```

| Field | Rules |
| --- | --- |
| customer.email | Required. A valid email address. |
| customer.first_name , last_name , phone , company | Optional. |
| customer.shopify_customer_id | Optional. Digits only. Links the quote to an existing Shopify customer. |
| items | Required. 1 to 50 items. |
| items[].variant_id | Required. The Shopify variant id, as a number or a gid://shopify/ProductVariant/... id. It must exist in this store. |
| items[].quantity | Required. A whole number from 1 upward. |
| items[].properties | Optional. Up to 20 name / value pairs, such as an engraving. |
| items[].note | Optional note on that line. |
| fields | An object of the customer's answers. Each key must be a field key from GET /form — including keys such as contact_info[email] — and every field the form marks required must be present , even if you also send customer . File fields can't be set through the API. All fields together may not exceed 60 KB. |
| note | Optional internal note, up to 5,000 characters. |
| tags | Optional. Up to 20 tags. |
| locale | Optional language for the emails, such as en . |
| options.send_notifications | Send the usual quote emails. Default: no. |
| options.run_integrations | Run your integrations (such as Zapier) for this quote. Default: no. |

**Prices come from Shopify.** You send only the variant and the quantity. The app loads each product's title, SKU, price and image from your store, so a client can never set a price.

**Notifications are off by default**, so importing old leads doesn't email your customers by accident. Turn on `send_notifications` when you want the normal emails.

If a required field is missing, the call fails with `422 validation_failed` and `field` names it, for example `fields.contact_info[first_name]`. Call [GET /form](https://docs.samita.io/sa-request-a-quote/public-api/quote-form) first so you know which fields your store requires.

A successful call returns **201** and the new quote, in the same shape as reading one quote. A **Created via Public API** note, with the key's name, is added to it.

### Safe retries with Idempotency-Key

Send an `Idempotency-Key` header with a value unique to the thing you are creating, such as your CRM's lead id. If the same key arrives again within 24 hours — a timeout, a retry — the API returns the quote it already made instead of creating a second one. The repeat returns **200**, not 201.

If a retry arrives while the first request is still running, you get `409 idempotency_conflict`. Wait a moment and send it again.

## Update a quote

`PATCH /quotes/{id}` — permission `quotes:update`. Send `status`, `note`, or both.

```bash
curl -X PATCH https://quote.samita.io/api/public/v1/quotes/29238181 \
  -H "X-SAMITA-API-KEY: sqt_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "status": "purchased", "note": "PO 7781 received" }'
```

* `status` can be `unread`, `read`, `purchased`, `fulfilled` or `rejected`. Other statuses are set by the app.
* `note` adds an internal note to the quote (1 to 5,000 characters). It does not replace earlier notes.
* A status change is recorded in the quote's timeline as **API: {key name}**, so your team can see where it came from.
* Sending neither returns `422 validation_failed`.

The response is the updated quote.

## Delete a quote

`DELETE /quotes/{id}` — permission `quotes:delete`.

```bash
curl -X DELETE https://quote.samita.io/api/public/v1/quotes/29238181 \
  -H "X-SAMITA-API-KEY: sqt_your_key_here"
```

```json
{ "id": 29238181, "deleted": true }
```

> **Warning**
>
> Deleting is permanent. The quote and its line items cannot be restored.

## Delete several quotes

`POST /quotes/bulk_delete` — permission `quotes:delete`. Send 1 to 50 quote ids.

```bash
curl https://quote.samita.io/api/public/v1/quotes/bulk_delete \
  -H "X-SAMITA-API-KEY: sqt_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "ids": [29238181, 29238182, 9999] }'
```

```json
{ "deleted": [29238181, 29238182], "not_found": [9999] }
```

Ids that do not exist in your store come back under `not_found` rather than failing the whole call.

Deletes are limited to **200 quotes per minute** across both endpoints. Over that, you get `429 rate_limited` and a `Retry-After` header.

## Next steps

* [Quote form](https://docs.samita.io/sa-request-a-quote/public-api/quote-form) — the field keys for `fields`
* [Errors](https://docs.samita.io/sa-request-a-quote/public-api/errors) — what each error means
* [View and edit a quote](https://docs.samita.io/sa-request-a-quote/managing-quotes/view-and-edit) — the same quotes in the app
