---
title: "POST /transactions/sync"
method: POST
path: "/transactions/sync"
---

# POST /transactions/sync

`POST /transactions/sync`

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

## Request body

- object
  - `merchant_id` integer, required — Unique identifier for the merchant.
  - `external_user_id` string, required — Your unique identifier for the user.
  - `cursor` string — 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**.
  - `limit` integer, nullable — Maximum number of transactions to retrieve (min: 1, max: 100).

## Response `200`

Successful request.

- object
  - `merchant` Merchant
    - `id` integer — Unique identifier for the merchant.
    - `name` string — Name of the merchant.
  - `transactions` Transaction[]
    - `id` string — UUID for the transaction. It is best practice to deduplicate on this value.
    - `external_id` string, nullable — External identifier for the transaction provided by the merchant.
    - `datetime` string, date-time — Timestamp of the transaction in UTC. ISO 8601 format. **Note that Knot does not guarantee a specific order in which transactions are returned.**
    - `url` string, nullable — URL associated with the transaction.
    - `order_status` 'ORDERED' | 'BILLED' | 'SHIPPED' | 'DELIVERED' | 'RETURNED' | 'REFUNDED' | 'CANCELLED' | 'FAILED' | 'COMPLETED' | 'PICKED_UP' | 'UNRECOGNIZED' — Status of the order associated with the transaction.
    - `shipping` Shipping, nullable — Shipping information for the transaction.
      - `location` Location, nullable — Location information including recipient name and address.
        - `address` Address, nullable — Address information.
          - `line1` string, nullable — First line of the address.
          - `line2` string, nullable — Second line of the address.
          - `city` string, nullable — City portion of the address.
          - `region` string, nullable — Region portion of the address, usually a state abbreviation. Must be an ISO 3166-2 sub-division code.
          - `postal_code` string, nullable — Postal code of the address.
          - `country` string — Country portion of the address. Must be an ISO 3166-1 alpha-2 code.
        - `first_name` string, nullable — First name of the recipient.
        - `last_name` string, nullable — Last name of the recipient.
    - `payment_methods` PaymentMethod[] — List of payment methods.
      - `external_id` string, nullable — External identifier for the payment method provided by the merchant.
      - `type` 'CARD' | 'APPLE_PAY' | 'GOOGLE_PAY' | 'AMAZON_PAY' | 'PAYPAL' | 'CASH_APP' | 'VENMO' | 'AFFIRM' | 'KLARNA' | 'ONEPAY' | 'GIFT_CARD' | 'CASH' | 'BANK_ACCOUNT' | 'LOYALTY_POINTS' | 'UNRECOGNIZED' — Type of the payment method.
      - `brand` string, nullable — Brand of the payment method. Includes `EBTSNAP`.
      - `last_four` string, nullable — Last 4 digits of the payment method, if a payment card.
      - `name` string, nullable — Name of the payment method provided by the user.
      - `transaction_amount` string, nullable — Transaction amount associated with the payment method.
    - `price` TransactionPrice
      - `sub_total` string, nullable — Subtotal price of the transaction.
      - `adjustments` Adjustment[] — List of price adjustments.
        - `type` 'DISCOUNT' | 'TAX' | 'TIP' | 'FEE' | 'REFUND' | 'UNRECOGNIZED' — Type of adjustment.
        - `label` string, nullable — Label of the adjustment from the merchant.
        - `amount` string — Amount of the adjustment.
      - `total` string — Total price of the transaction.
      - `currency` string, nullable — Currency of the price. ISO 4217 format.
    - `products` Product[]
      - `external_id` string, nullable — External identifier for the product.
      - `gtin` string, nullable — 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.
      - `name` string — Name of the product.
      - `description` string, nullable — Description of the product.
      - `category` 'CATEGORY1' | 'CATEGORY2' | 'CATEGORY3' | 'UNRECOGNIZED' — The category of the product.
      - `url` string, nullable — URL of the product.
      - `image_url` string, nullable — URL of the product image.
      - `quantity` integer, nullable — Number of units of the product purchased in the transaction.
      - `price` ProductPrice
        - `sub_total` string, nullable — Subtotal price of the product in the transaction.
        - `total` string, nullable — Total price of the product in the transaction.
        - `unit_price` string, nullable — Price of the product per unit.
      - `seller` Seller, nullable
        - `name` string, nullable — Name of the seller offering the product.
        - `url` string, nullable — URL of the seller's page within the merchant's marketplace.
      - `eligibility` string[] — The eligibility of the product. `EBT`, `EBTSNAP`, `EBTCASH`, and `WIC` values are coming soon.
    - `loyalty_membership` LoyaltyMembership, nullable
      - `tier` string, nullable — Tier of the loyalty membership.
  - `next_cursor` string, nullable — Cursor token for the next page of transactions.
  - `limit` integer — Number of transactions returned based on the limit provided.

## Other responses

- `400` — Bad request.
- `401` — Unauthorized request.
- `403` — Forbidden request.
- `500` — Internal server error.

---

[API](https://skmtc.net/knotapi/apis/knot-api.md) · [All operations](https://skmtc.net/knotapi/apis/knot-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/knotapi/knot-api/versions/4610832c2087/schema)