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

Contacts

Add Contact

post /contacts
Deprecated!

Used for adding a new contact to the external CRM.

REQUEST BODY
object
crmcontact
posthttps://customcrmapi.example.com/contacts
{
  "email": "",
  "membernumber": "",
  "namefirst": "Steve",
  "namelast": "Johnson",
  "personalid": "",
  "company": "",
  "companyid": "",
  "phone": "",
  "mobile": "+11223334455",
  "invoice_address": "",
  "invoice_address2": "",
  "invoice_zip": "",
  "invoice_city": "",
  "invoice_state": "",
  "invoice_countryid": "",
  "delivery_address": "",
  "delivery_address2": "",
  "delivery_zip": "",
  "delivery_city": "",
  "delivery_state": "",
  "delivery_countryid": "",
  "gender": "male",
  "birthday": "1986-05-15T00:00:00Z",
  "accepts_email": true,
  "accepts_sms": true,
  "accepts_mail": true,
  "acceptedconsents": [
    "1",
    "2"
  ]
}
RESPONSE JSON
""255934461""
HTTP Status Code Summary
200Returns contactid
400Bad Request. Invalid syntax, missing required argument or invalid request.
401Unauthorized. Authorization failed.
404Resource not found. The url is invalid.
500Internal Server Error.

Find Contact

get /contacts
Deprecated!

Used for finding a contact in the external CRM. See CrmContact for fields.

PARAMETERS
key
string
query
REQUIRED

Key for filtering an exact match of a contact. The response array should contain exactly one contact if key is found or an empty if key is not found.

include_extended
boolean
query

Boolean indicating if extended fields for contact should be included in response.

Default: false
Returns

Returns an array with 1 item of type CrmContact or an empty array if no contact could be found for the key provided.

crmcontact
gethttps://customcrmapi.example.com/contacts?key=12345
RESPONSE JSON
[
  {
    "contactid": "123456789",
    "email": "laura.smith@example.com",
    "membernumber": "12345",
    "namefirst": "Laura",
    "namelast": "Smith",
    "personalid": "",
    "company": "",
    "companyid": "",
    "phone": "",
    "mobile": "",
    "invoice_address": "10 Main St.",
    "invoice_address2": "",
    "invoice_zip": "",
    "invoice_city": "Townsville",
    "invoice_state": "",
    "invoice_countryid": "",
    "delivery_address": "",
    "delivery_address2": "",
    "delivery_zip": "",
    "delivery_city": "",
    "delivery_state": "",
    "delivery_countryid": "",
    "gender": "female",
    "birthday": "1986-05-15T00:00:00Z",
    "accepts_email": true,
    "accepts_sms": true,
    "accepts_mail": true,
    "acceptedconsents": [
      "1",
      "2"
    ],
    "voucherpasswords": [],
    "storeexternalid": null
  }
]
HTTP Status Code Summary
200Returns an array with 1 item of type CrmContact or an empty array if no contact could be found for the key provided.
400Bad Request. Invalid syntax, missing required argument or invalid request.
401Unauthorized. Authorization failed.
404Resource not found. The url is invalid.
500Internal Server Error.

Get Contact

get /contacts/{contactid}
Deprecated!

Used for getting a contact from the external CRM using contactid (primary key).

PARAMETERS
contactid
integer
path
REQUIRED
include_extended
boolean
query

Boolean indicating if extended fields for contact should be included in response.

Default: false
Returns

Returns a CrmContact.

