Sitoo CRM SPI

Search Customer

get /customers

Find a customer in the CRM database. Note! There is also a lookup endpoint which is used to make a lookup in an external database

PARAMETERS
key
string
query
REQUIRED

Key to search for

key_type
string
query
REQUIRED

Type of field to search for

SearchKeyType
Returns

Returns a list of customers. Should be one customer or empty if no customer is found.

gethttps://crm.example.com/customers?key_type=member_number&key=10012
RESPONSE JSON
[
{
"customer_id": "a26d8975-3b86-43c0-9b12-a86401074770",
"member_number": "10012",
"email": "john.doe@example.com",
"name_first": "John",
"name_last": "Doe",
"mobile": "+46701112233",
"invoice_address": {
"address": "Street",
"city": "City",
"zip": "12345",
"country_id": "SE"
},
"gender": "male",
"accepts_communication": [
"email",
"mail",
"sms"
],
"consents": [
"consent_personal_offers"
],
"status": {
"color": "green",
"text": ""
},
"promotions": [
{
"name": "10% Off",
"promotion_id": "d65804be-1941-4a5b-851a-abd000bfc8bc",
"promotion_type": {
"type": "cart_percent",
"value_int": 10
},
"redeemed": false
}
],
"bonus_checks": [],
"voucher_passwords": [
"member_pricelist"
],
"store_id_home": "200",
"sections": [
{
"title": "Customer Info",
"values": [
{
"text": "2451",
"title": "Bonus Points",
"type": "text"
}
]
}
]
}
]
HTTP Status Code Summary
200Returns a list of customers. Should be one customer or empty if no customer is found.
400Bad Request. Invalid input or other client request error.
401Unauthorized. Authentication is required.
403Forbidden. The client does not have sufficient access rights.
404Not Found. The specified resource was not found.
429Too Many Requests. A request limit has been reached.
500Internal Server Error. An internal error has occurred on the server.
502Bad Gateway. The request can't be handled by the server.
503Service Unavailable. The service requested is unavailable.
504Gateway Timeout. The server did not respond in time.

Add Customer

post /customers

Add a new customer.

REQUEST BODY
object
REQUIRED

Customer object

Customer
Returns

Customer added OK.

posthttps://crm.example.com/customers
{
"member_number": "10012",
"email": "john.doe@example.com",
"name_first": "John",
"name_last": "Doe",
"mobile": "+46701112233",
"invoice_address": {
"address": "Street",
"city": "City",
"zip": "12345",
"country_id": "SE"
},
"gender": "male",
"accepts_communication": [
"email",
"mail",
"sms"
],
"consents": [],
"status": {
"color": "green",
"text": ""
},
"promotions": [
{
"name": "10% Off",
"promotion_id": "d65804be-1941-4a5b-851a-abd000bfc8bc",
"promotion_type": {
"type": "cart_percent",
"value_int": 10
},
"redeemed": false
}
],
"bonus_checks": [],
"voucher_passwords": [
"member_pricelist"
],
"store_id_home": "200",
"sections": [
{
"title": "Customer Info",
"values": [
{
"text": "2451",
"title": "Bonus Points",
"type": "text"
}
]
}
]
}
RESPONSE JSON
{
"customer_id": "a26d8975-3b86-43c0-9b12-a86401074770",
"member_number": "10012",
"email": "john.doe@example.com",
"name_first": "John",
"name_last": "Doe",
"mobile": "+46701112233",
"invoice_address": {
"address": "Street",
"city": "City",
"zip": "12345",
"country_id": "SE"
},
"gender": "male",
"accepts_communication": [
"email",
"mail",
"sms"
],
"consents": [],
"status": {
"color": "green",
"text": ""
},
"promotions": [
{
"name": "10% Off",
"promotion_id": "d65804be-1941-4a5b-851a-abd000bfc8bc",
"promotion_type": {
"type": "cart_percent",
"value_int": 10
},
"redeemed": false
}
],
"bonus_checks": [],
"voucher_passwords": [
"member_pricelist"
],
"store_id_home": "200",
"sections": [
{
"title": "Customer Info",
"values": [
{
"text": "2451",
"title": "Bonus Points",
"type": "text"
}
]
}
]
}
HTTP Status Code Summary
201Customer added OK.
400Bad Request. Invalid input or other client request error.
401Unauthorized. Authentication is required.
403Forbidden. The client does not have sufficient access rights.
404Not Found. The specified resource was not found.
429Too Many Requests. A request limit has been reached.
500Internal Server Error. An internal error has occurred on the server.
502Bad Gateway. The request can't be handled by the server.
503Service Unavailable. The service requested is unavailable.
504Gateway Timeout. The server did not respond in time.

