Create transaction

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    passId: '<string>',
    storeId: '<string>',
    pointsSpent: 1,
    remainingUsesBefore: 123,
    terminalId: '<string>',
    transactionDate: '<string>',
    reference: '<string>',
    pointsEarned: 1,
    statusReason: '<string>',
    remainingUsesAfter: 123,
    payment: {reference: '<string>', pspReference: '<string>'},
    additionalData: {
      posRegisterId: '<string>',
      lineItems: [
        {
          quantity: 123,
          color: '<string>',
          itemCategory: '<string>',
          amountExcludingTax: {currency: '<string>', value: 123},
          taxPercentage: 123,
          description: '<string>',
          upc: '<string>',
          manufacturer: '<string>',
          size: '<string>',
          imageUrl: '<string>',
          amountIncludingTax: {currency: '<string>', value: 123},
          productUrl: '<string>',
          sku: '<string>',
          taxAmount: {currency: '<string>', value: 123},
          brand: '<string>'
        }
      ],
      posEftPosText: '<string>',
      pos: '<string>',
      posData: {},
      pspData: {},
      mcc: 123
    }
  })
};

fetch('https://api.platform.getstell.com/v1/transactions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

curl --request POST \
  --url https://api.platform.getstell.com/v1/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "passId": "<string>",
  "storeId": "<string>",
  "pointsSpent": 1,
  "remainingUsesBefore": 123,
  "terminalId": "<string>",
  "transactionDate": "<string>",
  "reference": "<string>",
  "pointsEarned": 1,
  "statusReason": "<string>",
  "remainingUsesAfter": 123,
  "payment": {
    "reference": "<string>",
    "pspReference": "<string>"
  },
  "additionalData": {
    "posRegisterId": "<string>",
    "lineItems": [
      {
        "quantity": 123,
        "color": "<string>",
        "itemCategory": "<string>",
        "amountExcludingTax": {
          "currency": "<string>",
          "value": 123
        },
        "taxPercentage": 123,
        "description": "<string>",
        "upc": "<string>",
        "manufacturer": "<string>",
        "size": "<string>",
        "imageUrl": "<string>",
        "amountIncludingTax": {
          "currency": "<string>",
          "value": 123
        },
        "productUrl": "<string>",
        "sku": "<string>",
        "taxAmount": {
          "currency": "<string>",
          "value": 123
        },
        "brand": "<string>"
      }
    ],
    "posEftPosText": "<string>",
    "pos": "<string>",
    "posData": {},
    "pspData": {},
    "mcc": 123
  }
}
'

import requests

url = "https://api.platform.getstell.com/v1/transactions"

payload = {
    "passId": "<string>",
    "storeId": "<string>",
    "pointsSpent": 1,
    "remainingUsesBefore": 123,
    "terminalId": "<string>",
    "transactionDate": "<string>",
    "reference": "<string>",
    "pointsEarned": 1,
    "statusReason": "<string>",
    "remainingUsesAfter": 123,
    "payment": {
        "reference": "<string>",
        "pspReference": "<string>"
    },
    "additionalData": {
        "posRegisterId": "<string>",
        "lineItems": [
            {
                "quantity": 123,
                "color": "<string>",
                "itemCategory": "<string>",
                "amountExcludingTax": {
                    "currency": "<string>",
                    "value": 123
                },
                "taxPercentage": 123,
                "description": "<string>",
                "upc": "<string>",
                "manufacturer": "<string>",
                "size": "<string>",
                "imageUrl": "<string>",
                "amountIncludingTax": {
                    "currency": "<string>",
                    "value": 123
                },
                "productUrl": "<string>",
                "sku": "<string>",
                "taxAmount": {
                    "currency": "<string>",
                    "value": 123
                },
                "brand": "<string>"
            }
        ],
        "posEftPosText": "<string>",
        "pos": "<string>",
        "posData": {},
        "pspData": {},
        "mcc": 123
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "data": {
    "passId": "<string>",
    "storeId": "<string>",
    "transactionDate": "2023-11-07T05:31:56Z",
    "createdAt": "2023-11-07T05:31:56Z",
    "id": "<string>",
    "updatedAt": "2023-11-07T05:31:56Z",
    "pointsSpent": 123,
    "remainingUsesBefore": 123,
    "terminalId": "<string>",
    "reference": "<string>",
    "pointsEarned": 123,
    "statusReason": "<string>",
    "remainingUsesAfter": 123,
    "payment": {
      "reference": "<string>",
      "amount": {
        "currency": "<string>",
        "value": 1
      },
      "pspReference": "<string>"
    },
    "additionalData": {}
  },
  "requestId": "<string>"
}

{
  "requestId": "<string>",
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request parameters",
    "details": {}
  }
}