crmcontact
gethttps://customcrmapi.example.com/contacts/123456789?include_extended=true
RESPONSE JSON
{
  "contactid": "123456789",
  "email": "laura.smith@example.com",
  "membernumber": "12345",
  "namefirst": "Laura",
  "namelast": "Smith",
  "personalid": "",
  "company": "",
  "companyid": "",
  "phone": "",
  "mobile": "",
  "invoice_address": "10 Main St.",
  "invoice_address2": "",
  "invoice_zip": "",
  "invoice_city": "Townsville",
  "invoice_state": "",
  "invoice_countryid": "",
  "delivery_address": "",
  "delivery_address2": "",
  "delivery_zip": "",
  "delivery_city": "",
  "delivery_state": "",
  "delivery_countryid": "",
  "gender": "female",
  "birthday": "1986-05-15T00:00:00Z",
  "accepts_email": true,
  "accepts_sms": true,
  "accepts_mail": true,
  "acceptedconsents": [
    "1",
    "2"
  ],
  "status_color": "orange",
  "status_text": "Phone number not registered.",
  "promotions": [
    {
      "promotionid": "1",
      "promotiontype": {
        "type": "manual"
      },
      "name": "Promotion",
      "description": "Promotional giveaway for members",
      "redeemed": false,
      "dateredeemed": null
    },
    {
      "promotionid": "2",
      "promotiontype": {
        "type": "cart_percent",
        "value_int": 50
      },
      "name": "50% Discount",
      "description": "50 percent off during spring sale",
      "redeemed": false,
      "dateredeemed": null
    },
    {
      "promotionid": "3",
      "promotiontype": {
        "type": "cart_amount",
        "value_money": "200.00"
      },
      "name": "200 Discount",
      "description": "200 off for our valued members",
      "redeemed": false,
      "dateredeemed": null
    },
    {
      "promotionid": "4",
      "promotiontype": {
        "type": "offer",
        "value_string": "SPRINGDISCOUNT"
      },
      "name": "Spring Offer",
      "description": "Spring offer for new members",
      "redeemed": false,
      "dateredeemed": null
    }
  ],
  "bonuschecks": [
    {
      "bonuscheckid": "1",
      "name": "Bonus Check",
      "description": "",
      "cartamount": "100.00",
      "redeemed": false,
      "dateredeemed": null
    }
  ],
  "transactions": [
    {
      "transactionid": "123456789",
      "receiptid": "ST01CH010000100112345",
      "orderid": 112233,
      "orderexternalid": null,
      "datecreated": 1525767472,
      "storeid": "999",
      "storename": "Sitoo Concept Store",
      "items": [
        {
          "itemid": "1",
          "sku": "7768-01",
          "productname": "Box",
          "productname2": null,
          "note": "",
          "productgroupname": "Standard",
          "brand": "",
          "custom1": null,
          "custom2": null,
          "custom3": null,
          "custom4": null,
          "custom5": null,
          "vatvalue": 25,
          "total": "200.00",
          "vat": "40.00",
          "manual_discount": "0.00",
          "manual_discountvat": "0.00",
          "manual_discountname": null,
          "quantity": 2,
          "unitsize": null,
          "unitlabel": null,
          "discounts": [
            {
              "name": "40% discount",
              "total": "80.00",
              "vat": "16.00",
              "discountid": "1010",
              "discountcode": "PRO123"
            }
          ]
        },
        {
          "itemid": "2",
          "sku": "6449-01",
          "productname": "Envelope",
          "productname2": null,
          "note": "",
          "productgroupname": "Standard",
          "brand": "",
          "custom1": null,
          "custom2": null,
          "custom3": null,
          "custom4": null,
          "custom5": null,
          "vatvalue": 25,
          "total": "500.00",
          "vat": "100.00",
          "manual_discount": "0.00",
          "manual_discountvat": "0.00",
          "manual_discountname": null,
          "quantity": 1,
          "unitsize": null,
          "unitlabel": null,
          "discounts": []
        }
      ],
      "payments": [
        {
          "paymentid": "1",
          "name": "Card",
          "total": "620.00"
        }
      ],
      "redeemedbonuschecks": null,
      "redeemedpromotions": null,
      "currencycode": "USD"
    }
  ],
  "voucherpasswords": [],
  "storeexternalid": null
}
HTTP Status Code Summary
200Returns a CrmContact.
400Bad Request. Invalid syntax, missing required argument or invalid request.
401Unauthorized. Authorization failed.
404Resource not found. The url is invalid.
500Internal Server Error.

Update Contact

put /contacts/{contactid}
Deprecated!

Used for updating an existing contact in the external CRM.

PARAMETERS
contactid
integer
path
REQUIRED
REQUEST BODY
object
crmcontact
puthttps://customcrmapi.example.com/contacts/123456789
{
  "email": "laura.smith@example.com",
  "membernumber": "",
  "namefirst": "Laura",
  "namelast": "Smith",
  "personalid": "",
  "company": "",
  "companyid": "",
  "phone": "",
  "mobile": "+22334445566",
  "invoice_address": "",
  "invoice_address2": "",
  "invoice_zip": "",
  "invoice_city": "",
  "invoice_state": "",
  "invoice_countryid": "",
  "delivery_address": "",
  "delivery_address2": "",
  "delivery_zip": "",
  "delivery_city": "",
  "delivery_state": "",
  "delivery_countryid": "",
  "gender": "male",
  "birthday": "1986-05-15T00:00:00Z",
  "accepts_email": true,
  "accepts_sms": true,
  "accepts_mail": true,
  "acceptedconsents": [
    "1",
    "2"
  ]
}
HTTP Status Code Summary
200
400Bad Request. Invalid syntax, missing required argument or invalid request.
401Unauthorized. Authorization failed.
404Resource not found. The url is invalid.
500Internal Server Error.

