Kiliba logo
API docs by Redocly

Kiliba API (1.0.0)

Download OpenAPI specification:

E-mail: sysadmin@kiliba.com

Welcome to the Kiliba API!

This API allows you to read and write data from your Kiliba account, enabling seamless integration with your systems and workflows.

To get started, you'll need your API key, which is available on the Integrations page of your Kiliba dashboard.

Happy building!

— The Kiliba Team

🔐 Authentication

To authenticate your requests, include your API key in the X-API-Key header of each request.

curl -X GET "https://preprod.api.kiliba.ai/client/v1/customers/paginated" \
  -H "X-API-Key: your_api_key_here"

Kiliba customers

List, whitelist and blacklist customers.

List customers

List customers.

Authorizations:
ApiKeyAuth
query Parameters
limit
number [ 1 .. 10000 ]
Default: 1000

Page size

page
number >= 1
Default: 1

Page index

date_update
string <date-time>

Minimum (included) value for date_update, default timezone is UTC

blacklist_date
string <date-time>

Minimum (included) value for blacklist_date, default timezone is UTC

blacklist_reasons
Array of strings

Blacklist reasons to filter, empty value for null

statuses
Array of strings
Items Enum: "subscribed" "blacklisted" "invalidContact" "blocked" "ignoredCa" "warmup"

Customer status

whitelist_date
string <date-time>

Minimum (included) value for whitelist_date, default timezone is UTC

whitelist_reasons
Array of strings

Whitelist reasons to filter, empty value for null

Responses

Response samples

Content type
application/json
{
  • "customers": [
    ],
  • "total": 0,
  • "totalOutOfPackage": 0
}

Blacklist customers

Blacklist customers with reason apiclientv1, if customer has a Kiliba blacklist reason (example when customer out of package), it will not be possible to modify it.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
customer_emails
required
Array of strings

List of customer emails to blacklist.

Responses

Request samples

Content type
application/json
{
  • "customer_emails": [
    ]
}

Response samples

Content type
application/json
{
  • "processed_emails": 0
}

Whitelist customers

Whitelist customers with reason apiclientv1, if customer has a Kiliba blacklist reason (example when customer out of package), it will not be possible to whitelist it.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
customer_emails
required
Array of strings

List of customer emails to whitelist.

Responses

Request samples

Content type
application/json
{
  • "customer_emails": [
    ]
}

Response samples

Content type
application/json
{
  • "processed_emails": 0
}

Import your data

Import your own data into Kiliba. This feature is currently in beta and must first be enabled by the technical team before you can start.

Bulk import product categories

Allows bulk import of product categories from external sources into Kiliba.

Each request can include up to 1000 product categories with a maximum payload size of 6 MB.

Product categories submitted to this endpoint must include all required properties. The endpoint will either create a new category if it does not exist or fully overwrite an existing category.

Partial updates are not supported; the request must contain all product category properties.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
Array (<= 1000 items)
required
string or number

The product category ID in your system.

This is a mandatory field and serves as the unique key to identify a category.

(string or number) or null

The parent product category ID in your system. Can be used to define a hierarchy of categories.

name
required
string

The name of the product category in your system.

object

A key-value store for user-defined properties.

This field allows storing arbitrary metadata as a JSON object.

The total serialized size of the object must not exceed 2 KB.

Kiliba does not process or utilize this metadata.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "processed": 0
}

Bulk import products

Allows bulk import of products from external sources into Kiliba.

Each request can include up to 1000 products with a maximum payload size of 6 MB.

Products submitted to this endpoint must include all required properties. The endpoint will either create a new product if it does not exist or fully overwrite an existing product.

Partial updates are not supported; the request must contain all product properties.

To mark a product as deleted, set the deleted property to true. This is the only case where a product can be submitted with only its IDs and the { deleted: true } property.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
Array (<= 1000 items)
Any of
required
string or number

The product ID in your system.

This is a mandatory field and is part of the composite key (with variantId) used to uniquely identify a product.

It will also serve as a reference when products are linked during the import of carts and orders.

(string or number) or null

The product variant ID in your system.

This is an optional field and is part of the composite key (with id) used to uniquely identify a product.

It is used to define product variations, such as a shirt with different sizes or colors.

