Policies
Download the complete public OpenAPI schema
Policies
Create and manage reusable spending policies used to evaluate purchases.
You can configure max spending per transaction or per time interval, max number of PurchaseIntents per day, or merchant restrictions based on category (MCC code). It is impossible for purchases to go through when they are outside of the policy limits.
GET /v1/policies
List policies
Return reusable spending policies visible to the authenticated API key.
Parameters, request, responses, and security
{
"tags": [
"policies"
],
"summary": "List policies",
"description": "Return reusable spending policies visible to the authenticated API key.",
"operationId": "v1_list_policies",
"parameters": [
{
"required": false,
"schema": {
"type": "boolean",
"title": "Include Archived",
"default": false
},
"name": "include_archived",
"in": "query"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicPolicyLibraryListResponse"
}
}
}
},
"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_policies",
"x-mcp-exposed": true,
"x-public-path": "/v1/policies",
"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/policies \\\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_policies\",\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_policies\",\n arguments: {},\n});"
}
]
}
POST /v1/policies
Create a policy
Create a reusable spending policy for future purchase-intent evaluation.
Parameters, request, responses, and security
{
"tags": [
"policies"
],
"summary": "Create a policy",
"description": "Create a reusable spending policy for future purchase-intent evaluation.",
"operationId": "v1_create_policy",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PolicyCreate"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicPolicyLibraryRead"
}
}
}
},
"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_policy",
"x-mcp-exposed": true,
"x-public-path": "/v1/policies",
"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/policies \\\n -H 'Authorization: Bearer pr_sk_test_...' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"name\": \"...\"\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_policy\",\n \"arguments\": {\n \"name\": \"...\"\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_policy\",\n arguments: {\n \"name\": \"...\"\n},\n});"
}
]
}
GET /v1/policies/{policy_id}
Retrieve a policy
Return one spending policy by ID when it belongs to the authenticated account.
Parameters, request, responses, and security
{
"tags": [
"policies"
],
"summary": "Retrieve a policy",
"description": "Return one spending policy by ID when it belongs to the authenticated account.",
"operationId": "v1_get_policy",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"title": "Policy Id"
},
"name": "policy_id",
"in": "path"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicPolicyLibraryRead"
}
}
}
},
"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_policy",
"x-mcp-exposed": true,
"x-public-path": "/v1/policies/{policy_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/policies/... \\\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_policy\",\n \"arguments\": {\n \"policy_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_policy\",\n arguments: {\n \"policy_id\": \"...\"\n},\n});"
}
]
}
POST /v1/policies/{policy_id}
Update a policy
Apply a partial update to a spending policy and create a new policy version.
Parameters, request, responses, and security
{
"tags": [
"policies"
],
"summary": "Update a policy",
"description": "Apply a partial update to a spending policy and create a new policy version.",
"operationId": "v1_update_policy",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"title": "Policy Id"
},
"name": "policy_id",
"in": "path"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PolicyPatch"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicPolicyLibraryRead"
}
}
}
},
"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_policy",
"x-mcp-exposed": true,
"x-public-path": "/v1/policies/{policy_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/policies/... \\\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_policy\",\n \"arguments\": {\n \"policy_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_policy\",\n arguments: {\n \"policy_id\": \"...\"\n},\n});"
}
]
}
POST /v1/policies/{policy_id}/archive
Archive a policy
Archive a spending policy without deleting its version history.
Parameters, request, responses, and security
{
"tags": [
"policies"
],
"summary": "Archive a policy",
"description": "Archive a spending policy without deleting its version history.",
"operationId": "v1_archive_policy",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"title": "Policy Id"
},
"name": "policy_id",
"in": "path"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicPolicyLibraryRead"
}
}
}
},
"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_archive_policy",
"x-mcp-exposed": true,
"x-public-path": "/v1/policies/{policy_id}/archive",
"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 POST https://api.openmerchant.dev/v1/policies/.../archive \\\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_archive_policy\",\n \"arguments\": {\n \"policy_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_archive_policy\",\n arguments: {\n \"policy_id\": \"...\"\n},\n});"
}
]
}
POST /v1/policies/{policy_id}/rollback
Roll back a policy
Restore a spending policy to a previous version and record a new current version.
Parameters, request, responses, and security
{
"tags": [
"policies"
],
"summary": "Roll back a policy",
"description": "Restore a spending policy to a previous version and record a new current version.",
"operationId": "v1_rollback_policy",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"title": "Policy Id"
},
"name": "policy_id",
"in": "path"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PolicyRollbackBody"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicPolicyLibraryRead"
}
}
}
},
"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_rollback_policy",
"x-mcp-exposed": true,
"x-public-path": "/v1/policies/{policy_id}/rollback",
"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 POST https://api.openmerchant.dev/v1/policies/.../rollback \\\n -H 'Authorization: Bearer pr_sk_test_...' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"target_version_number\": 1\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_rollback_policy\",\n \"arguments\": {\n \"policy_id\": \"...\",\n \"target_version_number\": 1\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_rollback_policy\",\n arguments: {\n \"policy_id\": \"...\",\n \"target_version_number\": 1\n},\n});"
}
]
}
POST /v1/policies/{policy_id}/unarchive
Unarchive a policy
Restore an archived spending policy so it can be selected again.
Parameters, request, responses, and security
{
"tags": [
"policies"
],
"summary": "Unarchive a policy",
"description": "Restore an archived spending policy so it can be selected again.",
"operationId": "v1_unarchive_policy",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"title": "Policy Id"
},
"name": "policy_id",
"in": "path"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicPolicyLibraryRead"
}
}
}
},
"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_unarchive_policy",
"x-mcp-exposed": true,
"x-public-path": "/v1/policies/{policy_id}/unarchive",
"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 POST https://api.openmerchant.dev/v1/policies/.../unarchive \\\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_unarchive_policy\",\n \"arguments\": {\n \"policy_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_unarchive_policy\",\n arguments: {\n \"policy_id\": \"...\"\n},\n});"
}
]
}
GET /v1/policies/{policy_id}/versions
List policy versions
Return immutable historical versions for a spending policy.
Parameters, request, responses, and security
{
"tags": [
"policies"
],
"summary": "List policy versions",
"description": "Return immutable historical versions for a spending policy.",
"operationId": "v1_list_policy_versions",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"title": "Policy Id"
},
"name": "policy_id",
"in": "path"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PolicyVersionListResponse"
}
}
}
},
"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_policy_versions",
"x-mcp-exposed": true,
"x-public-path": "/v1/policies/{policy_id}/versions",
"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 GET https://api.openmerchant.dev/v1/policies/.../versions \\\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_policy_versions\",\n \"arguments\": {\n \"policy_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_list_policy_versions\",\n arguments: {\n \"policy_id\": \"...\"\n},\n});"
}
]
}