Introduction
Guides
API Reference
SPI CRM v2
SPI CRM v1
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

Gift Cards

Add Gift Card

post /giftcards.json

The Add Gift Card endpoint is only called when the system is configured to be using gift cards of type voucher (printed on receipt printer).

PARAMETERS
deliverytype
object
query

Delivery Type

DeliveryType
Default: "preprinted"
deliverytext
string
query

Delivery Text

email
string
query

Email address when using deliverytype "email"

mobile
string
query

Mobile in MSISDN format when using deliverytype "sms"

product_reference
string
query

Product reference (usually SKU)

pin
string
query

Gift Card PIN

REQUEST BODY
object
GiftCard
Returns

Returns an object of type GiftCardResponse

GiftCardResponse
posthttps://spi-gift-card.example.com/giftcards.json?deliverytype=preprinted
{
  "type": "giftcard",
  "currencycode": "USD",
  "transactions": [
    {
      "moneyamount": "500.00",
      "merchant_reference": "SC101"
    }
  ]
}
RESPONSE JSON
{
  "giftcard": {
    "type": "giftcard",
    "currencycode": "USD",
    "cardnumber": "95116763063530548720",
    "cardnumber_display": "95** **** **** **** 8720",
    "redeemable": true,
    "date_expires": 1866322799,
    "date_created": 1550669776,
    "moneyamount": "500.00",
    "requirespin": false,
    "transactions": [
      {
        "transactionid": "3458",
        "date": 1550669776,
        "moneyamount": "500.00",
        "merchant_reference": "SC101",
        "staff_reference": null,
        "transaction_reference": null
      }
    ]
  },
  "addedtransactionids": [
    "3458",
    "a8e9cbd970ebfc2c20037b8e41c7e3c0aa522238"
  ],
  "receipttext": null,
  "print_voucher": false,
  "print_pin": null
}
HTTP Status Code Summary
200Returns an object of type GiftCardResponse
400Bad Request. Invalid syntax, missing required argument or invalid request.
401Unauthorized. Authorization failed.
404Resource not found. The url is invalid.
429Too Many Requests.
500Internal Server Error.

Get Gift Card

get /giftcards/{cardnumber}.json
PARAMETERS
cardnumber
string
path
REQUIRED
pin
string
query

Validate gift card PIN.

Returns

Returns an object of type GiftCardResponse.

GiftCardResponse
gethttps://spi-gift-card.example.com/giftcards/95123456789012345678.json
RESPONSE JSON
{
  "type": "giftcard",
  "currencycode": "USD",
  "cardnumber": "95123456789012345678",
  "cardnumber_display": "95** **** **** **** 5678",
  "redeemable": true,
  "date_expires": 1888181999,
  "date_created": 1569923445,
  "moneyamount": "371.00",
  "requirespin": false,
  "transactions": [
    {
      "transactionid": "3456",
      "date": 1569923445,
      "moneyamount": "500.00",
      "merchant_reference": "SC101",
      "staff_reference": null,
      "transaction_reference": null
    },
    {
      "transactionid": "3457",
      "date": 1570540431,
      "moneyamount": "-129.00",
      "merchant_reference": "SC102",
      "staff_reference": null,
      "transaction_reference": null
    }
  ]
}
HTTP Status Code Summary
200Returns an object of type GiftCardResponse.
400Bad Request. Invalid syntax, missing required argument or invalid request.
401Unauthorized. Authorization failed.
404Resource not found. The URL is invalid.
429Too Many Requests.
500Internal Server Error.

Add Gift Card Transaction

post /giftcards/{cardnumber}/transactions.json
PARAMETERS
cardnumber
string
path
REQUIRED
pin
string
query

Gift Card PIN (Required if requirespin is set to true).

REQUEST BODY
object
GiftCardTransaction
Returns

Returns and object of type GiftCardResponse

