iKentoo API documentation

Financial REST Service API Guide

Resources

Test authentication

Test Auth

GET /finance/{businessLocationId}/testAuth

Returns a OK status if authentication is correct.

Path parameters

Parameter Type Optional Description

businessLocationId

Integer

false

The business location id.

Query parameters

No parameters.

Request fields

No request body.

Response fields

No response body.

Example request

$ curl 'https://apiBaseEndpoint/finance/1234567/testAuth' -i

Example response

HTTP/1.1 200 OK

Get business’s payment methods

Lookup Payment Methods

GET /finance/{businessLocationId}/paymentMethods

Lookup payment methods of a business location.

Path parameters

Parameter Type Optional Description

businessLocationId

Integer

false

The business location id.

Query parameters

No parameters.

Request fields

No request body.

Response fields

Path Type Optional Description

links

Array[Object]

true

links[].rel

String

true

links[].href

String

true

content

Array[Object]

true

content[].name

String

false

Name of the payment method.

content[].code

String

false

Code of the payment method.

content[].accountingReference

String

true

Payment method accounting reference.

content[].pmId

Integer

true

Immutable internal identifier.

content[].links

Array[Object]

true

content[].links[].rel

String

true

content[].links[].href

String

true

Example request

$ curl 'https://apiBaseEndpoint/finance/1234567/paymentMethods' -i

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 635

