Quotes
List, read, create, update and delete quotes with the Public API, with request and response examples.
Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.
All paths are relative to https://quote.samita.io/api/public/v1. Every call sends your key in X-SAMITA-API-KEY. See Authentication.
List quotes
Section titled “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. |
curl "https://quote.samita.io/api/public/v1/quotes?status=unread&limit=50" \ -H "X-SAMITA-API-KEY: sqt_your_key_here"{ "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
Section titled “Read one quote”GET /quotes/{id} — permission quotes:read.
curl https://quote.samita.io/api/public/v1/quotes/29238181 \ -H "X-SAMITA-API-KEY: sqt_your_key_here"{ "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
Section titled “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.
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 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
Section titled “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
Section titled “Update a quote”PATCH /quotes/{id} — permission quotes:update. Send status, note, or both.
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" }'statuscan beunread,read,purchased,fulfilledorrejected. Other statuses are set by the app.noteadds 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
Section titled “Delete a quote”DELETE /quotes/{id} — permission quotes:delete.
curl -X DELETE https://quote.samita.io/api/public/v1/quotes/29238181 \ -H "X-SAMITA-API-KEY: sqt_your_key_here"{ "id": 29238181, "deleted": true }Delete several quotes
Section titled “Delete several quotes”POST /quotes/bulk_delete — permission quotes:delete. Send 1 to 50 quote ids.
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] }'{ "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
Section titled “Next steps”- Quote form — the field keys for
fields - Errors — what each error means
- View and edit a quote — the same quotes in the app