PurchaseIntents
Download the complete public OpenAPI schema
PurchaseIntents
Buy one or more items by creating a PurchaseIntent. Items from the same merchant are batched together into carts.
Configure additional preferences, such as preferring pickup vs delivery, or reuse default preferences from the profile.
When human approval is required by policy, call the approve API to confirm the PurchaseIntent and begin execution.
GET /v1/purchase_intents
List purchase intents
Return purchase-intent audit rows for the authenticated API key.
Parameters, request, responses, and security
{
"tags": [
"purchase-intents"
],
"summary": "List purchase intents",
"description": "Return purchase-intent audit rows for the authenticated API key.",
"operationId": "v1_list_purchase_intents",
"parameters": [
{
"required": false,
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/PublicPurchaseIntentStatus"
},
{
"type": "null"
}
],
"title": "Status"
},
"name": "status",
"in": "query"
},
{
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Profile Id"
},
"name": "profile_id",
"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/PublicAuditTrailListResponse"
}
}
}
},
"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_purchase_intents",
"x-mcp-exposed": true,
"x-public-path": "/v1/purchase_intents",
"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/purchase_intents \\\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_purchase_intents\",\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_purchase_intents\",\n arguments: {},\n});"
}
]
}
POST /v1/purchase_intents
Create a purchase intent
Create a Purchase Intent, which represents the intent to buy one or more items. Items from the same merchant are batched together into the same cart to save on fulfillment fees. Configure other preferences, like the maximum amount allowed to be spent on shipping, delivery, or pickup fees.
Parameters, request, responses, and security
{
"tags": [
"purchase-intents"
],
"summary": "Create a purchase intent",
"description": "Create a Purchase Intent, which represents the intent to buy one or more items. Items from the same merchant are batched together into the same cart to save on fulfillment fees. Configure other preferences, like the maximum amount allowed to be spent on shipping, delivery, or pickup fees.",
"operationId": "v1_create_purchase_intent",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicPurchaseIntentCreate"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicPurchaseIntentPollRead"
}
}
}
},
"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_purchase_intent",
"x-mcp-exposed": true,
"x-public-path": "/v1/purchase_intents",
"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/purchase_intents \\\n -H 'Authorization: Bearer pr_sk_test_...' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"items\": [\n {}\n ],\n \"profile_id\": \"...\"\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_purchase_intent\",\n \"arguments\": {\n \"items\": [\n {}\n ],\n \"profile_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_create_purchase_intent\",\n arguments: {\n \"items\": [\n {}\n ],\n \"profile_id\": \"...\"\n},\n});"
}
]
}
GET /v1/purchase_intents/{purchase_intent_id}
Retrieve a purchase intent
Return the public lifecycle state for one purchase intent.
Parameters, request, responses, and security
{
"tags": [
"purchase-intents"
],
"summary": "Retrieve a purchase intent",
"description": "Return the public lifecycle state for one purchase intent.",
"operationId": "v1_get_purchase_intent",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"title": "Purchase Intent Id"
},
"name": "purchase_intent_id",
"in": "path"
},
{
"required": false,
"schema": {
"items": {
"$ref": "#/components/schemas/PublicPurchaseIntentExpand"
},
"type": "array",
"title": "Expand"
},
"name": "expand",
"in": "query"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicPurchaseIntentPollRead"
}
}
}
},
"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_purchase_intent",
"x-mcp-exposed": true,
"x-public-path": "/v1/purchase_intents/{purchase_intent_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/purchase_intents/... \\\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_purchase_intent\",\n \"arguments\": {\n \"purchase_intent_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_purchase_intent\",\n arguments: {\n \"purchase_intent_id\": \"...\"\n},\n});"
}
]
}
POST /v1/purchase_intents/{purchase_intent_id}
Update a purchase intent
Apply a partial update to a purchase intent, including approval after verification.
Parameters, request, responses, and security
{
"tags": [
"purchase-intents"
],
"summary": "Update a purchase intent",
"description": "Apply a partial update to a purchase intent, including approval after verification.",
"operationId": "v1_update_purchase_intent",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"title": "Purchase Intent Id"
},
"name": "purchase_intent_id",
"in": "path"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicPurchaseIntentUpdate"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicPurchaseIntentPollRead"
}
}
}
},
"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_purchase_intent",
"x-mcp-exposed": true,
"x-public-path": "/v1/purchase_intents/{purchase_intent_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/purchase_intents/... \\\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_purchase_intent\",\n \"arguments\": {\n \"purchase_intent_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_purchase_intent\",\n arguments: {\n \"purchase_intent_id\": \"...\"\n},\n});"
}
]
}
POST /v1/purchase_intents/{purchase_intent_id}/approve
Approve a purchase intent
When policy requires human approval, call the approve API to represent approval by the profile user.
For issued cards, just pass the approve parameter. For cards with agentic commerce enrollement that require a passkey, the PI will be created with a challenge; you will need to pass payment_action.verification_challenge params to complete the approval. For payment_action.kind=cvc_reentry, collect a CVC token and pass temporary_cvc_token_id.
Parameters, request, responses, and security
{
"tags": [
"purchase-intents"
],
"summary": "Approve a purchase intent",
"description": "When policy requires human approval, call the approve API to represent approval by the profile user.\n\nFor issued cards, just pass the approve parameter.\nFor cards with agentic commerce enrollement that require a passkey, the PI will be created with a challenge; you will need to pass payment_action.verification_challenge params to complete the approval.\nFor payment_action.kind=cvc_reentry, collect a CVC token and pass temporary_cvc_token_id.",
"operationId": "v1_approve_purchase_intent",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"title": "Purchase Intent Id"
},
"name": "purchase_intent_id",
"in": "path"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/PublicApprovalAction"
},
{
"type": "null"
}
],
"title": "Payload"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicPurchaseIntentPollRead"
}
}
}
},
"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_approve_purchase_intent",
"x-mcp-exposed": true,
"x-public-path": "/v1/purchase_intents/{purchase_intent_id}/approve",
"x-docs-kind": "other",
"x-docs-order": 100,
"x-docs-depth": 2,
"x-docs-action-order": 50,
"x-codeSamples": [
{
"lang": "shell",
"label": "curl",
"source": "curl -X POST https://api.openmerchant.dev/v1/purchase_intents/.../approve \\\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_approve_purchase_intent\",\n \"arguments\": {\n \"purchase_intent_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_approve_purchase_intent\",\n arguments: {\n \"purchase_intent_id\": \"...\"\n},\n});"
}
]
}
POST /v1/purchase_intents/{purchase_intent_id}/payment_verification_challenge
Create a payment verification challenge
When creating a PurchaseIntent that requires a passkey, the challenge is automatically created. Use this endpoint when payment_action.verification_challenge is missing or expired to recreate it. For payment_action.kind=cvc_reentry, collect and submit temporary_cvc_token_id instead.
Parameters, request, responses, and security
{
"tags": [
"purchase-intents"
],
"summary": "Create a payment verification challenge",
"description": "When creating a PurchaseIntent that requires a passkey, the challenge is automatically created. Use this endpoint when `payment_action.verification_challenge` is missing or expired to recreate it. For `payment_action.kind=cvc_reentry`, collect and submit `temporary_cvc_token_id` instead.",
"operationId": "v1_create_payment_verification_challenge",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"title": "Purchase Intent Id"
},
"name": "purchase_intent_id",
"in": "path"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaymentVerificationChallengeRead"
}
}
}
},
"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_payment_verification_challenge",
"x-mcp-exposed": true,
"x-public-path": "/v1/purchase_intents/{purchase_intent_id}/payment_verification_challenge",
"x-docs-kind": "other",
"x-docs-order": 100,
"x-docs-depth": 2,
"x-docs-action-order": 55,
"x-codeSamples": [
{
"lang": "shell",
"label": "curl",
"source": "curl -X POST https://api.openmerchant.dev/v1/purchase_intents/.../payment_verification_challenge \\\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_create_payment_verification_challenge\",\n \"arguments\": {\n \"purchase_intent_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_create_payment_verification_challenge\",\n arguments: {\n \"purchase_intent_id\": \"...\"\n},\n});"
}
]
}
POST /v1/purchase_intents/{purchase_intent_id}/retry
Retry a purchase intent
Retry a purchase intent that failed or paused in a retryable state. To retry a checkout blocked on merchant sign-in, collect the credentials with the MerchantAuthHandoff element and pass the credential_ticket_id returned by a defer_retry submit — raw merchant credentials are never accepted on this endpoint. Tickets are one-time and short-lived: redemption destroys the ticket, and an expired or replayed ticket returns 410.
Parameters, request, responses, and security
{
"tags": [
"purchase-intents"
],
"summary": "Retry a purchase intent",
"description": "Retry a purchase intent that failed or paused in a retryable state. To retry a checkout blocked on merchant sign-in, collect the credentials with the MerchantAuthHandoff element and pass the `credential_ticket_id` returned by a `defer_retry` submit — raw merchant credentials are never accepted on this endpoint. Tickets are one-time and short-lived: redemption destroys the ticket, and an expired or replayed ticket returns 410.",
"operationId": "v1_retry_purchase_intent",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"title": "Purchase Intent Id"
},
"name": "purchase_intent_id",
"in": "path"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/PublicPurchaseIntentRetryRequest"
},
{
"type": "null"
}
],
"title": "Payload"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicPurchaseIntentPollRead"
}
}
}
},
"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_retry_purchase_intent",
"x-mcp-exposed": true,
"x-public-path": "/v1/purchase_intents/{purchase_intent_id}/retry",
"x-docs-kind": "other",
"x-docs-order": 100,
"x-docs-depth": 2,
"x-docs-action-order": 60,
"x-codeSamples": [
{
"lang": "shell",
"label": "curl",
"source": "curl -X POST https://api.openmerchant.dev/v1/purchase_intents/.../retry \\\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_retry_purchase_intent\",\n \"arguments\": {\n \"purchase_intent_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_retry_purchase_intent\",\n arguments: {\n \"purchase_intent_id\": \"...\"\n},\n});"
}
]
}
POST /v1/purchase_intents/{purchase_intent_id}/cancel
Cancel a purchase intent
Cancel any queued or in-progress purchase attempts and close the purchase intent.
Parameters, request, responses, and security
{
"tags": [
"purchase-intents"
],
"summary": "Cancel a purchase intent",
"description": "Cancel any queued or in-progress purchase attempts and close the purchase intent.",
"operationId": "v1_cancel_purchase_intent",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"title": "Purchase Intent Id"
},
"name": "purchase_intent_id",
"in": "path"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicPurchaseIntentPollRead"
}
}
}
},
"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_cancel_purchase_intent",
"x-mcp-exposed": true,
"x-public-path": "/v1/purchase_intents/{purchase_intent_id}/cancel",
"x-docs-kind": "other",
"x-docs-order": 100,
"x-docs-depth": 2,
"x-docs-action-order": 70,
"x-codeSamples": [
{
"lang": "shell",
"label": "curl",
"source": "curl -X POST https://api.openmerchant.dev/v1/purchase_intents/.../cancel \\\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_cancel_purchase_intent\",\n \"arguments\": {\n \"purchase_intent_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_cancel_purchase_intent\",\n arguments: {\n \"purchase_intent_id\": \"...\"\n},\n});"
}
]
}
POST /v1/purchase_intents/{purchase_intent_id}/cart_executions/{cart_execution_id}/cancel
Cancel a merchant cart
Cancel one queued or in-progress merchant cart within a multi-cart purchase intent, leaving the other merchant carts untouched.
Parameters, request, responses, and security
{
"tags": [
"purchase-intents"
],
"summary": "Cancel a merchant cart",
"description": "Cancel one queued or in-progress merchant cart within a multi-cart purchase intent, leaving the other merchant carts untouched.",
"operationId": "v1_cancel_purchase_intent_cart_execution",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"title": "Purchase Intent Id"
},
"name": "purchase_intent_id",
"in": "path"
},
{
"required": true,
"schema": {
"type": "string",
"title": "Cart Execution Id"
},
"name": "cart_execution_id",
"in": "path"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicPurchaseIntentPollRead"
}
}
}
},
"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_cancel_purchase_intent_cart_execution",
"x-mcp-exposed": true,
"x-public-path": "/v1/purchase_intents/{purchase_intent_id}/cart_executions/{cart_execution_id}/cancel",
"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/purchase_intents/.../cart_executions/.../cancel \\\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_cancel_purchase_intent_cart_execution\",\n \"arguments\": {\n \"purchase_intent_id\": \"...\",\n \"cart_execution_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_cancel_purchase_intent_cart_execution\",\n arguments: {\n \"purchase_intent_id\": \"...\",\n \"cart_execution_id\": \"...\"\n},\n});"
}
]
}
POST /v1/purchase_intents/{purchase_intent_id}/cart_executions/{cart_execution_id}/retry
Retry a merchant cart
Retry one failed merchant cart within a multi-cart purchase intent, leaving the other merchant carts untouched.
Parameters, request, responses, and security
{
"tags": [
"purchase-intents"
],
"summary": "Retry a merchant cart",
"description": "Retry one failed merchant cart within a multi-cart purchase intent, leaving the other merchant carts untouched.",
"operationId": "v1_retry_purchase_intent_cart_execution",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"title": "Purchase Intent Id"
},
"name": "purchase_intent_id",
"in": "path"
},
{
"required": true,
"schema": {
"type": "string",
"title": "Cart Execution Id"
},
"name": "cart_execution_id",
"in": "path"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicPurchaseIntentPollRead"
}
}
}
},
"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_retry_purchase_intent_cart_execution",
"x-mcp-exposed": true,
"x-public-path": "/v1/purchase_intents/{purchase_intent_id}/cart_executions/{cart_execution_id}/retry",
"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/purchase_intents/.../cart_executions/.../retry \\\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_retry_purchase_intent_cart_execution\",\n \"arguments\": {\n \"purchase_intent_id\": \"...\",\n \"cart_execution_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_retry_purchase_intent_cart_execution\",\n arguments: {\n \"purchase_intent_id\": \"...\",\n \"cart_execution_id\": \"...\"\n},\n});"
}
]
}
GET /v1/purchase_intents/{purchase_intent_id}/events
Stream purchase-intent events
Open a server-sent events stream for purchase-intent lifecycle updates.
Parameters, request, responses, and security
{
"tags": [
"purchase-intents"
],
"summary": "Stream purchase-intent events",
"description": "Open a server-sent events stream for purchase-intent lifecycle updates.",
"operationId": "v1_stream_purchase_intent_events",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"title": "Purchase Intent Id"
},
"name": "purchase_intent_id",
"in": "path"
},
{
"required": false,
"schema": {
"items": {
"$ref": "#/components/schemas/PublicPurchaseIntentExpand"
},
"type": "array",
"title": "Expand"
},
"name": "expand",
"in": "query"
}
],
"responses": {
"200": {
"description": "Server-sent purchase-intent lifecycle events.",
"content": {
"text/event-stream": {
"schema": {
"type": "string"
}
}
}
},
"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_stream_purchase_intent_events",
"x-mcp-exposed": true,
"x-public-path": "/v1/purchase_intents/{purchase_intent_id}/events",
"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/purchase_intents/.../events \\\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_stream_purchase_intent_events\",\n \"arguments\": {\n \"purchase_intent_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_stream_purchase_intent_events\",\n arguments: {\n \"purchase_intent_id\": \"...\"\n},\n});"
}
]
}