Introduction
Guides
API Reference
SPI CRM v2
SPI CRM v1
SPI Events
SPI Gift Card
SPI Payment
SPI Product Search
Shipments v3
Purchase Prices v3

Gift Cards

Add Gift Card

post /sites/{siteid}/giftcards
PARAMETERS
siteid
integer
path
REQUIRED
deliverytype
string
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 giftcardresponse

giftcardresponse
posthttps://api.mysitoo.com/v2/accounts/1500/sites/1/giftcards.json?deliverytype=preprinted
{
  "type": "giftcard",
  "currencycode": "USD",
  "cardnumber": "95116763063530548720",
  "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 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 /sites/{siteid}/giftcards/{cardnumber}
PARAMETERS
siteid
integer
path
REQUIRED
cardnumber
string
path
REQUIRED
pin
string
query

Validate gift card PIN.

Returns

Returns a giftcardresponse.

giftcardresponse
gethttps://api.mysitoo.com/v2/accounts/1500/sites/1/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 a 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 /sites/{siteid}/giftcards/{cardnumber}/transactions
PARAMETERS
siteid
integer
path
REQUIRED
cardnumber
string
path
REQUIRED
pin
string
query

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

REQUEST BODY
object
giftcardtransaction
Returns

Returns giftcardresponse

giftcardresponse
posthttps://api.mysitoo.com/v2/accounts/1500/sites/1/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 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 /sites/{siteid}/giftcards/{cardnumber}/transactions

Used for rollback of transaction that has been performed.

PARAMETERS
siteid
integer
path
REQUIRED
cardnumber
string
path
REQUIRED
REQUEST BODY
object
giftcardresponse
deletehttps://api.mysitoo.com/v2/accounts/1500/sites/1/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 giftcard.

currencycode
string
REQUIRED

Currency for the giftcard. (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. See giftcard.

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 © 2024 Sitoo AB. All rights reserved.