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 Tax Free
Journals v3
Purchase Prices v3
Shipments v3

SPI Insurances

Create Cart Insurance

post /cart-insurances

Make query to create cart insurance options for products in the cart.

PARAMETERS
Store-ID
string
header

ID of the store (Sitoo clients will send the externalid property of the store object in Sitoo).

Staff-ID
string
header

ID of the staff (Sitoo clients will send the externalid property of the user object in Sitoo).

Register-ID
string
header

ID of the register.

Request-ID
string
header

ID of the request.

REQUEST BODY
object
REQUIRED

The cart insurance object consisting of an array of items (products) with their respective insurance options.

CartInsurance
Returns

Successful. Returns a CartInsurance object, including details of insurance options, applicable to the cart.

CartInsurance
posthttps://insurance.example.com/cart-insurances
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "crm_channel_id": "custom-crm",
  "customer_id": "123456789",
  "currency_code": "USD",
  "items": [
    {
      "id": "1",
      "sku": "234.788.14",
      "name": "iPhone 15",
      "variant_text": "Space Grey",
      "product_group": "Mobile Phones",
      "quantity": 1,
      "total": "1299.00",
      "additional_data": {
        "item-serial": "123456789",
        "item-imei": "98765432"
      }
    }
  ]
}
RESPONSE JSON
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "items": [
    {
      "id": "1",
      "sku": "234.788.14",
      "insurance_options": [
        {
          "type": "none",
          "sku": "0",
          "name": "No Insurance",
          "product_group": "",
          "unit_price": "0.00",
          "sales_taxes": []
        },
        {
          "type": "insurance",
          "sku": "987-12",
          "name": "12 Months",
          "product_group": "Tech Insurance",
          "unit_price": "39.90",
          "sales_taxes": [
            {
              "name": "Regular VAT",
              "amount": "7.98",
              "percentage": 25
            }
          ],
          "additional_data": {
            "insurance-period": "12"
          }
        },
        {
          "type": "insurance",
          "sku": "987-24",
          "name": "24 Months",
          "product_group": "Tech Insurance",
          "unit_price": "59.90",
          "sales_taxes": [
            {
              "name": "Regular VAT",
              "amount": "11.98",
              "percentage": 25
            }
          ],
          "additional_data": {
            "insurance-period": "24"
          }
        }
      ],
      "policyholder_info": {
        "name": "required",
        "personal_id": "required",
        "address": "required",
        "comment": "optional"
      }
    }
  ]
}
HTTP Status Code Summary
201Successful. Returns a CartInsurance object, including details of insurance options, applicable to the cart.
400Invalid request. Data sent from client is invalid.
401Missing or bad authentication.
403User is not authorized to perform operation.
500Internal Server Error.
502Bad Gateway.

Objects

CartInsurance
object

The object containing the current cart in the POS that insurance options should be returned for.

PROPERTIES
id
string
REQUIRED

The ID for the product insurance options, unique identifier. Sitoo POS will send cart ID for this field.

crm_channel_id
string
WRITE ONLY

The ID for the CRM channel that the customer belongs to.

customer_id
string
WRITE ONLY

The ID for the customer associated with the purchase.

currency_code
string
(iso-4217)
WRITE ONLY
REQUIRED

Currency used for the cart (3-letter ISO 4217).

Max Length: 3
Min Length: 3
items
array
(CartItem)
REQUIRED

Cart items (products) in the cart.

CartItem
object

The object holding a cart item for a product to be insured.

PROPERTIES
id
string
REQUIRED

The ID used to identify the specific product item in the cart. Sitoo POS will send the cart item ID for this field.

Max Length: 128
Min Length: 1
sku
string
REQUIRED

Stock Keeping Unit (SKU) for the cart item.

Max Length: 128
name
string
WRITE ONLY
REQUIRED

The name of the product.

Max Length: 256
variant_text
string
WRITE ONLY

