Markets
Download the complete public OpenAPI schema
Markets
Define the per-market pricing and locale vocabulary a hosted merchant sells into. Each market binds a currency and its supported locales, and carries the geographic rules that route a buyer to it.
GET /v1/markets
List merchant markets
List binding prices, locales, status, and routing scopes by market.
Parameters, request, responses, and security
{
"tags": [
"markets"
],
"summary": "List merchant markets",
"description": "List binding prices, locales, status, and routing scopes by market.",
"operationId": "v1_list_markets",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicV1MarketListResponse"
}
}
}
}
},
"security": [
{
"ApiKeyBearer": []
}
],
"x-api-audience": "public_v1",
"x-api-authentication": "required",
"x-operation-id": "v1_list_markets",
"x-mcp-exposed": true,
"x-public-path": "/v1/markets",
"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/markets \\\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_markets\",\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_markets\",\n arguments: {},\n});"
}
]
}
POST /v1/markets
Create a merchant market
Create one currency market with supported locales and routing rules.
Parameters, request, responses, and security
{
"tags": [
"markets"
],
"summary": "Create a merchant market",
"description": "Create one currency market with supported locales and routing rules.",
"operationId": "v1_create_market",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MarketCreate"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicV1MarketRead"
}
}
}
},
"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_market",
"x-mcp-exposed": true,
"x-public-path": "/v1/markets",
"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/markets \\\n -H 'Authorization: Bearer pr_sk_test_...' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"code\": \"...\",\n \"currency\": \"AED\",\n \"default_locale\": \"ar-AE\",\n \"locales\": [\n \"ar-AE\"\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_market\",\n \"arguments\": {\n \"code\": \"...\",\n \"currency\": \"AED\",\n \"default_locale\": \"ar-AE\",\n \"locales\": [\n \"ar-AE\"\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_market\",\n arguments: {\n \"code\": \"...\",\n \"currency\": \"AED\",\n \"default_locale\": \"ar-AE\",\n \"locales\": [\n \"ar-AE\"\n ]\n},\n});"
}
]
}
GET /v1/markets/{code}
Retrieve a merchant market
Retrieve one merchant market by immutable merchant-scoped code.
Parameters, request, responses, and security
{
"tags": [
"markets"
],
"summary": "Retrieve a merchant market",
"description": "Retrieve one merchant market by immutable merchant-scoped code.",
"operationId": "v1_get_market",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"title": "Code"
},
"name": "code",
"in": "path"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicV1MarketRead"
}
}
}
},
"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_market",
"x-mcp-exposed": true,
"x-public-path": "/v1/markets/{code}",
"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/markets/... \\\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_market\",\n \"arguments\": {\n \"code\": \"...\"\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_market\",\n arguments: {\n \"code\": \"...\"\n},\n});"
}
]
}
POST /v1/markets/{code}
Update a merchant market
Update market currency, status, locales, or routing rules.
Parameters, request, responses, and security
{
"tags": [
"markets"
],
"summary": "Update a merchant market",
"description": "Update market currency, status, locales, or routing rules.",
"operationId": "v1_update_market",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"title": "Code"
},
"name": "code",
"in": "path"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MarketPatch"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicV1MarketRead"
}
}
}
},
"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_market",
"x-mcp-exposed": true,
"x-public-path": "/v1/markets/{code}",
"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/markets/... \\\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_market\",\n \"arguments\": {\n \"code\": \"...\"\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_market\",\n arguments: {\n \"code\": \"...\"\n},\n});"
}
]
}
DELETE /v1/markets/{code}
Delete a merchant market
Delete an unpriced market that is not the merchant default.
Parameters, request, responses, and security
{
"tags": [
"markets"
],
"summary": "Delete a merchant market",
"description": "Delete an unpriced market that is not the merchant default.",
"operationId": "v1_delete_market",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"title": "Code"
},
"name": "code",
"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_market",
"x-mcp-exposed": true,
"x-public-path": "/v1/markets/{code}",
"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/markets/... \\\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_market\",\n \"arguments\": {\n \"code\": \"...\"\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_market\",\n arguments: {\n \"code\": \"...\"\n},\n});"
}
]
}
POST /v1/markets/{code}/make_default
Make a merchant market default
Make one active market the fallback for buyer catalog requests.
Parameters, request, responses, and security
{
"tags": [
"markets"
],
"summary": "Make a merchant market default",
"description": "Make one active market the fallback for buyer catalog requests.",
"operationId": "v1_make_default_market",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"title": "Code"
},
"name": "code",
"in": "path"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicV1MarketRead"
}
}
}
},
"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_make_default_market",
"x-mcp-exposed": false,
"x-public-path": "/v1/markets/{code}/make_default",
"x-docs-kind": "other",
"x-docs-order": 100,
"x-docs-depth": 2,
"x-docs-action-order": 1000
}