Record types

Introduction

All data within the Sharespine Integration Platform revolves around records and these records have different properties depending on their type. These records can also have different relationships to each other.

In this section we will go through all these and highlight important information for you to understand how to work with them in the best way possible.

Connection

A tenant can have multiple connections to external systems. The Connection record gives information about existing connections and their state. The Connection interface is currently READ-ONLY via API.

Log event

erDiagram LogEvent ||--o| RelatedMsgs: "contains"

All import/export transactions within the Integration Platform generates a trace in the form of logs. These logs are accessible through log events which contain information about general transaction details as well as all related records affected by the transaction.

Each record has auxiliary log message with more detailed information about the status message of that particular record.

Add a log event

External error events can be added through the API endpoint /log/event. It is intended to be used to inform the user about errors that have occurred in the remote system during an import/export through the API. The events will be shown in user interface for the integration platform under event history.

Example:

  [
    {
        "severity": "Error",
        "relatedRecordType": "order",
        "direction": "export",
        "summary": "Product missing in remote system",
        "body": [
            "The order could not be created",
            "An order row contained an unknown product SKU"
        ],
        "relatedIdMsgs": [
            {
                "id": "3fb2568eb7e165e34dd311af5550002b",
                "displayId": "1001",
                "message": "Order could not be created"
            }
        ],
        "time": "2015-01-02T03:04:05Z"
    }
  ]
Note
  • The function is should only be used to record relevant events to make it easier to debug an API-connection. It is not intended to be used as a logger for the external system.
  • direction should be seen from the integration platform i.e export is data leaving the platform (imported by another system) and import is data added/updated to the integration platform. The value bidi indicates that information is bidirectional.
  • Multiple events can be added in one request
  • time suppose to include the time when the error occurred in the external system.

Product