Product variant data for the product.

Example: ""Size: Medium""
Max Length: 256
product_group
string
WRITE ONLY
REQUIRED

Name of the product group for this cart item.

Max Length: 64
quantity
integer
WRITE ONLY
REQUIRED

Quantity for the cart item.

Minimum: 1
total
Money
WRITE ONLY
REQUIRED

Total amount to pay for the cart item incl. VAT (after discounts have been applied).

additional_data
object
WRITE ONLY

Additional data that is associated with the cart item (product).

<*>
string
Properties with values of type `string` is allowed.
insurance_options
array
(InsuranceOption)
READ ONLY
REQUIRED

Insurance options for this cart item.

policyholder_info
PolicyHolderInfo
READ ONLY
REQUIRED

Policy holder info that should be collected for the policyholder of this insurance.

InsuranceOption
object

An object containing an insurance for a product.

PROPERTIES
type
string

The type of insurance option.

Default: "insurance"
VALUES
none
insurance
sku
string
REQUIRED

Stock keeping unit (SKU) for this insurance option. Unique value to identify the insurance option.

Max Length: 128
name
string
REQUIRED

The name of the insurance option.

Max Length: 256
variant_text
string

Product variant data for the insurance option.

Example: ""Size: Medium""
Max Length: 256
product_group
string
REQUIRED

Name of the product group for the insurance option.

Example: ""Tech Insurance""
Max Length: 64
unit_price
Money
REQUIRED

Price per unit for the insurance option incl. sales tax (VAT). What the customer will pay for the insurance option. The value must be greater than or equal to "0.00". The zero value, "0.00", is used for the insurance type none.

unit_sales_taxes
array
(SalesTax)
REQUIRED

Sales taxes included per unit.

additional_data
object

Additional data that will be added to order items if the insurance is purchased.

<*>
string
Properties with values of type `string` is allowed.

Money
string

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

PolicyHolderInfo
object

Object holding the definition of what information that needs to be collected for the policyholder of the insurance.

PROPERTIES
name
PolicyHolderInfoCollectionMode

Full name of the policyholder.

personal_id
PolicyHolderInfoCollectionMode

Personal ID (SSN or similar) for the policyholder.

address
PolicyHolderInfoCollectionMode

Full address for the policyholder.

mobile
PolicyHolderInfoCollectionMode

Mobile phone number for the policyholder.

email
PolicyHolderInfoCollectionMode

Email for the policyholder.

comment
PolicyHolderInfoCollectionMode

A note regarding the policyholder or the insurance instance.

PolicyHolderInfoCollectionMode
string

An enumerated value indicating how the type of information should be collected for the policyholder of an insurance.

  • not-collected Not requested from policyholder
  • required Needs to be provided
  • optional Can be optionally provided

SalesTax
object

The sales tax object.

PROPERTIES
name
string
REQUIRED

The name of the tax.

Example: ""Regular VAT""
Max Length: 64
amount
Money
REQUIRED

The amount of tax.

Example: ""20.00""
percentage
number
REQUIRED

The tax percentage.

Example: "25"
Minimum: 0
Example: { "name": "Regular VAT", "amount": "20.00", "percentage": 25 }

ErrorCode
string

Error code describing the data and depending on value, the error_data property will contain the following additional information:

Error codeAdditional info
field-missingfield
field-unknownfield
field-readonlyfield
field-typefield
field-validationfield
version-invalidnone
condition-failednone
othernone
Example: "field-missing"

ErrorMessage
object

Error object returned when a request is not successful.

PROPERTIES
request_id
string
REQUIRED

ID of request.

Example: ""123e4567-e89b-12d3-a456-426614174000""
error_code
ErrorCode
REQUIRED

The error code returned.

error_data
object
REQUIRED

A string map with fields depending on the error_code. The field message is always available.

<*>
string
Copyright © 2025 Sitoo AB. All rights reserved.