Quotes
Download the complete public OpenAPI schema
Quotes
Create, list, retrieve, and refresh buyer-owned authoritative quotes. Completed merchant pricing and availability return inline; poll only after an indeterminate responder timeout.
GET /v1/quotes
List buyer quotes
List only quotes requested by this immutable account and mode.
Parameters, request, responses, and security
{
"tags": [
"quotes"
],
"summary": "List buyer quotes",
"description": "List only quotes requested by this immutable account and mode.",
"operationId": "v1_list_quotes",
"parameters": [
{
"required": false,
"schema": {
"type": "integer",
"maximum": 200.0,
"minimum": 1.0,
"title": "Limit",
"default": 20
},
"name": "limit",
"in": "query"
},
{
"required": false,
"schema": {
"type": "integer",
"minimum": 0.0,
"title": "Offset",
"default": 0
},
"name": "offset",
"in": "query"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicV1QuoteListResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"security": [
{
"ApiKeyBearer": []
}
],
"x-api-audience": "public_v1",
"x-api-authentication": "required",
"x-operation-id": "v1_list_quotes",
"x-mcp-exposed": true,
"x-public-path": "/v1/quotes",
"x-docs-kind": "list",
"x-docs-order": 40,
"x-docs-depth": 0,
"x-docs-action-order": 1000,
"x-codeSamples": [
{
"lang": "shell",
"label": "curl",
"source": "curl -X GET https://api.openmerchant.dev/v1/quotes \\\n -H 'Authorization: Bearer pr_sk_test_...'"
},
{
"lang": "shell",
"label": "MCP (Streamable HTTP)",
"source": "curl -X POST https://api.openmerchant.dev/mcp/v1 \\\n -H 'Authorization: Bearer pr_sk_test_...' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"v1_list_quotes\",\n \"arguments\": {}\n }\n}'"
},
{
"lang": "typescript",
"label": "MCP SDK (TS)",
"source": "// Reusing a Client connected to /mcp/v1 — see the \"MCP server\" tag for setup.\nconst result = await client.callTool({\n name: \"v1_list_quotes\",\n arguments: {},\n});"
}
]
}
POST /v1/quotes
Create quote
Resolve exactly one merchant from catalog_item_id, catalog_variant_id, or merchant_slug; persist the buyer-owned quote; send one signed quote.requested event to that merchant's designated responder; and wait up to ten seconds for offers. A 202 response remains pollable at Location.
Parameters, request, responses, and security
{
"tags": [
"quotes"
],
"summary": "Create quote",
"description": "Resolve exactly one merchant from catalog_item_id, catalog_variant_id, or merchant_slug; persist the buyer-owned quote; send one signed quote.requested event to that merchant's designated responder; and wait up to ten seconds for offers. A 202 response remains pollable at Location.",
"operationId": "v1_create_quote",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"title": "Idempotency-Key"
},
"name": "Idempotency-Key",
"in": "header"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicV1QuoteCreateRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "The authoritative quote resolution completed inline.",
"headers": {
"Cache-Control": {
"description": "Buyer quote responses are never shared-cacheable.",
"schema": {
"type": "string",
"example": "private, no-store"
}
},
"Location": {
"description": "Canonical URL for retrieving the persisted quote.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicV1QuoteRead"
}
}
}
},
"202": {
"description": "The quote is persisted, but the responder deadline elapsed; poll the Location resource.",
"headers": {
"Cache-Control": {
"description": "Buyer quote responses are never shared-cacheable.",
"schema": {
"type": "string",
"example": "private, no-store"
}
},
"Location": {
"description": "Canonical URL for retrieving the persisted quote.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Suggested polling delay in seconds after an indeterminate timeout.",
"schema": {
"type": "integer",
"example": 2
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicV1QuoteRead"
}
}
}
},
"409": {
"description": "Merchant/responder setup is incomplete, the idempotency key conflicts, or the quote state cannot be refreshed."
},
"422": {
"description": "The merchant requires typed buyer input before repricing.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicV1QuoteRead"
}
}
}
},
"502": {
"description": "The designated responder returned an invalid or terminal failure."
},
"404": {
"description": "The selected merchant or catalog reference is not public in this mode."
}
},
"security": [
{
"ApiKeyBearer": []
}
],
"x-api-audience": "public_v1",
"x-api-authentication": "required",
"x-operation-id": "v1_create_quote",
"x-mcp-exposed": true,
"x-public-path": "/v1/quotes",
"x-docs-kind": "create",
"x-docs-order": 10,
"x-docs-depth": 0,
"x-docs-action-order": 1000,
"x-codeSamples": [
{
"lang": "shell",
"label": "curl",
"source": "curl -X POST https://api.openmerchant.dev/v1/quotes \\\n -H 'Authorization: Bearer pr_sk_test_...' \\\n -H 'Content-Type: application/json' \\\n -d '\"...\"'"
},
{
"lang": "shell",
"label": "MCP (Streamable HTTP)",
"source": "curl -X POST https://api.openmerchant.dev/mcp/v1 \\\n -H 'Authorization: Bearer pr_sk_test_...' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"v1_create_quote\",\n \"arguments\": {\n \"body\": \"...\"\n }\n }\n}'"
},
{
"lang": "typescript",
"label": "MCP SDK (TS)",
"source": "// Reusing a Client connected to /mcp/v1 — see the \"MCP server\" tag for setup.\nconst result = await client.callTool({\n name: \"v1_create_quote\",\n arguments: {\n \"body\": \"...\"\n},\n});"
}
]
}
GET /v1/quotes/{quote_id}
Get quote
Retrieve a quote only when its persisted requester account and mode match the authenticated secret key.
Parameters, request, responses, and security
{
"tags": [
"quotes"
],
"summary": "Get quote",
"description": "Retrieve a quote only when its persisted requester account and mode match the authenticated secret key.",
"operationId": "v1_get_quote",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"title": "Quote Id"
},
"name": "quote_id",
"in": "path"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicV1QuoteRead"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"security": [
{
"ApiKeyBearer": []
}
],
"x-api-audience": "public_v1",
"x-api-authentication": "required",
"x-operation-id": "v1_get_quote",
"x-mcp-exposed": true,
"x-public-path": "/v1/quotes/{quote_id}",
"x-docs-kind": "retrieve",
"x-docs-order": 30,
"x-docs-depth": 0,
"x-docs-action-order": 1000,
"x-codeSamples": [
{
"lang": "shell",
"label": "curl",
"source": "curl -X GET https://api.openmerchant.dev/v1/quotes/... \\\n -H 'Authorization: Bearer pr_sk_test_...'"
},
{
"lang": "shell",
"label": "MCP (Streamable HTTP)",
"source": "curl -X POST https://api.openmerchant.dev/mcp/v1 \\\n -H 'Authorization: Bearer pr_sk_test_...' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"v1_get_quote\",\n \"arguments\": {\n \"quote_id\": \"...\"\n }\n }\n}'"
},
{
"lang": "typescript",
"label": "MCP SDK (TS)",
"source": "// Reusing a Client connected to /mcp/v1 — see the \"MCP server\" tag for setup.\nconst result = await client.callTool({\n name: \"v1_get_quote\",\n arguments: {\n \"quote_id\": \"...\"\n},\n});"
}
]
}
POST /v1/quotes/{quote_id}
Update quote
Re-run the immutable saved request in a new resolution generation. Requires a new Idempotency-Key. The body is optional: its only field is price_proposal, a new unit price to propose, which counts as one of the quote's limited proposals.
Parameters, request, responses, and security
{
"tags": [
"quotes"
],
"summary": "Update quote",
"description": "Re-run the immutable saved request in a new resolution generation. Requires a new Idempotency-Key. The body is optional: its only field is `price_proposal`, a new unit price to propose, which counts as one of the quote's limited proposals.",
"operationId": "v1_refresh_quote",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"title": "Quote Id"
},
"name": "quote_id",
"in": "path"
},
{
"required": true,
"schema": {
"type": "string",
"title": "Idempotency-Key"
},
"name": "Idempotency-Key",
"in": "header"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QuoteRefreshRequest"
}
}
}
},
"responses": {
"200": {
"description": "The authoritative quote resolution completed inline.",
"headers": {
"Cache-Control": {
"description": "Buyer quote responses are never shared-cacheable.",
"schema": {
"type": "string",
"example": "private, no-store"
}
},
"Location": {
"description": "Canonical URL for retrieving the persisted quote.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicV1QuoteRead"
}
}
}
},
"202": {
"description": "The quote is persisted, but the responder deadline elapsed; poll the Location resource.",
"headers": {
"Cache-Control": {
"description": "Buyer quote responses are never shared-cacheable.",
"schema": {
"type": "string",
"example": "private, no-store"
}
},
"Location": {
"description": "Canonical URL for retrieving the persisted quote.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Suggested polling delay in seconds after an indeterminate timeout.",
"schema": {
"type": "integer",
"example": 2
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicV1QuoteRead"
}
}
}
},
"409": {
"description": "Merchant/responder setup is incomplete, the idempotency key conflicts, or the quote state cannot be refreshed."
},
"422": {
"description": "The merchant requires typed buyer input before repricing.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicV1QuoteRead"
}
}
}
},
"502": {
"description": "The designated responder returned an invalid or terminal failure."
},
"404": {
"description": "The quote is absent or outside the caller ownership scope."
}
},
"security": [
{
"ApiKeyBearer": []
}
],
"x-api-audience": "public_v1",
"x-api-authentication": "required",
"x-operation-id": "v1_refresh_quote",
"x-mcp-exposed": true,
"x-public-path": "/v1/quotes/{quote_id}",
"x-docs-kind": "update",
"x-docs-order": 20,
"x-docs-depth": 0,
"x-docs-action-order": 1000,
"x-codeSamples": [
{
"lang": "shell",
"label": "curl",
"source": "curl -X POST https://api.openmerchant.dev/v1/quotes/... \\\n -H 'Authorization: Bearer pr_sk_test_...'"
},
{
"lang": "shell",
"label": "MCP (Streamable HTTP)",
"source": "curl -X POST https://api.openmerchant.dev/mcp/v1 \\\n -H 'Authorization: Bearer pr_sk_test_...' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"v1_refresh_quote\",\n \"arguments\": {\n \"quote_id\": \"...\"\n }\n }\n}'"
},
{
"lang": "typescript",
"label": "MCP SDK (TS)",
"source": "// Reusing a Client connected to /mcp/v1 — see the \"MCP server\" tag for setup.\nconst result = await client.callTool({\n name: \"v1_refresh_quote\",\n arguments: {\n \"quote_id\": \"...\"\n},\n});"
}
]
}