Any product with a populated variantId will be treated as a product with variations.

This field will also serve as a reference when products are linked during the import of carts and orders.

string or null

The product SKU in your system.

required
object

The product name in your system.

The keys of the object must be the ISO 639-1 language codes.

object

The product description in your system.

The keys of the object must be the ISO 639-1 language codes.

price
required
number >= 0

The price of the product excluding tax. Must be a non-negative number.

priceWithTax
required
number >= 0

The price of the product including tax. Must be a non-negative number.

Array of objects

An array of promotional details for the product.

Each promotion includes a price, a price with tax, and optional start and end dates.

canBeRecommended
boolean
Default: true

Indicates if the product can be recommended in communications (marketing, smartletter, ...).

Set to false to disable recommendations for this product. It will never appear in any emails.

quantity
required
integer [ 0 .. 9007199254740991 ]

The quantity of the product in stock. Must be a non-negative integer.

inStock
required
boolean

Indicates if the product is currently in stock.

Set to true if the product is available, otherwise false.

We will only recommend products that are out of stock if recommendIfOutOfStock is set to true.

recommendIfOutOfStock
boolean
Default: false

Indicates if the product can still be recommended even when out of stock.

Set to true to allow recommendations when the product is out of stock.

string or null

The URL of the product image.

relativeUrl
required
string

The relative URL of the product in your system.

absoluteUrl
required
string <uri>

The absolute URL of the product in your system.

isDefaultVariant
boolean
Default: false

Indicates if this is the default variant of the product.

If set to true, this variant will be recommended by default.

The last variant pushed with this property set to true will be considered the default variant.

required
Array of strings or numbers non-empty

A list of category IDs where this product is included.

A product must have at least one category.

This references IDs from imported categories.

required
string or number

The default category ID for the product.

object

A key-value store for user-defined properties.

This field allows storing arbitrary metadata as a JSON object.

The total serialized size of the object must not exceed 2 KB.

Kiliba does not process or utilize this metadata.

createdAt
required
string <date-time>

The creation date of the product in ISO 8601 format.

updatedAt
required
string <date-time>

The last update date of the product in ISO 8601 format.

deleted
boolean
Default: false

Set to true to mark the product as deleted.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "processed": 0
}

Bulk import customer groups

Allows bulk import of customer groups from external sources into Kiliba.

Each request can include up to 1000 customer groups with a maximum payload size of 6 MB.

Customer groups submitted to this endpoint must include all required properties. The endpoint will either create a new customer group if it does not exist or fully overwrite an existing customer group.

Partial updates are not supported; the request must contain all customer group properties.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
Array (<= 1000 items)
required
string or number

The customer group ID in your system.

This is a mandatory field and serves as the unique key to identify a customer group.

name
required
string

The non-translatable name of the customer group.

object

A key-value store for user-defined properties.

This field allows storing arbitrary metadata as a JSON object.

The total serialized size of the object must not exceed 2 KB.

Kiliba does not process or utilize this metadata.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "processed": 0
}

Bulk import customers

Allows bulk import of customers from external sources into Kiliba.

Each request can include up to 1000 customers with a maximum payload size of 6 MB.

Customers submitted to this endpoint must include all required properties. The endpoint will either create a new customer if it does not exist or fully overwrite an existing customer.

Partial updates are not supported; the request must contain all customer properties.

To mark a customer as deleted, set the deleted property to true. This is the only case where a customer can be submitted with only its ID and the { deleted: true } property.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
Array (<= 1000 items)
Any of
required
string or number

The customer ID in your system.

This ID will be used as the reference for the customer ID in carts and orders imports.

email
required
string <email>

The email address of the customer.

string or null

The first name of the customer.

string or null

The last name of the customer.

string or null

The birthday of the customer in YYYY-MM-DD format.

number or null

The gender of the customer. 0 for unknown, 1 for man, 2 for woman.

emailMarketingConsent
required
boolean

Indicates if the customer has given consent to receive marketing emails.

smsMarketingConsent
required
boolean

Indicates if the customer has given consent to receive marketing SMS.

required
Array of strings or numbers non-empty

A list of shop IDs the customer is related to. At least one shop is required.

required
string or number

The default shop ID for the customer.