erDiagram Product ||--o{ ProductPrice: contains ProductPrice ||--|| Pricelist: "refers to" ProductPrice ||--|{ QtyPrice: contains Product ||--o{ VariantGroup : "refers to" Product ||--o{ Category : "refers to" Product ||--o{ AttributeValue : "contains" AttributeValue ||--|| Attribute : "refers to" Product ||--o{ Alternatecontent: "contains" Alternatecontent ||--|| ContentGroup: "refers to" Product ||--o{ Picture: "contains" Picture ||--|| File: "refers to" Product ||--o{ CustomData: "contains"

A Product is a central record type in the Integration Platform. The product refers to the entity sold to the end customer and should have a unique sku (Stock Keeping Unit). The Integration Platform collects and saves information about the product in a unified format. The data is stored as product properties and references to other record types.

Complete or partial product information can be added and updated through the available API-endpoints. The complete aggregated product information can always be accessed through the API.

Variant group

erDiagram VariantGroup ||--o{ CustomData: "contains" VariantGroup ||--o{ Picture: "contains" Picture ||--o{ File: "refers to" Product }o--|| VariantGroup: "refers to" VariantGroup ||--o{ Alternatecontent: "contains" Alternatecontent ||--|| ContentGroup: "refers to" VariantGroup ||--o{ AttributeValue : "contains" AttributeValue ||--|| Attribute : "refers to"

A Variant Group is used to group products that have a logical connection to each other. The variant group can contain information that is common for the products that belong to it. Pictures that are common for all products can be saved in the product variant group while pictures that are unique for the product should be saved in that individual product record.

Example

A variant group can be Shoe which is connected to the products Red shoe size 42, Red shoe size 43, Blue shoe size 42 and Blue shoe size 43. The size and color would in this example be attributes connected to the product.

Category

erDiagram Category ||--o{ Child: "contains" Category ||--o{ CustomData: "contains"

A category is used to logically connect products that belong to the same segment. The category can contain child categories and products can refer to both main categories and child categories. The products are not saved within the category instead the product contains a reference to the category.

Example of a category structure:

erDiagram Clothes ||--|| T-Shirts: "contains" Clothes ||--|| Trousers: "contains" Trousers ||--|| Jeans: "contains" Trousers ||--|| Leggings: "contains" Trousers ||--|| Chinos: "contains"

Price list

erDiagram Product ||--o{ ProductPrice: contains ProductPrice ||--|| Pricelist: "refers to" ProductPrice ||--|{ QtyPrice: contains Pricelist ||--o{ CustomData: "contains"

The Integration Platform is using the concept of price lists to logically structure prices between systems. The price list itself mainly contains name, default currency and optionally some custom data. The actual price values are saved directly in the product record with a reference to the price list.

The product price contains an array of qtyPrice which allows setting price levels based on the purchase quantity.

Product prices

To add a price you need to connect a price list and to specify the price per quantity (purchaseQty).

Warning

All prices for a product will be replaced when updating the prices field through the PUT /product/{localId} endpoint.

Note

The endpoint POST /product/{localId}/price allows updates for a specific price list without affecting all prices. A price list should only exist once within the prices array.

prices
This field exists on the product record and contains an array of prices. Note that all prices need to be sent when updating the prices field.
pricelist
The integration platform supports multiple price list. To add a price it is mandatory to have at least one price list.
qtyPrices
The integration platform supports prices based on the purchase qty e.g. 1 for SEK 20 each or if you buy at least 5 it is SEK 12 each. See example below.
purchaseQty
The limit for when the price is valid e.g 5 means that quantity of at least 5 will qualify
originalPriceExclVat
This field contains the price in the format Money

Example: The following example will add two price levels to one price list and one price level to another price list

{
    "prices": [
        {
            "pricelist": {
                "localId": "3fb2568eb7e165e34dd311af5550002b",
            },
            "qtyPrices": [
                {
                    "purchaseQty": "1",
                    "originalPriceExclVat": {
                        "currency": "SEK",
                        "amount": "20.00",
                        "decimals": 2
                    }
                },
                {
                    "purchaseQty": "5",
                    "originalPriceExclVat": {
                        "currency": "SEK",
                        "amount": "12.00",
                        "decimals": 2
                    }
                }
            ]
        },
        {
            "pricelist": {
                "localId": "3fb2568eb7e165e34dd311af5550002c",
            },
            "qtyPrices": [
                {
                    "purchaseQty": "1",
                    "originalPriceExclVat": {
                        "currency": "SEK",
                        "amount": "50.00",
                        "decimals": 2
                    }
                }
            ]
        }
    ]
}

Content Group

erDiagram Alternatecontent ||--|| ContentGroup: "refers to" Product ||--o{ Alternatecontent: "contains" ContentGroup ||--o{ CustomData: "contains"

A content group is used to structure alternate content for products or variant groups. The content group contains some settings that specify how specific fields should be modified.

Tip

Content group (alternate content) is the concept of having parallel content to be used in different channels. For example when you want different content published in different sales channels for the same product.

The content group provides the opportunity to send different texts depending on the receiving system. A common use case is to create a content group for a marketplace to enable custom product titles and descriptions for that marketplace.

The actual text is saved in the product record in the alternateContent field which is connected to a content group by localId.

Example of content group

Request

$ curl
    -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Tenant: <TENANT CODE>' \
    -H 'X-ConnectionId: <CONNECTION ID>' \
    https://api.{HOSTNAME}/api/product/{localId}

Response

Full response omitted for brevity.

{
    "alternateContent": {
        "3fb2568eb7e165e34dd311af5550002b": {
            "contentGroupId": "3fb2568eb7e165e34dd311af5550002b",
            "title": "string",
            "title_lang": {
                "swe": "Exempeltext",
                "eng": "Example text"
            },
            "shortDescription": "string",
            "shortDescription_lang": {
                "swe": "Exempeltext",
                "eng": "Example text"
            },
            "description": "string",
            "description_lang": {
                "swe": "Exempeltext",
                "eng": "Example text"
            }
        }
    },
    ...
}

More information in the Swagger API reference.

Attribute

erDiagram ProductOrVariantGroup ||--o{ AttributeValue : "contains" AttributeValue ||--|| Attribute : "refers to" Attribute ||--o{ CustomData : "contains"

The attribute mainly consists of a name. It is possible to add attribute values to a product or a variant group and to connect these values to the attribute e.g. the attribute named Size can be connected to a product and the attribute value XL is added to the product. The attribute itself does not contain any attribute values.

The customData field is used to configure attributes in the Integration Platform to match attributes for remote systems. See CustomData

File

erDiagram Product ||--o{ Picture: "contains" Picture ||--|| File: "refers to"

The Integration Platform has a file storage system that handles uploaded files. Upload a file through the API and then connect the file to a Product or Variant group. Read more in the endpoints for POST /product/{localId}/picture or POST /product/variantgroup/{localId}/picture.

Order

erDiagram Order ||--o{ OrderRow: "contains" Order ||--o| ShippingAddress: "contains" Order ||--o| BillingAddress: "contains" Order ||--o{ Shipment: "refers to" Order ||--o{ PaymentTransction: "refers to" PaymentTransction ||--|| PaymentMethod: "refers to" PaymentTransction ||--|{ PaymentEvent: "refers to" Order ||--o| ReturnOrder: "refers to"

The Order is a central record type in the Integration Platform. The order contains information about a sale that has taken place and it includes rows, addresses and can have shipment(s) and payment transaction(s). A complete set of order information is recommended to leverage the full potential of the Integration Platform.

The Integration Platform can use an Order;

  • as a source when creating an invoice.
  • to fulfill shipments.
  • to reconcile payments.
  • and more…

Order type

An order can be a sales order or a return order. A sales order is a document generated by the seller specifying the details about the product or services ordered by the customer. A return order is a document specifying the items returned by the customer, it might be all or a subset of the original order.

Order status fields

The Integration Platform supports three different status fields to represent the current status of an order. All fields have a fixed set of status options which can be used e.g. in conditions for a connection. It is recommended to use all relevant fields even if the original system has a different status representation.

Example

Assume that the source system only has one status field with the value “Paid and Delivered”. That should probably be translated to paymentStatus: "paid", shippingStatus: "delivered" and orderStatus: "completed".

Order status

The Integration Platform has a fixed set of order status options that is used to describe the current order status.

pending
The order is in a pending state, ready to begin being processed.
processing
The order is in a processing state, undergoing fulfillment.
completed
The order is in a completed state, dispatched to customer.
cancelled
The order has been cancelled.

Order shipping status

The Integration Platform has a fixed set of shipping status options that is used to describe the current shipping status. Information about the actual shipment is saved as a Shipment and the payment information is saved as Payment Transaction Events.

not-shipped
The shipment status of the order is pending.
fully-shipped
The shipment status of the order is fulfilled.
part-shipped
The shipment status of the order is partly fulfilled.
returned
The shipment status of the order is returned.

Order payment status

The Integration Platform has a fixed set of payment status options that is used to describe the current payment status.

unpaid
No money has been paid at all yet.
fully-paid
All money paid.
partially-paid
Some money paid.
cancelled
The payment has been cancelled. Probably due to order being cancelled.

Order row

The order row should contain all information needed to deliver and bookkeep the sale e.g. title, qty, pricePerUnit and Tax.

Order row type

The Integration Platform supports multiple rowType’s. It is important that the correct rowType is used for each order row. The Integration Platform can use the row type as a part of a condition when sending the order information to an ERP or Accounting system.

The current valid options are:

product
This is a physical product or a service.
paymentfee
A payment fee.
shippingfee
A shipping fee.
handlingfee
A handling fee.
discount
Row discount, a discount bound to this specific row item.
voucher
A gift card, coupon or similar. Important to have side ordered in order being bookkept later in the chain.
comment
A human-readable free text comment attached to the row.
rounding
Tip amount, since it is important to bookkeep correct later in the chain.
gratuity
Tip amount, since it is important to bookkeep correct later in the chain.
customamount
A custom amount that can be used for separate cost or compensation that does not fit any of the other row types. Expected, but not mandatory, content for this row type is:
  • qty = 1
  • title = describe the amount
  • sku = empty or a relevant id or code
  • weight, volume and unit is irrelevant and can be null.

Order row prices & discounts

Note

All row prices are net amounts excl. tax. Tax is separated into distinct fields. Discount values are used to record the existance of discount, but it should not be included into row total.

Outline on how to interpret and utilize row prices and discounts. Let’s first discuss the purpose of following important fields;

qty
How many items of something (where something is indicated by rowType) this row accounts for.
pricePerUnitExclTax
The amount for each item. Net. That is, per unit, excluding of all tax(es) and discounts.
perUnitTaxes
The tax for each item.
rowDiscountExclTax
Information about possible total discount amount for all items on this row. Already deducted in above perUnitExclTax and can be used as information when you want to communicate if discount has been applied.
perDiscountTaxes
Information about possible total tax amount for all item on this row. Also behaves just like rowDiscountExclTax

Invoice

The Invoice is a central record type in the Integration Platform. The invoice is the receipt of a sale that has taken place and it includes rows, addresses and payment transaction(s). A complete set of order information is recommended to leverage the full potential of the Integration Platform.

Invoice type

An invoice can be of type invoice or credit. An invoice is a document generated by the seller specifying the details about the product or services bought by the customer. A credit invoice is a document specifying the items returned by the customer.

Invoice status fields

The Integration Platform supports two different status fields to represent the current status of an invoice. All fields have a fixed set of status options which can be used e.g in conditions for native Connectors. It is recommended to use all relevant fields even if the original system has a different status representation.

Invoice status

The Integration Platform has a fixed set of order status options that is used to describe the current order status.

draft
The invoice is currently being edited, not yet ready and subject to change.
sent
The invoice has been sent to customer, should not be edited from now on.
credited
The invoice has been credited.
cancelled
The invoice has been cancelled, can be used if the invoice has nt yet been sent to the customer. If it has, credited is used instead.

Invoice payment status

The Integration Platform has a fixed set of payment status options that is used to describe the current payment status.

unpaid
The invoice has not yet been fully paid. Might be totally unpaid or partially paid.
fully-paid
The invoice has been fully paid and no more money left to pay by customer.
partially-paid
The invoice is party paid, awaiting full payment.
cancelled
The invoice payment has been cancelled, probably due to the invoice being cancelled.

Invoice row

The invoice row should contain all information needed to deliver and bookkeep the sale e.g description, quantity, sales price and tax/vat.

Invoice row type

Same as Order row type. Read that section for more information.

Invoice row prices & discounts

Same as Order row prices & discounts. Read that section for more information.

Shipment

A shipment is not its own record type but rather a part of the record type Order. An order can have multiple shipments and each shipment contains information about the forwarder that deliveries the parcel and tracking information. Add as much relevant shipment information as possible.

trackingCode
Used if the whole shipment have its own tracking code
trackingUri
Used when the shipment have a specific uri for the shipment
forwarder
The service/company that deliveries the shipment.
  • code - unique code that identifies the forwarder
  • name - a human readable name for the forwarder
parcels
The parcels contains a list of parcels that belong to the shipment. A shipment usually have at least one parcel and each parcel has its unique trackingCode.
  • parcelType - add type if the information is available. Use the forwarders parcel type when possible e.g EVENLOPE1, BOX1, ..
  • weight - weight of the parcel as shipped
  • volume - volume of the parcel as shipped
Note

The shipment does not have a status. The shipmentStatus belongs to the Order.

Payment Method

A payment method is required when adding a payment transaction to an order. The payment method in the platform represents a specific type of payment e.g gift card, invoice, credit card and so on. The external payment methods can be mapped to the platform’s payment methods from the settings in a connector. The mapping does not need to be one-to-one.

Payment Transaction

erDiagram Order ||--o{ PaymentTransaction: "refers to" PaymentTransaction ||--|| PaymentMethod: "refers to" PaymentTransaction ||--|{ PaymentEvent: "refers to" PaymentEvent ||--o| Prepare: "contains" PaymentEvent ||--o{ Cancel: "contains" PaymentEvent ||--o{ Payment: "contains" PaymentEvent ||--o{ Refund: "contains" PaymentEvent ||--o{ Deposit: "contains" PaymentEvent ||--o{ Credit: "contains"

An order can have one or more payment transactions. The payment transactions and their events are used to represent each payment state, which later can be used in automatic accounting. A scenario with multiple transactions is when an order is paid using a Gift card and the Gift card does not cover the full order amount, remaining amount is paid with Credit card.

A payment transaction is always started with a prepare event in the integration platform. A prepare event is usually created when a payment is reserved by the payment provider. A prepare event is added to an order and it also contains a payment method, see API-endpoint POST /order/{localid}/payment. Following events is added directly to the payment transaction, see API-endpoint POST /payment/transaction/{localid}/event

Events

prepare
Payment initiated/reserved in external system, meaning a sale has taken place.
cancel
The payment was cancelled/aborted before the payment was captured/finalized.
payment
Payment captured/finalized in an external system, meaning it is now paid by the customer.
deposit
A payout has been issued by the Payment System Provider (PSP), meaning the merchant now has the money.
refund
The customer has been refunded a partial or full amount due to, for example, a return for some reason.
credit
A credit has been issued by the PSP, meaning the merchant will be deducted money on the next payout.

A common transaction event sequence is:

  1. prepare - Payment initiated/reserved in external system, meaning a sale has taken place.
  2. payment - Payment captured/finalized in an external system, meaning it is now paid by the customer.
  3. deposit - A payout has been issued by the Payment System Provider (PSP), meaning the merchant now has the money.

Another possible transaction sequence is:

  1. prepare - Payment initiated/reserved in external system, meaning a sale has taken place.
  2. payment - Payment captured/finalized in an external system, meaning it is now paid by the customer.
  3. deposit - A payout has been issued by the Payment System Provider (PSP), meaning the merchant now has the money.
  4. credit - The customer has been credited a partial or full amount due to, for example, a return for some reason.
  5. refund - A refund has been issued by the PSP, meaning the merchant will be deducted money on the next payout.

Another possible transaction sequence is:

  1. prepare - Payment initiated/reserved in external system, meaning a sale has taken place.
  2. cancel - Payment canceled in the external system (possible since the payment was never paid by the customer). As opposed to the above scenario where the payment event existed and thus not possible to simply cancel.

Example of creating a simple Payment Transaction

The first step is to start the transaction with a prepare event. The event is created from an order endpoint.

The example below represents that a payment have been authorized and 100 SEK has been reserved. The PSP deducts a fee of 4 SEK and the VAT for the fee is 1 SEK.

$ curl
    -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Tenant: <TENANT CODE>' \
    -H 'X-ConnectionId: <CONNECTION ID>' \
    https://api.{HOSTNAME}/api/order/{localId}/payment \
    -XPOST \
    -d \
    '{
        "type": "prepare",
        "eventTime": "2015-01-02T03:04:05Z",
        "paymentMethodId": "3fb2568eb7e165e34dd311af5550002b",
        "correlationId": "{Unique id for the transaction (created by the payment service provider)}",
        "correlationOrderNo": "string",
        "comment": "string",
        "amount": {
            "currency": "SEK",
            "amount": "100.00"
        },
        "feeExclTax": {
            "currency": "SEK",
            "amount": "4.00"
        },
        "feeTaxes": [
            {
                "taxType": "vat",
                "label": "string",
                "percentage": "25.00",
                "taxableAmount": {
                    "currency": "SEK",
                    "amount": "4.00"
                },
                "tax": {
                    "currency": "SEK",
                    "amount": "1.00"
                }
            }
        ]
    }'

All transaction events thereafter are added through the POST /payment/transaction/{localId}/event/ endpoint. More details can be found in the Swagger API reference.

Example of adding a customer payment event to a Payment Transaction

All subsequent events are added directly to the payment transaction. The example below represents that a payment have been captured and 100 SEK has been reserved. The PSP deducts a fee of 4 SEK and the VAT for the fee is 1 SEK. Note that the total fee for payment transaction now is 8 SEK (4 SEK in prepare + 4 SEK in payment).

$ curl
    -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Tenant: <TENANT CODE>' \
    -H 'X-ConnectionId: <CONNECTION ID>' \
    https://api.{HOSTNAME}/api/payment/transaction/{localId}/event/ \
    -XPOST \
    -d \
    '{
        "type": "payment",
        "eventTime": "2015-01-02T03:04:05Z",
        "amount": {
            "currency": "SEK",
            "amount": "100.00"
        },
        "feeExclTax": {
            "currency": "SEK",
            "amount": "4.00"
        },
        "feeTaxes": [
            {
                "taxType": "vat",
                "label": "string",
                "percentage": "25.00",
                "taxableAmount": {
                    "currency": "SEK",
                    "amount": "4.00"
                },
                "tax": {
                    "currency": "SEK",
                    "amount": "1.00"
                }
            }
        ]
    }'

More details can be found in the Swagger API reference.

Cash Register

erDiagram CashRegister ||--|| ZReport: "refers to"

The cash register represents a single unique physical cash register and is primarily used for grouping Z Reports since at least one cash register is needed to be able to transport Z Report’s within the platform.

Z Report

erDiagram ZReport ||--|| CashRegister: "refers to" ZReport ||--o{ SalesPayments: "contains" ZReport ||--o{ SalesPerTax: "contains" ZReport ||--o{ ReturnsRefunds: "contains" ZReport ||--o{ ReturnsPerTax: "contains"

A Z Report is a detailed history of the transactions for one day, a.k.a. Daily taking. All sales, returns, gratuity, gift cards and information about payment methods used are possible to use within the Z Report.

It is primarily used to transfer the aggregated set of transactions (receipts) for one single day.

Important concepts within the settlement report are the usage of;

  • sales Aggregated customer receipts for all sales events.
  • returns Aggregated customer receipts for all sales events.
  • coupon Aggregated sold gift cards.
  • gratuity Aggregated gratuity/tipping.
  • rounding Possible occurrence of difference between physically received money and money accounted for within the Z Report.
  • paymentmethod Aggregated information per distinct payment method.

Settlement Report

erDiagram SettlementReport ||--o{ depositedPerPaymentMethod: "contains" SettlementReport ||--o{ refundedPerPaymentMethod: "contains" SettlementReport ||--o{ paidPerPaymentMethod: "contains" SettlementReport ||--o{ creditedPerPaymentMethod: "contains"

A Settlement report represents reconciliation information and is primarily used to transfer the aggregated set of transactions within a timeframe on an external liquid account.

Settlements are usually used in conjunction with Z Reports where Z Reports holds information about cash register events and the Settlement Reports reconciliation information from PSP affected by these sales events.

Important concepts within the settlement report are the usage of;

  • paid Money transferred from Customer to PSP.
  • deposited Money transferred from PSP to Merchant.
  • refunded Money transferred from PSP to Customer.
  • credited Money transferred from Merchant to PSP.

Ledger account

erDiagram LedgerAccount ||--o{ CustomData: "contains"

A ledger account can hold a name, number and description. The integration platform has the possibility to create ledger entries based on transactions, where each entry will be connected to an account. The account in the integration platform is mapped to an account in the external system before ledger entries are exported.

Warning

This record type is experimental and might be subject to change

Ledger entry

erDiagram LedgerEntry ||--o{ CustomData: "contains" LedgerEntry ||--|| LedgerAccount: "refers to"

A ledger entry contains:

seriesId
The series to where the entry should be added.
entryDate
The date when the transaction occurred and the date for when the transaction is added to the ledger.
currency
The currency of the ledger entry.
comment
A descriptive text of the ledger entry.
entrySource
The system that created the ledger entry e.g a connector in the integration platform.
rows
The ledger entry rows with information about ledger account, debit amount and credit amount.
Warning

This record type is experimental and might be subject to change