Sync Transactions

POST

transactions

sync

curl --request POST \
  --url https://development.knotapi.com/transactions/sync \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '{
  "merchant_id": 46,
  "external_user_id": "abc",
  "cursor": "eyJpZCI6MjI3ODEsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
  "limit": 5
}'

{
  "merchant": {
    "id": 4,
    "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",
      "payment_methods": [
        {
          "external_id": "x7q9m2lbw5pazc",
          "type": "CARD",
          "brand": "VISA",
          "last_four": "5690",
          "name": "Homer's credit card",
          "transaction_amount": "16.23"
        }
      ],
      "price": {
        "sub_total": "12.56",
        "adjustments": [
          {
            "type": "TAX",
            "label": "NYC local sales tax",
            "amount": "3.67"
          }
        ],
        "total": "16.23",
        "currency": "USD"
      },
      "products": [
        {
          "external_id": "10315643",
          "name": "Great Value Turkey Flavored Stuffing Mix",
          "url": "https://www.example.com/ip/10315643",
          "quantity": 1,
          "price": {
            "sub_total": "12.56",
            "total": "12.56",
            "unit_price": "12.56"
          },
          "eligibility": [
            "FSA/HSA"
          ]
        }
      ]
    }
  ],
  "next_cursor": "<string>",
  "limit": 5
}

Authorizations

Authorization

string

header

required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Body

application/json

The input parameters required for syncing transactions.

merchant_id

integer

required

Unique identifier for the merchant.

Example:

46

external_user_id

string

required

Unique identifier for the user.

Example:

"abc"

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.

Example:

"eyJpZCI6MjI3ODEsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"

limit

integer

default:5

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

Example:

5

Response

200

application/json

Successful request.

merchant

object

transactions

object[]

transactions.id

string

Unique identifier for the transaction.

Example:

"13da3c28-a068-4642-9ce2-b730cfda5f5f"

transactions.external_id

string | null

External identifier for the transaction provided by the merchant.

Example:

"a9x7bq2lmw5p"

transactions.datetime

string

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"

transactions.url

string | null

URL associated with the transaction.

Example:

"https://www.example.com/orders/123123123"

transactions.order_status

enum<string>

Status of the order associated with the transaction.

Available options:

ORDERED,

BILLED,

SHIPPED,

DELIVERED,

REFUNDED,

CANCELLED,

FAILED,

COMPLETED,

PICKED_UP,

UNRECOGNIZED

Example:

"COMPLETED"

transactions.payment_methods

object[]

List of payment methods.

transactions.price

object

transactions.products

object[]

transactions.products.external_id

string | null

External identifier for the product.

Example:

"10315643"

transactions.products.name

string

Name of the product.

Example:

"Great Value Turkey Flavored Stuffing Mix"

transactions.products.url

string | null

URL of the product.

Example:

"https://www.example.com/ip/10315643"

transactions.products.quantity

integer | null

Number of units of the product purchased in the transaction.

Example:

1

transactions.products.price

object

transactions.products.eligibility

string[]

The eligibility of the product.

Example:

["FSA/HSA"]

next_cursor

string | null

Cursor token for the next page of transactions.

limit

integer

Number of transactions returned based on the limit provided.

Example:

5

Was this page helpful?

The Transaction Object Get Transaction By ID

curl --request POST \
  --url https://development.knotapi.com/transactions/sync \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '{
  "merchant_id": 46,
  "external_user_id": "abc",
  "cursor": "eyJpZCI6MjI3ODEsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
  "limit": 5
}'

{
  "merchant": {
    "id": 4,
    "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",
      "payment_methods": [
        {
          "external_id": "x7q9m2lbw5pazc",
          "type": "CARD",
          "brand": "VISA",
          "last_four": "5690",
          "name": "Homer's credit card",
          "transaction_amount": "16.23"
        }
      ],
      "price": {
        "sub_total": "12.56",
        "adjustments": [
          {
            "type": "TAX",
            "label": "NYC local sales tax",
            "amount": "3.67"
          }
        ],
        "total": "16.23",
        "currency": "USD"
      },
      "products": [
        {
          "external_id": "10315643",
          "name": "Great Value Turkey Flavored Stuffing Mix",
          "url": "https://www.example.com/ip/10315643",
          "quantity": 1,
          "price": {
            "sub_total": "12.56",
            "total": "12.56",
            "unit_price": "12.56"
          },
          "eligibility": [
            "FSA/HSA"
          ]
        }
      ]
    }
  ],
  "next_cursor": "<string>",
  "limit": 5
}

Overview

Sessions

CardSwitcher

TransactionLink

Merchants

Users

Sync Transactions

Authorizations

Body

Response