required
Array of strings or numbers non-empty

A list of customer group IDs the customer belongs to. At least one group is required.

required
string or number

The default customer group ID for the customer.

langIsoCode
required
string = 2 characters

The language of the customer using ISO 639-1 code.

object (importAddress)

The billing address of the customer.

createdAt
required
string <date-time>

The creation date of the customer in ISO 8601 format.

updatedAt
required
string <date-time>

The last update date of the customer in ISO 8601 format.

deleted
boolean
Default: false

Set to true to mark the customer as deleted.

object

A key-value store for user-defined properties.

This field allows storing arbitrary metadata as a JSON object.

The total serialized size of the object must not exceed 2 KB.

Kiliba does not process or utilize this metadata.

object

Flat custom fields payload used for secondary customer enrichment.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "processed": 0
}

Bulk import orders

Allows bulk import of orders from external sources into Kiliba.

Each request can include up to 1000 orders with a maximum payload size of 6 MB.

Orders submitted to this endpoint must include all required properties. The endpoint will either create a new order if it does not exist or fully overwrite an existing order.

Partial updates are not supported; the request must contain all order properties.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
Array (<= 1000 items)
required
string or number

The order ID in your system.

This is a mandatory field and serves as the unique key to identify an order.

string or null

The order reference in your system.

This is an optional field and can be used to provide a human-readable reference for the order.

status
required
string

The status of the order. Any string value is accepted.

(string or number) or null

The cart ID in your system that reference the cart associated with the order.

object

The customer associated with the order.

required
string or number

The shop ID in your system that reference the shop associated with the order.

object (importAddress)

The billing address associated with the order.

This includes details such as street address, city, country, and postal code.

amount
required
number >= 0

The real amount paid for the order excluding tax. Must be a non-negative number.

This represents the actual amount paid by the customer, not the calculated or expected amount.

amountWithTax
required
number >= 0

The real amount paid for the order including tax. Must be a non-negative number.

This represents the actual amount paid by the customer, including all applicable taxes.

required
Array of objects

A list of products included in the order.

Each product includes its ID, optional variant ID, quantity, and the amounts paid (with and without tax).

promoCodes
Array of strings
Default: []

A list of promo codes used in the order.

Each promo code is represented as a string.

createdAt
required
string <date-time>

The creation date of the order in ISO 8601 format.

updatedAt
required
string <date-time>

The last update date of the order in ISO 8601 format.

object

A key-value store for user-defined properties.

This field allows storing arbitrary metadata as a JSON object.

The total serialized size of the object must not exceed 2 KB.

Kiliba does not process or utilize this metadata.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "processed": 0
}

Bulk import carts

Allows bulk import of carts from external sources into Kiliba.

Each request can include up to 1000 carts with a maximum payload size of 6 MB.

Carts submitted to this endpoint must include all required properties. The endpoint will either create a new cart if it does not exist or fully overwrite an existing cart.

Partial updates are not supported; the request must contain all cart properties.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
Array (<= 1000 items)
required
string or number

The cart ID in your system.

This is a mandatory field and serves as the unique key to identify a cart.

object

The customer associated with the cart.

required
string or number

The shop ID in your system that reference the shop associated with the cart.

langIsoCode
required
string = 2 characters

The language of the cart using ISO 639-1 code.

amount
required
number >= 0

The total amount of the cart excluding tax. Must be a non-negative number.

This represents the calculated amount of the cart items.

amountWithTax
required
number >= 0

The total amount of the cart including tax. Must be a non-negative number.

This represents the calculated amount of the cart items including all applicable taxes.

required
Array of objects

A list of products included in the cart.

Each product includes its ID, optional variant ID, quantity, cumulative amounts, and URLs.

promoCodes
Array of strings
Default: []

A list of promo codes applied to the cart.

Each promo code is represented as a string.

object (importAddress)

The billing address associated with the cart.

This includes details such as street address, city, country, and postal code.

createdAt
required
string <date-time>

The creation date of the cart in ISO 8601 format.

updatedAt
required
string <date-time>

The last update date of the cart in ISO 8601 format.

object

A key-value store for user-defined properties.

This field allows storing arbitrary metadata as a JSON object.

The total serialized size of the object must not exceed 2 KB.

