Introduction
Guides
API Reference
SPI CRM v2
SPI CRM v1
SPI Digital Receipts
SPI Discount Cards
SPI Events
SPI Gift Card
SPI Insurance
SPI Payment
SPI Product Recommendations
SPI Product Search
SPI RFID
SPI Tax Free
Journals v3
Purchase Prices v3
Shipments v3

SPI Discount Cards

Look up a discount card

post /discount-cards/lookup

Looks up discount card details by card number

PARAMETERS
eshop_id
integer
query

Eshop ID

Store-ID
string
header

The external ID of the store the register belongs to.

Staff-ID
string
header

The external ID of the staff.

Register-ID
string
header

The ID of the register used.

Request-ID
string
header

A unique ID for the request, used for tracing and debugging.

REQUEST BODY
object
Lookup
Returns

Discount Card object with transaction ID.

LookupResponse
post/discount-cards/lookup
{
  "card_number": "1234567890"
}
RESPONSE JSON
{
  "currency_code": "USD",
  "card_name": "My Discount Card",
  "card_number": "1234567890",
  "card_number_display": "**********7890",
  "card_type": "Type of Card",
  "active": true,
  "original_balance": "100.00",
  "limit_type": "hard",
  "balance": "50.00",
  "discount_percentage": 10,
  "alternate_discount": {
    "alternate_discount_percentage": 5,
    "product_attribute_id": "low_margin",
    "product_attribute_value": "true"
  },
  "date_expires": 1704067200,
  "requires_pin": false
}
HTTP Status Code Summary
200Discount Card object with transaction ID.
400Bad request
404Not found
500Internal server error

Post a discount card transaction

post /discount-cards/transactions

Post a discount card transaction

PARAMETERS
eshop_id
integer
query

Eshop ID

Store-ID
string
header

The external ID of the store the register belongs to.

Staff-ID
string
header

The external ID of the staff.

Register-ID
string
header

The ID of the register used.

Request-ID
string
header

A unique ID for the request, used for tracing and debugging.

REQUEST BODY
object
Transaction
Returns

Transaction created

TransactionResponse
post/discount-cards/transactions
{
  "card_number": "1234567890",
  "pin_input": "1234",
  "date": 1704067200,
  "discount_amount": "10.00",
  "total_amount": "123.00",
  "transaction_type": "sale",
  "transaction_reference": "123e4567-e89b-12d3-a456-426614174000",
  "transaction_code": "456"
}
RESPONSE JSON
{
  "currency_code": "USD",
  "card_name": "My Discount Card",
  "card_number": "1234567890",
  "card_number_display": "**********7890",
  "card_type": "Type of Card",
  "active": true,
  "original_balance": "100.00",
  "limit_type": "hard",
  "balance": "50.00",
  "discount_percentage": 10,
  "alternate_discount": {
    "alternate_discount_percentage": 5,
    "product_attribute_id": "low_margin",
    "product_attribute_value": "true"
  },
  "date_expires": 1704067200,
  "requires_pin": false,
  "transaction_id": "txn_1234567890"
}
HTTP Status Code Summary
201Transaction created
400Bad request
404Not found
422Invalid PIN
500Internal server error

Revert a discount card transaction

post /discount-cards/transactions/{transaction_id}/revert

Reverts a discount card transaction. Used if something went wrong during purchase. For refunds, use the post transaction endpoint with type 'refund'.

PARAMETERS
transaction_id
string
path
REQUIRED

The unique id of the transaction to revert.

eshop_id
integer
query

Eshop ID

Store-ID
string
header

The external ID of the store the register belongs to.

Staff-ID
string
header

The external ID of the staff.

Register-ID
string
header

The ID of the register used.

Request-ID
string
header

A unique ID for the request, used for tracing and debugging.

REQUEST BODY
object
RevertTransaction
Returns

Transaction reverted

TransactionResponse
post/discount-cards/transactions/{transaction_id}/revert
{
  "card_number": "1234567890",
  "pin_input": "1234"
}
RESPONSE JSON
{
  "currency_code": "USD",
  "card_name": "My Discount Card",
  "card_number": "1234567890",
  "card_number_display": "**********7890",
  "card_type": "Type of Card",
  "active": true,
  "original_balance": "100.00",
  "limit_type": "hard",
  "balance": "50.00",
  "discount_percentage": 10,
  "alternate_discount": {
    "alternate_discount_percentage": 5,
    "product_attribute_id": "low_margin",
    "product_attribute_value": "true"
  },
  "date_expires": 1704067200,
  "requires_pin": false,
  "transaction_id": "txn_1234567890"
}
HTTP Status Code Summary
200Transaction reverted
400Bad request
404Not found
422Invalid PIN
500Internal server error

Objects

Error
object

PROPERTIES
error_code
string
REQUIRED
error_data
REQUIRED
message
string
REQUIRED
request_id
string
REQUIRED
<*>
object
Example: { "error_code": "field-missing", "error_data": { "message": "Application error" }, "request_id": "123e4567-e89b-12d3-a456-426614174123" }

Lookup
object

PROPERTIES
card_number
string
REQUIRED

The unique id of the discount card (card number).

<*>
object

LookupResponse
object

