Requests and responses
The request format, response shapes, paging, status values and the per-minute limits that apply to every endpoint.
Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.
Requests
Section titled “Requests”- Base URL:
https://quote.samita.io/api/public/v1 - Protocol: HTTPS only.
- Authentication: an API key in the
X-SAMITA-API-KEYheader. See Authentication. - Body: send JSON with
Content-Type: application/json, and ask for JSON withAccept: application/json. - IDs in URLs: the quote
id(a number), not the quotenumber.
Responses
Section titled “Responses”Every response is JSON.
- A single record is wrapped in its name, such as
{"quote": { ... }}. - A list comes with a
pageobject. - An error is always
{"errors": [ ... ]}. See Errors.
Formats
Section titled “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
Section titled “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
Section titled “Paging”GET /quotes pages with a cursor:
- Call
GET /quotes?limit=50. The default is 50 and the maximum 100. - Read
page.has_next. Iftrue, call again withcursorset topage.next_cursor. - Stop when
has_nextisfalse.
"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
Section titled “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:
{ "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
Section titled “Keep a sync cheap”- Store the highest
updated_atyou have seen and ask only for newer quotes withupdated_at_min. - Filter by
statusto fetch only what you need. - Read
GET /quotes/{id}only for quotes that changed.