> ## Documentation Index > Fetch the complete documentation index at: https://docs.knotapi.com/llms.txt > Use this file to discover all available pages before exploring further. # Sync Transactions > Sync a user's transactions for a merchant account using cursor-based pagination. ## OpenAPI ````yaml POST /transactions/sync 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: [] paths: /transactions/sync: post: description: >- Sync a user's transactions for a merchant account using cursor-based pagination. operationId: transaction_sync 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. On 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 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 external_user_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_CURSOR_FORMAT 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 components: schemas: Merchant: type: object required: - id - name properties: id: type: integer description: Unique identifier for the merchant. example: 45 name: type: string description: Name of the merchant. example: Walmart 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 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 - 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. Shipping: type: - object - 'null' description: Shipping information for the transaction. properties: location: $ref: '#/components/schemas/Location' 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 - 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. 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 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: - integer - 'null' 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 LoyaltyMembership: type: - object - 'null' properties: tier: type: - string - 'null' description: Tier of the loyalty membership. example: Walmart+ Assist 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 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' 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 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 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. ````