Sync Transactions

Changed on Nov 3, 2026

Sync a user's transactions for a merchant account using cursor-based pagination.

post/transactions/sync

Request

Base URL
https://development.knotapi.com
URL
https://development.knotapi.com/transactions/sync
Auth
HTTP basic

Request body

merchant_idinteger required

Unique identifier for the merchant.

external_user_idstring required

Your unique identifier for the user.

cursorstring

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.

limitinteger nullable

Maximum number of transactions to retrieve (min: 1, max: 100).

Example request

{
  "merchant_id": 45,
  "external_user_id": "abc",
  "cursor": "eyJpZCI6MjI3ODEsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
  "limit": 100
}

Response

Successful request.

next_cursorstring nullable

Cursor token for the next page of transactions.

limitinteger

Number of transactions returned based on the limit provided.

Example response

{
  "merchant": {
    "id": 45,
    "name": "Walmart"
  },
  "transactions": [
    {
      "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"
      }
    }
  ],
  "limit": 5
}

Changes

Nov 3, 2026f10ecfa12c00 Revision changes
- breaking
  the //// response's property type changed from integer null to number null, and format from no format to double for status
- warning
  added the new CANCELLABLE_SUBSCRIPTION_NOT_FOUND enum value to the response property for the response status
- warning
  added the new CANCELLABLE_SUBSCRIPTION_NOT_FOUND enum value to the response property for the response status
- warning
  added the new CANCELLABLE_SUBSCRIPTION_NOT_FOUND enum value to the response property for the response status
- warning
  added the new CANCELLABLE_SUBSCRIPTION_NOT_FOUND enum value to the response property for the response status
- warning
  added the new CRYPTO enum value to the //// response property for the response status
- warning
  added the new ENVIRONMENT_MISMATCH enum value to the response property for the response status
- warning
  added the new ENVIRONMENT_MISMATCH enum value to the response property for the response status
- warning
  added the new ENVIRONMENT_MISMATCH enum value to the response property for the response status
- warning
  added the new ENVIRONMENT_MISMATCH enum value to the response property for the response status
- warning
  added the new INSUFFICIENT_ROLE enum value to the response property for the response status
- warning
  added the new INSUFFICIENT_ROLE enum value to the response property for the response status
- warning
  added the new INSUFFICIENT_ROLE enum value to the response property for the response status
- warning
  added the new INSUFFICIENT_ROLE enum value to the response property for the response status
- warning
  added the new INSUFFICIENT_SCOPE enum value to the response property for the response status
- warning
  added the new INSUFFICIENT_SCOPE enum value to the response property for the response status
- warning
  added the new INSUFFICIENT_SCOPE enum value to the response property for the response status
- warning
  added the new INSUFFICIENT_SCOPE enum value to the response property for the response status
- warning
  added the new INVALID_ACCESS_TOKEN enum value to the response property for the response status
- warning
  added the new INVALID_ACCESS_TOKEN enum value to the response property for the response status
- warning
  added the new INVALID_ACCESS_TOKEN enum value to the response property for the response status
- warning
  added the new INVALID_ACCESS_TOKEN enum value to the response property for the response status
- warning
  added the new MULTIPLE_CANCELLABLE_SUBSCRIPTIONS_FOUND enum value to the response property for the response status
- warning
  added the new MULTIPLE_CANCELLABLE_SUBSCRIPTIONS_FOUND enum value to the response property for the response status
- warning
  added the new MULTIPLE_CANCELLABLE_SUBSCRIPTIONS_FOUND enum value to the response property for the response status
- warning
  added the new MULTIPLE_CANCELLABLE_SUBSCRIPTIONS_FOUND enum value to the response property for the response status
- warning
  added the new RATE_LIMIT_EXCEEDED enum value to the response property for the response status
- warning
  added the new RATE_LIMIT_EXCEEDED enum value to the response property for the response status
- warning
  added the new RATE_LIMIT_EXCEEDED enum value to the response property for the response status
- warning
  added the new RATE_LIMIT_EXCEEDED enum value to the response property for the response status
- warning
  added the new REQUEST_LOG_ERROR enum value to the response property for the response status
- warning
  added the new REQUEST_LOG_ERROR enum value to the response property for the response status
- warning
  added the new REQUEST_LOG_ERROR enum value to the response property for the response status
- warning
  added the new REQUEST_LOG_ERROR enum value to the response property for the response status
- warning
  added the new REQUEST_LOG_NOT_FOUND enum value to the response property for the response status
- warning
  added the new REQUEST_LOG_NOT_FOUND enum value to the response property for the response status
- warning
  added the new REQUEST_LOG_NOT_FOUND enum value to the response property for the response status
- warning
  added the new REQUEST_LOG_NOT_FOUND enum value to the response property for the response status
- warning
  added the new REQUEST_LOG_QUERY_TIMEOUT enum value to the response property for the response status
- warning
  added the new REQUEST_LOG_QUERY_TIMEOUT enum value to the response property for the response status
- warning
  added the new REQUEST_LOG_QUERY_TIMEOUT enum value to the response property for the response status
- warning
  added the new REQUEST_LOG_QUERY_TIMEOUT enum value to the response property for the response status
- warning
  added the new WEBHOOK_ENDPOINT_ALREADY_EXISTS enum value to the response property for the response status
- warning
  added the new WEBHOOK_ENDPOINT_ALREADY_EXISTS enum value to the response property for the response status
- warning
  added the new WEBHOOK_ENDPOINT_ALREADY_EXISTS enum value to the response property for the response status
- warning
  added the new WEBHOOK_ENDPOINT_ALREADY_EXISTS enum value to the response property for the response status
- warning
  added the new WEBHOOK_ENDPOINT_ERROR enum value to the response property for the response status
- warning
  added the new WEBHOOK_ENDPOINT_ERROR enum value to the response property for the response status
- warning
  added the new WEBHOOK_ENDPOINT_ERROR enum value to the response property for the response status
- warning
  added the new WEBHOOK_ENDPOINT_ERROR enum value to the response property for the response status
- warning
  added the new WEBHOOK_ENDPOINT_LIMIT_REACHED enum value to the response property for the response status
- warning
  added the new WEBHOOK_ENDPOINT_LIMIT_REACHED enum value to the response property for the response status
- warning
  added the new WEBHOOK_ENDPOINT_LIMIT_REACHED enum value to the response property for the response status
- warning
  added the new WEBHOOK_ENDPOINT_LIMIT_REACHED enum value to the response property for the response status
- warning
  added the new WEBHOOK_ENDPOINT_NOT_FOUND enum value to the response property for the response status
- warning
  added the new WEBHOOK_ENDPOINT_NOT_FOUND enum value to the response property for the response status
- warning
  added the new WEBHOOK_ENDPOINT_NOT_FOUND enum value to the response property for the response status
- warning
  added the new WEBHOOK_ENDPOINT_NOT_FOUND enum value to the response property for the response status

Operation history