AiFi Cloud API (2.0)

aifi: support@aifi.io URL: https://aifi.com/

AiFi API documentation

Admin API - orders

List orders

query Parameters

minCreatedAt	string <date-time> Example: minCreatedAt=2024-09-22T00:00:00.000Z
maxCreatedAt	string <date-time> Example: maxCreatedAt=2024-09-29T00:00:00.000Z
minUpdatedAt	string <date-time> Example: minUpdatedAt=2024-09-23T00:00:00.000Z
maxUpdatedAt	string <date-time> Example: maxUpdatedAt=2024-09-30T00:00:00.000Z
page	integer Default: 0
pageSize	integer <= 200 Default: 50
orderBy	string Default: "id" Enum: "id" "storeId" "totalPrice" "draftCreatedAt"
direction	string Enum: "asc" "desc" Direction of sorting
id	integer
status	Array of strings Items Enum: "draft" "paid" "unpaid" "completed_so_far" "paymentProcessing" "contested" "reviewed"
externalStatus	Array of strings Items Enum: "ok" "failedObtainingPrice" "failedSendingWebhook"
customerRole	Array of strings Items Enum: "customer" "employee" "tester" "untracked" "unknown"
sessionId	Array of strings Id of a session, which resulted in an order
externalId	Array of strings Client defined order identifiers
startTime	string <date-time>
endTime	string <date-time>
storeId	integer >= 1
customerId	integer
paymentTransactionId	string
includeContest	boolean Default: false
includeProducts	boolean Default: false
customerPaymentInstrumentBin	string [ 6 .. 8 ] characters First 6-8 digits of a card number. Exact match.
customerPaymentInstrumentLast4	string^\d{4}$ Example: customerPaymentInstrumentLast4=1111 Card last 4 digits, required when customerPaymentInstrumentExpDate is provided
customerPaymentInstrumentExpDate	string Example: customerPaymentInstrumentExpDate=03/28 Card expire date in MM/YY format
minTotalPrice	string <float> Example: minTotalPrice=2.50
maxTotalPrice	string <float> Example: maxTotalPrice=2.50
minTotalProductQuantity	integer Example: minTotalProductQuantity=1
maxTotalProductQuantity	integer Example: maxTotalProductQuantity=5
minDraftCreatedAt	string <date-time> Example: minDraftCreatedAt=2024-09-22T00:00:00.000Z
maxDraftCreatedAt	string <date-time> Example: maxDraftCreatedAt=2024-09-29T00:00:00.000Z

Responses

Response Schema: application/json

required

Array of objects (OrderListItemDto)

Array

createdAt

required

string <date-time>

ISO formatted date representing when the entity was created

updatedAt

required

string <date-time>

ISO formatted date representing when the entity was last updated

id

required

integer

version

required

integer

Default is 1, a newer version of order will be created when an order get contested

isLatest

required

integer

Whether it is the latest version

customerId

required

string <integer>

AiFi customer id, formatted as string

storeId

required

integer

The id of the store where the shopping happens

status

required

string

Enum: "draft" "paid" "unpaid" "completed_so_far" "paymentProcessing" "contested" "reviewed"

transactionId

required

number or null

Id of transaction for specified shopping session

customerShoppingSessionId

required

number or null

Id of shopping session

externalId

required

string or null

Id of this order in external system

externalStatus

required

string

Enum: "ok" "failedObtainingPrice" "failedSendingWebhook"

subtotalPrice

required

string <float>

A decimal representation of the subtotal price of this order

totalPrice

required

string <float>

A decimal representation of the total price of this order

totalTax

required

string <float>

A decimal representation of the total tax of this order

paidAt

required

string or null <date-time>

ISO formatted date of order payment

notificationSentAt

required

string or null <date-time>

ISO formatted date of order notification sent to the app

extraText

required

string

Deprecated

Default: ""

Deprecated: Use vendorMetadata with EXTRA_TEXT type instead. Extra text shows on the receipt page. This field will be removed in a future version.

completedAt

required

string or null <date-time>

ISO formatted date of order completion

draftCreatedAt

required

string or null <date-time>

ISO formatted date of draft order creation

object

Available when query param includeContest=true

id required	integer Id of contested order
orderId required	string <integer> Id of original order
orderVersion required	integer Version of original order
fromOperator required	boolean Whether created by operator
status required	string Enum: "contested" "reviewed" "original"
contestedTotalPrice required	string Total price provided by a customer, may be empty. the service will calculate it if it is missing
originalTotalPrice required	string Total price of original order
customerMessage required	string or null Message provided by a customer

Array of objects (LegacyLineItemDto)

Deprecated

Available when query param includeProducts=true.

Array

name required	string
price required	string or null <float> Unit price for single item, depending on configuration it may either contain the tax (suitable e.g. for integrations in EU) or not (suitable e.g. for integrations in the US)
barcode required	string Default barcode of default variant for this product
category required	string or null Deprecated
thumbnail required	string or null URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.
weight required	number or null Weight of a default variant
sku required	string or null Deprecated
externalId required	string or null Client defined product identifier
taxCode required	string or null Avalara tax code, available ig avalara integration is enabled
id required	integer
createdAt required	string <date-time> ISO formatted date
updatedAt required	string <date-time> ISO formatted date
productId required	string <integer> id of the product
isExternallyAdded required	boolean Informs if item was added by cart mutator
orderProductExternalId required	string or null External id of order product snapshot
orderProductSnapshotId required	integer Id of order product snapshot
quantity required	integer Quantity of the product
subtotalPrice required	string or null <float> A decimal representation of the subtotal price of this lineitem
totalPrice required	string or null <float> A decimal representation of the total price of this lineitem
totalTax required	string or null <float> A decimal representation of the total tax of this lineitem

required

object

offset based pagination

object

Query parameter to fetch previous page

offset required	integer Pagination offset
count required	integer Number of results

object

Query parameter to fetch next page

offset required	integer Pagination offset
count required	integer Number of results

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

{"data": [{"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"id": 0,
"version": 0,
"isLatest": 0,
"customerId": "11",
"storeId": 1,
"status": "draft",
"transactionId": 0,
"customerShoppingSessionId": 0,
"externalId": "string",
"externalStatus": "ok",
"subtotalPrice": "1.80",
"totalPrice": "2.15",
"totalTax": "0.35",
"paidAt": "2019-08-24T14:15:22Z",
"notificationSentAt": "2019-08-24T14:15:22Z",
"extraText": "",
"completedAt": "2019-08-24T14:15:22Z",
"draftCreatedAt": "2019-08-24T14:15:22Z",
"contest": {"id": 0,
"orderId": "string",
"orderVersion": 0,
"fromOperator": true,
"status": "contested",
"contestedTotalPrice": "120.00",
"originalTotalPrice": "123.45",
"customerMessage": "string"
},
"products": [{"name": "string",
"price": "string",
"barcode": "string",
"category": "string",
"thumbnail": "string",
"weight": 0,
"sku": "string",
"externalId": "string",
"taxCode": "string",
"id": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"productId": "string",
"isExternallyAdded": true,
"orderProductExternalId": "string",
"orderProductSnapshotId": 0,
"quantity": 0,
"subtotalPrice": "1.80",
"totalPrice": "2.15",
"totalTax": "0.35"
}
]
}
],
"pagination": {"previous": {"offset": 0,
"count": 0
},
"next": {"offset": 0,
"count": 0
}
}
}

Create an order

Request Body schema: application/json
required

customerId

required

integer

transactionId

required

integer

status

required

string

Enum: "draft" "paid" "unpaid" "completed_so_far" "paymentProcessing" "contested" "reviewed"

storeId

required

integer

required

Array of objects (OrderProductDto)

Array

id	integer Id of product
quantity	integer Quantity of the product

Responses

Response Schema: application/json

createdAt

required

string <date-time>

ISO formatted date representing when the entity was created

updatedAt

required

string <date-time>

ISO formatted date representing when the entity was last updated

id

required

integer

version

required

integer

Default is 1, a newer version of order will be created when an order get contested

isLatest

required

integer

Whether it is the latest version

customerId

required

string <integer>

AiFi customer id, formatted as string

storeId

required

integer

The id of the store where the shopping happens

status

required

string

Enum: "draft" "paid" "unpaid" "completed_so_far" "paymentProcessing" "contested" "reviewed"

transactionId

required

number or null

Id of transaction for specified shopping session

externalId

required

string or null

Id of this order in external system

externalStatus

required

string

Enum: "ok" "failedObtainingPrice" "failedSendingWebhook"

subtotalPrice

required

string <float>

A decimal representation of the subtotal price of this order

totalPrice

required

string <float>

A decimal representation of the total price of this order

totalTax

required

string <float>

A decimal representation of the total tax of this order

paidAt

required

string or null <date-time>

ISO formatted date of order payment

notificationSentAt

required

string or null <date-time>

ISO formatted date of order notification sent to the app

extraText

required

string

Deprecated

Default: ""

Deprecated: Use vendorMetadata with EXTRA_TEXT type instead. Extra text shows on the receipt page. This field will be removed in a future version.

completedAt

required

string or null <date-time>

ISO formatted date of order completion

draftCreatedAt

required

string or null <date-time>

ISO formatted date of draft order creation

sessionId

required

string or null

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.

required

object

Deprecated

Deprecated, use paymentTransaction

paymentTransactionId required	string or null The id of the transaction. Non-empty only if the order is past the "draft" stage
refunded required	boolean Whether the transaction was refunded. Only meaningful if paymentTransactionId is non-empty
tryRefundTimes required	integer The number of times a refund was attempted for this transaction
paymentFailed required	boolean Did the payment fail. Only meaningful if paymentTransactionId is non-empty

required

object (PaymentTransactionSummaryDto)

paymentTransactionId required	string or null The id of the transaction. Non-empty only if the order is past the "draft" stage
refunded required	boolean Whether the transaction was refunded. Only meaningful if paymentTransactionId is non-empty
tryRefundTimes required	integer The number of times a refund was attempted for this transaction
paymentStatus required	string or null Enum: "success" "failure" "processing"

required

Array of objects (LegacyLineItemWithTaxRatesDto)

Deprecated

Deprecated, use 'lineItems'

Array

name

required

string

price

required

string or null <float>

Unit price for single item, depending on configuration it may either contain the tax (suitable e.g. for integrations in EU) or not (suitable e.g. for integrations in the US)

barcode

required

string

Default barcode of default variant for this product

category

required

string or null

Deprecated

thumbnail

required

string or null

URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.

weight

required

number or null

Weight of a default variant

sku

required

string or null

Deprecated

externalId

required

string or null

Client defined product identifier

taxCode

required

string or null

Avalara tax code, available ig avalara integration is enabled

id

required

integer

createdAt

required

string <date-time>

ISO formatted date

updatedAt

required

string <date-time>

ISO formatted date

productId

required

string <integer>

id of the product

isExternallyAdded

required

boolean

Informs if item was added by cart mutator

orderProductExternalId

required

string or null

External id of order product snapshot

quantity

required

integer

Quantity of the product

subtotalPrice

required

string or null <float>

A decimal representation of the subtotal price of this lineitem

totalPrice

required

string or null <float>

A decimal representation of the total price of this lineitem

totalTax

required

string or null <float>

A decimal representation of the total tax of this lineitem

Array of objects (OrderDetailTaxRateDto)

Array

title required	string or null
amount required	string <float>
taxRate required	string <float>

required

Array of objects (LineItemWithTaxRatesDto)

Array

isExternallyAdded

required

boolean

Informs if item was added by cart mutator

quantity

required

integer

Quantity of the product

subtotalPrice

required

string or null <float>

A decimal representation of the subtotal price of this lineitem

totalPrice

required

string or null <float>

A decimal representation of the total price of this lineitem

totalTax

required

string or null <float>

A decimal representation of the total tax of this lineitem

Array of objects (OrderDetailTaxRateDto)

Array

title required	string or null
amount required	string <float>
taxRate required	string <float>

price

required

string or null <float>

Actual unit price of the line item. The price could be adjusted by external integration via cart-mutator webhook

externalId

required

string or null

External id of order product snapshot

status

required

string

Enum: "ORIGINAL" "ADJUSTED" "REMOVED" "ADDED"

Indicate whether the lineitem is contested

required

object (ProductSnapshotDto)

name required	string
price required	string or null <float> Unit price for single item, depending on configuration it may either contain the tax (suitable e.g. for integrations in EU) or not (suitable e.g. for integrations in the US)
barcode required	string Default barcode of default variant for this product
category required	string or null Deprecated
thumbnail required	string or null URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.
weight required	number or null Weight of a default variant
sku required	string or null Deprecated
externalId required	string or null Client defined product identifier
taxCode required	string or null Avalara tax code, available ig avalara integration is enabled
id required	integer
productId required	integer id of the product
createdAt required	string <date-time> ISO formatted date
updatedAt required	string <date-time> ISO formatted date

vendorMetadata

required

object

Vendor metadata containing arbitrary vendor data, organized by vendor name

required

object (SessionShallowDto)

createdAt required	string <date-time> ISO formatted date representing when the entity was created
updatedAt required	string <date-time> ISO formatted date representing when the entity was last updated
id required	integer
customerId required	integer AiFi customer id
code required	string An entry code that can rendered as QR and used to enter AiFi store
codeFirstSuccesfullyScannedAt required	string or null <date-time> ISO formatted date, the first time when the QR get scanned successfully
codeLastSuccesfullyScannedAt required	string or null <date-time> ISO formatted date, the last time when the QR get scanned successfully
customerFirstEnteredAt required	string or null <date-time> ISO formatted time, when the first shopper enter the store
customerLastEnteredAt required	string or null <date-time> ISO formatted time, when the last shopper enter the store
customerFirstExitedAt required	string or null <date-time> ISO formatted time, when the first shopper exit the store
customerLastExitedAt required	string or null <date-time> ISO formatted time, when the last shopper exit the store
customerPaymentInstrumentId required	integer or null Payment instrument id
customerSatisfaction required	integer or null [ 0 .. 100 ] Satisfaction from the shopping session submitted by the customer. Can be null if not submitted or when customer wished to not ask him.
customerSatisfactionSubmitted required	boolean Default: false Whether satisfaction has been submitted
groupSize required	integer Expected group size associated with the shopping session
visitors required	integer Actual group size associated with the shopping session
locationId required	string or null
priority required	integer [ -10 .. 10 ] Default: 0 Customer priority. default to 0, which means any regular customer. customers with higher priority will have their shopping sessions prioritized during processing, the lower priority is opposite.
sessionToken required	string A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.
sessionId required	string A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.
referencedSessionId required	string or null Default: null Referenced session token, that points to the source session
status required	string Enum: "active" "declined" "validated" "checkout_performed"
storeId required	integer or null AiFi store id
storeIdScannableAt required	integer or null the id of store which the QrCode of test case can be valided. It can be scanned at any store if the value is null.
suspectedFraud required	boolean Default: false Indicate whether the shopping session is suspected fraud
metadata required	object Represents an arbitrary object. Note that the `events` key is reserved by AiFi for ThirdParty and Handoff Events. The value provided in the `metadata` field will completely overwrite the existing object. If your integration depends on the `events` key in the metadata, ensure it is preserved to avoid accidental deletion. To add new keys to the existing metadata object: Retrieve the current metadata using the Get Session List endpoint. Merge the retrieved metadata with the new keys you wish to add. Submit the updated object in the `metadata` field. Be cautious, as replacing the `metadata` value without preserving necessary keys may lead to unintended data loss.
expiresAt required	string <date-time> ISO formatted date at which this entry code will expire

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"customerId": 0,
"transactionId": 0,
"status": "draft",
"storeId": 0,
"products": [{"id": 0,
"quantity": 0
}
]
}

Response samples

201
422

Content type

application/json

{"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"id": 0,
"version": 0,
"isLatest": 0,
"customerId": "11",
"storeId": 1,
"status": "draft",
"transactionId": 0,
"externalId": "string",
"externalStatus": "ok",
"subtotalPrice": "1.80",
"totalPrice": "2.15",
"totalTax": "0.35",
"paidAt": "2019-08-24T14:15:22Z",
"notificationSentAt": "2019-08-24T14:15:22Z",
"extraText": "",
"completedAt": "2019-08-24T14:15:22Z",
"draftCreatedAt": "2019-08-24T14:15:22Z",
"sessionId": "string",
"transaction": {"paymentTransactionId": "string",
"refunded": true,
"tryRefundTimes": 0,
"paymentFailed": true
},
"paymentTransaction": {"paymentTransactionId": "string",
"refunded": true,
"tryRefundTimes": 0,
"paymentStatus": "success"
},
"products": [{"name": "string",
"price": "string",
"barcode": "string",
"category": "string",
"thumbnail": "string",
"weight": 0,
"sku": "string",
"externalId": "string",
"taxCode": "string",
"id": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"productId": "string",
"isExternallyAdded": true,
"orderProductExternalId": "string",
"quantity": 0,
"subtotalPrice": "1.80",
"totalPrice": "2.15",
"totalTax": "0.35",
"taxRates": "Tax breakdown for this lineitem"
}
],
"lineItems": [{"isExternallyAdded": true,
"quantity": 0,
"subtotalPrice": "1.80",
"totalPrice": "2.15",
"totalTax": "0.35",
"taxRates": "Tax breakdown for this lineitem",
"price": "10.00",
"externalId": "string",
"status": "ORIGINAL",
"productSnapshot": {"name": "string",
"price": "string",
"barcode": "string",
"category": "string",
"thumbnail": "string",
"weight": 0,
"sku": "string",
"externalId": "string",
"taxCode": "string",
"id": 0,
"productId": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
}
],
"vendorMetadata": {"PaymentProvider": [{"type": "DISCOUNT",
"value": "Applied discount 5%"
}
]
},
"session": {"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"id": 0,
"customerId": 0,
"code": "c69bb289-1190-4156-b9f6-bfb7f61e85db",
"codeFirstSuccesfullyScannedAt": "2019-08-24T14:15:22Z",
"codeLastSuccesfullyScannedAt": "2019-08-24T14:15:22Z",
"customerFirstEnteredAt": "2019-08-24T14:15:22Z",
"customerLastEnteredAt": "2019-08-24T14:15:22Z",
"customerFirstExitedAt": "2019-08-24T14:15:22Z",
"customerLastExitedAt": "2019-08-24T14:15:22Z",
"customerPaymentInstrumentId": 0,
"customerSatisfaction": 95,
"customerSatisfactionSubmitted": false,
"groupSize": 0,
"visitors": 0,
"locationId": "string",
"priority": 0,
"sessionToken": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"sessionId": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"referencedSessionId": null,
"status": "active",
"storeId": 0,
"storeIdScannableAt": 0,
"suspectedFraud": false,
"metadata": {"events": [{"eventId": "6bdbfb2d-65b2-491c-bc97-c0ac73338476",
"metadata": {"key": "value"
}
}
],
"exampleKey": "exampleValue"
},
"expiresAt": "2019-08-24T14:15:22Z"
}
}

Get order by id

path Parameters

orderId

required

integer

query Parameters

version

integer

Responses

Response Schema: application/json

createdAt

required

string <date-time>

ISO formatted date representing when the entity was created

updatedAt

required

string <date-time>

ISO formatted date representing when the entity was last updated

id

required

integer

version

required

integer

Default is 1, a newer version of order will be created when an order get contested

isLatest

required

integer

Whether it is the latest version

customerId

required

string <integer>

AiFi customer id, formatted as string

storeId

required

integer

The id of the store where the shopping happens

status

required

string

Enum: "draft" "paid" "unpaid" "completed_so_far" "paymentProcessing" "contested" "reviewed"

transactionId

required

number or null

Id of transaction for specified shopping session

externalId

required

string or null

Id of this order in external system

externalStatus

required

string

Enum: "ok" "failedObtainingPrice" "failedSendingWebhook"

subtotalPrice

required

string <float>

A decimal representation of the subtotal price of this order

totalPrice

required

string <float>

A decimal representation of the total price of this order

totalTax

required

string <float>

A decimal representation of the total tax of this order

paidAt

required

string or null <date-time>

ISO formatted date of order payment

notificationSentAt

required

string or null <date-time>

ISO formatted date of order notification sent to the app

extraText

required

string

Deprecated

Default: ""

Deprecated: Use vendorMetadata with EXTRA_TEXT type instead. Extra text shows on the receipt page. This field will be removed in a future version.

completedAt

required

string or null <date-time>

ISO formatted date of order completion

draftCreatedAt

required

string or null <date-time>

ISO formatted date of draft order creation

sessionId

required

string or null

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.

required

object

Deprecated

Deprecated, use paymentTransaction

paymentTransactionId required	string or null The id of the transaction. Non-empty only if the order is past the "draft" stage
refunded required	boolean Whether the transaction was refunded. Only meaningful if paymentTransactionId is non-empty
tryRefundTimes required	integer The number of times a refund was attempted for this transaction
paymentFailed required	boolean Did the payment fail. Only meaningful if paymentTransactionId is non-empty

required

object (PaymentTransactionSummaryDto)

paymentTransactionId required	string or null The id of the transaction. Non-empty only if the order is past the "draft" stage
refunded required	boolean Whether the transaction was refunded. Only meaningful if paymentTransactionId is non-empty
tryRefundTimes required	integer The number of times a refund was attempted for this transaction
paymentStatus required	string or null Enum: "success" "failure" "processing"

required

Array of objects (LegacyLineItemWithTaxRatesDto)

Deprecated

Deprecated, use 'lineItems'

Array

name

required

string

price

required

string or null <float>

Unit price for single item, depending on configuration it may either contain the tax (suitable e.g. for integrations in EU) or not (suitable e.g. for integrations in the US)

barcode

required

string

Default barcode of default variant for this product

category

required

string or null

Deprecated

thumbnail

required

string or null

URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.

weight

required

number or null

Weight of a default variant

sku

required

string or null

Deprecated

externalId

required

string or null

Client defined product identifier

taxCode

required

string or null

Avalara tax code, available ig avalara integration is enabled

id

required

integer

createdAt

required

string <date-time>

ISO formatted date

updatedAt

required

string <date-time>

ISO formatted date

productId

required

string <integer>

id of the product

isExternallyAdded

required

boolean

Informs if item was added by cart mutator

orderProductExternalId

required

string or null

External id of order product snapshot

quantity

required

integer

Quantity of the product

subtotalPrice

required

string or null <float>

A decimal representation of the subtotal price of this lineitem

totalPrice

required

string or null <float>

A decimal representation of the total price of this lineitem

totalTax

required

string or null <float>

A decimal representation of the total tax of this lineitem

Array of objects (OrderDetailTaxRateDto)

Array

title required	string or null
amount required	string <float>
taxRate required	string <float>

required

Array of objects (LineItemWithTaxRatesDto)

Array

isExternallyAdded

required

boolean

Informs if item was added by cart mutator

quantity

required

integer

Quantity of the product

subtotalPrice

required

string or null <float>

A decimal representation of the subtotal price of this lineitem

totalPrice

required

string or null <float>

A decimal representation of the total price of this lineitem

totalTax

required

string or null <float>

A decimal representation of the total tax of this lineitem

Array of objects (OrderDetailTaxRateDto)

Array

title required	string or null
amount required	string <float>
taxRate required	string <float>

price

required

string or null <float>

Actual unit price of the line item. The price could be adjusted by external integration via cart-mutator webhook

externalId

required

string or null

External id of order product snapshot

status

required

string

Enum: "ORIGINAL" "ADJUSTED" "REMOVED" "ADDED"

Indicate whether the lineitem is contested

required

object (ProductSnapshotDto)

name required	string
price required	string or null <float> Unit price for single item, depending on configuration it may either contain the tax (suitable e.g. for integrations in EU) or not (suitable e.g. for integrations in the US)
barcode required	string Default barcode of default variant for this product
category required	string or null Deprecated
thumbnail required	string or null URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.
weight required	number or null Weight of a default variant
sku required	string or null Deprecated
externalId required	string or null Client defined product identifier
taxCode required	string or null Avalara tax code, available ig avalara integration is enabled
id required	integer
productId required	integer id of the product
createdAt required	string <date-time> ISO formatted date
updatedAt required	string <date-time> ISO formatted date

vendorMetadata

required

object

Vendor metadata containing arbitrary vendor data, organized by vendor name

required

object (SessionShallowDto)

createdAt required	string <date-time> ISO formatted date representing when the entity was created
updatedAt required	string <date-time> ISO formatted date representing when the entity was last updated
id required	integer
customerId required	integer AiFi customer id
code required	string An entry code that can rendered as QR and used to enter AiFi store
codeFirstSuccesfullyScannedAt required	string or null <date-time> ISO formatted date, the first time when the QR get scanned successfully
codeLastSuccesfullyScannedAt required	string or null <date-time> ISO formatted date, the last time when the QR get scanned successfully
customerFirstEnteredAt required	string or null <date-time> ISO formatted time, when the first shopper enter the store
customerLastEnteredAt required	string or null <date-time> ISO formatted time, when the last shopper enter the store
customerFirstExitedAt required	string or null <date-time> ISO formatted time, when the first shopper exit the store
customerLastExitedAt required	string or null <date-time> ISO formatted time, when the last shopper exit the store
customerPaymentInstrumentId required	integer or null Payment instrument id
customerSatisfaction required	integer or null [ 0 .. 100 ] Satisfaction from the shopping session submitted by the customer. Can be null if not submitted or when customer wished to not ask him.
customerSatisfactionSubmitted required	boolean Default: false Whether satisfaction has been submitted
groupSize required	integer Expected group size associated with the shopping session
visitors required	integer Actual group size associated with the shopping session
locationId required	string or null
priority required	integer [ -10 .. 10 ] Default: 0 Customer priority. default to 0, which means any regular customer. customers with higher priority will have their shopping sessions prioritized during processing, the lower priority is opposite.
sessionToken required	string A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.
sessionId required	string A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.
referencedSessionId required	string or null Default: null Referenced session token, that points to the source session
status required	string Enum: "active" "declined" "validated" "checkout_performed"
storeId required	integer or null AiFi store id
storeIdScannableAt required	integer or null the id of store which the QrCode of test case can be valided. It can be scanned at any store if the value is null.
suspectedFraud required	boolean Default: false Indicate whether the shopping session is suspected fraud
metadata required	object Represents an arbitrary object. Note that the `events` key is reserved by AiFi for ThirdParty and Handoff Events. The value provided in the `metadata` field will completely overwrite the existing object. If your integration depends on the `events` key in the metadata, ensure it is preserved to avoid accidental deletion. To add new keys to the existing metadata object: Retrieve the current metadata using the Get Session List endpoint. Merge the retrieved metadata with the new keys you wish to add. Submit the updated object in the `metadata` field. Be cautious, as replacing the `metadata` value without preserving necessary keys may lead to unintended data loss.
expiresAt required	string <date-time> ISO formatted date at which this entry code will expire

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

{"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"id": 0,
"version": 0,
"isLatest": 0,
"customerId": "11",
"storeId": 1,
"status": "draft",
"transactionId": 0,
"externalId": "string",
"externalStatus": "ok",
"subtotalPrice": "1.80",
"totalPrice": "2.15",
"totalTax": "0.35",
"paidAt": "2019-08-24T14:15:22Z",
"notificationSentAt": "2019-08-24T14:15:22Z",
"extraText": "",
"completedAt": "2019-08-24T14:15:22Z",
"draftCreatedAt": "2019-08-24T14:15:22Z",
"sessionId": "string",
"transaction": {"paymentTransactionId": "string",
"refunded": true,
"tryRefundTimes": 0,
"paymentFailed": true
},
"paymentTransaction": {"paymentTransactionId": "string",
"refunded": true,
"tryRefundTimes": 0,
"paymentStatus": "success"
},
"products": [{"name": "string",
"price": "string",
"barcode": "string",
"category": "string",
"thumbnail": "string",
"weight": 0,
"sku": "string",
"externalId": "string",
"taxCode": "string",
"id": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"productId": "string",
"isExternallyAdded": true,
"orderProductExternalId": "string",
"quantity": 0,
"subtotalPrice": "1.80",
"totalPrice": "2.15",
"totalTax": "0.35",
"taxRates": "Tax breakdown for this lineitem"
}
],
"lineItems": [{"isExternallyAdded": true,
"quantity": 0,
"subtotalPrice": "1.80",
"totalPrice": "2.15",
"totalTax": "0.35",
"taxRates": "Tax breakdown for this lineitem",
"price": "10.00",
"externalId": "string",
"status": "ORIGINAL",
"productSnapshot": {"name": "string",
"price": "string",
"barcode": "string",
"category": "string",
"thumbnail": "string",
"weight": 0,
"sku": "string",
"externalId": "string",
"taxCode": "string",
"id": 0,
"productId": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
}
],
"vendorMetadata": {"PaymentProvider": [{"type": "DISCOUNT",
"value": "Applied discount 5%"
}
]
},
"session": {"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"id": 0,
"customerId": 0,
"code": "c69bb289-1190-4156-b9f6-bfb7f61e85db",
"codeFirstSuccesfullyScannedAt": "2019-08-24T14:15:22Z",
"codeLastSuccesfullyScannedAt": "2019-08-24T14:15:22Z",
"customerFirstEnteredAt": "2019-08-24T14:15:22Z",
"customerLastEnteredAt": "2019-08-24T14:15:22Z",
"customerFirstExitedAt": "2019-08-24T14:15:22Z",
"customerLastExitedAt": "2019-08-24T14:15:22Z",
"customerPaymentInstrumentId": 0,
"customerSatisfaction": 95,
"customerSatisfactionSubmitted": false,
"groupSize": 0,
"visitors": 0,
"locationId": "string",
"priority": 0,
"sessionToken": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"sessionId": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"referencedSessionId": null,
"status": "active",
"storeId": 0,
"storeIdScannableAt": 0,
"suspectedFraud": false,
"metadata": {"events": [{"eventId": "6bdbfb2d-65b2-491c-bc97-c0ac73338476",
"metadata": {"key": "value"
}
}
],
"exampleKey": "exampleValue"
},
"expiresAt": "2019-08-24T14:15:22Z"
}
}

Update order by id

Note: The extraText field (if used) is deprecated. Use the vendorMetadata API endpoint instead.

path Parameters

orderId

required

integer

Request Body schema: application/json
required

transactionId

integer

Id of shopping transaction

object (UpdateOrderPaymentTransactionDto)

paymentTransactionId	string The payment id to identify the payment transaction in payment provider
paymentStatus	string Enum: "success" "failure"

status

string

Enum: "draft" "paid" "unpaid" "completed_so_far" "paymentProcessing" "contested" "reviewed"

The order status should be derived from payment status when paymentTransaction.paymentStatus is provided

Array of objects (OrderProductDto)

Array

id	integer Id of product
quantity	integer Quantity of the product

externalStatus

string

Enum: "ok" "failedObtainingPrice" "failedSendingWebhook"

externalId

string

Client defined order identifiers

Responses

Response Schema: application/json

createdAt

required

string <date-time>

ISO formatted date representing when the entity was created

updatedAt

required

string <date-time>

ISO formatted date representing when the entity was last updated

id

required

integer

version

required

integer

Default is 1, a newer version of order will be created when an order get contested

isLatest

required

integer

Whether it is the latest version

customerId

required

string <integer>

AiFi customer id, formatted as string

storeId

required

integer

The id of the store where the shopping happens

status

required

string

Enum: "draft" "paid" "unpaid" "completed_so_far" "paymentProcessing" "contested" "reviewed"

transactionId

required

number or null

Id of transaction for specified shopping session

externalId

required

string or null

Id of this order in external system

externalStatus

required

string

Enum: "ok" "failedObtainingPrice" "failedSendingWebhook"

subtotalPrice

required

string <float>

A decimal representation of the subtotal price of this order

totalPrice

required

string <float>

A decimal representation of the total price of this order

totalTax

required

string <float>

A decimal representation of the total tax of this order

paidAt

required

string or null <date-time>

ISO formatted date of order payment

notificationSentAt

required

string or null <date-time>

ISO formatted date of order notification sent to the app

extraText

required

string

Deprecated

Default: ""

Deprecated: Use vendorMetadata with EXTRA_TEXT type instead. Extra text shows on the receipt page. This field will be removed in a future version.

completedAt

required

string or null <date-time>

ISO formatted date of order completion

draftCreatedAt

required

string or null <date-time>

ISO formatted date of draft order creation

sessionId

required

string or null

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.

required

object

Deprecated

Deprecated, use paymentTransaction

paymentTransactionId required	string or null The id of the transaction. Non-empty only if the order is past the "draft" stage
refunded required	boolean Whether the transaction was refunded. Only meaningful if paymentTransactionId is non-empty
tryRefundTimes required	integer The number of times a refund was attempted for this transaction
paymentFailed required	boolean Did the payment fail. Only meaningful if paymentTransactionId is non-empty

required

object (PaymentTransactionSummaryDto)

paymentTransactionId required	string or null The id of the transaction. Non-empty only if the order is past the "draft" stage
refunded required	boolean Whether the transaction was refunded. Only meaningful if paymentTransactionId is non-empty
tryRefundTimes required	integer The number of times a refund was attempted for this transaction
paymentStatus required	string or null Enum: "success" "failure" "processing"

required

Array of objects (LegacyLineItemWithTaxRatesDto)

Deprecated

Deprecated, use 'lineItems'

Array

name

required

string

price

required

string or null <float>

Unit price for single item, depending on configuration it may either contain the tax (suitable e.g. for integrations in EU) or not (suitable e.g. for integrations in the US)

barcode

required

string

Default barcode of default variant for this product

category

required

string or null

Deprecated

thumbnail

required

string or null

URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.

weight

required

number or null

Weight of a default variant

sku

required

string or null

Deprecated

externalId

required

string or null

Client defined product identifier

taxCode

required

string or null

Avalara tax code, available ig avalara integration is enabled

id

required

integer

createdAt

required

string <date-time>

ISO formatted date

updatedAt

required

string <date-time>

ISO formatted date

productId

required

string <integer>

id of the product

isExternallyAdded

required

boolean

Informs if item was added by cart mutator

orderProductExternalId

required

string or null

External id of order product snapshot

quantity

required

integer

Quantity of the product

subtotalPrice

required

string or null <float>

A decimal representation of the subtotal price of this lineitem

totalPrice

required

string or null <float>

A decimal representation of the total price of this lineitem

totalTax

required

string or null <float>

A decimal representation of the total tax of this lineitem

Array of objects (OrderDetailTaxRateDto)

Array

title required	string or null
amount required	string <float>
taxRate required	string <float>

required

Array of objects (LineItemWithTaxRatesDto)

Array

isExternallyAdded

required

boolean

Informs if item was added by cart mutator

quantity

required

integer

Quantity of the product

subtotalPrice

required

string or null <float>

A decimal representation of the subtotal price of this lineitem

totalPrice

required

string or null <float>

A decimal representation of the total price of this lineitem

totalTax

required

string or null <float>

A decimal representation of the total tax of this lineitem

Array of objects (OrderDetailTaxRateDto)

Array

title required	string or null
amount required	string <float>
taxRate required	string <float>

price

required

string or null <float>

Actual unit price of the line item. The price could be adjusted by external integration via cart-mutator webhook

externalId

required

string or null

External id of order product snapshot

status

required

string

Enum: "ORIGINAL" "ADJUSTED" "REMOVED" "ADDED"

Indicate whether the lineitem is contested

required

object (ProductSnapshotDto)

name required	string
price required	string or null <float> Unit price for single item, depending on configuration it may either contain the tax (suitable e.g. for integrations in EU) or not (suitable e.g. for integrations in the US)
barcode required	string Default barcode of default variant for this product
category required	string or null Deprecated
thumbnail required	string or null URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.
weight required	number or null Weight of a default variant
sku required	string or null Deprecated
externalId required	string or null Client defined product identifier
taxCode required	string or null Avalara tax code, available ig avalara integration is enabled
id required	integer
productId required	integer id of the product
createdAt required	string <date-time> ISO formatted date
updatedAt required	string <date-time> ISO formatted date

vendorMetadata

required

object

Vendor metadata containing arbitrary vendor data, organized by vendor name

required

object (SessionShallowDto)

createdAt required	string <date-time> ISO formatted date representing when the entity was created
updatedAt required	string <date-time> ISO formatted date representing when the entity was last updated
id required	integer
customerId required	integer AiFi customer id
code required	string An entry code that can rendered as QR and used to enter AiFi store
codeFirstSuccesfullyScannedAt required	string or null <date-time> ISO formatted date, the first time when the QR get scanned successfully
codeLastSuccesfullyScannedAt required	string or null <date-time> ISO formatted date, the last time when the QR get scanned successfully
customerFirstEnteredAt required	string or null <date-time> ISO formatted time, when the first shopper enter the store
customerLastEnteredAt required	string or null <date-time> ISO formatted time, when the last shopper enter the store
customerFirstExitedAt required	string or null <date-time> ISO formatted time, when the first shopper exit the store
customerLastExitedAt required	string or null <date-time> ISO formatted time, when the last shopper exit the store
customerPaymentInstrumentId required	integer or null Payment instrument id
customerSatisfaction required	integer or null [ 0 .. 100 ] Satisfaction from the shopping session submitted by the customer. Can be null if not submitted or when customer wished to not ask him.
customerSatisfactionSubmitted required	boolean Default: false Whether satisfaction has been submitted
groupSize required	integer Expected group size associated with the shopping session
visitors required	integer Actual group size associated with the shopping session
locationId required	string or null
priority required	integer [ -10 .. 10 ] Default: 0 Customer priority. default to 0, which means any regular customer. customers with higher priority will have their shopping sessions prioritized during processing, the lower priority is opposite.
sessionToken required	string A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.
sessionId required	string A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.
referencedSessionId required	string or null Default: null Referenced session token, that points to the source session
status required	string Enum: "active" "declined" "validated" "checkout_performed"
storeId required	integer or null AiFi store id
storeIdScannableAt required	integer or null the id of store which the QrCode of test case can be valided. It can be scanned at any store if the value is null.
suspectedFraud required	boolean Default: false Indicate whether the shopping session is suspected fraud
metadata required	object Represents an arbitrary object. Note that the `events` key is reserved by AiFi for ThirdParty and Handoff Events. The value provided in the `metadata` field will completely overwrite the existing object. If your integration depends on the `events` key in the metadata, ensure it is preserved to avoid accidental deletion. To add new keys to the existing metadata object: Retrieve the current metadata using the Get Session List endpoint. Merge the retrieved metadata with the new keys you wish to add. Submit the updated object in the `metadata` field. Be cautious, as replacing the `metadata` value without preserving necessary keys may lead to unintended data loss.
expiresAt required	string <date-time> ISO formatted date at which this entry code will expire

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"transactionId": 0,
"paymentTransaction": {"paymentTransactionId": "string",
"paymentStatus": "success"
},
"status": "draft",
"products": [{"id": 0,
"quantity": 0
}
],
"externalStatus": "ok",
"externalId": "string"
}

Response samples

200
422

Content type

application/json

{"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"id": 0,
"version": 0,
"isLatest": 0,
"customerId": "11",
"storeId": 1,
"status": "draft",
"transactionId": 0,
"externalId": "string",
"externalStatus": "ok",
"subtotalPrice": "1.80",
"totalPrice": "2.15",
"totalTax": "0.35",
"paidAt": "2019-08-24T14:15:22Z",
"notificationSentAt": "2019-08-24T14:15:22Z",
"extraText": "",
"completedAt": "2019-08-24T14:15:22Z",
"draftCreatedAt": "2019-08-24T14:15:22Z",
"sessionId": "string",
"transaction": {"paymentTransactionId": "string",
"refunded": true,
"tryRefundTimes": 0,
"paymentFailed": true
},
"paymentTransaction": {"paymentTransactionId": "string",
"refunded": true,
"tryRefundTimes": 0,
"paymentStatus": "success"
},
"products": [{"name": "string",
"price": "string",
"barcode": "string",
"category": "string",
"thumbnail": "string",
"weight": 0,
"sku": "string",
"externalId": "string",
"taxCode": "string",
"id": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"productId": "string",
"isExternallyAdded": true,
"orderProductExternalId": "string",
"quantity": 0,
"subtotalPrice": "1.80",
"totalPrice": "2.15",
"totalTax": "0.35",
"taxRates": "Tax breakdown for this lineitem"
}
],
"lineItems": [{"isExternallyAdded": true,
"quantity": 0,
"subtotalPrice": "1.80",
"totalPrice": "2.15",
"totalTax": "0.35",
"taxRates": "Tax breakdown for this lineitem",
"price": "10.00",
"externalId": "string",
"status": "ORIGINAL",
"productSnapshot": {"name": "string",
"price": "string",
"barcode": "string",
"category": "string",
"thumbnail": "string",
"weight": 0,
"sku": "string",
"externalId": "string",
"taxCode": "string",
"id": 0,
"productId": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
}
],
"vendorMetadata": {"PaymentProvider": [{"type": "DISCOUNT",
"value": "Applied discount 5%"
}
]
},
"session": {"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"id": 0,
"customerId": 0,
"code": "c69bb289-1190-4156-b9f6-bfb7f61e85db",
"codeFirstSuccesfullyScannedAt": "2019-08-24T14:15:22Z",
"codeLastSuccesfullyScannedAt": "2019-08-24T14:15:22Z",
"customerFirstEnteredAt": "2019-08-24T14:15:22Z",
"customerLastEnteredAt": "2019-08-24T14:15:22Z",
"customerFirstExitedAt": "2019-08-24T14:15:22Z",
"customerLastExitedAt": "2019-08-24T14:15:22Z",
"customerPaymentInstrumentId": 0,
"customerSatisfaction": 95,
"customerSatisfactionSubmitted": false,
"groupSize": 0,
"visitors": 0,
"locationId": "string",
"priority": 0,
"sessionToken": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"sessionId": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"referencedSessionId": null,
"status": "active",
"storeId": 0,
"storeIdScannableAt": 0,
"suspectedFraud": false,
"metadata": {"events": [{"eventId": "6bdbfb2d-65b2-491c-bc97-c0ac73338476",
"metadata": {"key": "value"
}
}
],
"exampleKey": "exampleValue"
},
"expiresAt": "2019-08-24T14:15:22Z"
}
}

Retry order checkout

path Parameters

orderId

required

integer

Responses

Response Schema: application/json

storeId

required

integer

The id of the store where the shopping happens

totalPrice

required

string <float>

A decimal representation of the total price of this order

orderId

required

integer

orderVersion

required

integer

Default is 1, a newer version of order will be created when an order get contested

externalOrderId

required

string or null

Id of this order in external system

required

object

Store identifiers

oasisApiStoreId required	integer Store identifier that is only internal to cloud-api
aifiUniqueStoreId required	string or null Unique identifier across all AiFi stores. it will only be filled in by TechOPS/deployment engineers

paymentFailed

required

boolean

Informs whether payment failed, or was successfully collected

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

{"storeId": 1,
"totalPrice": "2.15",
"orderId": 0,
"orderVersion": 0,
"externalOrderId": "string",
"store": {"oasisApiStoreId": 0,
"aifiUniqueStoreId": "string"
},
"paymentFailed": true
}

Add vendor metadata to order

Adds a metadata entry to the specified vendor for the latest order version. This is an append-only operation.

path Parameters

orderId required	integer Order ID
vendorName required	string Vendor name to associate the metadata with

Request Body schema: application/json
required

type required	string Type of metadata entry (e.g., DISCOUNT, SURCHARGE, EMV, EXTRA_TEXT, or custom type)
value required	string Value of the metadata entry

Responses

Response Schema: application/json

orderId required	integer
orderVersion required	integer
vendorName required	string
metadata required	object

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"type": "DISCOUNT",
"value": "Applied discount 5% total due to using Platinum Credit Card."
}

Response samples

201
422

Content type

application/json

{"orderId": 0,
"orderVersion": 0,
"vendorName": "string",
"metadata": { }
}

Admin API - products

List products snapshots

query Parameters

pageSize	integer Example: pageSize=10 Page size
page	integer Page number
time	string <date-time> timestamp
	string or Array of strings Product ID or array of Product IDs
name	string Case insensitive

Responses

Response Schema: application/json

required

Array of objects (ProductSnapshotListItemDto)

Array

name required	string
price required	string or null <float> Unit price for single item, depending on configuration it may either contain the tax (suitable e.g. for integrations in EU) or not (suitable e.g. for integrations in the US)
barcode required	string Default barcode of default variant for this product
category required	string or null Deprecated
thumbnail required	string or null URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.
weight required	number or null Weight of a default variant
sku required	string or null Deprecated
externalId required	string or null Client defined product identifier
taxCode required	string or null Avalara tax code, available ig avalara integration is enabled
id required	integer
createdAt required	string <date-time> ISO formatted date
updatedAt required	string <date-time> ISO formatted date
productId required	string <integer> id of the product

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

{"data": [{"name": "string",
"price": "string",
"barcode": "string",
"category": "string",
"thumbnail": "string",
"weight": 0,
"sku": "string",
"externalId": "string",
"taxCode": "string",
"id": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"productId": "string"
}
]
}

List product variants

query Parameters

minCreatedAt	string <date-time> Example: minCreatedAt=2024-09-22T00:00:00.000Z
maxCreatedAt	string <date-time> Example: maxCreatedAt=2024-09-29T00:00:00.000Z
minUpdatedAt	string <date-time> Example: minUpdatedAt=2024-09-23T00:00:00.000Z
maxUpdatedAt	string <date-time> Example: maxUpdatedAt=2024-09-30T00:00:00.000Z
offset	integer >= 0 Pagination offset
count	integer [ 1 .. 200 ] Default: 50 Number of results
productId	Array of integers Filter by productId(s)
name	Array of strings Filter by name(s)
barcode	Array of strings Filter by barcode(s)
externalId	Array of strings Filter by externalId(s)
invalidThumbnail	boolean Filter by invalidThumbnail
isDefault	boolean Filter by isDefault flag

Responses

Response Schema: application/json

required

Array of objects (ProductVariantResponseDto)

Array

id

required

integer

name

required

string

thumbnail

required

string or null

URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.

invalidThumbnail

required

boolean

Marks whether thumbnail is a valid image

externalId

required

string or null <= 255 characters

Client defined product variant identifier

weight

required

string or null <float>

A decimal representation of the product's weight

required

Array of objects (ProductVariantBarcodeDto)

List of barcodes, associated with a variant

Array

isDefault required	boolean Informs whether this is a default barcode, for a variant. Every variant must have exactly one default barcode at all times.
barcode required	string Barcode value

isDefault

required

boolean

Informs whether this is a default variant, for a product. Every product must have exactly one default variant at all times.

productId

required

integer

id of a product in AiFi system

required

object (CursorBasedPaginationDto)

object

Query parameter to fetch previous page

count required	integer Number of results
before required	string Id or base64 encoded cursor(id + sortKey)
direction required	string Enum: "asc" "desc" Direction of sorting

object

Query parameter to fetch next page

count required	integer Number of results
after required	string Id or base64 encoded cursor(id + sortKey)
direction required	string Enum: "asc" "desc" Direction of sorting

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

{"variants": [{"id": 0,
"name": "string",
"thumbnail": "string",
"invalidThumbnail": true,
"externalId": "string",
"weight": "string",
"barcodes": [{"isDefault": true,
"barcode": "string"
}
],
"isDefault": true,
"productId": 0
}
],
"pagination": {"previous": {"count": 0,
"before": "string",
"direction": "asc"
},
"next": {"count": 0,
"after": "string",
"direction": "asc"
}
}
}

Get product variant by id

path Parameters

id

required

integer

Id of the product variant

Responses

Response Schema: application/json

id

required

integer

name

required

string

thumbnail

required

string or null

URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.

invalidThumbnail

required

boolean

Marks whether thumbnail is a valid image

externalId

required

string or null <= 255 characters

Client defined product variant identifier

weight

required

string or null <float>

A decimal representation of the product's weight

required

Array of objects (ProductVariantBarcodeDto)

List of barcodes, associated with a variant

Array

isDefault required	boolean Informs whether this is a default barcode, for a variant. Every variant must have exactly one default barcode at all times.
barcode required	string Barcode value

isDefault

required

boolean

Informs whether this is a default variant, for a product. Every product must have exactly one default variant at all times.

productId

required

integer

id of a product in AiFi system

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

{"id": 0,
"name": "string",
"thumbnail": "string",
"invalidThumbnail": true,
"externalId": "string",
"weight": "string",
"barcodes": [{"isDefault": true,
"barcode": "string"
}
],
"isDefault": true,
"productId": 0
}

Delete product variant

path Parameters

id

required

integer

Id of the product variant

Responses

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

422

Content type

application/json

{"message": "Invalid request body",
"type": "E_INVALID_BODY",
"errors": [{"error": "\"email\" is required",
"rule": "any.required",
"field": "\"email\""
}
]
}

Update product variant

path Parameters

id

required

integer

Id of the product variant

Request Body schema: application/json
required

name

string

weight

number >= 0

Array of objects (ProductVariantBarcodeDto)

List of barcodes, associated with a variant

Array

isDefault required	boolean Informs whether this is a default barcode, for a variant. Every variant must have exactly one default barcode at all times.
barcode required	string Barcode value

isDefault

boolean

Informs whether this is a default variant, for a product. Every product must have exactly one default variant at all times.

thumbnail

string

invalidThumbnail

boolean

Marks whether thumbnail is a valid image. Can only be specified if 'thumbnail' was also specified and it's value is not empty. If 'thumbnail' was specified then default value for this field is 'false'. Otherwise there is no default value and this field's value depends on whether thumbnail's url was automatically resolved

externalId

string <= 255 characters

Client defined product variant identifier

Responses

Response Schema: application/json

id

required

integer

name

required

string

thumbnail

required

string or null

URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.

invalidThumbnail

required

boolean

Marks whether thumbnail is a valid image

externalId

required

string or null <= 255 characters

Client defined product variant identifier

weight

required

string or null <float>

A decimal representation of the product's weight

required

Array of objects (ProductVariantBarcodeDto)

List of barcodes, associated with a variant

Array

isDefault required	boolean Informs whether this is a default barcode, for a variant. Every variant must have exactly one default barcode at all times.
barcode required	string Barcode value

isDefault

required

boolean

Informs whether this is a default variant, for a product. Every product must have exactly one default variant at all times.

productId

required

integer

id of a product in AiFi system

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"name": "string",
"weight": 0,
"barcodes": [{"isDefault": true,
"barcode": "string"
}
],
"isDefault": true,
"thumbnail": "string",
"invalidThumbnail": true,
"externalId": "string"
}

Response samples

200
422

Content type

application/json

{"id": 0,
"name": "string",
"thumbnail": "string",
"invalidThumbnail": true,
"externalId": "string",
"weight": "string",
"barcodes": [{"isDefault": true,
"barcode": "string"
}
],
"isDefault": true,
"productId": 0
}

Get a default variant for product

path Parameters

productId

required

integer

Id of the product

Responses

Response Schema: application/json

id

required

integer

name

required

string

thumbnail

required

string or null

URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.

invalidThumbnail

required

boolean

Marks whether thumbnail is a valid image

externalId

required

string or null <= 255 characters

Client defined product variant identifier

weight

required

string or null <float>

A decimal representation of the product's weight

required

Array of objects (ProductVariantBarcodeDto)

List of barcodes, associated with a variant

Array

isDefault required	boolean Informs whether this is a default barcode, for a variant. Every variant must have exactly one default barcode at all times.
barcode required	string Barcode value

isDefault

required

boolean

Informs whether this is a default variant, for a product. Every product must have exactly one default variant at all times.

productId

required

integer

id of a product in AiFi system

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

{"id": 0,
"name": "string",
"thumbnail": "string",
"invalidThumbnail": true,
"externalId": "string",
"weight": "string",
"barcodes": [{"isDefault": true,
"barcode": "string"
}
],
"isDefault": true,
"productId": 0
}

Create product variant

path Parameters

productId

required

integer

Id of the product

Request Body schema: application/json
required

name

required

string

weight

required

number >= 0

required

Array of objects (ProductVariantBarcodeDto)

List of barcodes, associated with a variant

Array

isDefault required	boolean Informs whether this is a default barcode, for a variant. Every variant must have exactly one default barcode at all times.
barcode required	string Barcode value

isDefault

boolean

Default: false

Informs whether this is a default variant, for a product. Every product must have exactly one default variant at all times.

thumbnail

required

string

URL to thumbnail. If not provided best-effort will be taken to resolve thumbnail url automatically

invalidThumbnail

boolean

Marks whether thumbnail is a valid image. Can only be specified if 'thumbnail' was also specified and it's value is not empty. If 'thumbnail' was specified then default value for this field is 'false'. Otherwise there is no default value and this field's value depends on whether thumbnail's url was automatically resolved

externalId

string <= 255 characters

Client defined product variant identifier

Responses

Response Schema: application/json

id

required

integer

name

required

string

thumbnail

required

string or null

URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.

invalidThumbnail

required

boolean

Marks whether thumbnail is a valid image

externalId

required

string or null <= 255 characters

Client defined product variant identifier

weight

required

string or null <float>

A decimal representation of the product's weight

required

Array of objects (ProductVariantBarcodeDto)

List of barcodes, associated with a variant

Array

isDefault required	boolean Informs whether this is a default barcode, for a variant. Every variant must have exactly one default barcode at all times.
barcode required	string Barcode value

isDefault

required

boolean

Informs whether this is a default variant, for a product. Every product must have exactly one default variant at all times.

productId

required

integer

id of a product in AiFi system

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"name": "string",
"weight": 0,
"barcodes": [{"isDefault": true,
"barcode": "string"
}
],
"isDefault": false,
"thumbnail": "string",
"invalidThumbnail": true,
"externalId": "string"
}

Response samples

201
422

Content type

application/json

{"id": 0,
"name": "string",
"thumbnail": "string",
"invalidThumbnail": true,
"externalId": "string",
"weight": "string",
"barcodes": [{"isDefault": true,
"barcode": "string"
}
],
"isDefault": true,
"productId": 0
}

Add barcode to variant

path Parameters

id

required

integer

Id of the product variant

Request Body schema: application/json
required

isDefault required	boolean Informs whether this is a default barcode, for a variant. Every variant must have exactly one default barcode at all times.
barcode required	string Barcode value

Responses

Response Schema: application/json

id

required

integer

name

required

string

thumbnail

required

string or null

URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.

invalidThumbnail

required

boolean

Marks whether thumbnail is a valid image

externalId

required

string or null <= 255 characters

Client defined product variant identifier

weight

required

string or null <float>

A decimal representation of the product's weight

required

Array of objects (ProductVariantBarcodeDto)

List of barcodes, associated with a variant

Array

isDefault required	boolean Informs whether this is a default barcode, for a variant. Every variant must have exactly one default barcode at all times.
barcode required	string Barcode value

isDefault

required

boolean

Informs whether this is a default variant, for a product. Every product must have exactly one default variant at all times.

productId

required

integer

id of a product in AiFi system

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"isDefault": true,
"barcode": "string"
}

Response samples

200
422

Content type

application/json

{"id": 0,
"name": "string",
"thumbnail": "string",
"invalidThumbnail": true,
"externalId": "string",
"weight": "string",
"barcodes": [{"isDefault": true,
"barcode": "string"
}
],
"isDefault": true,
"productId": 0
}

Deletes specified barcode from variant

In case deleted barcode was a default barcode for variant, it's oldest barcode becomes a new default.

path Parameters

id required	integer Id of the product variant
barcode required	string

Responses

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

422

Content type

application/json

{"message": "Invalid request body",
"type": "E_INVALID_BODY",
"errors": [{"error": "\"email\" is required",
"rule": "any.required",
"field": "\"email\""
}
]
}

List products

query Parameters

offset	integer >= 0 Pagination offset
count	integer [ 1 .. 200 ] Default: 50 Number of results
minCreatedAt	string <date-time> Example: minCreatedAt=2024-09-22T00:00:00.000Z
maxCreatedAt	string <date-time> Example: maxCreatedAt=2024-09-29T00:00:00.000Z
minUpdatedAt	string <date-time> Example: minUpdatedAt=2024-09-23T00:00:00.000Z
maxUpdatedAt	string <date-time> Example: maxUpdatedAt=2024-09-30T00:00:00.000Z
sort	string Default: "id" Enum: "createdAt" "name" "price" "quantity" "id" Sort key, default to id
direction	string Default: "asc" Enum: "asc" "desc" Sort direction, default to asc
id	Array of integers Filter by id(s)
name	Array of strings Filter by name(s)
barcode	Array of strings Filter by barcode(s)
externalId	Array of strings Filter by externalId(s)
invalidThumbnail	boolean Filter by invalidThumbnail
priceMin	number >= 0 Filter by price (NOTE: does not apply to store-specific prices)
priceMax	number >= 0 Filter by price (NOTE: does not apply to store-specific prices)
quantityMin	integer >= 0 Deprecated Filter by quantity
quantityMax	integer >= 0 Deprecated Filter by quantity
category	Array of strings Deprecated Filter by category(categories)
sku	Array of strings Deprecated Filter by sku(s)
location	Array of strings Deprecated Filter by location(s)

Responses

Response Schema: application/json

One of

required

Array of objects (ProductResponseDto)

Array

id

required

string <integer>

Id of the product

name

required

string

price

required

string or null <float>

Unit price for single item, depending on configuration it may either contain the tax (suitable e.g. for integrations in EU) or not (suitable e.g. for integrations in the US)

barcode

required

string

Default barcode of default variant for this product

category

required

string or null

Deprecated

thumbnail

required

string or null

URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.

invalidThumbnail

required

boolean

Marks whether thumbnail is a valid image

productId

required

integer or null

Deprecated

Id of a product in Shopify

quantity

required

integer or null

Deprecated

weight

required

number or null

Weight of a default variant

sku

required

string or null

Deprecated

inventoryItemId

required

integer or null

Deprecated

externalId

required

string or null

Client defined product identifier

restricted

required

boolean

Whether the product is a restriction item

taxCode

required

string or null

Avalara tax code, available ig avalara integration is enabled

required

Array of objects (ProductStorePriceDto)

The current (latest) store prices for each store that they were defined for

Array

storeId required	string <integer> id of the store
productId required	string <integer> id of the product
price required	string <integer> Unit price for single item, depending on configuration it may either contain the tax (suitable e.g. for integrations in EU) or not (suitable e.g. for integrations in the US)
createdAt required	string <date-time> ISO formatted date representing when the entity was created

required

Array of objects (ProductVariantResponseDto)

List of product variants

Array

id

required

integer

name

required

string

thumbnail

required

string or null

URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.

invalidThumbnail

required

boolean

Marks whether thumbnail is a valid image

externalId

required

string or null <= 255 characters

Client defined product variant identifier

weight

required

string or null <float>

A decimal representation of the product's weight

required

Array of objects (ProductVariantBarcodeDto)

List of barcodes, associated with a variant

Array

isDefault required	boolean Informs whether this is a default barcode, for a variant. Every variant must have exactly one default barcode at all times.
barcode required	string Barcode value

isDefault

required

boolean

Informs whether this is a default variant, for a product. Every product must have exactly one default variant at all times.

productId

required

integer

id of a product in AiFi system

required

object

offset based pagination

object

Query parameter to fetch previous page

offset required	integer Pagination offset
count required	integer Number of results

object

Query parameter to fetch next page

offset required	integer Pagination offset
count required	integer Number of results

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

Example

ListProductResponseDto

{"products": [{"id": "string",
"name": "string",
"price": "string",
"barcode": "string",
"category": "string",
"thumbnail": "string",
"invalidThumbnail": true,
"productId": 0,
"quantity": 0,
"weight": 0,
"sku": "string",
"inventoryItemId": 0,
"externalId": "string",
"restricted": true,
"taxCode": "string",
"storePrices": [{"storeId": "string",
"productId": "string",
"price": "string",
"createdAt": "2019-08-24T14:15:22Z"
}
],
"variants": [{"id": 0,
"name": "string",
"thumbnail": "string",
"invalidThumbnail": true,
"externalId": "string",
"weight": "string",
"barcodes": [{"isDefault": true,
"barcode": "string"
}
],
"isDefault": true,
"productId": 0
}
]
}
],
"pagination": {"previous": {"offset": 0,
"count": 0
},
"next": {"offset": 0,
"count": 0
}
}
}

Upsert product by product externalId

This endpoint allows you to upsert (create or update) a product by specifying externalId in the query.

query Parameters

externalId

required

string

Client defined product identifier

Request Body schema: application/json
required

One of

name

required

string

price

required

number >= 0

The default price, used if a store-specific price is not specified.

quantity

integer >= 0

Deprecated

Default: 0

category

string

Deprecated

sku

string

Deprecated

thumbnail

string

URL to thumbnail. If not provided best-effort will be taken to resolve thumbnail url automatically

invalidThumbnail

string

Marks whether thumbnail is a valid image. Can only be specified if 'thumbnail' was also specified and it's value is not empty. If 'thumbnail' was specified then default value for this field is 'false'. Otherwise there is no default value and this field's value depends on whether thumbnail's url was automatically resolved

inventoryItemId

integer

Deprecated

externalId

string

Client defined product identifier

taxCode

string or null

Avalara tax code, available ig avalara integration is enabled

restricted

boolean

Whether the product is a restriction item

Array of objects (CreateStorePriceRequestDto)

An optional list to specify prices per store. IMPORTANT - if specified once, you cannot go back to the default price! You will need to update the prices every time going forward.

Array

storeId required	integer >= 1 id of the store
price required	number >= 0 Unit price for single item, depending on configuration it may either contain the tax (suitable e.g. for integrations in EU) or not (suitable e.g. for integrations in the US)

barcode

required

string

Default barcode of default variant for this product

weight

required

number

Weight of a default variant

Responses

Response Schema: application/json

id

required

string <integer>

Id of the product

name

required

string

price

required

string or null <float>

Unit price for single item, depending on configuration it may either contain the tax (suitable e.g. for integrations in EU) or not (suitable e.g. for integrations in the US)

barcode

required

string

Default barcode of default variant for this product

category

required

string or null

Deprecated

thumbnail

required

string or null

URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.

invalidThumbnail

required

boolean

Marks whether thumbnail is a valid image

productId

required

integer or null

Deprecated

Id of a product in Shopify

quantity

required

integer or null

Deprecated

weight

required

number or null

Weight of a default variant

sku

required

string or null

Deprecated

inventoryItemId

required

integer or null

Deprecated

externalId

required

string or null

Client defined product identifier

restricted

required

boolean

Whether the product is a restriction item

taxCode

required

string or null

Avalara tax code, available ig avalara integration is enabled

required

Array of objects (ProductStorePriceDto)

The current (latest) store prices for each store that they were defined for

Array

storeId required	string <integer> id of the store
productId required	string <integer> id of the product
price required	string <integer> Unit price for single item, depending on configuration it may either contain the tax (suitable e.g. for integrations in EU) or not (suitable e.g. for integrations in the US)
createdAt required	string <date-time> ISO formatted date representing when the entity was created

required

Array of objects (ProductVariantResponseDto)

List of product variants

Array

id

required

integer

name

required

string

thumbnail

required

string or null

URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.

invalidThumbnail

required

boolean

Marks whether thumbnail is a valid image

externalId

required

string or null <= 255 characters

Client defined product variant identifier

weight

required

string or null <float>

A decimal representation of the product's weight

required

Array of objects (ProductVariantBarcodeDto)

List of barcodes, associated with a variant

Array

isDefault required	boolean Informs whether this is a default barcode, for a variant. Every variant must have exactly one default barcode at all times.
barcode required	string Barcode value

isDefault

required

boolean

Informs whether this is a default variant, for a product. Every product must have exactly one default variant at all times.

productId

required

integer

id of a product in AiFi system

Response Schema: application/json

id

required

string <integer>

Id of the product

name

required

string

price

required

string or null <float>

Unit price for single item, depending on configuration it may either contain the tax (suitable e.g. for integrations in EU) or not (suitable e.g. for integrations in the US)

barcode

required

string

Default barcode of default variant for this product

category

required

string or null

Deprecated

thumbnail

required

string or null

URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.

invalidThumbnail

required

boolean

Marks whether thumbnail is a valid image

productId

required

integer or null

Deprecated

Id of a product in Shopify

quantity

required

integer or null

Deprecated

weight

required

number or null

Weight of a default variant

sku

required

string or null

Deprecated

inventoryItemId

required

integer or null

Deprecated

externalId

required

string or null

Client defined product identifier

restricted

required

boolean

Whether the product is a restriction item

taxCode

required

string or null

Avalara tax code, available ig avalara integration is enabled

required

Array of objects (ProductStorePriceDto)

The current (latest) store prices for each store that they were defined for

Array

storeId required	string <integer> id of the store
productId required	string <integer> id of the product
price required	string <integer> Unit price for single item, depending on configuration it may either contain the tax (suitable e.g. for integrations in EU) or not (suitable e.g. for integrations in the US)
createdAt required	string <date-time> ISO formatted date representing when the entity was created

required

Array of objects (ProductVariantResponseDto)

List of product variants

Array

id

required

integer

name

required

string

thumbnail

required

string or null

URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.

invalidThumbnail

required

boolean

Marks whether thumbnail is a valid image

externalId

required

string or null <= 255 characters

Client defined product variant identifier

weight

required

string or null <float>

A decimal representation of the product's weight

required

Array of objects (ProductVariantBarcodeDto)

List of barcodes, associated with a variant

Array

isDefault required	boolean Informs whether this is a default barcode, for a variant. Every variant must have exactly one default barcode at all times.
barcode required	string Barcode value

isDefault

required

boolean

Informs whether this is a default variant, for a product. Every product must have exactly one default variant at all times.

productId

required

integer

id of a product in AiFi system

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

Example

CreateProductWithBarcodeRequestDto

{"name": "string",
"price": 0,
"quantity": 0,
"category": "string",
"sku": "string",
"thumbnail": "string",
"invalidThumbnail": "string",
"inventoryItemId": 0,
"externalId": "string",
"taxCode": "string",
"restricted": true,
"storePrices": [{"storeId": 1,
"price": 0
}
],
"barcode": "string",
"weight": 0
}

Response samples

200
201
422

Content type

application/json

{"id": "string",
"name": "string",
"price": "string",
"barcode": "string",
"category": "string",
"thumbnail": "string",
"invalidThumbnail": true,
"productId": 0,
"quantity": 0,
"weight": 0,
"sku": "string",
"inventoryItemId": 0,
"externalId": "string",
"restricted": true,
"taxCode": "string",
"storePrices": [{"storeId": "string",
"productId": "string",
"price": "string",
"createdAt": "2019-08-24T14:15:22Z"
}
],
"variants": [{"id": 0,
"name": "string",
"thumbnail": "string",
"invalidThumbnail": true,
"externalId": "string",
"weight": "string",
"barcodes": [{"isDefault": true,
"barcode": "string"
}
],
"isDefault": true,
"productId": 0
}
]
}

Create a product

Request Body schema: application/json
required

One of

name

required

string

price

required

number >= 0

The default price, used if a store-specific price is not specified.

quantity

integer >= 0

Deprecated

Default: 0

category

string

Deprecated

sku

string

Deprecated

thumbnail

string

URL to thumbnail. If not provided best-effort will be taken to resolve thumbnail url automatically

invalidThumbnail

string

Marks whether thumbnail is a valid image. Can only be specified if 'thumbnail' was also specified and it's value is not empty. If 'thumbnail' was specified then default value for this field is 'false'. Otherwise there is no default value and this field's value depends on whether thumbnail's url was automatically resolved

inventoryItemId

integer

Deprecated

externalId

string

Client defined product identifier

taxCode

string or null

Avalara tax code, available ig avalara integration is enabled

restricted

boolean

Whether the product is a restriction item

Array of objects (CreateStorePriceRequestDto)

An optional list to specify prices per store. IMPORTANT - if specified once, you cannot go back to the default price! You will need to update the prices every time going forward.

Array

storeId required	integer >= 1 id of the store
price required	number >= 0 Unit price for single item, depending on configuration it may either contain the tax (suitable e.g. for integrations in EU) or not (suitable e.g. for integrations in the US)

barcode

required

string

Default barcode of default variant for this product

weight

required

number

Weight of a default variant

Responses

Response Schema: application/json

id

required

string <integer>

Id of the product

name

required

string

price

required

string or null <float>

Unit price for single item, depending on configuration it may either contain the tax (suitable e.g. for integrations in EU) or not (suitable e.g. for integrations in the US)

barcode

required

string

Default barcode of default variant for this product

category

required

string or null

Deprecated

thumbnail

required

string or null

URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.

invalidThumbnail

required

boolean

Marks whether thumbnail is a valid image

productId

required

integer or null

Deprecated

Id of a product in Shopify

quantity

required

integer or null

Deprecated

weight

required

number or null

Weight of a default variant

sku

required

string or null

Deprecated

inventoryItemId

required

integer or null

Deprecated

externalId

required

string or null

Client defined product identifier

restricted

required

boolean

Whether the product is a restriction item

taxCode

required

string or null

Avalara tax code, available ig avalara integration is enabled

required

Array of objects (ProductStorePriceDto)

The current (latest) store prices for each store that they were defined for

Array

storeId required	string <integer> id of the store
productId required	string <integer> id of the product
price required	string <integer> Unit price for single item, depending on configuration it may either contain the tax (suitable e.g. for integrations in EU) or not (suitable e.g. for integrations in the US)
createdAt required	string <date-time> ISO formatted date representing when the entity was created

required

Array of objects (ProductVariantResponseDto)

List of product variants

Array

id

required

integer

name

required

string

thumbnail

required

string or null

URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.

invalidThumbnail

required

boolean

Marks whether thumbnail is a valid image

externalId

required

string or null <= 255 characters

Client defined product variant identifier

weight

required

string or null <float>

A decimal representation of the product's weight

required

Array of objects (ProductVariantBarcodeDto)

List of barcodes, associated with a variant

Array

isDefault required	boolean Informs whether this is a default barcode, for a variant. Every variant must have exactly one default barcode at all times.
barcode required	string Barcode value

isDefault

required

boolean

Informs whether this is a default variant, for a product. Every product must have exactly one default variant at all times.

productId

required

integer

id of a product in AiFi system

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

Example

CreateProductWithBarcodeRequestDto

{"name": "string",
"price": 0,
"quantity": 0,
"category": "string",
"sku": "string",
"thumbnail": "string",
"invalidThumbnail": "string",
"inventoryItemId": 0,
"externalId": "string",
"taxCode": "string",
"restricted": true,
"storePrices": [{"storeId": 1,
"price": 0
}
],
"barcode": "string",
"weight": 0
}

Response samples

201
422

Content type

application/json

{"id": "string",
"name": "string",
"price": "string",
"barcode": "string",
"category": "string",
"thumbnail": "string",
"invalidThumbnail": true,
"productId": 0,
"quantity": 0,
"weight": 0,
"sku": "string",
"inventoryItemId": 0,
"externalId": "string",
"restricted": true,
"taxCode": "string",
"storePrices": [{"storeId": "string",
"productId": "string",
"price": "string",
"createdAt": "2019-08-24T14:15:22Z"
}
],
"variants": [{"id": 0,
"name": "string",
"thumbnail": "string",
"invalidThumbnail": true,
"externalId": "string",
"weight": "string",
"barcodes": [{"isDefault": true,
"barcode": "string"
}
],
"isDefault": true,
"productId": 0
}
]
}

Get a list of all the taxrates available

Responses

Response Schema: application/json

Array

taxCode required	string Avalara tax code
country required	string Enum: "AC" "AD" "AE" "AF" "AG" "AI" "AL" "AM" "AN" "AO" "AR" "AT" "AU" "AW" "AX" "AZ" "BA" "BB" "BD" "BE" "BF" "BG" "BH" "BI" "BJ" "BL" "BM" "BN" "BO" "BQ" "BR" "BS" "BT" "BV" "BW" "BY" "BZ" "CA" "CC" "CD" "CF" "CG" "CH" "CI" "CK" "CL" "CM" "CN" "CO" "CR" "CU" "CV" "CW" "CX" "CY" "CZ" "DE" "DJ" "DK" "DM" "DO" "DZ" "EC" "EE" "EG" "EH" "ER" "ES" "ET" "FI" "FJ" "FK" "FO" "FR" "GA" "GB" "GD" "GE" "GF" "GG" "GH" "GI" "GL" "GM" "GN" "GP" "GQ" "GR" "GS" "GT" "GW" "GY" "HK" "HM" "HN" "HR" "HT" "HU" "ID" "IE" "IL" "IM" "IN" "IO" "IQ" "IR" "IS" "IT" "JE" "JM" "JO" "JP" "KE" "KG" "KH" "KI" "KM" "KN" "KP" "KR" "KW" "KY" "KZ" "LA" "LB" "LC" "LI" "LK" "LR" "LS" "LT" "LU" "LV" "LY" "MA" "MC" "MD" "ME" "MF" "MG" "MK" "ML" "MM" "MN" "MO" "MQ" "MR" "MS" "MT" "MU" "MV" "MW" "MX" "MY" "MZ" "NA" "NC" "NE" "NF" "NG" "NI" "NL" "NO" "NP" "NR" "NU" "NZ" "OM" "PA" "PE" "PF" "PG" "PH" "PK" "PL" "PM" "PN" "PS" "PT" "PY" "QA" "RE" "RO" "RS" "RU" "RW" "SA" "SB" "SC" "SD" "SE" "SG" "SH" "SI" "SJ" "SK" "SL" "SM" "SN" "SO" "SR" "SS" "ST" "SV" "SX" "SY" "SZ" "TA" "TC" "TD" "TF" "TG" "TH" "TJ" "TK" "TL" "TM" "TN" "TO" "TR" "TT" "TV" "TW" "TZ" "UA" "UG" "UM" "US" "UY" "UZ" "VA" "VC" "VE" "VG" "VN" "VU" "WF" "WS" "XK" "YE" "YT" "ZA" "ZM" "ZW" ISO 3166 two character country codes
description required	string a description of the tax code

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

[{"taxCode": "string",
"country": "AC",
"description": "string"
}
]

List categories

query Parameters

count

number

Default: 50

This endpoint doesn't support pagination but you can use count query param to specify number of results.

Responses

Response Schema: application/json

Array

string

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

["string"
]

Get product detail by id

path Parameters

id

required

integer

Id of a product

Responses

Response Schema: application/json

One of

id

required

string <integer>

Id of the product

name

required

string

price

required

string or null <float>

Unit price for single item, depending on configuration it may either contain the tax (suitable e.g. for integrations in EU) or not (suitable e.g. for integrations in the US)

barcode

required

string

Default barcode of default variant for this product

category

required

string or null

Deprecated

thumbnail

required

string or null

URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.

invalidThumbnail

required

boolean

Marks whether thumbnail is a valid image

productId

required

integer or null

Deprecated

Id of a product in Shopify

quantity

required

integer or null

Deprecated

weight

required

number or null

Weight of a default variant

sku

required

string or null

Deprecated

inventoryItemId

required

integer or null

Deprecated

externalId

required

string or null

Client defined product identifier

restricted

required

boolean

Whether the product is a restriction item

taxCode

required

string or null

Avalara tax code, available ig avalara integration is enabled

required

Array of objects (ProductStorePriceDto)

The current (latest) store prices for each store that they were defined for

Array

storeId required	string <integer> id of the store
productId required	string <integer> id of the product
price required	string <integer> Unit price for single item, depending on configuration it may either contain the tax (suitable e.g. for integrations in EU) or not (suitable e.g. for integrations in the US)
createdAt required	string <date-time> ISO formatted date representing when the entity was created

required

Array of objects (ProductVariantResponseDto)

List of product variants

Array

id

required

integer

name

required

string

thumbnail

required

string or null

URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.

invalidThumbnail

required

boolean

Marks whether thumbnail is a valid image

externalId

required

string or null <= 255 characters

Client defined product variant identifier

weight

required

string or null <float>

A decimal representation of the product's weight

required

Array of objects (ProductVariantBarcodeDto)

List of barcodes, associated with a variant

Array

isDefault required	boolean Informs whether this is a default barcode, for a variant. Every variant must have exactly one default barcode at all times.
barcode required	string Barcode value

isDefault

required

boolean

Informs whether this is a default variant, for a product. Every product must have exactly one default variant at all times.

productId

required

integer

id of a product in AiFi system

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

Example

ProductResponseDto

{"id": "string",
"name": "string",
"price": "string",
"barcode": "string",
"category": "string",
"thumbnail": "string",
"invalidThumbnail": true,
"productId": 0,
"quantity": 0,
"weight": 0,
"sku": "string",
"inventoryItemId": 0,
"externalId": "string",
"restricted": true,
"taxCode": "string",
"storePrices": [{"storeId": "string",
"productId": "string",
"price": "string",
"createdAt": "2019-08-24T14:15:22Z"
}
],
"variants": [{"id": 0,
"name": "string",
"thumbnail": "string",
"invalidThumbnail": true,
"externalId": "string",
"weight": "string",
"barcodes": [{"isDefault": true,
"barcode": "string"
}
],
"isDefault": true,
"productId": 0
}
]
}

Update product by product id

This endpoint allows you to update a product by specifying id in the path.

path Parameters

id

required

integer

id of a product

Request Body schema: application/json
required

One of

name

required

string

price

required

number >= 0

The default price, used if a store-specific price is not specified.

quantity

integer >= 0

Deprecated

Default: 0

category

string

Deprecated

sku

string

Deprecated

thumbnail

string

URL to thumbnail. If not provided best-effort will be taken to resolve thumbnail url automatically

invalidThumbnail

string

Marks whether thumbnail is a valid image. Can only be specified if 'thumbnail' was also specified and it's value is not empty. If 'thumbnail' was specified then default value for this field is 'false'. Otherwise there is no default value and this field's value depends on whether thumbnail's url was automatically resolved

inventoryItemId

integer

Deprecated

externalId

string

Client defined product identifier

taxCode

string or null

Avalara tax code, available ig avalara integration is enabled

restricted

boolean

Whether the product is a restriction item

Array of objects (CreateStorePriceRequestDto)

An optional list to specify prices per store. IMPORTANT - if specified once, you cannot go back to the default price! You will need to update the prices every time going forward.

Array

storeId required	integer >= 1 id of the store
price required	number >= 0 Unit price for single item, depending on configuration it may either contain the tax (suitable e.g. for integrations in EU) or not (suitable e.g. for integrations in the US)

barcode

required

string

Default barcode of default variant for this product

weight

required

number

Weight of a default variant

Responses

Response Schema: application/json

id

required

string <integer>

Id of the product

name

required

string

price

required

string or null <float>

Unit price for single item, depending on configuration it may either contain the tax (suitable e.g. for integrations in EU) or not (suitable e.g. for integrations in the US)

barcode

required

string

Default barcode of default variant for this product

category

required

string or null

Deprecated

thumbnail

required

string or null

URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.

invalidThumbnail

required

boolean

Marks whether thumbnail is a valid image

productId

required

integer or null

Deprecated

Id of a product in Shopify

quantity

required

integer or null

Deprecated

weight

required

number or null

Weight of a default variant

sku

required

string or null

Deprecated

inventoryItemId

required

integer or null

Deprecated

externalId

required

string or null

Client defined product identifier

restricted

required

boolean

Whether the product is a restriction item

taxCode

required

string or null

Avalara tax code, available ig avalara integration is enabled

required

Array of objects (ProductStorePriceDto)

The current (latest) store prices for each store that they were defined for

Array

storeId required	string <integer> id of the store
productId required	string <integer> id of the product
price required	string <integer> Unit price for single item, depending on configuration it may either contain the tax (suitable e.g. for integrations in EU) or not (suitable e.g. for integrations in the US)
createdAt required	string <date-time> ISO formatted date representing when the entity was created

required

Array of objects (ProductVariantResponseDto)

List of product variants

Array

id

required

integer

name

required

string

thumbnail

required

string or null

URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.

invalidThumbnail

required

boolean

Marks whether thumbnail is a valid image

externalId

required

string or null <= 255 characters

Client defined product variant identifier

weight

required

string or null <float>

A decimal representation of the product's weight

required

Array of objects (ProductVariantBarcodeDto)

List of barcodes, associated with a variant

Array

isDefault required	boolean Informs whether this is a default barcode, for a variant. Every variant must have exactly one default barcode at all times.
barcode required	string Barcode value

isDefault

required

boolean

Informs whether this is a default variant, for a product. Every product must have exactly one default variant at all times.

productId

required

integer

id of a product in AiFi system

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

Example

CreateProductWithBarcodeRequestDto

{"name": "string",
"price": 0,
"quantity": 0,
"category": "string",
"sku": "string",
"thumbnail": "string",
"invalidThumbnail": "string",
"inventoryItemId": 0,
"externalId": "string",
"taxCode": "string",
"restricted": true,
"storePrices": [{"storeId": 1,
"price": 0
}
],
"barcode": "string",
"weight": 0
}

Response samples

200
422

Content type

application/json

{"id": "string",
"name": "string",
"price": "string",
"barcode": "string",
"category": "string",
"thumbnail": "string",
"invalidThumbnail": true,
"productId": 0,
"quantity": 0,
"weight": 0,
"sku": "string",
"inventoryItemId": 0,
"externalId": "string",
"restricted": true,
"taxCode": "string",
"storePrices": [{"storeId": "string",
"productId": "string",
"price": "string",
"createdAt": "2019-08-24T14:15:22Z"
}
],
"variants": [{"id": 0,
"name": "string",
"thumbnail": "string",
"invalidThumbnail": true,
"externalId": "string",
"weight": "string",
"barcodes": [{"isDefault": true,
"barcode": "string"
}
],
"isDefault": true,
"productId": 0
}
]
}

Delete product by id

path Parameters

id

required

integer

Id of a product

Responses

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

422

Content type

application/json

{"message": "Invalid request body",
"type": "E_INVALID_BODY",
"errors": [{"error": "\"email\" is required",
"rule": "any.required",
"field": "\"email\""
}
]
}

Trigger an async job to sync product to store(s)

Request Body schema: application/json
required

storeId

integer

Id of target store, or sync product to all store if not provided

Responses

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"storeId": 0
}

Response samples

422

Content type

application/json

{"message": "Invalid request body",
"type": "E_INVALID_BODY",
"errors": [{"error": "\"email\" is required",
"rule": "any.required",
"field": "\"email\""
}
]
}

Get product planogram

path Parameters

id

required

integer

Id of a product

query Parameters

storeId	integer Example: storeId=11 Id of the physical store
withMisplacements	boolean Whether result should contain misplaced instances of the product

Responses

Response Schema: application/json

required

object or null

additional property

object (ProductPlanogramShelfDto)

productAvailable

boolean

required

object

additional property

object (ShelfInventoryDto)

shelfIndex

required

integer

Index of a shelf

required

object

Coordinates of the shelf

dimX

required

number

dimY

required

number

dimZ

required

number

required

object (TransformAllRequiredDto)

required

object (Pos3DDto)

x required	string <float> x coordinate
y required	string <float> y coordinate
z required	string <float> z coordinate

required

object (Pos3DDto)

x required	string <float> x coordinate
y required	string <float> y coordinate
z required	string <float> z coordinate

required

Array of objects (ShelfBinDto)

Array

binSize

required

number

productId

required

integer or null

Id of the product which should be present in this bin

productName

required

string or null

Name of the product which should be present in this bin

productBarcode

required

string or null

Barcode of the product which should be present in this bin

thumbnail

required

string or null

Thumbnail of the product which should be present in this bin

restricted

required

boolean or null

Whether the product is a restriction item

productUnits

required

number or null

Number of all products in the bin that are supposed to be there

unplannedProductsUnits

number

Number of all products in the bin that are not supposed to be there

Array of objects (BinPlanogramDto)

All products that are present in the bin

Array

quantity

required

number

required

object (BinProductDto)

barcode required	string
barcodeType required	string Deprecated Enum: "upc" "ean13" "unknown"
productId required	integer or null
name	string
price	string
thumbnail	string <uri>
weight	number
retailerType required	string Deprecated Enum: "shopify" "unknown"
RIN	string Deprecated Retailer identification number
restricted	boolean

sizeType

required

string

Enum: "plate" "meters"

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

{"gondolasPlanogram": {"property1": {"productAvailable": true,
"shelves": {"property1": {"shelfIndex": 5,
"coordinates": {"dimX": 0,
"dimY": 0,
"dimZ": 0,
"transform": {"translation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
},
"rotation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
}
}
},
"bins": [{"binSize": 0,
"productId": 0,
"productName": "string",
"productBarcode": "string",
"thumbnail": "string",
"restricted": true,
"productUnits": 0,
"unplannedProductsUnits": 0,
"products": [{"quantity": 0,
"product": {"barcode": null,
"barcodeType": null,
"productId": null,
"name": null,
"price": null,
"thumbnail": null,
"weight": null,
"retailerType": null,
"RIN": null,
"restricted": null
}
}
]
}
],
"sizeType": "plate"
},
"property2": {"shelfIndex": 5,
"coordinates": {"dimX": 0,
"dimY": 0,
"dimZ": 0,
"transform": {"translation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
},
"rotation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
}
}
},
"bins": [{"binSize": 0,
"productId": 0,
"productName": "string",
"productBarcode": "string",
"thumbnail": "string",
"restricted": true,
"productUnits": 0,
"unplannedProductsUnits": 0,
"products": [{"quantity": 0,
"product": {"barcode": null,
"barcodeType": null,
"productId": null,
"name": null,
"price": null,
"thumbnail": null,
"weight": null,
"retailerType": null,
"RIN": null,
"restricted": null
}
}
]
}
],
"sizeType": "plate"
}
}
},
"property2": {"productAvailable": true,
"shelves": {"property1": {"shelfIndex": 5,
"coordinates": {"dimX": 0,
"dimY": 0,
"dimZ": 0,
"transform": {"translation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
},
"rotation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
}
}
},
"bins": [{"binSize": 0,
"productId": 0,
"productName": "string",
"productBarcode": "string",
"thumbnail": "string",
"restricted": true,
"productUnits": 0,
"unplannedProductsUnits": 0,
"products": [{"quantity": 0,
"product": {"barcode": null,
"barcodeType": null,
"productId": null,
"name": null,
"price": null,
"thumbnail": null,
"weight": null,
"retailerType": null,
"RIN": null,
"restricted": null
}
}
]
}
],
"sizeType": "plate"
},
"property2": {"shelfIndex": 5,
"coordinates": {"dimX": 0,
"dimY": 0,
"dimZ": 0,
"transform": {"translation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
},
"rotation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
}
}
},
"bins": [{"binSize": 0,
"productId": 0,
"productName": "string",
"productBarcode": "string",
"thumbnail": "string",
"restricted": true,
"productUnits": 0,
"unplannedProductsUnits": 0,
"products": [{"quantity": 0,
"product": {"barcode": null,
"barcodeType": null,
"productId": null,
"name": null,
"price": null,
"thumbnail": null,
"weight": null,
"retailerType": null,
"RIN": null,
"restricted": null
}
}
]
}
],
"sizeType": "plate"
}
}
}
}
}

Admin API - customers

Lists all customers

query Parameters

minCreatedAt	string <date-time> Example: minCreatedAt=2024-09-22T00:00:00.000Z
maxCreatedAt	string <date-time> Example: maxCreatedAt=2024-09-29T00:00:00.000Z
minUpdatedAt	string <date-time> Example: minUpdatedAt=2024-09-23T00:00:00.000Z
maxUpdatedAt	string <date-time> Example: maxUpdatedAt=2024-09-30T00:00:00.000Z
externalId	string If provided filters result list by externalId(s)
email	string If provided filters result list by email(s)
paymentInstrumentProviderId	string If provided filters result list by id(s) of a payment instrument, associated with the resulting record, specified exactly as in payment provider's system

Responses

Response Schema: application/json

Array

id required	integer
externalId required	string or null Id of the customer in external system
role required	string Enum: "customer" "employee" "tester" "untracked" "unknown" Role of the customer
metadata required	object or null This object can contain custom metadata information
priority required	integer [ -10 .. 10 ] Default: 0 Customer priority. default to 0, which means any regular customer. customers with higher priority will have their shopping sessions prioritized during processing, the lower priority is opposite.
email required	string <email>
firstName required	string or null
lastName required	string or null
phone required	string or null

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

[{"id": 0,
"externalId": "string",
"role": "customer",
"metadata": {"arbitraryKey": "arbitraryValue"
},
"priority": 0,
"email": "user@example.com",
"firstName": "string",
"lastName": "string",
"phone": "string"
}
]

Create customer

Request Body schema: application/json
required

email	string <email> The system will randomly generate a fake email if not provided
password	string <password> [ 8 .. 255 ] characters The system will randomly generate a fake password if not provided
externalId	string Id of the customer in external system
firstName	string
lastName	string
phone	string
role	string Default: "customer" Enum: "customer" "employee" "tester" "untracked" "unknown" Role of the customer
priority	integer [ -10 .. 10 ] Default: 0 Customer priority. default to 0, which means any regular customer. customers with higher priority will have their shopping sessions prioritized during processing, the lower priority is opposite.
metadata	object or null Default: null This object can contain custom metadata information

Responses

Response Schema: application/json

id required	integer
externalId required	string or null Id of the customer in external system
role required	string Enum: "customer" "employee" "tester" "untracked" "unknown" Role of the customer
metadata required	object or null This object can contain custom metadata information
priority required	integer [ -10 .. 10 ] Default: 0 Customer priority. default to 0, which means any regular customer. customers with higher priority will have their shopping sessions prioritized during processing, the lower priority is opposite.
email required	string <email>
firstName required	string or null
lastName required	string or null
phone required	string or null

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"email": "user@example.com",
"password": "pa$$word",
"externalId": "string",
"firstName": "string",
"lastName": "string",
"phone": "string",
"role": "customer",
"priority": 0,
"metadata": {"arbitraryKey": "arbitraryValue"
}
}

Response samples

201
422

Content type

application/json

{"id": 0,
"externalId": "string",
"role": "customer",
"metadata": {"arbitraryKey": "arbitraryValue"
},
"priority": 0,
"email": "user@example.com",
"firstName": "string",
"lastName": "string",
"phone": "string"
}

Notifies Register frontend to start a flow Deprecated

Notifies Register frontend to start a flow of registering new customer with specified token, this endpoint has been deprecated, use api/admin/v2/stores/{storeId}/check-in/{checkInDeviceId}/remote-register instead

Request Body schema: application/json
required

token required	string A string token to start frontend registration flow
storeId required	integer Id of the physical store
tokenType required	string Default: "SESSION_ID" Enum: "SESSION_ID" "NONE" session token type
checkInDeviceId	integer The id of check-in device

Responses

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"token": "string",
"storeId": 0,
"tokenType": "SESSION_ID",
"checkInDeviceId": 0
}

Response samples

422

Content type

application/json

{"message": "Invalid request body",
"type": "E_INVALID_BODY",
"errors": [{"error": "\"email\" is required",
"rule": "any.required",
"field": "\"email\""
}
]
}

Get customer detail by customerId

path Parameters

customerId

required

integer

Responses

Response Schema: application/json

id required	integer
externalId required	string or null Id of the customer in external system
role required	string Enum: "customer" "employee" "tester" "untracked" "unknown" Role of the customer
metadata required	object or null This object can contain custom metadata information
priority required	integer [ -10 .. 10 ] Default: 0 Customer priority. default to 0, which means any regular customer. customers with higher priority will have their shopping sessions prioritized during processing, the lower priority is opposite.
email required	string <email>
firstName required	string or null
lastName required	string or null
phone required	string or null

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

{"id": 0,
"externalId": "string",
"role": "customer",
"metadata": {"arbitraryKey": "arbitraryValue"
},
"priority": 0,
"email": "user@example.com",
"firstName": "string",
"lastName": "string",
"phone": "string"
}

Update customer by customerId

path Parameters

customerId

required

integer

Request Body schema: application/json
required

email

string <email>

The system will randomly generate a fake email if not provided

externalId

string

Id of the customer in external system

firstName

string

lastName

string

phone

string

role

string

Default: "customer"

Enum: "customer" "employee" "tester" "untracked" "unknown"

Role of the customer

priority

integer [ -10 .. 10 ]

Default: 0

Customer priority. default to 0, which means any regular customer. customers with higher priority will have their shopping sessions prioritized during processing, the lower priority is opposite.

metadata

object or null

Default: null

This object can contain custom metadata information

password

string <password> [ 8 .. 255 ] characters

New password that will be set for the user

currentPassword

string <password> [ 8 .. 255 ] characters

Current password of the user

blocked

boolean

If true, the customer cannot enter the store

object (CardUpdateRequestDto)

provider required	string Enum: "NONE" "STRIPE" "PAYTER" "ADYEN" "FREEDOM_PAY" "GENERIC"
underlyingPaymentProvider	string To identify the real payment provider when provider is GENERIC
cardToken	string or null Card token to charge customer, pass null to delete the existing payment instrument
cardId	string Unique id of the card. as apposed to cardToken, it should be the same (for a physical card) upon every tokenization
cardBin	string [ 6 .. 8 ] characters Bank identification number, first 6-8 digits of card's number
cardLast4Digits	string = 4 characters Last 4 digits of the card
cardExpiryDate	string Expiry date of the card in MM/YYYY or MM/YY format
defaultCard	string Default: false Whether it's the default card
cardBrand	string <= 30 characters Allow retailer to specify card brand, the length of this field should be less than or equal to 30. if this value is unknown or not specified, empty string will be included in webhooks

cardType

string

Deprecated

Default: "NONE"

Enum: "NONE" "STRIPE" "PAYTER" "ADYEN" "FREEDOM_PAY" "GENERIC"

Card/payment provider, deprecated, use card.provider instead

cardToken

string or null

Deprecated

Card token to charge customer, pass null to delete the existing payment instrument, deprecated, use card.cardToken instead

Responses

Response Schema: application/json

id required	integer
externalId required	string or null Id of the customer in external system
role required	string Enum: "customer" "employee" "tester" "untracked" "unknown" Role of the customer
metadata required	object or null This object can contain custom metadata information
priority required	integer [ -10 .. 10 ] Default: 0 Customer priority. default to 0, which means any regular customer. customers with higher priority will have their shopping sessions prioritized during processing, the lower priority is opposite.
email required	string <email>
firstName required	string or null
lastName required	string or null
phone required	string or null

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"email": "user@example.com",
"externalId": "string",
"firstName": "string",
"lastName": "string",
"phone": "string",
"role": "customer",
"priority": 0,
"metadata": {"arbitraryKey": "arbitraryValue"
},
"password": "pa$$word",
"currentPassword": "pa$$word",
"blocked": true,
"card": {"provider": "NONE",
"underlyingPaymentProvider": "string",
"cardToken": "string",
"cardId": "string",
"cardBin": "string",
"cardLast4Digits": "stri",
"cardExpiryDate": "string",
"defaultCard": false,
"cardBrand": "string"
},
"cardType": "NONE",
"cardToken": "string"
}

Response samples

200
422

Content type

application/json

{"id": 0,
"externalId": "string",
"role": "customer",
"metadata": {"arbitraryKey": "arbitraryValue"
},
"priority": 0,
"email": "user@example.com",
"firstName": "string",
"lastName": "string",
"phone": "string"
}

Set a card token for a customer

path Parameters

customerId

required

integer

Request Body schema: application/json
required

provider required	string Enum: "NONE" "STRIPE" "PAYTER" "ADYEN" "FREEDOM_PAY" "GENERIC" Payment provider
cardToken required	string Enum: "NONE" "STRIPE" "PAYTER" "ADYEN" "FREEDOM_PAY" "GENERIC" Card token to charge customer

Responses

Response Schema: application/json

id required	integer
externalId required	string or null Id of the customer in external system
role required	string Enum: "customer" "employee" "tester" "untracked" "unknown" Role of the customer
metadata required	object or null This object can contain custom metadata information
priority required	integer [ -10 .. 10 ] Default: 0 Customer priority. default to 0, which means any regular customer. customers with higher priority will have their shopping sessions prioritized during processing, the lower priority is opposite.
email required	string <email>
firstName required	string or null
lastName required	string or null
phone required	string or null

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"provider": "NONE",
"cardToken": "NONE"
}

Response samples

200
422

Content type

application/json

{"id": 0,
"externalId": "string",
"role": "customer",
"metadata": {"arbitraryKey": "arbitraryValue"
},
"priority": 0,
"email": "user@example.com",
"firstName": "string",
"lastName": "string",
"phone": "string"
}

Create new entry code for a customer

path Parameters

customerId

required

integer

query Parameters

displayable

boolean

If true, the returned value will be returned in a form which can be used as a qr-code payload. resulting qr-code can be scanned to let somebody into the store. otherwise the returned value will be returned "as is" and can be used in other calls to the APIs

Request Body schema: application/json
required

code

string

Entry code to be added to valid customer codes

groupSize

integer

Group size for that entry code

sessionId

string

Session token sent out later by aifi to identify transactions made on this entry code

referencedSessionId

string or null

Default: null

Referenced session token, that points to the source session

expiresAt

string <date-time>

ISO 8601 encoded time, at which this entry code will expire. If not specified a default value (depending on a deployment) will be set.

priority

integer [ -10 .. 10 ]

Default: 0

Customer priority. default to 0, which means any regular customer. customers with higher priority will have their shopping sessions prioritized during processing, the lower priority is opposite.

object

Card reader error, to allow registration screen to display error message to customer

errorType required	string <= 255 characters Error type, could be 'PRE_AUTH_VALIDATION_ERROR', 'USER_REGISTRATION_ERROR' etc
errorCode required	integer [ 80 .. 99 ] Entry screen will display corresponding error page according to the error code
message required	string <= 255 characters Message describing cause of the error

Responses

Response Schema: application/json

code

required

string

An entry code that can rendered as QR and used to enter AiFi store

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"code": "string",
"groupSize": 0,
"sessionId": "string",
"referencedSessionId": null,
"expiresAt": "2019-08-24T14:15:22Z",
"priority": 0,
"error": {"errorType": "string",
"errorCode": 80,
"message": "string"
}
}

Response samples

201
422

Content type

application/json

{"code": "string"
}

Add a new card to customer

path Parameters

customerId

required

integer

Request Body schema: application/json
required

provider required	string Enum: "NONE" "STRIPE" "PAYTER" "ADYEN" "FREEDOM_PAY" "GENERIC"
underlyingPaymentProvider	string To identify the real payment provider when provider is GENERIC
defaultCard	string Default: false Whether it's the default card
cardBrand	string <= 30 characters Allow retailer to specify card brand, the length of this field should be less than or equal to 30. if this value is unknown or not specified, empty string will be included in webhooks
cardToken required	string Card token to charge customer
cardId required	string Unique id of the card. as apposed to cardToken, it should be the same (for a physical card) upon every tokenization

Responses

Response Schema: application/json

id

required

integer

Id of the card

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"provider": "NONE",
"underlyingPaymentProvider": "string",
"defaultCard": false,
"cardBrand": "string",
"cardToken": "string",
"cardId": "string"
}

Response samples

201
422

Content type

application/json

{"id": 0
}

Delete a card by id

path Parameters

customerId required	integer
cardId required	integer

Responses

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

422

Content type

application/json

{"message": "Invalid request body",
"type": "E_INVALID_BODY",
"errors": [{"error": "\"email\" is required",
"rule": "any.required",
"field": "\"email\""
}
]
}

Mark a card as default

path Parameters

customerId required	integer
cardId required	integer

Responses

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

422

Content type

application/json

{"message": "Invalid request body",
"type": "E_INVALID_BODY",
"errors": [{"error": "\"email\" is required",
"rule": "any.required",
"field": "\"email\""
}
]
}

Admin API - sessions

List sessions

query Parameters

minCreatedAt	string <date-time> Example: minCreatedAt=2024-09-22T00:00:00.000Z
maxCreatedAt	string <date-time> Example: maxCreatedAt=2024-09-29T00:00:00.000Z
minUpdatedAt	string <date-time> Example: minUpdatedAt=2024-09-23T00:00:00.000Z
maxUpdatedAt	string <date-time> Example: maxUpdatedAt=2024-09-30T00:00:00.000Z
count	integer <= 200 Default: 20 Number of results
after	string Id or base64 encoded cursor(id + sortKey)
before	string Id or base64 encoded cursor(id + sortKey)
orderBy	string Enum: "id" "code" "storeId" "visitors" "groupSize" "expiresAt" "customerId" "storeId" "codeLastSuccesfullyScannedAt" "customerLastEnteredAt" "createdAt" "updatedAt" The sort key, sorting by id by default
direction	string Enum: "asc" "desc" Direction of sorting
id	integer
code	string
sessionToken	string
storeId	integer
customerId	integer
status	Array of strings Items Enum: "active" "declined" "validated" "checkout_performed"
minVisitors	integer >= 0
maxVisitors	integer >= 1
minGroupSize	integer >= 0
maxGroupSize	integer >= 1
minExpiresAt	string <date-time>
maxExpiresAt	string <date-time>
minCodeLastSuccesfullyScannedAt	string <date-time>
maxCodeLastSuccesfullyScannedAt	string <date-time>
minCustomerLastEnteredAt	string <date-time>
maxCustomerLastEnteredAt	string <date-time>

Responses

Response Schema: application/json

required

Array of objects (SessionListItemDto)

Array

createdAt

required

string <date-time>

ISO formatted date representing when the entity was created

updatedAt

required

string <date-time>

ISO formatted date representing when the entity was last updated

code

required

string

An entry code that can rendered as QR and used to enter AiFi store

codeFirstSuccesfullyScannedAt

required

string or null <date-time>

ISO formatted date, the first time when the QR get scanned successfully

codeLastSuccesfullyScannedAt

required

string or null <date-time>

ISO formatted date, the last time when the QR get scanned successfully

customerFirstEnteredAt

required

string or null <date-time>

ISO formatted time, when the first shopper enter the store

customerLastEnteredAt

required

string or null <date-time>

ISO formatted time, when the last shopper enter the store

customerFirstExitedAt

required

string or null <date-time>

ISO formatted time, when the first shopper exit the store

customerLastExitedAt

required

string or null <date-time>

ISO formatted time, when the last shopper exit the store

customerPaymentInstrumentId

required

integer or null

Payment instrument id

customerSatisfaction

required

integer or null [ 0 .. 100 ]

Satisfaction from the shopping session submitted by the customer. Can be null if not submitted or when customer wished to not ask him.

customerSatisfactionSubmitted

required

boolean

Default: false

Whether satisfaction has been submitted

groupSize

required

integer

Expected group size associated with the shopping session

visitors

required

integer

Actual group size associated with the shopping session

locationId

required

string or null

priority

required

integer [ -10 .. 10 ]

Default: 0

Customer priority. default to 0, which means any regular customer. customers with higher priority will have their shopping sessions prioritized during processing, the lower priority is opposite.

sessionToken

required

string

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.

sessionId

required

string

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.

referencedSessionId

required

string or null

Default: null

Referenced session token, that points to the source session

status

required

string

Enum: "active" "declined" "validated" "checkout_performed"

storeId

required

integer or null

AiFi store id

storeIdScannableAt

required

integer or null

the id of store which the QrCode of test case can be valided. It can be scanned at any store if the value is null.

suspectedFraud

required

boolean

Default: false

Indicate whether the shopping session is suspected fraud

metadata

required

object

Represents an arbitrary object. Note that the events key is reserved by AiFi for ThirdParty and Handoff Events. The value provided in the metadata field will completely overwrite the existing object. If your integration depends on the events key in the metadata, ensure it is preserved to avoid accidental deletion. To add new keys to the existing metadata object:

Retrieve the current metadata using the Get Session List endpoint.
Merge the retrieved metadata with the new keys you wish to add.
Submit the updated object in the metadata field.

Be cautious, as replacing the metadata value without preserving necessary keys may lead to unintended data loss.

expiresAt

required

string <date-time>

ISO formatted date at which this entry code will expire

id

required

string <integer>

customerId

required

string <integer>

object (SessionListItemCustomerDto)

externalId required	string or null Id of the customer in external system
role required	string Enum: "customer" "employee" "tester" "untracked" "unknown" Role of the customer
metadata required	object or null This object can contain custom metadata information
priority required	integer [ -10 .. 10 ] Default: 0 Customer priority. default to 0, which means any regular customer. customers with higher priority will have their shopping sessions prioritized during processing, the lower priority is opposite.
email required	string <email>
firstName required	string or null
lastName required	string or null
phone required	string or null
id required	string <integer>

object (SessionListItemStoreDto)

aifiUniqueStoreId required	string Unique identifier across all AiFi stores. it will only be filled in by TechOPS/deployment engineers
status required	string Enum: "OPEN" "CLOSED" "CLOSED_FOR_MAINTENANCE" Status of a store, indicates whether the store is open to customers
deploymentStatus required	string Enum: "LIVE" "TESTING" "DEPLOYMENT" "DECOMMISSIONED" Deployment status of a store, indicated whether the store is live, under deployment or testing
addressLine1 required	string Address of a store, including details such as: street name, building number, floor, etc
addressCity required	string City of the address
addressRegion required	string The region of the address, such as the province, state, or district
addressCountry required	string Enum: "AC" "AD" "AE" "AF" "AG" "AI" "AL" "AM" "AN" "AO" "AR" "AT" "AU" "AW" "AX" "AZ" "BA" "BB" "BD" "BE" "BF" "BG" "BH" "BI" "BJ" "BL" "BM" "BN" "BO" "BQ" "BR" "BS" "BT" "BV" "BW" "BY" "BZ" "CA" "CC" "CD" "CF" "CG" "CH" "CI" "CK" "CL" "CM" "CN" "CO" "CR" "CU" "CV" "CW" "CX" "CY" "CZ" "DE" "DJ" "DK" "DM" "DO" "DZ" "EC" "EE" "EG" "EH" "ER" "ES" "ET" "FI" "FJ" "FK" "FO" "FR" "GA" "GB" "GD" "GE" "GF" "GG" "GH" "GI" "GL" "GM" "GN" "GP" "GQ" "GR" "GS" "GT" "GW" "GY" "HK" "HM" "HN" "HR" "HT" "HU" "ID" "IE" "IL" "IM" "IN" "IO" "IQ" "IR" "IS" "IT" "JE" "JM" "JO" "JP" "KE" "KG" "KH" "KI" "KM" "KN" "KP" "KR" "KW" "KY" "KZ" "LA" "LB" "LC" "LI" "LK" "LR" "LS" "LT" "LU" "LV" "LY" "MA" "MC" "MD" "ME" "MF" "MG" "MK" "ML" "MM" "MN" "MO" "MQ" "MR" "MS" "MT" "MU" "MV" "MW" "MX" "MY" "MZ" "NA" "NC" "NE" "NF" "NG" "NI" "NL" "NO" "NP" "NR" "NU" "NZ" "OM" "PA" "PE" "PF" "PG" "PH" "PK" "PL" "PM" "PN" "PS" "PT" "PY" "QA" "RE" "RO" "RS" "RU" "RW" "SA" "SB" "SC" "SD" "SE" "SG" "SH" "SI" "SJ" "SK" "SL" "SM" "SN" "SO" "SR" "SS" "ST" "SV" "SX" "SY" "SZ" "TA" "TC" "TD" "TF" "TG" "TH" "TJ" "TK" "TL" "TM" "TN" "TO" "TR" "TT" "TV" "TW" "TZ" "UA" "UG" "UM" "US" "UY" "UZ" "VA" "VC" "VE" "VG" "VN" "VU" "WF" "WS" "XK" "YE" "YT" "ZA" "ZM" "ZW" Country code of the address. it's a ISO_3166-1_alpha-2 code
addressPostalCode required	string Postal code of the address.
thirdPartyId required	string or null Deprecated External id of a store, retailers can specify their own id for the store via this field We would send this field in the payload of checkout webhook with key storeExternalId For example, we will include "storeExternalId": "store0001" in the payload of checkout webhook if retailer specifies this field with "store0001"
storeUrl required	string or null On-premise api url of a store
maxPeople required	integer How many people can be at the store at the same time
storeConfigId required	integer or null Id of store config
name required	string or null A combination of retailer name, city and country mainly used in aifi internally, it's not very friendly to customer, so the field displayableName will be used as store name in SMS notification
id required	string <integer>
employeeInside required	boolean Indicate whether the store has employee inside

object (CursorBasedPaginationDto)

object

Query parameter to fetch previous page

count required	integer Number of results
before required	string Id or base64 encoded cursor(id + sortKey)
direction required	string Enum: "asc" "desc" Direction of sorting

object

Query parameter to fetch next page

count required	integer Number of results
after required	string Id or base64 encoded cursor(id + sortKey)
direction required	string Enum: "asc" "desc" Direction of sorting

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

{"data": [{"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"code": "c69bb289-1190-4156-b9f6-bfb7f61e85db",
"codeFirstSuccesfullyScannedAt": "2019-08-24T14:15:22Z",
"codeLastSuccesfullyScannedAt": "2019-08-24T14:15:22Z",
"customerFirstEnteredAt": "2019-08-24T14:15:22Z",
"customerLastEnteredAt": "2019-08-24T14:15:22Z",
"customerFirstExitedAt": "2019-08-24T14:15:22Z",
"customerLastExitedAt": "2019-08-24T14:15:22Z",
"customerPaymentInstrumentId": 0,
"customerSatisfaction": 95,
"customerSatisfactionSubmitted": false,
"groupSize": 0,
"visitors": 0,
"locationId": "string",
"priority": 0,
"sessionToken": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"sessionId": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"referencedSessionId": null,
"status": "active",
"storeId": 0,
"storeIdScannableAt": 0,
"suspectedFraud": false,
"metadata": {"events": [{"eventId": "6bdbfb2d-65b2-491c-bc97-c0ac73338476",
"metadata": {"key": "value"
}
}
],
"exampleKey": "exampleValue"
},
"expiresAt": "2019-08-24T14:15:22Z",
"id": "string",
"customerId": "string",
"customer": {"externalId": "string",
"role": "customer",
"metadata": {"arbitraryKey": "arbitraryValue"
},
"priority": 0,
"email": "user@example.com",
"firstName": "string",
"lastName": "string",
"phone": "string",
"id": "string"
},
"store": {"aifiUniqueStoreId": "string",
"status": "OPEN",
"deploymentStatus": "LIVE",
"addressLine1": "string",
"addressCity": "string",
"addressRegion": "string",
"addressCountry": "AC",
"addressPostalCode": "string",
"thirdPartyId": "string",
"storeUrl": "string",
"maxPeople": 0,
"storeConfigId": 0,
"name": "string",
"id": "string",
"employeeInside": true
}
}
],
"pagination": {"previous": {"count": 0,
"before": "string",
"direction": "asc"
},
"next": {"count": 0,
"after": "string",
"direction": "asc"
}
}
}

Update customer shopping session

As of so far, the endpoint only be used to report fraudulent behavior by mark shopping session suspectedFraud=true

path Parameters

sessionId

required

string

Example: d3a00526-1864-4f6e-bb2d-46e3ab7fa780

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.

Request Body schema: application/json
required

suspectedFraud

boolean

Indicate whether the shopping session is suspected fraud, only true is allowed

metadata

object

Represents an arbitrary object. Note that the events key is reserved by AiFi for ThirdParty and Handoff Events. The value provided in the metadata field will completely overwrite the existing object. If your integration depends on the events key in the metadata, ensure it is preserved to avoid accidental deletion. To add new keys to the existing metadata object:

Retrieve the current metadata using the Get Session List endpoint.
Merge the retrieved metadata with the new keys you wish to add.
Submit the updated object in the metadata field.

Be cautious, as replacing the metadata value without preserving necessary keys may lead to unintended data loss.

Responses

Response Schema: application/json

createdAt

required

string <date-time>

ISO formatted date representing when the entity was created

updatedAt

required

string <date-time>

ISO formatted date representing when the entity was last updated

id

required

integer

customerId

required

integer

AiFi customer id

code

required

string

An entry code that can rendered as QR and used to enter AiFi store

codeFirstSuccesfullyScannedAt

required

string or null <date-time>

ISO formatted date, the first time when the QR get scanned successfully

codeLastSuccesfullyScannedAt

required

string or null <date-time>

ISO formatted date, the last time when the QR get scanned successfully

customerFirstEnteredAt

required

string or null <date-time>

ISO formatted time, when the first shopper enter the store

customerLastEnteredAt

required

string or null <date-time>

ISO formatted time, when the last shopper enter the store

customerFirstExitedAt

required

string or null <date-time>

ISO formatted time, when the first shopper exit the store

customerLastExitedAt

required

string or null <date-time>

ISO formatted time, when the last shopper exit the store

customerPaymentInstrumentId

required

integer or null

Payment instrument id

customerSatisfaction

required

integer or null [ 0 .. 100 ]

Satisfaction from the shopping session submitted by the customer. Can be null if not submitted or when customer wished to not ask him.

customerSatisfactionSubmitted

required

boolean

Default: false

Whether satisfaction has been submitted

groupSize

required

integer

Expected group size associated with the shopping session

visitors

required

integer

Actual group size associated with the shopping session

locationId

required

string or null

priority

required

integer [ -10 .. 10 ]

Default: 0

Customer priority. default to 0, which means any regular customer. customers with higher priority will have their shopping sessions prioritized during processing, the lower priority is opposite.

sessionToken

required

string

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.

sessionId

required

string

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.

referencedSessionId

required

string or null

Default: null

Referenced session token, that points to the source session

status

required

string

Enum: "active" "declined" "validated" "checkout_performed"

storeId

required

integer or null

AiFi store id

storeIdScannableAt

required

integer or null

the id of store which the QrCode of test case can be valided. It can be scanned at any store if the value is null.

suspectedFraud

required

boolean

Default: false

Indicate whether the shopping session is suspected fraud

metadata

required

object

Represents an arbitrary object. Note that the events key is reserved by AiFi for ThirdParty and Handoff Events. The value provided in the metadata field will completely overwrite the existing object. If your integration depends on the events key in the metadata, ensure it is preserved to avoid accidental deletion. To add new keys to the existing metadata object:

Retrieve the current metadata using the Get Session List endpoint.
Merge the retrieved metadata with the new keys you wish to add.
Submit the updated object in the metadata field.

Be cautious, as replacing the metadata value without preserving necessary keys may lead to unintended data loss.

expiresAt

required

string <date-time>

ISO formatted date at which this entry code will expire

object (CustomerResponseDto)

id required	integer
externalId required	string or null Id of the customer in external system
role required	string Enum: "customer" "employee" "tester" "untracked" "unknown" Role of the customer
metadata required	object or null This object can contain custom metadata information
priority required	integer [ -10 .. 10 ] Default: 0 Customer priority. default to 0, which means any regular customer. customers with higher priority will have their shopping sessions prioritized during processing, the lower priority is opposite.
email required	string <email>
firstName required	string or null
lastName required	string or null
phone required	string or null

object (SessionListItemStoreDto)

aifiUniqueStoreId required	string Unique identifier across all AiFi stores. it will only be filled in by TechOPS/deployment engineers
status required	string Enum: "OPEN" "CLOSED" "CLOSED_FOR_MAINTENANCE" Status of a store, indicates whether the store is open to customers
deploymentStatus required	string Enum: "LIVE" "TESTING" "DEPLOYMENT" "DECOMMISSIONED" Deployment status of a store, indicated whether the store is live, under deployment or testing
addressLine1 required	string Address of a store, including details such as: street name, building number, floor, etc
addressCity required	string City of the address
addressRegion required	string The region of the address, such as the province, state, or district
addressCountry required	string Enum: "AC" "AD" "AE" "AF" "AG" "AI" "AL" "AM" "AN" "AO" "AR" "AT" "AU" "AW" "AX" "AZ" "BA" "BB" "BD" "BE" "BF" "BG" "BH" "BI" "BJ" "BL" "BM" "BN" "BO" "BQ" "BR" "BS" "BT" "BV" "BW" "BY" "BZ" "CA" "CC" "CD" "CF" "CG" "CH" "CI" "CK" "CL" "CM" "CN" "CO" "CR" "CU" "CV" "CW" "CX" "CY" "CZ" "DE" "DJ" "DK" "DM" "DO" "DZ" "EC" "EE" "EG" "EH" "ER" "ES" "ET" "FI" "FJ" "FK" "FO" "FR" "GA" "GB" "GD" "GE" "GF" "GG" "GH" "GI" "GL" "GM" "GN" "GP" "GQ" "GR" "GS" "GT" "GW" "GY" "HK" "HM" "HN" "HR" "HT" "HU" "ID" "IE" "IL" "IM" "IN" "IO" "IQ" "IR" "IS" "IT" "JE" "JM" "JO" "JP" "KE" "KG" "KH" "KI" "KM" "KN" "KP" "KR" "KW" "KY" "KZ" "LA" "LB" "LC" "LI" "LK" "LR" "LS" "LT" "LU" "LV" "LY" "MA" "MC" "MD" "ME" "MF" "MG" "MK" "ML" "MM" "MN" "MO" "MQ" "MR" "MS" "MT" "MU" "MV" "MW" "MX" "MY" "MZ" "NA" "NC" "NE" "NF" "NG" "NI" "NL" "NO" "NP" "NR" "NU" "NZ" "OM" "PA" "PE" "PF" "PG" "PH" "PK" "PL" "PM" "PN" "PS" "PT" "PY" "QA" "RE" "RO" "RS" "RU" "RW" "SA" "SB" "SC" "SD" "SE" "SG" "SH" "SI" "SJ" "SK" "SL" "SM" "SN" "SO" "SR" "SS" "ST" "SV" "SX" "SY" "SZ" "TA" "TC" "TD" "TF" "TG" "TH" "TJ" "TK" "TL" "TM" "TN" "TO" "TR" "TT" "TV" "TW" "TZ" "UA" "UG" "UM" "US" "UY" "UZ" "VA" "VC" "VE" "VG" "VN" "VU" "WF" "WS" "XK" "YE" "YT" "ZA" "ZM" "ZW" Country code of the address. it's a ISO_3166-1_alpha-2 code
addressPostalCode required	string Postal code of the address.
thirdPartyId required	string or null Deprecated External id of a store, retailers can specify their own id for the store via this field We would send this field in the payload of checkout webhook with key storeExternalId For example, we will include "storeExternalId": "store0001" in the payload of checkout webhook if retailer specifies this field with "store0001"
storeUrl required	string or null On-premise api url of a store
maxPeople required	integer How many people can be at the store at the same time
storeConfigId required	integer or null Id of store config
name required	string or null A combination of retailer name, city and country mainly used in aifi internally, it's not very friendly to customer, so the field displayableName will be used as store name in SMS notification
id required	string <integer>
employeeInside required	boolean Indicate whether the store has employee inside

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"suspectedFraud": true,
"metadata": {"events": [{"eventId": "6bdbfb2d-65b2-491c-bc97-c0ac73338476",
"metadata": {"key": "value"
}
}
],
"exampleKey": "exampleValue"
}
}

Response samples

200
422

Content type

application/json

{"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"id": 0,
"customerId": 0,
"code": "c69bb289-1190-4156-b9f6-bfb7f61e85db",
"codeFirstSuccesfullyScannedAt": "2019-08-24T14:15:22Z",
"codeLastSuccesfullyScannedAt": "2019-08-24T14:15:22Z",
"customerFirstEnteredAt": "2019-08-24T14:15:22Z",
"customerLastEnteredAt": "2019-08-24T14:15:22Z",
"customerFirstExitedAt": "2019-08-24T14:15:22Z",
"customerLastExitedAt": "2019-08-24T14:15:22Z",
"customerPaymentInstrumentId": 0,
"customerSatisfaction": 95,
"customerSatisfactionSubmitted": false,
"groupSize": 0,
"visitors": 0,
"locationId": "string",
"priority": 0,
"sessionToken": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"sessionId": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"referencedSessionId": null,
"status": "active",
"storeId": 0,
"storeIdScannableAt": 0,
"suspectedFraud": false,
"metadata": {"events": [{"eventId": "6bdbfb2d-65b2-491c-bc97-c0ac73338476",
"metadata": {"key": "value"
}
}
],
"exampleKey": "exampleValue"
},
"expiresAt": "2019-08-24T14:15:22Z",
"customer": {"id": 0,
"externalId": "string",
"role": "customer",
"metadata": {"arbitraryKey": "arbitraryValue"
},
"priority": 0,
"email": "user@example.com",
"firstName": "string",
"lastName": "string",
"phone": "string"
},
"store": {"aifiUniqueStoreId": "string",
"status": "OPEN",
"deploymentStatus": "LIVE",
"addressLine1": "string",
"addressCity": "string",
"addressRegion": "string",
"addressCountry": "AC",
"addressPostalCode": "string",
"thirdPartyId": "string",
"storeUrl": "string",
"maxPeople": 0,
"storeConfigId": 0,
"name": "string",
"id": "string",
"employeeInside": true
}
}

Manual checkout

Causes cart, of a specified sessionId, to be cleared. Effectively starts new transaction for given shopping session.

path Parameters

sessionId

required

string

Example: d3a00526-1864-4f6e-bb2d-46e3ab7fa780

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.

Request Body schema: application/json
required

transactionId

integer

ID of transaction for specified shopping session. Should not be specified by retailer. If not provided will be evaluated automatically

required

object (CartDto)

required

Array of objects (CartItemDto)

Array

productId required	integer >= 1 id of a product in AiFi system
quantity required	integer >= 0
status	string Default: "unassisted" Enum: "correct" "add" "remove" "unassisted" "walkout"

Responses

Response Schema: application/json

orderId

required

integer

storeId

required

integer

AiFi store id

required

object (StoreIdsDto)

oasisApiStoreId required	integer Store identifier that is only internal to cloud-api
aifiUniqueStoreId required	string or null Unique identifier across all AiFi stores. it will only be filled in by TechOPS/deployment engineers

totalPrice

required

string <float>

A decimal representation of the total price of this order

paymentTransactionId

string or null

Unique identifier of this payment transaction

paymentFailed

boolean

Informs whether payment failed, or was successfully collected

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"transactionId": 0,
"cart": {"products": [{"productId": 1,
"quantity": 0,
"status": "correct"
}
]
}
}

Response samples

200
422

Content type

application/json

{"orderId": 1234,
"storeId": 0,
"store": {"oasisApiStoreId": 0,
"aifiUniqueStoreId": "string"
},
"totalPrice": "1.50",
"paymentTransactionId": "string",
"paymentFailed": true
}

Get live cart

path Parameters

sessionId

required

string

Example: d3a00526-1864-4f6e-bb2d-46e3ab7fa780

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.

Responses

Response Schema: application/json

required

Array of objects (LiveCartProductDto)

Array

id required	string <integer> Id of the product
name required	string
price required	string or null <float> Unit price for single item, depending on configuration it may either contain the tax (suitable e.g. for integrations in EU) or not (suitable e.g. for integrations in the US)
barcode required	string Default barcode of default variant for this product
thumbnail required	string or null URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.
externalId required	string or null Client defined product identifier
quantity required	integer >= 0

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

{"products": [{"id": "string",
"name": "string",
"price": "string",
"barcode": "string",
"thumbnail": "string",
"externalId": "string",
"quantity": 0
}
]
}

Update live cart

path Parameters

sessionId

required

string

Example: d3a00526-1864-4f6e-bb2d-46e3ab7fa780

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.

Request Body schema: application/json
required

required

object (UpdateCartDto)

required

Array of objects (UpdateCartItemDto)

Array

productId required	integer >= 1 id of a product in AiFi system
quantity required	integer >= 0
status required	string Enum: "correct" "add" "remove"

Responses

Response Schema: application/json

required

Array of objects (UpdateCartItemResponseDto)

Array

productId required	integer >= 1 id of a product in AiFi system
quantity required	integer >= 0

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"cart": {"products": [{"productId": 1,
"quantity": 0,
"status": "correct"
}
]
}
}

Response samples

200
422

Content type

application/json

{"products": [{"productId": 1,
"quantity": 0
}
]
}

Add pre-authorization to session

path Parameters

sessionId

required

string

Example: d3a00526-1864-4f6e-bb2d-46e3ab7fa780

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.

Request Body schema: application/json
required

amount required	integer >= 1 Pre-auth amount presented as minor units
paymentInstrumentToken required	string
externalPreAuthId required	string

Responses

Response Schema: application/json

paymentInstrumentToken required	string
externalPreAuthId required	string
id required	integer Id of the pre-authorization
sessionId required	string A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"amount": 1,
"paymentInstrumentToken": "string",
"externalPreAuthId": "string"
}

Response samples

201
422

Content type

application/json

{"paymentInstrumentToken": "string",
"externalPreAuthId": "string",
"id": 0,
"sessionId": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780"
}

Put scanned products to the session

path Parameters

sessionId

required

string

Example: d3a00526-1864-4f6e-bb2d-46e3ab7fa780

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.

Request Body schema: application/json
required

required

Array of objects (ProductDto)

Array

productReference required	string
quantity required	integer
referenceType	string Default: "barcode" Enum: "barcode" "id" "externalId"

Responses

Response Schema: application/json

required

Array of objects (ProductDto)

Array

productReference required	string
quantity required	integer
referenceType	string Default: "barcode" Enum: "barcode" "id" "externalId"

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"products": [{"productReference": "1234567890128",
"quantity": 1,
"referenceType": "barcode"
}
]
}

Response samples

200
422

Content type

application/json

{"products": [{"productReference": "1234567890128",
"quantity": 1,
"referenceType": "barcode"
}
]
}

Get fraud scoring for the session

path Parameters

sessionId

required

string

Example: d3a00526-1864-4f6e-bb2d-46e3ab7fa780

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.

Responses

Response Schema: application/json

fraudScore

required

number [ 0 .. 1 ]

A score between 0 and 1 indicating the likelihood of fraudulent activity. Higher values suggest greater risk.

flaggedAsFraudulent

required

boolean

Indicates whether the transaction or entity was flagged as potentially fraudulent based on the fraud score.

Array of objects (FraudScoreMissedItemDto)

Array

categoryId required	string Product category suspected to be missing from scanned cart
quantity required	integer Estimated quantity not scanned or not paid for
confidence required	number [ 0 .. 1 ] [0-1] estimated likelihood that the item is missing from the scanned cart
binId required	string Unique identifier of the most likely bin, where expected item is located

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

{"fraudScore": "0.86",
"flaggedAsFraudulent": true,
"missedItems": [{"categoryId": "1",
"quantity": 1,
"confidence": "0.86",
"binId": "uuid1"
}
]
}

Admin API - contests

Get list of contested orders

query Parameters

minCreatedAt	string <date-time> Example: minCreatedAt=2024-09-22T00:00:00.000Z
maxCreatedAt	string <date-time> Example: maxCreatedAt=2024-09-29T00:00:00.000Z
minUpdatedAt	string <date-time> Example: minUpdatedAt=2024-09-23T00:00:00.000Z
maxUpdatedAt	string <date-time> Example: maxUpdatedAt=2024-09-30T00:00:00.000Z
status	string Enum: "contested" "reviewed"
orderId	integer
storeId	integer
startTime	string <date-time>
endTime	string <date-time>
page	integer Default: 0
pageSize	integer Default: 10

Responses

Response Schema: application/json

required

Array of objects (ContestedListItemDto)

List of contested orders match given criteria

Array

createdAt

required

string <date-time>

ISO formatted date representing when the entity was created

updatedAt

required

string <date-time>

ISO formatted date representing when the entity was last updated

deletedAt

required

string or null <date-time>

ISO formatted date representing when the entity was soft deleted

id

required

integer

Id of contested order

orderId

required

string <integer>

Id of original order

orderVersion

required

integer

Version of original order

sessionId

required

string or null

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.

message

required

string

Message provided by a customer, may be empty

fromOperator

required

boolean

Whether created by operator

status

required

string

Enum: "contested" "reviewed" "original"

contestedTotalPrice

required

string

Total price provided by a customer, may be empty. the service will calculate it if it is missing

reviewedTotalPrice

required

string or null

Total price confirmed during review, it's null if the status is not reviewed

originalTotalPrice

required

string

Total price of original order

required

object (OrderShallowDto)

createdAt required	string <date-time> ISO formatted date representing when the entity was created
updatedAt required	string <date-time> ISO formatted date representing when the entity was last updated
id required	integer
version required	integer Default is 1, a newer version of order will be created when an order get contested
isLatest required	integer Whether it is the latest version
customerId required	string <integer> AiFi customer id, formatted as string
storeId required	integer The id of the store where the shopping happens
status required	string Enum: "draft" "paid" "unpaid" "completed_so_far" "paymentProcessing" "contested" "reviewed"
transactionId required	number or null Id of transaction for specified shopping session
customerShoppingSessionId required	number or null Id of shopping session
externalId required	string or null Id of this order in external system
externalStatus required	string Enum: "ok" "failedObtainingPrice" "failedSendingWebhook"
subtotalPrice required	string <float> A decimal representation of the subtotal price of this order
totalPrice required	string <float> A decimal representation of the total price of this order
totalTax required	string <float> A decimal representation of the total tax of this order
paidAt required	string or null <date-time> ISO formatted date of order payment
notificationSentAt required	string or null <date-time> ISO formatted date of order notification sent to the app
extraText required	string Deprecated Default: "" Deprecated: Use vendorMetadata with EXTRA_TEXT type instead. Extra text shows on the receipt page. This field will be removed in a future version.
completedAt required	string or null <date-time> ISO formatted date of order completion
draftCreatedAt required	string or null <date-time> ISO formatted date of draft order creation

required

object

Offset based pagination

object

Query parameter to fetch previous page

offset required	integer Pagination offset
count required	integer Number of results

object

Query parameter to fetch next page

offset required	integer Pagination offset
count required	integer Number of results

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

{"contestedOrders": [{"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"deletedAt": "2019-08-24T14:15:22Z",
"id": 0,
"orderId": "string",
"orderVersion": 0,
"sessionId": "string",
"message": "string",
"fromOperator": true,
"status": "contested",
"contestedTotalPrice": "120.00",
"reviewedTotalPrice": "120.00",
"originalTotalPrice": "123.45",
"order": {"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"id": 0,
"version": 0,
"isLatest": 0,
"customerId": "11",
"storeId": 1,
"status": "draft",
"transactionId": 0,
"customerShoppingSessionId": 0,
"externalId": "string",
"externalStatus": "ok",
"subtotalPrice": "1.80",
"totalPrice": "2.15",
"totalTax": "0.35",
"paidAt": "2019-08-24T14:15:22Z",
"notificationSentAt": "2019-08-24T14:15:22Z",
"extraText": "",
"completedAt": "2019-08-24T14:15:22Z",
"draftCreatedAt": "2019-08-24T14:15:22Z"
}
}
],
"pagination": {"previous": {"offset": 0,
"count": 0
},
"next": {"offset": 0,
"count": 0
}
}
}

Create a contest for order

Request Body schema: application/json
required

orderId

required

integer

Id of the order is being contested

message

string

Default: ""

Message provided by a customer, may be empty

required

Array of objects (CreateContestOrderItemDto)

Line items need to be contested

Array

id required	integer Deprecated Same as productId, please use productId
productId required	integer Id of a product
contestedQuantity required	integer The quantity that the customer believes would be correct

Responses

Response Schema: application/json

Array

createdAt required	string <date-time> ISO formatted date representing when the entity was created
id required	integer Id of contest item
productId required	integer Id of product
rin required	string <integer> Deprecated Use productId instead
contestedOrderId required	integer Id of the contested order
originalQuantity required	integer Quantity of the product in original order
contestedQuantity required	integer The quantity that the customer believes would be correct

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"orderId": 0,
"message": "",
"items": [{"id": 0,
"productId": 0,
"contestedQuantity": 0
}
]
}

Response samples

201
422

Content type

application/json

[{"createdAt": "2019-08-24T14:15:22Z",
"id": 0,
"productId": 0,
"rin": "string",
"contestedOrderId": 0,
"originalQuantity": 0,
"contestedQuantity": 0
}
]

Get contested order by original order id

path Parameters

orderId

required

integer

Responses

Response Schema: application/json

createdAt

required

string <date-time>

ISO formatted date representing when the entity was created

updatedAt

required

string <date-time>

ISO formatted date representing when the entity was last updated

deletedAt

required

string or null <date-time>

ISO formatted date representing when the entity was soft deleted

id

required

integer

Id of contested order

orderId

required

string <integer>

Id of original order

orderVersion

required

integer

Version of original order

sessionId

required

string or null

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.

message

required

string

Message provided by a customer, may be empty

fromOperator

required

boolean

Whether created by operator

status

required

string

Enum: "contested" "reviewed" "original"

contestedTotalPrice

required

string

Total price provided by a customer, may be empty. the service will calculate it if it is missing

reviewedTotalPrice

required

string or null

Total price confirmed during review, it's null if the status is not reviewed

originalTotalPrice

required

string

Total price of original order

required

Array of objects (ContestedItemDto)

Line items get contested

Array

id

required

integer

Deprecated

Use productSnapshot.productId

productId

required

integer

Deprecated

Use 'productSnapshot.productId'

name

required

string

Deprecated

Use 'productSnapshot.name'

price

required

string <float>

Deprecated

Use 'productSnapshot.price'

thumbnail

required

string or null

Deprecated

Use 'productSnapshot.thumbnail'

required

object or null

name required	string
price required	string or null <float> Unit price for single item, depending on configuration it may either contain the tax (suitable e.g. for integrations in EU) or not (suitable e.g. for integrations in the US)
barcode required	string Default barcode of default variant for this product
category required	string or null Deprecated
thumbnail required	string or null URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.
weight required	number or null Weight of a default variant
sku required	string or null Deprecated
externalId required	string or null Client defined product identifier
taxCode required	string or null Avalara tax code, available ig avalara integration is enabled
id required	integer
productId required	integer id of the product
createdAt required	string <date-time> ISO formatted date
updatedAt required	string <date-time> ISO formatted date

originalQuantity

required

integer

Quantity of the product in original order

contestedQuantity

required

integer

The quantity that the customer believes would be correct

reviewedQuantity

integer

Quantity of the product specified during review, available only if the contest status is reviewed

required

object

The transaction related to the contested order

paymentTransactionId required	string or null The id of the transaction. Non-empty only if the order is past the "draft" stage
refunded required	boolean Whether the transaction was refunded. Only meaningful if paymentTransactionId is non-empty
tryRefundTimes required	integer The number of times a refund was attempted for this transaction
paymentFailed required	boolean Did the payment fail. Only meaningful if paymentTransactionId is non-empty

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

{"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"deletedAt": "2019-08-24T14:15:22Z",
"id": 0,
"orderId": "string",
"orderVersion": 0,
"sessionId": "string",
"message": "string",
"fromOperator": true,
"status": "contested",
"contestedTotalPrice": "120.00",
"reviewedTotalPrice": "120.00",
"originalTotalPrice": "123.45",
"items": [{"id": 0,
"productId": 0,
"name": "string",
"price": "string",
"thumbnail": "string",
"productSnapshot": {"name": "string",
"price": "string",
"barcode": "string",
"category": "string",
"thumbnail": "string",
"weight": 0,
"sku": "string",
"externalId": "string",
"taxCode": "string",
"id": 0,
"productId": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
},
"originalQuantity": 0,
"contestedQuantity": 0,
"reviewedQuantity": 0
}
],
"transaction": {"paymentTransactionId": "string",
"refunded": true,
"tryRefundTimes": 0,
"paymentFailed": true
}
}

Update contested order

path Parameters

orderId

required

integer

Request Body schema: application/json
required

reviewedTotalPrice

required

number

Default: null

It will calculate the reviewedTotalPrice based on contested items if there is no reviewedTotalPrice in request.

By default, reviewedTotalPrice takes precedence over cart mutator totalPrice. Cart Mutator implementation should respect and properly handle adjusted reviewedTotalPrice.

required

Array of objects (UpdateContestOrderItemDto)

Array

id required	integer Deprecated Same as productId, please use productId
productId required	integer Id of a product
reviewedQuantity required	integer Quantity of the product specified during review

Responses

Response Schema: application/json

createdAt

required

string <date-time>

ISO formatted date representing when the entity was created

updatedAt

required

string <date-time>

ISO formatted date representing when the entity was last updated

deletedAt

required

string or null <date-time>

ISO formatted date representing when the entity was soft deleted

id

required

integer

Id of contested order

orderId

required

string <integer>

Id of original order

orderVersion

required

integer

Version of original order

sessionId

required

string or null

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.

message

required

string

Message provided by a customer, may be empty

fromOperator

required

boolean

Whether created by operator

status

required

string

Enum: "contested" "reviewed" "original"

contestedTotalPrice

required

string

Total price provided by a customer, may be empty. the service will calculate it if it is missing

reviewedTotalPrice

required

string or null

Total price confirmed during review, it's null if the status is not reviewed

originalTotalPrice

required

string

Total price of original order

required

Array of objects (ContestedItemDto)

Line items get contested

Array

id

required

integer

Deprecated

Use productSnapshot.productId

productId

required

integer

Deprecated

Use 'productSnapshot.productId'

name

required

string

Deprecated

Use 'productSnapshot.name'

price

required

string <float>

Deprecated

Use 'productSnapshot.price'

thumbnail

required

string or null

Deprecated

Use 'productSnapshot.thumbnail'

required

object or null

name required	string
price required	string or null <float> Unit price for single item, depending on configuration it may either contain the tax (suitable e.g. for integrations in EU) or not (suitable e.g. for integrations in the US)
barcode required	string Default barcode of default variant for this product
category required	string or null Deprecated
thumbnail required	string or null URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.
weight required	number or null Weight of a default variant
sku required	string or null Deprecated
externalId required	string or null Client defined product identifier
taxCode required	string or null Avalara tax code, available ig avalara integration is enabled
id required	integer
productId required	integer id of the product
createdAt required	string <date-time> ISO formatted date
updatedAt required	string <date-time> ISO formatted date

originalQuantity

required

integer

Quantity of the product in original order

contestedQuantity

required

integer

The quantity that the customer believes would be correct

reviewedQuantity

integer

Quantity of the product specified during review, available only if the contest status is reviewed

required

object

The transaction related to the contested order

paymentTransactionId required	string or null The id of the transaction. Non-empty only if the order is past the "draft" stage
refunded required	boolean Whether the transaction was refunded. Only meaningful if paymentTransactionId is non-empty
tryRefundTimes required	integer The number of times a refund was attempted for this transaction
paymentFailed required	boolean Did the payment fail. Only meaningful if paymentTransactionId is non-empty

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"reviewedTotalPrice": null,
"items": [{"id": 0,
"productId": 0,
"reviewedQuantity": 0
}
]
}

Response samples

200
422

Content type

application/json

{"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"deletedAt": "2019-08-24T14:15:22Z",
"id": 0,
"orderId": "string",
"orderVersion": 0,
"sessionId": "string",
"message": "string",
"fromOperator": true,
"status": "contested",
"contestedTotalPrice": "120.00",
"reviewedTotalPrice": "120.00",
"originalTotalPrice": "123.45",
"items": [{"id": 0,
"productId": 0,
"name": "string",
"price": "string",
"thumbnail": "string",
"productSnapshot": {"name": "string",
"price": "string",
"barcode": "string",
"category": "string",
"thumbnail": "string",
"weight": 0,
"sku": "string",
"externalId": "string",
"taxCode": "string",
"id": 0,
"productId": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
},
"originalQuantity": 0,
"contestedQuantity": 0,
"reviewedQuantity": 0
}
],
"transaction": {"paymentTransactionId": "string",
"refunded": true,
"tryRefundTimes": 0,
"paymentFailed": true
}
}

Admin API - stores

Get list of stores

query Parameters

count	integer <= 200 Default: 20 Number of results
after	string Id or base64 encoded cursor(id + sortKey)
before	string Id or base64 encoded cursor(id + sortKey)
orderBy	string The sort key, sorting by id by default
direction	string Enum: "asc" "desc" Direction of sorting
id	integer Id of a physical store. The id is required when retailer want to make a call to specified store.
status	string Enum: "OPEN" "CLOSED" "CLOSED_FOR_MAINTENANCE" Status of a store, indicates whether the store is open to customers
externalId	string External id of a store, retailers can specify their own id for the store via this field We would send this field in the payload of checkout webhook with key storeExternalId For example, we will include "storeExternalId": "store0001" in the payload of checkout webhook if retailer specifies this field with "store0001"
deploymentStatus	string Enum: "LIVE" "TESTING" "DEPLOYMENT" "DECOMMISSIONED" Deployment status of a store, indicated whether the store is live, under deployment or testing
aifiUniqueStoreId	string Unique identifier across all AiFi stores. it will only be filled in by TechOPS/deployment engineers

Responses

Response Schema: application/json

required

Array of objects (StoreListItemResponseDto)

Array

aifiUniqueStoreId

required

string

Unique identifier across all AiFi stores. it will only be filled in by TechOPS/deployment engineers

status

required

string

Enum: "OPEN" "CLOSED" "CLOSED_FOR_MAINTENANCE"

Status of a store, indicates whether the store is open to customers

deploymentStatus

required

string

Enum: "LIVE" "TESTING" "DEPLOYMENT" "DECOMMISSIONED"

Deployment status of a store, indicated whether the store is live, under deployment or testing

addressLine1

required

string

Address of a store, including details such as: street name, building number, floor, etc

addressCity

required

string

City of the address

addressRegion

required

string

The region of the address, such as the province, state, or district

addressCountry

required

string

Enum: "AC" "AD" "AE" "AF" "AG" "AI" "AL" "AM" "AN" "AO" "AR" "AT" "AU" "AW" "AX" "AZ" "BA" "BB" "BD" "BE" "BF" "BG" "BH" "BI" "BJ" "BL" "BM" "BN" "BO" "BQ" "BR" "BS" "BT" "BV" "BW" "BY" "BZ" "CA" "CC" "CD" "CF" "CG" "CH" "CI" "CK" "CL" "CM" "CN" "CO" "CR" "CU" "CV" "CW" "CX" "CY" "CZ" "DE" "DJ" "DK" "DM" "DO" "DZ" "EC" "EE" "EG" "EH" "ER" "ES" "ET" "FI" "FJ" "FK" "FO" "FR" "GA" "GB" "GD" "GE" "GF" "GG" "GH" "GI" "GL" "GM" "GN" "GP" "GQ" "GR" "GS" "GT" "GW" "GY" "HK" "HM" "HN" "HR" "HT" "HU" "ID" "IE" "IL" "IM" "IN" "IO" "IQ" "IR" "IS" "IT" "JE" "JM" "JO" "JP" "KE" "KG" "KH" "KI" "KM" "KN" "KP" "KR" "KW" "KY" "KZ" "LA" "LB" "LC" "LI" "LK" "LR" "LS" "LT" "LU" "LV" "LY" "MA" "MC" "MD" "ME" "MF" "MG" "MK" "ML" "MM" "MN" "MO" "MQ" "MR" "MS" "MT" "MU" "MV" "MW" "MX" "MY" "MZ" "NA" "NC" "NE" "NF" "NG" "NI" "NL" "NO" "NP" "NR" "NU" "NZ" "OM" "PA" "PE" "PF" "PG" "PH" "PK" "PL" "PM" "PN" "PS" "PT" "PY" "QA" "RE" "RO" "RS" "RU" "RW" "SA" "SB" "SC" "SD" "SE" "SG" "SH" "SI" "SJ" "SK" "SL" "SM" "SN" "SO" "SR" "SS" "ST" "SV" "SX" "SY" "SZ" "TA" "TC" "TD" "TF" "TG" "TH" "TJ" "TK" "TL" "TM" "TN" "TO" "TR" "TT" "TV" "TW" "TZ" "UA" "UG" "UM" "US" "UY" "UZ" "VA" "VC" "VE" "VG" "VN" "VU" "WF" "WS" "XK" "YE" "YT" "ZA" "ZM" "ZW"

Country code of the address. it's a ISO_3166-1_alpha-2 code

addressPostalCode

required

string

Postal code of the address.

id

required

string <integer>

Id of a physical store. The id is required when retailer want to make a call to specified store.

required

object

Store identifiers

oasisApiStoreId required	integer Store identifier that is only internal to cloud-api
aifiUniqueStoreId required	string or null Unique identifier across all AiFi stores. it will only be filled in by TechOPS/deployment engineers

name

required

string

Default: ""

A combination of retailer name, city and country mainly used in aifi internally, it's not very friendly to customer, so the field displayableName will be used as store name in SMS notification

displayableName

required

string

Default: ""

Store name from customer perspective, displayableName is a value set in the DB or a default of using store.name

thirdPartyId

required

string or null

Deprecated

External id of a store, retailers can specify their own id for the store via this field

We would send this field in the payload of checkout webhook with key storeExternalId

For example, we will include "storeExternalId": "store0001" in the payload of checkout webhook if retailer specifies this field with "store0001"

storeUrl

required

string or null

On-premise api url of a store

maxPeople

required

integer

How many people can be at the store at the same time

storeConfigId

required

integer or null

Id of store config

externalId

required

string or null

External id of a store, retailers can specify their own id for the store via this field

We would send this field in the payload of checkout webhook with key storeExternalId

For example, we will include "storeExternalId": "store0001" in the payload of checkout webhook if retailer specifies this field with "store0001"

health

required

string

Enum: "online" "offline" "shadow"

If thirdPartyId is empty, will return empty string. if not, will return 'offline' at the moment

address

required

object

Deprecated

Always return empty object

required

object (CursorBasedPaginationDto)

object

Query parameter to fetch previous page

count required	integer Number of results
before required	string Id or base64 encoded cursor(id + sortKey)
direction required	string Enum: "asc" "desc" Direction of sorting

object

Query parameter to fetch next page

count required	integer Number of results
after required	string Id or base64 encoded cursor(id + sortKey)
direction required	string Enum: "asc" "desc" Direction of sorting

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

{"stores": [{"aifiUniqueStoreId": "string",
"status": "OPEN",
"deploymentStatus": "LIVE",
"addressLine1": "string",
"addressCity": "string",
"addressRegion": "string",
"addressCountry": "AC",
"addressPostalCode": "string",
"id": "string",
"store": {"oasisApiStoreId": 0,
"aifiUniqueStoreId": "string"
},
"name": "",
"displayableName": "",
"thirdPartyId": "string",
"storeUrl": "string",
"maxPeople": 0,
"storeConfigId": 0,
"externalId": "string",
"health": "online",
"address": { }
}
],
"pagination": {"previous": {"count": 0,
"before": "string",
"direction": "asc"
},
"next": {"count": 0,
"after": "string",
"direction": "asc"
}
}
}

Create a store

Request Body schema: application/json
required

aifiUniqueStoreId required	string Unique identifier across all AiFi stores. it will only be filled in by TechOPS/deployment engineers
status required	string Enum: "OPEN" "CLOSED" "CLOSED_FOR_MAINTENANCE" Status of a store, indicates whether the store is open to customers
deploymentStatus required	string Enum: "LIVE" "TESTING" "DEPLOYMENT" "DECOMMISSIONED" Deployment status of a store, indicated whether the store is live, under deployment or testing
maxPeople	integer Default: 0 How many people can be at the store at the same time
storeUrl required	string <uri> On-premise api url of a store
name	string A combination of retailer name, city and country mainly used in aifi internally, it's not very friendly to customer, so the field displayableName will be used as store name in SMS notification
displayableName	string Store name from customer perspective, displayableName is a value set in the DB or a default of using store.name
thirdPartyId	string External id of a store, retailers can specify their own id for the store via this field We would send this field in the payload of checkout webhook with key storeExternalId For example, we will include "storeExternalId": "store0001" in the payload of checkout webhook if retailer specifies this field with "store0001"
addressLine1 required	string Address of a store, including details such as: street name, building number, floor, etc
addressCity required	string City of the address
addressRegion required	string The region of the address, such as the province, state, or district
addressCountry required	string Enum: "AC" "AD" "AE" "AF" "AG" "AI" "AL" "AM" "AN" "AO" "AR" "AT" "AU" "AW" "AX" "AZ" "BA" "BB" "BD" "BE" "BF" "BG" "BH" "BI" "BJ" "BL" "BM" "BN" "BO" "BQ" "BR" "BS" "BT" "BV" "BW" "BY" "BZ" "CA" "CC" "CD" "CF" "CG" "CH" "CI" "CK" "CL" "CM" "CN" "CO" "CR" "CU" "CV" "CW" "CX" "CY" "CZ" "DE" "DJ" "DK" "DM" "DO" "DZ" "EC" "EE" "EG" "EH" "ER" "ES" "ET" "FI" "FJ" "FK" "FO" "FR" "GA" "GB" "GD" "GE" "GF" "GG" "GH" "GI" "GL" "GM" "GN" "GP" "GQ" "GR" "GS" "GT" "GW" "GY" "HK" "HM" "HN" "HR" "HT" "HU" "ID" "IE" "IL" "IM" "IN" "IO" "IQ" "IR" "IS" "IT" "JE" "JM" "JO" "JP" "KE" "KG" "KH" "KI" "KM" "KN" "KP" "KR" "KW" "KY" "KZ" "LA" "LB" "LC" "LI" "LK" "LR" "LS" "LT" "LU" "LV" "LY" "MA" "MC" "MD" "ME" "MF" "MG" "MK" "ML" "MM" "MN" "MO" "MQ" "MR" "MS" "MT" "MU" "MV" "MW" "MX" "MY" "MZ" "NA" "NC" "NE" "NF" "NG" "NI" "NL" "NO" "NP" "NR" "NU" "NZ" "OM" "PA" "PE" "PF" "PG" "PH" "PK" "PL" "PM" "PN" "PS" "PT" "PY" "QA" "RE" "RO" "RS" "RU" "RW" "SA" "SB" "SC" "SD" "SE" "SG" "SH" "SI" "SJ" "SK" "SL" "SM" "SN" "SO" "SR" "SS" "ST" "SV" "SX" "SY" "SZ" "TA" "TC" "TD" "TF" "TG" "TH" "TJ" "TK" "TL" "TM" "TN" "TO" "TR" "TT" "TV" "TW" "TZ" "UA" "UG" "UM" "US" "UY" "UZ" "VA" "VC" "VE" "VG" "VN" "VU" "WF" "WS" "XK" "YE" "YT" "ZA" "ZM" "ZW" Country code of the address. it's a ISO_3166-1_alpha-2 code
addressPostalCode required	string Postal code of the address.

Responses

Response Schema: application/json

aifiUniqueStoreId

required

string

Unique identifier across all AiFi stores. it will only be filled in by TechOPS/deployment engineers

status

required

string

Enum: "OPEN" "CLOSED" "CLOSED_FOR_MAINTENANCE"

Status of a store, indicates whether the store is open to customers

deploymentStatus

required

string

Enum: "LIVE" "TESTING" "DEPLOYMENT" "DECOMMISSIONED"

Deployment status of a store, indicated whether the store is live, under deployment or testing

addressLine1

required

string

Address of a store, including details such as: street name, building number, floor, etc

addressCity

required

string

City of the address

addressRegion

required

string

The region of the address, such as the province, state, or district

addressCountry

required

string

Enum: "AC" "AD" "AE" "AF" "AG" "AI" "AL" "AM" "AN" "AO" "AR" "AT" "AU" "AW" "AX" "AZ" "BA" "BB" "BD" "BE" "BF" "BG" "BH" "BI" "BJ" "BL" "BM" "BN" "BO" "BQ" "BR" "BS" "BT" "BV" "BW" "BY" "BZ" "CA" "CC" "CD" "CF" "CG" "CH" "CI" "CK" "CL" "CM" "CN" "CO" "CR" "CU" "CV" "CW" "CX" "CY" "CZ" "DE" "DJ" "DK" "DM" "DO" "DZ" "EC" "EE" "EG" "EH" "ER" "ES" "ET" "FI" "FJ" "FK" "FO" "FR" "GA" "GB" "GD" "GE" "GF" "GG" "GH" "GI" "GL" "GM" "GN" "GP" "GQ" "GR" "GS" "GT" "GW" "GY" "HK" "HM" "HN" "HR" "HT" "HU" "ID" "IE" "IL" "IM" "IN" "IO" "IQ" "IR" "IS" "IT" "JE" "JM" "JO" "JP" "KE" "KG" "KH" "KI" "KM" "KN" "KP" "KR" "KW" "KY" "KZ" "LA" "LB" "LC" "LI" "LK" "LR" "LS" "LT" "LU" "LV" "LY" "MA" "MC" "MD" "ME" "MF" "MG" "MK" "ML" "MM" "MN" "MO" "MQ" "MR" "MS" "MT" "MU" "MV" "MW" "MX" "MY" "MZ" "NA" "NC" "NE" "NF" "NG" "NI" "NL" "NO" "NP" "NR" "NU" "NZ" "OM" "PA" "PE" "PF" "PG" "PH" "PK" "PL" "PM" "PN" "PS" "PT" "PY" "QA" "RE" "RO" "RS" "RU" "RW" "SA" "SB" "SC" "SD" "SE" "SG" "SH" "SI" "SJ" "SK" "SL" "SM" "SN" "SO" "SR" "SS" "ST" "SV" "SX" "SY" "SZ" "TA" "TC" "TD" "TF" "TG" "TH" "TJ" "TK" "TL" "TM" "TN" "TO" "TR" "TT" "TV" "TW" "TZ" "UA" "UG" "UM" "US" "UY" "UZ" "VA" "VC" "VE" "VG" "VN" "VU" "WF" "WS" "XK" "YE" "YT" "ZA" "ZM" "ZW"

Country code of the address. it's a ISO_3166-1_alpha-2 code

addressPostalCode

required

string

Postal code of the address.

required

object

Store identifiers

oasisApiStoreId required	integer Store identifier that is only internal to cloud-api
aifiUniqueStoreId required	string or null Unique identifier across all AiFi stores. it will only be filled in by TechOPS/deployment engineers

thirdPartyId

required

string or null

Deprecated

External id of a store, retailers can specify their own id for the store via this field

We would send this field in the payload of checkout webhook with key storeExternalId

For example, we will include "storeExternalId": "store0001" in the payload of checkout webhook if retailer specifies this field with "store0001"

storeUrl

required

string or null

On-premise api url of a store

maxPeople

required

integer

How many people can be at the store at the same time

storeConfigId

required

integer or null

Id of store config

externalId

required

string or null

External id of a store, retailers can specify their own id for the store via this field

We would send this field in the payload of checkout webhook with key storeExternalId

For example, we will include "storeExternalId": "store0001" in the payload of checkout webhook if retailer specifies this field with "store0001"

health

required

string

Enum: "online" "offline" "shadow"

If thirdPartyId is empty, will return empty string. if not, will return 'offline' at the moment

address

required

object

Deprecated

Always return empty object

id

required

integer

Id of a physical store. The id is required when retailer want to make a call to specified store.

name

required

string or null

A combination of retailer name, city and country mainly used in aifi internally, it's not very friendly to customer, so the field displayableName will be used as store name in SMS notification

displayableName

required

string or null

Store name from customer perspective, displayableName is a value set in the DB or a default of using store.name

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"aifiUniqueStoreId": "string",
"status": "OPEN",
"deploymentStatus": "LIVE",
"maxPeople": 0,
"storeUrl": "http://example.com",
"name": "string",
"displayableName": "string",
"thirdPartyId": "string",
"addressLine1": "string",
"addressCity": "string",
"addressRegion": "string",
"addressCountry": "AC",
"addressPostalCode": "string"
}

Response samples

200
422

Content type

application/json

{"aifiUniqueStoreId": "string",
"status": "OPEN",
"deploymentStatus": "LIVE",
"addressLine1": "string",
"addressCity": "string",
"addressRegion": "string",
"addressCountry": "AC",
"addressPostalCode": "string",
"store": {"oasisApiStoreId": 0,
"aifiUniqueStoreId": "string"
},
"thirdPartyId": "string",
"storeUrl": "string",
"maxPeople": 0,
"storeConfigId": 0,
"externalId": "string",
"health": "online",
"address": { },
"id": 0,
"name": "string",
"displayableName": "string"
}

Get a store

path Parameters

storeId

required

integer

Id of a physical store. The id is required when retailer want to make a call to specified store.

Responses

Response Schema: application/json

aifiUniqueStoreId

required

string

Unique identifier across all AiFi stores. it will only be filled in by TechOPS/deployment engineers

status

required

string

Enum: "OPEN" "CLOSED" "CLOSED_FOR_MAINTENANCE"

Status of a store, indicates whether the store is open to customers

deploymentStatus

required

string

Enum: "LIVE" "TESTING" "DEPLOYMENT" "DECOMMISSIONED"

Deployment status of a store, indicated whether the store is live, under deployment or testing

addressLine1

required

string

Address of a store, including details such as: street name, building number, floor, etc

addressCity

required

string

City of the address

addressRegion

required

string

The region of the address, such as the province, state, or district

addressCountry

required

string

Enum: "AC" "AD" "AE" "AF" "AG" "AI" "AL" "AM" "AN" "AO" "AR" "AT" "AU" "AW" "AX" "AZ" "BA" "BB" "BD" "BE" "BF" "BG" "BH" "BI" "BJ" "BL" "BM" "BN" "BO" "BQ" "BR" "BS" "BT" "BV" "BW" "BY" "BZ" "CA" "CC" "CD" "CF" "CG" "CH" "CI" "CK" "CL" "CM" "CN" "CO" "CR" "CU" "CV" "CW" "CX" "CY" "CZ" "DE" "DJ" "DK" "DM" "DO" "DZ" "EC" "EE" "EG" "EH" "ER" "ES" "ET" "FI" "FJ" "FK" "FO" "FR" "GA" "GB" "GD" "GE" "GF" "GG" "GH" "GI" "GL" "GM" "GN" "GP" "GQ" "GR" "GS" "GT" "GW" "GY" "HK" "HM" "HN" "HR" "HT" "HU" "ID" "IE" "IL" "IM" "IN" "IO" "IQ" "IR" "IS" "IT" "JE" "JM" "JO" "JP" "KE" "KG" "KH" "KI" "KM" "KN" "KP" "KR" "KW" "KY" "KZ" "LA" "LB" "LC" "LI" "LK" "LR" "LS" "LT" "LU" "LV" "LY" "MA" "MC" "MD" "ME" "MF" "MG" "MK" "ML" "MM" "MN" "MO" "MQ" "MR" "MS" "MT" "MU" "MV" "MW" "MX" "MY" "MZ" "NA" "NC" "NE" "NF" "NG" "NI" "NL" "NO" "NP" "NR" "NU" "NZ" "OM" "PA" "PE" "PF" "PG" "PH" "PK" "PL" "PM" "PN" "PS" "PT" "PY" "QA" "RE" "RO" "RS" "RU" "RW" "SA" "SB" "SC" "SD" "SE" "SG" "SH" "SI" "SJ" "SK" "SL" "SM" "SN" "SO" "SR" "SS" "ST" "SV" "SX" "SY" "SZ" "TA" "TC" "TD" "TF" "TG" "TH" "TJ" "TK" "TL" "TM" "TN" "TO" "TR" "TT" "TV" "TW" "TZ" "UA" "UG" "UM" "US" "UY" "UZ" "VA" "VC" "VE" "VG" "VN" "VU" "WF" "WS" "XK" "YE" "YT" "ZA" "ZM" "ZW"

Country code of the address. it's a ISO_3166-1_alpha-2 code

addressPostalCode

required

string

Postal code of the address.

required

object

Store identifiers

oasisApiStoreId required	integer Store identifier that is only internal to cloud-api
aifiUniqueStoreId required	string or null Unique identifier across all AiFi stores. it will only be filled in by TechOPS/deployment engineers

thirdPartyId

required

string or null

Deprecated

External id of a store, retailers can specify their own id for the store via this field

We would send this field in the payload of checkout webhook with key storeExternalId

For example, we will include "storeExternalId": "store0001" in the payload of checkout webhook if retailer specifies this field with "store0001"

storeUrl

required

string or null

On-premise api url of a store

maxPeople

required

integer

How many people can be at the store at the same time

storeConfigId

required

integer or null

Id of store config

externalId

required

string or null

External id of a store, retailers can specify their own id for the store via this field

We would send this field in the payload of checkout webhook with key storeExternalId

For example, we will include "storeExternalId": "store0001" in the payload of checkout webhook if retailer specifies this field with "store0001"

health

required

string

Enum: "online" "offline" "shadow"

If thirdPartyId is empty, will return empty string. if not, will return 'offline' at the moment

address

required

object

Deprecated

Always return empty object

id

required

integer

Id of a physical store. The id is required when retailer want to make a call to specified store.

name

required

string or null

A combination of retailer name, city and country mainly used in aifi internally, it's not very friendly to customer, so the field displayableName will be used as store name in SMS notification

displayableName

required

string or null

Store name from customer perspective, displayableName is a value set in the DB or a default of using store.name

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

{"aifiUniqueStoreId": "string",
"status": "OPEN",
"deploymentStatus": "LIVE",
"addressLine1": "string",
"addressCity": "string",
"addressRegion": "string",
"addressCountry": "AC",
"addressPostalCode": "string",
"store": {"oasisApiStoreId": 0,
"aifiUniqueStoreId": "string"
},
"thirdPartyId": "string",
"storeUrl": "string",
"maxPeople": 0,
"storeConfigId": 0,
"externalId": "string",
"health": "online",
"address": { },
"id": 0,
"name": "string",
"displayableName": "string"
}

Update a store

path Parameters

storeId

required

integer

Id of a physical store. The id is required when retailer want to make a call to specified store.

Request Body schema: application/json
required

aifiUniqueStoreId	string Unique identifier across all AiFi stores. it will only be filled in by TechOPS/deployment engineers
status	string Enum: "OPEN" "CLOSED" "CLOSED_FOR_MAINTENANCE" Status of a store, indicates whether the store is open to customers
deploymentStatus	string Enum: "LIVE" "TESTING" "DEPLOYMENT" "DECOMMISSIONED" Deployment status of a store, indicated whether the store is live, under deployment or testing
maxPeople	integer How many people can be at the store at the same time
storeUrl	string <uri> On-premise api url of a store
name	string A combination of retailer name, city and country mainly used in aifi internally, it's not very friendly to customer, so the field displayableName will be used as store name in SMS notification
displayableName	string Store name from customer perspective, displayableName is a value set in the DB or a default of using store.name
thirdPartyId	string or null External id of a store, retailers can specify their own id for the store via this field We would send this field in the payload of checkout webhook with key storeExternalId For example, we will include "storeExternalId": "store0001" in the payload of checkout webhook if retailer specifies this field with "store0001" if you send null for this variable, it'll clear thirdPartyId
addressLine1	string Address of a store, including details such as: street name, building number, floor, etc
addressCity	string City of the address
addressRegion	string The region of the address, such as the province, state, or district
addressCountry	string Enum: "AC" "AD" "AE" "AF" "AG" "AI" "AL" "AM" "AN" "AO" "AR" "AT" "AU" "AW" "AX" "AZ" "BA" "BB" "BD" "BE" "BF" "BG" "BH" "BI" "BJ" "BL" "BM" "BN" "BO" "BQ" "BR" "BS" "BT" "BV" "BW" "BY" "BZ" "CA" "CC" "CD" "CF" "CG" "CH" "CI" "CK" "CL" "CM" "CN" "CO" "CR" "CU" "CV" "CW" "CX" "CY" "CZ" "DE" "DJ" "DK" "DM" "DO" "DZ" "EC" "EE" "EG" "EH" "ER" "ES" "ET" "FI" "FJ" "FK" "FO" "FR" "GA" "GB" "GD" "GE" "GF" "GG" "GH" "GI" "GL" "GM" "GN" "GP" "GQ" "GR" "GS" "GT" "GW" "GY" "HK" "HM" "HN" "HR" "HT" "HU" "ID" "IE" "IL" "IM" "IN" "IO" "IQ" "IR" "IS" "IT" "JE" "JM" "JO" "JP" "KE" "KG" "KH" "KI" "KM" "KN" "KP" "KR" "KW" "KY" "KZ" "LA" "LB" "LC" "LI" "LK" "LR" "LS" "LT" "LU" "LV" "LY" "MA" "MC" "MD" "ME" "MF" "MG" "MK" "ML" "MM" "MN" "MO" "MQ" "MR" "MS" "MT" "MU" "MV" "MW" "MX" "MY" "MZ" "NA" "NC" "NE" "NF" "NG" "NI" "NL" "NO" "NP" "NR" "NU" "NZ" "OM" "PA" "PE" "PF" "PG" "PH" "PK" "PL" "PM" "PN" "PS" "PT" "PY" "QA" "RE" "RO" "RS" "RU" "RW" "SA" "SB" "SC" "SD" "SE" "SG" "SH" "SI" "SJ" "SK" "SL" "SM" "SN" "SO" "SR" "SS" "ST" "SV" "SX" "SY" "SZ" "TA" "TC" "TD" "TF" "TG" "TH" "TJ" "TK" "TL" "TM" "TN" "TO" "TR" "TT" "TV" "TW" "TZ" "UA" "UG" "UM" "US" "UY" "UZ" "VA" "VC" "VE" "VG" "VN" "VU" "WF" "WS" "XK" "YE" "YT" "ZA" "ZM" "ZW" Country code of the address. it's a ISO_3166-1_alpha-2 code
addressPostalCode	string Postal code of the address.

Responses

Response Schema: application/json

aifiUniqueStoreId

required

string

Unique identifier across all AiFi stores. it will only be filled in by TechOPS/deployment engineers

status

required

string

Enum: "OPEN" "CLOSED" "CLOSED_FOR_MAINTENANCE"

Status of a store, indicates whether the store is open to customers

deploymentStatus

required

string

Enum: "LIVE" "TESTING" "DEPLOYMENT" "DECOMMISSIONED"

Deployment status of a store, indicated whether the store is live, under deployment or testing

addressLine1

required

string

Address of a store, including details such as: street name, building number, floor, etc

addressCity

required

string

City of the address

addressRegion

required

string

The region of the address, such as the province, state, or district

addressCountry

required

string

Enum: "AC" "AD" "AE" "AF" "AG" "AI" "AL" "AM" "AN" "AO" "AR" "AT" "AU" "AW" "AX" "AZ" "BA" "BB" "BD" "BE" "BF" "BG" "BH" "BI" "BJ" "BL" "BM" "BN" "BO" "BQ" "BR" "BS" "BT" "BV" "BW" "BY" "BZ" "CA" "CC" "CD" "CF" "CG" "CH" "CI" "CK" "CL" "CM" "CN" "CO" "CR" "CU" "CV" "CW" "CX" "CY" "CZ" "DE" "DJ" "DK" "DM" "DO" "DZ" "EC" "EE" "EG" "EH" "ER" "ES" "ET" "FI" "FJ" "FK" "FO" "FR" "GA" "GB" "GD" "GE" "GF" "GG" "GH" "GI" "GL" "GM" "GN" "GP" "GQ" "GR" "GS" "GT" "GW" "GY" "HK" "HM" "HN" "HR" "HT" "HU" "ID" "IE" "IL" "IM" "IN" "IO" "IQ" "IR" "IS" "IT" "JE" "JM" "JO" "JP" "KE" "KG" "KH" "KI" "KM" "KN" "KP" "KR" "KW" "KY" "KZ" "LA" "LB" "LC" "LI" "LK" "LR" "LS" "LT" "LU" "LV" "LY" "MA" "MC" "MD" "ME" "MF" "MG" "MK" "ML" "MM" "MN" "MO" "MQ" "MR" "MS" "MT" "MU" "MV" "MW" "MX" "MY" "MZ" "NA" "NC" "NE" "NF" "NG" "NI" "NL" "NO" "NP" "NR" "NU" "NZ" "OM" "PA" "PE" "PF" "PG" "PH" "PK" "PL" "PM" "PN" "PS" "PT" "PY" "QA" "RE" "RO" "RS" "RU" "RW" "SA" "SB" "SC" "SD" "SE" "SG" "SH" "SI" "SJ" "SK" "SL" "SM" "SN" "SO" "SR" "SS" "ST" "SV" "SX" "SY" "SZ" "TA" "TC" "TD" "TF" "TG" "TH" "TJ" "TK" "TL" "TM" "TN" "TO" "TR" "TT" "TV" "TW" "TZ" "UA" "UG" "UM" "US" "UY" "UZ" "VA" "VC" "VE" "VG" "VN" "VU" "WF" "WS" "XK" "YE" "YT" "ZA" "ZM" "ZW"

Country code of the address. it's a ISO_3166-1_alpha-2 code

addressPostalCode

required

string

Postal code of the address.

required

object

Store identifiers

oasisApiStoreId required	integer Store identifier that is only internal to cloud-api
aifiUniqueStoreId required	string or null Unique identifier across all AiFi stores. it will only be filled in by TechOPS/deployment engineers

thirdPartyId

required

string or null

Deprecated

External id of a store, retailers can specify their own id for the store via this field

We would send this field in the payload of checkout webhook with key storeExternalId

For example, we will include "storeExternalId": "store0001" in the payload of checkout webhook if retailer specifies this field with "store0001"

storeUrl

required

string or null

On-premise api url of a store

maxPeople

required

integer

How many people can be at the store at the same time

storeConfigId

required

integer or null

Id of store config

externalId

required

string or null

External id of a store, retailers can specify their own id for the store via this field

We would send this field in the payload of checkout webhook with key storeExternalId

For example, we will include "storeExternalId": "store0001" in the payload of checkout webhook if retailer specifies this field with "store0001"

health

required

string

Enum: "online" "offline" "shadow"

If thirdPartyId is empty, will return empty string. if not, will return 'offline' at the moment

address

required

object

Deprecated

Always return empty object

id

required

integer

Id of a physical store. The id is required when retailer want to make a call to specified store.

name

required

string or null

A combination of retailer name, city and country mainly used in aifi internally, it's not very friendly to customer, so the field displayableName will be used as store name in SMS notification

displayableName

required

string or null

Store name from customer perspective, displayableName is a value set in the DB or a default of using store.name

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"aifiUniqueStoreId": "string",
"status": "OPEN",
"deploymentStatus": "LIVE",
"maxPeople": 0,
"storeUrl": "http://example.com",
"name": "string",
"displayableName": "string",
"thirdPartyId": "string",
"addressLine1": "string",
"addressCity": "string",
"addressRegion": "string",
"addressCountry": "AC",
"addressPostalCode": "string"
}

Response samples

200
422

Content type

application/json

{"aifiUniqueStoreId": "string",
"status": "OPEN",
"deploymentStatus": "LIVE",
"addressLine1": "string",
"addressCity": "string",
"addressRegion": "string",
"addressCountry": "AC",
"addressPostalCode": "string",
"store": {"oasisApiStoreId": 0,
"aifiUniqueStoreId": "string"
},
"thirdPartyId": "string",
"storeUrl": "string",
"maxPeople": 0,
"storeConfigId": 0,
"externalId": "string",
"health": "online",
"address": { },
"id": 0,
"name": "string",
"displayableName": "string"
}

Notifies Register frontend to start a flow, of registering new customer with specified token

path Parameters

storeId required	integer Id of a physical store. The id is required when retailer want to make a call to specified store.
checkInDeviceId required	integer

Request Body schema: application/json
required

token required	string A string token to start frontend registration flow
tokenType required	string Default: "SESSION_ID" Enum: "SESSION_ID" "NONE" session token type

Responses

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"token": "string",
"tokenType": "SESSION_ID"
}

Response samples

422

Content type

application/json

{"message": "Invalid request body",
"type": "E_INVALID_BODY",
"errors": [{"error": "\"email\" is required",
"rule": "any.required",
"field": "\"email\""
}
]
}

For a given store, zone and time return a list of shoppers, who were present in the zone at that time

path Parameters

storeId required	integer Id of a physical store. The id is required when retailer want to make a call to specified store.
zoneId required	string

query Parameters

timestamp

required

string

Example: timestamp=1697721601000

Ether Unix timestamp in milliseconds (always UTC), example: 1697721601000. Or ISO8601 format with milliseconds (timezone can be passed according to standard), example: "2023-10-05T14:48:00.000Z"

  Important note: we reject requests with:

    Timestamp from the future

    Timestamp older than 5 minutes (for now we don't keep historical shoppers)

Responses

Response Schema: application/json

storeId

required

integer

Id of a physical store. The id is required when retailer want to make a call to specified store.

storeExternalId

required

string or null

External id of a store, retailers can specify their own id for the store via this field

We would send this field in the payload of checkout webhook with key storeExternalId

For example, we will include "storeExternalId": "store0001" in the payload of checkout webhook if retailer specifies this field with "store0001"

required

object

Store Identifiers

oasisApiStoreId required	integer Store identifier that is only internal to cloud-api
aifiUniqueStoreId required	string or null Unique identifier across all AiFi stores. it will only be filled in by TechOPS/deployment engineers

required

Array of objects (ShopperInZoneCameraImageDto)

List of camera images, one image for each camera. the list may be empty if no images could be found

Array

cameraId required	integer
frameUri required	string Full camera image, can be either a data URI or https:// URL pointing to image

required

Array of objects (ShopperInZoneDto)

All shoppers that were in the zone

Array

required

object

Unique shopper object across all items in shoppers list

shopperId

required

string

Identifier of the shopper

shopperFlags

required

Array of strings

Items Enum: "POTENTIALLY_INTERACTED_WITH_ALCOHOL" "POTENTIALLY_SUSPICIOUS_BEHAVIOUR"

required

Array of objects (ShopperFaceCoordinationDto)

List of shopper face coordinates, can be empty if no images could be found for given shopper

Array

cameraId

required

integer

Use to match with proper image

required

object

Coordinates describing the shopper's face. Point (0, 0) corresponds to the top-left corner of the image. As we move down and to the right, both the y and x-values increase

required

object (Pos2DDto)

x required	integer
y required	integer

required

object (Pos2DDto)

x required	integer
y required	integer

interactionsCount

integer >= 0

Total number of shopper's interactions

restrictedInteractionsCount

integer >= 0

Total number of shopper's interactions with restricted items

Array of objects (InterestGroupInteractionCounterDto)

List of interest groups with their interaction counts

Array

id required	string Interest group identifier
name required	string Interest group name
interactionsCount required	integer >= 0 Number of interactions for this interest group

required

object

Shopper's session, note that multiple shoppers can have the same session (group shopping)

sessionId

required

string

A unique token to identify a shopping session

shoppingSessionFlags

required

Array of strings

Items Enum: "POTENTIALLY_INTERACTED_WITH_ALCOHOL" "POTENTIALLY_SUSPICIOUS_BEHAVIOUR"

interactionsCount

number

restrictedInteractionsCount

number

Array of objects (InterestGroupInteractionCounterDto)

List of interest groups with their interaction counts

Array

id required	string Interest group identifier
name required	string Interest group name
interactionsCount required	integer >= 0 Number of interactions for this interest group

required

object or null

Customer entity related with the shopper's session, if null it means that we can't relate any known customer with the session

externalId required	string or null Id of the customer in external system
role required	string Enum: "customer" "employee" "tester" "untracked" "unknown" Role of the customer
metadata required	object or null This object can contain custom metadata information
priority required	integer [ -10 .. 10 ] Default: 0 Customer priority. default to 0, which means any regular customer. customers with higher priority will have their shopping sessions prioritized during processing, the lower priority is opposite.
id required	string <integer> AiFi customer id, formatted as string

enteredAt

required

string <date-time>

ISO8601 formatted time, in which the shopper entered the zone

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

{"storeId": 0,
"storeExternalId": "string",
"store": {"oasisApiStoreId": 0,
"aifiUniqueStoreId": "string"
},
"cameraImages": [{"cameraId": 0,
"frameUri": "string"
}
],
"shoppers": [{"shopper": {"shopperId": "string",
"shopperFlags": ["POTENTIALLY_INTERACTED_WITH_ALCOHOL"
],
"faceCoordinates": [{"cameraId": 0,
"location": {"topLeft": {"x": 0,
"y": 0
},
"bottomRight": {"x": 0,
"y": 0
}
}
}
],
"interactionsCount": 0,
"restrictedInteractionsCount": 0,
"interestGroups": [{"id": "string",
"name": "string",
"interactionsCount": 0
}
]
},
"session": {"sessionId": "string",
"shoppingSessionFlags": ["POTENTIALLY_INTERACTED_WITH_ALCOHOL"
],
"interactionsCount": 0,
"restrictedInteractionsCount": 0,
"interestGroups": [{"id": "string",
"name": "string",
"interactionsCount": 0
}
]
},
"customer": {"externalId": "string",
"role": "customer",
"metadata": {"arbitraryKey": "arbitraryValue"
},
"priority": 0,
"id": "string"
},
"enteredAt": "2019-08-24T14:15:22Z"
}
]
}

Get heatmap during specified period

path Parameters

storeId

required

integer

Id of a physical store. The id is required when retailer want to make a call to specified store.

query Parameters

from required	integer >= 0 Star timestamp
to required	integer >= 0 End timestamp

Responses

Response Schema: application/json

string <binary>

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

"string"

Get store status

path Parameters

storeId

required

integer

Id of a physical store. The id is required when retailer want to make a call to specified store.

Responses

Response Schema: application/json

status required	string Enum: "OPEN" "CLOSED" "CLOSED_FOR_MAINTENANCE" Status of a store, indicates whether the store is open to customers
employeeInside required	boolean A flag indicate whether employee is currently present in the store, we will mark all unexpected shoppers(targets that appeared and weren’t bound to a proper session) as employees when the flag employeeInside=true
deploymentStatus required	string Enum: "LIVE" "TESTING" "DEPLOYMENT" "DECOMMISSIONED" Deployment status of a store, indicated whether the store is live, under deployment or testing

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

{"status": "OPEN",
"employeeInside": true,
"deploymentStatus": "LIVE"
}

Set store status

path Parameters

storeId

required

integer

Id of a physical store. The id is required when retailer want to make a call to specified store.

Request Body schema: application/json
required

status	string Enum: "OPEN" "CLOSED" "CLOSED_FOR_MAINTENANCE" Status of a store, indicates whether the store is open to customers
employeeInside	boolean Whether any employee is in the store
deploymentStatus	string Enum: "LIVE" "TESTING" "DEPLOYMENT" "DECOMMISSIONED" Deployment status of a store, indicated whether the store is live, under deployment or testing

Responses

Response Schema: application/json

status required	string Enum: "OPEN" "CLOSED" "CLOSED_FOR_MAINTENANCE" Status of a store, indicates whether the store is open to customers
employeeInside required	boolean A flag indicate whether employee is currently present in the store, we will mark all unexpected shoppers(targets that appeared and weren’t bound to a proper session) as employees when the flag employeeInside=true
deploymentStatus required	string Enum: "LIVE" "TESTING" "DEPLOYMENT" "DECOMMISSIONED" Deployment status of a store, indicated whether the store is live, under deployment or testing

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"status": "OPEN",
"employeeInside": true,
"deploymentStatus": "LIVE"
}

Response samples

200
422

Content type

application/json

{"status": "OPEN",
"employeeInside": true,
"deploymentStatus": "LIVE"
}

Get customers count Deprecated

This endpoint has been deprecated, use api/admin/v2/stores/{storeId}/customers/count instead

path Parameters

storeId

required

integer

Id of a physical store. The id is required when retailer want to make a call to specified store.

Responses

Response Schema: application/json

visitorsInStoreCount

required

integer

How many people in the store

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

{"visitorsInStoreCount": 0
}

Get all gondola basic information

path Parameters

storeId

required

integer

Id of a physical store. The id is required when retailer want to make a call to specified store.

Responses

Response Schema: application/json

Array

id

required

integer

Id of a gondola

required

Array of objects (ShelfIdDto)

Array

id required	string [ 3 .. 64 ] characters Combination of gondola id and shelf index
shelfIndex required	integer Index of a shelf

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

[{"id": 2,
"shelves": [{"id": "2-5",
"shelfIndex": 5
}
]
}
]

Get one gondola information

path Parameters

storeId required	integer Id of a physical store. The id is required when retailer want to make a call to specified store.
gondolaId required	integer Example: 2 Id of a gondola

query Parameters

includeCoordinates	boolean Default: false
includeGlobalCoordinates	boolean Default: false
includeBins	boolean Default: false

Responses

Response Schema: application/json

object

Available only if query parameter includeCoordinates=true

x required	string <float> x coordinate
y required	string <float> y coordinate
z required	string <float> z coordinate

object

Available only if query parameter includeCoordinates=true

x required	string <float> x coordinate
y required	string <float> y coordinate
z required	string <float> z coordinate

object

Available only if query parameter includeCoordinates=true

x required	string <float> x coordinate
y required	string <float> y coordinate
z required	string <float> z coordinate

object

Available only if query parameter includeGlobalCoordinates=true

object

Available only if query parameter includeCoordinates=true

x required	string <float> x coordinate
y required	string <float> y coordinate
z required	string <float> z coordinate

object

Available only if query parameter includeCoordinates=true

x required	string <float> x coordinate
y required	string <float> y coordinate
z required	string <float> z coordinate

id

required

integer

Id of a gondola

required

object (GondolaShelfDto)

object

Available only if query parameter includeCoordinates=true

x required	string <float> x coordinate
y required	string <float> y coordinate
z required	string <float> z coordinate

object

Available only if query parameter includeCoordinates=true

x required	string <float> x coordinate
y required	string <float> y coordinate
z required	string <float> z coordinate

object

Available only if query parameter includeCoordinates=true

x required	string <float> x coordinate
y required	string <float> y coordinate
z required	string <float> z coordinate

object

Available only if query parameter includeGlobalCoordinates=true

object

Available only if query parameter includeCoordinates=true

x required	string <float> x coordinate
y required	string <float> y coordinate
z required	string <float> z coordinate

object

Available only if query parameter includeCoordinates=true

x required	string <float> x coordinate
y required	string <float> y coordinate
z required	string <float> z coordinate

id

required

string [ 3 .. 64 ] characters

Combination of gondola id and shelf index

shelfIndex

required

integer

Index of a shelf

Array of objects (BinDetailDto)

Available only if query parameter includeBins=true

Array

object

Available only if query parameter includeCoordinates=true

x required	string <float> x coordinate
y required	string <float> y coordinate
z required	string <float> z coordinate

object

Available only if query parameter includeCoordinates=true

x required	string <float> x coordinate
y required	string <float> y coordinate
z required	string <float> z coordinate

object

Available only if query parameter includeCoordinates=true

x required	string <float> x coordinate
y required	string <float> y coordinate
z required	string <float> z coordinate

object

Available only if query parameter includeGlobalCoordinates=true

object

Available only if query parameter includeCoordinates=true

x required	string <float> x coordinate
y required	string <float> y coordinate
z required	string <float> z coordinate

object

Available only if query parameter includeCoordinates=true

x required	string <float> x coordinate
y required	string <float> y coordinate
z required	string <float> z coordinate

id

required

integer

Id of a bin

index

required

integer

Index of a bin

name

required

string or null

Name of the gondola

disabledAt

required

string or null <date-time>

When the gondola get disabled

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

{"dimensions": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
},
"rotation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
},
"translation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
},
"globalCoordinates": {"rotation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
},
"translation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
}
},
"id": 2,
"shelves": {"dimensions": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
},
"rotation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
},
"translation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
},
"globalCoordinates": {"rotation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
},
"translation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
}
},
"id": "2-5",
"shelfIndex": 5,
"bins": [{"dimensions": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
},
"rotation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
},
"translation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
},
"globalCoordinates": {"rotation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
},
"translation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
}
},
"id": 0,
"index": 0
}
]
},
"name": "string",
"disabledAt": "2019-08-24T14:15:22Z"
}

Update specified gondola

path Parameters

storeId required	integer Id of a physical store. The id is required when retailer want to make a call to specified store.
gondolaId required	integer Example: 2 Id of a gondola

Request Body schema: application/json
required

name

string

Name of the gondola

disabled

boolean

Whether disable the gondola

object

Update the coordinates of specified gondola

dimX

required

number

dimY

required

number

dimZ

required

number

object (TransformDto)

object (TranslationDto)

translationX required	number
translationY required	number
translationZ required	number

object (RotationDto)

rotationX required	number
rotationY required	number
rotationZ required	number

Responses

Response Schema: application/json

id

required

integer

Id of a gondola

name

required

string or null

Name of the gondola

disabledAt

required

string or null <date-time>

When the gondola get disabled

required

Array of objects (ShelfIdDto)

Array

id required	string [ 3 .. 64 ] characters Combination of gondola id and shelf index
shelfIndex required	integer Index of a shelf

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"name": "string",
"disabled": true,
"coordinates": {"dimX": 0,
"dimY": 0,
"dimZ": 0,
"transform": {"translation": {"translationX": 0,
"translationY": 0,
"translationZ": 0
},
"rotation": {"rotationX": 0,
"rotationY": 0,
"rotationZ": 0
}
}
}
}

Response samples

200
422

Content type

application/json

{"id": 2,
"name": "string",
"disabledAt": "2019-08-24T14:15:22Z",
"shelves": [{"id": "2-5",
"shelfIndex": 5
}
]
}

Get shelves of one gondola

path Parameters

storeId required	integer Id of a physical store. The id is required when retailer want to make a call to specified store.
gondolaId required	integer Example: 2 Id of a gondola

Responses

Response Schema: application/json

required

object

additional property

object (ShelfInventoryDto)

shelfIndex

required

integer

Index of a shelf

required

object

Coordinates of the shelf

dimX

required

number

dimY

required

number

dimZ

required

number

required

object (TransformAllRequiredDto)

required

object (Pos3DDto)

x required	string <float> x coordinate
y required	string <float> y coordinate
z required	string <float> z coordinate

required

object (Pos3DDto)

x required	string <float> x coordinate
y required	string <float> y coordinate
z required	string <float> z coordinate

required

Array of objects (ShelfBinDto)

Array

binSize

required

number

productId

required

integer or null

Id of the product which should be present in this bin

productName

required

string or null

Name of the product which should be present in this bin

productBarcode

required

string or null

Barcode of the product which should be present in this bin

thumbnail

required

string or null

Thumbnail of the product which should be present in this bin

restricted

required

boolean or null

Whether the product is a restriction item

productUnits

required

number or null

Number of all products in the bin that are supposed to be there

unplannedProductsUnits

number

Number of all products in the bin that are not supposed to be there

Array of objects (BinPlanogramDto)

All products that are present in the bin

Array

quantity

required

number

required

object (BinProductDto)

barcode required	string
barcodeType required	string Deprecated Enum: "upc" "ean13" "unknown"
productId required	integer or null
name	string
price	string
thumbnail	string <uri>
weight	number
retailerType required	string Deprecated Enum: "shopify" "unknown"
RIN	string Deprecated Retailer identification number
restricted	boolean

sizeType

required

string

Enum: "plate" "meters"

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

{"shelves": {"property1": {"shelfIndex": 5,
"coordinates": {"dimX": 0,
"dimY": 0,
"dimZ": 0,
"transform": {"translation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
},
"rotation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
}
}
},
"bins": [{"binSize": 0,
"productId": 0,
"productName": "string",
"productBarcode": "string",
"thumbnail": "string",
"restricted": true,
"productUnits": 0,
"unplannedProductsUnits": 0,
"products": [{"quantity": 0,
"product": {"barcode": "850050071228",
"barcodeType": "upc",
"productId": 49427929792799,
"name": "White Claw Black Cherry",
"price": 1,
"thumbnail": "http://example.com",
"weight": 0,
"retailerType": "shopify",
"RIN": "string",
"restricted": true
}
}
]
}
],
"sizeType": "plate"
},
"property2": {"shelfIndex": 5,
"coordinates": {"dimX": 0,
"dimY": 0,
"dimZ": 0,
"transform": {"translation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
},
"rotation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
}
}
},
"bins": [{"binSize": 0,
"productId": 0,
"productName": "string",
"productBarcode": "string",
"thumbnail": "string",
"restricted": true,
"productUnits": 0,
"unplannedProductsUnits": 0,
"products": [{"quantity": 0,
"product": {"barcode": "850050071228",
"barcodeType": "upc",
"productId": 49427929792799,
"name": "White Claw Black Cherry",
"price": 1,
"thumbnail": "http://example.com",
"weight": 0,
"retailerType": "shopify",
"RIN": "string",
"restricted": true
}
}
]
}
],
"sizeType": "plate"
}
}
}

Create a shelf

path Parameters

storeId

required

integer

Id of a physical store. The id is required when retailer want to make a call to specified store.

Request Body schema: application/json
required

gondolaId

required

integer

Id of a gondola

shelfIndex

required

integer

Index of a shelf

object

The coordinates of the shelf

dimX

required

number

dimY

required

number

dimZ

required

number

object (TransformDto)

object (TranslationDto)

translationX required	number
translationY required	number
translationZ required	number

object (RotationDto)

rotationX required	number
rotationY required	number
rotationZ required	number

Responses

Response Schema: application/json

gondolaId

required

integer

Id of a gondola

shelfIndex

required

integer

Index of a shelf

required

object

Coordinates of the shelf

dimX

required

number

dimY

required

number

dimZ

required

number

required

object (TransformAllRequiredDto)

required

object (Pos3DDto)

x required	string <float> x coordinate
y required	string <float> y coordinate
z required	string <float> z coordinate

required

object (Pos3DDto)

x required	string <float> x coordinate
y required	string <float> y coordinate
z required	string <float> z coordinate

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"gondolaId": 2,
"shelfIndex": 5,
"coordinates": {"dimX": 0,
"dimY": 0,
"dimZ": 0,
"transform": {"translation": {"translationX": 0,
"translationY": 0,
"translationZ": 0
},
"rotation": {"rotationX": 0,
"rotationY": 0,
"rotationZ": 0
}
}
}
}

Response samples

201
422

Content type

application/json

{"gondolaId": 2,
"shelfIndex": 5,
"coordinates": {"dimX": 0,
"dimY": 0,
"dimZ": 0,
"transform": {"translation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
},
"rotation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
}
}
}
}

Get shelf by shelf id

path Parameters

storeId required	integer Id of a physical store. The id is required when retailer want to make a call to specified store.
shelfId required	string [ 3 .. 64 ] characters Example: 2-5 Combination of gondola id and shelf index

Responses

Response Schema: application/json

gondolaId

required

integer

Id of a gondola

shelfIndex

required

integer

Index of a shelf

required

object

Coordinates of the shelf

dimX

required

number

dimY

required

number

dimZ

required

number

required

object (TransformAllRequiredDto)

required

object (Pos3DDto)

x required	string <float> x coordinate
y required	string <float> y coordinate
z required	string <float> z coordinate

required

object (Pos3DDto)

x required	string <float> x coordinate
y required	string <float> y coordinate
z required	string <float> z coordinate

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

{"gondolaId": 2,
"shelfIndex": 5,
"coordinates": {"dimX": 0,
"dimY": 0,
"dimZ": 0,
"transform": {"translation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
},
"rotation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
}
}
}
}

Delete shelf by shelf id

path Parameters

storeId required	integer Id of a physical store. The id is required when retailer want to make a call to specified store.
shelfId required	string [ 3 .. 64 ] characters Example: 2-5 Combination of gondola id and shelf index

Responses

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

422

Content type

application/json

{"message": "Invalid request body",
"type": "E_INVALID_BODY",
"errors": [{"error": "\"email\" is required",
"rule": "any.required",
"field": "\"email\""
}
]
}

Update shelf coordinates by shelf id

path Parameters

storeId required	integer Id of a physical store. The id is required when retailer want to make a call to specified store.
shelfId required	string [ 3 .. 64 ] characters Example: 2-5 Combination of gondola id and shelf index

Request Body schema: application/json
required

required

object

The coordinates of the shelf

dimX

required

number

dimY

required

number

dimZ

required

number

object (TransformDto)

object (TranslationDto)

translationX required	number
translationY required	number
translationZ required	number

object (RotationDto)

rotationX required	number
rotationY required	number
rotationZ required	number

Responses

Response Schema: application/json

gondolaId

required

integer

Id of a gondola

shelfIndex

required

integer

Index of a shelf

required

object

Coordinates of the shelf

dimX

required

number

dimY

required

number

dimZ

required

number

required

object (TransformAllRequiredDto)

required

object (Pos3DDto)

x required	string <float> x coordinate
y required	string <float> y coordinate
z required	string <float> z coordinate

required

object (Pos3DDto)

x required	string <float> x coordinate
y required	string <float> y coordinate
z required	string <float> z coordinate

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"coordinates": {"dimX": 0,
"dimY": 0,
"dimZ": 0,
"transform": {"translation": {"translationX": 0,
"translationY": 0,
"translationZ": 0
},
"rotation": {"rotationX": 0,
"rotationY": 0,
"rotationZ": 0
}
}
}
}

Response samples

200
422

Content type

application/json

{"gondolaId": 2,
"shelfIndex": 5,
"coordinates": {"dimX": 0,
"dimY": 0,
"dimZ": 0,
"transform": {"translation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
},
"rotation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
}
}
}
}

Get shelves inventory

path Parameters

storeId required	integer Id of a physical store. The id is required when retailer want to make a call to specified store.
shelfId required	string [ 3 .. 64 ] characters Example: 2-5 Combination of gondola id and shelf index

Responses

Response Schema: application/json

shelfIndex

required

integer

Index of a shelf

required

object

Coordinates of the shelf

dimX

required

number

dimY

required

number

dimZ

required

number

required

object (TransformAllRequiredDto)

required

object (Pos3DDto)

x required	string <float> x coordinate
y required	string <float> y coordinate
z required	string <float> z coordinate

required

object (Pos3DDto)

x required	string <float> x coordinate
y required	string <float> y coordinate
z required	string <float> z coordinate

required

Array of objects (ShelfBinDto)

Array

binSize

required

number

productId

required

integer or null

Id of the product which should be present in this bin

productName

required

string or null

Name of the product which should be present in this bin

productBarcode

required

string or null

Barcode of the product which should be present in this bin

thumbnail

required

string or null

Thumbnail of the product which should be present in this bin

restricted

required

boolean or null

Whether the product is a restriction item

productUnits

required

number or null

Number of all products in the bin that are supposed to be there

unplannedProductsUnits

number

Number of all products in the bin that are not supposed to be there

Array of objects (BinPlanogramDto)

All products that are present in the bin

Array

quantity

required

number

required

object (BinProductDto)

barcode required	string
barcodeType required	string Deprecated Enum: "upc" "ean13" "unknown"
productId required	integer or null
name	string
price	string
thumbnail	string <uri>
weight	number
retailerType required	string Deprecated Enum: "shopify" "unknown"
RIN	string Deprecated Retailer identification number
restricted	boolean

sizeType

required

string

Enum: "plate" "meters"

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

{"shelfIndex": 5,
"coordinates": {"dimX": 0,
"dimY": 0,
"dimZ": 0,
"transform": {"translation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
},
"rotation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
}
}
},
"bins": [{"binSize": 0,
"productId": 0,
"productName": "string",
"productBarcode": "string",
"thumbnail": "string",
"restricted": true,
"productUnits": 0,
"unplannedProductsUnits": 0,
"products": [{"quantity": 0,
"product": {"barcode": "850050071228",
"barcodeType": "upc",
"productId": 49427929792799,
"name": "White Claw Black Cherry",
"price": 1,
"thumbnail": "http://example.com",
"weight": 0,
"retailerType": "shopify",
"RIN": "string",
"restricted": true
}
}
]
}
],
"sizeType": "plate"
}

Get gondola planogram

path Parameters

storeId required	integer Id of a physical store. The id is required when retailer want to make a call to specified store.
gondolaId required	integer Example: 2 Id of a gondola

query Parameters

tOrigin

string <date-time>

Example: tOrigin=2023-07-03T10:00:00.000Z

Responses

Response Schema: application/json

tOrigin

string <date-time>

gondolas

required

Array of integers

currentGondola

required

integer or null

required

object or null

required

object

additional property

object (ShelfInventoryDto)

shelfIndex

required

integer

Index of a shelf

required

object

Coordinates of the shelf

dimX

required

number

dimY

required

number

dimZ

required

number

required

object (TransformAllRequiredDto)

required

object (Pos3DDto)

x required	string <float> x coordinate
y required	string <float> y coordinate
z required	string <float> z coordinate

required

object (Pos3DDto)

x required	string <float> x coordinate
y required	string <float> y coordinate
z required	string <float> z coordinate

required

Array of objects (ShelfBinDto)

Array

binSize

required

number

productId

required

integer or null

Id of the product which should be present in this bin

productName

required

string or null

Name of the product which should be present in this bin

productBarcode

required

string or null

Barcode of the product which should be present in this bin

thumbnail

required

string or null

Thumbnail of the product which should be present in this bin

restricted

required

boolean or null

Whether the product is a restriction item

productUnits

required

number or null

Number of all products in the bin that are supposed to be there

unplannedProductsUnits

number

Number of all products in the bin that are not supposed to be there

Array of objects (BinPlanogramDto)

All products that are present in the bin

Array

quantity

required

number

required

object (BinProductDto)

barcode required	string
barcodeType required	string Deprecated Enum: "upc" "ean13" "unknown"
productId required	integer or null
name	string
price	string
thumbnail	string <uri>
weight	number
retailerType required	string Deprecated Enum: "shopify" "unknown"
RIN	string Deprecated Retailer identification number
restricted	boolean

sizeType

required

string

Enum: "plate" "meters"

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

{"tOrigin": "2023-07-03T10:00:00.000Z",
"gondolas": [0
],
"currentGondola": 0,
"gondolaPlanogram": {"shelves": {"property1": {"shelfIndex": 5,
"coordinates": {"dimX": 0,
"dimY": 0,
"dimZ": 0,
"transform": {"translation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
},
"rotation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
}
}
},
"bins": [{"binSize": 0,
"productId": 0,
"productName": "string",
"productBarcode": "string",
"thumbnail": "string",
"restricted": true,
"productUnits": 0,
"unplannedProductsUnits": 0,
"products": [{"quantity": 0,
"product": {"barcode": "850050071228",
"barcodeType": "upc",
"productId": 49427929792799,
"name": "White Claw Black Cherry",
"price": 1,
"thumbnail": "http://example.com",
"weight": 0,
"retailerType": "shopify",
"RIN": "string",
"restricted": true
}
}
]
}
],
"sizeType": "plate"
},
"property2": {"shelfIndex": 5,
"coordinates": {"dimX": 0,
"dimY": 0,
"dimZ": 0,
"transform": {"translation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
},
"rotation": {"x": "0.8978",
"y": "0.0254",
"z": "2.1645"
}
}
},
"bins": [{"binSize": 0,
"productId": 0,
"productName": "string",
"productBarcode": "string",
"thumbnail": "string",
"restricted": true,
"productUnits": 0,
"unplannedProductsUnits": 0,
"products": [{"quantity": 0,
"product": {"barcode": "850050071228",
"barcodeType": "upc",
"productId": 49427929792799,
"name": "White Claw Black Cherry",
"price": 1,
"thumbnail": "http://example.com",
"weight": 0,
"retailerType": "shopify",
"RIN": "string",
"restricted": true
}
}
]
}
],
"sizeType": "plate"
}
}
}
}

Set shelf planogram

path Parameters

storeId required	integer Id of a physical store. The id is required when retailer want to make a call to specified store.
gondolaId required	integer Example: 2 Id of a gondola

Request Body schema: application/json
required

shelfIndex

required

integer

Index of a shelf

required

Array of objects (SetPlanogramBinDto)

Array

size required	integer Number of plates that the bin consists of
productId required	integer Id of product in AiFi system

sizeType

string

Default: "plate"

Enum: "plate" "meters"

Responses

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"shelfIndex": 5,
"bins": [{"size": 0,
"productId": 0
}
],
"sizeType": "plate"
}

Response samples

422

Content type

application/json

{"message": "Invalid request body",
"type": "E_INVALID_BODY",
"errors": [{"error": "\"email\" is required",
"rule": "any.required",
"field": "\"email\""
}
]
}

Update inventory

path Parameters

storeId required	integer Id of a physical store. The id is required when retailer want to make a call to specified store.
shelfId required	string [ 3 .. 64 ] characters Example: 2-5 Combination of gondola id and shelf index
binIndex required	integer >= 0 Index of target bin

Request Body schema: application/json
required

One of

required

object (InventoryRequestProductDto)

barcode required	string
barcodeType	string Enum: "upc" "ean13" "unknown"

quantityDifference

required

integer [ -1000 .. 1000 ]

Update with quantity difference

Responses

Response Schema: application/json

gondolaId

required

integer

Id of a gondola

shelfIndex

required

integer

Index of a shelf

id

required

string [ 3 .. 64 ] characters

Combination of gondola id and shelf index

required

object

Coordinates of the shelf

dimX

required

number

dimY

required

number

dimZ

required

number

object (TransformDto)

object (TranslationDto)

translationX required	number
translationY required	number
translationZ required	number

object (RotationDto)

rotationX required	number
rotationY required	number
rotationZ required	number

required

Array of objects (UpdateInventoryBinResponseDto)

Array

Array of objects (InventoryProductAndQuantityDto)

Array

required

object (InventoryBinProductDto)

barcode required	string
barcodeType required	string Deprecated Enum: "upc" "ean13" "unknown"
name	string
price	string
thumbnail	string <uri>
weight	number
retailerType required	string Deprecated Enum: "shopify" "unknown"
RIN	string Deprecated Retailer identification number
restricted	boolean

quantity

required

integer

size

required

number

required

object (InventoryDefaultProductDto)

barcode required	string
barcodeType	string Enum: "upc" "ean13" "unknown"

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

Example

UpdateInventoryWithDiffRequestDto

{"product": {"barcode": "850050071228",
"barcodeType": "upc"
},
"quantityDifference": -1000
}

Response samples

200
422

Content type

application/json

{"gondolaId": 2,
"shelfIndex": 5,
"id": "2-5",
"coordinates": {"dimX": 0,
"dimY": 0,
"dimZ": 0,
"transform": {"translation": {"translationX": 0,
"translationY": 0,
"translationZ": 0
},
"rotation": {"rotationX": 0,
"rotationY": 0,
"rotationZ": 0
}
}
},
"bins": [{"products": [{"product": {"barcode": "850050071228",
"barcodeType": "upc",
"name": "White Claw Black Cherry",
"price": 1,
"thumbnail": "http://example.com",
"weight": 0,
"retailerType": "shopify",
"RIN": "string",
"restricted": true
},
"quantity": 0
}
],
"size": 0,
"defaultProduct": {"barcode": "850050071228",
"barcodeType": "upc"
}
}
]
}

Check parcels

path Parameters

storeId

required

integer

Id of a physical store. The id is required when retailer want to make a call to specified store.

Request Body schema: application/json
required

customerId

required

integer

Id of customer

required

Array of objects (ParcelProductDto)

Array

barcode required	string
quantity required	integer >= 1

Responses

Response Schema: application/json

status

required

string

Enum: "CORRECT" "PARCEL_NOT_OWNED"

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"customerId": 0,
"parcels": [{"barcode": "string",
"quantity": 1
}
]
}

Response samples

200
422

Content type

application/json

{"status": "CORRECT"
}

Verify entry-code by entry Deprecated

DEPRECATED - use verify QR code by device

path Parameters

storeId required	integer Id of a physical store. The id is required when retailer want to make a call to specified store.
entryId required	string

Request Body schema: application/json
required

verificationCode

required

string

An entry code that can rendered as QR and used to enter AiFi store

Responses

Response Schema: application/json

One of

status required	string Value: "OK" validation success
sessionId required	string A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.
groupSize required	integer expected number of people to enter the store
role required	string Enum: "customer" "employee" "tester" "untracked" "unknown" role of the customer

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"verificationCode": "string"
}

Response samples

200
422

Content type

application/json

Example

VerifyEntryCodeResponseDto

{"status": "OK",
"sessionId": "string",
"groupSize": 0,
"role": "customer"
}

Verify entry code and check in by device id

Endpoint returns 200 http code also in all instances when the code was successfully
examined but rejected from one of the reasons bellow.

Http error codes are used only when there are other errors preventing the check.


When the code is validated successfully, the response includes `status:OK` and `sessionId`, `sessionId`
is _customer's shopping session id_ (also referenced as transactionId on some AIFI
diagrams).

When the code is validated failed, the response includes `status:FAILED` and `reason`.

List of possible reasons for which the code could get rejected:


message: 'Invalid verification code',

code: 1,


message: 'Verification code has expired',

code: 2,


message: 'Verification code was already used',

code: 3,


message: 'Verification code was already declined',

code: 4,


message: 'Verification code was issued for different store',

code: 5,


message: 'Customer was not found',

code: 6,


message: "Customer doesn't have associated stripe customerId",

code: 7,


message: "Customer doesn't have payment method set up",

code: 8,


message: "Customer has unsettled transactions"

code: 9,


message: "Customer's card is expired"

code: 10,


message: "The limit of people in this store was reached"

code: 11,


message: "The store is closed"

code: 12,


message: "The store is closed for maintenance"

code: 13,


message: "External verification error"

code: 14,


message: "Couldn't pre-authorize required amount on customer's card"

code: 15,

path Parameters

storeId required	integer Id of a physical store. The id is required when retailer want to make a call to specified store.
checkInDeviceId required	integer

Request Body schema: application/json
required

verificationCode

required

string

An entry code that can rendered as QR and used to enter AiFi store

Responses

Response Schema: application/json

One of

status required	string Value: "OK" validation success
sessionId required	string A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.
groupSize required	integer expected number of people to enter the store
role required	string Enum: "customer" "employee" "tester" "untracked" "unknown" role of the customer

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"verificationCode": "string"
}

Response samples

200
422

Content type

application/json

Example

VerifyEntryCodeResponseDto

{"status": "OK",
"sessionId": "string",
"groupSize": 0,
"role": "customer"
}

Create check tasks

path Parameters

storeId

required

integer

Id of a physical store. The id is required when retailer want to make a call to specified store.

Request Body schema: application/json
required

shelfId required	string [ 3 .. 64 ] characters Combination of gondola id and shelf index
binIndex	integer >= 0 Index of target bin

Responses

Response Schema: application/json

code required	number
msg required	string

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"shelfId": "2-5",
"binIndex": 0
}

Response samples

201
422

Content type

application/json

{"code": 0,
"msg": "string"
}

Get list of cameras

path Parameters

storeId

required

integer

Id of a physical store. The id is required when retailer want to make a call to specified store.

Responses

Response Schema: application/json

Array

id required	integer
cameraType required	string Enum: "unknown" "rgb" "depth"
k1	string
k2	string
p1	string
p2	string
fx	string
fy	string
cx	string
cy	string
rotationX	string
rotationY	string
rotationZ	string
translationX	string
translationY	string
translationZ	string

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

[{"id": 0,
"cameraType": "unknown",
"k1": "0.0",
"k2": "0.0",
"p1": "0.0",
"p2": "0.0",
"fx": "0.0",
"fy": "0.0",
"cx": "0.0",
"cy": "0.0",
"rotationX": "0.0",
"rotationY": "0.0",
"rotationZ": "0.0",
"translationX": "0.0",
"translationY": "0.0",
"translationZ": "0.0"
}
]

Get a camera by id

path Parameters

storeId required	integer Id of a physical store. The id is required when retailer want to make a call to specified store.
cameraId required	integer >= 1 Id of the camera

Responses

Response Schema: application/json

id required	integer
cameraType required	string Enum: "unknown" "rgb" "depth"
k1	string
k2	string
p1	string
p2	string
fx	string
fy	string
cx	string
cy	string
rotationX	string
rotationY	string
rotationZ	string
translationX	string
translationY	string
translationZ	string

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

{"id": 0,
"cameraType": "unknown",
"k1": "0.0",
"k2": "0.0",
"p1": "0.0",
"p2": "0.0",
"fx": "0.0",
"fy": "0.0",
"cx": "0.0",
"cy": "0.0",
"rotationX": "0.0",
"rotationY": "0.0",
"rotationZ": "0.0",
"translationX": "0.0",
"translationY": "0.0",
"translationZ": "0.0"
}

Get on-prem services health

path Parameters

storeId

required

integer

Id of a physical store. The id is required when retailer want to make a call to specified store.

Responses

Response Schema: application/json

status

required

string

Enum: "UNKNOWN" "OK" "WARNING" "CRITICAL"

Overall status

version

required

string

Version of store-api

required

Array of objects (StatusMessageDto)

Array

status required	string Enum: "UNKNOWN" "OK" "WARNING" "CRITICAL"
message required	string

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

{"status": "UNKNOWN",
"version": "string",
"statusMessages": [{"status": "UNKNOWN",
"message": "string"
}
]
}

Get customers count

path Parameters

storeId

required

integer

Id of a physical store. The id is required when retailer want to make a call to specified store.

Responses

Response Schema: application/json

count

required

integer

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

{"count": 0
}

Update an event by event id

path Parameters

storeId required	integer Id of a physical store. The id is required when retailer want to make a call to specified store.
eventId required	string id of an event

Request Body schema: application/json
required

shopperId

required

string

identifier of the shopper

Array of objects (EventAnnotationProductDto)

Array

productId required	string identifier of a product
quantity required	integer quantity of a product
binIndex required	integer >= 1 index of the target bin
shelfIndex required	integer >= 1 index of the target shelf
gondolaId required	integer >= 1 index of the target gondola

Responses

Response Schema: application/json

shopperId required	string identifier of the shopper
eventId required	string id of an event

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"shopperId": "string",
"products": [{"productId": "string",
"quantity": 0,
"binIndex": 1,
"shelfIndex": 1,
"gondolaId": 1
}
]
}

Response samples

200
422

Content type

application/json

{"shopperId": "string",
"eventId": "string"
}

Update an event by event id, events annotation for backward compatibility

path Parameters

eventId

required

string

id of an event

Request Body schema: application/json
required

shopperId

required

string

identifier of the shopper

Array of objects (EventAnnotationProductDto)

Array

productId required	string identifier of a product
quantity required	integer quantity of a product
binIndex required	integer >= 1 index of the target bin
shelfIndex required	integer >= 1 index of the target shelf
gondolaId required	integer >= 1 index of the target gondola

Responses

Response Schema: application/json

shopperId required	string identifier of the shopper
eventId required	string id of an event

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"shopperId": "string",
"products": [{"productId": "string",
"quantity": 0,
"binIndex": 1,
"shelfIndex": 1,
"gondolaId": 1
}
]
}

Response samples

200
422

Content type

application/json

{"shopperId": "string",
"eventId": "string"
}

Confirm an event by event id

path Parameters

storeId required	integer Id of a physical store. The id is required when retailer want to make a call to specified store.
eventId required	string id of an event

Request Body schema: application/json
required

shopperId

required

string

identifier of the shopper

Array of objects (EventAnnotationProductDto)

Array

productId required	string identifier of a product
quantity required	integer quantity of a product
binIndex required	integer >= 1 index of the target bin
shelfIndex required	integer >= 1 index of the target shelf
gondolaId required	integer >= 1 index of the target gondola

Responses

Response Schema: application/json

shopperId required	string identifier of the shopper
eventId required	string id of an event

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"shopperId": "string",
"products": [{"productId": "string",
"quantity": 0,
"binIndex": 1,
"shelfIndex": 1,
"gondolaId": 1
}
]
}

Response samples

200
422

Content type

application/json

{"shopperId": "string",
"eventId": "string"
}

Confirm an event by event id, events annotation for backward compatibility

path Parameters

eventId

required

string

id of an event

Request Body schema: application/json
required

shopperId

required

string

identifier of the shopper

Array of objects (EventAnnotationProductDto)

Array

productId required	string identifier of a product
quantity required	integer quantity of a product
binIndex required	integer >= 1 index of the target bin
shelfIndex required	integer >= 1 index of the target shelf
gondolaId required	integer >= 1 index of the target gondola

Responses

Response Schema: application/json

shopperId required	string identifier of the shopper
eventId required	string id of an event

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"shopperId": "string",
"products": [{"productId": "string",
"quantity": 0,
"binIndex": 1,
"shelfIndex": 1,
"gondolaId": 1
}
]
}

Response samples

200
422

Content type

application/json

{"shopperId": "string",
"eventId": "string"
}

Create an event for a third party device

path Parameters

storeId required	integer Id of a physical store. The id is required when retailer want to make a call to specified store.
thirdPartyDeviceId required	string Id of the third party device

Request Body schema: application/json
required

uuid

required

string <uuid>

timestamp

required

integer

unix timestamp (in seconds) when this event occured

required

Array of objects (EventProductDto)

Array

productReference required	string
quantity required	integer
referenceType	string Default: "barcode" Enum: "barcode" "id" "externalId"

object

property name*

additional property

any

Responses

Response Schema: application/json

uuid required	string <uuid> The id of the event
sourceId required	string The id of the third party device

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"uuid": "04178fa1-0b07-4e3f-b3ca-6c60d528cf82",
"timestamp": 1611928852,
"products": [{"productReference": "1234567890128",
"quantity": 1,
"referenceType": "barcode"
}
],
"metadata": "{\"key\": \"value\"}"
}

Response samples

201
422

Content type

application/json

{"uuid": "04178fa1-0b07-4e3f-b3ca-6c60d528cf82",
"sourceId": "string"
}

Delete a third party device event by event id

path Parameters

storeId required	integer Id of a physical store. The id is required when retailer want to make a call to specified store.
thirdPartyDeviceId required	string Id of the third party device
eventId required	string id of the event

Responses

Response Schema: application/json

uuid required	string <uuid> The id of the event
sourceId required	string The id of the third party device

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

204
422

Content type

application/json

{"uuid": "04178fa1-0b07-4e3f-b3ca-6c60d528cf82",
"sourceId": "string"
}

Create an event for a shopper

path Parameters

storeId

required

integer

Id of a physical store. The id is required when retailer want to make a call to specified store.

Request Body schema: application/json
required

uuid

required

string <uuid>

timestamp

required

integer

unix timestamp (in seconds) when this event occured

required

Array of objects (EventProductDto)

Array

productReference required	string
quantity required	integer
referenceType	string Default: "barcode" Enum: "barcode" "id" "externalId"

object

property name*

additional property

any

shopperId

required

string

Identifier of the Shopper

Responses

Response Schema: application/json

uuid required	string <uuid> The id of the event
sourceId required	string The id of the third party device

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"uuid": "04178fa1-0b07-4e3f-b3ca-6c60d528cf82",
"timestamp": 1611928852,
"products": [{"productReference": "1234567890128",
"quantity": 1,
"referenceType": "barcode"
}
],
"metadata": "{\"key\": \"value\"}",
"shopperId": "string"
}

Response samples

201
422

Content type

application/json

{"uuid": "04178fa1-0b07-4e3f-b3ca-6c60d528cf82",
"sourceId": "string"
}

Create an frame annotation event for IDAP

path Parameters

storeId required	integer Id of a physical store. The id is required when retailer want to make a call to specified store.
idapDeviceId required	string Example: 37a426e5-f432-4f1c-9563-f6a8c795ca39 Id of the IDAP device

Request Body schema: application/json
required

timestamp

required

integer

unix timestamp (in milliseconds) when this event occurred

uniqueEventId

required

string <= 256 characters

unique id of the event

sessionId

string or null <= 256 characters

Default: null

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.

oldShopperId

string or null

Default: null

Identifier of previous shopper that did reid

required

object (MetadataDto)

subsystem required	string Enum: "FACE" "TAP"
faceX1	number Required only when subsystem=FACE
faceY1	number Required only when subsystem=FACE
faceX2	number Required only when subsystem=FACE
faceY2	number Required only when subsystem=FACE
distanceM	number Required only when subsystem=FACE
externalId	string <= 256 characters Required only when subsystem=FACE
detectionSequenceId	number <= 256 characters Required only when subsystem=FACE

Responses

Response Schema: application/json

uniqueEventId

required

string <= 256 characters

unique id of the event

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"timestamp": 1709171638704,
"uniqueEventId": "bbd3fb79-f6c0-44df-bee0-0647e51b6c83",
"sessionId": null,
"oldShopperId": null,
"metadata": {"subsystem": "FACE",
"faceX1": 624,
"faceY1": 694,
"faceX2": 296,
"faceY2": 376,
"distanceM": 3.12,
"externalId": "25ff492f-ed5b-4e89-a06e-adbb38c6f094",
"detectionSequenceId": 0
}
}

Response samples

200
422

Content type

application/json

{"uniqueEventId": "bbd3fb79-f6c0-44df-bee0-0647e51b6c83"
}

Session confirmation api proxy

path Parameters

storeId required	integer Id of a physical store. The id is required when retailer want to make a call to specified store.
sessionId required	string A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.

Responses

Response Schema: application/json

id required	string A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.
transactionId required	integer
confirmation required	string Enum: "manual" "auto" "none"
shoppersRole required	string Enum: "customer" "employee" "tester" "untracked" "unknown"

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

{"id": "string",
"transactionId": 0,
"confirmation": "manual",
"shoppersRole": "customer"
}

Correct reid

path Parameters

storeId

required

integer

Id of a physical store. The id is required when retailer want to make a call to specified store.

Request Body schema: application/json
required

shopperId required	string identifier of the shopper
shopperReId required	string the correct reid of the shopper

Responses

Response Schema: application/json

shopperId required	string identifier of the shopper
shopperReId required	string the correct reid of the shopper
shoppingSessionId required	string A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"shopperId": "string",
"shopperReId": "string"
}

Response samples

200
422

Content type

application/json

{"shopperId": "string",
"shopperReId": "string",
"shoppingSessionId": "string"
}

Update the specific shopper

path Parameters

storeId required	integer Id of a physical store. The id is required when retailer want to make a call to specified store.
shopperId required	string identifier of the shopper

Request Body schema: application/json
required

sessionId

required

string

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.

Responses

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"sessionId": "string"
}

Response samples

422

Content type

application/json

{"message": "Invalid request body",
"type": "E_INVALID_BODY",
"errors": [{"error": "\"email\" is required",
"rule": "any.required",
"field": "\"email\""
}
]
}

Update the specific shopper

For a given store, notify about shoppers' identities match

path Parameters

storeId

required

integer

Id of a physical store. The id is required when retailer want to make a call to specified store.

Request Body schema: application/json
required

registeredShopperId required	string Identifier of the shopper belonging to registered session
registeredSessionId required	string SessionId for the registered shopper
visitorShopperId required	string Identifier of the shopper belonging to visitor session
visitorSessionId required	string SessionId for the visitor shopper that was matched with a registered shopper

Responses

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"registeredShopperId": "768593402456789",
"registeredSessionId": "cdf95c70-53e6-4f41-9edd-a288d834c16f",
"visitorShopperId": "766789212312312",
"visitorSessionId": "fdb04f43-f274-4692-a0f5-dc6ea16ba10e"
}

Response samples

422

Content type

application/json

{"message": "Invalid request body",
"type": "E_INVALID_BODY",
"errors": [{"error": "\"email\" is required",
"rule": "any.required",
"field": "\"email\""
}
]
}

Get zones

path Parameters

storeId

required

integer

Id of a physical store. The id is required when retailer want to make a call to specified store.

query Parameters

label

Array of strings

Default: ""

Items Enum: "none" "unknown" "entry" "exit" "checkout" "scanning" "employeeEntrance" "trackingBoundaries" "trackingInvalid" "trackingEntry" "trackingExit" "framesOnPull"

If provided filters result list by zone labels

Responses

Response Schema: application/json

Array

id required	string
labels required	Array of strings Items Enum: "none" "unknown" "entry" "exit" "checkout" "scanning" "employeeEntrance" "trackingBoundaries" "trackingInvalid" "trackingEntry" "trackingExit" "framesOnPull" If provided filters result list by zone labels
name required	string

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

[{"id": "string",
"labels": ["none"
],
"name": "string"
}
]

List RFID tags

path Parameters

storeId

required

integer

Id of a physical store. The id is required when retailer want to make a call to specified store.

query Parameters

offset	integer >= 0 Pagination offset
count	integer [ 1 .. 200 ] Default: 50 Number of results
epc	Array of strings Filter by epc

Responses

Response Schema: application/json

required

object (OffsetBasedPaginationDto)

object

Query parameter to fetch previous page

offset required	integer Pagination offset
count required	integer Number of results

object

Query parameter to fetch next page

offset required	integer Pagination offset
count required	integer Number of results

required

Array of objects (TagResponseDto)

Array

required

object (EpcDto)

id

required

string

epc string

createdAt

required

string <date-time>

ISO formatted date of order creation

updatedAt

required

string <date-time>

ISO formatted date of last order update

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

{"pagination": {"previous": {"offset": 0,
"count": 0
},
"next": {"offset": 0,
"count": 0
}
},
"tags": [{"epc": {"id": "30340bf8dc40882d3e83b804"
},
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
}

Upsert tags

path Parameters

storeId

required

integer

Id of a physical store. The id is required when retailer want to make a call to specified store.

header Parameters

x-batch-strategy

required

string

Enum: "all-or-nothing" "ignore-errors"

all-or-nothing

The endpoint rejects the whole batch when a batch contains invalid epc(s):
- Invalid epc format
- The corresponding product doesn't exist


ignore-errors

The endpoint ignores invalid epc(s) and persist all valid epc(s) to the system.

Request Body schema: application/json
required

required

Array of objects (EpcTagDto)

Multi RFID epc tags

Array

required

object (EpcDto)

id

required

string

epc string

Responses

Response Schema: application/json

required

Array of objects (TagResponseDto)

Successfully upserted tags

Array

required

object (EpcDto)

id

required

string

epc string

createdAt

required

string <date-time>

ISO formatted date of order creation

updatedAt

required

string <date-time>

ISO formatted date of last order update

required

object (UpsertTagErrorDto)

invalidTags required	Array of strings Invalid tags
tagsMissingProduct required	Array of strings Tags which missing corresponding products

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"tags": [{"epc": {"id": "30340bf8dc40882d3e83b804"
}
}
]
}

Response samples

200
422

Content type

application/json

{"success": [{"epc": {"id": "30340bf8dc40882d3e83b804"
},
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"errors": {"invalidTags": ["string"
],
"tagsMissingProduct": ["string"
]
}
}

Delete all RFID tags

path Parameters

storeId

required

integer

Id of a physical store. The id is required when retailer want to make a call to specified store.

Responses

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

422

Content type

application/json

{"message": "Invalid request body",
"type": "E_INVALID_BODY",
"errors": [{"error": "\"email\" is required",
"rule": "any.required",
"field": "\"email\""
}
]
}

Get RFID tag

path Parameters

storeId required	integer Id of a physical store. The id is required when retailer want to make a call to specified store.
id required	string Example: 30340bf8dc40882d3e83b804 epc string

Responses

Response Schema: application/json

required

object (EpcDto)

id

required

string

epc string

createdAt

required

string <date-time>

ISO formatted date of order creation

updatedAt

required

string <date-time>

ISO formatted date of last order update

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

{"epc": {"id": "30340bf8dc40882d3e83b804"
},
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Admin API - retailer

Get retailer config

Responses

Response Schema: application/json

domainName required	string Domain name
powerbiGuid required	string or null Powerbi guid (GUID) string token
createdAt required	string <date-time> ISO formatted date
updatedAt required	string <date-time> ISO formatted date

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

{"domainName": "string",
"powerbiGuid": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Update retailer config

Request Body schema: application/json
required

domainName	string Domain name
powerbiGuid	string or null Powerbi guid (GUID) string token, pass null to clear it

Responses

Response Schema: application/json

domainName required	string Domain name
powerbiGuid required	string or null Powerbi guid (GUID) string token
createdAt required	string <date-time> ISO formatted date
updatedAt required	string <date-time> ISO formatted date

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Request samples

Payload

Content type

application/json

{"domainName": "string",
"powerbiGuid": "string"
}

Response samples

200
422

Content type

application/json

{"domainName": "string",
"powerbiGuid": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Admin API - config

Get system configuration

Responses

Response Schema: application/json

jiraHelpdeskLink

required

string <uri>

Link to jira help desk

required

object

Currency configuration

code required	string Currency code, USD, CNY, etc
symbol required	string Currency symbol, $, ¥, etc

required

object

Product configuration

priceIncludesTax

required

boolean

Whether product price includes tax

required

object

Tax configuration

provider

required

string

Enum: "AIFI" "AVALARA" "NONE"

Tax provider

required

object

Product Categories API configuration

enabled

required

boolean

Whether Product Categories API is enabled

payments

required

object

Payments configuration returned by Generic Payment Bridge. For detailed structure please refer to GPB - Configuration documentation.

Response Schema: application/json

message

required

string

type

required

string

required

Array of objects (ErrorDetailDto)

Array

error required	string A description of the error
rule required	string The validation rule
field required	string Field/path where the error happened

Response samples

200
422

Content type

application/json

{"jiraHelpdeskLink": "https://aifi.jira.com",
"currency": {"code": "USD",
"symbol": "$"
},
"product": {"priceIncludesTax": true
},
"tax": {"provider": "AIFI"
},
"productCategoriesApi": {"enabled": true
},
"payments": { }
}

Push - checkout zone

customer entered a checkout zone

AiFi system shall call this webhook when a customer entered a checkout zone in a given store. This webhook is intended to be only visual: no response is parsed and no action is taken regardless of the response.

Note: as an integrator, the URL you specify for checkout zone webhooks will be re-used for all checkout zone actions. For example, if you specify "http://example-retailer-api.com/webhook", then "http://example-retailer-api.com/webhook/entered" will be called in this case.

Request Body schema: application/json
required

sessionId

required

string

Deprecated

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system. Deprecated, usesession.sessionId

required

object

Customer information

externalId required	string or null Id of the customer in external system
metadata required	object or null This object can contain custom metadata information
id required	string <integer> AiFi customer id, formatted as string
role required	string Enum: "customer" "employee" "tester" "untracked" "unknown" Role of the customer

storeId

required

integer

AiFi store id

required

object (StoreIdsDto)

oasisApiStoreId required	integer Store identifier that is only internal to cloud-api
aifiUniqueStoreId required	string or null Unique identifier across all AiFi stores. it will only be filled in by TechOPS/deployment engineers

storeExternalId

required

string or null

Retailer store id

timeOfOrigin

required

string <date-time>

ISO formatted creation time of the event, that caused this webhook to be sent

timeOfIssue

required

string <date-time>

ISO formatted time, in which this webhook was sent

required

object or object

One of

createdAt

required

string <date-time>

ISO formatted date representing when the entity was created

updatedAt

required

string <date-time>

ISO formatted date representing when the entity was last updated

id

required

integer

customerId

required

integer

AiFi customer id

code

required

string

An entry code that can rendered as QR and used to enter AiFi store

codeFirstSuccesfullyScannedAt

required

string or null <date-time>

ISO formatted date, the first time when the QR get scanned successfully

codeLastSuccesfullyScannedAt

required

string or null <date-time>

ISO formatted date, the last time when the QR get scanned successfully

customerFirstEnteredAt

required

string or null <date-time>

ISO formatted time, when the first shopper enter the store

customerLastEnteredAt

required

string or null <date-time>

ISO formatted time, when the last shopper enter the store

customerFirstExitedAt

required

string or null <date-time>

ISO formatted time, when the first shopper exit the store

customerLastExitedAt

required

string or null <date-time>

ISO formatted time, when the last shopper exit the store

customerPaymentInstrumentId

required

integer or null

Payment instrument id

customerSatisfaction

required

integer or null [ 0 .. 100 ]

Satisfaction from the shopping session submitted by the customer. Can be null if not submitted or when customer wished to not ask him.

customerSatisfactionSubmitted

required

boolean

Default: false

Whether satisfaction has been submitted

groupSize

required

integer

Expected group size associated with the shopping session

visitors

required

integer

Actual group size associated with the shopping session

locationId

required

string or null

priority

required

integer [ -10 .. 10 ]

Default: 0

Customer priority. default to 0, which means any regular customer. customers with higher priority will have their shopping sessions prioritized during processing, the lower priority is opposite.

sessionToken

required

string

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.

sessionId

required

string

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.

referencedSessionId

required

string or null

Default: null

Referenced session token, that points to the source session

status

required

string

Enum: "active" "declined" "validated" "checkout_performed"

storeId

required

integer or null

AiFi store id

storeIdScannableAt

required

integer or null

the id of store which the QrCode of test case can be valided. It can be scanned at any store if the value is null.

suspectedFraud

required

boolean

Default: false

Indicate whether the shopping session is suspected fraud

metadata

required

object

Represents an arbitrary object. Note that the events key is reserved by AiFi for ThirdParty and Handoff Events. The value provided in the metadata field will completely overwrite the existing object. If your integration depends on the events key in the metadata, ensure it is preserved to avoid accidental deletion. To add new keys to the existing metadata object:

Retrieve the current metadata using the Get Session List endpoint.
Merge the retrieved metadata with the new keys you wish to add.
Submit the updated object in the metadata field.

Be cautious, as replacing the metadata value without preserving necessary keys may lead to unintended data loss.

expiresAt

required

string <date-time>

ISO formatted date at which this entry code will expire

shoppingSessionFlags

Array of strings

Items Enum: "POTENTIALLY_INTERACTED_WITH_ALCOHOL" "POTENTIALLY_SUSPICIOUS_BEHAVIOUR"

interactionsCount

number

restrictedInteractionsCount

number

Array of objects (InterestGroupInteractionCounterDto)

List of interest groups with their interaction counts

Array

id required	string Interest group identifier
name required	string Interest group name
interactionsCount required	integer >= 0 Number of interactions for this interest group

checkoutZoneId

required

string

For old integrations it will be sent as an integer, while for new ones it will be a string. Eventually all integrations will be converted to strings.

specialAttention

boolean

Deprecated

shoppingSessionFlags

Array of strings

Deprecated

Items Enum: "POTENTIALLY_INTERACTED_WITH_ALCOHOL" "POTENTIALLY_SUSPICIOUS_BEHAVIOUR"

required

object

Object holding information about the shopper who triggered the webhook

shopperId

required

string

Identifier of the Shopper

shopperFlags

string

Enum: "POTENTIALLY_INTERACTED_WITH_ALCOHOL" "POTENTIALLY_SUSPICIOUS_BEHAVIOUR"

interactionsCount

integer

Total number of shopper's interactions

restrictedInteractionsCount

integer

Total number of shopper's interactions with restricted items

reappeared

boolean

Indicates whether shopper reappeared

Array of objects (InterestGroupInteractionCounterDto)

List of interest groups with their interaction counts

Array

id required	string Interest group identifier
name required	string Interest group name
interactionsCount required	integer >= 0 Number of interactions for this interest group

Array of objects (CheckoutZoneCartItemDto)

Available only if the webhook is configured with option 'send_cart'

Array

id

required

string <integer>

Deprecated

Deprecated, use productSnapshot.productId

name

required

string

Deprecated

Deprecated, use productSnapshot.name

barcode

required

string

Deprecated

Deprecated, use productSnapshot.barcode

category

required

string or null

Deprecated

Deprecated, use productSnapshot.category

sku

required

string or null

Deprecated

Deprecated, use productSnapshot.sku

thumbnail

required

string or null

Deprecated

Deprecated, use productSnapshot.thumbnail

externalId

required

string or null

Deprecated

Deprecated, use productSnapshot.externalId

price

required

number

Deprecated

Deprecated, use productSnapshot.price

quantity

required

integer

quantity of a product

required

object (ProductSnapshotDto)

name required	string
price required	string or null <float> Unit price for single item, depending on configuration it may either contain the tax (suitable e.g. for integrations in EU) or not (suitable e.g. for integrations in the US)
barcode required	string Default barcode of default variant for this product
category required	string or null Deprecated
thumbnail required	string or null URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.
weight required	number or null Weight of a default variant
sku required	string or null Deprecated
externalId required	string or null Client defined product identifier
taxCode required	string or null Avalara tax code, available ig avalara integration is enabled
id required	integer
productId required	integer id of the product
createdAt required	string <date-time> ISO formatted date
updatedAt required	string <date-time> ISO formatted date

Responses

Response Schema: application/json

string

Request samples

Payload

Content type

application/json

{"sessionId": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"customer": {"externalId": "string",
"metadata": {"arbitraryKey": "arbitraryValue"
},
"id": "string",
"role": "customer"
},
"storeId": 0,
"store": {"oasisApiStoreId": 0,
"aifiUniqueStoreId": "string"
},
"storeExternalId": "string",
"timeOfOrigin": "2019-08-24T14:15:22Z",
"timeOfIssue": "2019-08-24T14:15:22Z",
"session": {"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"id": 0,
"customerId": 0,
"code": "c69bb289-1190-4156-b9f6-bfb7f61e85db",
"codeFirstSuccesfullyScannedAt": "2019-08-24T14:15:22Z",
"codeLastSuccesfullyScannedAt": "2019-08-24T14:15:22Z",
"customerFirstEnteredAt": "2019-08-24T14:15:22Z",
"customerLastEnteredAt": "2019-08-24T14:15:22Z",
"customerFirstExitedAt": "2019-08-24T14:15:22Z",
"customerLastExitedAt": "2019-08-24T14:15:22Z",
"customerPaymentInstrumentId": 0,
"customerSatisfaction": 95,
"customerSatisfactionSubmitted": false,
"groupSize": 0,
"visitors": 0,
"locationId": "string",
"priority": 0,
"sessionToken": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"sessionId": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"referencedSessionId": null,
"status": "active",
"storeId": 0,
"storeIdScannableAt": 0,
"suspectedFraud": false,
"metadata": {"events": [{"eventId": "6bdbfb2d-65b2-491c-bc97-c0ac73338476",
"metadata": {"key": "value"
}
}
],
"exampleKey": "exampleValue"
},
"expiresAt": "2019-08-24T14:15:22Z",
"shoppingSessionFlags": ["POTENTIALLY_INTERACTED_WITH_ALCOHOL"
],
"interactionsCount": 0,
"restrictedInteractionsCount": 0,
"interestGroups": [{"id": "string",
"name": "string",
"interactionsCount": 0
}
]
},
"checkoutZoneId": "string",
"specialAttention": true,
"shoppingSessionFlags": ["POTENTIALLY_INTERACTED_WITH_ALCOHOL"
],
"shopper": {"shopperId": "string",
"shopperFlags": "POTENTIALLY_INTERACTED_WITH_ALCOHOL",
"interactionsCount": 0,
"restrictedInteractionsCount": 0,
"reappeared": true,
"interestGroups": [{"id": "string",
"name": "string",
"interactionsCount": 0
}
]
},
"cart": [{"id": "string",
"name": "string",
"barcode": "string",
"category": "string",
"sku": "string",
"thumbnail": "string",
"externalId": "string",
"price": 0,
"quantity": 0,
"productSnapshot": {"name": "string",
"price": "string",
"barcode": "string",
"category": "string",
"thumbnail": "string",
"weight": 0,
"sku": "string",
"externalId": "string",
"taxCode": "string",
"id": 0,
"productId": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
}
]
}

Response samples

200

Content type

application/json

"string"

customer left a checkout zone

AiFi system shall call this webhook when a customer left a checkout zone in a given store. This webhook is intended to be only visual: no response is parsed and no action is taken regardless of the response.

Note: as an integrator, the URL you specify for checkout zone webhooks will be re-used for all checkout zone actions. For example, if you specify "http://example-retailer-api.com/webhook", then "http://example-retailer-api.com/webhook/left" will be called in this case.

Request Body schema: application/json
required

sessionId

required

string

Deprecated

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system. Deprecated, usesession.sessionId

required

object

Customer information

externalId required	string or null Id of the customer in external system
metadata required	object or null This object can contain custom metadata information
id required	string <integer> AiFi customer id, formatted as string
role required	string Enum: "customer" "employee" "tester" "untracked" "unknown" Role of the customer

storeId

required

integer

AiFi store id

required

object (StoreIdsDto)

oasisApiStoreId required	integer Store identifier that is only internal to cloud-api
aifiUniqueStoreId required	string or null Unique identifier across all AiFi stores. it will only be filled in by TechOPS/deployment engineers

storeExternalId

required

string or null

Retailer store id

timeOfOrigin

required

string <date-time>

ISO formatted creation time of the event, that caused this webhook to be sent

timeOfIssue

required

string <date-time>

ISO formatted time, in which this webhook was sent

required

object or object

One of

createdAt

required

string <date-time>

ISO formatted date representing when the entity was created

updatedAt

required

string <date-time>

ISO formatted date representing when the entity was last updated

id

required

integer

customerId

required

integer

AiFi customer id

code

required

string

An entry code that can rendered as QR and used to enter AiFi store

codeFirstSuccesfullyScannedAt

required

string or null <date-time>

ISO formatted date, the first time when the QR get scanned successfully

codeLastSuccesfullyScannedAt

required

string or null <date-time>

ISO formatted date, the last time when the QR get scanned successfully

customerFirstEnteredAt

required

string or null <date-time>

ISO formatted time, when the first shopper enter the store

customerLastEnteredAt

required

string or null <date-time>

ISO formatted time, when the last shopper enter the store

customerFirstExitedAt

required

string or null <date-time>

ISO formatted time, when the first shopper exit the store

customerLastExitedAt

required

string or null <date-time>

ISO formatted time, when the last shopper exit the store

customerPaymentInstrumentId

required

integer or null

Payment instrument id

customerSatisfaction

required

integer or null [ 0 .. 100 ]

Satisfaction from the shopping session submitted by the customer. Can be null if not submitted or when customer wished to not ask him.

customerSatisfactionSubmitted

required

boolean

Default: false

Whether satisfaction has been submitted

groupSize

required

integer

Expected group size associated with the shopping session

visitors

required

integer

Actual group size associated with the shopping session

locationId

required

string or null

priority

required

integer [ -10 .. 10 ]

Default: 0

Customer priority. default to 0, which means any regular customer. customers with higher priority will have their shopping sessions prioritized during processing, the lower priority is opposite.

sessionToken

required

string

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.

sessionId

required

string

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.

referencedSessionId

required

string or null

Default: null

Referenced session token, that points to the source session

status

required

string

Enum: "active" "declined" "validated" "checkout_performed"

storeId

required

integer or null

AiFi store id

storeIdScannableAt

required

integer or null

the id of store which the QrCode of test case can be valided. It can be scanned at any store if the value is null.

suspectedFraud

required

boolean

Default: false

Indicate whether the shopping session is suspected fraud

metadata

required

object

Represents an arbitrary object. Note that the events key is reserved by AiFi for ThirdParty and Handoff Events. The value provided in the metadata field will completely overwrite the existing object. If your integration depends on the events key in the metadata, ensure it is preserved to avoid accidental deletion. To add new keys to the existing metadata object:

Retrieve the current metadata using the Get Session List endpoint.
Merge the retrieved metadata with the new keys you wish to add.
Submit the updated object in the metadata field.

Be cautious, as replacing the metadata value without preserving necessary keys may lead to unintended data loss.

expiresAt

required

string <date-time>

ISO formatted date at which this entry code will expire

shoppingSessionFlags

Array of strings

Items Enum: "POTENTIALLY_INTERACTED_WITH_ALCOHOL" "POTENTIALLY_SUSPICIOUS_BEHAVIOUR"

interactionsCount

number

restrictedInteractionsCount

number

Array of objects (InterestGroupInteractionCounterDto)

List of interest groups with their interaction counts

Array

id required	string Interest group identifier
name required	string Interest group name
interactionsCount required	integer >= 0 Number of interactions for this interest group

checkoutZoneId

required

string

For old integrations it will be sent as an integer, while for new ones it will be a string. Eventually all integrations will be converted to strings.

specialAttention

boolean

Deprecated

shoppingSessionFlags

Array of strings

Deprecated

Items Enum: "POTENTIALLY_INTERACTED_WITH_ALCOHOL" "POTENTIALLY_SUSPICIOUS_BEHAVIOUR"

required

object

Object holding information about the shopper who triggered the webhook

shopperId

required

string

Identifier of the Shopper

shopperFlags

string

Enum: "POTENTIALLY_INTERACTED_WITH_ALCOHOL" "POTENTIALLY_SUSPICIOUS_BEHAVIOUR"

interactionsCount

integer

Total number of shopper's interactions

restrictedInteractionsCount

integer

Total number of shopper's interactions with restricted items

reappeared

boolean

Indicates whether shopper reappeared

Array of objects (InterestGroupInteractionCounterDto)

List of interest groups with their interaction counts

Array

id required	string Interest group identifier
name required	string Interest group name
interactionsCount required	integer >= 0 Number of interactions for this interest group

Array of objects (CheckoutZoneCartItemDto)

Available only if the webhook is configured with option 'send_cart'

Array

id

required

string <integer>

Deprecated

Deprecated, use productSnapshot.productId

name

required

string

Deprecated

Deprecated, use productSnapshot.name

barcode

required

string

Deprecated

Deprecated, use productSnapshot.barcode

category

required

string or null

Deprecated

Deprecated, use productSnapshot.category

sku

required

string or null

Deprecated

Deprecated, use productSnapshot.sku

thumbnail

required

string or null

Deprecated

Deprecated, use productSnapshot.thumbnail

externalId

required

string or null

Deprecated

Deprecated, use productSnapshot.externalId

price

required

number

Deprecated

Deprecated, use productSnapshot.price

quantity

required

integer

quantity of a product

required

object (ProductSnapshotDto)

name required	string
price required	string or null <float> Unit price for single item, depending on configuration it may either contain the tax (suitable e.g. for integrations in EU) or not (suitable e.g. for integrations in the US)
barcode required	string Default barcode of default variant for this product
category required	string or null Deprecated
thumbnail required	string or null URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.
weight required	number or null Weight of a default variant
sku required	string or null Deprecated
externalId required	string or null Client defined product identifier
taxCode required	string or null Avalara tax code, available ig avalara integration is enabled
id required	integer
productId required	integer id of the product
createdAt required	string <date-time> ISO formatted date
updatedAt required	string <date-time> ISO formatted date

Responses

Response Schema: application/json

string

Request samples

Payload

Content type

application/json

{"sessionId": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"customer": {"externalId": "string",
"metadata": {"arbitraryKey": "arbitraryValue"
},
"id": "string",
"role": "customer"
},
"storeId": 0,
"store": {"oasisApiStoreId": 0,
"aifiUniqueStoreId": "string"
},
"storeExternalId": "string",
"timeOfOrigin": "2019-08-24T14:15:22Z",
"timeOfIssue": "2019-08-24T14:15:22Z",
"session": {"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"id": 0,
"customerId": 0,
"code": "c69bb289-1190-4156-b9f6-bfb7f61e85db",
"codeFirstSuccesfullyScannedAt": "2019-08-24T14:15:22Z",
"codeLastSuccesfullyScannedAt": "2019-08-24T14:15:22Z",
"customerFirstEnteredAt": "2019-08-24T14:15:22Z",
"customerLastEnteredAt": "2019-08-24T14:15:22Z",
"customerFirstExitedAt": "2019-08-24T14:15:22Z",
"customerLastExitedAt": "2019-08-24T14:15:22Z",
"customerPaymentInstrumentId": 0,
"customerSatisfaction": 95,
"customerSatisfactionSubmitted": false,
"groupSize": 0,
"visitors": 0,
"locationId": "string",
"priority": 0,
"sessionToken": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"sessionId": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"referencedSessionId": null,
"status": "active",
"storeId": 0,
"storeIdScannableAt": 0,
"suspectedFraud": false,
"metadata": {"events": [{"eventId": "6bdbfb2d-65b2-491c-bc97-c0ac73338476",
"metadata": {"key": "value"
}
}
],
"exampleKey": "exampleValue"
},
"expiresAt": "2019-08-24T14:15:22Z",
"shoppingSessionFlags": ["POTENTIALLY_INTERACTED_WITH_ALCOHOL"
],
"interactionsCount": 0,
"restrictedInteractionsCount": 0,
"interestGroups": [{"id": "string",
"name": "string",
"interactionsCount": 0
}
]
},
"checkoutZoneId": "string",
"specialAttention": true,
"shoppingSessionFlags": ["POTENTIALLY_INTERACTED_WITH_ALCOHOL"
],
"shopper": {"shopperId": "string",
"shopperFlags": "POTENTIALLY_INTERACTED_WITH_ALCOHOL",
"interactionsCount": 0,
"restrictedInteractionsCount": 0,
"reappeared": true,
"interestGroups": [{"id": "string",
"name": "string",
"interactionsCount": 0
}
]
},
"cart": [{"id": "string",
"name": "string",
"barcode": "string",
"category": "string",
"sku": "string",
"thumbnail": "string",
"externalId": "string",
"price": 0,
"quantity": 0,
"productSnapshot": {"name": "string",
"price": "string",
"barcode": "string",
"category": "string",
"thumbnail": "string",
"weight": 0,
"sku": "string",
"externalId": "string",
"taxCode": "string",
"id": 0,
"productId": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
}
]
}

Response samples

200

Content type

application/json

"string"

Push - checkout

customer group checked out

AiFi system shall call this webhook when a customer checked out in a store and an order is being placed in AiFi system (we use statuses "draft" and "completed" for it), or a contested order has been reviewed already (status "reviewed"). This webhook will capture the payment information from response and update order status based on that, after the checkout webhook only if the retailer is not integrated the payment providers of AiFi. If the retailer returns the multiple paymentIds, we will only store the first paymentId at the moment, and the rest will be ignored.

Note: as an integrator, the URL you specify for this webhook is going to be exactly the URL that will be called. For example, if you specify "http://example-retailer-api.com/webhook", then exactly "http://example-retailer-api.com/webhook" will be called.

Request Body schema: application/json
required

sessionId

required

string

Deprecated

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system. Deprecated, usesession.sessionId

required

SessionShallowDto (object) or InvalidSessionInWebhookDto (object)

One of

createdAt required	string <date-time> ISO formatted date representing when the entity was created
updatedAt required	string <date-time> ISO formatted date representing when the entity was last updated
id required	integer
customerId required	integer AiFi customer id
code required	string An entry code that can rendered as QR and used to enter AiFi store
codeFirstSuccesfullyScannedAt required	string or null <date-time> ISO formatted date, the first time when the QR get scanned successfully
codeLastSuccesfullyScannedAt required	string or null <date-time> ISO formatted date, the last time when the QR get scanned successfully
customerFirstEnteredAt required	string or null <date-time> ISO formatted time, when the first shopper enter the store
customerLastEnteredAt required	string or null <date-time> ISO formatted time, when the last shopper enter the store
customerFirstExitedAt required	string or null <date-time> ISO formatted time, when the first shopper exit the store
customerLastExitedAt required	string or null <date-time> ISO formatted time, when the last shopper exit the store
customerPaymentInstrumentId required	integer or null Payment instrument id
customerSatisfaction required	integer or null [ 0 .. 100 ] Satisfaction from the shopping session submitted by the customer. Can be null if not submitted or when customer wished to not ask him.
customerSatisfactionSubmitted required	boolean Default: false Whether satisfaction has been submitted
groupSize required	integer Expected group size associated with the shopping session
visitors required	integer Actual group size associated with the shopping session
locationId required	string or null
priority required	integer [ -10 .. 10 ] Default: 0 Customer priority. default to 0, which means any regular customer. customers with higher priority will have their shopping sessions prioritized during processing, the lower priority is opposite.
sessionToken required	string A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.
sessionId required	string A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.
referencedSessionId required	string or null Default: null Referenced session token, that points to the source session
status required	string Enum: "active" "declined" "validated" "checkout_performed"
storeId required	integer or null AiFi store id
storeIdScannableAt required	integer or null the id of store which the QrCode of test case can be valided. It can be scanned at any store if the value is null.
suspectedFraud required	boolean Default: false Indicate whether the shopping session is suspected fraud
metadata required	object Represents an arbitrary object. Note that the `events` key is reserved by AiFi for ThirdParty and Handoff Events. The value provided in the `metadata` field will completely overwrite the existing object. If your integration depends on the `events` key in the metadata, ensure it is preserved to avoid accidental deletion. To add new keys to the existing metadata object: Retrieve the current metadata using the Get Session List endpoint. Merge the retrieved metadata with the new keys you wish to add. Submit the updated object in the `metadata` field. Be cautious, as replacing the `metadata` value without preserving necessary keys may lead to unintended data loss.
expiresAt required	string <date-time> ISO formatted date at which this entry code will expire

required

object

Customer information

externalId required	string or null Id of the customer in external system
metadata required	object or null This object can contain custom metadata information
id required	string <integer> AiFi customer id, formatted as string
role required	string Enum: "customer" "employee" "tester" "untracked" "unknown" Role of the customer

storeId

required

integer

AiFi store id

required

object (StoreIdsDto)

oasisApiStoreId required	integer Store identifier that is only internal to cloud-api
aifiUniqueStoreId required	string or null Unique identifier across all AiFi stores. it will only be filled in by TechOPS/deployment engineers

storeExternalId

required

string or null

Retailer store id

timeOfOrigin

required

string <date-time>

ISO formatted creation time of the event, that caused this webhook to be sent

timeOfIssue

required

string <date-time>

ISO formatted time, in which this webhook was sent

orderId

required

integer

AiFi internal order id

status

required

string

Enum: "reviewed" "draft" "completed"

required

Array of objects (CheckoutCartItemDto)

Array

id

required

string <integer>

Deprecated

Deprecated, use productSnapshot.productId

name

required

string

Deprecated

Deprecated, use productSnapshot.name

barcode

required

string

Deprecated

Deprecated, use productSnapshot.barcode

category

required

string or null

Deprecated

Deprecated, use productSnapshot.category

sku

required

string or null

Deprecated

Deprecated, use productSnapshot.sku

thumbnail

required

string or null

Deprecated

Deprecated, use productSnapshot.thumbnail

externalId

required

string or null

Deprecated

Deprecated, use productSnapshot.externalId

price

required

number

Deprecated

Deprecated, use productSnapshot.price

productId

required

integer or null

Deprecated

Id of a product in Shopify

quantity

required

integer

quantity of a product

required

object (ProductSnapshotDto)

name required	string
price required	string or null <float> Unit price for single item, depending on configuration it may either contain the tax (suitable e.g. for integrations in EU) or not (suitable e.g. for integrations in the US)
barcode required	string Default barcode of default variant for this product
category required	string or null Deprecated
thumbnail required	string or null URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.
weight required	number or null Weight of a default variant
sku required	string or null Deprecated
externalId required	string or null Client defined product identifier
taxCode required	string or null Avalara tax code, available ig avalara integration is enabled
id required	integer
productId required	integer id of the product
createdAt required	string <date-time> ISO formatted date
updatedAt required	string <date-time> ISO formatted date

Array of objects (PredictedVariantDto)

Array

quantity

required

integer

required

object (ProductVariantResponseDto)

id

required

integer

name

required

string

thumbnail

required

string or null

URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.

invalidThumbnail

required

boolean

Marks whether thumbnail is a valid image

externalId

required

string or null <= 255 characters

Client defined product variant identifier

weight

required

string or null <float>

A decimal representation of the product's weight

required

Array of objects (ProductVariantBarcodeDto)

List of barcodes, associated with a variant

Array

isDefault required	boolean Informs whether this is a default barcode, for a variant. Every variant must have exactly one default barcode at all times.
barcode required	string Barcode value

isDefault

required

boolean

Informs whether this is a default variant, for a product. Every product must have exactly one default variant at all times.

productId

required

integer

id of a product in AiFi system

required

Array of objects (CartMutatorTaxLineDto)

Array

taxId required	string An unique identifier of the tax
title required	string or null
rate required	string <float> Tax rate in float format. For example, '0.19' means 0.19 x 100 = 19%
amount required	string <float> Tax amount in float format.

amount

required

number

Deprecated

A calculated total for the order

totalPrice

required

string <float>

A calculated total for the order

totalTax

required

string <float>

Total tax for the order

subtotalPrice

required

string <float>

Subtotal price(totalPrice - totalTax = subtotalPrice) for the order

required

object (WebhookPaymentPayloadDto)

paymentProvider

required

string

Enum: "NONE" "STRIPE" "PAYTER" "ADYEN" "FREEDOM_PAY" "GENERIC"

Name of the payment provider

required

object or null

type required	string Default: "card"
cardBin required	string or null The first 6-8 digits of a card's number. Null if unknown
cardLast4 required	string The last 4 digits of the card's number. Empty string if unknown
cardExpMonth required	integer Integer representation of the month in range [1..12]. 1 means January, 12 December. Special value 0 is returned, if unknown
cardExpYear required	integer 4 digit year. Special value 0 is returned, if unknown
cardBrand required	string A card brand. Allowed values, if payment integration is provided by OASIS platform, are [`american express`, `diners club`, `discover`, `JCB`, `mastercard`, `unionpay`, `visa`]. If payment integration is provided by the retailer, can be any string. If this value is unknown or not specified, empty string is returned

paymentStatus

required

string

Enum: "success" "failure" "processing"

Status of the payment

paymentTransactionIds

required

Array of strings

List of payment transaction ids

Responses

Response Schema: application/json

externalId

string

object

Payment information captured from checkout webhook response

paymentStatus required	string Enum: "success" "processing" "failure" Status of the payment
paymentTransactionIds required	Array of strings List of payment transaction ids, associated with a given order. If empty, AiFi will persist the information

Request samples

Payload

Content type

application/json

{"sessionId": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"session": {"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"id": 0,
"customerId": 0,
"code": "c69bb289-1190-4156-b9f6-bfb7f61e85db",
"codeFirstSuccesfullyScannedAt": "2019-08-24T14:15:22Z",
"codeLastSuccesfullyScannedAt": "2019-08-24T14:15:22Z",
"customerFirstEnteredAt": "2019-08-24T14:15:22Z",
"customerLastEnteredAt": "2019-08-24T14:15:22Z",
"customerFirstExitedAt": "2019-08-24T14:15:22Z",
"customerLastExitedAt": "2019-08-24T14:15:22Z",
"customerPaymentInstrumentId": 0,
"customerSatisfaction": 95,
"customerSatisfactionSubmitted": false,
"groupSize": 0,
"visitors": 0,
"locationId": "string",
"priority": 0,
"sessionToken": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"sessionId": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"referencedSessionId": null,
"status": "active",
"storeId": 0,
"storeIdScannableAt": 0,
"suspectedFraud": false,
"metadata": {"events": [{"eventId": "6bdbfb2d-65b2-491c-bc97-c0ac73338476",
"metadata": {"key": "value"
}
}
],
"exampleKey": "exampleValue"
},
"expiresAt": "2019-08-24T14:15:22Z"
},
"customer": {"externalId": "string",
"metadata": {"arbitraryKey": "arbitraryValue"
},
"id": "string",
"role": "customer"
},
"storeId": 0,
"store": {"oasisApiStoreId": 0,
"aifiUniqueStoreId": "string"
},
"storeExternalId": "string",
"timeOfOrigin": "2019-08-24T14:15:22Z",
"timeOfIssue": "2019-08-24T14:15:22Z",
"orderId": 0,
"status": "reviewed",
"cart": [{"id": "string",
"name": "string",
"barcode": "string",
"category": "string",
"sku": "string",
"thumbnail": "string",
"externalId": "string",
"price": 0,
"productId": 0,
"quantity": 0,
"productSnapshot": {"name": "string",
"price": "string",
"barcode": "string",
"category": "string",
"thumbnail": "string",
"weight": 0,
"sku": "string",
"externalId": "string",
"taxCode": "string",
"id": 0,
"productId": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
},
"predictedVariants": [{"quantity": 0,
"variant": {"id": 0,
"name": "string",
"thumbnail": "string",
"invalidThumbnail": true,
"externalId": "string",
"weight": "string",
"barcodes": [{"isDefault": true,
"barcode": "string"
}
],
"isDefault": true,
"productId": 0
}
}
],
"taxLines": [{"taxId": "string",
"title": "string",
"rate": "string",
"amount": "string"
}
]
}
],
"amount": 10.99,
"totalPrice": "10.99",
"totalTax": "0.99",
"subtotalPrice": "10.00",
"payment": {"paymentProvider": "NONE",
"paymentInstrument": {"type": "card",
"cardBin": "string",
"cardLast4": "string",
"cardExpMonth": 0,
"cardExpYear": 0,
"cardBrand": "string"
},
"paymentStatus": "success",
"paymentTransactionIds": ["string"
]
}
}

Response samples

200

Content type

application/json

{"externalId": "string",
"payment": {"paymentStatus": "success",
"paymentTransactionIds": ["string"
]
}
}

Push - transitions

customer entered a store

AiFi system shall call this webhook when a customer entered a store. This webhook is intended to be only informative: no response is parsed and no action is taken regardless of the response.

IMPORTANT NOTE: This event is going to be triggered for every person from the group, that entered on the account of the provided customer. As an example, for a group of 2 people that enter together on a single app, you get the exact same push notification twice, with customer field being the person that app was registered for, after each person has entered the store.

Note: as an integrator, the URL you specify for transitions webhooks will be re-used for all transitions actions. For example, if you specify "http://example-retailer-api.com/webhook", then "http://example-retailer-api.com/webhook/entered" will be called in this case.

Request Body schema: application/json
required

sessionId

required

string

Deprecated

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system. Deprecated, usesession.sessionId

required

SessionShallowDto (object) or InvalidSessionInWebhookDto (object)

One of

createdAt required	string <date-time> ISO formatted date representing when the entity was created
updatedAt required	string <date-time> ISO formatted date representing when the entity was last updated
id required	integer
customerId required	integer AiFi customer id
code required	string An entry code that can rendered as QR and used to enter AiFi store
codeFirstSuccesfullyScannedAt required	string or null <date-time> ISO formatted date, the first time when the QR get scanned successfully
codeLastSuccesfullyScannedAt required	string or null <date-time> ISO formatted date, the last time when the QR get scanned successfully
customerFirstEnteredAt required	string or null <date-time> ISO formatted time, when the first shopper enter the store
customerLastEnteredAt required	string or null <date-time> ISO formatted time, when the last shopper enter the store
customerFirstExitedAt required	string or null <date-time> ISO formatted time, when the first shopper exit the store
customerLastExitedAt required	string or null <date-time> ISO formatted time, when the last shopper exit the store
customerPaymentInstrumentId required	integer or null Payment instrument id
customerSatisfaction required	integer or null [ 0 .. 100 ] Satisfaction from the shopping session submitted by the customer. Can be null if not submitted or when customer wished to not ask him.
customerSatisfactionSubmitted required	boolean Default: false Whether satisfaction has been submitted
groupSize required	integer Expected group size associated with the shopping session
visitors required	integer Actual group size associated with the shopping session
locationId required	string or null
priority required	integer [ -10 .. 10 ] Default: 0 Customer priority. default to 0, which means any regular customer. customers with higher priority will have their shopping sessions prioritized during processing, the lower priority is opposite.
sessionToken required	string A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.
sessionId required	string A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.
referencedSessionId required	string or null Default: null Referenced session token, that points to the source session
status required	string Enum: "active" "declined" "validated" "checkout_performed"
storeId required	integer or null AiFi store id
storeIdScannableAt required	integer or null the id of store which the QrCode of test case can be valided. It can be scanned at any store if the value is null.
suspectedFraud required	boolean Default: false Indicate whether the shopping session is suspected fraud
metadata required	object Represents an arbitrary object. Note that the `events` key is reserved by AiFi for ThirdParty and Handoff Events. The value provided in the `metadata` field will completely overwrite the existing object. If your integration depends on the `events` key in the metadata, ensure it is preserved to avoid accidental deletion. To add new keys to the existing metadata object: Retrieve the current metadata using the Get Session List endpoint. Merge the retrieved metadata with the new keys you wish to add. Submit the updated object in the `metadata` field. Be cautious, as replacing the `metadata` value without preserving necessary keys may lead to unintended data loss.
expiresAt required	string <date-time> ISO formatted date at which this entry code will expire

required

object

Customer information

externalId required	string or null Id of the customer in external system
metadata required	object or null This object can contain custom metadata information
id required	string <integer> AiFi customer id, formatted as string
role required	string Enum: "customer" "employee" "tester" "untracked" "unknown" Role of the customer

storeId

required

integer

AiFi store id

required

object (StoreIdsDto)

oasisApiStoreId required	integer Store identifier that is only internal to cloud-api
aifiUniqueStoreId required	string or null Unique identifier across all AiFi stores. it will only be filled in by TechOPS/deployment engineers

storeExternalId

required

string or null

Retailer store id

timeOfOrigin

required

string <date-time>

ISO formatted creation time of the event, that caused this webhook to be sent

timeOfIssue

required

string <date-time>

ISO formatted time, in which this webhook was sent

required

object or null

paymentProvider

required

string

Enum: "NONE" "STRIPE" "PAYTER" "ADYEN" "FREEDOM_PAY" "GENERIC"

Name of the payment provider

shopperId

required

string

Identifier of the Shopper

required

object (TransitionShopperDto)

shopperId

required

string

Identifier of the Shopper

Responses

Response Schema: application/json

string

Request samples

Payload

Content type

application/json

{"sessionId": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"session": {"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"id": 0,
"customerId": 0,
"code": "c69bb289-1190-4156-b9f6-bfb7f61e85db",
"codeFirstSuccesfullyScannedAt": "2019-08-24T14:15:22Z",
"codeLastSuccesfullyScannedAt": "2019-08-24T14:15:22Z",
"customerFirstEnteredAt": "2019-08-24T14:15:22Z",
"customerLastEnteredAt": "2019-08-24T14:15:22Z",
"customerFirstExitedAt": "2019-08-24T14:15:22Z",
"customerLastExitedAt": "2019-08-24T14:15:22Z",
"customerPaymentInstrumentId": 0,
"customerSatisfaction": 95,
"customerSatisfactionSubmitted": false,
"groupSize": 0,
"visitors": 0,
"locationId": "string",
"priority": 0,
"sessionToken": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"sessionId": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"referencedSessionId": null,
"status": "active",
"storeId": 0,
"storeIdScannableAt": 0,
"suspectedFraud": false,
"metadata": {"events": [{"eventId": "6bdbfb2d-65b2-491c-bc97-c0ac73338476",
"metadata": {"key": "value"
}
}
],
"exampleKey": "exampleValue"
},
"expiresAt": "2019-08-24T14:15:22Z"
},
"customer": {"externalId": "string",
"metadata": {"arbitraryKey": "arbitraryValue"
},
"id": "string",
"role": "customer"
},
"storeId": 0,
"store": {"oasisApiStoreId": 0,
"aifiUniqueStoreId": "string"
},
"storeExternalId": "string",
"timeOfOrigin": "2019-08-24T14:15:22Z",
"timeOfIssue": "2019-08-24T14:15:22Z",
"payment": {"paymentProvider": "NONE"
},
"shopperId": "string",
"shopper": {"shopperId": "string"
}
}

Response samples

200

Content type

application/json

"string"

customer left a store

AiFi system shall call this webhook when a customer left a store. This webhook is intended to be only informative: no response is parsed and no action is taken regardless of the response.

IMPORTANT NOTE: This event is going to be triggered for every person from the group, that entered on the account of the provided customer. As an example, for a group of 2 people that enter together on a single app, you get the exact same push notification twice, with customer field being the person that app was registered for, after each person has left the store.

Note: as an integrator, the URL you specify for transitions webhooks will be re-used for all transitions actions. For example, if you specify "http://example-retailer-api.com/webhook", then "http://example-retailer-api.com/webhook/entered" will be called in this case.

Request Body schema: application/json
required

sessionId

required

string

Deprecated

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system. Deprecated, usesession.sessionId

required

SessionShallowDto (object) or InvalidSessionInWebhookDto (object)

One of

createdAt required	string <date-time> ISO formatted date representing when the entity was created
updatedAt required	string <date-time> ISO formatted date representing when the entity was last updated
id required	integer
customerId required	integer AiFi customer id
code required	string An entry code that can rendered as QR and used to enter AiFi store
codeFirstSuccesfullyScannedAt required	string or null <date-time> ISO formatted date, the first time when the QR get scanned successfully
codeLastSuccesfullyScannedAt required	string or null <date-time> ISO formatted date, the last time when the QR get scanned successfully
customerFirstEnteredAt required	string or null <date-time> ISO formatted time, when the first shopper enter the store
customerLastEnteredAt required	string or null <date-time> ISO formatted time, when the last shopper enter the store
customerFirstExitedAt required	string or null <date-time> ISO formatted time, when the first shopper exit the store
customerLastExitedAt required	string or null <date-time> ISO formatted time, when the last shopper exit the store
customerPaymentInstrumentId required	integer or null Payment instrument id
customerSatisfaction required	integer or null [ 0 .. 100 ] Satisfaction from the shopping session submitted by the customer. Can be null if not submitted or when customer wished to not ask him.
customerSatisfactionSubmitted required	boolean Default: false Whether satisfaction has been submitted
groupSize required	integer Expected group size associated with the shopping session
visitors required	integer Actual group size associated with the shopping session
locationId required	string or null
priority required	integer [ -10 .. 10 ] Default: 0 Customer priority. default to 0, which means any regular customer. customers with higher priority will have their shopping sessions prioritized during processing, the lower priority is opposite.
sessionToken required	string A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.
sessionId required	string A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.
referencedSessionId required	string or null Default: null Referenced session token, that points to the source session
status required	string Enum: "active" "declined" "validated" "checkout_performed"
storeId required	integer or null AiFi store id
storeIdScannableAt required	integer or null the id of store which the QrCode of test case can be valided. It can be scanned at any store if the value is null.
suspectedFraud required	boolean Default: false Indicate whether the shopping session is suspected fraud
metadata required	object Represents an arbitrary object. Note that the `events` key is reserved by AiFi for ThirdParty and Handoff Events. The value provided in the `metadata` field will completely overwrite the existing object. If your integration depends on the `events` key in the metadata, ensure it is preserved to avoid accidental deletion. To add new keys to the existing metadata object: Retrieve the current metadata using the Get Session List endpoint. Merge the retrieved metadata with the new keys you wish to add. Submit the updated object in the `metadata` field. Be cautious, as replacing the `metadata` value without preserving necessary keys may lead to unintended data loss.
expiresAt required	string <date-time> ISO formatted date at which this entry code will expire

required

object

Customer information

externalId required	string or null Id of the customer in external system
metadata required	object or null This object can contain custom metadata information
id required	string <integer> AiFi customer id, formatted as string
role required	string Enum: "customer" "employee" "tester" "untracked" "unknown" Role of the customer

storeId

required

integer

AiFi store id

required

object (StoreIdsDto)

oasisApiStoreId required	integer Store identifier that is only internal to cloud-api
aifiUniqueStoreId required	string or null Unique identifier across all AiFi stores. it will only be filled in by TechOPS/deployment engineers

storeExternalId

required

string or null

Retailer store id

timeOfOrigin

required

string <date-time>

ISO formatted creation time of the event, that caused this webhook to be sent

timeOfIssue

required

string <date-time>

ISO formatted time, in which this webhook was sent

required

object or null

paymentProvider

required

string

Enum: "NONE" "STRIPE" "PAYTER" "ADYEN" "FREEDOM_PAY" "GENERIC"

Name of the payment provider

shopperId

required

string

Identifier of the Shopper

required

object (TransitionShopperDto)

shopperId

required

string

Identifier of the Shopper

Responses

Response Schema: application/json

string

Request samples

Payload

Content type

application/json

{"sessionId": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"session": {"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"id": 0,
"customerId": 0,
"code": "c69bb289-1190-4156-b9f6-bfb7f61e85db",
"codeFirstSuccesfullyScannedAt": "2019-08-24T14:15:22Z",
"codeLastSuccesfullyScannedAt": "2019-08-24T14:15:22Z",
"customerFirstEnteredAt": "2019-08-24T14:15:22Z",
"customerLastEnteredAt": "2019-08-24T14:15:22Z",
"customerFirstExitedAt": "2019-08-24T14:15:22Z",
"customerLastExitedAt": "2019-08-24T14:15:22Z",
"customerPaymentInstrumentId": 0,
"customerSatisfaction": 95,
"customerSatisfactionSubmitted": false,
"groupSize": 0,
"visitors": 0,
"locationId": "string",
"priority": 0,
"sessionToken": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"sessionId": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"referencedSessionId": null,
"status": "active",
"storeId": 0,
"storeIdScannableAt": 0,
"suspectedFraud": false,
"metadata": {"events": [{"eventId": "6bdbfb2d-65b2-491c-bc97-c0ac73338476",
"metadata": {"key": "value"
}
}
],
"exampleKey": "exampleValue"
},
"expiresAt": "2019-08-24T14:15:22Z"
},
"customer": {"externalId": "string",
"metadata": {"arbitraryKey": "arbitraryValue"
},
"id": "string",
"role": "customer"
},
"storeId": 0,
"store": {"oasisApiStoreId": 0,
"aifiUniqueStoreId": "string"
},
"storeExternalId": "string",
"timeOfOrigin": "2019-08-24T14:15:22Z",
"timeOfIssue": "2019-08-24T14:15:22Z",
"payment": {"paymentProvider": "NONE"
},
"shopperId": "string",
"shopper": {"shopperId": "string"
}
}

Response samples

200

Content type

application/json

"string"

Push - entry codes

verify entry-code at external provider

AiFi system shall call this webhook during the entry-code validation.

In regular mode, the webhook is only called if both the entry code and the customer owning it were previously registered in AiFi system.

However, if the QR code passthrough option is turned on (consult your account manager if you need this option turned on), the webhook is called as the first step during the validation. In this case, the retailer can optionally return a customerId that will be used to match the customer entity and dynamically create the entry code. If no customerId is returned, but status is still OK, AiFi will dynamically create both the customer entity and the associated entry code.

Retailer or third party can perform their additional checks (such as: pre-authorization of funds etc) and return to AiFi whether their checks succeeded. Take note, that AiFi can deny customer the entry without calling this endpoint (for example, when the store is closed). AiFi may also deny entry after this call, if a payment provider is specified on AiFi side and the payment methods checks fail.

Endpoint returns 200 http code also in all instances when the code was successfully examined but rejected for any reason.

Http error codes are used only when there are other errors preventing the check, such as: 404, reason: 'Customer id not found'

Note: as an integrator, the URL you specify for this webhook is going to be exactly the URL that will be called. For example, if you specify "http://example-retailer-api.com/webhook", then exactly "http://example-retailer-api.com/webhook" will be called.

Request Body schema: application/json
required

storeId

required

integer

AiFi store id

required

object (StoreIdsDto)

oasisApiStoreId required	integer Store identifier that is only internal to cloud-api
aifiUniqueStoreId required	string or null Unique identifier across all AiFi stores. it will only be filled in by TechOPS/deployment engineers

storeExternalId

required

string or null

Retailer store id

timeOfOrigin

required

string <date-time>

ISO formatted creation time of the event, that caused this webhook to be sent

timeOfIssue

required

string <date-time>

ISO formatted time, in which this webhook was sent

customerId

required

integer or null

Deprecated

AiFi customer id

required

object or null

Customer information

externalId required	string or null Id of the customer in external system
metadata required	object or null This object can contain custom metadata information
id required	string <integer> AiFi customer id, formatted as string
role required	string Enum: "customer" "employee" "tester" "untracked" "unknown" Role of the customer

role

required

string or null

Deprecated

Enum: "customer" "employee" "tester" "untracked" "unknown"

checkInDeviceId

required

integer or null

The id of check-in device

entryCode

required

string

Entry code to be verified

expectedGroupSize

required

integer or null

Group size that was specified by the user in the customer app, when requesting a qr code

groupSize

integer

Size of a group that was present in the scanning zone during qr code scan

required

object (PaymentProviderInfoDto)

paymentProvider

required

string

Enum: "NONE" "STRIPE" "PAYTER" "ADYEN" "FREEDOM_PAY" "GENERIC"

Name of the payment provider

Responses

Response Schema: application/json

status required	string Enum: "OK" "FAILED" Status of the entry-code verification. 'OK' if validation passed, 'FAILED' if validation failed.
reason	string Reason for failure (if applicable)
sessionId	string (Optional) Override of the default session id to be then used in further communication. The length of sessionId must be ≤ 36 characters. JWT strings are prohibited.
customerId	number (Optional, QR code passthrough mode only) specify AiFi customer ID to be matched with this dynamic entry code

Request samples

Payload

Content type

application/json

{"storeId": 0,
"store": {"oasisApiStoreId": 0,
"aifiUniqueStoreId": "string"
},
"storeExternalId": "string",
"timeOfOrigin": "2019-08-24T14:15:22Z",
"timeOfIssue": "2019-08-24T14:15:22Z",
"customerId": 0,
"customer": {"externalId": "string",
"metadata": {"arbitraryKey": "arbitraryValue"
},
"id": "string",
"role": "customer"
},
"role": "customer",
"checkInDeviceId": 0,
"entryCode": "string",
"expectedGroupSize": 0,
"groupSize": 0,
"payment": {"paymentProvider": "NONE"
}
}

Response samples

200

Content type

application/json

{"status": "FAILED",
"reason": "Payment verification failed",
"sessionId": "cc256d83-a307-483e-b3bf-3740cb925f92",
"customerId": 123
}

notify external provider on entry-code validation failure

AiFi system shall call this webhook when entry-code validation fails due to some reason. Request is sent as a fire-and-forget, hence retailer's response will not be used at all. Note: As an integrator, the URL you specify for this webhook is going to be exactly the URL that will be called. For example, if you specify "http://example-retailer-api.com/webhook", then exactly "http://example-retailer-api.com/webhook" will be called.

Request Body schema: application/json
required

storeId

required

integer

AiFi store id

required

object (StoreIdsDto)

oasisApiStoreId required	integer Store identifier that is only internal to cloud-api
aifiUniqueStoreId required	string or null Unique identifier across all AiFi stores. it will only be filled in by TechOPS/deployment engineers

timeOfOrigin

required

string <date-time>

ISO formatted creation time of the event, that caused this webhook to be sent

timeOfIssue

required

string <date-time>

ISO formatted time, in which this webhook was sent

sessionId

required

string

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.

required

object or null

Customer information

externalId required	string or null Id of the customer in external system
metadata required	object or null This object can contain custom metadata information
id required	string <integer> AiFi customer id, formatted as string
role required	string Enum: "customer" "employee" "tester" "untracked" "unknown" Role of the customer

checkInDeviceId

required

integer or null

The id of check-in device

entryCode

required

string

Entry code to be verified

errorMessage

required

string

Message describing cause of the issue

errorCode

required

integer

Error code describing cause of the issue

Responses

Response Schema: application/json

string

Request samples

Payload

Content type

application/json

{"storeId": 0,
"store": {"oasisApiStoreId": 0,
"aifiUniqueStoreId": "string"
},
"timeOfOrigin": "2019-08-24T14:15:22Z",
"timeOfIssue": "2019-08-24T14:15:22Z",
"sessionId": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"customer": {"externalId": "string",
"metadata": {"arbitraryKey": "arbitraryValue"
},
"id": "string",
"role": "customer"
},
"checkInDeviceId": 0,
"entryCode": "string",
"errorMessage": "string",
"errorCode": 0
}

Response samples

200

Content type

application/json

"string"

Push - evaluate order price

request to third party to evaluate order price

AiFi system shall call this webhook when a customer checked out, but before an order is being placed in AiFi system. The webhook expects that the third party system is going to take the list of the products specified and based on them calculate the final total price of the order, that is going to be then used to check out the customer.

Note: as an integrator, the URL you specify for this webhook is going to be exactly the URL that will be called. For example, if you specify "http://example-retailer-api.com/webhook", then exactly "http://example-retailer-api.com/webhook" will be called.

Request Body schema: application/json
required

sessionId

required

string

Deprecated

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system. Deprecated, usesession.sessionId

required

SessionShallowDto (object) or InvalidSessionInWebhookDto (object)

One of

createdAt required	string <date-time> ISO formatted date representing when the entity was created
updatedAt required	string <date-time> ISO formatted date representing when the entity was last updated
id required	integer
customerId required	integer AiFi customer id
code required	string An entry code that can rendered as QR and used to enter AiFi store
codeFirstSuccesfullyScannedAt required	string or null <date-time> ISO formatted date, the first time when the QR get scanned successfully
codeLastSuccesfullyScannedAt required	string or null <date-time> ISO formatted date, the last time when the QR get scanned successfully
customerFirstEnteredAt required	string or null <date-time> ISO formatted time, when the first shopper enter the store
customerLastEnteredAt required	string or null <date-time> ISO formatted time, when the last shopper enter the store
customerFirstExitedAt required	string or null <date-time> ISO formatted time, when the first shopper exit the store
customerLastExitedAt required	string or null <date-time> ISO formatted time, when the last shopper exit the store
customerPaymentInstrumentId required	integer or null Payment instrument id
customerSatisfaction required	integer or null [ 0 .. 100 ] Satisfaction from the shopping session submitted by the customer. Can be null if not submitted or when customer wished to not ask him.
customerSatisfactionSubmitted required	boolean Default: false Whether satisfaction has been submitted
groupSize required	integer Expected group size associated with the shopping session
visitors required	integer Actual group size associated with the shopping session
locationId required	string or null
priority required	integer [ -10 .. 10 ] Default: 0 Customer priority. default to 0, which means any regular customer. customers with higher priority will have their shopping sessions prioritized during processing, the lower priority is opposite.
sessionToken required	string A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.
sessionId required	string A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.
referencedSessionId required	string or null Default: null Referenced session token, that points to the source session
status required	string Enum: "active" "declined" "validated" "checkout_performed"
storeId required	integer or null AiFi store id
storeIdScannableAt required	integer or null the id of store which the QrCode of test case can be valided. It can be scanned at any store if the value is null.
suspectedFraud required	boolean Default: false Indicate whether the shopping session is suspected fraud
metadata required	object Represents an arbitrary object. Note that the `events` key is reserved by AiFi for ThirdParty and Handoff Events. The value provided in the `metadata` field will completely overwrite the existing object. If your integration depends on the `events` key in the metadata, ensure it is preserved to avoid accidental deletion. To add new keys to the existing metadata object: Retrieve the current metadata using the Get Session List endpoint. Merge the retrieved metadata with the new keys you wish to add. Submit the updated object in the `metadata` field. Be cautious, as replacing the `metadata` value without preserving necessary keys may lead to unintended data loss.
expiresAt required	string <date-time> ISO formatted date at which this entry code will expire

required

object

Customer information

externalId required	string or null Id of the customer in external system
metadata required	object or null This object can contain custom metadata information
id required	string <integer> AiFi customer id, formatted as string
role required	string Enum: "customer" "employee" "tester" "untracked" "unknown" Role of the customer

storeId

required

integer

AiFi store id

required

object (StoreIdsDto)

oasisApiStoreId required	integer Store identifier that is only internal to cloud-api
aifiUniqueStoreId required	string or null Unique identifier across all AiFi stores. it will only be filled in by TechOPS/deployment engineers

storeExternalId

required

string or null

Retailer store id

timeOfOrigin

required

string <date-time>

ISO formatted creation time of the event, that caused this webhook to be sent

timeOfIssue

required

string <date-time>

ISO formatted time, in which this webhook was sent

orderId

required

integer

AiFi internal order id

status

required

string

Value: "completed"

required

Array of objects (PriceCalculatorCartItemDto)

Array

id

required

string <integer>

Deprecated

Deprecated, use productSnapshot.productId

name

required

string

Deprecated

Deprecated, use productSnapshot.name

barcode

required

string

Deprecated

Deprecated, use productSnapshot.barcode

category

required

string or null

Deprecated

Deprecated, use productSnapshot.category

sku

required

string or null

Deprecated

Deprecated, use productSnapshot.sku

thumbnail

required

string or null

Deprecated

Deprecated, use productSnapshot.thumbnail

externalId

required

string or null

Deprecated

Deprecated, use productSnapshot.externalId

price

required

number

Deprecated

Deprecated, use productSnapshot.price

quantity

required

integer

quantity of a product

required

object (ProductSnapshotDto)

name required	string
price required	string or null <float> Unit price for single item, depending on configuration it may either contain the tax (suitable e.g. for integrations in EU) or not (suitable e.g. for integrations in the US)
barcode required	string Default barcode of default variant for this product
category required	string or null Deprecated
thumbnail required	string or null URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.
weight required	number or null Weight of a default variant
sku required	string or null Deprecated
externalId required	string or null Client defined product identifier
taxCode required	string or null Avalara tax code, available ig avalara integration is enabled
id required	integer
productId required	integer id of the product
createdAt required	string <date-time> ISO formatted date
updatedAt required	string <date-time> ISO formatted date

Responses

Response Schema: application/json

totalPrice

required

string <number>

A decimal representation of the total price to charge the customer

totalTax

string <number>

A decimal representation of the total tax to charge the customer

Array of objects (ApiProductPrice)

Effective prices for each order position

Array

id required	number AiFi product id as in the request
effectivePrice required	string <number> The price of this product used to calculate the total, formatted as a decimal
message	string Optional string explanation of the promotions applied

Request samples

Payload

Content type

application/json

{"sessionId": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"session": {"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"id": 0,
"customerId": 0,
"code": "c69bb289-1190-4156-b9f6-bfb7f61e85db",
"codeFirstSuccesfullyScannedAt": "2019-08-24T14:15:22Z",
"codeLastSuccesfullyScannedAt": "2019-08-24T14:15:22Z",
"customerFirstEnteredAt": "2019-08-24T14:15:22Z",
"customerLastEnteredAt": "2019-08-24T14:15:22Z",
"customerFirstExitedAt": "2019-08-24T14:15:22Z",
"customerLastExitedAt": "2019-08-24T14:15:22Z",
"customerPaymentInstrumentId": 0,
"customerSatisfaction": 95,
"customerSatisfactionSubmitted": false,
"groupSize": 0,
"visitors": 0,
"locationId": "string",
"priority": 0,
"sessionToken": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"sessionId": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"referencedSessionId": null,
"status": "active",
"storeId": 0,
"storeIdScannableAt": 0,
"suspectedFraud": false,
"metadata": {"events": [{"eventId": "6bdbfb2d-65b2-491c-bc97-c0ac73338476",
"metadata": {"key": "value"
}
}
],
"exampleKey": "exampleValue"
},
"expiresAt": "2019-08-24T14:15:22Z"
},
"customer": {"externalId": "string",
"metadata": {"arbitraryKey": "arbitraryValue"
},
"id": "string",
"role": "customer"
},
"storeId": 0,
"store": {"oasisApiStoreId": 0,
"aifiUniqueStoreId": "string"
},
"storeExternalId": "string",
"timeOfOrigin": "2019-08-24T14:15:22Z",
"timeOfIssue": "2019-08-24T14:15:22Z",
"orderId": 0,
"status": "completed",
"cart": [{"id": "string",
"name": "string",
"barcode": "string",
"category": "string",
"sku": "string",
"thumbnail": "string",
"externalId": "string",
"price": 0,
"quantity": 0,
"productSnapshot": {"name": "string",
"price": "string",
"barcode": "string",
"category": "string",
"thumbnail": "string",
"weight": 0,
"sku": "string",
"externalId": "string",
"taxCode": "string",
"id": 0,
"productId": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
}
]
}

Response samples

200

Content type

application/json

{"totalPrice": "1.35",
"totalTax": "0.35",
"effectivePrices": [{"id": 28612838096970,
"effectivePrice": "1.35",
"message": "Promo 50% off"
}
]
}

Push - cart mutator

request to third party with cart mutation

AiFi system shall call this webhook when a customer checked out in a store and an order is being placed in AiFi system. The webhook is also called when an order's contest is reviewed. Important notes about calling webhook during a contest:

it can happen even a few days later after the actual shopping journey. Retailer should use timeOfOrigin (time of the original shopping journey),
items that were previously added by the webhook during the checkout will not be sent again during review!
calling webhook during review can be distinguished by status field.
by default, reviewedTotalPrice takes precedence over cart mutator totalPrice. Cart Mutator implementation should respect and properly handle adjusted reviewedTotalPrice.

The webhook expects that the third party system is going to mutate cart items and adjust order prices according to the cart mutation. Possible use cases include: extending items with taxLines, adding deposit items, adjusting prices, and removing or adding new cart items.

Some communication details:

when response couldn't be received, or crucial fields are missing, Aifi system fails silently (mutator webhook is omitted)
when only some particular cart item in response is incorrect, Aifi system ignores that item (for example, when neither id nor externalId of cart item couldn't be resolved to AiFi object)

Note: as an integrator, the URL you specify for this webhook is going to be exactly the URL that will be called. For example, if you specify "http://example-retailer-api.com/webhook", then exactly "http://example-retailer-api.com/webhook" will be called.

Request Body schema: application/json
required

sessionId

required

string

Deprecated

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system. Deprecated, usesession.sessionId

required

SessionShallowDto (object) or InvalidSessionInWebhookDto (object)

One of

createdAt required	string <date-time> ISO formatted date representing when the entity was created
updatedAt required	string <date-time> ISO formatted date representing when the entity was last updated
id required	integer
customerId required	integer AiFi customer id
code required	string An entry code that can rendered as QR and used to enter AiFi store
codeFirstSuccesfullyScannedAt required	string or null <date-time> ISO formatted date, the first time when the QR get scanned successfully
codeLastSuccesfullyScannedAt required	string or null <date-time> ISO formatted date, the last time when the QR get scanned successfully
customerFirstEnteredAt required	string or null <date-time> ISO formatted time, when the first shopper enter the store
customerLastEnteredAt required	string or null <date-time> ISO formatted time, when the last shopper enter the store
customerFirstExitedAt required	string or null <date-time> ISO formatted time, when the first shopper exit the store
customerLastExitedAt required	string or null <date-time> ISO formatted time, when the last shopper exit the store
customerPaymentInstrumentId required	integer or null Payment instrument id
customerSatisfaction required	integer or null [ 0 .. 100 ] Satisfaction from the shopping session submitted by the customer. Can be null if not submitted or when customer wished to not ask him.
customerSatisfactionSubmitted required	boolean Default: false Whether satisfaction has been submitted
groupSize required	integer Expected group size associated with the shopping session
visitors required	integer Actual group size associated with the shopping session
locationId required	string or null
priority required	integer [ -10 .. 10 ] Default: 0 Customer priority. default to 0, which means any regular customer. customers with higher priority will have their shopping sessions prioritized during processing, the lower priority is opposite.
sessionToken required	string A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.
sessionId required	string A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.
referencedSessionId required	string or null Default: null Referenced session token, that points to the source session
status required	string Enum: "active" "declined" "validated" "checkout_performed"
storeId required	integer or null AiFi store id
storeIdScannableAt required	integer or null the id of store which the QrCode of test case can be valided. It can be scanned at any store if the value is null.
suspectedFraud required	boolean Default: false Indicate whether the shopping session is suspected fraud
metadata required	object Represents an arbitrary object. Note that the `events` key is reserved by AiFi for ThirdParty and Handoff Events. The value provided in the `metadata` field will completely overwrite the existing object. If your integration depends on the `events` key in the metadata, ensure it is preserved to avoid accidental deletion. To add new keys to the existing metadata object: Retrieve the current metadata using the Get Session List endpoint. Merge the retrieved metadata with the new keys you wish to add. Submit the updated object in the `metadata` field. Be cautious, as replacing the `metadata` value without preserving necessary keys may lead to unintended data loss.
expiresAt required	string <date-time> ISO formatted date at which this entry code will expire

required

object

Customer information

externalId required	string or null Id of the customer in external system
metadata required	object or null This object can contain custom metadata information
id required	string <integer> AiFi customer id, formatted as string
role required	string Enum: "customer" "employee" "tester" "untracked" "unknown" Role of the customer

storeId

required

integer

AiFi store id

required

object (StoreIdsDto)

oasisApiStoreId required	integer Store identifier that is only internal to cloud-api
aifiUniqueStoreId required	string or null Unique identifier across all AiFi stores. it will only be filled in by TechOPS/deployment engineers

storeExternalId

required

string or null

Retailer store id

timeOfOrigin

required

string <date-time>

ISO formatted creation time of the event, that caused this webhook to be sent

timeOfIssue

required

string <date-time>

ISO formatted time, in which this webhook was sent

required

Array of objects (CartMutatorCartItemDto)

Array

id

required

string <integer>

Deprecated

Deprecated, use productSnapshot.productId

name

required

string

Deprecated

Deprecated, use productSnapshot.name

barcode

required

string

Deprecated

Deprecated, use productSnapshot.barcode

category

required

string or null

Deprecated

Deprecated, use productSnapshot.category

sku

required

string or null

Deprecated

Deprecated, use productSnapshot.sku

thumbnail

required

string or null

Deprecated

Deprecated, use productSnapshot.thumbnail

externalId

required

string or null

Deprecated

Deprecated, use productSnapshot.externalId

price

required

number

Deprecated

Deprecated, use productSnapshot.price

required

object (ProductSnapshotDto)

name required	string
price required	string or null <float> Unit price for single item, depending on configuration it may either contain the tax (suitable e.g. for integrations in EU) or not (suitable e.g. for integrations in the US)
barcode required	string Default barcode of default variant for this product
category required	string or null Deprecated
thumbnail required	string or null URL of the thumbnail for this product. Note that it needs not be the same as specified during product creation/update, as AIFI may host URLs in it's own storage.
weight required	number or null Weight of a default variant
sku required	string or null Deprecated
externalId required	string or null Client defined product identifier
taxCode required	string or null Avalara tax code, available ig avalara integration is enabled
id required	integer
productId required	integer id of the product
createdAt required	string <date-time> ISO formatted date
updatedAt required	string <date-time> ISO formatted date

quantity

required

integer

Quantity of the product

subtotalPrice

required

string <float>

A decimal representation of the subtotal price of this lineitem

totalPrice

required

string <float>

A decimal representation of the total price of this lineitem

totalTax

required

string <float>

A decimal representation of the total tax of this lineitem

required

Array of objects (CartMutatorTaxLineDto)

Array

taxId required	string An unique identifier of the tax
title required	string or null
rate required	string <float> Tax rate in float format. For example, '0.19' means 0.19 x 100 = 19%
amount required	string <float> Tax amount in float format.

required

object (CartMutatorMetadataDto)

required

object (CartMutatorMetadataCartDto)

priceIncludesTax

required

boolean

Whether product price includes tax

orderId

required

integer

AiFi internal order id

status

required

string

Enum: "reviewed" "draft" "completed"

totalPrice

required

string <float>

A calculated total for the order

totalTax

required

string <float>

Total tax for the order

subtotalPrice

required

string <float>

Subtotal price(totalPrice - totalTax = subtotalPrice) for the order

required

object (PaymentInfoDto)

paymentProvider

required

string

Enum: "NONE" "STRIPE" "PAYTER" "ADYEN" "FREEDOM_PAY" "GENERIC"

Name of the payment provider

required

object or null

type required	string Default: "card"
cardBin required	string or null The first 6-8 digits of a card's number. Null if unknown
cardLast4 required	string The last 4 digits of the card's number. Empty string if unknown
cardExpMonth required	integer Integer representation of the month in range [1..12]. 1 means January, 12 December. Special value 0 is returned, if unknown
cardExpYear required	integer 4 digit year. Special value 0 is returned, if unknown
cardBrand required	string A card brand. Allowed values, if payment integration is provided by OASIS platform, are [`american express`, `diners club`, `discover`, `JCB`, `mastercard`, `unionpay`, `visa`]. If payment integration is provided by the retailer, can be any string. If this value is unknown or not specified, empty string is returned

Responses

Response Schema: application/json

orderId

required

number

AiFi internal order id

totalPrice

required

string <number>

A calculated total for the order

subtotalPrice

required

string <number>

Subtotal price (totalPrice - totalTax = subtotalPrice) for the order

totalTax

required

string <number>

Total tax for the order

required

Array of objects (CartItem)

adjusted list of items in the cart of the customer

Array

id

required

string or null <integer>

Internal AiFi product id, at least one of id or externalId should be provided, if id is provided then it takes precedence over externalId

externalId

required

string or null

At least one of id or externalId should be provided, if id is provided then it takes precedence over externalId

quantity

required

number

totalPrice

required

string <number>

subtotal price + total tax

subtotalPrice

required

string <number>

subtotal price of the product line item without any taxes

totalTax

required

string <number>

total tax of the product line item

required

Array of objects (TaxLine)

list of taxes

Array

title required	string or null
rate required	string <float> Tax rate in float format. For example, '0.19' means 0.19 x 100 = 19%
amount required	string <float> Tax amount in float format.
taxId required	string An unique identifier of the tax

isDeposit

boolean

describe if the cart item is a deposit item, if so it can be treated specially

Request samples

Payload

Content type

application/json

{"sessionId": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"session": {"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"id": 0,
"customerId": 0,
"code": "c69bb289-1190-4156-b9f6-bfb7f61e85db",
"codeFirstSuccesfullyScannedAt": "2019-08-24T14:15:22Z",
"codeLastSuccesfullyScannedAt": "2019-08-24T14:15:22Z",
"customerFirstEnteredAt": "2019-08-24T14:15:22Z",
"customerLastEnteredAt": "2019-08-24T14:15:22Z",
"customerFirstExitedAt": "2019-08-24T14:15:22Z",
"customerLastExitedAt": "2019-08-24T14:15:22Z",
"customerPaymentInstrumentId": 0,
"customerSatisfaction": 95,
"customerSatisfactionSubmitted": false,
"groupSize": 0,
"visitors": 0,
"locationId": "string",
"priority": 0,
"sessionToken": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"sessionId": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"referencedSessionId": null,
"status": "active",
"storeId": 0,
"storeIdScannableAt": 0,
"suspectedFraud": false,
"metadata": {"events": [{"eventId": "6bdbfb2d-65b2-491c-bc97-c0ac73338476",
"metadata": {"key": "value"
}
}
],
"exampleKey": "exampleValue"
},
"expiresAt": "2019-08-24T14:15:22Z"
},
"customer": {"externalId": "string",
"metadata": {"arbitraryKey": "arbitraryValue"
},
"id": "string",
"role": "customer"
},
"storeId": 0,
"store": {"oasisApiStoreId": 0,
"aifiUniqueStoreId": "string"
},
"storeExternalId": "string",
"timeOfOrigin": "2019-08-24T14:15:22Z",
"timeOfIssue": "2019-08-24T14:15:22Z",
"cart": [{"id": "string",
"name": "string",
"barcode": "string",
"category": "string",
"sku": "string",
"thumbnail": "string",
"externalId": "string",
"price": 0,
"productSnapshot": {"name": "string",
"price": "string",
"barcode": "string",
"category": "string",
"thumbnail": "string",
"weight": 0,
"sku": "string",
"externalId": "string",
"taxCode": "string",
"id": 0,
"productId": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
},
"quantity": 0,
"subtotalPrice": "1.80",
"totalPrice": "2.15",
"totalTax": "0.35",
"taxLines": [{"taxId": "string",
"title": "string",
"rate": "string",
"amount": "string"
}
]
}
],
"metadata": {"cart": {"priceIncludesTax": true
}
},
"orderId": 0,
"status": "reviewed",
"totalPrice": "10.99",
"totalTax": "0.99",
"subtotalPrice": "10.00",
"payment": {"paymentProvider": "NONE",
"paymentInstrument": {"type": "card",
"cardBin": "string",
"cardLast4": "string",
"cardExpMonth": 0,
"cardExpYear": 0,
"cardBrand": "string"
}
}
}

Response samples

200

Content type

application/json

{"orderId": 123,
"totalPrice": "10.99",
"subtotalPrice": "10.00",
"totalTax": "0.99",
"cart": [{"id": "28587028316208",
"externalId": "some-external-id-208",
"quantity": 1,
"totalPrice": "5.40",
"subtotalPrice": "5.38",
"totalTax": "0.02",
"taxLines": [{"title": "string",
"rate": "string",
"amount": "string",
"taxId": "string"
}
],
"isDeposit": true
}
]
}

Push - remote register

start remote register

AiFi system shall call this webhook during in /api/admin/v2/customers/remote-register is called in AiFi system.

This webhook is to notify the Checkout-UI that it should start a flow of registering new customer, with specified sessionId.

Request Body schema: application/json
required

storeId

required

integer

AiFi store id

required

object (StoreIdsDto)

oasisApiStoreId required	integer Store identifier that is only internal to cloud-api
aifiUniqueStoreId required	string or null Unique identifier across all AiFi stores. it will only be filled in by TechOPS/deployment engineers

storeExternalId

required

string or null

Retailer store id

timeOfOrigin

required

string <date-time>

ISO formatted creation time of the event, that caused this webhook to be sent

timeOfIssue

required

string <date-time>

ISO formatted time, in which this webhook was sent

token

required

string

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.

tokenType

string

Default: "SESSION_ID"

Enum: "NONE" "STRIPE" "PAYTER" "ADYEN" "FREEDOM_PAY" "GENERIC" "SESSION_ID"

Registration token type

checkInDeviceId

required

integer or null

This property will contain a null value if the endpoint /api/admin/v2/customers/remote-register was used. However, it's guaranteed to have a proper value if the endpoint /api/admin/v2/stores/{storeId}/check-in/{checkInDeviceId}/remote-register was used

required

object or null

Customer information

externalId required	string or null Id of the customer in external system
metadata required	object or null This object can contain custom metadata information
id required	string <integer> AiFi customer id, formatted as string
role required	string Enum: "customer" "employee" "tester" "untracked" "unknown" Role of the customer

required

object or null

email required	string <email>
firstName required	string or null
lastName required	string or null
phone required	string or null
phoneNumber required	string or null Deprecated This property is deprecated. Please use phone instead

Responses

Request samples

Payload

Content type

application/json

{"storeId": 0,
"store": {"oasisApiStoreId": 0,
"aifiUniqueStoreId": "string"
},
"storeExternalId": "string",
"timeOfOrigin": "2019-08-24T14:15:22Z",
"timeOfIssue": "2019-08-24T14:15:22Z",
"token": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"tokenType": "NONE",
"checkInDeviceId": 0,
"customer": {"externalId": "string",
"metadata": {"arbitraryKey": "arbitraryValue"
},
"id": "string",
"role": "customer"
},
"customerPersonalInfo": {"email": "user@example.com",
"firstName": "string",
"lastName": "string",
"phone": "string",
"phoneNumber": "string"
}
}

Push - customer created

customer was created or updated

AiFi system shall call this webhook when a customer is created and his personal data is fully collected. Additionally, it will be called every time when existing customer's personal data is updated. Personal data considered here is either of [firstName, lastName, email, phoneNumber]. This webhook is intended to be only informative: no response is parsed and no action is taken regardless of the response.

Note: as an integrator, the URL you specify for this webhook is going to be exactly the URL that will be called. For example, if you specify "http://example-retailer-api.com/webhook", then exactly "http://example-retailer-api.com/webhook" will be called.

Request Body schema: application/json
required

required

object

Customer information

externalId required	string or null Id of the customer in external system
metadata required	object or null This object can contain custom metadata information
id required	string <integer> AiFi customer id, formatted as string
role required	string Enum: "customer" "employee" "tester" "untracked" "unknown" Role of the customer

timeOfOrigin

required

string <date-time>

ISO formatted creation time of the event, that caused this webhook to be sent

timeOfIssue

required

string <date-time>

ISO formatted time, in which this webhook was sent

required

object (CustomerPersonalInfoDto)

email required	string <email>
firstName required	string or null
lastName required	string or null
phone required	string or null
phoneNumber required	string or null Deprecated This property is deprecated. Please use phone instead

Responses

Response Schema: application/json

string

Request samples

Payload

Content type

application/json

{"customer": {"externalId": "string",
"metadata": {"arbitraryKey": "arbitraryValue"
},
"id": "string",
"role": "customer"
},
"timeOfOrigin": "2019-08-24T14:15:22Z",
"timeOfIssue": "2019-08-24T14:15:22Z",
"customerPersonalInfo": {"email": "user@example.com",
"firstName": "string",
"lastName": "string",
"phone": "string",
"phoneNumber": "string"
}
}

Response samples

200

Content type

application/json

"string"

Push - suspected fraud

possible fraudulent shoppers/strange behaviors are identified

AiFi system shall call this webhook when a possible fraudulent shoppers/strange behaviors are identified. This webhook is intended to be only informative: no response is parsed and no action is taken regardless of the response.

Request Body schema: application/json
required

sessionId

required

string

Deprecated

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system. Deprecated, usesession.sessionId

required

SessionShallowDto (object) or InvalidSessionInWebhookDto (object)

One of

createdAt required	string <date-time> ISO formatted date representing when the entity was created
updatedAt required	string <date-time> ISO formatted date representing when the entity was last updated
id required	integer
customerId required	integer AiFi customer id
code required	string An entry code that can rendered as QR and used to enter AiFi store
codeFirstSuccesfullyScannedAt required	string or null <date-time> ISO formatted date, the first time when the QR get scanned successfully
codeLastSuccesfullyScannedAt required	string or null <date-time> ISO formatted date, the last time when the QR get scanned successfully
customerFirstEnteredAt required	string or null <date-time> ISO formatted time, when the first shopper enter the store
customerLastEnteredAt required	string or null <date-time> ISO formatted time, when the last shopper enter the store
customerFirstExitedAt required	string or null <date-time> ISO formatted time, when the first shopper exit the store
customerLastExitedAt required	string or null <date-time> ISO formatted time, when the last shopper exit the store
customerPaymentInstrumentId required	integer or null Payment instrument id
customerSatisfaction required	integer or null [ 0 .. 100 ] Satisfaction from the shopping session submitted by the customer. Can be null if not submitted or when customer wished to not ask him.
customerSatisfactionSubmitted required	boolean Default: false Whether satisfaction has been submitted
groupSize required	integer Expected group size associated with the shopping session
visitors required	integer Actual group size associated with the shopping session
locationId required	string or null
priority required	integer [ -10 .. 10 ] Default: 0 Customer priority. default to 0, which means any regular customer. customers with higher priority will have their shopping sessions prioritized during processing, the lower priority is opposite.
sessionToken required	string A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.
sessionId required	string A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.
referencedSessionId required	string or null Default: null Referenced session token, that points to the source session
status required	string Enum: "active" "declined" "validated" "checkout_performed"
storeId required	integer or null AiFi store id
storeIdScannableAt required	integer or null the id of store which the QrCode of test case can be valided. It can be scanned at any store if the value is null.
suspectedFraud required	boolean Default: false Indicate whether the shopping session is suspected fraud
metadata required	object Represents an arbitrary object. Note that the `events` key is reserved by AiFi for ThirdParty and Handoff Events. The value provided in the `metadata` field will completely overwrite the existing object. If your integration depends on the `events` key in the metadata, ensure it is preserved to avoid accidental deletion. To add new keys to the existing metadata object: Retrieve the current metadata using the Get Session List endpoint. Merge the retrieved metadata with the new keys you wish to add. Submit the updated object in the `metadata` field. Be cautious, as replacing the `metadata` value without preserving necessary keys may lead to unintended data loss.
expiresAt required	string <date-time> ISO formatted date at which this entry code will expire

required

object

Customer information

externalId required	string or null Id of the customer in external system
metadata required	object or null This object can contain custom metadata information
id required	string <integer> AiFi customer id, formatted as string
role required	string Enum: "customer" "employee" "tester" "untracked" "unknown" Role of the customer

storeId

required

integer

AiFi store id

required

object (StoreIdsDto)

oasisApiStoreId required	integer Store identifier that is only internal to cloud-api
aifiUniqueStoreId required	string or null Unique identifier across all AiFi stores. it will only be filled in by TechOPS/deployment engineers

storeExternalId

required

string or null

Retailer store id

timeOfOrigin

required

string <date-time>

ISO formatted creation time of the event, that caused this webhook to be sent

timeOfIssue

required

string <date-time>

ISO formatted time, in which this webhook was sent

required

object (PaymentInfoDto)

paymentProvider

required

string

Enum: "NONE" "STRIPE" "PAYTER" "ADYEN" "FREEDOM_PAY" "GENERIC"

Name of the payment provider

required

object or null

type required	string Default: "card"
cardBin required	string or null The first 6-8 digits of a card's number. Null if unknown
cardLast4 required	string The last 4 digits of the card's number. Empty string if unknown
cardExpMonth required	integer Integer representation of the month in range [1..12]. 1 means January, 12 December. Special value 0 is returned, if unknown
cardExpYear required	integer 4 digit year. Special value 0 is returned, if unknown
cardBrand required	string A card brand. Allowed values, if payment integration is provided by OASIS platform, are [`american express`, `diners club`, `discover`, `JCB`, `mastercard`, `unionpay`, `visa`]. If payment integration is provided by the retailer, can be any string. If this value is unknown or not specified, empty string is returned

Responses

Request samples

Payload

Content type

application/json

{"sessionId": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"session": {"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"id": 0,
"customerId": 0,
"code": "c69bb289-1190-4156-b9f6-bfb7f61e85db",
"codeFirstSuccesfullyScannedAt": "2019-08-24T14:15:22Z",
"codeLastSuccesfullyScannedAt": "2019-08-24T14:15:22Z",
"customerFirstEnteredAt": "2019-08-24T14:15:22Z",
"customerLastEnteredAt": "2019-08-24T14:15:22Z",
"customerFirstExitedAt": "2019-08-24T14:15:22Z",
"customerLastExitedAt": "2019-08-24T14:15:22Z",
"customerPaymentInstrumentId": 0,
"customerSatisfaction": 95,
"customerSatisfactionSubmitted": false,
"groupSize": 0,
"visitors": 0,
"locationId": "string",
"priority": 0,
"sessionToken": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"sessionId": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"referencedSessionId": null,
"status": "active",
"storeId": 0,
"storeIdScannableAt": 0,
"suspectedFraud": false,
"metadata": {"events": [{"eventId": "6bdbfb2d-65b2-491c-bc97-c0ac73338476",
"metadata": {"key": "value"
}
}
],
"exampleKey": "exampleValue"
},
"expiresAt": "2019-08-24T14:15:22Z"
},
"customer": {"externalId": "string",
"metadata": {"arbitraryKey": "arbitraryValue"
},
"id": "string",
"role": "customer"
},
"storeId": 0,
"store": {"oasisApiStoreId": 0,
"aifiUniqueStoreId": "string"
},
"storeExternalId": "string",
"timeOfOrigin": "2019-08-24T14:15:22Z",
"timeOfIssue": "2019-08-24T14:15:22Z",
"payment": {"paymentProvider": "NONE",
"paymentInstrument": {"type": "card",
"cardBin": "string",
"cardLast4": "string",
"cardExpMonth": 0,
"cardExpYear": 0,
"cardBrand": "string"
}
}
}

Push - tracking

tracking

The AiFi system will trigger this webhook when the Retailer will call us on any of the below endpoints. Its primary function is to inform an external system about the association match of an individual within the AiFi system.

/stores/:storeId/idapDevices/:idapDeviceId/frame-annotation-event

Request Body schema: application/json
required

storeId

required

integer

AiFi store id

required

object (StoreIdsDto)

oasisApiStoreId required	integer Store identifier that is only internal to cloud-api
aifiUniqueStoreId required	string or null Unique identifier across all AiFi stores. it will only be filled in by TechOPS/deployment engineers

timeOfOrigin

required

string <date-time>

ISO formatted creation time of the event, that caused this webhook to be sent

timeOfIssue

required

string <date-time>

ISO formatted time, in which this webhook was sent

shopperId

required

string or null

Identifier of the Shopper. It can be null when AiFi will not be able to match Shopper

uniqueEventId

required

string

External unique event id that comes to AiFi systems from outside system

Responses

Request samples

Payload

Content type

application/json

{"storeId": 0,
"store": {"oasisApiStoreId": 0,
"aifiUniqueStoreId": "string"
},
"timeOfOrigin": "2019-08-24T14:15:22Z",
"timeOfIssue": "2019-08-24T14:15:22Z",
"shopperId": "string",
"uniqueEventId": "string"
}

Push - restricted products interactions

restricted products interactions

The AiFi system will trigger this webhook when shopper will interact with any of restricted products

Request Body schema: application/json
required

sessionId

required

string

Deprecated

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system. Deprecated, usesession.sessionId

required

object

Customer information

externalId required	string or null Id of the customer in external system
metadata required	object or null This object can contain custom metadata information
id required	string <integer> AiFi customer id, formatted as string
role required	string Enum: "customer" "employee" "tester" "untracked" "unknown" Role of the customer

storeId

required

integer

AiFi store id

required

object (StoreIdsDto)

oasisApiStoreId required	integer Store identifier that is only internal to cloud-api
aifiUniqueStoreId required	string or null Unique identifier across all AiFi stores. it will only be filled in by TechOPS/deployment engineers

storeExternalId

required

string or null

Retailer store id

timeOfOrigin

required

string <date-time>

ISO formatted creation time of the event, that caused this webhook to be sent

timeOfIssue

required

string <date-time>

ISO formatted time, in which this webhook was sent

eventId

required

string

Source event identifier

required

object (RestrictedProductsInteractionShopperDto)

shopperId required	string Identifier of the Shopper
shopperFlags required	string Enum: "POTENTIALLY_INTERACTED_WITH_ALCOHOL" "POTENTIALLY_SUSPICIOUS_BEHAVIOUR"

required

SessionShallowWithFlagsDto (object) or InvalidSessionInWebhookDto (object)

One of

createdAt required	string <date-time> ISO formatted date representing when the entity was created
updatedAt required	string <date-time> ISO formatted date representing when the entity was last updated
id required	integer
customerId required	integer AiFi customer id
code required	string An entry code that can rendered as QR and used to enter AiFi store
codeFirstSuccesfullyScannedAt required	string or null <date-time> ISO formatted date, the first time when the QR get scanned successfully
codeLastSuccesfullyScannedAt required	string or null <date-time> ISO formatted date, the last time when the QR get scanned successfully
customerFirstEnteredAt required	string or null <date-time> ISO formatted time, when the first shopper enter the store
customerLastEnteredAt required	string or null <date-time> ISO formatted time, when the last shopper enter the store
customerFirstExitedAt required	string or null <date-time> ISO formatted time, when the first shopper exit the store
customerLastExitedAt required	string or null <date-time> ISO formatted time, when the last shopper exit the store
customerPaymentInstrumentId required	integer or null Payment instrument id
customerSatisfaction required	integer or null [ 0 .. 100 ] Satisfaction from the shopping session submitted by the customer. Can be null if not submitted or when customer wished to not ask him.
customerSatisfactionSubmitted required	boolean Default: false Whether satisfaction has been submitted
groupSize required	integer Expected group size associated with the shopping session
visitors required	integer Actual group size associated with the shopping session
locationId required	string or null
priority required	integer [ -10 .. 10 ] Default: 0 Customer priority. default to 0, which means any regular customer. customers with higher priority will have their shopping sessions prioritized during processing, the lower priority is opposite.
sessionToken required	string A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.
sessionId required	string A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.
referencedSessionId required	string or null Default: null Referenced session token, that points to the source session
status required	string Enum: "active" "declined" "validated" "checkout_performed"
storeId required	integer or null AiFi store id
storeIdScannableAt required	integer or null the id of store which the QrCode of test case can be valided. It can be scanned at any store if the value is null.
suspectedFraud required	boolean Default: false Indicate whether the shopping session is suspected fraud
metadata required	object Represents an arbitrary object. Note that the `events` key is reserved by AiFi for ThirdParty and Handoff Events. The value provided in the `metadata` field will completely overwrite the existing object. If your integration depends on the `events` key in the metadata, ensure it is preserved to avoid accidental deletion. To add new keys to the existing metadata object: Retrieve the current metadata using the Get Session List endpoint. Merge the retrieved metadata with the new keys you wish to add. Submit the updated object in the `metadata` field. Be cautious, as replacing the `metadata` value without preserving necessary keys may lead to unintended data loss.
expiresAt required	string <date-time> ISO formatted date at which this entry code will expire
shoppingSessionFlags required	Array of strings Items Enum: "POTENTIALLY_INTERACTED_WITH_ALCOHOL" "POTENTIALLY_SUSPICIOUS_BEHAVIOUR"

shoppingSessionFlags

required

Array of strings

Deprecated

Items Enum: "POTENTIALLY_INTERACTED_WITH_ALCOHOL" "POTENTIALLY_SUSPICIOUS_BEHAVIOUR"

Use session.shoppingSessionFlags

productIds

required

Array of strings

List of products with interaction

gondolaIds

required

Array of integers

List of gondolas

Responses

Request samples

Payload

Content type

application/json

{"sessionId": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"customer": {"externalId": "string",
"metadata": {"arbitraryKey": "arbitraryValue"
},
"id": "string",
"role": "customer"
},
"storeId": 0,
"store": {"oasisApiStoreId": 0,
"aifiUniqueStoreId": "string"
},
"storeExternalId": "string",
"timeOfOrigin": "2019-08-24T14:15:22Z",
"timeOfIssue": "2019-08-24T14:15:22Z",
"eventId": "string",
"shopper": {"shopperId": "string",
"shopperFlags": "POTENTIALLY_INTERACTED_WITH_ALCOHOL"
},
"session": {"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"id": 0,
"customerId": 0,
"code": "c69bb289-1190-4156-b9f6-bfb7f61e85db",
"codeFirstSuccesfullyScannedAt": "2019-08-24T14:15:22Z",
"codeLastSuccesfullyScannedAt": "2019-08-24T14:15:22Z",
"customerFirstEnteredAt": "2019-08-24T14:15:22Z",
"customerLastEnteredAt": "2019-08-24T14:15:22Z",
"customerFirstExitedAt": "2019-08-24T14:15:22Z",
"customerLastExitedAt": "2019-08-24T14:15:22Z",
"customerPaymentInstrumentId": 0,
"customerSatisfaction": 95,
"customerSatisfactionSubmitted": false,
"groupSize": 0,
"visitors": 0,
"locationId": "string",
"priority": 0,
"sessionToken": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"sessionId": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"referencedSessionId": null,
"status": "active",
"storeId": 0,
"storeIdScannableAt": 0,
"suspectedFraud": false,
"metadata": {"events": [{"eventId": "6bdbfb2d-65b2-491c-bc97-c0ac73338476",
"metadata": {"key": "value"
}
}
],
"exampleKey": "exampleValue"
},
"expiresAt": "2019-08-24T14:15:22Z",
"shoppingSessionFlags": ["POTENTIALLY_INTERACTED_WITH_ALCOHOL"
]
},
"shoppingSessionFlags": ["POTENTIALLY_INTERACTED_WITH_ALCOHOL"
],
"productIds": ["string"
],
"gondolaIds": [0
]
}

Push - identity matching

identity matching

AiFi system will trigger this webhook once it detects that a visitor shopper can be matched automatically to some registered session. As an integrator, upon receiving, you should create a new session (for the same customer to whom the registered session belongs to) and assign the visitor shopper to it. The intended result is to make sure that this shopper is no longer a visitor but a registered shopper and therefore can be charged upon finishing his shopping journey.

Request Body schema: application/json
required

sessionId

required

string

Deprecated

A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system. Deprecated, usesession.sessionId

required

object

Customer information

externalId required	string or null Id of the customer in external system
metadata required	object or null This object can contain custom metadata information
id required	string <integer> AiFi customer id, formatted as string
role required	string Enum: "customer" "employee" "tester" "untracked" "unknown" Role of the customer

storeId

required

integer

AiFi store id

required

object (StoreIdsDto)

oasisApiStoreId required	integer Store identifier that is only internal to cloud-api
aifiUniqueStoreId required	string or null Unique identifier across all AiFi stores. it will only be filled in by TechOPS/deployment engineers

storeExternalId

required

string or null

Retailer store id

timeOfOrigin

required

string <date-time>

ISO formatted creation time of the event, that caused this webhook to be sent

timeOfIssue

required

string <date-time>

ISO formatted time, in which this webhook was sent

required

object

Provides details about the session for the registered shopper that was matched with the visitor shopper. During identity matching, the system attempts to associate the visitor shopper with the corresponding registered shopper. Ultimately, the goal is to link the visitor shopper to the session of the same customer for whom the registered session was originally created.

createdAt required	string <date-time> ISO formatted date representing when the entity was created
updatedAt required	string <date-time> ISO formatted date representing when the entity was last updated
id required	integer
customerId required	integer AiFi customer id
code required	string An entry code that can rendered as QR and used to enter AiFi store
codeFirstSuccesfullyScannedAt required	string or null <date-time> ISO formatted date, the first time when the QR get scanned successfully
codeLastSuccesfullyScannedAt required	string or null <date-time> ISO formatted date, the last time when the QR get scanned successfully
customerFirstEnteredAt required	string or null <date-time> ISO formatted time, when the first shopper enter the store
customerLastEnteredAt required	string or null <date-time> ISO formatted time, when the last shopper enter the store
customerFirstExitedAt required	string or null <date-time> ISO formatted time, when the first shopper exit the store
customerLastExitedAt required	string or null <date-time> ISO formatted time, when the last shopper exit the store
customerPaymentInstrumentId required	integer or null Payment instrument id
customerSatisfaction required	integer or null [ 0 .. 100 ] Satisfaction from the shopping session submitted by the customer. Can be null if not submitted or when customer wished to not ask him.
customerSatisfactionSubmitted required	boolean Default: false Whether satisfaction has been submitted
groupSize required	integer Expected group size associated with the shopping session
visitors required	integer Actual group size associated with the shopping session
locationId required	string or null
priority required	integer [ -10 .. 10 ] Default: 0 Customer priority. default to 0, which means any regular customer. customers with higher priority will have their shopping sessions prioritized during processing, the lower priority is opposite.
sessionToken required	string A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.
sessionId required	string A unique token to identify a shopping session. Note, sessionToken and sessionId are same concept in AIFI system.
referencedSessionId required	string or null Default: null Referenced session token, that points to the source session
status required	string Enum: "active" "declined" "validated" "checkout_performed"
storeId required	integer or null AiFi store id
storeIdScannableAt required	integer or null the id of store which the QrCode of test case can be valided. It can be scanned at any store if the value is null.
suspectedFraud required	boolean Default: false Indicate whether the shopping session is suspected fraud
metadata required	object Represents an arbitrary object. Note that the `events` key is reserved by AiFi for ThirdParty and Handoff Events. The value provided in the `metadata` field will completely overwrite the existing object. If your integration depends on the `events` key in the metadata, ensure it is preserved to avoid accidental deletion. To add new keys to the existing metadata object: Retrieve the current metadata using the Get Session List endpoint. Merge the retrieved metadata with the new keys you wish to add. Submit the updated object in the `metadata` field. Be cautious, as replacing the `metadata` value without preserving necessary keys may lead to unintended data loss.
expiresAt required	string <date-time> ISO formatted date at which this entry code will expire

visitorShopperId

required

string

Identifier of the Visitor shopper that was matched with registered shopper during identity matching

Responses

Request samples

Payload

Content type

application/json

{"sessionId": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"customer": {"externalId": "string",
"metadata": {"arbitraryKey": "arbitraryValue"
},
"id": "string",
"role": "customer"
},
"storeId": 0,
"store": {"oasisApiStoreId": 0,
"aifiUniqueStoreId": "string"
},
"storeExternalId": "string",
"timeOfOrigin": "2019-08-24T14:15:22Z",
"timeOfIssue": "2019-08-24T14:15:22Z",
"session": {"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"id": 0,
"customerId": 0,
"code": "c69bb289-1190-4156-b9f6-bfb7f61e85db",
"codeFirstSuccesfullyScannedAt": "2019-08-24T14:15:22Z",
"codeLastSuccesfullyScannedAt": "2019-08-24T14:15:22Z",
"customerFirstEnteredAt": "2019-08-24T14:15:22Z",
"customerLastEnteredAt": "2019-08-24T14:15:22Z",
"customerFirstExitedAt": "2019-08-24T14:15:22Z",
"customerLastExitedAt": "2019-08-24T14:15:22Z",
"customerPaymentInstrumentId": 0,
"customerSatisfaction": 95,
"customerSatisfactionSubmitted": false,
"groupSize": 0,
"visitors": 0,
"locationId": "string",
"priority": 0,
"sessionToken": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"sessionId": "d3a00526-1864-4f6e-bb2d-46e3ab7fa780",
"referencedSessionId": null,
"status": "active",
"storeId": 0,
"storeIdScannableAt": 0,
"suspectedFraud": false,
"metadata": {"events": [{"eventId": "6bdbfb2d-65b2-491c-bc97-c0ac73338476",
"metadata": {"key": "value"
}
}
],
"exampleKey": "exampleValue"
},
"expiresAt": "2019-08-24T14:15:22Z"
},
"visitorShopperId": "string"
}

AiFi Cloud API (2.0)

Admin API - orders

List orders

query Parameters

Responses

Response Schema: application/json

Response Schema: application/json

Response samples

Create an order

Request Body schema: application/jsonrequired

Responses

Response Schema: application/json

Response Schema: application/json

Request samples

Response samples

Get order by id

path Parameters

query Parameters

Responses

Response Schema: application/json

Response Schema: application/json

Response samples

Update order by id

path Parameters

Request Body schema: application/jsonrequired

Responses

Response Schema: application/json

Response Schema: application/json

Request samples

Response samples

Retry order checkout

path Parameters

Responses

Response Schema: application/json

Response Schema: application/json

Response samples

Add vendor metadata to order

path Parameters

Request Body schema: application/jsonrequired

Responses

Response Schema: application/json

Response Schema: application/json

Request samples

Response samples

Admin API - products

List products snapshots

query Parameters

Responses

Response Schema: application/json

Response Schema: application/json

Response samples

List product variants

query Parameters

Responses

Response Schema: application/json

Response Schema: application/json

Response samples

Get product variant by id

path Parameters

Responses

Response Schema: application/json

Response Schema: application/json

Response samples

Delete product variant

path Parameters

Responses

Response Schema: application/json

Response samples

Update product variant

path Parameters

Request Body schema: application/jsonrequired

Responses

Response Schema: application/json

Response Schema: application/json

Request samples

Response samples

Get a default variant for product

path Parameters

Responses

Response Schema: application/json

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required