PurchaseIntent Links

Download the complete public OpenAPI schema

PurchaseIntent Links

Issue short-lived hosted links that let an end customer view a PurchaseIntent and act on it — approve, decline, cancel, retry, or sign in to the merchant when the agent hits a login wall — on an OpenMerchant-hosted page.

Scope what the recipient may do with allowed_actions, and keep expires_in_hours short: an approve-capable link is spending authority. The returned url carries the only copy of the secret token; store or forward it immediately. Links expire automatically and can be invalidated early with the revoke endpoint.

GET /v1/purchase_intents/{purchase_intent_id}/links

List PurchaseIntent links

Parameters, request, responses, and security


{
  "tags": [
    "purchase-intent-links"
  ],
  "summary": "List PurchaseIntent links",
  "operationId": "v1_list_purchase_intent_links",
  "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/PublicPurchaseIntentLinkListResponse"
          }
        }
      }
    },
    "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_intent_links",
  "x-mcp-exposed": true,
  "x-public-path": "/v1/purchase_intents/{purchase_intent_id}/links",
  "x-docs-kind": "other",
  "x-docs-order": 100,
  "x-docs-depth": 2,
  "x-docs-action-order": 20,
  "x-codeSamples": [
    {
      "lang": "shell",
      "label": "curl",
      "source": "curl -X GET https://api.openmerchant.dev/v1/purchase_intents/.../links \\\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_intent_links\",\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_list_purchase_intent_links\",\n  arguments: {\n  \"purchase_intent_id\": \"...\"\n},\n});"
    }
  ]
}

POST /v1/purchase_intents/{purchase_intent_id}/links

Create a PurchaseIntent link

Issue a hosted, co-branded link the end customer can open to view this purchase intent and act on it (approve, decline, cancel, retry, or sign in to the merchant). The raw token is embedded in url on this response ONLY — store the URL, not the token. Scope allowed_actions and keep expires_in_hours short: an approve-capable link is spending authority.

Parameters, request, responses, and security


{
  "tags": [
    "purchase-intent-links"
  ],
  "summary": "Create a PurchaseIntent link",
  "description": "Issue a hosted, co-branded link the end customer can open to view this purchase intent and act on it (approve, decline, cancel, retry, or sign in to the merchant). The raw token is embedded in `url` on this response ONLY — store the URL, not the token. Scope `allowed_actions` and keep `expires_in_hours` short: an approve-capable link is spending authority.",
  "operationId": "v1_create_purchase_intent_link",
  "parameters": [
    {
      "required": true,
      "schema": {
        "type": "string",
        "title": "Purchase Intent Id"
      },
      "name": "purchase_intent_id",
      "in": "path"
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/PurchaseIntentLinkCreateRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "201": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PublicPurchaseIntentLinkRead"
          }
        }
      }
    },
    "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_link",
  "x-mcp-exposed": true,
  "x-public-path": "/v1/purchase_intents/{purchase_intent_id}/links",
  "x-docs-kind": "other",
  "x-docs-order": 100,
  "x-docs-depth": 2,
  "x-docs-action-order": 10,
  "x-codeSamples": [
    {
      "lang": "shell",
      "label": "curl",
      "source": "curl -X POST https://api.openmerchant.dev/v1/purchase_intents/.../links \\\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_purchase_intent_link\",\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_purchase_intent_link\",\n  arguments: {\n  \"purchase_intent_id\": \"...\"\n},\n});"
    }
  ]
}

POST /v1/purchase_intents/{purchase_intent_id}/links/{link_id}/revoke

Revoke a PurchaseIntent link

Parameters, request, responses, and security


{
  "tags": [
    "purchase-intent-links"
  ],
  "summary": "Revoke a PurchaseIntent link",
  "operationId": "v1_revoke_purchase_intent_link",
  "parameters": [
    {
      "required": true,
      "schema": {
        "type": "string",
        "title": "Purchase Intent Id"
      },
      "name": "purchase_intent_id",
      "in": "path"
    },
    {
      "required": true,
      "schema": {
        "type": "string",
        "title": "Link Id"
      },
      "name": "link_id",
      "in": "path"
    }
  ],
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PublicPurchaseIntentLinkRead"
          }
        }
      }
    },
    "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_revoke_purchase_intent_link",
  "x-mcp-exposed": true,
  "x-public-path": "/v1/purchase_intents/{purchase_intent_id}/links/{link_id}/revoke",
  "x-docs-kind": "other",
  "x-docs-order": 100,
  "x-docs-depth": 2,
  "x-docs-action-order": 30,
  "x-codeSamples": [
    {
      "lang": "shell",
      "label": "curl",
      "source": "curl -X POST https://api.openmerchant.dev/v1/purchase_intents/.../links/.../revoke \\\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_revoke_purchase_intent_link\",\n    \"arguments\": {\n      \"purchase_intent_id\": \"...\",\n      \"link_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_revoke_purchase_intent_link\",\n  arguments: {\n  \"purchase_intent_id\": \"...\",\n  \"link_id\": \"...\"\n},\n});"
    }
  ]
}