Update Customer

put /customers/{customer_id}

Update customer with new data.

PARAMETERS
customer_id
string
path
REQUIRED

ID of the customer

REQUEST BODY
object
REQUIRED

Customer object

Customer
Returns

Customer updated OK.

puthttps://crm.example.com/customers/a26d8975-3b86-43c0-9b12-a86401074770
{
"customer_id": "a26d8975-3b86-43c0-9b12-a86401074770",
"member_number": "10012",
"email": "john.doe@example.com",
"name_first": "John",
"name_last": "Doe",
"mobile": "+46701112233",
"invoice_address": {
"address": "Street",
"city": "City",
"zip": "12345",
"country_id": "SE"
},
"gender": "male",
"accepts_communication": [
"email",
"mail",
"sms"
],
"consents": [
"consent_personal_offers"
]
}
RESPONSE JSON
{
"customer_id": "a26d8975-3b86-43c0-9b12-a86401074770",
"member_number": "10012",
"email": "john.doe@example.com",
"name_first": "John",
"name_last": "Doe",
"mobile": "+46701112233",
"invoice_address": {
"address": "Street",
"city": "City",
"zip": "12345",
"country_id": "SE"
},
"gender": "male",
"accepts_communication": [
"email",
"mail",
"sms"
],
"consents": [
"consent_personal_offers"
],
"status": {
"color": "green",
"text": ""
},
"promotions": [
{
"name": "10% Off",
"promotion_id": "d65804be-1941-4a5b-851a-abd000bfc8bc",
"promotion_type": {
"type": "cart_percent",
"value_int": 10
},
"redeemed": false
}
],
"bonus_checks": [],
"voucher_passwords": [
"member_pricelist"
],
"store_id_home": "200",
"sections": [
{
"title": "Customer Info",
"values": [
{
"text": "2451",
"title": "Bonus Points",
"type": "text"
}
]
}
]
}
HTTP Status Code Summary
200Customer updated OK.
400Bad Request. Invalid input or other client request error.
401Unauthorized. Authentication is required.
403Forbidden. The client does not have sufficient access rights.
404Not Found. The specified resource was not found.
429Too Many Requests. A request limit has been reached.
500Internal Server Error. An internal error has occurred on the server.
502Bad Gateway. The request can't be handled by the server.
503Service Unavailable. The service requested is unavailable.
504Gateway Timeout. The server did not respond in time.

Get Customer

get /customers/{customer_id}

Get a customer by the customer ID.

PARAMETERS
customer_id
string
path
REQUIRED

ID of the customer

Returns

Returns a customer.

get/customers/{customer_id}
RESPONSE JSON
{
"customer_id": "a26d8975-3b86-43c0-9b12-a86401074770",
"member_number": "10012",
"email": "john.doe@example.com",
"name_first": "John",
"name_last": "Doe",
"mobile": "+46701112233",
"invoice_address": {
"address": "Street",
"city": "City",
"zip": "12345",
"country_id": "SE"
},
"gender": "male",
"accepts_communication": [
"email",
"mail",
"sms"
],
"consents": [
"consent_personal_offers"
],
"status": {
"color": "green",
"text": ""
},
"promotions": [
{
"name": "10% Off",
"promotion_id": "d65804be-1941-4a5b-851a-abd000bfc8bc",
"promotion_type": {
"type": "cart_percent",
"value_int": 10
},
"redeemed": false
}
],
"bonus_checks": [],
"voucher_passwords": [
"member_pricelist"
],
"store_id_home": "200",
"sections": [
{
"title": "Customer Info",
"values": [
{
"text": "2451",
"title": "Bonus Points",
"type": "text"
}
]
}
]
}
HTTP Status Code Summary
200Returns a customer.
400Bad Request. Invalid input or other client request error.
401Unauthorized. Authentication is required.
403Forbidden. The client does not have sufficient access rights.
404Not Found. The specified resource was not found.
429Too Many Requests. A request limit has been reached.
500Internal Server Error. An internal error has occurred on the server.
502Bad Gateway. The request can't be handled by the server.
503Service Unavailable. The service requested is unavailable.
504Gateway Timeout. The server did not respond in time.

