Rate cards
Download the complete public OpenAPI schema
Rate cards
Price every way an order can reach a buyer. A rate card is one buyer-facing fulfillment service, in one currency, served to some markets, with a timing promise and one fee rule — flat, tiered on weight, order value, distance, item count, or fulfillment label, or waived above a free-shipping threshold.
GET /v1/rate_cards
List fulfillment rate cards
List priced fulfillment services by mode, market, status, or search.
Parameters, request, responses, and security
{
"tags": [
"rate-cards"
],
"summary": "List fulfillment rate cards",
"description": "List priced fulfillment services by mode, market, status, or search.",
"operationId": "v1_list_rate_cards",
"parameters": [
{
"required": false,
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/AgenticFulfillmentType"
},
{
"type": "null"
}
],
"title": "Fulfillment Type"
},
"name": "fulfillment_type",
"in": "query"
},
{
"required": false,
"schema": {
"anyOf": [
{
"type": "string",
"maxLength": 64
},
{
"type": "null"
}
],
"title": "Market Id"
},
"name": "market_id",
"in": "query"
},
{
"required": false,
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/FulfillmentRateCardStatus"
},
{
"type": "null"
}
],
"title": "Status"
},
"name": "status",
"in": "query"
},
{
"required": false,
"schema": {
"anyOf": [
{
"type": "string",
"maxLength": 255,
"minLength": 1
},
{
"type": "null"
}
],
"title": "Q"
},
"name": "q",
"in": "query"
},
{
"required": false,
"schema": {
"type": "integer",
"maximum": 200.0,
"minimum": 1.0,
"title": "Limit",
"default": 50
},
"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/PublicV1RateCardListResponse"
}
}
}
},
"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_rate_cards",
"x-mcp-exposed": true,
"x-public-path": "/v1/rate_cards",
"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/rate_cards \\\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_rate_cards\",\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_rate_cards\",\n arguments: {},\n});"
}
]
}
POST /v1/rate_cards
Create a fulfillment rate card
Create one priced fulfillment service with its markets, zones, labels, locations, timing promise, and fee rule.
Parameters, request, responses, and security
{
"tags": [
"rate-cards"
],
"summary": "Create a fulfillment rate card",
"description": "Create one priced fulfillment service with its markets, zones, labels, locations, timing promise, and fee rule.",
"operationId": "v1_create_rate_card",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RateCardCreate"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicV1RateCardRead"
}
}
}
},
"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_create_rate_card",
"x-mcp-exposed": true,
"x-public-path": "/v1/rate_cards",
"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/rate_cards \\\n -H 'Authorization: Bearer pr_sk_test_...' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"name\": \"...\",\n \"fulfillment_type\": \"delivery\",\n \"provider\": \"fedex\",\n \"currency\": \"AED\",\n \"market_ids\": [\n \"...\"\n ],\n \"timing\": {},\n \"rate\": {\n \"kind\": \"free\"\n }\n}'"
},
{
"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_rate_card\",\n \"arguments\": {\n \"name\": \"...\",\n \"fulfillment_type\": \"delivery\",\n \"provider\": \"fedex\",\n \"currency\": \"AED\",\n \"market_ids\": [\n \"...\"\n ],\n \"timing\": {},\n \"rate\": {\n \"kind\": \"free\"\n }\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_rate_card\",\n arguments: {\n \"name\": \"...\",\n \"fulfillment_type\": \"delivery\",\n \"provider\": \"fedex\",\n \"currency\": \"AED\",\n \"market_ids\": [\n \"...\"\n ],\n \"timing\": {},\n \"rate\": {\n \"kind\": \"free\"\n }\n},\n});"
}
]
}
GET /v1/rate_cards/{rate_card_id}
Retrieve a fulfillment rate card
Retrieve one rate card owned by the credential’s merchant.
Parameters, request, responses, and security
{
"tags": [
"rate-cards"
],
"summary": "Retrieve a fulfillment rate card",
"description": "Retrieve one rate card owned by the credential’s merchant.",
"operationId": "v1_get_rate_card",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"title": "Rate Card Id"
},
"name": "rate_card_id",
"in": "path"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicV1RateCardRead"
}
}
}
},
"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_rate_card",
"x-mcp-exposed": true,
"x-public-path": "/v1/rate_cards/{rate_card_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/rate_cards/... \\\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_rate_card\",\n \"arguments\": {\n \"rate_card_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_rate_card\",\n arguments: {\n \"rate_card_id\": \"...\"\n},\n});"
}
]
}
PATCH /v1/rate_cards/{rate_card_id}
Update a fulfillment rate card
Update a rate card; every supplied child list fully replaces the persisted one.
Parameters, request, responses, and security
{
"tags": [
"rate-cards"
],
"summary": "Update a fulfillment rate card",
"description": "Update a rate card; every supplied child list fully replaces the persisted one.",
"operationId": "v1_update_rate_card",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"title": "Rate Card Id"
},
"name": "rate_card_id",
"in": "path"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RateCardPatch"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicV1RateCardRead"
}
}
}
},
"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_update_rate_card",
"x-mcp-exposed": true,
"x-public-path": "/v1/rate_cards/{rate_card_id}",
"x-docs-kind": "other",
"x-docs-order": 100,
"x-docs-depth": 2,
"x-docs-action-order": 1000,
"x-codeSamples": [
{
"lang": "shell",
"label": "curl",
"source": "curl -X PATCH https://api.openmerchant.dev/v1/rate_cards/... \\\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_update_rate_card\",\n \"arguments\": {\n \"rate_card_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_update_rate_card\",\n arguments: {\n \"rate_card_id\": \"...\"\n},\n});"
}
]
}
DELETE /v1/rate_cards/{rate_card_id}
Delete a fulfillment rate card
Delete one rate card. Orders already placed keep the fulfillment charge they captured.
Parameters, request, responses, and security
{
"tags": [
"rate-cards"
],
"summary": "Delete a fulfillment rate card",
"description": "Delete one rate card. Orders already placed keep the fulfillment charge they captured.",
"operationId": "v1_delete_rate_card",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"title": "Rate Card Id"
},
"name": "rate_card_id",
"in": "path"
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"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_delete_rate_card",
"x-mcp-exposed": true,
"x-public-path": "/v1/rate_cards/{rate_card_id}",
"x-docs-kind": "other",
"x-docs-order": 100,
"x-docs-depth": 2,
"x-docs-action-order": 1000,
"x-codeSamples": [
{
"lang": "shell",
"label": "curl",
"source": "curl -X DELETE https://api.openmerchant.dev/v1/rate_cards/... \\\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_delete_rate_card\",\n \"arguments\": {\n \"rate_card_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_delete_rate_card\",\n arguments: {\n \"rate_card_id\": \"...\"\n},\n});"
}
]
}