# Requests and responses

> The request format, response shapes, paging, status values and the per-minute limits that apply to every endpoint.

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

## Requests

* **Base URL:** `https://quote.samita.io/api/public/v1`
* **Protocol:** HTTPS only.
* **Authentication:** an API key in the `X-SAMITA-API-KEY` header. See [Authentication](https://docs.samita.io/sa-request-a-quote/public-api/authentication).
* **Body:** send JSON with `Content-Type: application/json`, and ask for JSON with `Accept: application/json`.
* **IDs in URLs:** the quote `id` (a number), not the quote `number`.

## Responses

Every response is JSON.

* A single record is wrapped in its name, such as `{"quote": { ... }}`.
* A list comes with a `page` object.
* An error is always `{"errors": [ ... ]}`. See [Errors](https://docs.samita.io/sa-request-a-quote/public-api/errors).

### Formats

| Value | Format |
| --- | --- |
| Times | ISO 8601 in UTC, such as 2026-11-18T07:21:10Z . |
| Money | A decimal string such as "98.00" , with the quote's currency alongside. A missing price is null . |
| IDs from Shopify | Strings of digits, such as "40512345678901" . |
| Empty values | null , or an empty list. |

### Statuses

A quote's `status` is a word:

| Status | Can you set it? | Meaning |
| --- | --- | --- |
| unread | Yes | New, not opened yet. |
| read | Yes | Opened by your team. |
| purchased | Yes | The customer bought. |
| fulfilled | Yes | The order was fulfilled. |
| rejected | Yes | Declined. |
| converting | No | A draft order is being created. |
| draft_order_created | No | A draft order exists for it. |

The last two are set by the app when you convert a quote to a draft order, so the API only reads them.

## Paging

`GET /quotes` pages with a **cursor**:

1. Call `GET /quotes?limit=50`. The default is 50 and the maximum 100.
2. Read `page.has_next`. If `true`, call again with `cursor` set to `page.next_cursor`.
3. Stop when `has_next` is `false`.

```json
"page": { "has_next": true, "next_cursor": "29238180" }
```

Quotes come newest first. Cursors stay correct when quotes are added while you page. Only quotes that were actually submitted are listed — an unsent quote basket is not.

## Limits

Requests are limited **per minute, per store**, in groups:

| Group | Limit per minute | Endpoints |
| --- | --- | --- |
| Read | 120 | /ping , /form , GET /quotes/{id} |
| List | 60 | GET /quotes |
| Write | 60 | PATCH , DELETE and bulk_delete |
| Create | 20 | POST /quotes |
| Delete volume | 200 quotes | Quotes removed by DELETE and bulk_delete combined |

The limit counts the store's requests across all of its keys, so a second key does not give you more room.

When you go over, the API answers `429 rate_limited` with a `Retry-After` header holding the seconds to wait:

```json
{ "errors": [ { "code": "rate_limited", "message": "Too many requests. Retry after 23 seconds." } ] }
```

Wait that long, then retry. For a large sync, page with `limit=100`, spread the calls out, and back off when you see `429`.

## Keep a sync cheap

* Store the highest `updated_at` you have seen and ask only for newer quotes with `updated_at_min`.
* Filter by `status` to fetch only what you need.
* Read `GET /quotes/{id}` only for quotes that changed.

## Next steps

* [Quotes](https://docs.samita.io/sa-request-a-quote/public-api/quotes) — the endpoints in detail
* [Errors](https://docs.samita.io/sa-request-a-quote/public-api/errors) — every error and what to do