{
  "requestId": "<string>",
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required",
    "details": {}
  }
}

{
  "requestId": "<string>",
  "error": {
    "code": "FORBIDDEN",
    "message": "Access denied to this resource",
    "details": {}
  }
}

{
  "requestId": "<string>",
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "details": {}
  }
}

{
  "requestId": "<string>",
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An internal server error occurred",
    "details": {}
  }
}

POST

https://api.platform.getstell.com

transactions

Create transaction

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    passId: '<string>',
    storeId: '<string>',
    pointsSpent: 1,
    remainingUsesBefore: 123,
    terminalId: '<string>',
    transactionDate: '<string>',
    reference: '<string>',
    pointsEarned: 1,
    statusReason: '<string>',
    remainingUsesAfter: 123,
    payment: {reference: '<string>', pspReference: '<string>'},
    additionalData: {
      posRegisterId: '<string>',
      lineItems: [
        {
          quantity: 123,
          color: '<string>',
          itemCategory: '<string>',
          amountExcludingTax: {currency: '<string>', value: 123},
          taxPercentage: 123,
          description: '<string>',
          upc: '<string>',
          manufacturer: '<string>',
          size: '<string>',
          imageUrl: '<string>',
          amountIncludingTax: {currency: '<string>', value: 123},
          productUrl: '<string>',
          sku: '<string>',
          taxAmount: {currency: '<string>', value: 123},
          brand: '<string>'
        }
      ],
      posEftPosText: '<string>',
      pos: '<string>',
      posData: {},
      pspData: {},
      mcc: 123
    }
  })
};

fetch('https://api.platform.getstell.com/v1/transactions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

curl --request POST \
  --url https://api.platform.getstell.com/v1/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "passId": "<string>",
  "storeId": "<string>",
  "pointsSpent": 1,
  "remainingUsesBefore": 123,
  "terminalId": "<string>",
  "transactionDate": "<string>",
  "reference": "<string>",
  "pointsEarned": 1,
  "statusReason": "<string>",
  "remainingUsesAfter": 123,
  "payment": {
    "reference": "<string>",
    "pspReference": "<string>"
  },
  "additionalData": {
    "posRegisterId": "<string>",
    "lineItems": [
      {
        "quantity": 123,
        "color": "<string>",
        "itemCategory": "<string>",
        "amountExcludingTax": {
          "currency": "<string>",
          "value": 123
        },
        "taxPercentage": 123,
        "description": "<string>",
        "upc": "<string>",
        "manufacturer": "<string>",
        "size": "<string>",
        "imageUrl": "<string>",
        "amountIncludingTax": {
          "currency": "<string>",
          "value": 123
        },
        "productUrl": "<string>",
        "sku": "<string>",
        "taxAmount": {
          "currency": "<string>",
          "value": 123
        },
        "brand": "<string>"
      }
    ],
    "posEftPosText": "<string>",
    "pos": "<string>",
    "posData": {},
    "pspData": {},
    "mcc": 123
  }
}
'

import requests

url = "https://api.platform.getstell.com/v1/transactions"