{
  "_embedded" : {
    "paymentMethodList" : [ {
      "name" : "Mastercard",
      "code" : "MC",
      "accountingReference" : "creditCard",
      "pmId" : 9904194584600
    }, {
      "name" : "iZettle",
      "code" : "IZTL",
      "pmId" : 9904194584601
    }, {
      "name" : "B7Test",
      "code" : "IKPMS",
      "accountingReference" : "pmd",
      "pmId" : 9904194584602
    }, {
      "name" : "Zapper",
      "code" : "ZAPPER",
      "accountingReference" : "zap",
      "pmId" : 9904194584603
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://apiBaseEndpoint/finance/1234567/paymentMethods"
    }
  }
}

Get business’s accounting groups

Lookup Accounting Groups

GET /finance/{businessLocationId}/accountingGroups

Lookup accounting groups of a business location.

Path parameters

Parameter Type Optional Description

businessLocationId

Integer

false

The business location id.

Query parameters

No parameters.

Request fields

No request body.

Response fields

Path Type Optional Description

links

Array[Object]

true

links[].rel

String

true

links[].href

String

true

content

Array[Object]

true

content[].accountingGroupId

Integer

true

Internal immutable ID for this accounting Group.

content[].name

String

true

Name of this accounting group.

content[].statisticGroup

String

true

Statistic group (can be null).

content[].code

String

true

Optional accounting code as configured by the merchant for this accounting group.

Example request

$ curl 'https://apiBaseEndpoint/finance/1234567/accountingGroups' -i

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 415

{
  "_embedded" : {
    "accountingGroupList" : [ {
      "accountingGroupId" : 1234,
      "name" : "Drinks",
      "code" : "DRI"
    }, {
      "accountingGroupId" : 4567,
      "name" : "Ice cream",
      "code" : "IC"
    }, {
      "accountingGroupId" : 789,
      "name" : "Misc"
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://apiBaseEndpoint/finance/1234567/accountingGroups"
    }
  }
}

Get businesses data

Lookup Businesses

GET /data/businesses

Lookup user businesses and their business locations.

Path parameters

No parameters.

Query parameters

No parameters.

Request fields

No request body.

Response fields

Path Type Optional Description

links

Array[Object]

true

links[].rel

String

true

links[].href

String

true

content

Array[Object]

true

content[].businessName

String

true

Business name.

content[].businessId

Integer

true

Business id.

content[].currencyCode

String

true

Currency as an ISO 3 character code.

content[].businessLocations

Array[Object]

true

The business locations under this business.

content[].businessLocations[].blName

String

true

Business location name.

content[].businessLocations[].blId

Integer

true

Business location id.

content[].businessLocations[].country

String

true

Business location country.

content[].businessLocations[].timezone

String

true

Business location timezone.

content[].businessLocations[].links

Array[Object]

true

content[].businessLocations[].links[].rel

String

true

content[].businessLocations[].links[].href

String

true

content[].links

Array[Object]

true

content[].links[].rel

String

true

content[].links[].href

String

true

Example request

$ curl 'https://apiBaseEndpoint/data/businesses' -i

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 542

{
  "_embedded" : {
    "businessList" : [ {
      "businessName" : "iKentoo",
      "businessId" : 1,
      "currencyCode" : "CHF",
      "businessLocations" : [ {
        "blName" : "Demo",
        "blId" : 25769803788,
        "country" : "CH",
        "timezone" : "Europe/Zurich"
      }, {
        "blName" : "iKentoo 2",
        "blId" : 25769805870,
        "country" : "CH",
        "timezone" : "Europe/Zurich"
      } ]
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://apiBaseEndpoint/data/businesses"
    }
  }
}

Get daily financial data

Get Daily Financials

GET /finance/{businessLocationId}/dailyFinancials

Get the financial data for the business day (or for the given date).

Path parameters

Parameter Type Optional Description

businessLocationId

Integer

false

The business location id.

Query parameters

Parameter Type Optional Description

date

Object

true

The date concerned (not required, by default this is the current date). ISO Date Format yyyy-MM-dd, e.g. "2000-10-31".

includeConsumers

Boolean

true

indicates whether the consumers should be included in the response (default false). Use include param instead, with consumer value.

Default value: 'false'.

include

String

true

(V3 only) comma separated list of additional fields to include in the sales lines. Possible values are: staff, table, consumer, revenue_center, account_profile, payment_authorization.

Default value: ''.

Request fields

No request body.

Response fields

Path Type Optional Description

businessName

String

true

Name of the business location.

nextStartOfDayAsIso8601

String

true

Start of next working day, this field indicates in the merchants local time when the current business day will be closed and a new one is started. Set only with daily endpoints.

businessLocationId

Integer

true

Business location id.

sales

Array[Object]

true

Array of sale objects.

sales[].accountReference

String

true

IKentoo internal account reference.

sales[].accountFiscId

String

true

IKentoo internal account human readable identifier.

sales[].receiptId

String

true

Receipt identifier.

sales[].source

Object

true

V3 only: Account at the source of the current account.

sales[].source.initialAccountId

String

true

First account that generated the current account (can be the same).

sales[].source.previousAccountId

String

true

Account that is directly linked to the current account (may be not set).

sales[].salesLines

Array[Object]

true

Sales items.

sales[].salesLines[].id

String

true

Line identifier.

sales[].salesLines[].parentLineId

String

true

(V3 only) Parent line identifier (if any).

sales[].salesLines[].totalNetAmountWithTax

Decimal

true

Total amount for this line including discounts and tax.

sales[].salesLines[].totalNetAmountWithoutTax

Decimal

true

Total amount for this line excluding tax.

sales[].salesLines[].menuListPrice

Decimal

true

Total amount for this line before service charge and discount if any.

sales[].salesLines[].unitCostPrice

Decimal

true

(V3 only) Cost price of a single item (set to 0 if not provided).

sales[].salesLines[].serviceCharge

Decimal

true

Service charge.

sales[].salesLines[].serviceChargeRate

Decimal

true

Service charge rate.

sales[].salesLines[].discountAmount

Decimal

true

Line discount amount (if any).

sales[].salesLines[].taxAmount

Decimal

true

(V3 only) Tax amount.

sales[].salesLines[].discountType

String

true

Line discount type (if any).

sales[].salesLines[].discountCode

String

true

Line discount code (if any).

sales[].salesLines[].discountName

String

true

Line discount name (if any).

sales[].salesLines[].accountDiscountAmount

Decimal

true

Account discount amount (if any).

sales[].salesLines[].accountDiscountType

String

true

Account discount type (if any).

sales[].salesLines[].accountDiscountCode

String

true

Account discount code (if any).

sales[].salesLines[].accountDiscountName

String

true

Account discount name (if any).

sales[].salesLines[].totalDiscountAmount

Decimal

true

Total discount amount (if any): sum of line level and account level.

sales[].salesLines[].sku

String

true

SKU for this line item, this value is mutable.

sales[].salesLines[].name

String

true

Item name.

sales[].salesLines[].statisticGroup

String

true

Statistic group.

sales[].salesLines[].quantity

Decimal

true

Quantity sold, this value can be a fraction when item is sold by weight for example.

sales[].salesLines[].taxRatePercentage

Decimal

true

Tax rate for this line item as a percentage.

sales[].salesLines[].accountingGroup

Object

true

Accounting group this item belongs to, this value is mutable.

sales[].salesLines[].accountingGroup.accountingGroupId

Integer

true

Internal immutable ID for this accounting Group.

sales[].salesLines[].accountingGroup.name

String

true

Name of this accounting group.

sales[].salesLines[].accountingGroup.statisticGroup

String

true

Statistic group (can be null).

sales[].salesLines[].accountingGroup.code

String

true

Optional accounting code as configured by the merchant for this accounting group.

sales[].salesLines[].currency

String

true

Currency code as an ISO 3 character CODE.

sales[].salesLines[].tags

Array[String]

true

Transaction tags (optional).

sales[].salesLines[].revenueCenter

String

true

V3 only: revenue center name (revenue_center include param).

sales[].salesLines[].revenueCenterId

Integer

true

V3 only: revenue center id (revenue_center include param).

sales[].salesLines[].categories

Array[Object]

true

Transaction categories (V3 only).

sales[].salesLines[].categories[].category

String

true

sales[].salesLines[].categories[].value

String

true

sales[].salesLines[].timeOfSale

String

true

The time in ISO8601 when this sale was made.

sales[].salesLines[].staffId

Integer

true

Staff identifier (with param include=staff).

sales[].salesLines[].staffName

String

true

Staff name (with param include=staff).

sales[].salesLines[].deviceId

Integer

true

Device identifier which produced this transaction line.

sales[].salesLines[].deviceName

String

true

Device name which produced this transaction line.

sales[].salesLines[].voidReason

String

true

Void reason (if the line is voided).

sales[].salesLines[].accountProfileCode

String

true

V3 only: Account profile code (with param include=account_profile).

sales[].payments

Array[Object]

true

Payments. Warning: not included by default in /financials endpoint (please use include param to have it).

sales[].payments[].code

String

true

Payment method code used to settle this payment line.

sales[].payments[].description

String

true

Payment method friendly name used to settle this payment line.

sales[].payments[].paymentMethodId

Integer

true

Payment method internal identifier.

sales[].payments[].netAmountWithTax

Decimal

true

Net paid amount including discounts and tax.

sales[].payments[].currency

String

true

Payment currency code as an ISO 3 character CODE.

sales[].payments[].tip

Decimal

true

Tip amount if any.

sales[].payments[].consumer

Object

true

The consumer.

sales[].payments[].consumer.id

String

true

sales[].payments[].consumer.title

String

true

sales[].payments[].consumer.firstName

String

true

sales[].payments[].consumer.lastName

String

true

sales[].payments[].consumer.phoneNumber1

String

true

sales[].payments[].consumer.phoneNumber2

String

true

sales[].payments[].consumer.companyName

String

true

sales[].payments[].consumer.addressLine1

String

true

sales[].payments[].consumer.addressLine2

String

true

sales[].payments[].consumer.zipCode

String

true

sales[].payments[].consumer.city

String

true

sales[].payments[].consumer.email

String

true

sales[].payments[].consumer.taxIdentifier

String

true

sales[].payments[].consumer.fiscalCode

String

true

sales[].payments[].consumer.destinationCode

String

true

sales[].payments[].consumer.state

String

true

sales[].payments[].type

String

true

V3 only: Payment type:

- NORMAL: normal payment - ACCOUNTS_RECEIVABLE: Payment is due but not received

.

Must be one of [NORMAL, ACCOUNTS_RECEIVABLE].

sales[].payments[].deviceId

Integer

true

Device identifier.

sales[].payments[].deviceName

String

true

Device name.

sales[].payments[].staffId

Integer

true

Tender staff identifier (with param include=staff).

sales[].payments[].staffName

String

true

Tender staff name (with param include=staff).

sales[].payments[].authorization

String

true

Payment authorization.

sales[].payments[].revenueCenter

String

true

V3 only: revenue center name (with param include=revenue_center).

sales[].payments[].revenueCenterId

Integer

true

V3 only: revenue center id (with param include=revenue_center).

sales[].timeOfOpening

String

true

The date on which this account has been opened.

sales[].timeOfCloseAndPaid

String

true

The date on which this sales was made in ISO8601.

sales[].cancelled

Boolean

true

V2 only: indicates whether the sale has been cancelled.

sales[].externalFiscalNumber

String

true

V3 only: external fiscal number (if used).

sales[].tableNumber

String

true

V3 only: table number.

sales[].tableName

String

true

V3 only: table name.

sales[].accountProfileCode

String

true

V3 only: Account profile code (with param include=account_profile).

sales[].ownerName

String

true

V3 only: Account owner name (with param include=staff).

sales[].ownerId

Integer

true

V3 only: Account owner id (with param include=staff).

sales[].type

String

true

V3 only: Sale type:

- SALE: normal sale - VOID: sale that voids another sale - RECALL: sale that recalled another sale - REFUND: sale that refunded another sale - SPLIT: sale that has been splitted from another sale - UPDATE: sale that is used to store payment updates - TRANSFER: sale that is used to store transfers - FLOAT: sale that is used to store cash lifts/drops - TRANSITORY: sale that is carry payments across periods

.

sales[].externalReferences

Array[String]

true

External references, allowing partners to identify the origin of the sale. The format of these references is [type]:[ID in origin system].

sales[].nbCovers

Decimal

true

V3-only: Number of covers for the current account.

In some rare cases of split accounts, the number might be decimal.

sales[].dineIn

Boolean

true

Indicates whether the sale is for dine in or take away/delivery/online orders.

sales[].deviceId

Integer

true

Device identifier.

sales[].deviceName

String

true

Device name.

sales[].voidReason

String

true

Void reason (if the sale is voided).

dataComplete

Boolean

true

Whether the day is closed.

nextPageToken

String

true

Token to use to get the next page if any (only with /financials endpoint).

links

Array[Object]

true

links[].rel

String

true

links[].href

String

true

Example request

$ curl 'https://apiBaseEndpoint/finance/1234567/dailyFinancials?include=consumer' -i

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 3880

{
  "businessName" : "My business location",
  "nextStartOfDayAsIso8601" : "2020-01-14T05:30:00+02:00",
  "businessLocationId" : 1234567,
  "sales" : [ {
    "accountReference" : "0c901700-b964-11e7-8b58-13be377c10re",
    "accountFiscId" : "A4275.9",
    "source" : {
      "initialAccountId" : "A4275.3",
      "previousAccountId" : "A4275.3"
    },
    "salesLines" : [ {
      "totalNetAmountWithTax" : "5.50",
      "menuListPrice" : "5.50",
      "serviceCharge" : "0.50",
      "serviceChargeRate" : "10.00",
      "taxAmount" : "4.6296",
      "sku" : "SKU-BEER",
      "name" : "beer",
      "quantity" : "1.000",
      "taxRatePercentage" : "1.08",
      "accountingGroup" : {
        "accountingGroupId" : 123,
        "name" : "DRINKS",
        "code" : "1200"
      },
      "currency" : "CHF",
      "revenueCenter" : "Poste fixe",
      "revenueCenterId" : 123456,
      "categories" : [ {
        "category" : "default",
        "value" : "Boissons"
      } ]
    } ],
    "payments" : [ {
      "code" : "AMEX",
      "description" : "American Express",
      "netAmountWithTax" : "5.50",
      "currency" : "CHF",
      "tip" : "1.00",
      "consumer" : {
        "id" : "b3854d5a-ea22-44fd-b822-017cdfc83f07",
        "title" : "Sir",
        "firstName" : "John",
        "lastName" : "Doe",
        "phoneNumber1" : "0041 22 700 45 45",
        "phoneNumber2" : "078 123 45 67",
        "companyName" : "iKentoo",
        "addressLine1" : "Route des Jeunes 5",
        "zipCode" : "1227",
        "city" : "Les Acacias",
        "email" : "johnDoe@iKentoo.com"
      },
      "type" : "NORMAL",
      "revenueCenter" : "Poste fixe",
      "revenueCenterId" : 123456
    } ],
    "timeOfOpening" : "2020-01-14T14:30:00+02:00",
    "timeOfCloseAndPaid" : "2020-01-14T14:35:00+02:00",
    "type" : "SALE",
    "externalReferences" : [ "RESA-XX:some-external-id" ],
    "nbCovers" : 6.0,
    "dineIn" : true
  }, {
    "accountReference" : "0c901700-b964-11e7-8b58-13be377c10re",
    "accountFiscId" : "A4275.9",
    "source" : {
      "initialAccountId" : "A4275.3",
      "previousAccountId" : "A4275.3"
    },
    "salesLines" : [ {
      "totalNetAmountWithTax" : "5.50",
      "menuListPrice" : "5.50",
      "serviceCharge" : "0.50",
      "serviceChargeRate" : "10.00",
      "taxAmount" : "4.6296",
      "sku" : "SKU-BEER",
      "name" : "beer",
      "quantity" : "1.000",
      "taxRatePercentage" : "1.08",
      "accountingGroup" : {
        "accountingGroupId" : 123,
        "name" : "DRINKS",
        "code" : "1200"
      },
      "currency" : "CHF",
      "revenueCenter" : "Poste fixe",
      "revenueCenterId" : 123456,
      "categories" : [ {
        "category" : "default",
        "value" : "Boissons"
      } ]
    } ],
    "payments" : [ {
      "code" : "AMEX",
      "description" : "American Express",
      "netAmountWithTax" : "5.50",
      "currency" : "CHF",
      "tip" : "1.00",
      "consumer" : {
        "id" : "b3854d5a-ea22-44fd-b822-017cdfc83f07",
        "title" : "Sir",
        "firstName" : "John",
        "lastName" : "Doe",
        "phoneNumber1" : "0041 22 700 45 45",
        "phoneNumber2" : "078 123 45 67",
        "companyName" : "iKentoo",
        "addressLine1" : "Route des Jeunes 5",
        "zipCode" : "1227",
        "city" : "Les Acacias",
        "email" : "johnDoe@iKentoo.com"
      },
      "type" : "NORMAL",
      "revenueCenter" : "Poste fixe",
      "revenueCenterId" : 123456
    } ],
    "timeOfOpening" : "2020-01-14T14:30:00+02:00",
    "timeOfCloseAndPaid" : "2020-01-14T14:35:00+02:00",
    "type" : "SALE",
    "externalReferences" : [ ],
    "nbCovers" : 6.0,
    "dineIn" : false
  } ],
  "dataComplete" : true,
  "_links" : {
    "self" : {
      "href" : "https://apiBaseEndpoint/finance/1234567/dailyFinancials?date=2020-01-14&includeConsumers=true&include=consumer"
    }
  }
}

Get financial data (with time range and page size)

Get Financials

GET /finance/{businessLocationId}/financials/{from}/{to}

(V3 only) Get financial for a given time range.

Path parameters

Parameter Type Optional Description

businessLocationId

Integer

false

The business location id.

from

Object

false

Time range start (included). Must be after the change to version 3.

to

Object

false

Time range end (excluded).

Query parameters

Parameter Type Optional Description

include

String

true

Comma separated list of additional fields to include in the sales lines. Possible values are: staff, table, consumer, payments, revenue_center, account_profile, payment_authorization.

Default value: ''.

pageSize

Integer

true

Number of results to return. If the given value exceed the system configured value, it will be floored.

Default value: '1000'.

nextPageToken

String

true

Token to use to get the next page (given in results if there is a following page).

Default value: ''.

Request fields

No request body.

Response fields

Path Type Optional Description

businessName

String

true

Name of the business location.

nextStartOfDayAsIso8601

String

true

Start of next working day, this field indicates in the merchants local time when the current business day will be closed and a new one is started. Set only with daily endpoints.

businessLocationId

Integer

true

Business location id.

sales

Array[Object]

true

Array of sale objects.

sales[].accountReference

String

true

IKentoo internal account reference.

sales[].accountFiscId

String

true

IKentoo internal account human readable identifier.

sales[].receiptId

String

true

Receipt identifier.

sales[].source

Object

true

V3 only: Account at the source of the current account.

sales[].source.initialAccountId

String

true

First account that generated the current account (can be the same).

sales[].source.previousAccountId

String

true

Account that is directly linked to the current account (may be not set).

sales[].salesLines

Array[Object]

true

Sales items.

sales[].salesLines[].id

String

true

Line identifier.

sales[].salesLines[].parentLineId

String

true

(V3 only) Parent line identifier (if any).

sales[].salesLines[].totalNetAmountWithTax

Decimal

true

Total amount for this line including discounts and tax.

sales[].salesLines[].totalNetAmountWithoutTax

Decimal

true

Total amount for this line excluding tax.

sales[].salesLines[].menuListPrice

Decimal

true

Total amount for this line before service charge and discount if any.

sales[].salesLines[].unitCostPrice

Decimal

true

(V3 only) Cost price of a single item (set to 0 if not provided).

sales[].salesLines[].serviceCharge

Decimal

true

Service charge.

sales[].salesLines[].serviceChargeRate

Decimal

true

Service charge rate.

sales[].salesLines[].discountAmount

Decimal

true

Line discount amount (if any).

sales[].salesLines[].taxAmount

Decimal

true

(V3 only) Tax amount.

sales[].salesLines[].discountType

String

true

Line discount type (if any).

sales[].salesLines[].discountCode

String

true

Line discount code (if any).

sales[].salesLines[].discountName

String

true

Line discount name (if any).

sales[].salesLines[].accountDiscountAmount

Decimal

true

Account discount amount (if any).

sales[].salesLines[].accountDiscountType

String

true

Account discount type (if any).

sales[].salesLines[].accountDiscountCode

String

true

Account discount code (if any).

sales[].salesLines[].accountDiscountName

String

true

Account discount name (if any).

sales[].salesLines[].totalDiscountAmount

Decimal

true

Total discount amount (if any): sum of line level and account level.

sales[].salesLines[].sku

String

true

SKU for this line item, this value is mutable.

sales[].salesLines[].name

String

true

Item name.

sales[].salesLines[].statisticGroup

String

true

Statistic group.

sales[].salesLines[].quantity

Decimal

true

Quantity sold, this value can be a fraction when item is sold by weight for example.

sales[].salesLines[].taxRatePercentage

Decimal

true

Tax rate for this line item as a percentage.

sales[].salesLines[].accountingGroup

Object

true

Accounting group this item belongs to, this value is mutable.

sales[].salesLines[].accountingGroup.accountingGroupId

Integer

true

Internal immutable ID for this accounting Group.

sales[].salesLines[].accountingGroup.name

String

true

Name of this accounting group.

sales[].salesLines[].accountingGroup.statisticGroup

String

true

Statistic group (can be null).

sales[].salesLines[].accountingGroup.code

String

true

Optional accounting code as configured by the merchant for this accounting group.

sales[].salesLines[].currency

String

true

Currency code as an ISO 3 character CODE.

sales[].salesLines[].tags

Array[String]

true

Transaction tags (optional).

sales[].salesLines[].revenueCenter

String

true

V3 only: revenue center name (revenue_center include param).

sales[].salesLines[].revenueCenterId

Integer

true

V3 only: revenue center id (revenue_center include param).

sales[].salesLines[].categories

Array[Object]

true

Transaction categories (V3 only).

sales[].salesLines[].categories[].category

String

true

sales[].salesLines[].categories[].value

String

true

sales[].salesLines[].timeOfSale

String

true

The time in ISO8601 when this sale was made.

sales[].salesLines[].staffId

Integer

true

Staff identifier (with param include=staff).

sales[].salesLines[].staffName

String

true

Staff name (with param include=staff).

sales[].salesLines[].deviceId

Integer

true

Device identifier which produced this transaction line.

sales[].salesLines[].deviceName

String

true

Device name which produced this transaction line.

sales[].salesLines[].voidReason

String

true

Void reason (if the line is voided).

sales[].salesLines[].accountProfileCode

String

true

V3 only: Account profile code (with param include=account_profile).

sales[].payments

Array[Object]

true

Payments. Warning: not included by default in /financials endpoint (please use include param to have it).

sales[].payments[].code

String

true

Payment method code used to settle this payment line.

sales[].payments[].description

String

true

Payment method friendly name used to settle this payment line.

sales[].payments[].paymentMethodId

Integer

true

Payment method internal identifier.

sales[].payments[].netAmountWithTax

Decimal

true

Net paid amount including discounts and tax.

sales[].payments[].currency

String

true

Payment currency code as an ISO 3 character CODE.

sales[].payments[].tip

Decimal

true

Tip amount if any.

sales[].payments[].consumer

Object

true

The consumer.

sales[].payments[].consumer.id

String

true

sales[].payments[].consumer.title

String

true

sales[].payments[].consumer.firstName

String

true

sales[].payments[].consumer.lastName

String

true

sales[].payments[].consumer.phoneNumber1

String

true

sales[].payments[].consumer.phoneNumber2

String

true

sales[].payments[].consumer.companyName

String

true

sales[].payments[].consumer.addressLine1

String

true

sales[].payments[].consumer.addressLine2

String

true

sales[].payments[].consumer.zipCode

String

true

sales[].payments[].consumer.city

String

true

sales[].payments[].consumer.email

String

true

sales[].payments[].consumer.taxIdentifier

String

true

sales[].payments[].consumer.fiscalCode

String

true

sales[].payments[].consumer.destinationCode

String

true

sales[].payments[].consumer.state

String

true

sales[].payments[].type

String

true

V3 only: Payment type:

- NORMAL: normal payment - ACCOUNTS_RECEIVABLE: Payment is due but not received

.

Must be one of [NORMAL, ACCOUNTS_RECEIVABLE].

sales[].payments[].deviceId

Integer

true

Device identifier.

sales[].payments[].deviceName

String

true

Device name.

sales[].payments[].staffId

Integer

true

Tender staff identifier (with param include=staff).

sales[].payments[].staffName

String

true

Tender staff name (with param include=staff).

sales[].payments[].authorization

String

true

Payment authorization.

sales[].payments[].revenueCenter

String

true

V3 only: revenue center name (with param include=revenue_center).

sales[].payments[].revenueCenterId

Integer

true

V3 only: revenue center id (with param include=revenue_center).

sales[].timeOfOpening

String

true

The date on which this account has been opened.

sales[].timeOfCloseAndPaid

String

true

The date on which this sales was made in ISO8601.

sales[].cancelled

Boolean

true

V2 only: indicates whether the sale has been cancelled.

sales[].externalFiscalNumber

String

true

V3 only: external fiscal number (if used).

sales[].tableNumber

String

true

V3 only: table number.

sales[].tableName

String

true

V3 only: table name.

sales[].accountProfileCode

String

true

V3 only: Account profile code (with param include=account_profile).

sales[].ownerName

String

true

V3 only: Account owner name (with param include=staff).

sales[].ownerId

Integer

true

V3 only: Account owner id (with param include=staff).

sales[].type

String

true

V3 only: Sale type:

- SALE: normal sale - VOID: sale that voids another sale - RECALL: sale that recalled another sale - REFUND: sale that refunded another sale - SPLIT: sale that has been splitted from another sale - UPDATE: sale that is used to store payment updates - TRANSFER: sale that is used to store transfers - FLOAT: sale that is used to store cash lifts/drops - TRANSITORY: sale that is carry payments across periods

.

sales[].externalReferences

Array[String]

true

External references, allowing partners to identify the origin of the sale. The format of these references is [type]:[ID in origin system].

sales[].nbCovers

Decimal

true

V3-only: Number of covers for the current account.

In some rare cases of split accounts, the number might be decimal.

sales[].dineIn

Boolean

true

Indicates whether the sale is for dine in or take away/delivery/online orders.

sales[].deviceId

Integer

true

Device identifier.

sales[].deviceName

String

true

Device name.

sales[].voidReason

String

true

Void reason (if the sale is voided).

dataComplete

Boolean

true

Whether the day is closed.

nextPageToken

String

true

Token to use to get the next page if any (only with /financials endpoint).

links

Array[Object]

true

links[].rel

String

true

links[].href

String

true

Example request

$ curl 'https://apiBaseEndpoint/finance/1234567/financials/2019-07-11T14:00:00+02:00/2019-07-11T15:30:00+02:00?include=payments&pageSize=500' -i

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 3883

{
  "businessName" : "My business location",
  "businessLocationId" : 1234567,
  "sales" : [ {
    "accountReference" : "0c901700-b964-11e7-8b58-13be377c10re",
    "accountFiscId" : "A4275.9",
    "source" : {
      "initialAccountId" : "A4275.3",
      "previousAccountId" : "A4275.3"
    },
    "salesLines" : [ {
      "totalNetAmountWithTax" : "5.50",
      "menuListPrice" : "5.50",
      "serviceCharge" : "0.50",
      "serviceChargeRate" : "10.00",
      "taxAmount" : "4.6296",
      "sku" : "SKU-BEER",
      "name" : "beer",
      "quantity" : "1.000",
      "taxRatePercentage" : "1.08",
      "accountingGroup" : {
        "accountingGroupId" : 123,
        "name" : "DRINKS",
        "code" : "1200"
      },
      "currency" : "CHF",
      "revenueCenter" : "Poste fixe",
      "revenueCenterId" : 123456,
      "categories" : [ {
        "category" : "default",
        "value" : "Boissons"
      } ]
    } ],
    "payments" : [ {
      "code" : "AMEX",
      "description" : "American Express",
      "netAmountWithTax" : "5.50",
      "currency" : "CHF",
      "tip" : "1.00",
      "consumer" : {
        "id" : "b3854d5a-ea22-44fd-b822-017cdfc83f07",
        "title" : "Sir",
        "firstName" : "John",
        "lastName" : "Doe",
        "phoneNumber1" : "0041 22 700 45 45",
        "phoneNumber2" : "078 123 45 67",
        "companyName" : "iKentoo",
        "addressLine1" : "Route des Jeunes 5",
        "zipCode" : "1227",
        "city" : "Les Acacias",
        "email" : "johnDoe@iKentoo.com"
      },
      "type" : "NORMAL",
      "revenueCenter" : "Poste fixe",
      "revenueCenterId" : 123456
    } ],
    "timeOfOpening" : "2020-01-14T14:30:00+02:00",
    "timeOfCloseAndPaid" : "2020-01-14T14:35:00+02:00",
    "type" : "SALE",
    "externalReferences" : [ "RESA-XX:some-external-id" ],
    "nbCovers" : 6.0,
    "dineIn" : true
  }, {
    "accountReference" : "0c901700-b964-11e7-8b58-13be377c10re",
    "accountFiscId" : "A4275.9",
    "source" : {
      "initialAccountId" : "A4275.3",
      "previousAccountId" : "A4275.3"
    },
    "salesLines" : [ {
      "totalNetAmountWithTax" : "5.50",
      "menuListPrice" : "5.50",
      "serviceCharge" : "0.50",
      "serviceChargeRate" : "10.00",
      "taxAmount" : "4.6296",
      "sku" : "SKU-BEER",
      "name" : "beer",
      "quantity" : "1.000",
      "taxRatePercentage" : "1.08",
      "accountingGroup" : {
        "accountingGroupId" : 123,
        "name" : "DRINKS",
        "code" : "1200"
      },
      "currency" : "CHF",
      "revenueCenter" : "Poste fixe",
      "revenueCenterId" : 123456,
      "categories" : [ {
        "category" : "default",
        "value" : "Boissons"
      } ]
    } ],
    "payments" : [ {
      "code" : "AMEX",
      "description" : "American Express",
      "netAmountWithTax" : "5.50",
      "currency" : "CHF",
      "tip" : "1.00",
      "consumer" : {
        "id" : "b3854d5a-ea22-44fd-b822-017cdfc83f07",
        "title" : "Sir",
        "firstName" : "John",
        "lastName" : "Doe",
        "phoneNumber1" : "0041 22 700 45 45",
        "phoneNumber2" : "078 123 45 67",
        "companyName" : "iKentoo",
        "addressLine1" : "Route des Jeunes 5",
        "zipCode" : "1227",
        "city" : "Les Acacias",
        "email" : "johnDoe@iKentoo.com"
      },
      "type" : "NORMAL",
      "revenueCenter" : "Poste fixe",
      "revenueCenterId" : 123456
    } ],
    "timeOfOpening" : "2020-01-14T14:30:00+02:00",
    "timeOfCloseAndPaid" : "2020-01-14T14:35:00+02:00",
    "type" : "SALE",
    "externalReferences" : [ ],
    "nbCovers" : 6.0,
    "dineIn" : false
  } ],
  "dataComplete" : true,
  "nextPageToken" : "",
  "_links" : {
    "self" : {
      "href" : "https://apiBaseEndpoint/finance/1234567/financials/2019-07-11T14:00:00+02:00/2019-07-11T15:30:00+02:00?include=payments&pageSize=1000&nextPageToken="
    }
  }
}

Get aggregated daily sales

Get Aggregated Sales

GET /finance/{businessLocationId}/aggregatedSales

Get the aggregated sales for the business day (or for the given date) with different levels (one or several) of aggregations. Aggregations are done in the order of the groupBy keywords. A time range can be asked with the parameters from and to, it can not be combined with date.

Path parameters

Parameter Type Optional Description

businessLocationId

Integer

false

The business location id.

Query parameters

Parameter Type Optional Description

date

Object

true

The date concerned (not required, by default this is the current date). ISO Date Format yyyy-MM-dd, e.g. "2000-10-31".

groupBy

String

false

List (comma separated) of aggregators: staff, device, deviceId, tag, accountingGroup, statisticGroup, hour, sku OR a category in the format of 'category:%group%'.

Size must be between 3 and 2147483647 inclusive.

flattened

Boolean

true

To have a flattened response.

Default value: 'false'.

from

Object

true

Time range start (included). Must be after the change to version 3. ISO 8601 date time (url encoded).

to

Object

true

Time range end (excluded). ISO 8601 date time (url encoded).

Request fields

No request body.

Response fields

No response body.

Example request

$ curl 'https://apiBaseEndpoint/finance/1234567/aggregatedSales?groupBy=staff,device,accountingGroup' -i

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1466

{
  "totalAmount" : "131.25",
  "serviceCharge" : "17.25",
  "totalDiscountedAmount" : "0.00",
  "totalTaxAmount" : "9.38",
  "numberOfSales" : 13.0,
  "children" : [ {
    "groupByKey" : "staff",
    "children" : [ {
      "groupByValue" : "Arnaud",
      "totalAmount" : "131.25",
      "serviceCharge" : "17.25",
      "totalDiscountedAmount" : "0.00",
      "totalTaxAmount" : "9.38",
      "numberOfSales" : 13.0,
      "children" : [ {
        "groupByKey" : "device",
        "children" : [ {
          "groupByValue" : "iPad29",
          "totalAmount" : "131.25",
          "serviceCharge" : "17.25",
          "totalDiscountedAmount" : "0.00",
          "totalTaxAmount" : "9.38",
          "numberOfSales" : 13.0,
          "children" : [ {
            "groupByKey" : "accountingGroup",
            "children" : [ {
              "groupByValue" : "Cuisine",
              "totalAmount" : "104.80",
              "serviceCharge" : "13.80",
              "totalDiscountedAmount" : "0.00",
              "totalTaxAmount" : "7.49",
              "numberOfSales" : 8.0
            }, {
              "groupByValue" : "Boissons",
              "totalAmount" : "26.45",
              "serviceCharge" : "3.45",
              "totalDiscountedAmount" : "0.00",
              "totalTaxAmount" : "1.89",
              "numberOfSales" : 5.0
            } ]
          } ]
        } ]
      } ]
    } ]
  } ],
  "dataComplete" : true,
  "businessName" : "iKentoo test"
}

Example request (flattened format)

$ curl 'https://apiBaseEndpoint/finance/1234567/aggregatedSales?groupBy=accountingGroup,hour&flattened=true' -i

Example response (flattened format)

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 559

[ {
  "fields" : {
    "device" : "iPad29",
    "accountingGroup" : "Cuisine",
    "staff" : "Arnaud"
  },
  "totalAmount" : "104.80",
  "serviceCharge" : "13.80",
  "totalDiscountedAmount" : "0.00",
  "totalTaxAmount" : "7.49",
  "numberOfSales" : 8.0,
  "dataComplete" : true
}, {
  "fields" : {
    "device" : "iPad29",
    "accountingGroup" : "Boissons",
    "staff" : "Arnaud"
  },
  "totalAmount" : "26.45",
  "serviceCharge" : "3.45",
  "totalDiscountedAmount" : "0.00",
  "totalTaxAmount" : "1.89",
  "numberOfSales" : 5.0,
  "dataComplete" : true
} ]

Get sale by external reference ID

Get Sale By External Ref

GET /finance/{businessLocationId}/saleByExternalReference

Get a single sale detail by external reference.

Path parameters

Parameter Type Optional Description

businessLocationId

Integer

false

The business location id.

Query parameters

Parameter Type Optional Description

externalReferenceId

String

false

External reference.

Request fields

No request body.

Response fields

Path Type Optional Description

accountReference

String

true

IKentoo internal account reference.

accountFiscId

String

true

IKentoo internal account human readable identifier.

receiptId

String

true

Receipt identifier.

source

Object

true

V3 only: Account at the source of the current account.

source.initialAccountId

String

true

First account that generated the current account (can be the same).

source.previousAccountId

String

true

Account that is directly linked to the current account (may be not set).

salesLines

Array[Object]

true

Sales items.

salesLines[].id

String

true

Line identifier.

salesLines[].parentLineId

String

true

(V3 only) Parent line identifier (if any).

salesLines[].totalNetAmountWithTax

Decimal

true

Total amount for this line including discounts and tax.

salesLines[].totalNetAmountWithoutTax

Decimal

true

Total amount for this line excluding tax.

salesLines[].menuListPrice

Decimal

true

Total amount for this line before service charge and discount if any.

salesLines[].unitCostPrice

Decimal

true

(V3 only) Cost price of a single item (set to 0 if not provided).

salesLines[].serviceCharge

Decimal

true

Service charge.

salesLines[].serviceChargeRate

Decimal

true

Service charge rate.

salesLines[].discountAmount

Decimal

true

Line discount amount (if any).

salesLines[].taxAmount

Decimal

true

(V3 only) Tax amount.

salesLines[].discountType

String

true

Line discount type (if any).

salesLines[].discountCode

String

true

Line discount code (if any).

salesLines[].discountName

String

true

Line discount name (if any).

salesLines[].accountDiscountAmount

Decimal

true

Account discount amount (if any).

salesLines[].accountDiscountType

String

true

Account discount type (if any).

salesLines[].accountDiscountCode

String

true

Account discount code (if any).

salesLines[].accountDiscountName

String

true

Account discount name (if any).

salesLines[].totalDiscountAmount

Decimal

true

Total discount amount (if any): sum of line level and account level.

salesLines[].sku

String

true

SKU for this line item, this value is mutable.

salesLines[].name

String

true

Item name.

salesLines[].statisticGroup

String

true

Statistic group.

salesLines[].quantity

Decimal

true

Quantity sold, this value can be a fraction when item is sold by weight for example.

salesLines[].taxRatePercentage

Decimal

true

Tax rate for this line item as a percentage.

salesLines[].accountingGroup

Object

true

Accounting group this item belongs to, this value is mutable.

salesLines[].accountingGroup.accountingGroupId

Integer

true

Internal immutable ID for this accounting Group.

salesLines[].accountingGroup.name

String

true

Name of this accounting group.

salesLines[].accountingGroup.statisticGroup

String

true

Statistic group (can be null).

salesLines[].accountingGroup.code

String

true

Optional accounting code as configured by the merchant for this accounting group.

salesLines[].currency

String

true

Currency code as an ISO 3 character CODE.

salesLines[].tags

Array[String]

true

Transaction tags (optional).

salesLines[].revenueCenter

String

true

V3 only: revenue center name (revenue_center include param).

salesLines[].revenueCenterId

Integer

true

V3 only: revenue center id (revenue_center include param).

salesLines[].categories

Array[Object]

true

Transaction categories (V3 only).

salesLines[].categories[].category

String

true

salesLines[].categories[].value

String

true

salesLines[].timeOfSale

String

true

The time in ISO8601 when this sale was made.

salesLines[].staffId

Integer

true

Staff identifier (with param include=staff).

salesLines[].staffName

String

true

Staff name (with param include=staff).

salesLines[].deviceId

Integer

true

Device identifier which produced this transaction line.

salesLines[].deviceName

String

true

Device name which produced this transaction line.

salesLines[].voidReason

String

true

Void reason (if the line is voided).

salesLines[].accountProfileCode

String

true

V3 only: Account profile code (with param include=account_profile).

payments

Array[Object]

true

Payments. Warning: not included by default in /financials endpoint (please use include param to have it).

payments[].code

String

true

Payment method code used to settle this payment line.

payments[].description

String

true

Payment method friendly name used to settle this payment line.

payments[].paymentMethodId

Integer

true

Payment method internal identifier.

payments[].netAmountWithTax

Decimal

true

Net paid amount including discounts and tax.

payments[].currency

String

true

Payment currency code as an ISO 3 character CODE.

payments[].tip

Decimal

true

Tip amount if any.

payments[].consumer

Object

true

The consumer.

payments[].consumer.id

String

true

payments[].consumer.title

String

true

payments[].consumer.firstName

String

true

payments[].consumer.lastName

String

true

payments[].consumer.phoneNumber1

String

true

payments[].consumer.phoneNumber2

String

true

payments[].consumer.companyName

String

true

payments[].consumer.addressLine1

String

true

payments[].consumer.addressLine2

String

true

payments[].consumer.zipCode

String

true

payments[].consumer.city

String

true

payments[].consumer.email

String

true

payments[].consumer.taxIdentifier

String

true

payments[].consumer.fiscalCode

String

true

payments[].consumer.destinationCode

String

true

payments[].consumer.state

String

true

payments[].type

String

true

V3 only: Payment type:

- NORMAL: normal payment - ACCOUNTS_RECEIVABLE: Payment is due but not received

.

Must be one of [NORMAL, ACCOUNTS_RECEIVABLE].

payments[].deviceId

Integer

true

Device identifier.

payments[].deviceName

String

true

Device name.

payments[].staffId

Integer

true

Tender staff identifier (with param include=staff).

payments[].staffName

String

true

Tender staff name (with param include=staff).

payments[].authorization

String

true

Payment authorization.

payments[].revenueCenter

String

true

V3 only: revenue center name (with param include=revenue_center).

payments[].revenueCenterId

Integer

true

V3 only: revenue center id (with param include=revenue_center).

timeOfOpening

String

true

The date on which this account has been opened.

timeOfCloseAndPaid

String

true

The date on which this sales was made in ISO8601.

cancelled

Boolean

true

V2 only: indicates whether the sale has been cancelled.

externalFiscalNumber

String

true

V3 only: external fiscal number (if used).

tableNumber

String

true

V3 only: table number.

tableName

String

true

V3 only: table name.

accountProfileCode

String

true

V3 only: Account profile code (with param include=account_profile).

ownerName

String

true

V3 only: Account owner name (with param include=staff).

ownerId

Integer

true

V3 only: Account owner id (with param include=staff).

type

String

true

V3 only: Sale type:

- SALE: normal sale - VOID: sale that voids another sale - RECALL: sale that recalled another sale - REFUND: sale that refunded another sale - SPLIT: sale that has been splitted from another sale - UPDATE: sale that is used to store payment updates - TRANSFER: sale that is used to store transfers - FLOAT: sale that is used to store cash lifts/drops - TRANSITORY: sale that is carry payments across periods

.

externalReferences

Array[String]

true

External references, allowing partners to identify the origin of the sale. The format of these references is [type]:[ID in origin system].

nbCovers

Decimal

true

V3-only: Number of covers for the current account.

In some rare cases of split accounts, the number might be decimal.

dineIn

Boolean

true

Indicates whether the sale is for dine in or take away/delivery/online orders.

deviceId

Integer

true

Device identifier.

deviceName

String

true

Device name.

voidReason

String

true

Void reason (if the sale is voided).

Example request

$ curl 'https://apiBaseEndpoint/finance/1234567/saleByExternalReference?externalReferenceId=RESA-XX:some-external-id' -i

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1659

{
  "accountReference" : "0c901700-b964-11e7-8b58-13be377c10re",
  "accountFiscId" : "A4275.9",
  "source" : {
    "initialAccountId" : "A4275.3",
    "previousAccountId" : "A4275.3"
  },
  "salesLines" : [ {
    "totalNetAmountWithTax" : "5.50",
    "menuListPrice" : "5.50",
    "serviceCharge" : "0.50",
    "serviceChargeRate" : "10.00",
    "taxAmount" : "4.6296",
    "sku" : "SKU-BEER",
    "name" : "beer",
    "quantity" : "1.000",
    "taxRatePercentage" : "1.08",
    "accountingGroup" : {
      "accountingGroupId" : 123,
      "name" : "DRINKS",
      "code" : "1200"
    },
    "currency" : "CHF",
    "revenueCenter" : "Poste fixe",
    "revenueCenterId" : 123456,
    "categories" : [ {
      "category" : "default",
      "value" : "Boissons"
    } ]
  } ],
  "payments" : [ {
    "code" : "AMEX",
    "description" : "American Express",
    "netAmountWithTax" : "5.50",
    "currency" : "CHF",
    "tip" : "1.00",
    "consumer" : {
      "id" : "b3854d5a-ea22-44fd-b822-017cdfc83f07",
      "title" : "Sir",
      "firstName" : "John",
      "lastName" : "Doe",
      "phoneNumber1" : "0041 22 700 45 45",
      "phoneNumber2" : "078 123 45 67",
      "companyName" : "iKentoo",
      "addressLine1" : "Route des Jeunes 5",
      "zipCode" : "1227",
      "city" : "Les Acacias",
      "email" : "johnDoe@iKentoo.com"
    },
    "type" : "NORMAL",
    "revenueCenter" : "Poste fixe",
    "revenueCenterId" : 123456
  } ],
  "timeOfOpening" : "2020-01-14T14:30:00+02:00",
  "timeOfCloseAndPaid" : "2020-01-14T14:35:00+02:00",
  "type" : "SALE",
  "externalReferences" : [ "RESA-XX:some-external-id" ],
  "nbCovers" : 6.0,
  "dineIn" : true
}