Add Transaction

post /contacts/{contactid}/transactions
Deprecated!

Used for registering a transaction for an existing contact in the external CRM. NOTE! It is possible for the same transaction to be sent more than once, so the endpoint needs to handle that case.

PARAMETERS
contactid
integer
path
REQUIRED
REQUEST BODY
object
crmtransaction
posthttps://customcrmapi.example.com/contacts/123456789/transactions
{
  "receiptid": "ST01CH010000100112345",
  "orderid": 112233,
  "datecreated": 1526386290,
  "storeid": "1",
  "storename": "Sitoo Concept Store",
  "storeexternalid": "999",
  "posid": "ST01CH0100001001",
  "items": [
    {
      "itemid": "1",
      "sku": "7768-01",
      "productname": "Box",
      "productgroupname": "Standard",
      "vatvalue": 25,
      "total": "200.00",
      "vat": "40.00",
      "manual_discount": "0.00",
      "manual_discountvat": "0.00",
      "manual_discountname": null,
      "quantity": 2,
      "discounts": [
        {
          "discountcode": "MEMBER",
          "discountid": "1010",
          "name": "40% discount",
          "total": "80.00",
          "vat": "16.00"
        }
      ]
    },
    {
      "itemid": "2",
      "sku": "6449-01",
      "productname": "Envelope",
      "productgroupname": "Standard",
      "vatvalue": 25,
      "total": "50.00",
      "vat": "10.00",
      "manual_discount": "0.00",
      "manual_discountvat": "0.00",
      "manual_discountname": null,
      "quantity": 1,
      "discounts": []
    }
  ],
  "payments": [
    {
      "paymentid": "1",
      "name": "Card",
      "total": "170.00"
    }
  ],
  "redeemedpromotions": [
    "1"
  ],
  "currencycode": "USD"
}
RESPONSE JSON
""517475574""
HTTP Status Code Summary
200Returns transactionid
400Bad Request. Invalid syntax, missing required argument or invalid request.
401Unauthorized. Authorization failed.
404Resource not found. The url is invalid.
500Internal Server Error.

Objects

crmbonuscheck
object

PROPERTIES
bonuscheckid
string

ID of the bonus check

name
string

Name displayed for the bonus check

description
string

Description of the bonus check

cartamount
money

The amount value of the bonus check

redeemed
boolean

Boolean value indicating if the bonus check has been redeemed

dateredeemed
integer

Optional. Timestamp indicating when the bonus check was redeemed

crmcontact
object

PROPERTIES
contactid
string
READ ONLY

ID of the contact.

membernumber
string

Member Number for the contact. (This field is used to represent the customer on purchase receipts)

email
string

Email for the contact.

namefirst
string

First Name of the contact.

namelast
string

Last Name of the contact.

personalid
string

Social Security Number (SSN) for the contact.

company
string

Company for the contact.

companyid
string

Company ID for the contact.

phone
string

Phone Number for the contact.

mobile
string

Mobile Phone number for the contact.

invoice_address
string

Address for the contact (invoice).

invoice_address2
string

Address line 2 for the contact (invoice).

invoice_zip
string

Zip Code for the contact (invoice).

invoice_city
string

City for the contact (invoice).

invoice_state
string

State/Region for the contact (invoice).

invoice_countryid
string

2 character country code according to ISO 3166-1 standard for the contact (invoice).

delivery_address
string

Address for the contact (delivery).

delivery_address2
string

Address line 2 for the contact (delivery).

delivery_zip
string

Zip Code for the contact (delivery).

delivery_city
string

City for the contact (delivery).

delivery_state
string

State/Region for the contact (delivery).

delivery_countryid
string

2 character country code according to ISO 3166-1 standard for the contact (delivery).

gender
gender

Optional. Enumerated value for gender of the contact.

birthday
string

Optional. Date of birth for the contact in ISO 8601 format.

accepts_email
boolean

Boolean value indicating if contact accepts communication via email.

accepts_sms
boolean

Boolean value indicating if contact accepts communication via text messaging (SMS).

accepts_mail
boolean

Boolean value indicating if contact accepts communication via postal service.

acceptedconsents
array
(string)

Array of accepted consents (consentid) for the contact.

status_color
status_color

Extended. Optional. Enumerated value indicating status color for the contact.

status_text
string

Extended. Optional. Status Text for the contact.

promotions
array
(crmpromotion)

Extended. Optional. Array of CrmPromotion for the contact.

bonuschecks
array
(crmbonuscheck)

Extended. Optional. Array of CrmBonusCheck for the contact.

transactions
array
(crmtransaction)