Get Transactions

get /customers/{customer_id}/transactions

Get a list of transactions for the customer.

PARAMETERS
customer_id
string
path
REQUIRED

ID of the customer

Returns

Returns a list of transactions for the customer.

gethttps://crm.example.com/customers/a26d8975-3b86-43c0-9b12-a86401074770/transactions
RESPONSE JSON
[
{
"date_created": 1637239675,
"order_id": 10051,
"store_id": "200",
"store_name": "Concept Store",
"currency_code": "SEK",
"items": [
{
"discounts": [],
"product_name": "Deco Coat B/W",
"quantity": 1,
"sku": "597330-S",
"total": "490.00",
"vat": "98.00",
"vat_value": 25
}
],
"payments": [
{
"name": "Cash",
"total": "490.00"
}
]
}
]
HTTP Status Code Summary
200Returns a list of transactions for the customer.
400Bad Request. Invalid input or other client request error.
401Unauthorized. Authentication is required.
403Forbidden. The client does not have sufficient access rights.
404Not Found. The specified resource was not found.
429Too Many Requests. A request limit has been reached.
500Internal Server Error. An internal error has occurred on the server.
502Bad Gateway. The request can't be handled by the server.
503Service Unavailable. The service requested is unavailable.
504Gateway Timeout. The server did not respond in time.

Redeem Items

post /customers/{customer_id}/redeem

Redeem bonus checks or promotions. Note that this must redeem all items to be successful otherwise no items should be redeemed and status code 409 Can't redeem should be returned.

PARAMETERS
customer_id
string
path
REQUIRED

ID of the customer

REQUEST BODY
object
REQUIRED

Redeem object

Redeem
Returns

A redeem object where all items in it were successfully redeemed and with the `redeem_id` property set with the value used to undo a redeem.

posthttps://crm.example.com/customers/a26d8975-3b86-43c0-9b12-a86401074770/redeem
{
"bonus_checks": [],
"promotions": [
"d65804be-1941-4a5b-851a-abd000bfc8bc"
]
}
RESPONSE JSON
{
"redeem_id": "64DCDD6D716EA0F470734356665E5730",
"bonus_checks": [],
"promotions": [
"d65804be-1941-4a5b-851a-abd000bfc8bc"
]
}
HTTP Status Code Summary
200A redeem object where all items in it were successfully redeemed and with the `redeem_id` property set with the value used to undo a redeem.
400Bad Request. Invalid input or other client request error.
401Unauthorized. Authentication is required.
403Forbidden. The client does not have sufficient access rights.
404Not Found. The specified resource was not found.
409Can't redeem items.
429Too Many Requests. A request limit has been reached.
500Internal Server Error. An internal error has occurred on the server.
502Bad Gateway. The request can't be handled by the server.
503Service Unavailable. The service requested is unavailable.
504Gateway Timeout. The server did not respond in time.

Undo Redeem Items

delete /customers/{customer_id}/redeem/{redeem_id}

Undo a previous redeem operation. All items previously redeemed should be undone.

PARAMETERS
customer_id
string
path
REQUIRED

ID of the customer

redeem_id
string
path
REQUIRED

The redeem id returned from the redeem. Used to make the rollback.

deletehttps://crm.example.com/customers/a26d8975-3b86-43c0-9b12-a86401074770/redeem/64DCDD6D716EA0F470734356665E5730
HTTP Status Code Summary
200Successfully undone previously redeemed items.
400Bad Request. Invalid input or other client request error.
401Unauthorized. Authentication is required.
403Forbidden. The client does not have sufficient access rights.
404Not Found. The specified resource was not found.
409Can't undo redeem.
429Too Many Requests. A request limit has been reached.
500Internal Server Error. An internal error has occurred on the server.
502Bad Gateway. The request can't be handled by the server.
503Service Unavailable. The service requested is unavailable.
504Gateway Timeout. The server did not respond in time.

Get Consents

get /consents

Get a list of consents that the customer can agree to, upon registration.

Returns

Returns a list of consents.

Consent
array
gethttps://crm.example.com/consents
RESPONSE JSON
[
{
"consent_id": "consent_personal_offers",
"description": "",
"name": "Accepts Personal Offers",
"value": false
}
]
HTTP Status Code Summary
200Returns a list of consents.
400Bad Request. Invalid input or other client request error.
401Unauthorized. Authentication is required.
403Forbidden. The client does not have sufficient access rights.
404Not Found. The specified resource was not found.
429Too Many Requests. A request limit has been reached.
500Internal Server Error. An internal error has occurred on the server.
502Bad Gateway. The request can't be handled by the server.
503Service Unavailable. The service requested is unavailable.
504Gateway Timeout. The server did not respond in time.

