{ "openapi": "3.1.0", "info": { "title": "Knot API", "description": "An API to interact with the Knot merchant connectivity platform.", "version": "1.0.0" }, "servers": [ { "url": "https://development.knotapi.com", "description": "Development server" } ], "security": [ { "basicAuth": [] } ], "x-mint": { "mcp": { "enabled": true, "name": "knot" } }, "paths": { "/transactions/refresh": { "post": { "operationId": "transaction_refresh", "summary": "Refresh Transactions", "description": "Initiate an on-demand refresh of transaction data for a user's merchant account.", "requestBody": { "description": "The input parameters required for refreshing transactions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "merchant_id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 45 }, "external_user_id": { "type": "string", "description": "Your unique identifier for the user.", "example": "abc" } }, "required": [ "merchant_id", "external_user_id" ] } } } }, "responses": { "202": { "description": "Refresh request accepted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Success" } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ExternalUserIdRequired": { "summary": "external_user_id field is required", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The external_user_id field is required." } }, "MerchantIdRequired": { "summary": "merchant_id field is required", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The merchant_id field is required." } }, "UserNotFound": { "summary": "User not found", "value": { "error_type": "USER_ERROR", "error_code": "USER_NOT_FOUND", "error_message": "The user was not found. Please check the ID provided." } }, "MerchantAccountNotFound": { "summary": "Merchant account not found", "value": { "error_type": "MERCHANT_ACCOUNT_ERROR", "error_code": "MERCHANT_ACCOUNT_NOT_FOUND", "error_message": "The merchant account was not found. Please check the merchant_id provided." } }, "MerchantAccountDisconnected": { "summary": "Merchant account is disconnected", "value": { "error_type": "MERCHANT_ACCOUNT_ERROR", "error_code": "MERCHANT_ACCOUNT_DISCONNECTED", "error_message": "The merchant account is disconnected. Please check the merchant_id provided." } }, "MerchantUnavailable": { "summary": "Merchant is unavailable", "value": { "error_type": "MERCHANT_ERROR", "error_code": "MERCHANT_UNAVAILABLE", "error_message": "The merchant is unavailable. Please check the merchant_id provided." } }, "OngoingOperation": { "summary": "An existing operation is in progress", "value": { "error_type": "MERCHANT_ACCOUNT_ERROR", "error_code": "ONGOING_OPERATION", "error_message": "An existing operation is in progress." } } } } } }, "401": { "description": "Unauthorized request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthFailed": { "summary": "Auth failed", "value": { "error_type": "INVALID_INPUT", "error_code": "INVALID_API_KEYS", "error_message": "Invalid client_id or secret provided." } } } } } }, "403": { "description": "Forbidden request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NoAccess": { "summary": "No access", "value": { "error_type": "INVALID_REQUEST", "error_code": "NO_ACCESS", "error_message": "Please contact Knot for access to this endpoint." } } } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until the rate limit resets. The limit is 1 request per hour per linked merchant account.", "schema": { "type": "integer", "example": 3600 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RateLimitExceeded": { "summary": "Rate limit exceeded", "value": { "error_type": "RATE_LIMIT_ERROR", "error_code": "TOO_MANY_REQUESTS", "error_message": "Rate limit exceeded. Please retry after the time indicated in the Retry-After header." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InternalServerError": { "summary": "Unexpected server error", "value": { "message": "Server Error" } } } } } } } } }, "/transactions/sync": { "post": { "operationId": "transaction_sync", "summary": "Sync Transactions", "description": "Sync a user's transactions for a merchant account using cursor-based pagination.", "x-mint": { "mcp": { "enabled": true, "name": "sync-transactions", "description": "Sync a user's transactions for a merchant account using cursor-based pagination." } }, "requestBody": { "description": "The input parameters required for syncing transactions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "merchant_id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 45 }, "external_user_id": { "type": "string", "description": "Your unique identifier for the user.", "example": "abc" }, "cursor": { "type": "string", "description": "Cursor token pointing to the last transaction retrieved. The `/transactions/sync` endpoint uses **cursor-based** pagination to track which transactions have already been seen, minimizing data redundancy. \n\nOn the first call, the endpoint returns all transactions **paginated**. In subsequent calls, only new transactions are provided using the **next cursor**.", "example": "eyJpZCI6MjI3ODEsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0" }, "limit": { "type": [ "integer", "null" ], "description": "Maximum number of transactions to retrieve (min: 1, max: 100).", "minimum": 1, "maximum": 100, "example": 100, "default": 5 } }, "required": [ "merchant_id", "external_user_id" ] } } } }, "responses": { "200": { "description": "Successful request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "merchant": { "$ref": "#/components/schemas/Merchant" }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor token for the next page of transactions." }, "limit": { "type": "integer", "description": "Number of transactions returned based on the limit provided.", "example": 5 } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UserNotFound": { "summary": "User not found", "value": { "error_type": "USER_ERROR", "error_code": "USER_NOT_FOUND", "error_message": "The user was not found. Please check the ID provided." } }, "MerchantAccountNotFound": { "summary": "Merchant account was not found", "value": { "error_type": "MERCHANT_ACCOUNT_ERROR", "error_code": "MERCHANT_ACCOUNT_NOT_FOUND", "error_message": "The merchant account was not found. Please check the merchant_id provided." } }, "MerchantIdRequired": { "summary": "merchant_id field is required", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The merchant_id field is required." } }, "ExternalUserIdRequired": { "summary": "external_user_id not found", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The external user id field is required." } }, "LimitNotInteger": { "summary": "limit must be an integer", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The limit must be an integer." } }, "LimitMoreThanOne": { "summary": "The limit must be at least 1.", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The limit must be at least 1." } }, "LimitLessThanHundred": { "summary": "The limit may not be greater than 100.", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The limit may not be greater than 100." } }, "InvalidCursorFormat": { "summary": "Cursor format is invalid", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The provided cursor is invalid." } }, "CursorNotString": { "summary": "Cursor must be a string", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The cursor must be a string." } }, "NoAccess": { "summary": "No access", "value": { "error_type": "INVALID_REQUEST", "error_code": "NO_ACCESS", "error_message": "Please contact Knot for access to this endpoint." } } } } } }, "401": { "description": "Unauthorized request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthFailed": { "summary": "Auth failed", "value": { "error_type": "INVALID_INPUT", "error_code": "INVALID_API_KEYS", "error_message": "Invalid client_id or secret provided." } } } } } }, "403": { "description": "Forbidden request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NoAccess": { "summary": "No access", "value": { "error_type": "INVALID_REQUEST", "error_code": "NO_ACCESS", "error_message": "Please contact Knot for access to this endpoint." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InternalServerError": { "summary": "Unexpected server error", "value": { "message": "Server Error" } } } } } } } } }, "/transactions/{id}": { "get": { "operationId": "transaction_get_by_id", "summary": "Get Transaction By ID", "description": "Get a specific transaction by ID.", "x-mint": { "mcp": { "enabled": true, "name": "get-transaction-by-id", "description": "Get a specific transaction by ID." } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "13da3c28-a068-4642-9ce2-b730cfda5f5f" }, "description": "UUID for a transaction provided in the UPDATED_TRANSACTIONS_AVAILABLE webhook." } ], "responses": { "200": { "description": "Successful request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TransactionNotFound": { "summary": "Transaction not found", "value": { "error_type": "TRANSACTION_ERROR", "error_code": "TRANSACTION_NOT_FOUND", "error_message": "The transaction was not found. Please check the ID provided." } }, "NoAccess": { "summary": "No access", "value": { "error_type": "INVALID_REQUEST", "error_code": "NO_ACCESS", "error_message": "Please contact Knot for access to this endpoint." } } } } } }, "401": { "description": "Unauthorized request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthFailed": { "summary": "Auth failed", "value": { "error_type": "INVALID_INPUT", "error_code": "INVALID_API_KEYS", "error_message": "Invalid client_id or secret provided." } } } } } }, "403": { "description": "Forbidden request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NoAccess": { "summary": "No access", "value": { "error_type": "INVALID_REQUEST", "error_code": "NO_ACCESS", "error_message": "Please contact Knot for access to this endpoint." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InternalServerError": { "summary": "Unexpected server error", "value": { "message": "Server Error" } } } } } } } } }, "/transactions/{id}/raw": { "get": { "operationId": "transaction_get_raw_by_id", "summary": "Get Raw Transaction by ID", "description": "Get a specific raw transaction by ID.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "13da3c28-a068-4642-9ce2-b730cfda5f5f" }, "description": "UUID for a transaction." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2048, "example": "CAEQieSo6_MzGNW564HyMyIkMDE5ZjIwM2EtZGU3Ny03OWNlLWJiNDBtNzNhZmRmYTQwZWVjUgU0NDQzNGgBcgICA3opCicKCmV4dGVybmFsSWQSGTIXChUaEzIyMzUwMTU3NDc1MjMzMjAyIAQo.bUkUUocrBS_aRWnQ3oIC6krZMqKfGx8S-YZ8CT9BgO0" }, "description": "Cursor token pointing to the last raw data object retrieved. The `/transactions/{id}/raw` endpoint uses **cursor-based** pagination to track which of a transaction's raw data objects have already been seen, minimizing data redundancy. \n\nOn the first call, the endpoint returns all of the transaction's raw data objects **paginated**. In subsequent calls, only new raw data objects are provided using the **next cursor**." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100, "example": 10, "default": 10 }, "description": "Maximum number of raw data objects to retrieve (min: 1, max: 100)." } ], "responses": { "200": { "description": "Successful request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "merchant": { "$ref": "#/components/schemas/Merchant" }, "data": { "type": "array", "items": { "type": "object", "properties": { "content_type": { "type": "string", "description": "The MIME type of the merchant response." }, "encoding": { "type": "string", "nullable": true, "description": "The encoding of the body, if applicable. For example, base64 for binary responses such as gRPC/protobuf." }, "body": { "type": "string", "description": "The raw response body from the merchant." } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor token for the next page of raw data objects. Null if there are no further pages." }, "limit": { "type": [ "integer", "null" ], "description": "Number of raw data objects returned based on the limit provided.", "example": 10 } } }, "examples": { "Lyft": { "summary": "Lyft", "value": { "merchant": { "id": 42, "name": "Lyft" }, "limit": 10, "next_cursor": "CAEQieSo6_MzGNW564HyMyIkMDE5ZjIwM2EtZGU3Ny03OWNlLWJiNDBtNzNhZmRmYTQwZWVjUgU0NDQzNGgBcgICA3opCicKCmV4dGVybmFsSWQSGTIXChUaEzIyMzUwMTU3NDc1MjMzMjAyIAQo.bUkUUocrBS_aRWnQ3oIC6krZMqKfGx8S-YZ8CT9BgO0", "data": [ { "content_type": "application/json", "encoding": null, "body": "{...}" }, { "content_type": "application/json", "encoding": null, "body": "{...}" }, { "content_type": "application/json", "encoding": null, "body": "{...}" }, { "content_type": "application/json", "encoding": null, "body": "{...}" }, { "content_type": "application/json", "encoding": null, "body": "{...}" }, { "content_type": "application/json", "encoding": null, "body": "{...}" }, { "content_type": "application/json", "encoding": null, "body": "{...}" } ] } }, "Waymo": { "summary": "Waymo", "value": { "merchant": { "id": 2364, "name": "Waymo" }, "limit": 10, "next_cursor": null, "data": [ { "content_type": "application/grpc", "encoding": "base64", "body": "..." }, { "content_type": "application/grpc", "encoding": "base64", "body": "..." }, { "content_type": "application/grpc", "encoding": "base64", "body": "..." }, { "content_type": "application/grpc", "encoding": "base64", "body": "..." }, { "content_type": "application/grpc", "encoding": "base64", "body": "..." }, { "content_type": "application/grpc", "encoding": "base64", "body": "..." }, { "content_type": "application/grpc", "encoding": "base64", "body": "..." }, { "content_type": "application/grpc", "encoding": "base64", "body": "..." } ] } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "TransactionNotFound": { "summary": "Transaction not found", "value": { "error_type": "TRANSACTION_ERROR", "error_code": "TRANSACTION_NOT_FOUND", "error_message": "The transaction was not found. Please check the ID provided." } }, "LimitNotInteger": { "summary": "limit must be an integer", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The limit must be an integer." } }, "LimitMoreThanOne": { "summary": "The limit must be at least 1.", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The limit must be at least 1." } }, "LimitLessThanHundred": { "summary": "The limit may not be greater than 100.", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The limit may not be greater than 100." } }, "InvalidCursorFormat": { "summary": "Cursor format is invalid", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The cursor format is invalid." } }, "NoAccess": { "summary": "No access", "value": { "error_type": "INVALID_REQUEST", "error_code": "NO_ACCESS", "error_message": "Please contact Knot for access to this endpoint." } } } } } }, "401": { "description": "Unauthorized request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthFailed": { "summary": "Auth failed", "value": { "error_type": "INVALID_INPUT", "error_code": "INVALID_API_KEYS", "error_message": "Invalid client_id or secret provided." } } } } } }, "403": { "description": "Forbidden request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NoAccess": { "summary": "No access", "value": { "error_type": "INVALID_REQUEST", "error_code": "NO_ACCESS", "error_message": "Please contact Knot for access to this endpoint." } } } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until the rate limit resets. The limit is 250 requests per minute and 3,500 requests per hour.", "schema": { "type": "integer", "example": 60 } }, "X-RateLimit-Limit": { "description": "Maximum number of requests permitted in the window that was exhausted.", "schema": { "type": "integer", "example": 250 } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the window that was exhausted.", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Unix timestamp at which the rate limit resets.", "schema": { "type": "integer", "example": 1789653294 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Rate limit error message." } } }, "examples": { "RateLimitExceeded": { "summary": "Rate limit exceeded", "value": { "message": "Too Many Attempts." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InternalServerError": { "summary": "Unexpected server error", "value": { "message": "Server Error" } } } } } } } } }, "/products": { "get": { "operationId": "products_get", "summary": "Get Products", "description": "Retrieve a user's purchased products and their real-time prices at a given merchant or merchants.", "x-mint": { "mcp": { "enabled": true, "name": "get-products", "description": "Retrieve product pricing and savings data for a user across one or all linked merchant accounts." } }, "parameters": [ { "name": "external_user_id", "in": "query", "required": true, "description": "Your unique identifier for the user.", "schema": { "type": "string", "example": "abc" } }, { "name": "merchant_id", "in": "query", "required": false, "description": "Unique identifier for the merchant. When provided, results are scoped to that merchant. When omitted, results include all of the user's linked merchant accounts.", "schema": { "type": "integer", "example": 45 } } ], "responses": { "200": { "description": "Successful request.", "content": { "application/json": { "schema": { "type": "array", "items": { "oneOf": [ { "title": "Product information for a specific merchant", "type": "object", "properties": { "gtin": { "type": "string", "description": "Global Trade Item Number identifying the product.", "example": "012345678905" }, "price": { "type": "object", "properties": { "unit_price": { "type": "string", "description": "Per-unit price of the product.", "example": "12.56" } } }, "savings": { "type": "array", "description": "List of savings applied to the product. Empty if no savings are available.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "direct", "coupon" ], "description": "The type of savings." }, "amount": { "type": "string", "description": "Savings amount.", "example": "1.99" }, "description": { "type": "string", "description": "Human-readable description of the savings.", "example": "Now $12.56" } } } } } }, { "title": "Product information across all merchants", "type": "object", "properties": { "gtin": { "type": "string", "description": "Global Trade Item Number identifying the product.", "example": "012345678905" }, "merchants": { "type": "array", "items": { "type": "object", "properties": { "merchant": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the merchant.", "example": "45" }, "name": { "type": "string", "description": "Display name of the merchant.", "example": "Walmart" } } }, "price": { "type": "object", "properties": { "unit_price": { "type": "string", "description": "Per-unit price of the product at this merchant.", "example": "12.56" } } }, "savings": { "type": "array", "description": "List of savings applied to the product at this merchant. Empty if no savings are available.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "direct", "coupon" ], "description": "The type of savings." }, "amount": { "type": "string", "description": "Savings amount.", "example": "1.99" }, "description": { "type": "string", "description": "Human-readable description of the savings.", "example": "Now $12.56" } } } } } } } } } ] } }, "examples": { "WithMerchantId": { "summary": "With merchant_id \u2014 single-merchant product pricing", "value": [ { "gtin": "012345678905", "price": { "unit_price": "12.56" }, "savings": [ { "type": "direct", "amount": "1.99", "description": "Now $12.56" }, { "type": "coupon", "amount": "5.00", "description": "Get $5.00 Walmart Cash" } ] }, { "gtin": "012345678917", "price": { "unit_price": "19.99" }, "savings": [] } ] }, "WithoutMerchantId": { "summary": "Without merchant_id \u2014 product pricing across all linked merchants", "value": [ { "gtin": "012345678905", "merchants": [ { "merchant": { "id": "45", "name": "Walmart" }, "price": { "unit_price": "12.56" }, "savings": [ { "type": "direct", "amount": "1.99", "description": "Now $12.56" }, { "type": "coupon", "amount": "5.00", "description": "Get $5.00 Walmart Cash" } ] }, { "merchant": { "id": "44", "name": "Amazon" }, "price": { "unit_price": "13.67" }, "savings": [] } ] }, { "gtin": "012345671892", "merchants": [ { "merchant": { "id": "45", "name": "Walmart" }, "price": { "unit_price": "7.89" }, "savings": [ { "type": "direct", "amount": "2.03", "description": "Now $7.89" }, { "type": "coupon", "amount": "5.00", "description": "Get $5.00 Walmart Cash" } ] }, { "merchant": { "id": "44", "name": "Amazon" }, "price": { "unit_price": "8.55" }, "savings": [] } ] } ] } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ExternalUserIdRequired": { "summary": "external_user_id field is required", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The external_user_id field is required." } }, "UserNotFound": { "summary": "User not found", "value": { "error_type": "USER_ERROR", "error_code": "USER_NOT_FOUND", "error_message": "The user was not found. Please check the external_user_id provided." } }, "MerchantAccountNotFound": { "summary": "Merchant account not found", "value": { "error_type": "MERCHANT_ACCOUNT_ERROR", "error_code": "MERCHANT_ACCOUNT_NOT_FOUND", "error_message": "The merchant account was not found. Please check the merchant_id provided." } }, "NoAccess": { "summary": "No access", "value": { "error_type": "INVALID_REQUEST", "error_code": "NO_ACCESS", "error_message": "Please contact Knot for access to this endpoint." } } } } } }, "401": { "description": "Unauthorized request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthFailed": { "summary": "Auth failed", "value": { "error_type": "INVALID_INPUT", "error_code": "INVALID_API_KEYS", "error_message": "Invalid client_id or secret provided." } } } } } }, "403": { "description": "Forbidden request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NoAccess": { "summary": "No access", "value": { "error_type": "INVALID_REQUEST", "error_code": "NO_ACCESS", "error_message": "Please contact Knot for access to this endpoint." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InternalServerError": { "summary": "Unexpected server error", "value": { "message": "Server Error" } } } } } } } } }, "/subscriptions/list": { "post": { "operationId": "subscriptions_list", "summary": "List Subscriptions", "description": "List a user's subscriptions using cursor-based pagination.", "x-mint": { "mcp": { "enabled": true, "name": "list-subscriptions", "description": "List a user's subscriptions using cursor-based pagination." } }, "requestBody": { "description": "The input parameters required for listing subscriptions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "external_user_id": { "type": "string", "description": "Your unique identifier for the user.", "example": "abc" }, "merchant_id": { "type": "integer", "description": "The unique ID of a merchant. When provided, only subscriptions for that merchant's linked account are returned.", "example": 18 }, "status": { "type": "string", "description": "When provided, only subscriptions with this status are returned.", "example": "ACTIVE", "enum": [ "ACTIVE", "ACTIVE_CANCELLATION", "ACTIVE_PLAN_CHANGE", "ACTIVE_SUSPENSION", "PENDING", "PAUSED", "CANCELLED", "SUSPENDED", "UNRECOGNIZED" ] }, "is_paid": { "type": "boolean", "description": "When provided, only subscriptions matching this paid/free status are returned.", "example": true }, "is_family_plan": { "type": "boolean", "description": "When provided, only subscriptions matching this family-plan status are returned.", "example": false }, "is_cancellable": { "type": "boolean", "description": "When provided, only subscriptions matching this cancellable status are returned.", "example": true }, "cursor": { "type": "string", "description": "Cursor token pointing to the last subscription retrieved. The `/subscriptions/list` endpoint uses **cursor-based** pagination to track which subscriptions have already been seen, minimizing data redundancy. \n\nOn the first call, the endpoint returns all subscriptions **paginated**. In subsequent calls, only subscriptions after the **next cursor** are provided.", "example": "eyJpZCI6MjI3ODEsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0" }, "limit": { "type": "integer", "description": "Maximum number of subscriptions to retrieve (min: 1, max: 100).", "example": 100, "default": 100 } }, "required": [ "external_user_id" ] }, "examples": { "AllSubscriptions": { "summary": "List all subscriptions", "value": { "external_user_id": "abc" } }, "FilterByMerchant": { "summary": "List subscriptions for a specific merchant", "value": { "external_user_id": "abc", "merchant_id": 18 } } } } } }, "responses": { "200": { "description": "Successful request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/Subscription" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor token for the next page of subscriptions. `null` when there are no more subscriptions to retrieve." }, "limit": { "type": "integer", "description": "Number of subscriptions returned based on the limit provided.", "example": 100 } } }, "examples": { "AllSubscriptions": { "summary": "Example subscriptions response.", "value": { "subscriptions": [ { "id": "13da3c28-a068-4642-9ce2-b730cfda5f5f", "external_id": "a9x7bq2lmw5p", "name": "Disney+, Hulu Bundle Premium", "description": "Ad-free streaming with Disney+ and Hulu", "merchant": { "id": 18, "name": "Hulu", "category": "Streaming", "logo": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png", "parent_merchant": null }, "status": "ACTIVE", "billing_cycle": "RECURRING_MONTHLY", "next_billing_date": "2026-02-10", "last_billing_date": "2026-01-10", "start_date": "2025-06-15", "expiration_date": null, "payment_method": { "type": "CARD", "brand": "VISA", "last_four": "1234" }, "cancel_instructions": "You can cancel your subscription at any time from your account settings. Your cancellation will take effect at the end of your current billing period.", "is_paid": true, "is_family_plan": false, "is_cancellable": true, "price": { "total": "11.99", "currency": "USD" } }, { "id": "7a2e9f14-b532-48d1-ae73-c9f2d8e61b4a", "external_id": "sp_sub_8x2k4m", "name": "Premium Individual", "description": "Ad-free music streaming for one account", "merchant": { "id": 13, "name": "Spotify", "category": "Streaming", "logo": "https://knot.imgix.net/merchants/spotify-logo.png", "parent_merchant": null }, "status": "ACTIVE", "billing_cycle": "RECURRING_MONTHLY", "next_billing_date": "2026-03-10", "last_billing_date": "2026-02-10", "start_date": "2024-09-01", "expiration_date": null, "payment_method": { "type": "CARD", "brand": "VISA", "last_four": "1234" }, "cancel_instructions": "You can cancel your subscription at any time from your account settings.", "is_paid": true, "is_family_plan": false, "is_cancellable": true, "price": { "total": "12.99", "currency": "USD" } } ], "next_cursor": "eyJpZCI6MjI3ODEsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0", "limit": 100 } }, "FilterByMerchant": { "summary": "Example filtered-by-merchant response.", "value": { "subscriptions": [ { "id": "13da3c28-a068-4642-9ce2-b730cfda5f5f", "external_id": "a9x7bq2lmw5p", "name": "Disney+, Hulu Bundle Premium", "description": "Ad-free streaming with Disney+ and Hulu", "merchant": { "id": 18, "name": "Hulu", "category": "Streaming", "logo": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png", "parent_merchant": null }, "status": "ACTIVE", "billing_cycle": "RECURRING_MONTHLY", "next_billing_date": "2026-02-10", "last_billing_date": "2026-01-10", "start_date": "2025-06-15", "expiration_date": null, "payment_method": { "type": "CARD", "brand": "VISA", "last_four": "1234" }, "cancel_instructions": "You can cancel your subscription at any time from your account settings. Your cancellation will take effect at the end of your current billing period.", "is_paid": true, "is_family_plan": false, "is_cancellable": true, "price": { "total": "11.99", "currency": "USD" } } ], "next_cursor": null, "limit": 100 } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UserNotFound": { "summary": "User not found", "value": { "error_type": "USER_ERROR", "error_code": "USER_NOT_FOUND", "error_message": "The user was not found. Please check the ID provided." } }, "MerchantAccountNotFound": { "summary": "Merchant account not found", "value": { "error_type": "MERCHANT_ACCOUNT_ERROR", "error_code": "MERCHANT_ACCOUNT_NOT_FOUND", "error_message": "The merchant account was not found. Please check the merchant_id provided." } }, "ExternalUserIdRequired": { "summary": "external_user_id is required", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The external_user_id field is required." } }, "LimitNotInteger": { "summary": "limit must be an integer", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The limit must be an integer." } }, "LimitMoreThanOne": { "summary": "The limit must be at least 1.", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The limit must be at least 1." } }, "LimitLessThanHundred": { "summary": "The limit may not be greater than 100.", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The limit may not be greater than 100." } }, "InvalidCursorFormat": { "summary": "Cursor format is invalid", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The provided cursor is invalid." } }, "InvalidStatus": { "summary": "status is invalid", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The selected status is invalid." } }, "InvalidIsPaid": { "summary": "is_paid must be a boolean", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The is_paid field must be true or false." } }, "InvalidIsCancellable": { "summary": "is_cancellable must be a boolean", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The is_cancellable field must be true or false." } } } } } }, "401": { "description": "Unauthorized request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthFailed": { "summary": "Auth failed", "value": { "error_type": "INVALID_INPUT", "error_code": "INVALID_API_KEYS", "error_message": "Invalid client_id or secret provided." } } } } } }, "403": { "description": "Forbidden request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NoAccess": { "summary": "No access", "value": { "error_type": "INVALID_REQUEST", "error_code": "NO_ACCESS", "error_message": "Please contact Knot for access to this endpoint." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InternalServerError": { "summary": "Unexpected server error", "value": { "message": "Server Error" } } } } } } } } }, "/subscriptions/{id}": { "get": { "operationId": "subscription_get_by_id", "summary": "Get Subscription By ID", "description": "Get a specific subscription by ID.", "x-mint": { "mcp": { "enabled": true, "name": "get-subscription-by-id", "description": "Get a specific subscription by ID." } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "13da3c28-a068-4642-9ce2-b730cfda5f5f" }, "description": "Unique identifier for a subscription." } ], "responses": { "200": { "description": "Successful request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" }, "examples": { "Hulu": { "summary": "Hulu", "value": { "id": "13da3c28-a068-4642-9ce2-b730cfda5f5f", "external_id": "a9x7bq2lmw5p", "name": "Disney+, Hulu Bundle Premium", "description": "Ad-free streaming with Disney+ and Hulu", "merchant": { "id": 18, "name": "Hulu", "category": "Streaming", "logo": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png", "parent_merchant": null }, "status": "ACTIVE", "billing_cycle": "RECURRING_MONTHLY", "next_billing_date": "2026-02-10", "last_billing_date": "2026-01-10", "start_date": "2025-06-15", "expiration_date": null, "payment_method": { "type": "CARD", "brand": "VISA", "last_four": "1234" }, "cancel_instructions": "You can cancel your subscription at any time from your account settings. Your cancellation will take effect at the end of your current billing period. You'll continue to have access until May 30, 2026. You will not be charged again unless you restart your subscription.", "is_paid": true, "is_family_plan": false, "is_cancellable": true, "price": { "total": "11.99", "currency": "USD" } } }, "Spotify": { "summary": "Spotify", "value": { "id": "7a2e9f14-b532-48d1-ae73-c9f2d8e61b4a", "external_id": "sp_sub_8x2k4m", "name": "Premium Individual", "description": "Ad-free music streaming for one account", "merchant": { "id": 13, "name": "Spotify", "category": "Streaming", "logo": "https://knot.imgix.net/merchants/spotify-logo.png", "parent_merchant": null }, "status": "ACTIVE", "billing_cycle": "RECURRING_MONTHLY", "next_billing_date": "2026-03-10", "last_billing_date": "2026-02-10", "start_date": "2024-09-01", "expiration_date": null, "payment_method": { "type": "CARD", "brand": "VISA", "last_four": "1234" }, "cancel_instructions": "You can cancel your subscription at any time from your account settings. Your cancellation will take effect at the end of your current billing period. You'll continue to have access until May 30, 2026. You will not be charged again unless you restart your subscription.", "is_paid": true, "is_family_plan": false, "is_cancellable": true, "price": { "total": "12.99", "currency": "USD" } } }, "YouTubeTV": { "summary": "YouTube TV", "value": { "id": "b4c1e8a3-9d27-4f6e-a1b3-8c5d2e7f9a01", "external_id": "a9x7bq2lmw5p", "name": "Google Cloud Storage, 100GB", "description": "100 GB of cloud storage shared across Google Drive, Gmail, and Google Photos", "merchant": { "id": 25, "name": "YouTube TV", "category": "Streaming", "logo": "https://knot.imgix.net/merchants/youtube-tv-logo.png", "parent_merchant": { "id": 129, "name": "Google", "category": "Online shopping", "logo": "https://knot.imgix.net/merchants/google-logo.png" } }, "status": "ACTIVE", "billing_cycle": "RECURRING_MONTHLY", "next_billing_date": "2026-07-01", "last_billing_date": "2026-06-01", "start_date": "2025-03-15", "expiration_date": null, "payment_method": { "type": "CARD", "brand": "VISA", "last_four": "1234" }, "cancel_instructions": null, "is_paid": true, "is_family_plan": false, "is_cancellable": true, "price": { "total": "9.99", "currency": "USD" } } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "SubscriptionNotFound": { "summary": "Subscription not found", "value": { "error_type": "SUBSCRIPTION_ERROR", "error_code": "SUBSCRIPTION_NOT_FOUND", "error_message": "The subscription was not found. Please check the ID provided." } }, "NoAccess": { "summary": "No access", "value": { "error_type": "INVALID_REQUEST", "error_code": "NO_ACCESS", "error_message": "Please contact Knot for access to this endpoint." } } } } } }, "401": { "description": "Unauthorized request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthFailed": { "summary": "Auth failed", "value": { "error_type": "INVALID_INPUT", "error_code": "INVALID_API_KEYS", "error_message": "Invalid client_id or secret provided." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InternalServerError": { "summary": "Unexpected server error", "value": { "message": "Server Error" } } } } } } } } }, "/subscriptions/{id}/cancel": { "post": { "operationId": "subscription_cancel", "summary": "Cancel Subscription By ID", "description": "Cancel a subscription or bill associated with a linked merchant account using the subscription ID.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "ka8sdf0asdfm10as0a0sdfja7ssa8" }, "description": "The subscription ID from the subscription object." } ], "requestBody": { "description": "Optional parameters for cancelling a subscription or bill.", "content": { "application/json": { "schema": { "type": "object", "properties": { "simulate": { "description": "Simulate a failure in the development environment and trigger the `CANCELLATION_FAILED` webhook.", "oneOf": [ { "type": "string", "enum": [ "failed" ], "description": "The cancellation attempt fails after request validation.", "example": "failed" } ] } } }, "examples": { "Success": { "summary": "Success", "value": {} }, "Failure": { "summary": "Simulate failure", "value": { "simulate": "failed" } } } } } }, "responses": { "202": { "description": "Cancellation request accepted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Success" } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "SubscriptionIdRequired": { "summary": "Subscription ID is required", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The subscription ID field is required." } }, "SubscriptionNotFound": { "summary": "Subscription not found", "value": { "error_type": "SUBSCRIPTION_ERROR", "error_code": "SUBSCRIPTION_NOT_FOUND", "error_message": "The subscription was not found. Please check the ID provided." } }, "MerchantUnavailable": { "summary": "Merchant unavailable", "value": { "error_type": "MERCHANT_ERROR", "error_code": "MERCHANT_UNAVAILABLE", "error_message": "The merchant is unavailable. Please check the merchant_id provided." } }, "MerchantAccountDisconnected": { "summary": "Merchant account disconnected", "value": { "error_type": "MERCHANT_ACCOUNT_ERROR", "error_code": "MERCHANT_ACCOUNT_DISCONNECTED", "error_message": "The merchant account is disconnected. Please check the merchant_id provided." } }, "OngoingOperation": { "summary": "Ongoing operation", "value": { "error_type": "MERCHANT_ACCOUNT_ERROR", "error_code": "ONGOING_OPERATION", "error_message": "An existing operation is in progress." } } } } } }, "401": { "description": "Unauthorized request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthFailed": { "summary": "Auth failed", "value": { "error_type": "INVALID_INPUT", "error_code": "INVALID_API_KEYS", "error_message": "Invalid client_id or secret provided." } } } } } }, "403": { "description": "Forbidden request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NoAccess": { "summary": "No access", "value": { "error_type": "INVALID_REQUEST", "error_code": "NO_ACCESS", "error_message": "Please contact Knot for access to this endpoint." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InternalServerError": { "summary": "Unexpected server error", "value": { "message": "Server Error" } } } } } } } } }, "/subscriptions/cancel": { "post": { "operationId": "subscription_cancel_by_account", "summary": "Cancel Subscription By Account", "description": "Cancel a subscription or bill associated with a linked merchant account", "requestBody": { "description": "The input parameters required for cancelling a subscription or bill on a merchant account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "external_user_id": { "type": "string", "description": "Your unique identifier for the user.", "example": "abc" }, "merchant_id": { "type": "integer", "description": "The unique ID of the merchant whose linked account the subscription is cancelled on.", "example": 18 }, "simulate": { "type": "string", "description": "Simulate a failed cancellation or an error response in the development environment.", "example": "failed", "oneOf": [ { "const": "failed", "title": "failed", "description": "The cancellation attempt fails and triggers the `CANCELLATION_FAILED` webhook. Requires exactly one cancellable subscription on the merchant account; otherwise the matching `CANCELLABLE_SUBSCRIPTION_NOT_FOUND` or `MULTIPLE_CANCELLABLE_SUBSCRIPTIONS_FOUND` error is returned instead." }, { "const": "no_cancellable_subscriptions", "title": "no_cancellable_subscriptions", "description": "The request fails with a `CANCELLABLE_SUBSCRIPTION_NOT_FOUND` error, as if the merchant account had no cancellable subscriptions." }, { "const": "multiple_subscriptions", "title": "multiple_subscriptions", "description": "The request fails with a `MULTIPLE_CANCELLABLE_SUBSCRIPTIONS_FOUND` error listing the cancellable subscriptions on the merchant account." } ] } }, "required": [ "external_user_id", "merchant_id" ] }, "examples": { "Success": { "summary": "Success", "value": { "external_user_id": "abc", "merchant_id": 18 } }, "Failure": { "summary": "Simulate failure", "value": { "external_user_id": "abc", "merchant_id": 18, "simulate": "failed" } }, "NoCancellableSubscriptions": { "summary": "Simulate no cancellable subscriptions", "value": { "external_user_id": "abc", "merchant_id": 18, "simulate": "no_cancellable_subscriptions" } }, "MultipleCancellableSubscriptions": { "summary": "Simulate multiple cancellable subscriptions", "value": { "external_user_id": "abc", "merchant_id": 18, "simulate": "multiple_subscriptions" } } } } } }, "responses": { "202": { "description": "Cancellation request accepted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Success" } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "data": { "type": "object", "description": "Additional context returned with the `MULTIPLE_CANCELLABLE_SUBSCRIPTIONS_FOUND` error.", "properties": { "subscriptions": { "type": "array", "description": "The cancellable subscriptions found on the merchant account. Cancel one of them with [Cancel Subscription By ID](/api-reference/products/subscriptions/cancel).", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the subscription.", "example": "13da3c28-a068-4642-9ce2-b730cfda5f5f" }, "name": { "type": "string", "description": "Human-readable subscription name as displayed by the merchant.", "example": "Hulu (With Ads)" }, "description": { "type": [ "string", "null" ], "description": "Description of the subscription plan.", "example": "Stream thousands of shows and movies, with ads." }, "price": { "anyOf": [ { "$ref": "#/components/schemas/SubscriptionPrice" }, { "type": "null" } ] } } } } } } } } ] }, "examples": { "ExternalUserIdRequired": { "summary": "external_user_id is required", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The external_user_id field is required." } }, "MerchantIdRequired": { "summary": "merchant_id is required", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The merchant_id field is required." } }, "MerchantIdInvalid": { "summary": "merchant_id is invalid", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The selected merchant_id is invalid." } }, "UserNotFound": { "summary": "User not found", "value": { "error_type": "USER_ERROR", "error_code": "USER_NOT_FOUND", "error_message": "The user was not found. Please check the ID provided." } }, "MerchantAccountNotFound": { "summary": "Merchant account not found", "value": { "error_type": "MERCHANT_ACCOUNT_ERROR", "error_code": "MERCHANT_ACCOUNT_NOT_FOUND", "error_message": "The merchant account was not found. Please check the merchant_id provided." } }, "CancellableSubscriptionNotFound": { "summary": "No cancellable subscriptions found", "value": { "error_type": "SUBSCRIPTION_ERROR", "error_code": "CANCELLABLE_SUBSCRIPTION_NOT_FOUND", "error_message": "There are no cancellable subscriptions found." } }, "MultipleCancellableSubscriptionsFound": { "summary": "Multiple cancellable subscriptions found", "value": { "error_type": "SUBSCRIPTION_ERROR", "error_code": "MULTIPLE_CANCELLABLE_SUBSCRIPTIONS_FOUND", "error_message": "There are multiple cancellable subscriptions found.", "data": { "subscriptions": [ { "id": "13da3c28-a068-4642-9ce2-b730cfda5f5f", "name": "Hulu (With Ads)", "description": "Stream thousands of shows and movies, with ads.", "price": { "total": "9.99", "currency": "USD" } }, { "id": "7a2e9f14-b532-48d1-ae73-c9f2d8e61b4a", "name": "HBO Max Add-on", "description": "Add HBO Max to your Hulu plan, ad-free.", "price": { "total": "16.99", "currency": "USD" } } ] } } }, "MerchantUnavailable": { "summary": "Merchant unavailable", "value": { "error_type": "MERCHANT_ERROR", "error_code": "MERCHANT_UNAVAILABLE", "error_message": "The merchant is unavailable. Please check the merchant_id provided." } }, "MerchantAccountDisconnected": { "summary": "Merchant account disconnected", "value": { "error_type": "MERCHANT_ACCOUNT_ERROR", "error_code": "MERCHANT_ACCOUNT_DISCONNECTED", "error_message": "The merchant account is disconnected. Please check the merchant_id provided." } }, "OngoingOperation": { "summary": "Ongoing operation", "value": { "error_type": "MERCHANT_ACCOUNT_ERROR", "error_code": "ONGOING_OPERATION", "error_message": "An existing operation is in progress." } } } } } }, "401": { "description": "Unauthorized request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthFailed": { "summary": "Auth failed", "value": { "error_type": "INVALID_INPUT", "error_code": "INVALID_API_KEYS", "error_message": "Invalid client_id or secret provided." } } } } } }, "403": { "description": "Forbidden request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NoAccess": { "summary": "No access", "value": { "error_type": "INVALID_REQUEST", "error_code": "NO_ACCESS", "error_message": "Please contact Knot for access to this endpoint." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InternalServerError": { "summary": "Unexpected server error", "value": { "message": "Server Error" } } } } } } } } }, "/subscriptions/refresh": { "post": { "operationId": "subscription_refresh", "summary": "Refresh Subscriptions", "description": "Initiate an on-demand refresh of subscription data for a user's merchant account.", "requestBody": { "description": "The input parameters required for refreshing subscriptions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "merchant_id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 18 }, "external_user_id": { "type": "string", "description": "Your unique identifier for the user.", "example": "abc" } }, "required": [ "merchant_id", "external_user_id" ] } } } }, "responses": { "202": { "description": "Refresh request accepted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Success" } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ExternalUserIdRequired": { "summary": "external_user_id field is required", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The external_user_id field is required." } }, "MerchantIdRequired": { "summary": "merchant_id field is required", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The merchant_id field is required." } }, "MerchantIdInvalid": { "summary": "merchant_id field is invalid", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The selected merchant id is invalid." } }, "UserNotFound": { "summary": "User not found", "value": { "error_type": "USER_ERROR", "error_code": "USER_NOT_FOUND", "error_message": "The user was not found. Please check the ID provided." } }, "MerchantAccountNotFound": { "summary": "Merchant account not found", "value": { "error_type": "MERCHANT_ACCOUNT_ERROR", "error_code": "MERCHANT_ACCOUNT_NOT_FOUND", "error_message": "The merchant account was not found. Please check the merchant_id provided." } }, "MerchantAccountDisconnected": { "summary": "Merchant account is disconnected", "value": { "error_type": "MERCHANT_ACCOUNT_ERROR", "error_code": "MERCHANT_ACCOUNT_DISCONNECTED", "error_message": "The merchant account is disconnected. Please check the merchant_id provided." } }, "MerchantUnavailable": { "summary": "Merchant is unavailable", "value": { "error_type": "MERCHANT_ERROR", "error_code": "MERCHANT_UNAVAILABLE", "error_message": "The merchant is unavailable. Please check the merchant_id provided." } }, "OngoingOperation": { "summary": "An existing operation is in progress", "value": { "error_type": "MERCHANT_ACCOUNT_ERROR", "error_code": "ONGOING_OPERATION", "error_message": "An existing operation is in progress." } } } } } }, "401": { "description": "Unauthorized request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthFailed": { "summary": "Auth failed", "value": { "error_type": "INVALID_INPUT", "error_code": "INVALID_API_KEYS", "error_message": "Invalid client_id or secret provided." } } } } } }, "403": { "description": "Forbidden request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NoAccess": { "summary": "No access", "value": { "error_type": "INVALID_REQUEST", "error_code": "NO_ACCESS", "error_message": "Please contact Knot for access to this endpoint." } } } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until the rate limit resets. The limit is 1 request per 24 hours per linked merchant account.", "schema": { "type": "integer", "example": 14400 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RateLimitExceeded": { "summary": "Rate limit exceeded", "value": { "error_type": "RATE_LIMIT_ERROR", "error_code": "TOO_MANY_REQUESTS", "error_message": "Rate limit exceeded. Please retry after the time indicated in the Retry-After header." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InternalServerError": { "summary": "Unexpected server error", "value": { "message": "Server Error" } } } } } } } } }, "/cart": { "post": { "operationId": "cart_sync", "summary": "Sync Cart", "description": "Add one or more products to a user's merchant cart.", "x-mint": { "mcp": { "enabled": true, "name": "sync-cart", "description": "Add one or more products to a user's merchant cart." } }, "requestBody": { "description": "The input parameters required for adding products to a user's merchant cart.", "content": { "application/json": { "schema": { "type": "object", "properties": { "external_user_id": { "type": "string", "description": "Your unique identifier for the user.", "example": "abc123" }, "merchant_id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 44 }, "products": { "type": "array", "description": "List of products to add to the cart.", "items": { "type": "object", "properties": { "external_id": { "type": "string", "description": "Merchant's identifier for the product. Format varies by merchant.", "example": "3324893784" }, "fulfillment": { "type": "object", "description": "", "properties": { "id": { "type": "string", "description": "Unique identifier for the fulfillment option sent in [`SYNC_CART_SUCCEEDED`](https://docs.knotapi.com/shopping/webhook-events#sync-cart-succeeded).", "example": "5cfbe095d0cb9e597e316170d6ee9a6c667bddcde4a999222d2cc2b5bbfef7cf" } }, "required": [ "id" ] } }, "required": [ "external_id" ] } }, "delivery_location": { "type": "object", "description": "", "properties": { "address": { "type": "object", "description": "", "properties": { "line1": { "type": "string", "description": "First line of the delivery address.", "example": "123 Main St", "maxLength": 46 }, "line2": { "type": "string", "description": "Second line of the delivery address.", "example": "Floor 4", "maxLength": 46 }, "city": { "type": "string", "description": "City portion of the delivery address.", "example": "Los Angeles" }, "region": { "type": "string", "description": "Region portion of the delivery address, usually a state abbreviation. Must be an ISO 3166-2 sub-division code.", "example": "CA" }, "postal_code": { "type": "string", "description": "Postal code of the delivery address.", "example": "94105", "minLength": 5, "maxLength": 10 }, "country": { "type": "string", "description": "Country portion of the delivery address. Must be an ISO 3166-1 alpha-2 code.", "example": "US" } }, "required": [ "line1", "city", "region", "postal_code", "country" ] }, "first_name": { "type": "string", "maxLength": 255, "description": "First name for the delivery address.", "example": "Ada" }, "last_name": { "type": "string", "maxLength": 255, "description": "Last name for the delivery address.", "example": "Lovelace" }, "phone_number": { "type": "string", "description": "Phone number for the delivery address in E.164 format.", "example": "+11234567890" }, "set_as_default": { "type": "boolean", "description": "Whether the delivery address should be saved as the user's default in the merchant account.", "example": true, "default": false } }, "required": [ "address", "first_name", "last_name", "phone_number", "set_as_default" ] }, "simulate": { "description": "Simulate a failure in the development environment.", "oneOf": [ { "type": "string", "enum": [ "failed" ], "description": "The sync cart attempt fails.", "example": "failed" } ] } }, "required": [ "external_user_id", "merchant_id", "products" ] }, "examples": { "Success": { "summary": "Success", "value": { "external_user_id": "abc123", "merchant_id": 44, "products": [ { "external_id": "3324893784" } ] } }, "Failure": { "summary": "Failure", "value": { "external_user_id": "abc123", "merchant_id": 44, "products": [ { "external_id": "3324893784" } ], "simulate": "failed" } } } } } }, "responses": { "202": { "description": "Successful request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message.", "example": "Success" } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UserNotFound": { "summary": "User was not found", "value": { "error_type": "USER_ERROR", "error_code": "USER_NOT_FOUND", "error_message": "The user was not found. Please check the ID provided." } }, "MerchantAccountNotFound": { "summary": "Merchant account was not found", "value": { "error_type": "MERCHANT_ACCOUNT_ERROR", "error_code": "MERCHANT_ACCOUNT_NOT_FOUND", "error_message": "The merchant account was not found. Please check the merchant_id provided." } }, "MerchantAccountDisconnected": { "summary": "Merchant account is disconnected", "value": { "error_type": "MERCHANT_ACCOUNT_ERROR", "error_code": "MERCHANT_ACCOUNT_DISCONNECTED", "error_message": "The merchant account is disconnected. Please check the merchant_id provided." } }, "MerchantNotFound": { "summary": "Merchant was not found", "value": { "error_type": "MERCHANT_ERROR", "error_code": "MERCHANT_NOT_FOUND", "error_message": "The merchant was not found. Please check the merchant_id provided." } }, "MerchantUnavailable": { "summary": "Merchant is not available", "value": { "error_type": "MERCHANT_ERROR", "error_code": "MERCHANT_UNAVAILABLE", "error_message": "The merchant is unavailable. Please check the merchant_id provided." } }, "FulfillmentNotFound": { "summary": "Fulfillment was not found", "value": { "error_type": "CART_ERROR", "error_code": "FULFILLMENT_NOT_FOUND", "error_message": "The fulfillment option was not found. Please check the fulfillment.id provided." } }, "MerchantIdRequired": { "summary": "merchant_id field is required", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The merchant_id field is required." } }, "ExternalUserIdRequired": { "summary": "external_user_id is required", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The external_user_id field is required." } }, "ProductExternalIdRequired": { "summary": "product.external_id is required", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The product.external_id field is required." } }, "DeliveryLocationFieldRequired": { "summary": "Delivery location field required", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The delivery_location.phone_number field is required." } }, "InvalidDeliveryLocationField": { "summary": "Invalid delivery_location field", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The delivery_location.first_name must not be greater than 255 characters." } }, "OngoingOperation": { "summary": "There is an existing operation", "value": { "error_type": "MERCHANT_ACCOUNT_ERROR", "error_code": "ONGOING_OPERATION", "error_message": "An existing operation is in progress." } } } } } }, "401": { "description": "Unauthorized request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthFailed": { "summary": "Auth failed", "value": { "error_type": "INVALID_INPUT", "error_code": "INVALID_API_KEYS", "error_message": "Invalid client_id or secret provided." } } } } } }, "403": { "description": "Forbidden request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NoAccess": { "summary": "No access", "value": { "error_type": "INVALID_REQUEST", "error_code": "NO_ACCESS", "error_message": "Please contact Knot for access to this endpoint." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InternalServerError": { "summary": "Unexpected server error", "value": { "message": "Server Error" } } } } } } } } }, "/cart/checkout": { "post": { "operationId": "checkout", "summary": "Checkout", "description": "Checkout a user's merchant cart.", "x-mint": { "mcp": { "enabled": true, "name": "checkout", "description": "Checkout a user's merchant cart." } }, "requestBody": { "description": "The input parameters required to checkout a cart.", "content": { "application/json": { "schema": { "type": "object", "properties": { "external_user_id": { "type": "string", "description": "Your unique identifier for the user.", "example": "abc123" }, "merchant_id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 456 }, "payment_method": { "type": "object", "properties": { "id": { "type": "string", "description": "Your unique identifier for the payment method.", "example": "81n9al10a0ayn13" }, "jwe": { "type": "string", "description": "JWE value of the `user` and `card` objects. Created using the public key retrieved from [Retrieve JWK](https://docs.knotapi.com/api-reference/products/card-switcher/retrieve-jwk)", "example": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLC..." }, "is_single_use": { "type": "boolean", "description": "Whether the payment method is single-use only.", "example": true, "default": false } }, "required": [ "id", "jwe", "is_single_use" ] }, "simulate": { "description": "Simulate a failure in the development environment.", "oneOf": [ { "type": "string", "enum": [ "failed" ], "description": "The checkout attempt fails.", "example": "failed" } ] } }, "required": [ "external_user_id", "merchant_id" ] } } } }, "responses": { "202": { "description": "Successful request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message.", "example": "Success" } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UserNotFound": { "summary": "User was not found", "value": { "error_type": "USER_ERROR", "error_code": "USER_NOT_FOUND", "error_message": "The user was not found. Please check the ID provided." } }, "MerchantAccountNotFound": { "summary": "Merchant account was not found", "value": { "error_type": "MERCHANT_ACCOUNT_ERROR", "error_code": "MERCHANT_ACCOUNT_NOT_FOUND", "error_message": "The merchant account was not found. Please check the merchant_id provided." } }, "CartNotFound": { "summary": "Cart was not found", "value": { "error_type": "CART_ERROR", "error_code": "CART_NOT_FOUND", "error_message": "The cart was not found. Please ensure you synced the cart recently." } }, "MerchantAccountDisconnected": { "summary": "Merchant account is disconnected", "value": { "error_type": "MERCHANT_ACCOUNT_ERROR", "error_code": "MERCHANT_ACCOUNT_DISCONNECTED", "error_message": "The merchant account is disconnected. Please check the merchant_id provided." } }, "MerchantUnavailable": { "summary": "Merchant is not available", "value": { "error_type": "MERCHANT_ERROR", "error_code": "MERCHANT_UNAVAILABLE", "error_message": "The merchant is unavailable. Please check the merchant_id provided." } }, "MerchantIdRequired": { "summary": "merchant_id field is required", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The merchant_id field is required." } }, "ExternalUserIdRequired": { "summary": "external_user_id is required", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The external user id field is required." } }, "PaymentMethodFieldRequired": { "summary": "ID is missing in payment_method", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The payment_method.id field is required when payment_method is provided." } }, "UserFieldRequired": { "summary": "User object field required", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_JWE", "error_message": "The user.phone number is required." } }, "CardNumberNotNumeric": { "summary": "Card number not numeric.", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_JWE", "error_message": "The card.number must be numeric." } }, "CardNumberTooLong": { "summary": "Card number too long.", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_JWE", "error_message": "The card.number is too long for card type." } }, "CardNumberTooShort": { "summary": "Card number too short.", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_JWE", "error_message": "The card.number is too short for card type." } }, "CardNumberInvalid": { "summary": "Card number invalid.", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_JWE", "error_message": "The card.number is invalid and does not pass the Luhn check." } }, "CVVNotNumeric": { "summary": "CVV not numeric", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_JWE", "error_message": "The card.cvv must be numeric." } }, "CVVTooLong": { "summary": "CVV to long.", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_JWE", "error_message": "The card.cvv is too long for card type." } }, "CVVTooShort": { "summary": "CVV to short.", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_JWE", "error_message": "The card.cvv is too short for card type." } }, "CVVRequired": { "summary": "CVV is required.", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_JWE", "error_message": "The card.cvv is required." } }, "CardExpirationInvalid": { "summary": "Card expiration invalid.", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_JWE", "error_message": "The card.expiration should be in MM/YYYY or MM/YY format." } }, "CardExpired": { "summary": "Card expired.", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_JWE", "error_message": "The card is expired." } }, "InvalidJWE": { "summary": "JWE invalid.", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_JWE", "error_message": "The jwe is invalid." } }, "OngoingOperation": { "summary": "There is an existing operation", "value": { "error_type": "MERCHANT_ACCOUNT_ERROR", "error_code": "ONGOING_OPERATION", "error_message": "An existing operation is in progress." } } } } } }, "401": { "description": "Unauthorized request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthFailed": { "summary": "Auth failed", "value": { "error_type": "INVALID_INPUT", "error_code": "INVALID_API_KEYS", "error_message": "Invalid client_id or secret provided." } } } } } }, "403": { "description": "Forbidden request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NoAccess": { "summary": "No access", "value": { "error_type": "INVALID_REQUEST", "error_code": "NO_ACCESS", "error_message": "Please contact Knot for access to this endpoint." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InternalServerError": { "summary": "Unexpected server error", "value": { "message": "Server Error" } } } } } } } } }, "/session/create": { "post": { "operationId": "session_create", "summary": "Create Session", "description": "Create a session and use it to initialize the SDK.", "x-mint": { "mcp": { "enabled": true, "name": "create-session", "description": "Create a session and use it to initialize the SDK." } }, "requestBody": { "description": "The input parameters required for creating a session.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "card_switcher", "transaction_link", "link", "vault" ], "description": "Product to associate the session with.", "example": "card_switcher" }, "external_user_id": { "type": "string", "description": "Your unique identifier for the user.", "example": "123abc" }, "card_id": { "type": [ "string", "null" ], "description": "Your unique identifier for a specific card. **Required when `type = card_switcher`.** Optionally accepted when `type = vault`.", "example": "81n9al10a0ayn13", "default": null }, "email": { "type": [ "string", "null" ], "description": "User's email address. When provided, Knot will automatically detect the user's online merchant accounts to personalize the experience in the SDK.", "example": "ada.lovelace@gmail.com", "default": null }, "phone_number": { "type": [ "string", "null" ], "description": "User's phone number in E.164 format. When provided, Knot will automatically detect the user's online merchant accounts to personalize the experience in the SDK.", "example": "+11234567890", "default": null }, "processor_token": { "type": [ "string", "null" ], "description": "Plaid processor_token if using transaction data from Plaid to detect merchants.", "default": null }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string", "maxLength": 500 }, "maxProperties": 10, "description": "Optional key-value pairs to include in webhook payloads. Maximum 10 keys, 500 characters per value.", "example": { "reference_token": "abc123", "trace_id": "def456" }, "default": null } }, "required": [ "type", "external_user_id" ] }, "examples": { "CardSwitcher": { "summary": "Card Switcher", "value": { "type": "card_switcher", "external_user_id": "abc123", "card_id": "81n9al10a0ayn13", "merchant_id": 45, "email": "ada.lovelace@gmail.com", "phone_number": "+11234567890" } }, "TransactionLink": { "summary": "Transaction Link", "value": { "type": "transaction_link", "external_user_id": "abc123", "merchant_id": 45 } }, "Link": { "summary": "Link", "value": { "type": "link", "external_user_id": "abc123", "merchant_id": 45 } }, "Vault": { "summary": "Vault", "value": { "type": "vault", "external_user_id": "abc123", "merchant_id": 45 } } } } } }, "responses": { "200": { "description": "Successful request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "type": "string", "description": "A session.", "example": "915efe72-5136-4652-z91q-d9d48003c102" } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CardIdRequired": { "summary": "card_id is missing for type: card_switcher", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The card_id field is required when type = card_switcher." } }, "ExternalUserIdRequired": { "summary": "external_user_id is missing", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The external user id field is required." } }, "TypeRequired": { "summary": "type is missing", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The type field is required." } }, "InvalidPhoneNumber": { "summary": "Phone number is invalid", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The phone number format is invalid." } }, "InvalidEmail": { "summary": "Email is invalid", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The email must be a valid email address." } }, "InvalidProcessorToken": { "summary": "Processor token is invalid", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The processor token must be a string." } }, "InvalidCardBlocked": { "summary": "card.blocked is invalid", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The card.blocked field must be true or false." } } } } } }, "401": { "description": "Unauthorized request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthFailed": { "summary": "Auth failed", "value": { "error_type": "INVALID_INPUT", "error_code": "INVALID_API_KEYS", "error_message": "Invalid client_id or secret provided." } } } } } }, "403": { "description": "Forbidden request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NoAccess": { "summary": "No access", "value": { "error_type": "INVALID_REQUEST", "error_code": "NO_ACCESS", "error_message": "The type is not enabled. Please contact Knot for access to this endpoint." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InternalServerError": { "summary": "Unexpected server error", "value": { "message": "Server Error" } } } } } } } } }, "/session/extend": { "post": { "operationId": "session_extend", "summary": "Extend Session", "description": "Extend a session.", "x-mint": { "mcp": { "enabled": true, "name": "extend-session", "description": "Extend a session." } }, "requestBody": { "description": "The input parameters required for extending a session.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "description": "Specific session.", "example": "915efe72-5136-4652-z91q-d9d48003c102" } }, "required": [ "session_id" ] } } } }, "responses": { "200": { "description": "Successful request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "type": "string", "description": "The extended session.", "example": "915efe72-5136-4652-z91q-d9d48003c102" } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "SessionNotFound": { "summary": "Session was not found", "value": { "error_type": "SESSION_ERROR", "error_code": "SESSION_NOT_FOUND", "error_message": "The session was not found. Please check the ID provided." } }, "SessionIdRequired": { "summary": "session_id must be provided", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The session id field is required." } }, "InvalidSession": { "summary": "Session must be a string", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The session id field must be a string." } }, "ExtensionNotSupported": { "summary": "Session does not support extending", "value": { "error_type": "SESSION_ERROR", "error_code": "EXTEND_NOT_SUPPORTED", "error_message": "This session does not support extending its expiration." } } } } } }, "401": { "description": "Unauthorized request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthFailed": { "summary": "Auth failed", "value": { "error_type": "INVALID_INPUT", "error_code": "INVALID_API_KEYS", "error_message": "Invalid client_id or secret provided." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InternalServerError": { "summary": "Unexpected server error", "value": { "message": "Server Error" } } } } } } } } }, "/jwe/key": { "get": { "operationId": "jwe_get_public_key", "summary": "Retrieve JWK", "description": "Retrieve a public key in JWK format.", "x-mint": { "mcp": { "enabled": true, "name": "retrieve-jwk", "description": "Retrieve a public key in JWK format." } }, "responses": { "200": { "description": "Successful request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "alg": { "type": "string", "description": "Algorithm intended for use with the key.", "example": "RSA-OAEP-256" }, "e": { "type": "string", "description": "Exponent value for the RSA public key in Base64 URL format.", "example": "..." }, "key_ops": { "type": "array", "items": { "type": "string" }, "description": "Operation permitted for the key.", "example": [ "encrypt" ] }, "kid": { "type": "string", "description": "Unique identifier for the kid.", "example": "..." }, "kty": { "type": "string", "description": "Type of key.", "example": "RSA" }, "n": { "type": "string", "description": "Modulus value for the RSA public key in Base64 URL format.", "example": "..." }, "use": { "type": "string", "description": "Intended use of the key.", "example": "enc" } } } } } }, "401": { "description": "Unauthorized request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthFailed": { "summary": "Auth failed", "value": { "error_type": "INVALID_INPUT", "error_code": "INVALID_API_KEYS", "error_message": "Invalid client_id or secret provided." } } } } } } } } }, "/card": { "post": { "operationId": "card_switch", "summary": "Switch Card JWE", "description": "Switch a card in a user's merchant account.", "x-mint": { "mcp": { "enabled": true, "name": "switch-card", "description": "Switch a card in a user's merchant account." } }, "requestBody": { "description": "The input parameters required for switching a card.", "content": { "application/json": { "schema": { "oneOf": [ { "title": "CardSwitcher", "type": "object", "properties": { "jwe": { "type": "string", "description": "JWE value.", "example": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLC..." }, "task_id": { "type": "string", "description": "`task_id` value provided in the [`AUTHENTICATED`](/link/webhook-events/authenticated) webhook.", "example": "123456" } }, "required": [ "jwe", "task_id" ] }, { "title": "CardUpdater", "type": "object", "properties": { "jwe": { "type": "string", "description": "JWE value.", "example": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLC..." }, "external_user_id": { "type": "string", "description": "Your unique identifier for the user.", "example": "abc123" }, "merchant_id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 456 }, "card_name": { "type": "string", "description": "Name of the card. Learn more [here](/sdk/ios#customerconfiguration).", "example": "My Credit Card" }, "customer_name": { "type": "string", "description": "Name of the customer. Learn more [here](/sdk/ios#customerconfiguration).", "example": "John Doe" } }, "required": [ "jwe", "external_user_id", "merchant_id" ] } ] } } } }, "responses": { "200": { "description": "Successful request. Receiving this response means your request has passed validations, including the `jwe`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message.", "example": "Success" } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UserFieldRequired": { "summary": "User object field required", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_JWE", "error_message": "The user.phone number is required." } }, "CardNumberNotNumeric": { "summary": "Card number not numeric.", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_JWE", "error_message": "The card.number must be numeric." } }, "CardNumberTooLong": { "summary": "Card number too long.", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_JWE", "error_message": "The card.number is too long for card type." } }, "CardNumberTooShort": { "summary": "Card number too short.", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_JWE", "error_message": "The card.number is too short for card type." } }, "CardNumberInvalid": { "summary": "Card number invalid.", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_JWE", "error_message": "The card.number is invalid and does not pass the Luhn check." } }, "CVVNotNumeric": { "summary": "CVV not numeric", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_JWE", "error_message": "The card.cvv must be numeric." } }, "CVVTooLong": { "summary": "CVV to long.", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_JWE", "error_message": "The card.cvv is too long for card type." } }, "CVVTooShort": { "summary": "CVV to short.", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_JWE", "error_message": "The card.cvv is too short for card type." } }, "CVVRequired": { "summary": "CVV is required.", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_JWE", "error_message": "The card.cvv is required." } }, "CardExpirationInvalid": { "summary": "Card expiration invalid.", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_JWE", "error_message": "The card.expiration should be in MM/YYYY or MM/YY format." } }, "CardExpired": { "summary": "Card expired.", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_JWE", "error_message": "The card is expired." } }, "JWEInvalid": { "summary": "JWE invalid.", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_JWE", "error_message": "The jwe is invalid." } }, "OngoingOperation": { "summary": "There is an existing operation", "value": { "error_type": "MERCHANT_ACCOUNT_ERROR", "error_code": "ONGOING_OPERATION", "error_message": "An existing operation is in progress." } } } } } }, "403": { "description": "Forbidden request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NoAccess": { "summary": "No access", "value": { "error_type": "INVALID_REQUEST", "error_code": "NO_ACCESS", "error_message": "Please contact Knot for access to this endpoint." } } } } } } } } }, "/merchant/list": { "post": { "operationId": "merchant_list", "summary": "List Merchants", "description": "Retrieve a list of available merchants.", "x-mint": { "mcp": { "enabled": true, "name": "list-merchants", "description": "Retrieve a list of available merchants." } }, "requestBody": { "description": "The input parameters required for retrieving merchants.", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "card_switcher", "transaction_link", "shopping", "vault", "subscription_manager", "cancel" ], "description": "Product for which the merchants are available.", "example": "card_switcher" }, "platform": { "type": "string", "enum": [ "ios", "android", "web" ], "description": "Platform for which the merchants are available.", "example": "ios" }, "search": { "type": "string", "description": "Name of a specific merchant." }, "external_user_id": { "type": "string", "description": "Your unique identifier for the user. The values of the `status` parameter returned in the response when sending `external_user_id` can be found [here](https://docs.knotapi.com/api-reference/merchants/list-merchants-status).", "deprecated": true } }, "required": [ "type" ] }, "example": { "type": "card_switcher", "platform": "ios" } } } }, "responses": { "200": { "description": "Successful request.", "content": { "application/json": { "schema": { "description": "Array of available merchants.", "oneOf": [ { "title": "With platform in the request", "type": "array", "description": "`Platform` included in the request", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Static unique ID of the merchant (across all environments). This ID remains constant and does not change.", "example": 10 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Uber" }, "category": { "type": "string", "description": "Category of the merchant.", "example": "Transportation" }, "logo": { "type": "string", "description": "Logo URL for the merchant.", "example": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png" }, "popular": { "type": "boolean", "description": "Whether the merchant is a popular merchant amongst your unique audience.", "example": true }, "min_sdk_version": { "type": "string", "description": "The minimum SDK version (on the platform provided in the request) for which the merchant is available.", "example": "2.0.5" } } } }, { "title": "Without platform in the request", "type": "array", "description": "No `platform` in the request", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Static unique ID of the merchant (across all environments). This ID remains constant and does not change.", "example": 10 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Uber" }, "category": { "type": "string", "description": "Category of the merchant.", "example": "Transportation" }, "logo": { "type": "string", "description": "Logo URL for the merchant.", "example": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png" }, "popular": { "type": "boolean", "description": "Whether the merchant is a popular merchant amongst your unique audience.", "example": true } } } } ] }, "examples": { "WithPlatformInRequest": { "summary": "With platform in the request.", "value": [ { "id": 45, "name": "Walmart", "category": "Online shopping", "logo": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png", "popular": true, "min_sdk_version": "1.0.2" } ] }, "WithoutPlatformInRequest": { "summary": "Without platform in the request.", "value": [ { "id": 45, "name": "Walmart", "category": "Online shopping", "logo": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png", "popular": true } ] } } } } }, "401": { "description": "Unauthorized request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthFailed": { "summary": "Auth failed", "value": { "error_type": "INVALID_INPUT", "error_code": "INVALID_API_KEYS", "error_message": "Invalid client_id or secret provided." } } } } } }, "403": { "description": "Forbidden request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NoAccess": { "summary": "No access", "value": { "error_type": "INVALID_REQUEST", "error_code": "NO_ACCESS", "error_message": "The type is not enabled. Please contact Knot for access to this endpoint." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InternalServerError": { "summary": "Unexpected server error", "value": { "message": "Server Error" } } } } } } } } }, "/accounts/unlink": { "post": { "operationId": "account_link", "summary": "Unlink Merchant Account", "description": "Unlink a merchant account from the Knot platform.", "requestBody": { "description": "The input parameters required for unlinking a merchant account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "external_user_id": { "type": "string", "description": "Your unique identifier for the user.", "example": "abc123" }, "merchant_id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 12 } }, "required": [ "external_user_id", "merchant_id" ] } } } }, "responses": { "200": { "description": "Successful request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message.", "example": "Success" } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UserNotFound": { "summary": "User was not found", "value": { "error_type": "USER_ERROR", "error_code": "USER_NOT_FOUND", "error_message": "The user was not found. Please check the ID provided." } }, "MerchantIdRequired": { "summary": "merchant_id field is required", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The merchant_id field is required." } }, "ExternalUserIdRequired": { "summary": "external_user_id not found", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The external user id field is required." } }, "MerchantAccountNotFound": { "summary": "Merchant account was not found", "value": { "error_type": "MERCHANT_ACCOUNT_ERROR", "error_code": "MERCHANT_ACCOUNT_NOT_FOUND", "error_message": "The merchant account was not found. Please check the merchant_id provided." } } } } } }, "401": { "description": "Unauthorized request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthFailed": { "summary": "Auth failed", "value": { "error_type": "INVALID_INPUT", "error_code": "INVALID_API_KEYS", "error_message": "Invalid client_id or secret provided." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InternalServerError": { "summary": "Unexpected server error", "value": { "message": "Server Error" } } } } } } } } }, "/accounts/get": { "get": { "operationId": "accounts_get", "summary": "Get Merchant Accounts", "description": "Get a user's merchant accounts linked to Knot.", "x-mint": { "mcp": { "enabled": true, "name": "get-merchant-accounts", "description": "Get a user's merchant accounts linked to Knot." } }, "parameters": [ { "name": "external_user_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Your unique identifier for the user." }, { "name": "merchant_id", "in": "query", "required": false, "schema": { "type": "integer", "example": 19 }, "description": "Unique identifier for a merchant. Used to return a single merchant account object." }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "card_switcher", "transaction_link", "vault" ], "example": "card_switcher" }, "description": "Product type for which you want to get the status of the most recent login attempt in `lifecycle.status`." } ], "responses": { "200": { "description": "Successful request. If you pass a merchant_id in the request, the response will be a single object, instead of an array.", "content": { "application/json": { "schema": { "oneOf": [ { "title": "Multiple Accounts", "type": "array", "items": { "type": "object", "properties": { "merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Static unique ID of the merchant (across all environments). This ID remains constant and does not change.", "example": 10 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Uber" }, "logo": { "type": "string", "description": "Logo of the merchant.", "example": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png" } } }, "connection": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "connected", "disconnected" ], "description": "Connection status of the merchant account." }, "scopes": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "update_card", "cancel_subscription" ], "description": "Type of scope.", "example": "update_card" } } }, "description": "Array of scopes for the merchant account connection." } } }, "lifecycle": { "type": "object", "properties": { "status": { "type": [ "string", "null" ], "description": "Status of the most recent task login attempt for the type specified in the request.", "enum": [ "authenticating", "credentials_required", "otp_required", "approval_required", "security_questions_required", "zipcode_required", "dob_required", "license_required" ] } } }, "last_user_action": { "type": "object", "properties": { "attempted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the most recent cardswitch attempt." }, "status": { "type": [ "string", "null" ], "description": "Status of the most recent cardswitch attempt.", "enum": [ "succeeded", "failed" ] } } } } } }, { "title": "Single Account", "type": "object", "properties": { "merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Static unique ID of the merchant (across all environments). This ID remains constant and does not change.", "example": 10 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Uber" }, "logo": { "type": "string", "description": "Logo of the merchant.", "example": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png" } } }, "connection": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "connected", "disconnected" ], "description": "Connection status of the merchant account." }, "scopes": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "update_card", "cancel_subscription" ], "description": "Type of scope.", "example": "update_card" } } }, "description": "Array of scopes for the merchant account connection." } } }, "lifecycle": { "type": "object", "properties": { "status": { "type": [ "string", "null" ], "description": "Status of the most recent task login attempt for the type specified in the request.", "enum": [ "authenticating", "credentials_required", "otp_required", "approval_required", "security_questions_required", "zipcode_required", "dob_required", "license_required" ] } } }, "last_user_action": { "type": "object", "properties": { "attempted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the last user action." }, "status": { "type": [ "string", "null" ], "description": "Status of the last user action.", "enum": [ "succeeded", "failed" ] } } } } } ] }, "examples": { "TypeEmpty": { "summary": "Type is empty.", "value": [ { "merchant": { "id": 19, "name": "DoorDash", "logo": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png" }, "connection": { "status": "connected", "scopes": [ { "type": "update_card" } ] }, "lifecycle": { "status": null }, "last_user_action": { "attempted_at": null, "status": null } }, { "merchant": { "id": 40, "name": "Instacart", "logo": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png" }, "connection": { "status": "connected", "scopes": [ { "type": "update_card" } ] }, "lifecycle": { "status": null }, "last_user_action": { "attempted_at": null, "status": null } }, { "merchant": { "id": 12, "name": "Target", "logo": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png" }, "connection": { "status": "disconnected", "scopes": [] }, "lifecycle": { "status": null }, "last_user_action": { "attempted_at": null, "status": null } } ] }, "TypeEmptyWithMerchantId": { "summary": "Type empty with merchant id.", "value": { "merchant": { "id": 19, "name": "DoorDash", "logo": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png" }, "connection": { "status": "connected", "scopes": [ { "type": "update_card" } ] }, "lifecycle": { "status": null }, "last_user_action": { "attempted_at": null, "status": null } } }, "TypeCardSwitcher": { "summary": "Type = card_switcher.", "value": [ { "merchant": { "id": 19, "name": "DoorDash", "logo": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png" }, "connection": { "status": "connected", "scopes": [ { "type": "update_card" } ] }, "lifecycle": { "status": null }, "last_user_action": { "attempted_at": "2024-11-22T14:30:16Z", "status": "succeeded" } }, { "merchant": { "id": 40, "name": "Instacart", "logo": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png" }, "connection": { "status": "disconnected", "scopes": [] }, "lifecycle": { "status": "authenticating" }, "last_user_action": { "attempted_at": null, "status": null } }, { "merchant": { "id": 12, "name": "Target", "logo": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png" }, "connection": { "status": "connected", "scopes": [ { "type": "update_card" } ] }, "lifecycle": { "status": null }, "last_user_action": { "attempted_at": "2025-03-10T16:02:36Z", "status": "succeeded" } } ] }, "TypeTransactionLink": { "summary": "Type = transaction_link.", "value": [ { "merchant": { "id": 19, "name": "DoorDash", "logo": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png" }, "connection": { "status": "connected", "scopes": [ { "type": "update_card" } ] }, "lifecycle": { "status": null }, "last_user_action": { "attempted_at": null, "status": null } }, { "merchant": { "id": 40, "name": "Instacart", "logo": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png" }, "connection": { "status": "connected", "scopes": [ { "type": "update_card" } ] }, "lifecycle": { "status": "authenticating" }, "last_user_action": { "attempted_at": null, "status": null } }, { "merchant": { "id": 12, "name": "Target", "logo": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png" }, "connection": { "status": "disconnected", "scopes": [] }, "lifecycle": { "status": null }, "last_user_action": { "attempted_at": null, "status": null } } ] } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ExternalUserIdRequired": { "summary": "external_user_id not found", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The external user id field is required." } }, "InvalidType": { "summary": "Invalid product type", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The selected type is invalid." } }, "InvalidMerchantId": { "summary": "merchant_id is not valid", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The selected merchant id is invalid." } }, "UserNotFound": { "summary": "User was not found", "value": { "error_type": "USER_ERROR", "error_code": "USER_NOT_FOUND", "error_message": "The user was not found. Please check the ID provided." } }, "LinkedMerchantNotFound": { "summary": "Merchant account was not found", "value": { "error_type": "MERCHANT_ACCOUNT_ERROR", "error_code": "MERCHANT_ACCOUNT_NOT_FOUND", "error_message": "The merchant account was not found. Please check the merchant_id provided." } } } } } }, "401": { "description": "Unauthorized request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthFailed": { "summary": "Auth failed", "value": { "error_type": "INVALID_INPUT", "error_code": "INVALID_API_KEYS", "error_message": "Invalid client_id or secret provided." } } } } } }, "403": { "description": "Forbidden request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NoAccess": { "summary": "No access", "value": { "error_type": "INVALID_REQUEST", "error_code": "NO_ACCESS", "error_message": "The type is not enabled. Please contact Knot for access to this endpoint." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InternalServerError": { "summary": "Unexpected server error", "value": { "message": "Server Error" } } } } } } } } }, "/detect": { "post": { "operationId": "detect_accounts", "summary": "Detect Accounts", "description": "Detect merchant accounts with a user's email.", "requestBody": { "description": "The input parameters required for detecting a user's merchant accounts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "external_user_id": { "type": "string", "description": "Your unique identifier for the user.", "example": "123abc" }, "email": { "type": "string", "description": "The user's email address.", "example": "jane@example.com" }, "phone_number": { "type": "string", "description": "The user's phone number in E.164 format. Optional.", "example": "+14155551234" } }, "required": [ "external_user_id", "email" ] } } } }, "responses": { "202": { "description": "Successful request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message.", "example": "Success" } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "MissingExternalUserId": { "summary": "Missing external_user_id parameter", "value": { "error_type": "INVALID_INPUT", "error_code": "MISSING_PARAMETER", "error_message": "external_user_id is required." } }, "InvalidEmail": { "summary": "email is not a valid email address", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The email must be a valid email address." } }, "InvalidPhoneNumber": { "summary": "phone_number is not a valid phone number", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The phone_number must be in E.164 format." } }, "MissingEmail": { "summary": "Missing email parameter", "value": { "error_type": "INVALID_INPUT", "error_code": "MISSING_PARAMETER", "error_message": "email is required." } }, "OngoingOperation": { "summary": "An existing operation is in progress", "value": { "error_type": "MERCHANT_ACCOUNT_ERROR", "error_code": "ONGOING_OPERATION", "error_message": "An existing operation is in progress." } } } } } }, "401": { "description": "Unauthorized request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthFailed": { "summary": "Auth failed", "value": { "error_type": "INVALID_INPUT", "error_code": "INVALID_API_KEYS", "error_message": "Invalid client_id or secret provided." } } } } } }, "403": { "description": "Forbidden request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NoAccess": { "summary": "No access", "value": { "error_type": "INVALID_REQUEST", "error_code": "NO_ACCESS", "error_message": "Please contact Knot for access to this endpoint." } } } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds until the rate limit resets.", "schema": { "type": "integer", "example": 3600 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RateLimitExceeded": { "summary": "Rate limit exceeded", "value": { "error_type": "RATE_LIMIT_ERROR", "error_code": "TOO_MANY_REQUESTS", "error_message": "Rate limit exceeded. Please retry after the time indicated in the Retry-After header." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InternalServerError": { "summary": "Unexpected server error", "value": { "message": "Server Error" } } } } } } } } }, "/detected-accounts/search": { "post": { "operationId": "detected_accounts_search", "summary": "Search Detected Accounts", "description": "Search for a user's merchant accounts online.", "requestBody": { "description": "The input parameters required for identifying a user's account at a merchant.", "content": { "application/json": { "schema": { "type": "object", "properties": { "external_user_id": { "type": "string", "description": "Your unique identifier for the user.", "example": "123abc" }, "names": { "type": "array", "items": { "type": "string" }, "description": "Array of merchant or company names for which you want to identify merchant accounts. Can be a single merchant name or multiple.", "example": [ "Meta", "Uber", "johnson & johnson", "tiktok" ] } }, "required": [ "external_user_id", "names" ] } } } }, "responses": { "200": { "description": "Successful request.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The value provided in `name` in the request.", "example": "Meta" }, "detected": { "type": "boolean", "description": "Whether a merchant account was detected for the user.", "example": true }, "detected_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO timestamp when the merchant account was detected on the Knot platform.", "example": "2025-10-23T17:00:00Z" } } } }, "examples": { "MultipleMerchantAccounts": { "summary": "Multiple detected merchant accounts", "value": [ { "name": "Meta", "detected": true, "detected_at": "2025-10-23T17:00:00Z" }, { "name": "Uber", "detected": true, "detected_at": "2025-10-23T17:00:21Z" }, { "name": "johnson & johnson", "detected": false, "detected_at": null }, { "name": "tiktok", "detected": true, "detected_at": "2025-10-23T17:00:23Z" } ] }, "SingleMerchantAccount": { "summary": "Single detected merchant account", "value": [ { "name": "tiktok", "detected": true, "detected_at": "2025-10-23T17:00:23Z" } ] } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ExternalUserIdRequired": { "summary": "external_user_id is required", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The external_user_id field is required." } }, "NameRequired": { "summary": "name is required", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The name field is required." } }, "NameMustBeArray": { "summary": "name must be an array", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The name field must be an array." } } } } } }, "401": { "description": "Unauthorized request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthFailed": { "summary": "Auth failed", "value": { "error_type": "INVALID_INPUT", "error_code": "INVALID_API_KEYS", "error_message": "Invalid client_id or secret provided." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InternalServerError": { "summary": "Unexpected server error", "value": { "message": "Server Error" } } } } } } } } }, "/detected-accounts/list": { "post": { "operationId": "detected_accounts_list", "summary": "List Detected Accounts", "description": "List a user's detected accounts using cursor-based pagination.", "x-mint": { "mcp": { "enabled": true, "name": "list-detected-accounts", "description": "List a user's detected accounts using cursor-based pagination." } }, "requestBody": { "description": "The input parameters required for listing detected accounts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "external_user_id": { "type": "string", "description": "Your unique identifier for the user.", "example": "abc" }, "cursor": { "type": "string", "description": "Cursor token pointing to the last detected account retrieved. The `/detected-accounts/list` endpoint uses **cursor-based** pagination to track which detected accounts have already been seen, minimizing data redundancy. \n\nOn the first call, the endpoint returns all detected accounts **paginated**. In subsequent calls, only new detected accounts are provided using the **next cursor**.", "example": "eyJpZCI6MjI3ODEsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0" }, "limit": { "type": "integer", "description": "Maximum number of detected accounts to retrieve (min: 1, max: 100).", "example": 100, "default": 100 } }, "required": [ "external_user_id" ] } } } }, "responses": { "200": { "description": "Successful request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detected_accounts": { "type": "array", "items": { "type": "object", "properties": { "merchant": { "type": "object", "description": "Merchant information on the Knot platform.", "properties": { "id": { "type": "integer", "description": "Static unique ID of the merchant (across all environments). This ID remains constant and does not change.", "example": 122 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Spotify" }, "logo": { "type": "string", "description": "Logo of the merchant.", "example": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png" } } }, "detected_at": { "type": "string", "format": "date-time", "description": "ISO timestamp when the account was first detected.", "example": "2025-08-01T17:00:00Z" } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor token for the next page of detected accounts." }, "limit": { "type": "integer", "description": "Number of detected accounts returned based on the limit provided.", "example": 100 } } }, "examples": { "DetectedAccounts": { "summary": "Example detected accounts response.", "value": { "detected_accounts": [ { "merchant": { "id": 35, "name": "Spotify", "logo": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png" }, "detected_at": "2025-10-23T17:00:00Z" }, { "merchant": { "id": 44, "name": "Walmart", "logo": "https://knot.imgix.net/merchants/walmart.png" }, "detected_at": "2025-08-01T17:00:05Z" }, { "merchant": { "id": 84, "name": "Chewy", "logo": "https://knot.imgix.net/merchants/chewy.png" }, "detected_at": "2025-09-12T14:22:18Z" }, { "merchant": { "id": 71, "name": "Verizon", "logo": "https://knot.imgix.net/merchants/verizon.png" }, "detected_at": "2025-07-05T09:14:33Z" }, { "merchant": { "id": 53, "name": "Airbnb", "logo": "https://knot.imgix.net/merchants/airbnb.png" }, "detected_at": "2025-11-02T20:48:02Z" } ], "next_cursor": "eyJpZCI6MjI3ODEsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0", "limit": 100 } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ExternalUserIdRequired": { "summary": "external_user_id is required", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The external user id field is required." } }, "LimitNotInteger": { "summary": "limit must be an integer", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The limit must be an integer." } }, "LimitMoreThanOne": { "summary": "The limit must be at least 1.", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The limit must be at least 1." } }, "LimitLessThanHundred": { "summary": "The limit may not be greater than 100.", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The limit may not be greater than 100." } }, "InvalidCursorFormat": { "summary": "Cursor format is invalid", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The provided cursor is invalid." } } } } } }, "401": { "description": "Unauthorized request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthFailed": { "summary": "Auth failed", "value": { "error_type": "INVALID_INPUT", "error_code": "INVALID_API_KEYS", "error_message": "Invalid client_id or secret provided." } } } } } }, "403": { "description": "Forbidden request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NoAccess": { "summary": "No access", "value": { "error_type": "INVALID_REQUEST", "error_code": "NO_ACCESS", "error_message": "Please contact Knot for access to this endpoint." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InternalServerError": { "summary": "Unexpected server error", "value": { "message": "Server Error" } } } } } } } } }, "/detected-accounts/sync": { "post": { "operationId": "detected_accounts_sync", "summary": "Sync Detected Accounts", "deprecated": true, "description": "Sync a user's detected accounts using cursor-based pagination.", "x-mint": { "mcp": { "enabled": true, "name": "sync-detected-accounts", "description": "Sync a user's detected accounts using cursor-based pagination." } }, "requestBody": { "description": "The input parameters required for syncing detected accounts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "external_user_id": { "type": "string", "description": "Your unique identifier for the user.", "example": "abc" }, "cursor": { "type": "string", "description": "Cursor token pointing to the last detected account retrieved. The `/detected-accounts/sync` endpoint uses **cursor-based** pagination to track which detected accounts have already been seen, minimizing data redundancy. \n\nOn the first call, the endpoint returns all detected accounts **paginated**. In subsequent calls, only new detected accounts are provided using the **next cursor**.", "example": "eyJpZCI6MjI3ODEsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0" }, "limit": { "type": "integer", "description": "Maximum number of detected accounts to retrieve (min: 1, max: 100).", "example": 100, "default": 100 } }, "required": [ "external_user_id" ] } } } }, "responses": { "200": { "description": "Successful request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detected_accounts": { "type": "array", "items": { "type": "object", "properties": { "merchant": { "type": "object", "description": "Merchant information on the Knot platform.", "properties": { "id": { "type": "integer", "description": "Static unique ID of the merchant (across all environments). This ID remains constant and does not change.", "example": 122 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Spotify" }, "logo": { "type": "string", "description": "Logo of the merchant.", "example": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png" } } }, "login_method": { "type": [ "string", "null" ], "enum": [ "GOOGLE_SSO", "APPLE_SSO", "AMAZON_SSO", "USERNAME_PASSWORD", null ], "description": "The method used to log into the merchant account.", "example": "GOOGLE_SSO" }, "account_created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO timestamp when the account was created.", "example": "2025-02-24T11:53:09Z" }, "detected_at": { "type": "string", "format": "date-time", "description": "ISO timestamp when the account was first detected.", "example": "2025-08-01T17:00:00Z" } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor token for the next page of detected accounts." }, "limit": { "type": "integer", "description": "Number of detected accounts returned based on the limit provided.", "example": 100 } } }, "examples": { "DetectedAccounts": { "summary": "Example detected accounts response.", "value": { "detected_accounts": [ { "merchant": { "id": 35, "name": "Spotify", "logo": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png" }, "login_method": "GOOGLE_SSO", "account_created_at": "2025-08-24T11:53:09Z", "detected_at": "2025-10-23T17:00:00Z" }, { "merchant": { "id": 44, "name": "Walmart", "logo": "https://knot.imgix.net/merchants/walmart.png" }, "login_method": "", "account_created_at": "", "detected_at": "2025-08-01T17:00:05Z" } ], "next_cursor": "eyJpZCI6MjI3ODEsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0", "limit": 100 } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "MissingExternalUserId": { "summary": "Missing external_user_id parameter", "value": { "error_type": "INVALID_INPUT", "error_code": "MISSING_PARAMETER", "error_message": "external_user_id is required." } }, "LimitNotInteger": { "summary": "limit must be an integer", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The limit must be an integer." } }, "LimitMoreThanOne": { "summary": "The limit must be at least 1.", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The limit must be at least 1." } }, "LimitLessThanHundred": { "summary": "The limit may not be greater than 100.", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The limit may not be greater than 100." } }, "InvalidCursorFormat": { "summary": "Cursor format is invalid", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The provided cursor is invalid." } } } } } }, "401": { "description": "Unauthorized request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthFailed": { "summary": "Auth failed", "value": { "error_type": "INVALID_INPUT", "error_code": "INVALID_API_KEYS", "error_message": "Invalid client_id or secret provided." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InternalServerError": { "summary": "Unexpected server error", "value": { "message": "Server Error" } } } } } } } } }, "/audit_logs": { "servers": [ { "url": "https://production.knotapi.com", "description": "Production server" } ], "get": { "operationId": "audit_logs_get", "summary": "Get Audit Logs", "description": "Retrieve audit logs for employee usage of the Knot Dashboard.", "parameters": [ { "name": "start", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2025-01-01T00:00:00Z" }, "description": "Filter audit logs to those created on or after this timestamp. Must be in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)." }, { "name": "end", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2025-12-31T23:59:59Z" }, "description": "Filter audit logs to those created on or before this timestamp. Must be in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)." }, { "name": "next_cursor", "in": "query", "required": false, "schema": { "type": "string", "example": "eyJpZCI6MTIzNDU2LCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9" }, "description": "Cursor token for pagination. Use the `next_cursor` value from the previous response to retrieve the next page of results." } ], "responses": { "200": { "description": "Successful request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the audit log entry.", "example": "a0b66190-9e04-4bc6-82ae-5d98e1f70e59" }, "datetime": { "type": "string", "format": "date-time", "description": "ISO 8601 datetime (YYYY-MM-DDTHH:MM:SSZ) when the action occurred.", "example": "2025-12-23T15:48:58Z" }, "event": { "type": "object", "properties": { "action": { "type": "string", "description": "The action that was performed.", "example": "merchant.hide" }, "outcome": { "type": "object", "properties": { "status": { "type": "string", "description": "The outcome status of the action.", "example": "success" } }, "required": [ "status" ] } }, "required": [ "action", "outcome" ] }, "actor": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the user that performed the action. `System` if no individual user performed the action.", "example": "Ada Lovelace" }, "email": { "type": "string", "description": "Email address of the user that performed the action.", "example": "ada@lovelace.com" } }, "required": [ "name" ] }, "target": { "type": [ "object", "null" ], "description": "", "properties": { "type": { "type": [ "string", "null" ], "enum": [ "webhook", "secret", "domain", "user", "merchant", null ], "description": "The type of target entity.", "example": "merchant" }, "name": { "type": [ "string", "null" ], "description": "The name of the target entity.", "example": "Amazon Prime" }, "environment": { "type": [ "string", "null" ], "enum": [ "production", "development", null ], "description": "The environment associated with the target.", "example": "production" } }, "required": [ "type", "name", "environment" ] }, "context": { "type": "object", "properties": { "ip": { "type": "string", "description": "IP address from which the action was performed.", "example": "208.204.24.80" }, "user_agent": { "type": "string", "description": "User agent string of the browser or client used to perform the action.", "example": "Mozilla/5.0 ..." } } } }, "required": [ "id", "datetime", "event", "actor", "target", "context" ] } }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor token for the next page of audit logs. Null if there are no further results." }, "limit": { "type": "integer", "description": "Number of items per page.", "example": 100 } } }, "examples": { "ViewSecret": { "summary": "Example audit log response for viewing a secret", "value": { "data": [ { "id": "c2d88312-1b26-6de8-a4cg-7f1a3h92g81", "datetime": "2025-12-25T08:15:30Z", "event": { "action": "secret.view", "outcome": { "status": "success" } }, "actor": { "name": "Ada Lovelace", "email": "ada@lovelace.com" }, "target": { "type": "secret", "name": null, "environment": "production" }, "context": { "ip": "208.204.24.80", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36" } } ], "next_cursor": "eyJpZCI6MTIzNDU2LCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9", "limit": 100 } }, "HideMerchant": { "summary": "Example audit log response for hiding a merchant", "value": { "data": [ { "id": "a0b66190-9e04-4bc6-82ae-5d98e1f70e59", "datetime": "2025-12-23T15:48:58Z", "event": { "action": "merchant.hide", "outcome": { "status": "success" } }, "actor": { "name": "Ada Lovelace", "email": "ada@lovelace.com" }, "target": { "type": "merchant", "name": "Amazon Prime", "environment": null }, "context": { "ip": "208.204.24.80", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36" } } ], "next_cursor": "eyJpZCI6MTIzNDU2LCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9", "limit": 100 } }, "UpdateWebhook": { "summary": "Example audit log response for updating a webhook", "value": { "data": [ { "id": "b1c77201-0a15-5cd7-93bf-6e09f2g81f70", "datetime": "2025-12-24T10:30:00Z", "event": { "action": "webhook.update", "outcome": { "status": "success" } }, "actor": { "name": "Ada Lovelace", "email": "ada@lovelace.com" }, "target": { "type": "webhook", "name": null, "environment": "production" }, "context": { "ip": "208.204.24.80", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36" } } ], "next_cursor": null, "limit": 100 } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidStartDateFormat": { "summary": "Invalid start date format", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The start must be in ISO 8601 format." } }, "InvalidEndDateFormat": { "summary": "Invalid end date format", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The end must be in ISO 8601 format." } }, "InvalidCursorFormat": { "summary": "Cursor format is invalid", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_CURSOR_FORMAT", "error_message": "The provided cursor is invalid." } } } } } }, "401": { "description": "Unauthorized request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthFailed": { "summary": "Auth failed", "value": { "error_type": "INVALID_INPUT", "error_code": "INVALID_API_KEYS", "error_message": "Invalid client_id or secret provided." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InternalServerError": { "summary": "Unexpected server error", "value": { "message": "Server Error" } } } } } } } } }, "/user/delete": { "post": { "operationId": "user_delete", "summary": "Delete User & Data", "description": "Delete a user and their data.", "requestBody": { "description": "The input parameters required for deleting a user and their data.", "content": { "application/json": { "schema": { "type": "object", "properties": { "external_user_id": { "type": "string", "description": "Your unique identifier for the user.", "example": "abc123" } }, "required": [ "external_user_id" ] } } } }, "responses": { "200": { "description": "Successful request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message.", "example": "Success" } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ExternalUserIdRequired": { "summary": "external_user_id not found", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The external user id field is required." } }, "UserNotFound": { "summary": "User was not found", "value": { "error_type": "USER_ERROR", "error_code": "USER_NOT_FOUND", "error_message": "The user was not found. Please check the ID provided." } } } } } }, "401": { "description": "Unauthorized request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthFailed": { "summary": "Auth failed", "value": { "error_type": "INVALID_INPUT", "error_code": "INVALID_API_KEYS", "error_message": "Invalid client_id or secret provided." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InternalServerError": { "summary": "Unexpected server error", "value": { "message": "Server Error" } } } } } } } } }, "/development/accounts/link": { "post": { "operationId": "development_accounts_link", "summary": "Link Account", "description": "Link a merchant account in development.", "x-mint": { "mcp": { "enabled": true, "name": "link-account", "description": "Link a merchant account in development." } }, "requestBody": { "description": "The input parameters required for linking a merchant account in development.", "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "title": "CardSwitcher", "type": "object", "properties": { "external_user_id": { "type": "string", "description": "Your unique identifier for the user.", "example": "abc123" }, "merchant_id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 19 }, "card_switcher": { "type": "boolean", "description": "When set to true, simulates the card switcher flow.", "example": true }, "card_id": { "type": "string", "description": "Your unique identifier for a specific card. Required when `card_switcher` is `true`.", "example": "81n9al10a0ayn13" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string", "maxLength": 500 }, "maxProperties": 10, "description": "Optional key-value pairs to include in webhook payloads. Maximum 10 keys, 500 characters per value.", "example": { "reference_token": "abc123", "trace_id": "def456" }, "default": null } }, "required": [ "external_user_id", "merchant_id", "card_switcher", "card_id" ] }, { "title": "TransactionLink", "type": "object", "properties": { "external_user_id": { "type": "string", "description": "Your unique identifier for the user.", "example": "abc123" }, "merchant_id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 19 }, "transactions": { "type": "object", "description": "Configuration for whether to receive transactions when linking the account.", "properties": { "new": { "type": "boolean", "description": "Whether to generate new transactions and receive notification of them via the [`NEW_TRANSACTIONS_AVAILABLE`](/transaction-link/webhook-events/new-transactions-available) event to your webhook for testing.", "example": true, "default": true }, "updated": { "type": "boolean", "description": "Whether to update newly-generated transactions and receive notification of them via the [`UPDATED_TRANSACTIONS_AVAILABLE`](/transaction-link/webhook-events/updated-transactions-available) event to your webhook for testing. You must pass `new: true` in the request to use this parameter.", "example": false, "default": false } }, "required": [ "new" ] }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string", "maxLength": 500 }, "maxProperties": 10, "description": "Optional key-value pairs to include in webhook payloads. Maximum 10 keys, 500 characters per value.", "example": { "reference_token": "abc123", "trace_id": "def456" }, "default": null } }, "required": [ "external_user_id", "merchant_id", "transactions" ] }, { "title": "SubscriptionManager", "type": "object", "properties": { "external_user_id": { "type": "string", "description": "Your unique identifier for the user.", "example": "abc123" }, "merchant_id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 19 }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string", "maxLength": 500 }, "maxProperties": 10, "description": "Optional key-value pairs to include in webhook payloads. Maximum 10 keys, 500 characters per value.", "example": { "reference_token": "abc123", "trace_id": "def456" }, "default": null } }, "required": [ "external_user_id", "merchant_id" ] }, { "title": "Shopping", "type": "object", "properties": { "external_user_id": { "type": "string", "description": "Your unique identifier for the user.", "example": "abc123" }, "merchant_id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 19 }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string", "maxLength": 500 }, "maxProperties": 10, "description": "Optional key-value pairs to include in webhook payloads. Maximum 10 keys, 500 characters per value.", "example": { "reference_token": "abc123", "trace_id": "def456" }, "default": null } }, "required": [ "external_user_id", "merchant_id" ] } ] }, "examples": { "CardSwitcher": { "summary": "Card Switcher", "value": { "external_user_id": "abc123", "merchant_id": 19, "card_switcher": true, "card_id": "81n9al10a0ayn13" } }, "TransactionLink": { "summary": "Transaction Link", "value": { "external_user_id": "abc123", "merchant_id": 45, "transactions": { "new": true, "updated": false } } }, "SubscriptionManager": { "summary": "Subscription Manager", "value": { "external_user_id": "abc123", "merchant_id": 16 } }, "Shopping": { "summary": "Shopping", "value": { "external_user_id": "abc123", "merchant_id": 44 } } } } } }, "responses": { "200": { "description": "Successful request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message.", "example": "Success" } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ExternalUserIdRequired": { "summary": "external_user_id is required", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The external_user_id field is required." } }, "MerchantIdRequired": { "summary": "merchant_id is required", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The merchant_id field is required." } }, "InvalidMerchantId": { "summary": "merchant_id is invalid", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The selected merchant_id is invalid." } }, "InvalidTransactions": { "summary": "transactions must be an array", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The transactions must be an array." } }, "InvalidTransactionsNew": { "summary": "transactions.new must be boolean", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The transactions.new must be true or false." } }, "InvalidTransactionsUpdated": { "summary": "transactions.updated must be boolean", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The transactions.updated must be true or false." } }, "UserNotFound": { "summary": "User not found when updating transactions", "value": { "error_type": "USER_ERROR", "error_code": "USER_NOT_FOUND", "error_message": "The user was not found. Cannot update transactions for a non-existent user." } }, "MerchantAccountNotFound": { "summary": "Merchant account not found when updating transactions", "value": { "error_type": "MERCHANT_ACCOUNT_ERROR", "error_code": "MERCHANT_ACCOUNT_NOT_FOUND", "error_message": "The merchant account does not exist. Cannot update transactions for a non-existent merchant account." } }, "NoTransactionsToUpdate": { "summary": "No transactions to update", "value": { "error_type": "MERCHANT_ACCOUNT_ERROR", "error_code": "NO_TRANSACTIONS", "error_message": "The merchant account does not have any transactions to update." } } } } } }, "401": { "description": "Unauthorized request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthFailed": { "summary": "Auth failed", "value": { "error_type": "INVALID_INPUT", "error_code": "INVALID_API_KEYS", "error_message": "Invalid client_id or secret provided." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InternalServerError": { "summary": "Unexpected server error", "value": { "message": "Server Error" } } } } } } } } }, "/development/accounts/disconnect": { "post": { "operationId": "development_accounts_disconnect", "summary": "Disconnect Account", "description": "Change a merchant account's connection status to disconnected and subsequently fire the ACCOUNT_LOGIN_REQUIRED webhook.", "requestBody": { "description": "The input parameters required for changing a merchant account's connection status to disconnected in development.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "external_user_id": { "type": "string", "description": "Unique identifier for the user.", "example": "abc123" }, "merchant_id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 12 } }, "required": [ "external_user_id", "merchant_id" ] } } } }, "responses": { "200": { "description": "Successful request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message.", "example": "Success" } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UserNotFound": { "summary": "User not found", "value": { "error_type": "USER_ERROR", "error_code": "USER_NOT_FOUND", "error_message": "The user was not found. Please check the ID provided." } }, "MerchantIdRequired": { "summary": "merchant_id is required", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The merchant_id field is required." } }, "ExternalUserIdRequired": { "summary": "external_user_id is required", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The external user id field is required." } }, "MerchantAccountNotFound": { "summary": "Merchant account not found", "value": { "error_type": "MERCHANT_ACCOUNT_ERROR", "error_code": "MERCHANT_ACCOUNT_NOT_FOUND", "error_message": "The merchant account was not found. Please check the merchant_id provided." } } } } } }, "401": { "description": "Unauthorized request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthFailed": { "summary": "Auth failed", "value": { "error_type": "INVALID_INPUT", "error_code": "INVALID_API_KEYS", "error_message": "Invalid client_id or secret provided." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InternalServerError": { "summary": "Unexpected server error", "value": { "message": "Server Error" } } } } } } } } }, "/balance/payout": { "post": { "operationId": "balance_payout", "summary": "Payout Balance", "description": "Initiate a payout a balance from a user's merchant account wallet to their bank account.", "requestBody": { "description": "The input parameters required for initiating a payout.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "external_user_id": { "type": "string", "description": "Your unique identifier for the user.", "example": "abc123" }, "merchant_id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 11 }, "amount": { "type": "string", "description": "The amount to payout.", "example": "451.00" } }, "required": [ "external_user_id", "merchant_id", "amount" ] } } } }, "responses": { "200": { "description": "Successful request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message.", "example": "Success" } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UserNotFound": { "summary": "User not found", "value": { "error_type": "USER_ERROR", "error_code": "USER_NOT_FOUND", "error_message": "The user was not found. Please check the external_user_id provided." } }, "MerchantAccountNotFound": { "summary": "Merchant account not found", "value": { "error_type": "MERCHANT_ACCOUNT_ERROR", "error_code": "MERCHANT_ACCOUNT_NOT_FOUND", "error_message": "The merchant account was not found. Please check the merchant_id provided." } } } } } }, "401": { "description": "Unauthorized request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthFailed": { "summary": "Auth failed", "value": { "error_type": "INVALID_INPUT", "error_code": "INVALID_API_KEYS", "error_message": "Invalid client_id or secret provided." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InternalServerError": { "summary": "Unexpected server error", "value": { "message": "Server Error" } } } } } } } } }, "/balance/deposit": { "post": { "operationId": "balance_deposit", "summary": "Deposit Balance", "description": "Initiate a deposit of balance to a user's merchant account wallet from their bank account.", "requestBody": { "description": "The input parameters required for initiating a deposit.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "external_user_id": { "type": "string", "description": "Your unique identifier for the user.", "example": "abc123" }, "merchant_id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 456 }, "amount": { "type": "string", "description": "The amount to deposit.", "example": "25.00" } }, "required": [ "external_user_id", "merchant_id", "amount" ] } } } }, "responses": { "200": { "description": "Successful request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message.", "example": "Success" } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UserNotFound": { "summary": "User not found", "value": { "error_type": "USER_ERROR", "error_code": "USER_NOT_FOUND", "error_message": "The user was not found. Please check the external_user_id provided." } }, "MerchantAccountNotFound": { "summary": "Merchant account not found", "value": { "error_type": "MERCHANT_ACCOUNT_ERROR", "error_code": "MERCHANT_ACCOUNT_NOT_FOUND", "error_message": "The merchant account was not found. Please check the merchant_id provided." } } } } } }, "401": { "description": "Unauthorized request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthFailed": { "summary": "Auth failed", "value": { "error_type": "INVALID_INPUT", "error_code": "INVALID_API_KEYS", "error_message": "Invalid client_id or secret provided." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InternalServerError": { "summary": "Unexpected server error", "value": { "message": "Server Error" } } } } } } } } }, "/vault-workflow": { "post": { "operationId": "vault_workflow", "summary": "Vault Workflow", "description": "", "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "signature": { "type": "string", "description": "" }, "x_base": { "type": "string", "description": "" }, "payment_context_id": { "type": "string", "description": "" } } } } } }, "responses": { "200": { "description": "Successful request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message.", "example": "Success" } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "SignatureNotString": { "summary": "signature must be a string", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The signature must be a string." } }, "XBaseNotString": { "summary": "x_base must be a string", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The x_base must be a string." } }, "PaymentContextIdNotString": { "summary": "payment_context_id must be a string", "value": { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "The payment_context_id must be a string." } }, "WorkflowNotFound": { "summary": "Workflow not found", "value": { "error_type": "WORKFLOW_ERROR", "error_code": "WORKFLOW_NOT_FOUND", "error_message": "The workflow was not found or is in a terminal state." } } } } } }, "401": { "description": "Unauthorized request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "AuthFailed": { "summary": "Auth failed", "value": { "error_type": "INVALID_INPUT", "error_code": "INVALID_API_KEYS", "error_message": "Invalid client_id or secret provided." } } } } } }, "403": { "description": "Forbidden request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NoAccess": { "summary": "No access", "value": { "error_type": "INVALID_REQUEST", "error_code": "NO_ACCESS", "error_message": "Please contact Knot for access to this endpoint." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InternalServerError": { "summary": "Unexpected server error", "value": { "message": "Server Error" } } } } } } } } } }, "webhooks": { "authenticated": { "post": { "summary": "AUTHENTICATED", "description": "Fired when the authentication to a merchant is successful.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticatedWebhook" } } } } } }, "vaulting_succeeded": { "post": { "summary": "VAULTING_SUCCEEDED", "description": "Fired when a digital wallet is successfully vaulted to a user's merchant account.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultingSucceededWebhook" } } } } } }, "sync_cart_succeeded": { "post": { "summary": "SYNC_CART_SUCCEEDED", "description": "Fired when adding products to a user's merchant cart is successful.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncCartSucceededWebhook" } } } } } }, "sync_cart_failed": { "post": { "summary": "SYNC_CART_FAILED", "description": "Fired when adding products to a user's merchant cart fails.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncCartFailedWebhook" } } } } } }, "checkout_succeeded": { "post": { "summary": "CHECKOUT_SUCCEEDED", "description": "Fired when checkout succeeds for a user's merchant cart.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSucceededWebhook" } } } } } }, "checkout_failed": { "post": { "summary": "CHECKOUT_FAILED", "description": "Triggered when checkout fails for a user's merchant cart.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutFailedWebhook" } } } } } }, "card_updated": { "post": { "summary": "CARD_UPDATED", "description": "Fired when a card is updated in a merchant account.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardUpdatedWebhook" } } } } } }, "card_failed": { "post": { "summary": "CARD_FAILED", "description": "Fired when a card failed to be updated in a merchant account.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardFailedWebhook" } } } } } }, "new_transactions_available": { "post": { "summary": "NEW_TRANSACTIONS_AVAILABLE", "description": "Fired when new transactions for a user's merchant account are available.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewTransactionsAvailableWebhook" } } } } } }, "updated_transactions_available": { "post": { "summary": "UPDATED_TRANSACTIONS_AVAILABLE", "description": "Fired when updated data is available for existing transactions for a user's merchant account.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatedTransactionsAvailableWebhook" } } } } } }, "merchant_status_update": { "post": { "summary": "MERCHANT_STATUS_UPDATE", "description": "Fired when a merchant becomes available or unavailable.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantStatusUpdateWebhook" } } } } } }, "credentials_failed": { "post": { "summary": "CREDENTIALS_FAILED", "description": "Fired when the login credentials used to login to a merchant are incorrect and the user needs to re-enter them (if a `CARD_FAILED` webhook is not received).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialsFailedWebhook" } } } } } }, "otp_required": { "post": { "summary": "OTP_REQUIRED", "description": "Fired when a user needs to enter an OTP code to login to a merchant for the 1st time.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtpRequiredWebhook" } } } } } }, "otp_failed": { "post": { "summary": "OTP_FAILED", "description": "Fired when the OTP code used to login to a merchant is incorrect and the user needs to re-enter it (if a `CARD_FAILED` webhook is not received).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtpFailedWebhook" } } } } } }, "questions_required": { "post": { "summary": "QUESTIONS_REQUIRED", "description": "Fired when a user needs to provide answers to security questions for the 1st time.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionsRequiredWebhook" } } } } } }, "questions_failed": { "post": { "summary": "QUESTIONS_FAILED", "description": "Fired when the answers to security questions are incorrect and the user needs to re-enter the answers (if a `CARD_FAILED` webhook is not received).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionsFailedWebhook" } } } } } }, "dob_required": { "post": { "summary": "DOB_REQUIRED", "description": "Fired when a user needs to verify their date of birth to login to a merchant for the 1st time.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DobRequiredWebhook" } } } } } }, "dob_failed": { "post": { "summary": "DOB_FAILED", "description": "Fired when the date of birth provided is incorrect and the user needs to re-enter it (if a `CARD_FAILED` webhook is not received).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DobFailedWebhook" } } } } } }, "license_required": { "post": { "summary": "LICENSE_REQUIRED", "description": "Fired when a user needs to provide their driver license number to login to a merchant for the 1st time.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicenseRequiredWebhook" } } } } } }, "license_failed": { "post": { "summary": "LICENSE_FAILED", "description": "Fired when an incorrect driver license number is provided and the user needs to re-enter the driver license number.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicenseFailedWebhook" } } } } } }, "login_approval": { "post": { "summary": "LOGIN_APPROVAL", "description": "Fired when a user needs to approve the login to a merchant via a push notification, text message, or similar from a merchant.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginApprovalWebhook" } } } } } }, "accounts_retrieved": { "post": { "summary": "ACCOUNTS_RETRIEVED", "description": "Fired when a user's merchant accounts are successfully retrieved from their Google Account. This event is specific to the MassSwitcher feature.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountsRetrievedWebhook" } } } } } }, "account_login_required": { "post": { "summary": "ACCOUNT_LOGIN_REQUIRED", "description": "Fired when a user's merchant account is disconnected and requires the user to login again to reconnect the account.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountLoginRequiredWebhook" } } } } } }, "vaulting_failed": { "post": { "summary": "VAULTING_FAILED", "description": "Fired when a digital wallet fails to be vaulted to a user's merchant account.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultingFailedWebhook" } } } } } }, "new_detected_accounts_available": { "post": { "summary": "NEW_DETECTED_ACCOUNTS_AVAILABLE", "description": "Fired when new detected accounts are available.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewDetectedAccountsAvailableWebhook" } } } } } }, "account_detection_failed": { "post": { "summary": "ACCOUNT_DETECTION_FAILED", "description": "Fired when account detection failed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDetectionFailedWebhook" } } } } } }, "cancellation_succeeded": { "post": { "summary": "CANCELLATION_SUCCEEDED", "description": "Fired when a subscription or bill is canceled successfully.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancellationSucceededWebhook" } } } } } }, "cancellation_failed": { "post": { "summary": "CANCELLATION_FAILED", "description": "Fired when a subscription or bill fails to be canceled.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancellationFailedWebhook" } } } } } }, "new_subscriptions_available": { "post": { "summary": "NEW_SUBSCRIPTIONS_AVAILABLE", "description": "Fired when new subscriptions are available for a user's merchant account.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewSubscriptionsAvailableWebhook" } } } } } }, "updated_subscriptions_available": { "post": { "summary": "UPDATED_SUBSCRIPTIONS_AVAILABLE", "description": "Fired when updates are available for existing subscriptions for a user's merchant account.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatedSubscriptionsAvailableWebhook" } } } } } }, "port_data_succeeded": { "post": { "summary": "PORT_DATA_SUCCEEDED", "description": "Fired when the information required to port a user's phone number to another carrier has been successfully retrieved from their merchant account.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortDataSucceededWebhook" } } } } } } }, "components": { "schemas": { "Merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 45 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Walmart" } } }, "MerchantFull": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 18 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Hulu" }, "category": { "type": "string", "description": "Category of the merchant.", "example": "Streaming" }, "logo": { "type": "string", "description": "URL of the merchant's logo.", "example": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png" } } }, "Subscription": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the subscription.", "example": "13da3c28-a068-4642-9ce2-b730cfda5f5f" }, "external_id": { "type": "string", "description": "External identifier for the subscription provided by the merchant.", "example": "a9x7bq2lmw5p" }, "name": { "type": "string", "description": "Human-readable subscription name as displayed by the merchant.", "example": "Disney+, Hulu Bundle Premium" }, "description": { "type": [ "string", "null" ], "description": "Description of the subscription plan.", "example": "Ad-free streaming with Disney+ and Hulu" }, "merchant": { "$ref": "#/components/schemas/SubscriptionMerchant" }, "status": { "type": "string", "description": "Status of the subscription.", "example": "ACTIVE", "oneOf": [ { "const": "ACTIVE", "title": "ACTIVE", "description": "Billing and access ongoing." }, { "const": "ACTIVE_CANCELLATION", "title": "ACTIVE_CANCELLATION", "description": "Cancelled, but still active until end of billing period." }, { "const": "ACTIVE_PLAN_CHANGE", "title": "ACTIVE_PLAN_CHANGE", "description": "Plan change queued." }, { "const": "ACTIVE_SUSPENSION", "title": "ACTIVE_SUSPENSION", "description": "Service active but on a temporary grace period often due to payment failure. Likely to become suspended if payment is not made." }, { "const": "PENDING", "title": "PENDING", "description": "Not yet billed or activated." }, { "const": "PAUSED", "title": "PAUSED", "description": "Temporarily paused by user." }, { "const": "CANCELLED", "title": "CANCELLED", "description": "Fully terminated." }, { "const": "SUSPENDED", "title": "SUSPENDED", "description": "Service suspended by merchant, often due to payment failure." }, { "const": "UNRECOGNIZED", "title": "UNRECOGNIZED", "description": "Status could not be determined." } ] }, "billing_cycle": { "type": "string", "enum": [ "RECURRING_MONTHLY", "RECURRING_BIMONTHLY", "RECURRING_WEEKLY", "RECURRING_BIWEEKLY", "RECURRING_QUARTERLY", "RECURRING_SEMIANNUALLY", "RECURRING_ANNUALLY", "RECURRING_DAILY", "ONE_TIME", "UNRECOGNIZED" ], "description": "Billing cycle of the subscription.", "example": "RECURRING_MONTHLY" }, "next_billing_date": { "type": [ "string", "null" ], "format": "date", "description": "Date of the next scheduled charge in UTC. ISO 8601 format (YYYY-MM-DD).", "example": "2026-02-10" }, "last_billing_date": { "type": [ "string", "null" ], "format": "date", "description": "Date of the most recent attempted charge in UTC. ISO 8601 format (YYYY-MM-DD).", "example": "2026-01-10" }, "start_date": { "type": [ "string", "null" ], "format": "date", "description": "Start date for the subscription in UTC. ISO 8601 format (YYYY-MM-DD).", "example": "2025-06-15" }, "expiration_date": { "type": [ "string", "null" ], "format": "date", "description": "Date of the loss of access to the subscription due to cancellation or other means in UTC. ISO 8601 format (YYYY-MM-DD).", "example": null }, "payment_method": { "$ref": "#/components/schemas/SubscriptionPaymentMethod" }, "cancel_instructions": { "type": [ "string", "null" ], "description": "Instructions for cancelling the subscription, if available.", "example": "You can cancel your subscription at any time from your account settings. Your cancellation will take effect at the end of your current billing period. You'll continue to have access until May 30, 2026. You will not be charged again unless you restart your subscription." }, "is_paid": { "type": [ "boolean", "null" ], "description": "Whether the subscription is a paid plan or free.", "example": true }, "is_free_trial": { "type": [ "boolean", "null" ], "description": "Whether the subscription is currently in a free trial period, or was suspended or cancelled while in one.", "example": false }, "is_family_plan": { "type": [ "boolean", "null" ], "description": "Whether the subscription is a family plan.", "example": false }, "is_cancellable": { "type": "boolean", "description": "Indicates whether the merchant has marked this subscription as cancellable.", "example": true }, "price": { "anyOf": [ { "$ref": "#/components/schemas/SubscriptionPrice" }, { "type": "null" } ] } }, "example": { "id": "13da3c28-a068-4642-9ce2-b730cfda5f5f", "external_id": "a9x7bq2lmw5p", "name": "Disney+, Hulu Bundle Premium", "description": "Ad-free streaming with Disney+ and Hulu", "merchant": { "id": 18, "name": "Hulu", "category": "Streaming", "logo": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png" }, "status": "ACTIVE", "billing_cycle": "RECURRING_MONTHLY", "next_billing_date": "2026-02-10", "last_billing_date": "2026-01-10", "start_date": "2025-06-15", "expiration_date": null, "payment_method": { "type": "CARD", "brand": "VISA", "last_four": "1234" }, "cancel_instructions": "You can cancel your subscription at any time from your account settings. Your cancellation will take effect at the end of your current billing period. You'll continue to have access until May 30, 2026. You will not be charged again unless you restart your subscription.", "is_paid": true, "is_family_plan": false, "is_cancellable": true, "price": { "total": "11.99", "currency": "USD" } } }, "SubscriptionPaymentMethod": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "CARD", "THIRD_PARTY", "APPLE_PAY", "GOOGLE_PAY", "AMAZON_PAY", "PAYPAL", "CASH_APP", "VENMO", "AFFIRM", "KLARNA", "GIFT_CARD", "CASH", "BANK_ACCOUNT", "LOYALTY_POINTS", "UNRECOGNIZED" ], "description": "Type of the payment method.", "example": "CARD" }, "brand": { "type": [ "string", "null" ], "description": "Brand of the payment method.", "example": "VISA" }, "last_four": { "type": [ "string", "null" ], "description": "Last 4 digits of the payment method, if a payment card.", "example": "1234" } }, "example": { "type": "CARD", "brand": "VISA", "last_four": "1234" } }, "SubscriptionPrice": { "type": "object", "properties": { "total": { "type": "string", "description": "Total price of the subscription.", "example": "11.99" }, "currency": { "type": "string", "description": "Currency of the price. ISO 4217 format.", "example": "USD" } } }, "Transaction": { "type": "object", "properties": { "id": { "type": "string", "description": "UUID for the transaction. It is best practice to deduplicate on this value.", "example": "13da3c28-a068-4642-9ce2-b730cfda5f5f" }, "external_id": { "type": [ "string", "null" ], "description": "External identifier for the transaction provided by the merchant.", "example": "a9x7bq2lmw5p" }, "datetime": { "type": "string", "format": "date-time", "description": "Timestamp of the transaction in UTC. ISO 8601 format. **Note that Knot does not guarantee a specific order in which transactions are returned.**", "example": "2024-11-10T00:00:00+00:00" }, "url": { "type": [ "string", "null" ], "description": "URL associated with the transaction.", "example": "https://www.example.com/orders/123123123" }, "order_status": { "type": "string", "enum": [ "ORDERED", "BILLED", "SHIPPED", "DELIVERED", "RETURNED", "REFUNDED", "CANCELLED", "FAILED", "COMPLETED", "PICKED_UP", "UNRECOGNIZED" ], "description": "Status of the order associated with the transaction.", "example": "COMPLETED" }, "shipping": { "anyOf": [ { "$ref": "#/components/schemas/Shipping" }, { "type": "null" } ], "description": "Shipping information for the transaction, including the recipient's name and delivery address. `null` when no shipping data is available." }, "payment_methods": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethod" }, "description": "List of payment methods." }, "price": { "$ref": "#/components/schemas/TransactionPrice" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "loyalty_membership": { "anyOf": [ { "$ref": "#/components/schemas/LoyaltyMembership" }, { "type": "null" } ], "description": "Loyalty membership information for the merchant account, not necessarily related to the specific transaction. When `null`, the merchant account does not have the loyalty membership." } }, "example": { "id": "13da3c28-a068-4642-9ce2-b730cfda5f5f", "external_id": "a9x7bq2lmw5p", "datetime": "2024-11-10T00:00:00+00:00", "url": "https://www.example.com/orders/123123123", "order_status": "COMPLETED", "shipping": { "location": { "address": { "line1": "123 Main St", "line2": "Floor 4", "city": "Los Angeles", "region": "CA", "postal_code": "94105", "country": "US" }, "first_name": "Ada", "last_name": "Lovelace" } }, "payment_methods": [ { "external_id": "x7q9m2lbw5pazc", "type": "CARD", "brand": "VISA", "last_four": "5690", "name": "Ada's credit card", "transaction_amount": "23.20" }, { "external_id": "x7q9m2lbw5pazc", "type": "GIFT_CARD", "brand": "VISA", "last_four": "1802", "name": "", "transaction_amount": "20.00" } ], "price": { "sub_total": "43.69", "adjustments": [ { "type": "TAX", "label": "NYC local sales tax", "amount": "3.88" }, { "type": "DISCOUNT", "label": "Summer promo", "amount": "-4.37" } ], "total": "43.20", "currency": "USD" }, "products": [ { "external_id": "10315643", "gtin": "00381370044536", "name": "Band-Aid Adhesive Bandages Variety Pack", "description": "A convenient assortment of durable adhesive bandages designed to protect minor cuts and scrapes. Featuring a range of sizes for everyday first-aid needs, each bandage cushions the wound while helping keep out dirt and germs. Made to stay securely in place with a gentle adhesive, this variety pack is ideal for home, travel, school, or on-the-go care.", "category": "CATEGORY1", "url": "https://www.example.com/ip/10315643", "image_url": "https://storage.googleapis.com/txn-product-images/doordash/33972462636.jpg", "quantity": 1, "price": { "sub_total": "12.56", "total": "12.56", "unit_price": "12.56" }, "seller": null, "eligibility": [ "FSA/HSA" ] }, { "external_id": "1031891", "gtin": "00078731878120", "name": "Dixie Ultra 8-12 Paper Plate, 240-count", "description": "", "category": "CATEGORY2", "url": "https://www.example.com/ip/1031891", "image_url": "https://storage.googleapis.com/txn-product-images/doordash/33972462636.jpg", "quantity": 1, "price": { "sub_total": "8.14", "total": "8.14", "unit_price": "8.14" }, "seller": null, "eligibility": [] }, { "external_id": "1038973", "gtin": "00651277430015", "name": "4Pairs Men's Elite Sports Socks Athletic Crew Socks Mid-calf Boys for Football, Basketball, Running Soccer", "description": "High-performance athletic crew socks designed for comfort, support, and durability during intense activity. Made with breathable, moisture-wicking fabric to help keep feet dry, with reinforced heels and toes for added strength.", "category": "CATEGORY3", "url": "https://www.example.com/ip/1038973", "image_url": "https://storage.googleapis.com/txn-product-images/doordash/33972462636.jpg", "quantity": 1, "price": { "sub_total": "22.99", "total": "22.99", "unit_price": "22.99" }, "seller": { "name": "KingCamp Outdoor Products Co., Ltd.", "url": "https://www.example.com/browse/kingcamp/YnJhbmQ6S2luZ0NhbXAie" }, "eligibility": [] } ], "loyalty_membership": { "tier": "Walmart+ Assist" } } }, "PaymentMethod": { "type": "object", "properties": { "external_id": { "type": [ "string", "null" ], "description": "External identifier for the payment method provided by the merchant.", "example": "x7q9m2lbw5pazc" }, "type": { "type": "string", "enum": [ "CARD", "APPLE_PAY", "GOOGLE_PAY", "AMAZON_PAY", "PAYPAL", "CASH_APP", "VENMO", "AFFIRM", "KLARNA", "ONEPAY", "GIFT_CARD", "CASH", "BANK_ACCOUNT", "LOYALTY_POINTS", "CRYPTO", "UNRECOGNIZED" ], "description": "Type of the payment method.", "example": "CARD" }, "brand": { "type": [ "string", "null" ], "description": "Brand of the payment method. Includes `EBTSNAP`.", "example": "VISA" }, "last_four": { "type": [ "string", "null" ], "description": "Last 4 digits of the payment method, if a payment card.", "example": "5690" }, "name": { "type": [ "string", "null" ], "description": "Name of the payment method provided by the user.", "example": "Homer's credit card" }, "transaction_amount": { "type": [ "string", "null" ], "description": "Transaction amount associated with the payment method.", "example": "16.23" } } }, "TransactionPrice": { "type": "object", "properties": { "sub_total": { "type": [ "string", "null" ], "description": "Subtotal price of the transaction.", "example": "12.56" }, "adjustments": { "type": "array", "items": { "$ref": "#/components/schemas/Adjustment" }, "description": "List of price adjustments." }, "total": { "type": "string", "description": "Total price of the transaction.", "example": "16.23" }, "currency": { "type": [ "string", "null" ], "description": "Currency of the price. ISO 4217 format.", "example": "USD" } } }, "Shipping": { "type": [ "object", "null" ], "description": "Shipping information for the transaction.", "properties": { "location": { "$ref": "#/components/schemas/Location" } } }, "Location": { "type": [ "object", "null" ], "description": "Location information including recipient name and address.", "properties": { "address": { "$ref": "#/components/schemas/Address" }, "first_name": { "type": [ "string", "null" ], "maxLength": 255, "description": "First name of the recipient.", "example": "Ada" }, "last_name": { "type": [ "string", "null" ], "maxLength": 255, "description": "Last name of the recipient.", "example": "Lovelace" } } }, "Address": { "type": [ "object", "null" ], "description": "Address information.", "properties": { "line1": { "type": [ "string", "null" ], "description": "First line of the address.", "example": "123 Main St" }, "line2": { "type": [ "string", "null" ], "description": "Second line of the address.", "example": "Floor 4" }, "city": { "type": [ "string", "null" ], "description": "City portion of the address.", "example": "Los Angeles" }, "region": { "type": [ "string", "null" ], "description": "Region portion of the address, usually a state abbreviation. Must be an ISO 3166-2 sub-division code.", "example": "CA" }, "postal_code": { "type": [ "string", "null" ], "description": "Postal code of the address.", "example": "94105" }, "country": { "type": "string", "description": "Country portion of the address. Must be an ISO 3166-1 alpha-2 code.", "example": "US" } } }, "CartPrice": { "type": "object", "properties": { "sub_total": { "type": "string", "description": "Subtotal price of the products in the cart.", "example": "12.56" }, "adjustments": { "type": "array", "items": { "$ref": "#/components/schemas/Adjustment" }, "description": "List of price adjustments." }, "total": { "type": "string", "description": "Total price of the products in the cart.", "example": "16.23" }, "currency": { "type": "string", "description": "Currency of the price. ISO 4217 format.", "example": "USD" } } }, "Product": { "type": "object", "properties": { "external_id": { "type": [ "string", "null" ], "description": "External identifier for the product.", "example": "10315643" }, "gtin": { "type": [ "string", "null" ], "description": "Global Trade Item Number (GTIN-14) for the product. Always stored as a 14-digit zero-padded string, normalized from UPC, EAN, GTIN-12, or GTIN-13 formats.", "example": "00012345678901", "x-mint": { "post": ["coming soon"] } }, "name": { "type": "string", "description": "Name of the product.", "example": "Great Value Turkey Flavored Stuffing Mix" }, "description": { "type": [ "string", "null" ], "description": "Description of the product.", "example": "Savory and comforting stuffing mix seasoned with classic turkey flavor and a blend of aromatic herbs and spices. Made with soft, seasoned bread cubes that bake up moist on the inside with a lightly crisp top." }, "category": { "type": "string", "enum": [ "CATEGORY1", "CATEGORY2", "CATEGORY3", "UNRECOGNIZED" ], "description": "The category of the product.", "example": "CATEGORY1", "x-mint": { "post": ["coming soon"] } }, "url": { "type": [ "string", "null" ], "description": "URL of the product.", "example": "https://www.example.com/ip/10315643" }, "image_url": { "type": [ "string", "null" ], "description": "URL of the product image.", "example": "https://storage.googleapis.com/txn-product-images/doordash/33972462636.jpg" }, "quantity": { "type": [ "number", "null" ], "format": "double", "description": "Number of units of the product purchased in the transaction.", "example": 1 }, "price": { "anyOf": [ { "$ref": "#/components/schemas/ProductPrice" }, { "type": "null" } ] }, "seller": { "anyOf": [ { "$ref": "#/components/schemas/Seller" }, { "type": "null" } ], "description": "Seller information for the specific product, often different than the merchant if a marketplace. Nullable, but never an empty object/dictionary (`{}`)." }, "eligibility": { "type": "array", "items": { "type": "string", "enum": [ "FSA/HSA" ] }, "description": "The eligibility of the product. `EBT`, `EBTSNAP`, `EBTCASH`, and `WIC` values are coming soon.", "example": [ "FSA/HSA" ] } } }, "Seller": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Name of the seller offering the product.", "example": "KingCamp Outdoor Products Co., Ltd." }, "url": { "type": [ "string", "null" ], "description": "URL of the seller's page within the merchant's marketplace.", "example": "https://www.example.com/browse/kingcamp/YnJhbmQ6S2luZ0NhbXAie" } } }, "Adjustment": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "DISCOUNT", "TAX", "TIP", "FEE", "REFUND", "UNRECOGNIZED" ], "description": "Type of adjustment.", "example": "TAX" }, "label": { "type": [ "string", "null" ], "description": "Label of the adjustment from the merchant.", "example": "NYC local sales tax" }, "amount": { "type": "string", "description": "Amount of the adjustment.", "example": "3.67" } } }, "ProductPrice": { "type": "object", "properties": { "sub_total": { "type": [ "string", "null" ], "description": "Subtotal price of the product in the transaction.", "example": "12.56" }, "total": { "type": [ "string", "null" ], "description": "Total price of the product in the transaction.", "example": "12.56" }, "unit_price": { "type": [ "string", "null" ], "description": "Price of the product per unit.", "example": "12.56" } } }, "Fulfillment": { "type": "object", "description": "Fulfillment information containing the currently selected fulfillment preference in the root and additional fulfillment options in `fulfillment.options`.", "properties": { "id": { "type": "string", "description": "Unique identifier for the fulfillment preference.", "example": "5cfbe095d0cb9e597e316170d6ee9a6c667bddcde4a999222d2cc2b5bbfef7cf" }, "type": { "type": "string", "description": "Type of fulfillment preference", "oneOf": [ { "enum": [ "UNSCHEDULED_DELIVERY" ], "title": "Unscheduled Delivery", "description": "Delivered from a fulfillment center to the user's address without a scheduled delivery window." }, { "enum": [ "SCHEDULED_DELIVERY" ], "title": "Scheduled Delivery", "description": "Delivered from a store or local fulfillment center to the user's address in a scheduled delivery window." }, { "enum": [ "UNSCHEDULED_PICKUP" ], "title": "Unscheduled Pickup", "description": "Picked up from a store by the user without a scheduled pickup window." } ], "example": "SCHEDULED_DELIVERY" }, "label": { "type": "string", "description": "Label of the fulfillment preference from the merchant.", "example": "Express delivery" }, "availabilityStart": { "type": [ "string", "null" ], "description": "Timestamp of the fulfillment preference in UTC. ISO 8601 format. If unscheduled, this value represents the date of the fulfillment. If scheduled, this value represents the beginning of the scheduled window.", "example": "2025-08-10T15:00:00Z" }, "availabilityEnd": { "type": [ "string", "null" ], "description": "Timestamp of the end of the scheduled fulfillment preference window in UTC. ISO 8601 format. If unscheduled, this value will be the same as the availabilityStart. If scheduled, this value represents the end of the scheduled window.", "example": "2025-08-10T15:00:00Z" }, "price": { "type": "object", "description": "Price information for the fulfillment preference.", "properties": { "total": { "type": "string", "description": "Total price of the fulfillment preference. This is included in `price.total` for the entire cart, despite not being listed in `price.adjustments`.", "example": "0.00" }, "currency": { "type": "string", "description": "Currency of the price. ISO 4217 format.", "example": "USD" } } } } }, "Error": { "type": "object", "properties": { "error_type": { "type": "string", "description": "Type of error.", "enum": [ "INVALID_INPUT", "INVALID_REQUEST", "USER_ERROR", "SESSION_ERROR", "MERCHANT_ACCOUNT_ERROR", "MERCHANT_ERROR", "SUBSCRIPTION_ERROR", "TRANSACTION_ERROR", "CART_ERROR" ], "example": "INVALID_REQUEST" }, "error_code": { "type": "string", "description": "Error code.", "enum": [ "INVALID_API_KEYS", "INVALID_FIELD", "INVALID_JWE", "INVALID_CURSOR_FORMAT", "USER_NOT_FOUND", "MERCHANT_ACCOUNT_NOT_FOUND", "MERCHANT_ACCOUNT_DISCONNECTED", "SESSION_NOT_FOUND", "EXTEND_NOT_SUPPORTED", "MERCHANT_UNAVAILABLE", "NO_ACCESS", "TRANSACTION_NOT_FOUND", "NO_TRANSACTIONS", "SUBSCRIPTION_NOT_FOUND", "CANCELLABLE_SUBSCRIPTION_NOT_FOUND", "MULTIPLE_CANCELLABLE_SUBSCRIPTIONS_FOUND", "ONGOING_OPERATION", "CART_NOT_FOUND", "FULFILLMENT_NOT_FOUND" ], "example": "INVALID_FIELD" }, "error_message": { "type": "string", "description": "Detailed error message.", "example": "The limit may not be greater than 10." } } }, "SyncCartSucceededWebhook": { "type": "object", "properties": { "event": { "type": "string", "description": "Name of the webhook event.", "example": "SYNC_CART_SUCCEEDED" }, "external_user_id": { "type": "string", "description": "Unique identifier for the user.", "example": "123abc" }, "merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 45 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Walmart" }, "logo": { "type": "string", "description": "Logo of the merchant.", "example": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png?auto=format&w=240" } } }, "data": { "type": "object", "properties": { "cart": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "external_id": { "type": "string", "description": "External identifier for the product.", "example": "123abc" }, "fulfillment": { "allOf": [ { "$ref": "#/components/schemas/Fulfillment" }, { "type": "object", "properties": { "options": { "type": "array", "items": { "$ref": "#/components/schemas/Fulfillment" }, "description": "Alternative fulfillment options to the currently selected fulfillment preference." } } } ] } } }, "description": "List of products in the cart." }, "delivery_location": { "type": [ "object", "null" ], "description": "Delivery location for the cart.", "properties": { "address": { "type": "object", "description": "", "properties": { "line1": { "type": "string", "description": "First line of the delivery address.", "example": "123 Main St" }, "line2": { "type": [ "string", "null" ], "description": "Second line of the delivery address.", "example": "Floor 4" }, "city": { "type": "string", "description": "City portion of the delivery address.", "example": "Los Angeles" }, "region": { "type": "string", "description": "Region portion of the delivery address, usually a state abbreviation. Must be an ISO 3166-2 sub-division code.", "example": "CA" }, "postal_code": { "type": "string", "description": "Postal code of the delivery address.", "example": "94105" }, "country": { "type": "string", "description": "Country portion of the delivery address. Must be an ISO 3166-1 alpha-2 code.", "example": "US" } } }, "first_name": { "type": [ "string", "null" ], "maxLength": 255, "description": "First name for the delivery address.", "example": "Ada" }, "last_name": { "type": [ "string", "null" ], "maxLength": 255, "description": "Last name for the delivery address.", "example": "Lovelace" }, "phone_number": { "type": [ "string", "null" ], "description": "Phone number for the delivery address in E.164 format.", "example": "+11234567890" } } }, "price": { "$ref": "#/components/schemas/CartPrice" } } } } }, "timestamp": { "type": "integer", "description": "Unix timestamp of the webhook event in UTC.", "example": 1710864923198 } } }, "MerchantStatusUpdateWebhook": { "type": "object", "properties": { "event": { "type": "string", "description": "Name of the webhook event.", "example": "MERCHANT_STATUS_UPDATE" }, "merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 10 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Uber" }, "category": { "type": "string", "description": "Category of the merchant.", "example": "Transportation" }, "logo": { "type": "string", "description": "Logo of the merchant.", "example": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png?auto=format&w=240" } } }, "data": { "type": "object", "properties": { "type": { "type": "string", "description": "Product type.", "enum": [ "card_switcher", "transaction_link", "shopping" ], "example": "card_switcher" }, "status": { "type": "string", "description": "Merchant availability status.", "enum": [ "UP", "DOWN" ], "example": "UP" }, "platform": { "type": "string", "description": "Platform the status applies to.", "enum": [ "ios", "android", "web" ], "example": "ios" }, "sdk": { "type": [ "string", "null" ], "description": "Minimum SDK version the status applies to.", "example": "1.0.0" } } }, "timestamp": { "type": "integer", "description": "Unix timestamp of the webhook event in UTC.", "example": 1710864923198 } } }, "SyncCartFailedWebhook": { "type": "object", "properties": { "event": { "type": "string", "description": "Name of the webhook event.", "example": "SYNC_CART_FAILED" }, "external_user_id": { "type": "string", "description": "Unique identifier for the user.", "example": "123abc" }, "merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 7 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Best Buy" }, "logo": { "type": "string", "description": "Logo of the merchant.", "example": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png?auto=format&w=240" } } }, "data": { "type": "object", "properties": { "reason": { "type": "string", "description": "Reason for the failure.", "example": "product out of stock" } } }, "timestamp": { "type": "integer", "description": "Unix timestamp of the webhook event in UTC.", "example": 1710864923198 } } }, "CheckoutSucceededWebhook": { "type": "object", "properties": { "event": { "type": "string", "description": "Name of the webhook event.", "example": "CHECKOUT_SUCCEEDED" }, "external_user_id": { "type": "string", "description": "Unique identifier for the user.", "example": "123abc" }, "merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 7 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Best Buy" }, "logo": { "type": "string", "description": "Logo of the merchant.", "example": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png?auto=format&w=240" } } }, "data": { "type": "object", "properties": { "transactions": { "type": "array", "description": "Array of transaction objects.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "UUID for the transaction.", "example": "13da3c28-a068-4642-9ce2-b730cfda5f5f" } } } } } }, "timestamp": { "type": "integer", "description": "Unix timestamp of the webhook event in UTC.", "example": 1710864923198 } } }, "CheckoutFailedWebhook": { "type": "object", "properties": { "event": { "type": "string", "description": "Name of the webhook event.", "example": "CHECKOUT_FAILED" }, "external_user_id": { "type": "string", "description": "Unique identifier for the user.", "example": "123abc" }, "merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 7 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Best Buy" }, "logo": { "type": "string", "description": "Logo of the merchant.", "example": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png?auto=format&w=240" } } }, "data": { "type": "object", "properties": { "reason": { "type": "string", "description": "Reason for the failure.", "example": "card declined" } } }, "timestamp": { "type": "integer", "description": "Unix timestamp of the webhook event in UTC.", "example": 1710864923198 } } }, "VaultingSucceededWebhook": { "type": "object", "properties": { "event": { "type": "string", "description": "Name of the webhook event.", "example": "VAULTING_SUCCEEDED" }, "session_id": { "type": "string", "description": "Unique identifier for the session.", "example": "fb5aa994-ed1c-4c3e-b29a-b2a53222e584" }, "task_id": { "type": "integer", "description": "Unique identifier for the task.", "example": 25605 }, "external_user_id": { "type": "string", "description": "Unique identifier for the user.", "example": "3dcbb19a-b2f1-4a7b-8792-d76027b627b3" }, "merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 19 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "DoorDash" }, "logo": { "type": "string", "description": "Logo URL for the merchant.", "example": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png?auto=format&w=240" } } }, "data": { "type": "object", "properties": { "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Custom key-value pairs provided during session creation or SDK invocation. Only present if metadata was provided.", "example": { "reference_token": "abc123", "trace_id": "def456" } } } }, "timestamp": { "type": "integer", "description": "Unix timestamp of the webhook event in UTC.", "example": 1710864923198 } } }, "VaultingFailedWebhook": { "type": "object", "properties": { "event": { "type": "string", "description": "Name of the webhook event.", "example": "VAULTING_FAILED" }, "session_id": { "type": "string", "description": "Unique identifier for the session.", "example": "fb5aa994-ed1c-4c3e-b29a-b2a53222e584" }, "task_id": { "type": "integer", "description": "Unique identifier for the task.", "example": 25605 }, "external_user_id": { "type": "string", "description": "Unique identifier for the user.", "example": "3dcbb19a-b2f1-4a7b-8792-d76027b627b3" }, "merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 19 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "DoorDash" }, "logo": { "type": "string", "description": "Logo URL for the merchant.", "example": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png?auto=format&w=240" } } }, "data": { "type": "object", "properties": { "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Custom key-value pairs provided during session creation or SDK invocation. Only present if metadata was provided.", "example": { "reference_token": "abc123", "trace_id": "def456" } } } }, "timestamp": { "type": "integer", "description": "Unix timestamp of the webhook event in UTC.", "example": 1710864923198 } } }, "CardUpdatedWebhook": { "type": "object", "properties": { "event": { "type": "string", "description": "Name of the webhook event.", "example": "CARD_UPDATED" }, "session_id": { "type": [ "string", "null" ], "description": "Unique identifier for the session.", "example": "fb5aa994-ed1c-4c3e-b29a-b2a53222e584" }, "task_id": { "type": "integer", "description": "Unique identifier for the task.", "example": 25605 }, "external_user_id": { "type": "string", "description": "Unique identifier for the user.", "example": "3dcbb19a-b2f1-4a7b-8792-d76027b627b3" }, "merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 11 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Uber" } } }, "data": { "type": "object", "properties": { "card_id": { "type": "string", "description": "Unique identifier for the card.", "example": "123456789" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Custom key-value pairs provided during session creation or SDK invocation. Only present if metadata was provided.", "example": { "reference_token": "abc123", "trace_id": "def456" } }, "subscriptions": { "type": [ "array", "null" ], "description": "An array of subscription IDs associated with the merchant account. This optional data & functionality can be enabled upon request. Use [Get Subscription By ID](/api-reference/products/subscriptions/get-by-id) to retrieve full subscription details.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the subscription.", "example": "ka8sdf0asdfm10as0a0sdfja7ssa8" } } }, "example": [ { "id": "ka8sdf0asdfm10as0a0sdfja7ssa8" }, { "id": "8asdh29qjss923kd0d920skd8sjd8" } ] } } }, "timestamp": { "type": "integer", "description": "Unix timestamp of the webhook event in UTC.", "example": 1710864923198 } } }, "CardFailedWebhook": { "type": "object", "properties": { "event": { "type": "string", "description": "Name of the webhook event.", "example": "CARD_FAILED" }, "session_id": { "type": [ "string", "null" ], "description": "Unique identifier for the session.", "example": "fb5aa994-ed1c-4c3e-b29a-b2a53222e584" }, "task_id": { "type": "integer", "description": "Unique identifier for the task.", "example": 25605 }, "external_user_id": { "type": "string", "description": "Unique identifier for the user.", "example": "3dcbb19a-b2f1-4a7b-8792-d76027b627b3" }, "merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 11 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Uber" } } }, "data": { "type": "object", "properties": { "card_id": { "type": "string", "description": "Unique identifier for the card.", "example": "123456789" }, "reason": { "type": "string", "description": "Reason for the failure.", "example": "card expired" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Custom key-value pairs provided during session creation or SDK invocation. Only present if metadata was provided.", "example": { "reference_token": "abc123", "trace_id": "def456" } } } }, "timestamp": { "type": "integer", "description": "Unix timestamp of the webhook event in UTC.", "example": 1710864923198 } } }, "NewTransactionsAvailableWebhook": { "type": "object", "properties": { "event": { "type": "string", "description": "Name of the webhook event.", "example": "NEW_TRANSACTIONS_AVAILABLE" }, "external_user_id": { "type": "string", "description": "Unique identifier for the user.", "example": "123abc" }, "merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 36 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Uber Eats" } } }, "timestamp": { "type": "integer", "description": "Unix timestamp of the webhook event in UTC.", "example": 1710864923198 }, "data": { "type": "object", "description": "Holds additional data as applicable. Present only when additional data exists.", "properties": { "initial_sync": { "type": "boolean", "description": "When `true`, indicates the last 1 month of transaction history for the merchant account is available. This does not mean the entire length of transaction history is available yet, which will come in a subsequent webhook event of the same type once available. Omitted on subsequent webhook events for the same merchant account. Useful for designing a user experience that must be more immediate, albeit with less transaction data.", "example": true } } } } }, "UpdatedTransactionsAvailableWebhook": { "type": "object", "properties": { "event": { "type": "string", "description": "Name of the webhook event.", "example": "UPDATED_TRANSACTIONS_AVAILABLE" }, "external_user_id": { "type": "string", "description": "Unique identifier for the user.", "example": "123abc" }, "merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 36 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Uber Eats" } } }, "updated": { "type": "array", "description": "Array of transaction UUIDs.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "UUID for the transaction.", "example": "13da3c28-a068-4642-9ce2-b730cfda5f5f" } } } }, "timestamp": { "type": "integer", "description": "Unix timestamp of the webhook event in UTC.", "example": 1710864923198 } } }, "AuthenticatedWebhook": { "type": "object", "properties": { "event": { "type": "string", "description": "Name of the webhook event.", "example": "AUTHENTICATED" }, "session_id": { "type": "string", "description": "Unique identifier for the session.", "example": "fb5aa994-ed1c-4c3e-b29a-b2a53222e584" }, "task_id": { "type": "integer", "description": "Unique identifier for the task.", "example": 25605 }, "external_user_id": { "type": "string", "description": "Unique identifier for the user.", "example": "3dcbb19a-b2f1-4a7b-8792-d76027b627b3" }, "merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 10 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Uber" } } }, "data": { "type": "object", "properties": { "card_id": { "type": [ "string", "null" ], "description": "Unique identifier for the card.", "example": "123456789" }, "send_card": { "type": "boolean", "description": "Whether to send a card.", "example": true }, "entrypoint": { "type": [ "string", "null" ], "description": "Entry point.", "example": "onboarding" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Custom key-value pairs provided during session creation or SDK invocation. Only present if metadata was provided.", "example": { "reference_token": "abc123", "trace_id": "def456" } } } }, "timestamp": { "type": "integer", "description": "Unix timestamp of the webhook event in UTC.", "example": 1710864923198 } } }, "CredentialsFailedWebhook": { "type": "object", "properties": { "event": { "type": "string", "description": "Name of the webhook event.", "example": "CREDENTIALS_FAILED" }, "session_id": { "type": "string", "description": "Unique identifier for the session.", "example": "fb5aa994-ed1c-4c3e-b29a-b2a53222e584" }, "task_id": { "type": "integer", "description": "Unique identifier for the task.", "example": 25605 }, "external_user_id": { "type": "string", "description": "Unique identifier for the user.", "example": "3dcbb19a-b2f1-4a7b-8792-d76027b627b3" }, "merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 10 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Uber" } } }, "data": { "type": "object", "properties": { "card_id": { "type": "string", "description": "Unique identifier for the card.", "example": "123456789" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Custom key-value pairs provided during session creation or SDK invocation. Only present if metadata was provided.", "example": { "reference_token": "abc123", "trace_id": "def456" } } } }, "timestamp": { "type": "integer", "description": "Unix timestamp of the webhook event in UTC.", "example": 1710864923198 } } }, "OtpRequiredWebhook": { "type": "object", "properties": { "event": { "type": "string", "description": "Name of the webhook event.", "example": "OTP_REQUIRED" }, "session_id": { "type": "string", "description": "Unique identifier for the session.", "example": "fb5aa994-ed1c-4c3e-b29a-b2a53222e584" }, "task_id": { "type": "integer", "description": "Unique identifier for the task.", "example": 25605 }, "external_user_id": { "type": "string", "description": "Unique identifier for the user.", "example": "3dcbb19a-b2f1-4a7b-8792-d76027b627b3" }, "merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 10 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Uber" } } }, "data": { "type": "object", "properties": { "card_id": { "type": "string", "description": "Unique identifier for the card.", "example": "123456789" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Custom key-value pairs provided during session creation or SDK invocation. Only present if metadata was provided.", "example": { "reference_token": "abc123", "trace_id": "def456" } } } }, "timestamp": { "type": "integer", "description": "Unix timestamp of the webhook event in UTC.", "example": 1710864923198 } } }, "OtpFailedWebhook": { "type": "object", "properties": { "event": { "type": "string", "description": "Name of the webhook event.", "example": "OTP_FAILED" }, "session_id": { "type": "string", "description": "Unique identifier for the session.", "example": "fb5aa994-ed1c-4c3e-b29a-b2a53222e584" }, "task_id": { "type": "integer", "description": "Unique identifier for the task.", "example": 25605 }, "external_user_id": { "type": "string", "description": "Unique identifier for the user.", "example": "3dcbb19a-b2f1-4a7b-8792-d76027b627b3" }, "merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 11 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Uber" } } }, "data": { "type": "object", "properties": { "card_id": { "type": "string", "description": "Unique identifier for the card.", "example": "123456789" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Custom key-value pairs provided during session creation or SDK invocation. Only present if metadata was provided.", "example": { "reference_token": "abc123", "trace_id": "def456" } } } }, "timestamp": { "type": "integer", "description": "Unix timestamp of the webhook event in UTC.", "example": 1710864923198 } } }, "QuestionsRequiredWebhook": { "type": "object", "properties": { "event": { "type": "string", "description": "Name of the webhook event.", "example": "QUESTIONS_REQUIRED" }, "session_id": { "type": "string", "description": "Unique identifier for the session.", "example": "fb5aa994-ed1c-4c3e-b29a-b2a53222e584" }, "task_id": { "type": "integer", "description": "Unique identifier for the task.", "example": 25605 }, "external_user_id": { "type": "string", "description": "Unique identifier for the user.", "example": "3dcbb19a-b2f1-4a7b-8792-d76027b627b3" }, "merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 10 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Uber" } } }, "data": { "type": "object", "properties": { "card_id": { "type": "string", "description": "Unique identifier for the card.", "example": "123456789" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Custom key-value pairs provided during session creation or SDK invocation. Only present if metadata was provided.", "example": { "reference_token": "abc123", "trace_id": "def456" } } } }, "timestamp": { "type": "integer", "description": "Unix timestamp of the webhook event in UTC.", "example": 1710864923198 } } }, "QuestionsFailedWebhook": { "type": "object", "properties": { "event": { "type": "string", "description": "Name of the webhook event.", "example": "QUESTIONS_FAILED" }, "session_id": { "type": "string", "description": "Unique identifier for the session.", "example": "fb5aa994-ed1c-4c3e-b29a-b2a53222e584" }, "task_id": { "type": "integer", "description": "Unique identifier for the task.", "example": 25605 }, "external_user_id": { "type": "string", "description": "Unique identifier for the user.", "example": "3dcbb19a-b2f1-4a7b-8792-d76027b627b3" }, "merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 10 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Uber" } } }, "data": { "type": "object", "properties": { "card_id": { "type": "string", "description": "Unique identifier for the card.", "example": "123456789" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Custom key-value pairs provided during session creation or SDK invocation. Only present if metadata was provided.", "example": { "reference_token": "abc123", "trace_id": "def456" } } } }, "timestamp": { "type": "integer", "description": "Unix timestamp of the webhook event in UTC.", "example": 1710864923198 } } }, "DobRequiredWebhook": { "type": "object", "properties": { "event": { "type": "string", "description": "Name of the webhook event.", "example": "DOB_REQUIRED" }, "session_id": { "type": "string", "description": "Unique identifier for the session.", "example": "fb5aa994-ed1c-4c3e-b29a-b2a53222e584" }, "task_id": { "type": "integer", "description": "Unique identifier for the task.", "example": 25605 }, "external_user_id": { "type": "string", "description": "Unique identifier for the user.", "example": "3dcbb19a-b2f1-4a7b-8792-d76027b627b3" }, "merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 10 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "CVS" } } }, "data": { "type": "object", "properties": { "card_id": { "type": "string", "description": "Unique identifier for the card.", "example": "123456789" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Custom key-value pairs provided during session creation or SDK invocation. Only present if metadata was provided.", "example": { "reference_token": "abc123", "trace_id": "def456" } } } }, "timestamp": { "type": "integer", "description": "Unix timestamp of the webhook event in UTC.", "example": 1710864923198 } } }, "DobFailedWebhook": { "type": "object", "properties": { "event": { "type": "string", "description": "Name of the webhook event.", "example": "DOB_FAILED" }, "session_id": { "type": "string", "description": "Unique identifier for the session.", "example": "fb5aa994-ed1c-4c3e-b29a-b2a53222e584" }, "task_id": { "type": "integer", "description": "Unique identifier for the task.", "example": 25605 }, "external_user_id": { "type": "string", "description": "Unique identifier for the user.", "example": "3dcbb19a-b2f1-4a7b-8792-d76027b627b3" }, "merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 10 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "CVS" } } }, "data": { "type": "object", "properties": { "card_id": { "type": "string", "description": "Unique identifier for the card.", "example": "123456789" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Custom key-value pairs provided during session creation or SDK invocation. Only present if metadata was provided.", "example": { "reference_token": "abc123", "trace_id": "def456" } } } }, "timestamp": { "type": "integer", "description": "Unix timestamp of the webhook event in UTC.", "example": 1710864923198 } } }, "LicenseRequiredWebhook": { "type": "object", "properties": { "event": { "type": "string", "description": "Name of the webhook event.", "example": "LICENSE_REQUIRED" }, "session_id": { "type": "string", "description": "Unique identifier for the session.", "example": "fb5aa994-ed1c-4c3e-b29a-b2a53222e584" }, "task_id": { "type": "integer", "description": "Unique identifier for the task.", "example": 25605 }, "external_user_id": { "type": "string", "description": "Unique identifier for the user.", "example": "3dcbb19a-b2f1-4a7b-8792-d76027b627b3" }, "merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 10 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Uber" } } }, "data": { "type": "object", "properties": { "card_id": { "type": "string", "description": "Unique identifier for the card.", "example": "123456789" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Custom key-value pairs provided during session creation or SDK invocation. Only present if metadata was provided.", "example": { "reference_token": "abc123", "trace_id": "def456" } } } }, "timestamp": { "type": "integer", "description": "Unix timestamp of the webhook event in UTC.", "example": 1710864923198 } } }, "LicenseFailedWebhook": { "type": "object", "properties": { "event": { "type": "string", "description": "Name of the webhook event.", "example": "LICENSE_FAILED" }, "session_id": { "type": "string", "description": "Unique identifier for the session.", "example": "fb5aa994-ed1c-4c3e-b29a-b2a53222e584" }, "task_id": { "type": "integer", "description": "Unique identifier for the task.", "example": 25605 }, "external_user_id": { "type": "string", "description": "Unique identifier for the user.", "example": "3dcbb19a-b2f1-4a7b-8792-d76027b627b3" }, "merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 10 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Uber" } } }, "data": { "type": "object", "properties": { "card_id": { "type": "string", "description": "Unique identifier for the card.", "example": "123456789" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Custom key-value pairs provided during session creation or SDK invocation. Only present if metadata was provided.", "example": { "reference_token": "abc123", "trace_id": "def456" } } } }, "timestamp": { "type": "integer", "description": "Unix timestamp of the webhook event in UTC.", "example": 1710864923198 } } }, "LoginApprovalWebhook": { "type": "object", "properties": { "event": { "type": "string", "description": "Name of the webhook event.", "example": "LOGIN_APPROVAL" }, "session_id": { "type": "string", "description": "Unique identifier for the session.", "example": "fb5aa994-ed1c-4c3e-b29a-b2a53222e584" }, "task_id": { "type": "integer", "description": "Unique identifier for the task.", "example": 25605 }, "external_user_id": { "type": "string", "description": "Unique identifier for the user.", "example": "3dcbb19a-b2f1-4a7b-8792-d76027b627b3" }, "merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 10 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Uber" } } }, "data": { "type": "object", "properties": { "card_id": { "type": "string", "description": "Unique identifier for the card.", "example": "123456789" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Custom key-value pairs provided during session creation or SDK invocation. Only present if metadata was provided.", "example": { "reference_token": "abc123", "trace_id": "def456" } } } }, "timestamp": { "type": "integer", "description": "Unix timestamp of the webhook event in UTC.", "example": 1710864923198 } } }, "AccountsRetrievedWebhook": { "type": "object", "properties": { "event": { "type": "string", "description": "Name of the webhook event.", "example": "ACCOUNTS_RETRIEVED" }, "session_id": { "type": "string", "description": "Unique identifier for the session.", "example": "fb5aa994-ed1c-4c3e-b29a-b2a53222e584" }, "task_id": { "type": "integer", "description": "Unique identifier for the task.", "example": 25605 }, "external_user_id": { "type": "string", "description": "Unique identifier for the user.", "example": "3dcbb19a-b2f1-4a7b-8792-d76027b627b3" }, "merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 26 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Google Keychain" } } }, "data": { "type": "object", "properties": { "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Custom key-value pairs provided during session creation or SDK invocation. Only present if metadata was provided.", "example": { "reference_token": "abc123", "trace_id": "def456" } } } }, "timestamp": { "type": "integer", "description": "Unix timestamp of the webhook event in UTC.", "example": 1710864923198 } } }, "AccountLoginRequiredWebhook": { "type": "object", "properties": { "event": { "type": "string", "description": "Name of the webhook event.", "example": "ACCOUNT_LOGIN_REQUIRED" }, "external_user_id": { "type": "string", "description": "Unique identifier for the user.", "example": "3dcbb19a-b2f1-4a7b-8792-d76027b627b3" }, "merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 36 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Uber Eats" }, "logo": { "type": "string", "description": "Logo of the merchant.", "example": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png?auto=format&w=240" } } }, "timestamp": { "type": "integer", "description": "Unix timestamp of the webhook event in UTC.", "example": 1710864923198 } } }, "NewDetectedAccountsAvailableWebhook": { "type": "object", "properties": { "event": { "type": "string", "description": "Name of the webhook event.", "example": "NEW_DETECTED_ACCOUNTS_AVAILABLE" }, "external_user_id": { "type": "string", "description": "Unique identifier for the user.", "example": "3dcbb19a-b2f1-4a7b-8792-d76027b627b3" }, "data": { "type": "object", "properties": { "detected_accounts": { "type": "array", "description": "Merchants where the user has a detected account. Includes only merchants supported on the Knot platform.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 35 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Spotify" }, "logo": { "type": "string", "description": "Logo of the merchant.", "example": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png" } } } } }, "example": { "detected_accounts": [ { "id": 35, "name": "Spotify", "logo": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png" }, { "id": 44, "name": "Walmart", "logo": "https://knot.imgix.net/merchants/walmart.png" }, { "id": 84, "name": "Chewy", "logo": "https://knot.imgix.net/merchants/chewy.png" }, { "id": 71, "name": "Verizon", "logo": "https://knot.imgix.net/merchants/verizon.png" }, { "id": 53, "name": "Airbnb", "logo": "https://knot.imgix.net/merchants/airbnb.png" } ] } }, "timestamp": { "type": "integer", "description": "Unix timestamp of the webhook event in UTC.", "example": 1710864923198 } } }, "AccountDetectionFailedWebhook": { "type": "object", "properties": { "event": { "type": "string", "description": "Name of the webhook event.", "example": "ACCOUNT_DETECTION_FAILED" }, "external_user_id": { "type": "string", "description": "Unique identifier for the user.", "example": "3dcbb19a-b2f1-4a7b-8792-d76027b627b3" }, "merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 60 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Apple" } } }, "timestamp": { "type": "integer", "description": "Unix timestamp of the webhook event in UTC.", "example": 1710864923198 } } }, "CancellationSucceededWebhook": { "type": "object", "properties": { "event": { "type": "string", "description": "Name of the webhook event.", "example": "CANCELLATION_SUCCEEDED" }, "external_user_id": { "type": "string", "description": "Unique identifier for the user.", "example": "3dcbb19a-b2f1-4a7b-8792-d76027b627b3" }, "merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 11 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Uber" } } }, "data": { "type": "object", "properties": { "subscription_id": { "type": "string", "description": "Unique identifier for the cancelled subscription.", "example": "ka8sdf0asdfm10as0a0sdfja7ssa8" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Custom key-value pairs provided during session creation or SDK invocation. Only present if metadata was provided.", "example": { "reference_token": "abc123", "trace_id": "def456" } } } }, "timestamp": { "type": "integer", "description": "Unix timestamp of the webhook event in UTC.", "example": 1710864923198 } } }, "NewSubscriptionsAvailableWebhook": { "type": "object", "properties": { "event": { "type": "string", "description": "Name of the webhook event.", "example": "NEW_SUBSCRIPTIONS_AVAILABLE" }, "external_user_id": { "type": "string", "description": "Unique identifier for the user.", "example": "123abc" }, "merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 36 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Netflix" } } }, "data": { "type": "object", "properties": { "subscriptions": { "type": "array", "description": "Array of IDs for newly detected subscriptions.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the subscription.", "example": "ka8sdf0asdfm10as0a0sdfja7ssa8" } } } } } }, "timestamp": { "type": "integer", "description": "Unix timestamp of the webhook event in UTC.", "example": 1710864923198 } } }, "UpdatedSubscriptionsAvailableWebhook": { "type": "object", "properties": { "event": { "type": "string", "description": "Name of the webhook event.", "example": "UPDATED_SUBSCRIPTIONS_AVAILABLE" }, "external_user_id": { "type": "string", "description": "Unique identifier for the user.", "example": "123abc" }, "merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 36 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Netflix" } } }, "data": { "type": "object", "properties": { "subscriptions": { "type": "array", "description": "Array of IDs for subscriptions with updated data.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the subscription.", "example": "8asdh29qjss923kd0d920skd8sjd8" } } } } } }, "timestamp": { "type": "integer", "description": "Unix timestamp of the webhook event in UTC.", "example": 1710864923198 } } }, "CancellationFailedWebhook": { "type": "object", "properties": { "event": { "type": "string", "description": "Name of the webhook event.", "example": "CANCELLATION_FAILED" }, "external_user_id": { "type": "string", "description": "Unique identifier for the user.", "example": "3dcbb19a-b2f1-4a7b-8792-d76027b627b3" }, "merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 11 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Uber" } } }, "data": { "type": "object", "properties": { "subscription_id": { "type": "string", "description": "Unique identifier for the subscription that failed to be cancelled.", "example": "ka8sdf0asdfm10as0a0sdfja7ssa8" }, "reason": { "type": "string", "description": "Reason for the failure.", "example": "subscription already cancelled" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Custom key-value pairs provided during session creation or SDK invocation. Only present if metadata was provided.", "example": { "reference_token": "abc123", "trace_id": "def456" } } } }, "timestamp": { "type": "integer", "description": "Unix timestamp of the webhook event in UTC.", "example": 1710864923198 } } }, "LoyaltyMembership": { "type": [ "object", "null" ], "properties": { "tier": { "type": [ "string", "null" ], "description": "Tier of the loyalty membership.", "example": "Walmart+ Assist" } } }, "SubscriptionMerchant": { "type": "object", "description": "The merchant account linked by the user.", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 18 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "Hulu" }, "category": { "type": "string", "description": "Category of the merchant.", "example": "Streaming" }, "logo": { "type": "string", "description": "URL of the merchant's logo.", "example": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png" }, "parent_merchant": { "oneOf": [ { "$ref": "#/components/schemas/MerchantFull" }, { "type": "null" } ], "description": "Parent merchant of the merchant account linked by the user, or `null` when the linked merchant has no parent. E.g. `Google` is the parent of `YouTube TV` and `Amazon` is the parent of `Prime Video`." } } }, "PortDataSucceededWebhook": { "type": "object", "properties": { "event": { "type": "string", "description": "Name of the webhook event.", "example": "PORT_DATA_SUCCEEDED" }, "session_id": { "type": "string", "description": "Unique identifier for the session.", "example": "fb5aa994-ed1c-4c3e-b29a-b2a53222e584" }, "task_id": { "type": "integer", "description": "Unique identifier for the task.", "example": 25605 }, "external_user_id": { "type": "string", "description": "Unique identifier for the user.", "example": "3dcbb19a-b2f1-4a7b-8792-d76027b627b3" }, "merchant": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the merchant.", "example": 296 }, "name": { "type": "string", "description": "Name of the merchant.", "example": "AT&T" }, "logo": { "type": "string", "description": "Logo URL for the merchant.", "example": "https://knot.imgix.net/merchants/eg2HJmeltHCvsQmJTSQPCIJT3CBaPA2gV0HixEQO.png?auto=format&w=240" } } }, "data": { "type": "object", "properties": { "user": { "type": [ "object", "null" ], "description": "Account holder details on file with the carrier.", "properties": { "name": { "type": [ "object", "null" ], "properties": { "first_name": { "type": [ "string", "null" ], "description": "First name of the account holder.", "example": "Ada" }, "last_name": { "type": [ "string", "null" ], "description": "Last name of the account holder.", "example": "Lovelace" } } }, "address": { "type": [ "object", "null" ], "description": "Address of the account holder on file with the carrier.", "properties": { "street": { "type": [ "string", "null" ], "description": "First line of the address.", "example": "100 Main Street" }, "street2": { "type": [ "string", "null" ], "description": "Second line of the address.", "example": "#100" }, "city": { "type": [ "string", "null" ], "description": "City portion of the address.", "example": "NEW YORK" }, "region": { "type": [ "string", "null" ], "description": "Region portion of the address, usually a state abbreviation. Must be an ISO 3166-2 sub-division code.", "example": "NY" }, "postal_code": { "type": [ "string", "null" ], "description": "Postal code of the address.", "example": "12345" }, "country": { "type": [ "string", "null" ], "description": "Country portion of the address. Must be an ISO 3166-1 alpha-2 code.", "example": "US" } } }, "phone_number": { "type": [ "string", "null" ], "description": "Phone number to be ported to another carrier, in E.164 format.", "example": "+11234567890" } } }, "account_number": { "type": [ "string", "null" ], "description": "Account number for the user's phone plan with the carrier.", "example": "123456789012" }, "transfer_pin": { "type": [ "object", "null" ], "description": "PIN that authorizes porting the phone number to another carrier.", "properties": { "pin": { "type": [ "string", "null" ], "description": "PIN issued by the carrier. Also referred to as a number transfer PIN or port-out PIN.", "example": "123456" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO timestamp when the PIN expires. `null` if the carrier does not publish an expiration.", "example": "2026-08-28T17:45:00Z" } } }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Custom key-value pairs provided during session creation or SDK invocation. Only present if metadata was provided.", "example": { "reference_token": "abc123", "trace_id": "def456" } } } }, "timestamp": { "type": "integer", "description": "Unix timestamp of the webhook event in UTC.", "example": 1710864923198 } } } }, "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic", "description": "Basic authentication header of the form `Basic `, where `` is the base64-encoded string `username:password`. Use your `client_id` as the `username` and your `secret` as the `password` value." } } } }