payload = {
    "passId": "<string>",
    "storeId": "<string>",
    "pointsSpent": 1,
    "remainingUsesBefore": 123,
    "terminalId": "<string>",
    "transactionDate": "<string>",
    "reference": "<string>",
    "pointsEarned": 1,
    "statusReason": "<string>",
    "remainingUsesAfter": 123,
    "payment": {
        "reference": "<string>",
        "pspReference": "<string>"
    },
    "additionalData": {
        "posRegisterId": "<string>",
        "lineItems": [
            {
                "quantity": 123,
                "color": "<string>",
                "itemCategory": "<string>",
                "amountExcludingTax": {
                    "currency": "<string>",
                    "value": 123
                },
                "taxPercentage": 123,
                "description": "<string>",
                "upc": "<string>",
                "manufacturer": "<string>",
                "size": "<string>",
                "imageUrl": "<string>",
                "amountIncludingTax": {
                    "currency": "<string>",
                    "value": 123
                },
                "productUrl": "<string>",
                "sku": "<string>",
                "taxAmount": {
                    "currency": "<string>",
                    "value": 123
                },
                "brand": "<string>"
            }
        ],
        "posEftPosText": "<string>",
        "pos": "<string>",
        "posData": {},
        "pspData": {},
        "mcc": 123
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "data": {
    "passId": "<string>",
    "storeId": "<string>",
    "transactionDate": "2023-11-07T05:31:56Z",
    "createdAt": "2023-11-07T05:31:56Z",
    "id": "<string>",
    "updatedAt": "2023-11-07T05:31:56Z",
    "pointsSpent": 123,
    "remainingUsesBefore": 123,
    "terminalId": "<string>",
    "reference": "<string>",
    "pointsEarned": 123,
    "statusReason": "<string>",
    "remainingUsesAfter": 123,
    "payment": {
      "reference": "<string>",
      "amount": {
        "currency": "<string>",
        "value": 1
      },
      "pspReference": "<string>"
    },
    "additionalData": {}
  },
  "requestId": "<string>"
}

{
  "requestId": "<string>",
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request parameters",
    "details": {}
  }
}

{
  "requestId": "<string>",
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required",
    "details": {}
  }
}

{
  "requestId": "<string>",
  "error": {
    "code": "FORBIDDEN",
    "message": "Access denied to this resource",
    "details": {}
  }
}

{
  "requestId": "<string>",
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "details": {}
  }
}

{
  "requestId": "<string>",
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An internal server error occurred",
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

API key authentication. Include your API key as a Bearer token.

Example: Bearer sk_prod_xxxxxx

Get your API key from the Stell Dashboard.

Body

application/json

Data required to record a new transaction.

passId

string

required

ID of the pass to record transaction for

storeId

string

required

ID of the store where transaction occurred

type

enum<string>

required

Type of transaction being recorded

Available options:

ONLINE,

PASS_AND_PAYMENT,

PASS_ONLY,

PAYMENT_ONLY,

SCAN_ONLY,

CHECK_IN,

CHECK_OUT,

UNKNOWN

pointsSpent

integer

Loyalty points redeemed in this transaction

Required range: x >= 0

instrument

enum<string>

Payment method used for the transaction

Available options:

CARD,

CASH,

MOBILE,

OTHER,

APPLE_VAS,

GOOGLE_SMART_TAP,

QR,

NFC_TYPE_1,

NFC_TYPE_2,

NFC_TYPE_3,

NFC_TYPE_4,

NFC_TYPE_5,

MIFARE

remainingUsesBefore

integer

Number of remaining uses before this transaction (for access control)

terminalId

string

ID of the terminal that processed the transaction

transactionDate

string

ISO 8601 timestamp when transaction occurred (defaults to now). Accepts both timezone-bearing (2026-06-02T12:13:14Z) and timezone-less (2026-06-02T12:13:14, treated as UTC) forms.

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?$

reference

string

External transaction reference or receipt number

Maximum string length: 255

pointsEarned

integer

Loyalty points earned in this transaction

Required range: x >= 0

statusReason

string

Reason for transaction status (e.g., denial reason)

Maximum string length: 500

remainingUsesAfter

integer

Number of remaining uses after this transaction (for access control)

payment

object

Payment details for the transaction

Show child attributes

additionalData

object

Custom data attached to the transaction. Only pos, posData, posRegisterId, posEftPosText, pspData, mcc, and lineItems are accepted — posData/pspData accept arbitrary JSON, everything else does not.

Show child attributes

status

enum<string>

Transaction status

Available options:

APPROVED,

DENIED,

FAILED,

PENDING

Response

201 response

Response envelope carrying a transaction.

data

TransactionModel · object

required

Record of a pass scan, purchase, or redemption.

Show child attributes

requestId

string

required

Unique request identifier for debugging

Pattern: ^[0-9A-Z]{26}$

Getting started

Integration guide

Passes

Pass Templates

Engagement

Programs

Companies

Stores

Merchants

Terminals

Transactions

System

Create transaction

Authorizations

Body

Response