PROPERTIES
currency_code
string
(iso-4217)
REQUIRED

Currency for the giftcard. (ISO 4217, alpha-3)

Example: "USD"
Max Length: 3
Min Length: 3
card_name
string

The name of the discount card.

Example: "My Discount Card"
card_number
string
REQUIRED

The unique id of the gift card (card number).

Example: "1234567890"
Min Length: 1
card_number_display
string
READ ONLY

The masked card number, used for public display.

Example: "**********7890"
card_type
string

Type of card according to the provider.

Example: "Type of Card"
active
boolean
REQUIRED

If true, the discount card is active and can be used for a transaction.

Example: true
original_balance
string

Original monetary limit of discount card. Optional since unlimited cards have no original balance set.

Pattern: ^[-+]?[0-9]+\.[0-9]{2}$
Example: "100.00"
limit_type
string
REQUIRED

Type of limit for the discount card.

Example: "hard"
VALUES
soft
hard
unlimited
balance
string

Current monetary value left of the discount card. If not provided no value limits will be applied.

Pattern: ^[-+]?[0-9]+\.[0-9]{2}$
Example: "50.00"
discount_percentage
integer
REQUIRED

Discount percentage for full price products.

Example: 10
alternate_discount
object

Optional object for applying alternative discount.

alternate_discount_percentage
integer
REQUIRED

Alternative discount percentage to apply.

product_attribute_id
string
REQUIRED

The product attribute id that triggers the alternative discount. Targeted in combination with product_attribute_value.

product_attribute_value
string
REQUIRED

A product attribute allowed value that triggers the alternative discount.

date_expires
integer

The date for the expiration of the discount card. Only used for presentation, active flag decides if card could be used or not.

Example: 1704067200
requires_pin
boolean
REQUIRED

If true, a PIN is required in order to use the discount card.

Default: false
<*>
object

RevertTransaction
object

PROPERTIES
card_number
string
REQUIRED

The unique id of the gift card (card number).

pin_input
string

Discount card PIN to verify

<*>
object

Transaction
object

PROPERTIES
card_number
string
REQUIRED

The unique id of the discount card (card number).

Example: "1234567890"
pin_input
string

PIN code for the discount card. Required if the card requires a PIN.

Example: "1234"
date
integer
REQUIRED

Unix timestamp of the transaction.

Example: 1704067200
discount_amount
string
REQUIRED

Total discount amount that has been granted by the involved discount card, excludes any other promotions or manual discounts from this value.

Pattern: ^[-+]?[0-9]+\.[0-9]{2}$
Example: "10.00"
total_amount
string
REQUIRED

Total amount the customer is due to pay, which can include multiple discount sources.

Pattern: ^[-+]?[0-9]+\.[0-9]{2}$
Example: "123.00"
transaction_type
string
REQUIRED

Type of transaction.

Example: "sale"
VALUES
sale
return
transaction_reference
string
REQUIRED

An optional reference for the transaction, e.g. receipt id.

Example: "uuid"
refund_transaction_id
string

Required if transaction_type is 'refund'. The transaction_id of the original transaction.

Example: "txn_1234567890"
transaction_code
string

An optional code for the transaction.

<*>
object

TransactionResponse

PROPERTIES
currency_code
string
(iso-4217)
REQUIRED

Currency for the giftcard. (ISO 4217, alpha-3)

Example: "USD"
Max Length: 3
Min Length: 3
card_name
string

The name of the discount card.

Example: "My Discount Card"
card_number
string
REQUIRED

The unique id of the gift card (card number).

Example: "1234567890"
Min Length: 1
card_number_display
string
READ ONLY

The masked card number, used for public display.

Example: "**********7890"
card_type
string

Type of card according to the provider.

Example: "Type of Card"
active
boolean
REQUIRED

If true, the discount card is active and can be used for a transaction.

Example: true
original_balance
string

Original monetary limit of discount card. Optional since unlimited cards have no original balance set.

Pattern: ^[-+]?[0-9]+\.[0-9]{2}$
Example: "100.00"
limit_type
string
REQUIRED

Type of limit for the discount card.

Example: "hard"
VALUES
soft
hard
unlimited
balance
string

Current monetary value left of the discount card. If not provided no value limits will be applied.

Pattern: ^[-+]?[0-9]+\.[0-9]{2}$
Example: "50.00"
discount_percentage
integer
REQUIRED

Discount percentage for full price products.

Example: 10
alternate_discount
object

Optional object for applying alternative discount.

alternate_discount_percentage
integer
REQUIRED

Alternative discount percentage to apply.

product_attribute_id
string
REQUIRED

The product attribute id that triggers the alternative discount. Targeted in combination with product_attribute_value.

product_attribute_value
string
REQUIRED

A product attribute allowed value that triggers the alternative discount.

date_expires
integer

The date for the expiration of the discount card. Only used for presentation, active flag decides if card could be used or not.

Example: 1704067200
requires_pin
boolean
REQUIRED

If true, a PIN is required in order to use the discount card.

Default: false
transaction_id
string
REQUIRED

The unique id of the transaction.

Example: "txn_1234567890"
Copyright © 2026 Sitoo AB. All rights reserved.