GiftCardResponse
posthttps://spi-gift-card.example.com/giftcards/95116763063530548720/transactions.json
{
  "moneyamount": "-299.00",
  "merchant_reference": "SC102"
}
RESPONSE JSON
{
  "giftcard": {
    "type": "giftcard",
    "currencycode": "USD",
    "cardnumber": "95116763063530548720",
    "cardnumber_display": "95** **** **** **** 8720",
    "redeemable": true,
    "date_expires": 1866322799,
    "date_created": 1550669776,
    "moneyamount": "201.00",
    "requirespin": false,
    "transactions": [
      {
        "transactionid": "3458",
        "date": 1550669776,
        "moneyamount": "500.00",
        "merchant_reference": "SC101",
        "staff_reference": null,
        "transaction_reference": null
      },
      {
        "transactionid": "3459",
        "date": 1550669776,
        "moneyamount": "-299.00",
        "merchant_reference": "SC102",
        "staff_reference": null,
        "transaction_reference": null
      }
    ]
  },
  "addedtransactionids": [
    "3459",
    "a57a121adda749bd7c8e37d13913724cabe7c56e"
  ],
  "receipttext": null,
  "print_voucher": false,
  "print_pin": null
}
HTTP Status Code Summary
200Returns and object of type GiftCardResponse
400Bad Request. Invalid syntax, missing required argument or invalid request.
401Unauthorized. Authorization failed.
404Resource not found. The URL is invalid.
429Too Many Requests.
500Internal Server Error.

Delete Gift Card Transactions

delete /giftcards/{cardnumber}/transactions.json

Used for rollback of transaction that has been performed.

PARAMETERS
cardnumber
string
path
REQUIRED
REQUEST BODY
array
deletehttps://spi-gift-card.example.com/giftcards/95116763063530548720/transactions.json
[
  "3459",
  "a57a121adda749bd7c8e37d13913724cabe7c56e"
]
RESPONSE JSON
true
HTTP Status Code Summary
200Returns true
400Bad Request. Invalid syntax, missing required argument or invalid request.
401Unauthorized. Authorization failed.
404Resource not found. The URL is invalid.
429Too Many Requests.
500Internal Server Error.

Objects

DeliveryType
string

  • email Email
  • preprinted PrePrinted
  • printout Printout
  • sms SMS

GiftCard
object

The gift card object.

PROPERTIES
type
GiftCardType
REQUIRED

The type of gift card.

currencycode
string
REQUIRED

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

cardnumber
string

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

cardnumber_display
string
READ ONLY

The masked card number, used for public display.

redeemable
boolean
READ ONLY

If true, the gift card is active for redeem with the moneyamount available.

date_expires
Timestamp
READ ONLY

The date for the expiration of the gift card. (If passed, the gift card is invalid)

date_created
Timestamp
READ ONLY

The date that the gift card was created.

moneyamount
Money
READ ONLY

Current monetary value of the gift card.

requirespin
boolean
READ ONLY

Indicates if PIN is required when redeeming the gift card.

transactions
array
(GiftCardTransaction)

The transactions for this gift card. An array of GiftCardTransaction.

GiftCardResponse
object

Response object for gift card operations.

PROPERTIES
giftcard
GiftCard

The gift card object.

addedtransactionids
array
(string)

An array of transactionids added by the request. (Used for rollback)

receipttext
string

Optional text printed on the receipt.

print_voucher
boolean

If set to true, a gift card voucher should be printed.

print_pin
string

Optional PIN printed for the gift card (usually 4-6 digits).

GiftCardTransaction
object

Gift card transaction object.

PROPERTIES
transactionid
string
READ ONLY

The unique ID of this transaction.

date
Timestamp
READ ONLY

The date that this transaction occurred.

moneyamount
Money
REQUIRED

Money added or subtracted by this transaction.

merchant_reference
string

Optional merchant/store reference for this transaction. (Sitoo POS will send warehouse external ID in this field)

staff_reference
string

Optional staff reference for this transaction.

transaction_reference
string

Optional reference for this transaction. (Sitoo POS will send receipt ID in this field)

GiftCardType
string

  • giftcard Gift Card
  • creditnote Credit Note

Money
string

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

Timestamp
integer

Number of seconds since the Unix Epoch.

Copyright © 2025 Sitoo AB. All rights reserved.