Lookup Customer

get /lookup_customers

Lookup a customer in a global database (not part of the CRM). This can be used when creating a new customer for the CRM.

PARAMETERS
key
string
query
REQUIRED

Key to search for

key_type
string
query
REQUIRED

Type of field to search for

SearchKeyType
Returns

Returns a list of customers. Should be one customer or empty if no customer is found.

gethttps://crm.example.com/lookup_customers?key_type=mobile&key=0701112233
RESPONSE JSON
[
{
"email": "john.doe@example.com",
"name_first": "John",
"name_last": "Doe",
"mobile": "+46701112233",
"invoice_address": {
"address": "Street",
"city": "City",
"zip": "12345",
"country_id": "SE"
}
}
]
HTTP Status Code Summary
200Returns a list of customers. Should be one customer or empty if no customer is found.
400Bad Request. Invalid input or other client request error.
401Unauthorized. Authentication is required.
403Forbidden. The client does not have sufficient access rights.
404Not Found. The specified resource was not found.
429Too Many Requests. A request limit has been reached.
500Internal Server Error. An internal error has occurred on the server.
501Not implemented. This request is not implemented.
502Bad Gateway. The request can't be handled by the server.
503Service Unavailable. The service requested is unavailable.
504Gateway Timeout. The server did not respond in time.

Objects

Address
object

PROPERTIES
name
string

Name for the address. Usually the name of the recipient.

address
string
REQUIRED

The address line 1.

address2
string

The address line 2.

zip
string

Zip for the address.

city
string

City for the address.

state
string

State/Region for the address.

country_id
string

Country id for the address (ISO 3166-1 Alpha2 uppercase)

BonusCheck
object

PROPERTIES
bonus_check_id
string
REQUIRED

ID of the bonus check.

name
string
REQUIRED

Name displayed for the bonus check.

description
string

Description of the bonus check.

cart_amount
REQUIRED

The amount value of the bonus check.

redeemed
boolean
REQUIRED

Boolean value indicating if the bonus check has been redeemed.

date_redeemed
integer
(int64)

Timestamp indicating when the bonus check was redeemed.

CommunicationType
string

Option for way of communication

  • email E-mail
  • sms SMS (Short Text Message)
  • mail Mail

Consent
object

PROPERTIES
consent_id
string
REQUIRED

ID of the consent.

name
string
REQUIRED

Name displayed for the consent.

description
string

Description of the consent.

value
boolean
REQUIRED

Value indicating if the default value when adding a new customer should be to accept the consent or not.

Customer
object

PROPERTIES
customer_id
string
READ ONLY

ID of the customer. Created by the CRM. Required in GET.

member_number
string

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

email
string
(email)

Email for the customer.

name_first
string

First Name of the customer.

name_last
string

Last Name of the customer.

personal_id
string

Social Security Number (SSN) for the customer.

company
string

Company for the customer.

company_id
string

Company ID for the customer.

phone
string

Phone Number for the customer. (E.164 format)

mobile
string

Mobile Phone number for the customer. (E.164 format)

invoice_address

The invoice address.

name
string

Name for the address. Usually the name of the recipient.

address
string
REQUIRED

The address line 1.

address2
string

The address line 2.

zip
string

Zip for the address.

city
string

City for the address.

state
string

State/Region for the address.

country_id
string

Country id for the address (ISO 3166-1 Alpha2 uppercase)

delivery_address

The delivery address.

name
string

Name for the address. Usually the name of the recipient.

address
string
REQUIRED

The address line 1.

address2
string

The address line 2.

zip
string

Zip for the address.

city
string

City for the address.

state
string

State/Region for the address.

country_id
string

Country id for the address (ISO 3166-1 Alpha2 uppercase)

gender
birthday
string
(date)

Date of birth for the customer in ISO 8601 format.

accepts_communication

Accepted ways of communicating with customer.

consents
array
(string)

Array of ID:s for consents that have been accepted by the customer

status
READ ONLY

Status for the customer

color
REQUIRED
text
string
REQUIRED

Status text for the customer.

promotions
array
READ ONLY

Promotions for this customer.

bonus_checks
array
READ ONLY