Kiliba does not process or utilize this metadata.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "processed": 0
}

Bulk import visits

Allows bulk import of visits from external sources into Kiliba.

This endpoint can handle both product visits and category visits.

Each request can include up to 1000 visits with a maximum payload size of 6 MB.

Visits submitted to this endpoint must include all required properties. The endpoint will either create a new visit if it does not exist or fully overwrite an existing visit.

Partial updates are not supported; the request must contain all visit properties.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
Array (<= 1000 items)
Any of
(string or number) or null

The customer ID in your system associated with the visit.

Omit this field if the visit belongs to a guest.

email
required
string <email>

The email address of the customer or guest associated with the visit.

This field is required and useful for identifying the visitor.

url
required
string <uri>

The URL visited by the customer.

date
required
string <date-time>

The date of the visit in ISO 8601 format.

object

A key-value store for user-defined properties.

This field allows storing arbitrary metadata as a JSON object.

The total serialized size of the object must not exceed 2 KB.

Kiliba does not process or utilize this metadata.

required
string or number

The product ID associated with the visit.

(string or number) or null

The product variant ID associated with the visit.

(string or number) or null

The category ID associated with the visit.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "processed": 0
}

Upload retail source files

Upload raw physical store files through pre-signed S3 URLs, then enqueue asynchronous parsing and publication into the ImportAPI downstream flow.

Create a retail import upload session

Creates an upload session for a physical store source file.

Use the returned pre-signed S3 URL to upload the raw file, then call the completion endpoint to trigger parsing and publication.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
filename
required
string non-empty

Original file name.

contentType
string non-empty
Default: "text/tab-separated-values"

MIME type of the uploaded file.

size
number >= 0
Default: 0

Raw file size in bytes.

provider
string
Default: "retail"
Value: "retail"
string or null

Optional dataset hint. Kiliba can also auto-detect the dataset after upload.

string or null

Optional parser hint. When omitted, Kiliba uses the parser configured on the account.

string or null

Optional parser version hint. When omitted, Kiliba uses the version configured by default on the account.

object

Responses

Request samples

Content type
application/json
{
  • "filename": "string",
  • "contentType": "text/tab-separated-values",
  • "size": 0,
  • "provider": "retail",
  • "datasetType": "string",
  • "adapterKey": "string",
  • "adapterVersion": "v1",
  • "sourceConfig": {
    }
}

Response samples

Content type
application/json
{
  • "uploadId": "string",
  • "status": "created",
  • "s3Key": "string",
  • "presignedUrl": "string",
  • "expiresAt": "string"
}

Complete a retail import upload session

Marks the raw upload as completed, validates the uploaded file size, then enqueues asynchronous parsing through the retail import worker.

Authorizations:
ApiKeyAuth
path Parameters
uploadId
required
string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA...

Upload session identifier.

Responses

Response samples

Content type
application/json
{
  • "uploadId": "string",
  • "status": "created",
  • "currentStage": "detect",
  • "detectionStatus": "pending",
  • "detectionError": {
    },
  • "datasetType": "string",
  • "adapterKey": "string",
  • "adapterVersion": "string",
  • "detectedDatasetType": "string",
  • "detectedAdapterKey": "string",
  • "detectedAdapterVersion": "string",
  • "detectedParserKey": "string",
  • "detectedParserVersion": "string",
  • "detectedDatasets": [
    ],
  • "latestAttemptId": "f9c2524e-9e28-4b41-bedc-c81b7dedf778",
  • "rowsTotal": 0,
  • "rowsAccepted": 0,
  • "rowsRejected": 0,
  • "reportS3Key": "string",
  • "outputs": [
    ]
}

Send transactional emails

Send transactional emails using a Kiliba template

Send a transactional email.

Send a transactional email.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
transactionalEmailId
required
string

Transactional email Id

email
required
string

Recipient email address

language
required
string

Language code used for rendering (fr, en, es ...)

required
object

Transactional variables map (keys without #, values as rendered strings)

Responses

Request samples

Content type
application/json
{
  • "transactionalEmailId": "string",
  • "email": "string",
  • "language": "string",
  • "variables": {
    }
}

Response samples

Content type
application/json
{
  • "status": "string"
}