Extended. Optional. Array of CrmTransaction for the contact.

voucherpasswords
array
(string)

Optional. Associated voucher passwords, used to activate campaigns for contact in Sitoo POS.

storeexternalid
string

Optional. Store External ID from where the contact was created.

crmpromotion
object

PROPERTIES
promotionid
string

ID of the promotion.

promotiontype
promotiontype

Enumerated value for type of promotion.

name
string

Name of the promotion.

description
string

Description of the promotion.

redeemed
boolean

Boolean value indicating if the promotion has been redeemed

dateredeemed
integer

Optional. Timestamp indicating when the promotion was redeemed

crmtransaction
object

PROPERTIES
transactionid
string
READ ONLY

ID of the transaction.

receiptid
string

Optional. Sitoo Receipt ID for the transaction. (If set, then can be used to perform refund in Sitoo POS)

orderid
integer

Optional. Sitoo Order ID for the transaction. (If set, then can be used to perform refund in Sitoo POS)

orderexternalid
string

Optional. Sitoo Order External ID for the transaction. (If set, then can be used to perform refund in Sitoo POS)

datecreated
integer

Timestamp for when the transaction was created.

storeid
string

Store ID for the transaction.

storename
string

Store Name for the transaction.

storeexternalid
string

Optional. Store External ID for the transaction.

posid
string

Optional. POS ID for the transaction.

roundoff
money

Optional. Round Off for the transaction.

items
array
(crmtransactionitem)

Items in this transaction. Array of CrmTransactionItem.

payments
array
(crmtransactionpayment)

Payments for this transaction. Array of CrmTransactionPayment.

redeemedpromotions
array
(string)

Optional. Array with ID for promotions used in this transaction.

redeemedbonuschecks
array
(string)

Optional. Array with ID for bonus checks used in this transaction.

currencycode
string

Optional. Currency used for this transaction (3-letter ISO 4217).

crmtransactionitem
object

PROPERTIES
itemid
string

ID of transaction item.

sku
string

Stock Keeping Unit (SKU) for transaction item.

productname
string

Title row 1 for transaction item.

productname2
string

Optional. Title row 2 for transaction item.

note
string

Optional. Note for transaction item.

productgroupname
string

Name of product group for transaction item.

brand
string

Optional. Brand for transaction item.

custom1
string

Optional. Custom field 1 for transaction item.

custom2
string

Optional. Custom field 2 for transaction item.

custom3
string

Optional. Custom field 3 for transaction item.

custom4
string

Optional. Custom field 4 for transaction item.

custom5
string

Optional. Custom field 5 for transaction item.

vatvalue
number

VAT percentage for transaction item.

total
money

Total amount for item incl VAT (before applying manual discount and discounts)

vat
money

VAT amount for total.

manual_discount
money

Manual discount incl VAT

manual_discountvat
money

VAT amount for manual discount

manual_discountname
string

Optional. Name provided for manual discount

quantity
integer

Quantity for transaction item.

unitsize
decimalquantity

Optional. Unit Size (How much that is included in each unit).

unitlabel
string

Optional. Label for unit of transaction item. (e.g. kg)

discounts
array
(crmtransactionitemdiscount)

Array of CrmTransactionItemDiscount.

crmtransactionitemdiscount
object

PROPERTIES
name
string

Name of discount.

total
money

Discount incl VAT.

vat
money

VAT included in discount.

discountid
string

Optional. ID of discount.

discountcode
string

Optional. Code for discount.

crmtransactionpayment
object

PROPERTIES
paymentid
string

ID of the payment.

name
string

Name of the payment.

total
money

Amount for the payment.

decimalquantity

gender
string

  • female Female
  • male Male
  • undisclosed Undisclosed

money
string

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

promotiontype
object

The type of promotion

oneOf:

promotiontypecartamount
object

PROPERTIES
type
string
REQUIRED

The type of this promotion.

VALUES
cart_amount
value_money
money
REQUIRED

Cart amount to discount.

promotiontypecartpercent
object

PROPERTIES
type
string
REQUIRED

The type of this promotion.

VALUES
cart_percent
value_int
integer
REQUIRED

Percent to discount.

Minimum: 1
Maximum: 100

promotiontypemanual
object

PROPERTIES
type
string
REQUIRED

The type of this promotion.

VALUES
manual

promotiontypeoffer
object

PROPERTIES
type
string
REQUIRED

The type of this promotion.

VALUES
offer
value_string
string
REQUIRED

Voucher password that can enable campaigns that already exist in the Sitoo Platform.

status_color
string

  • green Green
  • orange Orange
  • red Red
Copyright © 2024 Sitoo AB. All rights reserved.