Introduction
Zoined API enables customers or third parties to send their data to Zoined using RESTful HTTP API. Uploaded data will be processed and stored to our data warehouse and used for generating analytic reports for the retailers. API service has end points for almost every facet of a retail business be it sales, inventory or even employee time keeping.This document contains instructions on how to access the Zoined API. This document contains two parts: introduction and reference. Introduction walks you through the general structure of the API and how to use it. Reference contains detailed documentation for each API end point including code examples for multiple programming languages, and live in-browser testing tool for the API end points.If you have any questions related to Zoined API, don't hesitate to contact Zoined support.
Authentication and security
Every client must authenticate itself to send data towards any end points in Zoined API service. This means that every request to the service must have an authorization header with an identification token. Token is unique to every customer and can be obtained by contacting Zoined support services.
An example of the header would be:
Authorization: Bearer dGVzdGlhc2lha2FzOnZhaWtlYXBhc3N1
All traffic to Zoined API is sent with HTTPS and protected with TLS.
Messaging and error handling
API service uses JSON data format to exchange data with clients. This means all replies to clients will be delivered in JSON (including all possible error messages). The successful requests; i.e. the requests which delivered data in the correct format and thereby resulted in successful archiving of data will get 200 OK response with a JSON message conveying number of records and the model to which it has been been added. This message looks like:
{
status: OK
msg: "1 Customer added"
}Error handling is done through standard HTTP status codes where code 200 means successful reply (no errors) and any other code describes error conditions while executing the service. Usually error code is accompanied by JSON reply that further describes what went wrong. Generally following error codes are used:
400 – Means that there is something wrong with the request submitted by the client. Usually there is JSON-reply describing the error. In most cases it is caused by missing or malformed request body (JSON), missing mandatory fields in the JSON or Type errors, e.g character instead of number, date/time format issues etc. Below is an example of visitors end point if an empty request body was sent.
{
"status": "NOT OK",
"msg": [
"/visitors: error.path.missing",
"/date: error.path.missing",
"/organisation_id: error.path.missing",
"/time: error.path.missing"
]
}401 – This code means that authentication has failed, due to missing or incorrect access token in authorization header. The response JSON body would be:
{
"status":"NOT OK",
"msg":"Unauthorized"
}404 – Requested service does not exist or request method (eg. GET vs. POST) is incorrect. The response JSON in this case would be:
{
"status":"NOT OK",
"msg":"End point requested does not exist"
}500 – There was an internal error while processing the request. This is often a problem with the service itself. If this persists please contact Zoined service team with detailed information about the error:
{
"status":"NOT OK",
"msg":"An Exception Occurred"
}503 – Service is entirely offline. This indicates maintenance break or problem with the infrastructure. If error persists, please contact support.
Frequently asked questions
Q: How do I choose data format to send my data? A: You need to set Content-Type header in your request to correct value. Zoined API currently supports either JSON or CSV data formats. Any other format is NOT supported and will cause error reply. By default we assume content is application/json but it can be changed to CSV by adding header: Content-Type: application/csv
Q: What is the number format?
No thousand separators. Use dot . as decimal separator.
Q: What is the date format?
A: All dates should be in ISO-format "YYYY-MM-DD".
Q: How do I enter the time? What is "Z" at the end of the time example?
A: Enter the time in 24 hour format "H24:Mi:ss". 'Z' stands for UTC time zone and is optional like all time zone information. Zoined will always use local time so any time zone information is just ignored and no time zone conversions are done.
Q: Do I enter values and headers with quotes (single or double) or without?
A: For JSON, use double quotes for all headers and values. For CSV, do not use anything for either except when escaping special characters (see below).
Q: How do I escape special characters in CSV?
A: If field value has separator character (eg. ;) backslash \ or double quote " in it, you'll need to escape it by wrapping the field value with double quotes " and prefixing any double quotes and backslashes with backslash. For example value example;\"value" should be converted to "example;\\\"value\"". Separator character can be specified with separator query string parameter. By default we assume semicolon ';'. Escape characters ('' and '"') cannot be changed.
Q: What character encoding should be used?
A: For JSON the standard specifies that character set should be Unicode with either UTF-8, UTF-16 or UTF-32 encoding. For CSV you can use any character encoding where separators and other special characters are encoded with single byte. Hence pure multi-byte encodings like UTF-16 are NOT supported with CSV format but mixed ones like UTF-8 are as long as special characters are encoded with single byte. Encoding should be specified with encoding query string parameter and it must correspond to encoding used in actual data. If unspecified then by default UTF-8 is assumed.
Q: How to get best performance for bigger data volume uploads?
A: First of don't send your data one row at a time by making separate API call for each row. That will severely degrade performance of overall data load causing it to take significantly longer time to complete. Instead use fixed size chunks of suitable size (eg. 100000 rows per chunk) for each API call. Json format is also generally slightly faster to process than csv data format.
Data upload
Data upload end points allow one to upload data into Zoined warehouse. Each different data type has their own end points which are documented below, however all of these end points have the same structure. They expect HTTP POST request with either JSON or CSV data as request body. Please not that all end point names in URL string are case sensitive and must be written exactly as written in this document.
JSON data should be array of objects. For example for campaigns this could be
[
{ "campaign_id": "My campaign ID", "campaign_name": "February 2016", "start_date": "2016-02-01", "end_date": "2016-02-29" },
{ "campaign_id": "My campaign ID2", "campaign_name": "March 2016", "start_date": "2016-03-01", "end_date": "2016-03-31" }
]
CSV data should declare fields on the first line (header), and remaining lines should contain data to be uploaded. You can select field separator by adding parameter
separatorto URL (URL escaping might be needed depending on separator char selected). Default separator is;. You also need to escape all field values properly in case they contain separator chars and/or double quotes"or backslashes\. Escaping is done by enclosing whole field with double quotes and adding backslash in front of any double quote or backslash characters. Eg. field:\this\ ;is; "test"would be escaped as:"\\this\\ ;is; \"test\"". For campaigns the uploaded CSV -file could be
campaign_id; campaign_name; start_date; end_date
My Campaign ID; February 2016; 2016-02-01; 2016-02-29
"My Campaign \"March\"";"March 2016";"2016-03-01";"2016-03-31"
Details for usable fields available within individual end point documentation.
Each of the data upload end points also support "dry run" mode where data is validated, but not stored into warehouse. This is useful when testing the API integration, as no changes are stored, but any structural errors are reported immediately.
Our API end points can handle very large messages as received data is streaming within our back-end. However, it usually makes sense to split files into max 5Gb chunks. This makes it faster to retry transfers if there are any network errors while transferring data.
For large files we recommend using Gzip encoding, as it can dramatically reduce amount of data to transfer. Gzip encoding can be used by encoding the data when sending and adding Content-Encoding header.
Content-Encoding: gzip
Sales transactions
This is the main fact entity within Zoined. It contains essential information about sales, such as number of items sold, sales price, rebates and purchase price.
It also links masterdata together by storing information about:
What was sold (Product dimension)
Where was it sold (Organisation dimension)
Who sold it (Salesperson Dimension)
To whom was it sold (Customer dimension)
Upload list of sales transactions
POST https://api.zoined.com/sales?dryRun=false&separator=%3B&encoding=utf-8
Parameters
dryRun | Only validate the request without storing the data Example: | Boolean |
separator | Column separator used when loading CSV data Example: | String |
encoding | Character encoding used in the CSV data (default is utf-8) Example: | String |
Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Unique ID for the transaction |
|
| string | ✅ | Secondary transaction identifier |
|
| string |
| Customer ID for identified customer |
|
| string |
| Delivery Customer ID for identified customer |
|
| string | ✅ | Sales date ( |
|
| string | ✅ | Sales time ( |
|
| string | ✅ | Product ID |
|
| number | ✅ | Sold quantity |
|
| number | ✅ | Unit price for a single product |
|
| number | ✅ | Total sales amount including tax |
|
| number |
| Total sales amount without tax |
|
| number |
| Optional compensation paid for this sale |
|
| number |
| Amount of rebate given including tax |
|
| number |
| Amount of rebate given without tax |
|
| string |
| Sales currency as ISO 4217 currency code. Required if multiple currencies are used. |
|
| string |
| Payment method |
|
| string |
| Supplier ID |
|
| string |
| Parent Product ID |
|
| number |
| Total purchase price including tax |
|
| number |
| Total purchase price without tax |
|
| string |
| Purchase currency as ISO 4217 currency code. Required if multiple currencies are used. |
|
| boolean |
| Unit indicator. |
|
| string | ✅ | Organisation unit ID |
|
| string |
| Store department ID |
|
| string |
| Salesperson ID |
|
| string |
| Responsible salesperson ID |
|
| string |
| Campaign ID |
|
| string |
| Transaction ID of the cancelled receipt |
|
| boolean |
| Indicates whether the transaction is cancelled. Default is |
|
| string |
| Delivery date ( |
|
| string |
| Delivery time ( |
|
| string |
| Order date ( |
|
| string |
| Order time ( |
|
| string |
| Invoice date ( |
|
| string |
| Invoice time ( |
|
| string |
| Cash register ID |
|
| string |
| Table number |
|
| string |
| Rebate code ID |
|
| string |
| Optional reference to the booking that generated this sale. |
|
| string |
| Optional booking line corresponding to this sale. |
|
| string |
| Event ID |
|
| string |
| Sales order ID from which this sales transaction (invoice) originates. |
|
| string |
| Sales order line item ID from which this sales transaction line (invoice) originates. |
|
| string |
| Parent line item ID that this line belongs to. |
|
| string |
| Custom field 1 |
|
| string |
| Custom field 2 |
|
... | ... |
| ... | ... |
| string |
| Custom field 15 |
|
| number |
| Custom metric 1 |
|
| number |
| Custom metric 2 |
|
... | ... |
| ... | ... |
| number |
| Custom metric 10 |
|
| string |
| Identifier of the source system. Required when mapping source system identifiers to master identifiers. |
|
Products
Sales items or services being sold.Products usually belong to product hierarchy which allows one to drill down from top of hierarchy to lower levels in the Zoined Analytics Portal. There are two ways of defining the product hierarchy:
Use FlatHierarchies endpoint with one of the product hierarchy keys entity_id having same product_id value.
Upload product hierarchy using ProductHierarchy endpoint, and add category_id field pointing to correct hierarchy level.
Upload list of products
POST /products
Creates or updates product master data.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Product Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Product ID |
|
| string | ✅ | Product name |
|
| string |
| Product description |
|
| string |
| Product category ID |
|
| number |
| Running average purchase price for the product |
|
| number |
| Default purchase price. Used if a sales transaction does not specify a purchase price. |
|
| number |
| Default retail price including tax |
|
| number |
| Default retail price excluding tax |
|
| number |
| VAT/tax rate |
|
| string |
| Unit of measure |
|
| string |
| Product size |
|
| string |
| Product width |
|
| string |
| Product height |
|
| string |
| Product color |
|
| string |
| Product type |
|
| string |
| Product brand |
|
| string |
| Product season |
|
| string |
| Product model |
|
| string |
| Product model number |
|
| string |
| Country of origin |
|
| number |
| Freight cost |
|
| number |
| Duty |
|
| string |
| Supplier ID |
|
| string |
| Product fabric |
|
| string |
| Buyer name |
|
| string |
| EAN code |
|
| string |
| Parent product ID |
|
| string |
| URL of an external product image |
|
Custom Fields
Field | Type | Description | Example |
| string | Custom field |
|
Custom Metrics
Field | Type | Description | Example |
| number | Custom metric 1 |
|
| number | Custom metric 2 |
|
| number | Custom metric 3 |
|
| number | Custom metric 4 |
|
| number | Custom metric 5 |
|
| number | Custom metric 6 |
|
| number | Custom metric 7 |
|
| number | Custom metric 8 |
|
| number | Custom metric 9 |
|
| number | Custom metric 10 |
|
Additional Fields
Field | Type | Description | Example |
| string | Identifier of the source system. Required when source system identifiers are mapped to master identifiers. |
|
Customers
Customers are identified consumers or businesses that buy your products or services. Details about customers are not shown in the service for data security reasons.
Upload list of customers
POST /customers
Creates or updates customer master data.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Customer Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Customer ID |
|
| string |
| Customer name |
|
| string |
| Customer company |
|
| string |
| Customer email |
|
| string |
| Customer phone |
|
| string |
| Customer street address |
|
| string |
| Customer ZIP/postal code |
|
| string |
| Customer city |
|
| string |
| Customer country |
|
| string |
| Customer group ID |
|
| string |
| Customer group name |
|
| string |
| Account number |
|
| string |
| VAT number |
|
| string |
| Customer account store ID |
|
| string |
| ID of the salesperson responsible for this customer account |
|
| string |
| Date when the customer was added to the system ( |
|
| string |
| Date when the customer subscribed to the newsletter ( |
|
| string |
| Date when the customer unsubscribed from the newsletter ( |
|
| string |
| Date when the customer registered in the system ( |
|
| string |
| Date when the customer unregistered from the system ( |
|
These customer/contact and lifecycle fields are documented in the supplied API material.
Deprecated Hierarchy Fields
Field | Type | Description | Example |
| string | Deprecated. Use the FlatHierarchy endpoint instead. |
|
| string | Deprecated. Use the FlatHierarchy endpoint instead. |
|
| string | Deprecated. Use the FlatHierarchy endpoint instead. |
|
| string | Deprecated. Use the FlatHierarchy endpoint instead. |
|
| string | Deprecated. Use the FlatHierarchy endpoint instead. |
|
Custom Dimensions
Field | Type | Description | Example |
| string | Custom customer dimension/field |
|
The endpoint supports 50 custom dimensions.
Custom Metrics
Field | Type | Description | Example |
| number | Custom metric 1 |
|
| number | Custom metric 2 |
|
| number | Custom metric 3 |
|
| number | Custom metric 4 |
|
| number | Custom metric 5 |
|
Additional Fields
Field | Type | Description | Example |
| string | Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Customer feedback
Customer feedback endpoint can be used to upload either free form survey results or satisfaction grades.
Upload list of customer feedback
POST /customerFeedbacks
Creates or updates customer feedback entries.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Customer Feedback Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Unique ID for this feedback entry |
|
| string |
| Optional ID for the survey respondent. Can be used to group all responses from a single respondent. |
|
| string |
| Optional survey ID. Can be used to separate responses between different surveys. |
|
| string |
| Optional feedback question ID. Recommended when multiple separate feedback questions are used. |
|
| string | ✅ | Identifier of the store this feedback entry refers to |
|
| string |
| Optional identifier of the department this feedback entry refers to |
|
| string | ✅ | Date of feedback ( |
|
| string |
| Optional time of feedback ( |
|
| string |
| Optional type of feedback |
|
| boolean |
| Indicates whether this is the main/overall feedback grade. Default is |
|
| number | ✅ | Numerical grade for the feedback |
|
| number |
| Optional numerical total grade calculated by the source, e.g. a Google Review score |
|
| string |
| Optional free-form feedback |
|
| string |
| Optional free-form feedback translated into English |
|
| string |
| URL of the external review |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Cashier balance
Cashier balance end point can be used to upload cash register book keeping reports mainly used to verify that payments match with store sales.
Upload list of cashier balances
POST /cashierBalance
Creates or updates cashier balance data.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Cashier Balance Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Identifier of the store for this balance |
|
| string |
| Optional identifier of the department for this balance |
|
| string |
| Optional cash register identifier for this balance |
|
| string |
| Optional batch or shift identifier for this balance row |
|
| string | ✅ | Payment method for this balance row |
|
| string | ✅ | Date of the balance ( |
|
| string |
| Optional time of the balance ( |
|
| string |
| Optional status of this batch ID |
|
| number | ✅ | Number of transactions for this shift and payment method |
|
| number | ✅ | Total amount of payments for this shift and payment method |
|
| number |
| Difference between sales and shift amounts |
|
| number |
| Amount of cash dropped from the register during this shift |
|
| number |
| Amount of cash paid out from the register during this shift |
|
| string |
| Shift currency as an ISO 4217 currency code. Required if multiple currencies are used. |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Organisations
Organisations are the sales locations. They can be physical stores, web commerce sites, warehouses or personal payment terminals.
Upload list of organisation units
POST /organisations
Creates or updates organisation/store master data.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Organisation Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Organisation / Store ID |
|
| string | ✅ | Organisation name |
|
| string |
| Street address |
|
| string |
| City |
|
| string |
| Postal code |
|
| string |
| State |
|
| string |
| Country |
|
| string |
| Sales area |
|
| number |
| Latitude |
|
| number |
| Longitude |
|
| string |
| Sales channel |
|
| string |
| Organisation type, e.g. Outlet / Brand / Essential |
|
| string |
| Organisation group |
|
| number |
| Store floor area, e.g. in m² |
|
| number |
| Number of customer seats in the store |
|
| string |
| Google review location URL |
|
| string |
| URL of an external store image |
|
| enum |
| Store status |
|
| string |
| Custom field 1 |
|
| string |
| Custom field 2 |
|
| string |
| Custom field 3 |
|
| string |
| Custom field 4 |
|
| string |
| Custom field 5 |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Departments
Departments are sections of sales locations.
Upload list of departments
POST /departments
Creates or updates department master data.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Department Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Department ID |
|
| string | ✅ | Human-readable name for the department |
|
| number |
| Floor area of the department in square meters |
|
| string |
| ID of the attached organisation |
|
| number |
| Number of customer seats available |
|
| string |
| Custom field 1 |
|
| string |
| Custom field 2 |
|
| string |
| Custom field 3 |
|
| string |
| Custom field 4 |
|
| string |
| Custom field 5 |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Sales persons
This is the sales person associated with the receipt.
Upload list of sales persons
POST /salesPersons
Creates or updates salesperson master data.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Salesperson Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Sales person ID |
|
| string |
| Sales person name |
|
| string |
| Sales person email |
|
| string |
| Sales person phone number |
|
| string |
| Employee ID |
|
| string |
| Employment start date |
|
| string |
| Employment end date |
|
| string |
| Custom field 1 |
|
| string |
| Custom field 2 |
|
| string |
| Custom field 3 |
|
| string |
| Custom field 4 |
|
| string |
| Custom field 5 |
|
| number |
| Custom metric 1 |
|
| number |
| Custom metric 2 |
|
| number |
| Custom metric 3 |
|
| number |
| Custom metric 4 |
|
| number |
| Custom metric 5 |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Cash registers
This is the physical cash register device associated with the receipt.
Upload list of cash registers
POST /cashRegisters
Creates or updates cash register master data.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Cash Register Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Register ID |
|
| string | ✅ | Register name |
|
| string |
| Organisation / store this register belongs to |
|
| string |
| Register type |
|
| string |
| Register group |
|
| string |
| Custom field 1 |
|
| string |
| Custom field 2 |
|
| string |
| Custom field 3 |
|
| string |
| Custom field 4 |
|
| string |
| Custom field 5 |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Store open hours
Open hours end point can be used to upload store open hours for all weekdays and for different seasons. Helps forecasting accuracy.
Upload list of open hours
POST /openHours
Creates or updates opening hours for organisations/stores.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Opening Hours Attributes
Field | Type | Required | Description | Example |
| string |
| Organisation / Store ID. If omitted, the entry is treated as the company default opening hours. |
|
| string | ✅ | Start date of the opening-hours season ( |
|
| string |
| End date of the opening-hours season ( |
|
| number | ✅ | Weekday as an integer ( |
|
| string | ✅ | Opening time ( |
|
| string | ✅ | Closing time ( |
|
| boolean |
| Indicates whether this is a special opening period |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Counters
Counters are visitor counting devices.
Upload list of counters
POST /counters
Creates or updates counter/camera master data.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Counter Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Counter ID |
|
| string | ✅ | Counter name |
|
| string |
| Name of identification folder |
|
| string |
| Camera serial number |
|
| string |
| Camera registration code |
|
| boolean | ✅ |
|
|
| boolean |
|
|
|
| boolean |
|
|
|
| string |
| ID of the store/organisation where the camera is located |
|
| string |
| ID of the department where the camera is located |
|
| string |
| Secondary department ID where in and out counts are reversed |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Accounts
This is the account associated with accounting data.
Upload list of bookkeeping accounts
POST /accounts
Creates or updates account master data.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Account Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Account ID |
|
| string | ✅ | Account name |
|
| string |
| Account type |
|
| string |
| Custom field 1 |
|
| string |
| Custom field 2 |
|
| string |
| Custom field 3 |
|
| string |
| Custom field 4 |
|
| string |
| Custom field 5 |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Events
This is the event associated with booking data.
Upload list of booking events
POST /events
Creates or updates event master data.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Event Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Event ID |
|
| string | ✅ | Event name |
|
| string |
| Event type |
|
| string |
| Venue name |
|
| string |
| Custom field 1 |
|
| string |
| Custom field 2 |
|
| string |
| Custom field 3 |
|
| string |
| Custom field 4 |
|
| string |
| Custom field 5 |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Calendar
Custom calendar attributes can be used to define custom retail calendar like 4-4-5 etc. with year starting and ending at desirable dates. Supported attributes include year, period (month), season and week number.
Upload custom calendar attributes
POST /calendar
Creates or updates calendar data, including reporting periods, weeks, seasons, comparable dates, and bank holidays.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Calendar Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Calendar date ( |
|
| string |
| Calendar year |
|
| string |
| Period name |
|
| number |
| Period number |
|
| number |
| Week number |
|
| string |
| Season name |
|
| string |
| Season identifier |
|
| string |
| Comparable sales date one year ago ( |
|
| string |
| Name of the bank holiday, if any |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Campaigns
A campaign is a sales effort which can be measured for progress and success. Campaigns can be linked to sales transactions either directly or via Campaign Products.
Upload list of campaigns
POST /campaigns
Creates or updates campaign master data.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Campaign Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Campaign ID |
|
| string | ✅ | Campaign name |
|
| string |
| Campaign type |
|
| string |
| Campaign start date ( |
|
| string |
| Campaign end date ( |
|
| string |
| Organisation ID |
|
| string |
| Custom field 1 |
|
| string |
| Custom field 2 |
|
| string |
| Custom field 3 |
|
| string |
| Custom field 4 |
|
| string |
| Custom field 5 |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Campaign products
Campaign products associates products with specific campaigns. This allows creation of campaigns retroactively, but will slow down data loading as each sales row needs to be matched against existing campaigns. Campaign products should only be used if it is not possible to add campaign information directly to sales transactions.
Upload list of campaign products
POST /campaignProducts
Creates or updates associations between campaigns and products.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Campaign Product Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Campaign ID |
|
| string |
| Associated category ID |
|
| string | ✅ | Associated product ID |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Campaign Sales
Campaign sales provides a way to link multiple campaigns to a single sales, sales order or sales offer line. Ordinarily only one campaign can be linked directly but this allows support for any number of campaigns per line.
Upload list of campaign sales
POST /salesCampaigns
Creates or updates campaign associations for sales transaction line items.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Sales Campaign Attributes
Field | Type | Required | Description | Example |
| string | ✅ | ID of the transaction this campaign is associated with |
|
| string | ✅ | Line item ID within the transaction this campaign is associated with |
|
| string | ✅ | Campaign ID |
|
| string |
| Type/origin of the campaign record. Supported values: |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Currency rates
Currency rates allow you to define internal exchange rates between different currencies in use.
Upload list of currency rates
POST /currencyRates
Creates or updates currency exchange rates.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Currency Rate Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Source currency as an ISO 4217 currency code |
|
| string | ✅ | Target currency as an ISO 4217 currency code |
|
| string | ✅ | First day when the exchange rate is valid |
|
| string | ✅ | Last day when the exchange rate is valid |
|
| number | ✅ | Exchange rate from the source currency to the target currency |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Work shifts
Allows you to upload planned of punched work shifts. This is interesting when combined with number of visitors or receipts - are the sales people working during the busiest times?If you are also recording breaks, you should send multiple entries per shift and just have suitable absence codes in place. We'll combine the shifts based on shift ids.
Upload list of work shifts
POST /workShifts
Creates or updates employee work shift data.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Work Shift Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Unique identifier for the work shift |
|
| string | ✅ | Organisation unit where the shift takes place |
|
| string | Conditional | Identifier of the salesperson / employee working. Required for punched shifts. |
|
| string |
| Store department ID |
|
| boolean |
| Whether this is a scheduled or punched shift. Default is |
|
| boolean |
| Whether this is productive or administrative work. Default is |
|
| boolean |
| Whether this shift is calculated as active work time. Default is |
|
| string | ✅ | Shift start date ( |
|
| string | ✅ | Shift start time ( |
|
| number | See note | Duration of the shift in hours |
|
| string | See note | Shift end date ( |
|
| string | See note | Shift end time ( |
|
| string |
| Type of shift. Free-form value available as a dimension in the portal. |
|
| string |
| Type of compensation for the shift |
|
| number |
| Cost associated with this shift |
|
| number |
| Total hours of breaks during this shift |
|
| number |
| Total salary cost associated with paid breaks during this shift |
|
| number |
| Total overtime hours during this shift |
|
| number |
| Total salary cost associated with overtime hours |
|
| string |
| Absence code if this entry describes an absence |
|
| string |
| Currency as an ISO 4217 currency code. Required if multiple currencies are used. |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| number |
| Custom metric 1 |
|
| number |
| Custom metric 2 |
|
| number |
| Custom metric 3 |
|
| number |
| Custom metric 4 |
|
| number |
| Custom metric 5 |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Employee hour entries
Allows you to upload worked hours for specific time. This is interesting when combined with number of visitors or receipts - are the sales people working during the busiest times?This endpoint is intended to be used when you have aggregate level information per minute/hour/day. If your data is consists of workshifts, you should use Workshifts endpoint.
Upload list of employee hour entries
POST /employeeHours
Creates or updates employee hours data.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Employee Hours Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Organisation / Store ID |
|
| string |
| Store department ID |
|
| string |
| Sales person ID |
|
| string |
| Employee type |
|
| string |
| Optional identifier for the entry |
|
| string |
| Absence code if this entry describes an absence |
|
| string | ✅ | Date of entry ( |
|
| string | ✅ | Time of entry ( |
|
| boolean |
| Whether this is a scheduled or punched shift. Default is |
|
| boolean |
| Whether this is productive or administrative work. Default is |
|
| number | ✅ | Number of hours to record for this specific time |
|
| number |
| Salary cost associated with these hours |
|
| number |
| Total hours of breaks |
|
| number |
| Total salary cost associated with paid breaks |
|
| string |
| Currency as an ISO 4217 currency code. Required if multiple currencies are used. |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Hourly staff costs
Allows you to upload store, department or sales person level hourly salaries for specific time period. This data is used as fallback method when provided employee hour or work shift data does not have costs included.
Upload list of staff cost entries
POST /staffCosts
Creates or updates hourly staff cost data.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Staff Cost Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Organisation / Store ID |
|
| string |
| Store department ID |
|
| string |
| Sales person ID |
|
| string | ✅ | Start date of the entry ( |
|
| number | ✅ | Hourly salary cost |
|
| string |
| Currency as an ISO 4217 currency code. Required if multiple currencies are used. |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Inventory snapshots
Inventory snapshots are used to provide product inventory saldo at specific point of time.
Upload list of inventory snapshots
POST /inventorySnapshots
Creates or updates inventory snapshot data.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Inventory Snapshot Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Organisation / Store ID |
|
| string | ✅ | Date of the inventory snapshot ( |
|
| string |
| Time of the inventory snapshot ( |
|
| string | ✅ | Product ID |
|
| string |
| Supplier ID |
|
| number | ✅ | On-hand quantity in inventory |
|
| number |
| Available quantity in inventory after pending/reserved orders |
|
| number |
| Quantity threshold at which more of this item should be ordered |
|
| number |
| Maximum quantity threshold for this item after reordering |
|
| number |
| Unit purchase price |
|
| number |
| Unit purchase price without tax |
|
| number |
| Unit sales price |
|
| number |
| Unit sales price without tax |
|
| string |
| Currency for the purchase price as an ISO 4217 currency code. Required if multiple currencies are used. |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Inventory transactions
Inventory transactions provide information about balance changes in inventories. They allow you to send information when new items have been purchased for inventory, or when existing products have been removed from inventory as waste.Inventory transactions are not used to update inventory saldo values. For that you should use Inventory snapshots.
Upload list of inventory transactions
POST /inventoryTransactions
Creates or updates inventory movement transactions.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Inventory Transaction Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Organisation / Store ID |
|
| string |
| Department ID |
|
| string |
| Sales person ID |
|
| string |
| Operator ID |
|
| string | ✅ | Date of the transaction ( |
|
| string |
| Time of the transaction ( |
|
| string |
| Date of transaction completion ( |
|
| string |
| Time of transaction completion ( |
|
| string | ✅ | Product ID |
|
| string |
| Supplier ID |
|
| string |
| Parent product ID |
|
| number | ✅ | Quantity moved from/to inventory |
|
| number |
| Final quantity moved from/to inventory after completion |
|
| number |
| Quantity expected in inventory, e.g. for stock takes |
|
| enum | ✅ | Inventory movement type |
|
| number |
| Movement status: |
|
| string |
| Optional identifier for the batch this movement row is part of |
|
| string |
| Optional line ID within the batch this movement row is part of |
|
| number |
| Unit purchase price |
|
| number |
| Unit purchase price without tax |
|
| number |
| Unit retail (sales) price |
|
| number |
| Unit retail (sales) price without tax |
|
| string |
| Optional reason code or description for the transaction |
|
| string | Conditional | Organisation / Store ID for the target of an inventory transfer. Mandatory for transfer movements. |
|
| string |
| Currency for the purchase price as an ISO 4217 currency code. Required if multiple currencies are used. |
|
| string |
| Purchase order ID from which this purchase movement originates |
|
| string |
| Purchase order line item ID from which this movement line originates |
|
| string |
| Custom field 1 |
|
| string |
| Custom field 2 |
|
| string |
| Custom field 3 |
|
| string |
| Custom field 4 |
|
| string |
| Custom field 5 |
|
| string |
| Custom field 6 |
|
| string |
| Custom field 7 |
|
| string |
| Custom field 8 |
|
| string |
| Custom field 9 |
|
| string |
| Custom field 10 |
|
| number |
| Custom metric 1 |
|
| number |
| Custom metric 2 |
|
| number |
| Custom metric 3 |
|
| number |
| Custom metric 4 |
|
| number |
| Custom metric 5 |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Capacity
Capacities are used to provide details about available capacity for various resources at specific point of time. These could be eg. hotel rooms or event tickets.
Upload list of capacities
POST /capacity
Creates or updates capacity data for events, tickets, or rooms.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Capacity Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Organisation ID |
|
| string | ✅ | Product ID |
|
| string |
| Event ID |
|
| string | ✅ | Date of capacity ( |
|
| string |
| Time of capacity ( |
|
| string | ✅ | Capacity type. Must be |
|
| number | ✅ | Maximum available capacity for this item |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Flat hierarchies
This end point provides way to upload hierarchy information for different entities like products and organisations in "flat"-form. This means that for each entity its full path in hierarchy is send, and hierarchy tree is build by us based on that.
Upload list of flat hierarchies
POST /flatHierarchies
Creates or updates flat hierarchy data with up to 10 hierarchy levels.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Flat Hierarchy Attributes
Field | Type | Required | Description | Example |
| enum | ✅ | Hierarchy key |
|
| string | ✅ | Identifier for the lowest-level entity in the hierarchy |
|
| string | ✅ | Name of the root category level |
|
| string |
| Name of category level 2 |
|
| string |
| Name of category level 3 |
|
| string |
| Name of category level 4 |
|
| string |
| Name of category level 5 |
|
| string |
| Name of category level 6 |
|
| string |
| Name of category level 7 |
|
| string |
| Name of category level 8 |
|
| string |
| Name of category level 9 |
|
| string |
| Name of category level 10 |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Product hierarchies
Product hierarchies provide a way to assign products into categories and subcategories.
Upload list of product categories
POST /productHierarchies
Creates or updates product category hierarchy data.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Product Hierarchy Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Category ID |
|
| string | ✅ | Category name |
|
| string |
| ID of the parent category. Use |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Rebate codes
The rebate codes can be used to describe reason for giving rebate on sales transactions.
Upload list of rebate codes
POST /rebateCodes
Creates or updates rebate code master data.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Rebate Code Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Rebate code ID |
|
| string | ✅ | Description of the rebate reason |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Payment types
Payment types provide attributes for payment methods used in sales transactions and/or payments.
Upload list of payment types
POST /paymentTypes
Creates or updates payment type data.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Payment Type Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Payment type ID |
|
| string | ✅ | Payment type name |
|
| string |
| Payment group |
|
| string |
| Custom field 1 |
|
| string |
| Custom field 2 |
|
| string |
| Custom field 3 |
|
| string |
| Custom field 4 |
|
| string |
| Custom field 5 |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Purchase orders
This end point can be used to record purchase orders into Zoined service.
Upload list of purchase orders
POST /purchaseOrders
Creates or updates purchase order data.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Purchase Order Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Unique ID for the transaction |
|
| string | ✅ | Secondary transaction identifier |
|
| string | ✅ | Product ID |
|
| string | ✅ | Organisation unit ID |
|
| string |
| Department ID |
|
| string |
| Purchaser ID |
|
| string |
| Supplier ID |
|
| string |
| Parent product ID |
|
| string | ✅ | Order date ( |
|
| string | ✅ | Order time ( |
|
| number | ✅ | Ordered quantity |
|
| string |
| Delivery date ( |
|
| string |
| Delivery time ( |
|
| number |
| Quantity delivered |
|
| string |
| Arrival date ( |
|
| string |
| Arrival time ( |
|
| number | ✅ | Order status: |
|
| string |
| Order type |
|
| number |
| Total purchase price including tax |
|
| number |
| Total purchase price without tax |
|
| number |
| Amount of rebate given including tax |
|
| number |
| Amount of rebate given without tax |
|
| number |
| Total retail (sales) value including tax |
|
| number |
| Total retail (sales) value without tax |
|
| string |
| Purchase currency as an ISO 4217 currency code. Required if multiple currencies are used. |
|
| string |
| Sales unit |
|
| boolean | ✅ | Indicates whether the transaction is cancelled: |
|
| string |
| Transaction ID of the cancelled receipt |
|
| number |
| Gross weight of ordered products |
|
| string |
| Custom field 1 |
|
| string |
| Custom field 2 |
|
| string |
| Custom field 3 |
|
| string |
| Custom field 4 |
|
| string |
| Custom field 5 |
|
| string |
| Custom field 6 |
|
| string |
| Custom field 7 |
|
| string |
| Custom field 8 |
|
| string |
| Custom field 9 |
|
| string |
| Custom field 10 |
|
| number |
| Custom metric 1 |
|
| number |
| Custom metric 2 |
|
| number |
| Custom metric 3 |
|
| number |
| Custom metric 4 |
|
| number |
| Custom metric 5 |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Sales offers
This end point can be used to record sales offers into Zoined service. Offers can be linked to sales orders.
Upload list of sales offers
POST /salesOffers
Creates or updates sales offer data.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Sales Offer Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Unique ID for the transaction |
|
| string | ✅ | Secondary transaction identifier |
|
| string |
| Customer ID for identified customer |
|
| string | ✅ | Product ID |
|
| number | ✅ | Offered quantity |
|
| number | ✅ | Unit price for a single product |
|
| number | ✅ | Total sales amount including tax |
|
| number |
| Total sales amount without tax |
|
| number |
| Amount of rebate given including tax |
|
| number |
| Amount of rebate given without tax |
|
| string |
| Sales currency as an ISO 4217 currency code. Required if multiple currencies are used. |
|
| string |
| Payment method |
|
| string |
| Supplier ID |
|
| string |
| Parent product ID |
|
| number |
| Total purchase price including tax |
|
| number |
| Total purchase price without tax |
|
| string |
| Purchase currency as an ISO 4217 currency code. Required if multiple currencies are used. |
|
| string |
| Organisation unit ID |
|
| string |
| Sales person ID |
|
| string | ✅ | Offer date ( |
|
| string | ✅ | Offer time ( |
|
| string |
| Offer validity date ( |
|
| string |
| Offer validity time ( |
|
| number | ✅ | Offer status: |
|
| string |
| Offer type |
|
| string |
| Custom field 1 |
|
| string |
| Custom field 2 |
|
| string |
| Custom field 3 |
|
| string |
| Custom field 4 |
|
| string |
| Custom field 5 |
|
| string |
| Custom field 6 |
|
| string |
| Custom field 7 |
|
| string |
| Custom field 8 |
|
| string |
| Custom field 9 |
|
| string |
| Custom field 10 |
|
| number |
| Custom metric 1 |
|
| number |
| Custom metric 2 |
|
| number |
| Custom metric 3 |
|
| number |
| Custom metric 4 |
|
| number |
| Custom metric 5 |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Sales orders
This end point can be used to record sales orders into Zoined service.
Upload list of sales orders
POST /salesOrders
Creates or updates sales order data.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Sales Order Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Unique ID for the transaction |
|
| string | ✅ | Secondary transaction identifier |
|
| string |
| Customer ID for identified customer |
|
| string |
| Delivery customer ID for identified customer |
|
| string | ✅ | Product ID |
|
| number | ✅ | Ordered quantity |
|
| number |
| Delivered quantity |
|
| number |
| Planned quantity |
|
| number | ✅ | Unit price for a single product |
|
| number | ✅ | Total sales amount including tax |
|
| number |
| Total sales amount without tax |
|
| number |
| Amount of rebate given including tax |
|
| number |
| Amount of rebate given without tax |
|
| string |
| Rebate code ID |
|
| string |
| Sales currency as an ISO 4217 currency code. Required if multiple currencies are used. |
|
| string |
| Payment method |
|
| number |
| Amount paid using the specified payment method |
|
| number |
| Amount of deposit paid for this order item |
|
| string |
| Supplier ID |
|
| string |
| Parent product ID |
|
| number |
| Total purchase price including tax |
|
| number |
| Total purchase price without tax |
|
| string |
| Purchase currency as an ISO 4217 currency code. Required if multiple currencies are used. |
|
| string |
| Organisation unit ID |
|
| string |
| Department ID |
|
| string |
| Sales person ID |
|
| string |
| Transaction ID of the cancelled receipt |
|
| string |
| Delivery date ( |
|
| string |
| Delivery time ( |
|
| string | ✅ | Order date ( |
|
| string | ✅ | Order time ( |
|
| string |
| Invoice date ( |
|
| string |
| Invoice time ( |
|
| string |
| Arrival date ( |
|
| string |
| Arrival time ( |
|
| number | ✅ | Order status: |
|
| string |
| Order type |
|
| string |
| Customer's internal order ID |
|
| string |
| ID of the related sales offer, if applicable |
|
| string |
| ID of the related sales offer line, if applicable |
|
| string |
| Custom field 1 |
|
| string |
| Custom field 2 |
|
| string |
| Custom field 3 |
|
| string |
| Custom field 4 |
|
| string |
| Custom field 5 |
|
| string |
| Custom field 6 |
|
| string |
| Custom field 7 |
|
| string |
| Custom field 8 |
|
| string |
| Custom field 9 |
|
| string |
| Custom field 10 |
|
| string |
| Custom field 11 |
|
| string |
| Custom field 12 |
|
| string |
| Custom field 13 |
|
| string |
| Custom field 14 |
|
| string |
| Custom field 15 |
|
| number |
| Custom metric 1 |
|
| number |
| Custom metric 2 |
|
| number |
| Custom metric 3 |
|
| number |
| Custom metric 4 |
|
| number |
| Custom metric 5 |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Sales summary
Sales Summary is a reduced, simplified data set that can be used instead of the detailed endpoints. It allows demoing Zoined with own, aggregated data, or can be used in production environment when the more detailed data set is not required or available.
Upload Sales summaries
POST /salesSummaries
Creates or updates aggregated sales summary data.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Sales Summary Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Sales date ( |
|
| string |
| Sales time ( |
|
| string | ✅ | Organisation / Store ID |
|
| string |
| Store department ID |
|
| string |
| Sales person ID |
|
| number |
| Total sales amount including tax |
|
| number |
| Total sales amount without tax |
|
| string |
| Sales currency as an ISO 4217 currency code. Required if multiple currencies are used. |
|
| number |
| Amount of rebate given including tax |
|
| number |
| Amount of rebate given without tax |
|
| number |
| Total purchase price including tax |
|
| number |
| Total purchase price without tax |
|
| string |
| Purchase currency as an ISO 4217 currency code. Required if multiple currencies are used. |
|
| number |
| Sold quantity |
|
| number |
| Number of receipts |
|
| string |
| Product ID |
|
| string |
| Customer ID for identified customer |
|
| string |
| Supplier ID |
|
| string |
| Parent product ID |
|
| string |
| Campaign ID |
|
| string |
| Rebate code ID |
|
| boolean |
| Indicates whether the transaction is cancelled. Default is |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| number |
| Custom metric 1 |
|
| number |
| Custom metric 2 |
|
| number |
| Custom metric 3 |
|
| number |
| Custom metric 4 |
|
| number |
| Custom metric 5 |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Sales payment
Sales payment can be used to send payment data for sales receipts since payment data with multiple payment types per receipt does not mix well with receipt row level transactions. Summed sales values from payment receipts should of course correspond to line item level sum in sales data and transaction_id should be the same as corresponding sales receipt transaction_id so that we can match them together when needed.
Upload sales payments
POST /salesPayments
Creates or updates sales payment data.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Sales Payment Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Unique ID for the transaction. Should match the sales receipt transaction ID where applicable. |
|
| string | ✅ | Transaction line item identifier |
|
| string | ✅ | Sales date ( |
|
| string |
| Sales time ( |
|
| string | ✅ | Organisation / Store ID |
|
| string |
| Store department ID |
|
| string |
| Sales person ID |
|
| string |
| Cash register ID |
|
| string |
| Table number |
|
| string | ✅ | Payment method ID |
|
| string |
| ID used to link a possible gift card used for this payment |
|
| number |
| Total sales amount including tax |
|
| number |
| Total sales amount without tax |
|
| string |
| Currency as an ISO 4217 currency code. Required if multiple currencies are used. |
|
| number |
| Amount of rebate given including tax |
|
| number |
| Amount of rebate given without tax |
|
| string |
| Customer ID for identified customer |
|
| string |
| Delivery customer ID for identified customer |
|
| string |
| Transaction ID of the cancelled receipt |
|
| boolean |
| Indicates whether the transaction is cancelled. Default is |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| number |
| Custom metric 1 |
|
| number |
| Custom metric 2 |
|
| number |
| Custom metric 3 |
|
| number |
| Custom metric 4 |
|
| number |
| Custom metric 5 |
|
| number |
| Custom metric 6 |
|
| number |
| Custom metric 7 |
|
| number |
| Custom metric 8 |
|
| number |
| Custom metric 9 |
|
| number |
| Custom metric 10 |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Giftcard Payments
Giftcard Payments can be used to send giftcard payments data for sales transactions involving gift cards as a payment method. It streamlines the management of giftcard payment information and usage, ensuring accuracy and consistency in sales records.
Upload list of giftcard payments
POST /giftcardPayments
Creates or updates gift card payment data.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Gift Card Payment Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Unique ID for the gift card |
|
| string | ✅ | Gift card number |
|
| string | ✅ | Gift card status |
|
| number |
| Gift card balance |
|
| string | ✅ | Gift card creation date ( |
|
| string |
| Gift card creation time ( |
|
| string |
| Gift card expiration date ( |
|
| string |
| Gift card expiration time ( |
|
| string |
| Sales ID |
|
| string | ✅ | Organisation / Store ID |
|
| string |
| Store department ID |
|
| string |
| Cash register ID |
|
| string |
| Sales person ID |
|
| string |
| Customer ID for identified customer |
|
| string | ✅ | Payment method ID |
|
| string | ✅ | Payment type |
|
| string | ✅ | Payment date ( |
|
| string | ✅ | Payment time ( |
|
| number | ✅ | Payment amount |
|
| string |
| Currency as an ISO 4217 currency code. Required if multiple currencies are used. |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| number |
| Custom metric 1 |
|
| number |
| Custom metric 2 |
|
| number |
| Custom metric 3 |
|
| number |
| Custom metric 4 |
|
| number |
| Custom metric 5 |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Accounting
Accounting can be used to send account level information (receipts) about operational income and costs of running the company. This information is used to eg. to calculate various margins usually found in profit loss statements.
Upload accounting data
POST /accounting
Creates or updates accounting transaction data.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Accounting Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Unique ID for this accounting receipt |
|
| string | ✅ | Unique ID for this accounting receipt line item |
|
| string | ✅ | Organisation / Store ID |
|
| string |
| Store department ID |
|
| string | ✅ | Account ID |
|
| string | ✅ | Event date ( |
|
| string |
| Event time ( |
|
| enum | ✅ | Receipt type |
|
| string |
| Optional bookkeeping receipt number |
|
| number |
| Total amount of this line item |
|
| number |
| Total amount of this line item without taxes |
|
| string |
| Currency as an ISO 4217 currency code. Required if multiple currencies are used. |
|
| boolean |
| Indicates whether this receipt has been cancelled |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Bookings
This end point can be used to record bookings into Zoined service.
Upload list of bookings
POST /bookings
Creates or updates booking data.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Booking Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Unique ID for the booking |
|
| string | ✅ | Secondary booking identifier |
|
| string |
| Customer ID for identified customer |
|
| string | ✅ | Product ID |
|
| string |
| Optional ID for the event this booking is for |
|
| string | ✅ | Organisation unit ID |
|
| string |
| Department ID |
|
| string |
| Sales person ID |
|
| number | ✅ | Booked quantity |
|
| number |
| Number of guests booked |
|
| number |
| Number of visits allowed per guest within the start and end dates |
|
| number | ✅ | Total booking sales amount including tax |
|
| number |
| Total booking sales amount without tax |
|
| string |
| Currency as an ISO 4217 currency code. Required if multiple currencies are used. |
|
| boolean |
| Indicates whether the booking has been cancelled |
|
| string | ✅ | Booking date ( |
|
| string |
| Booking time ( |
|
| string | ✅ | Event start date ( |
|
| string |
| Event start time ( |
|
| string |
| Event end date ( |
|
| string |
| Event end time ( |
|
| string | ✅ | Booking type. Must be |
|
| string |
| Custom field 1 |
|
| string |
| Custom field 2 |
|
| string |
| Custom field 3 |
|
| string |
| Custom field 4 |
|
| string |
| Custom field 5 |
|
| number |
| Custom metric 1 |
|
| number |
| Custom metric 2 |
|
| number |
| Custom metric 3 |
|
| number |
| Custom metric 4 |
|
| number |
| Custom metric 5 |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Suppliers
The party that sells your organisation the goods or merchandise
Upload list of suppliers
POST /suppliers
Creates or updates supplier data.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Supplier Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Supplier ID |
|
| string |
| Supplier name |
|
| string |
| Supplier email |
|
| string |
| Supplier phone number |
|
| string |
| Street address |
|
| string |
| City |
|
| string |
| Postal code |
|
| string |
| Country |
|
| string |
| Supplier group |
|
| string |
| Supplier type |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Visitors
Visitor count information from anti-theft gates or camera systems. Five different types of visitors can be reported: visitors coming in, visitors going out, visitors passing by, visitor average occupancy and visitor average visit time. You can also send data for visiting cars & bicycles for all of these five metrics but default is people.Visitor data can be sent either on store or department level. If department is empty visitors are considered to be entering/leaving/passing/visiting store. If department is specified then visitor entry is considered to be person moving inside the store. When showing visitor counts on portal store-level visitor counts are used, unless data is viewed on department level.
Upload list of visitors
POST /visitors
Creates or updates visitor data.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Visitor Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Organisation / Store ID |
|
| string |
| Department ID |
|
| string |
| Counter ID |
|
| string |
| Optional product ID associated with this visitor (e.g. ticket) |
|
| string |
| Optional customer associated with this visitor (e.g. ticket) |
|
| string | ✅ | Date of visit ( |
|
| string | ✅ | Time of visit ( |
|
| string |
| Optional location time zone |
|
| string |
| Type of visitor record: |
|
| string |
| Optional vehicle type. Supported values are |
|
| string |
| Optional area name for queue cameras |
|
| number |
| Threshold for low queue |
|
| number |
| Threshold for high queue |
|
| number | ✅ | Number of visitors at the given time |
|
| number |
| Custom metric 1 |
|
| number |
| Custom metric 2 |
|
| number |
| Custom metric 3 |
|
| number |
| Custom metric 4 |
|
| number |
| Custom metric 5 |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Field that can be used for custom dimensions |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Visitor demographics
Visitor demographics endpoint can be used to send data for detected visitor's age and gender.Demographic data is usually obtained with different (camera) system, and only for part of the visitors. This API endpoint allows sending of the data separately, so that we can then combine data with visitor information. Our analytics backend will use combined data to project gender & age group estimates into actual visitor counts.
Upload list of visitor demographics
POST /visitorDemographics
Creates or updates visitor demographic data.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Visitor Demographic Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Organisation / Store ID |
|
| string |
| Department ID |
|
| string |
| Counter ID |
|
| string | ✅ | Date of visit ( |
|
| string | ✅ | Time of visit ( |
|
| string |
| Gender of visitor. |
|
| number |
| Age of the visitor |
|
| number | ✅ | Number of visitors for the specified age and gender at the specified time |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Id mapping
ID Mapping allows you to define mappings between identifiers in different source systems and the master data. This allows you to link data between different systems so that they can be correlated and shown in sensible way in Zoined Analytics Portal.
Upload list of identifier mappings
POST /idMapping
Creates or updates mappings between source-system identifiers and master-data identifiers.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
ID Mapping Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Identifier in the source system |
|
| string | ✅ | Identifier in master data |
|
| string | ✅ | Entity type this mapping is for (e.g. |
|
| string | ✅ | Type of data this mapping applies to |
|
| string |
| Identifier of the source system this data is from. Needed when mapping source-system identifiers to master identifiers. |
|
Budgets
Budget end point allows you to upload budgets for individual metrics at the with selected level of granularity. You can for example send daily budget per store and monthly forecasts per category for sales value.
Upload list of budget entries
POST /budgets/type
Creates or updates budget or forecast data.
Parameters
Parameter | Type | Required | Description | Example |
| string |
| Type of budget. Currently supported values are |
|
| boolean |
| For weekly budgets, determines whether to use ISO 8601 weeks or US weeks. Default is |
|
| boolean |
| Only validate the request without storing the data. |
|
Budget Attributes
Field | Type | Required | Description | Example |
| number | ✅ | Year this budget entry refers to |
|
| number |
| Month this budget entry refers to. Either |
|
| number |
| Week number this budget entry refers to. Either |
|
| number |
| Optional day this budget entry refers to |
|
| number |
| Optional hour this budget refers to. |
|
| object | ✅ | Object containing the dimensions for the budget entry |
|
| object | ✅ | Object containing the metrics for the budget entry |
|
Last updated
This end point allows you to send information about last update time stamps for different entities you send to Zoined. After uploading entities you can post last update time stamp for each entity here, optionally on store level. This information is used to report to end users when certain data set was last updated. Times should be posted in UTC time as they will be converted to user local time zone when presented in portal. Similarly entity keys will be localized in user's selected language provided that correct key names are used.
Upload last updated time stamps
POST /updateTime
Updates the timestamp indicating when a specific data entity was last successfully updated.
Query Parameters
Parameter | Type | Required | Description | Example |
| boolean |
| Only validate the request without storing the data. |
|
| string |
| Column separator used when loading CSV data. |
|
| string |
| Character encoding used in the CSV data. Default is |
|
Update Time Attributes
Field | Type | Required | Description | Example |
| string | ✅ | Key of the entity updated. Generally one of the ZAPI endpoint names in lowercase, e.g. |
|
| string |
| Optional organisation unit this update refers to |
|
| string | ✅ | Timestamp when the entity was last successfully updated |
|
| string |
| Identifier of the source system. Needed when mapping source-system identifiers to master identifiers. |
|
Data download
Data download end points provide means for retrieving data from Zoined. This allows building integrations feeding external systems with the data sent to Zoined. Data returned from the download end points closely match the structures used while uploading the data but doesn't always match exactly due to deprecations in upload API and processing on the Zoined system. Each data download end point will contain full list of fields supported. Currently we support both JSON and CSV formats for all download end points.
For large downloads windowing should be used to keep individual result sets reasonable. offset and limit query parameters should be used to control this for each successive request. For example with 100000 limit the first request would be with offset 0, next with 100000, then 200000 and so on. Please note that max limit is hard capped to 1000000 rows per request so tune your parameters accordingly.
Sales transactions
Returns list of sales transactions in the system. Returned data can be limited with start and end query parameters.
Download sales transactions as JSON
Download sales transactions as CSV
Sales orders
Returns list of sales orders in the system. Returned data can be limited with start and end query parameters.
Download sales orders as JSON
Download sales orders as CSV
Sales offers
Returns list of sales offers in the system. Returned data can be limited with start and end query parameters.
Download sales offers as JSON
Download sales offers as CSV
Purchase orders
Returns list of purchase orders in the system. Returned data can be limited with start and end query parameters.
Download purchase orders as JSON
Download purchase orders as CSV
Sales summaries
Returns list of sales summaries in the system. Returned data can be limited with start and end query parameters.
Download sales summaries as JSON
Download sales summaries as CSV
Sales payments
Returns list of sales payments in the system. Returned data can be limited with start and end query parameters.
Download sales payments as JSON
Download sales payments as CSV
Giftcard payments
Returns list of giftcard payments in the system. Returned data can be limited with start and end query parameters.
Download giftcard payments as JSON
Download giftcard payments as CSV
Bookings
Returns list of bookings in the system. Returned data can be limited with start and end query parameters.
Download bookings as JSON
Download bookings as CSV
Accounting data
Returns list of accounting data in the system. Returned data can be limited with start and end query parameters.
Download accounting data as JSON
Download accounting dat as CSV
Cashier balance
Returns list of cashier balances in the system. Returned data can be limited with start and end query parameters.
Download cashier balances as JSON
Download cashier balances as CSV
Customer feedback
Returns list of customer feedback in the system. Returned data can be limited with start and end query parameters.
Download customer feedback as JSON
Download customer feedback as CSV
Inventory transactions
Returns list of inventory transactions in the system. Returned data can be limited with start and end query parameters.
Download inventory transactions as JSON
Download inventory transactions as CSV
Inventory snapshots
Returns list of inventory snapshots in the system. Returned data can be limited with start and end query parameters.
Download inventory snapshots as JSON
Download inventory snapshots as CSV
Capacity
Returns list of resource capacities in the system. Returned data can be limited with start and end query parameters.
Download capacities as JSON
Download capacities as CSV
Visitors
Returns list of visitors in the system. Returned data can be limited with start and end query parameters.
Download visitors as JSON
Download visitors as CSV
Visitor demographics
Returns list of visitor demographics in the system. Returned data can be limited with start and end query parameters.
Download visitor demographics as JSON
Download visitor demographics as CSV
Work shifts
Returns list of worked shifts in the system. Returned data can be limited with start and end query parameters.
Download work shifts as JSON
Download work shifts as CSV
Employee hours
Returns list of employee hours in the system (simpler form of work shifts without shift). Returned data can be limited with start and end query parameters.
Download employee hours as JSON
Download employee hours as CSV
Hourly staff costs
Returns list of hourly store, department and employee level hourly salary data in the system. Returned data can be limited with start and end query parameters.
Download staff costs as JSON
Download staff costs as CSV
Products
Returns list of products in the system. Returned data can be limited with product_id query parameters.
Download products as JSON
Download products as CSV
Customers
Returns list of customers in the system. Returned data can be limited with customer_id query parameters.
Download Customers as JSON
Download Customers as CSV
Organisations
Returns list of organisations in the system. Returned data can be limited with organisation_id query parameters.
Download organisations as JSON
Download organisations as CSV
Departments
Returns list of departments in the system. Returned data can be limited with department_id query parameters.
Download departments as JSON
Download departments as CSV
Sales persons
Returns list of sales persons in the system. Returned data can be limited with salesperson_id query parameters.
Download sales persons as JSON
Download sales persons as CSV
Cash Registers
Returns list of cash registers in the system. Returned data can be limited with register_id query parameter.
Download cash registers as JSON
Download cash registers as CSV
Accounts
Returns list of bookkeeping accounts in the system. Returned data can be limited with account_id query parameter.
Download accounts as JSON
Download accounts as CSV
Events
Returns list of booking events in the system. Returned data can be limited with event_id query parameter.
Download events as JSON
Download events as CSV
Category hierarchies
Returns list of all category hierarchies in the system. Returned data can be limited with category_id and hierarchy_key query parameters.
Download hierarchies as JSON
Download hierarchies as CSV
Flat hierarchies
Returns list of all hierarchies in the system in a flat format. Returned data can be limited with hierarchy_key query parameters.
Download flat hierarchies as JSON
Download flat hierarchies as CSV
Counters
Returns list of visitor counters in the system. Returned data can be limited with counter_id query parameters.
Download counters as JSON
Download counters as CSV
Campaigns
Returns list of campaigns in the system. Returned data can be limited with campaign_id, start and end query parameters.
Download campaigns as JSON
Download campaigns as CSV
Payment types
Returns list of payment types in the system. Returned data can be limited with payment_type_id query parameters.
Download payment types as JSON
Download payment types as CSV
Rebate codes
Returns list of rebate codes in the system. Returned data can be limited with rebate_code_id query parameters.
Download rebate codes as JSON
Download rebate codes as CSV
Suppliers
Returns list of suppliers in the system. Returned data can be limited with id query parameters.
Download suppliers as JSON
Download suppliers as CSV
Custom calendars
Returns custom calendar periods available in the system. Returned data can be limited with year and period query parameters.
Download custom calendar as JSON
Download custom calendar as CSV
Flat calendars
Returns custom calendar periods available in the system in a flat format (one row per day). Returned data can be limited with year query parameter.
Download flat calendar as JSON
Download flat calendar as CSV
Currency rates
Returns currency rates available in the system. Returned data can be limited with start, end and currency query parameters.
Download currency rates as JSON
Download currency rates as CSV
Budgets
Returns budgets available in the system. Returned data can be limited with year query parameter.
Download budgets as JSON
Data queries
These end points allow you to retrieve aggregated data from the warehouse. Results are provided by analytics back-end and as such very closely match the result sets we provide to end users through our portal and newsletters. Hence these end points can be most readily used to get such data sets integrated to other customer systems also. You'll minimally need to provide dimensions you want to group data over and metrics you'd like to see. You can also additionally filter results by time, or by dimension values and sort your result set by given fields.
Query data in tabular format
Returns requested dimensions and metrics as either JSON array or CSV table. Data is limited by default to 1000 entries and pagination information can be found from X-Zoined-* headers.
Query data as JSON
Retrieve tabular data in JSON format (flat array with one element per group).
Query data as CSV
Retrieve tabular data in CSV format. First row contains headers (field names for dimensions and metrics), and rest of the rows contain data values.
Query data in stream format
Returns requested dimensions and metrics as either JSON array or CSV table. Entire flat data set returned by request is always fetched as a streamed http response which client should store in one go. Streamed requests are ideal for fetching large base data sets quickly but they have certain limitations including no support for things like custom result set sorting, secondary aggregation or grouped series.
Query data as JSON stream
Retrieve stream data in JSON format (flat array with one element per group).
Query data as CSV stream
Retrieve stream data in CSV format. First row contains headers (field names for dimensions and metrics), and rest of the rows contain data values.
Maintenance
These endpoints allow you to do maintenance operations for warehouse.
Data
Reset all data in the warehouse
Allows one to do full or selective reset to data in the warehouse. This will allow one to start from clean state if something goes wrong while working with the integration or alternatively just remove some single/multiple bad data set(s). It is only possible to use this API before transitioning to production. After that you'll need to contact Zoined Support if you have need for full or partial warehouse reset. Entity names for selective reset are end point names in lower case and singular form eg. sales, salespayment, salesorder, organisation, product etc.
Selectively delete by given list of ids
This endpoint allows deleting existing transaction data by giving a list of transaction or entity id values already existing in the warehouse. Entity name for selective deletion is one of the end point names in lower case and singular form eg. sales, salespayment, salesorder, organisation, product etc.
Selectively delete by given date range
The endpoint allows deleting existing transaction data by giving a date range (eg. two sales dates) for data already existing in the warehouse. Entity name for selective deletion is one of the end point names in lower case and singular form eg. sales, salespayment, salesorder, organisation, product etc.
Selectively delete by given batch date range
The endpoint allows deleting existing transaction data by giving a batch date range (ie. data receipt timestamp) for data already existing in the warehouse. This endpoint is handy if you want to for example delete eg. all data send to Zoined within last 7 days (to resend it later). Entity name for selective deletion is one of the end point names in lower case and singular form eg. sales, salespayment, salesorder, organisation, product etc.