const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
passId: '<string>',
pointsSpent: 1,
remainingUsesBefore: 123,
terminalId: '<string>',
storeId: '<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>",
"pointsSpent": 1,
"remainingUsesBefore": 123,
"terminalId": "<string>",
"storeId": "<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>",
"pointsSpent": 1,
"remainingUsesBefore": 123,
"terminalId": "<string>",
"storeId": "<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>",
"type": "PURCHASE",
"transactionDate": "2023-11-07T05:31:56Z",
"createdAt": "2023-11-07T05:31:56Z",
"id": "<string>",
"updatedAt": "2023-11-07T05:31:56Z",
"tapMode": "SINGLE_TAP",
"pointsSpent": 123,
"channel": "IN_STORE",
"instrument": "APPLE_VAS",
"remainingUsesBefore": 123,
"terminalId": "<string>",
"storeId": "<string>",
"reference": "<string>",
"pointsEarned": 123,
"statusReason": "<string>",
"remainingUsesAfter": 123,
"payment": {
"reference": "<string>",
"amount": {
"currency": "<string>",
"value": 1
},
"method": "APPLE_PAY",
"pspReference": "<string>"
},
"additionalData": {},
"status": "APPROVED"
},
"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": {}
}
}Create transaction
Record a new transaction against a pass.
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
passId: '<string>',
pointsSpent: 1,
remainingUsesBefore: 123,
terminalId: '<string>',
storeId: '<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>",
"pointsSpent": 1,
"remainingUsesBefore": 123,
"terminalId": "<string>",
"storeId": "<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>",
"pointsSpent": 1,
"remainingUsesBefore": 123,
"terminalId": "<string>",
"storeId": "<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>",
"type": "PURCHASE",
"transactionDate": "2023-11-07T05:31:56Z",
"createdAt": "2023-11-07T05:31:56Z",
"id": "<string>",
"updatedAt": "2023-11-07T05:31:56Z",
"tapMode": "SINGLE_TAP",
"pointsSpent": 123,
"channel": "IN_STORE",
"instrument": "APPLE_VAS",
"remainingUsesBefore": 123,
"terminalId": "<string>",
"storeId": "<string>",
"reference": "<string>",
"pointsEarned": 123,
"statusReason": "<string>",
"remainingUsesAfter": 123,
"payment": {
"reference": "<string>",
"amount": {
"currency": "<string>",
"value": 1
},
"method": "APPLE_PAY",
"pspReference": "<string>"
},
"additionalData": {},
"status": "APPROVED"
},
"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
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
Data required to record a new transaction.
ID of the pass to record transaction for
What happened to the pass. Use channel for in-store vs online and tapMode for single- vs double-tap; the legacy ONLINE / PASS_AND_PAYMENT / PASS_ONLY / PAYMENT_ONLY values are rejected.
PURCHASE, REDEMPTION, POINTS_ADJUSTMENT, SCAN_ONLY, CHECK_IN, CHECK_OUT, UNKNOWN Whether pass and payment were captured in one terminal tap (SINGLE_TAP), separate taps (DOUBLE_TAP), or without a terminal (NONE)
SINGLE_TAP, DOUBLE_TAP, NONE Loyalty points redeemed in this transaction
x >= 0Where the customer was: IN_STORE or ONLINE
IN_STORE, ONLINE How the pass was presented (Apple VAS, Google Smart Tap, QR, NFC, MIFARE). The payment method goes in payment.method.
APPLE_VAS, GOOGLE_SMART_TAP, QR, NFC_TYPE_1, NFC_TYPE_2, NFC_TYPE_3, NFC_TYPE_4, NFC_TYPE_5, MIFARE, OTHER Number of remaining uses before this transaction (for access control)
ID of the terminal that processed the transaction
ID of the store where transaction occurred
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.
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?$External transaction reference or receipt number
255Loyalty points earned in this transaction
x >= 0Reason for transaction status (e.g., denial reason)
500Number of remaining uses after this transaction (for access control)
Payment details for the transaction
Show child attributes
Show child attributes
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
Show child attributes
Transaction status
APPROVED, DENIED, FAILED, PENDING Was this page helpful?