Bonus checks for this customer.

voucher_passwords
array
(string)
READ ONLY

Passwords for unlocking vouchers for this customer.

store_id_home
string

ID for the home store of the customer. Read only except for POST. Will be matched against externalid on Store in Sitoo.

sections
READ ONLY

Additional sections that the CRM can display for the customer.

CustomerSection
object

PROPERTIES
title
string
REQUIRED

Title of the section

values
array
REQUIRED

Fields that will be shown for this section.

CustomerSectionValueMoney
object

PROPERTIES
type
string
REQUIRED
VALUES
money
title
string
REQUIRED

Title of the field.

value
REQUIRED

CustomerSectionValueText
object

PROPERTIES
type
string
REQUIRED
VALUES
text
title
string
REQUIRED

Title of the field.

text
string
REQUIRED

Text value.

CustomerStatus
object

PROPERTIES
color
REQUIRED
text
string
REQUIRED

Status text for the customer.

CustomerStatusColor
string

Color used to indicate status for the customer

  • red Red
  • orange Orange
  • green Green

DecimalQuantity
string

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

Error
object

PROPERTIES
errortext
string
REQUIRED

Text describing the error.

statuscode
integer
REQUIRED

A status code for the error.

Gender
string

Gender of the customer

  • male Male
  • female Female
  • undisclosed Undisclosed

Money
string

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

Promotion
object

PROPERTIES
promotion_id
string
REQUIRED

ID of the promotion.

promotion_type
object
REQUIRED
name
string
REQUIRED

Name of the promotion.

description
string

Description of the promotion.

redeemed
boolean
REQUIRED

Value indicating if the promotion has been redeemed.

date_redeemed
integer
(int64)

Timestamp indicating when the promotion was redeemed

PromotionCartAmount
object

PROPERTIES
type
string
REQUIRED

The type of this promotion.

VALUES
cart_amount
value_money
REQUIRED

Cart amount to discount.

PromotionCartPercent
object

PROPERTIES
type
string
REQUIRED

The type of this promotion.

VALUES
cart_percent
value_int
integer
REQUIRED

Percent to discount.

Minimum: 1
Maximum: 100

PromotionManual
object

PROPERTIES
type
string
REQUIRED

ID of the promotion.

VALUES
manual

PromotionOffer
object

PROPERTIES
type
string
REQUIRED

The type of promotion.

VALUES
offer
value_string
string
REQUIRED

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

Redeem
object

PROPERTIES
redeem_id
string
READ ONLY

ID of the redeem. Can be used if a rollback is needed.

bonus_checks
array
(string)
REQUIRED

Array of bonus_check_id

promotions
array
(string)
REQUIRED

Array of promotion_id

SearchKeyType
string

Search key type

  • personal_id Personal ID
  • mobile Mobile Phone Number
  • email E-mail
  • member_number Member Number
  • company_id Company ID

Transaction
object

PROPERTIES
date_created
integer
(int64)
REQUIRED

Timestamp for when the transaction was created.

receipt_id
string

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

order_id
integer

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

order_external_id
string

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

store_id
string

Store ID for transaction. (If set, it can be matched against externalid on Store in Sitoo)

store_name
string
REQUIRED

Store Name for the transaction.

currency_code
string
REQUIRED

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

roundoff

Roundoff for the transaction.

items
REQUIRED

Items in transaction.

payments

Payments for transaction.

TransactionItem
object

PROPERTIES
sku
string
REQUIRED

Stock Keeping Unit (SKU) for transaction item.

product_name
string
REQUIRED

Title row 1 for transaction item.

product_name2
string

Title row 2 for transaction item.

quantity
integer
REQUIRED

Quantity for transaction item.

total
REQUIRED

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

vat
REQUIRED

VAT amount for total

manual_discount

Manual discount for this item incl VAT

manual_discount_vat

VAT amount for manual discount

manual_discount_name
string

Name provided for manual discount

vat_value
number
REQUIRED

VAT percentage for transaction item.

note
string

Note for transaction item.

unit_quantity

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

unit_label
string

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

discounts

Discounts for transaction item

TransactionItemDiscount
object

PROPERTIES
name
string
REQUIRED

Name of the discount

total
REQUIRED

Discount amount incl VAT

vat
REQUIRED

VAT included in discount amount

TransactionPayment
object

PROPERTIES
name
string
REQUIRED

Name of the payment

total
REQUIRED

Amount for the payment