openapi: 3.1.0
info:
title: Integration API
version: ''
description: |
Use the Integration API for user-facing, real time, high-traffic flows.
For example, use it to apply promotional offers or loyalty rewards during customer interactions,
track customer behavior, or deliver personalized incentives based on customer activity.
For more background information about this API, see
[Integration API](https://docs.talon.one/docs/dev/integration-api/overview).
> [!note] **Are you looking for a different API?**
> - To interact with the Campaign Manager for backoffice operations, see the [Management API](https://docs.talon.one/management-api).
> - To integrate with Talon.One from a CEP or CDP platform, see the [Third-party API](https://docs.talon.one/third-party-api).
## Authentication
Integration API keys are scoped to an Application and are independent of any user account.
A `401 Unauthorized` response means the key is invalid, expired, or scoped to a different
environment.
For details on generating and managing API keys, see
[Manage API keys](https://docs.talon.one/docs/product/applications/manage-api-keys).
## Response codes and error handling
Talon.One uses conventional HTTP response codes to indicate the success or failure of an API request.
Codes in the `2xx` range indicate success. Codes in the `4xx` range indicate the request failed based
on the information provided. Codes in the `5xx` range indicate an error with Talon.One servers.
Error responses include a `message` that summarizes what went wrong. Use it for logging and debugging.
When a request has one or more specific problems, the `errors` array lists each one separately:
- `title` gives a short description of the problem
- `source` shows where the error originated, for example, using a `pointer` property indicating the
problematic property in the request body.
| Code | Description | Action |
|------|-------------|--------|
| `2xx` | Success | None. |
| `400` | Bad request | Fix the request. For example, add a missing parameter or correct an invalid one. Not retryable. |
| `401` | Unauthorized | Provide a valid API key. Not retryable. |
| `404` | Not found | Check the resource path or ID. Not retryable. |
| `409` | Concurrency conflict | Switch to sequential requests. Retryable. |
| `429` | Rate limit exceeded | Retry with exponential backoff. |
| `5xx` | Server error | Retry with exponential backoff. |
## URL encoding
Encode all path and query parameter values that contain special characters. This applies to
customer profile IDs, session IDs, coupon codes, and any other user-supplied string passed as
a URL segment or query parameter.
For example, encode a `10$OFF_NOW` coupon code as `10%24OFF_NOW` before
including it in a request URL.
Requests with unencoded special characters may be misrouted or return unexpected errors.
For more information, see [HTML URL Encoding Reference](https://www.w3schools.com/tags/ref_urlencode.asp).
## Rate limiting
The Integration API returns `429 Too Many Requests` when you exceed the allowed request rate.
Implement exponential backoff before retrying.
To protect data integrity, a separate limit applies to **parallel requests for the same profile or
session**. For each customer profile or session integration ID, Talon.One allows up to **three parallel
requests**. It processes one immediately and queues up to two more. A request that arrives while the
queue is full receives a `409 Too many requests are updating this profile/session at the same time`
response.
This limit applies only to the following endpoints:
- [Update customer profile](https://docs.talon.one/integration-api#tag/Customer-profiles/operation/updateCustomerProfileV2)
- [Update customer session](https://docs.talon.one/integration-api/#tag/customer-sessions/PUT/v2/customer_sessions/{customerSessionId})
- [Track event](https://docs.talon.one/integration-api/#tag/events/POST/v2/events)
To avoid these `409` responses, send requests sequentially for each profile or session.
servers:
- url: https://yourbaseurl.talon.one
security:
- api_key_v1: []
tags:
- name: Achievements
description: |
Represents achievements that reward a customer profile for performing a number of specific actions or reaching a transactional milestone within a defined period.
For example, you can use achievements to award your customers when they purchase five cups of coffee in one week or when they purchase items worth $3000 in three months.
- name: Audiences
description: |
Represents lists of customer profiles that allow you to target specific groups of customers in your campaigns.
Audiences can be synced from customer data platforms or created directly in Talon.One.
See the [docs](https://docs.talon.one/docs/product/audiences/overview).
- name: Campaigns
description: |
Represents the primary resource used to control the behavior of the Talon.One Rule Engine.
They combine rulesets, coupons, and limits into a single unit.
See the [docs](https://docs.talon.one/docs/product/campaigns/overview).
- name: Catalogs
description: |
Represents a catalog of cart items with unique SKUs. Cart item catalogs allow you to synchronize your entire inventory with Talon.One.
See the [docs](https://docs.talon.one/docs/product/account/dev-tools/managing-cart-item-catalogs).
- name: Coupons
description: |
Represents unique codes belonging to a particular campaign. Coupons don't define any behavior on their own.
Instead the campaign ruleset can include rules that validate coupons and carry out particular effects.
See the [docs](https://docs.talon.one/docs/product/campaigns/coupons/coupon-page-overview).
- name: Customer profiles
description: |
Represents the customer's information. For instance, their contact information.
- name: Customer sessions
description: |
Represents the data related to a customer session. Typically, a customer session is the value and content of the customer's cart.
Sessions can be anonymous or linked to a customer profile and they have a life cycle from `open` to `closed`.
In general, a session is closed when the customer completes the checkout step.
Sessions are a key concept of Talon.One. We strongly recommend you read the [documentation about customer sessions](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions).
- name: Events
description: |
Represents a single occurrence of a specific customer action, for example, updating the cart or signing up for a newsletter.
There are 2 types of events:
- **Built-in events:** They are triggered by various endpoints, such as the [Update customer session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2) endpoint. [Learn more](https://docs.talon.one/docs/dev/concepts/entities/events).
- **Custom events:** They are triggered by the [Track event](https://docs.talon.one/integration-api#tag/Events/operation/trackEventV2) endpoint.
- name: Loyalty
description: |
Represents loyalty programs or concepts related to them.
Loyalty programs can be _profile-based_ or _card-based_, depending on whether loyalty points are linked
to [customer profiles](https://docs.talon.one/docs/product/applications/displaying-customer-profiles) or [loyalty cards](https://docs.talon.one/docs/product/loyalty-programs/card-based/card-based-overview).
See [the Product docs](https://docs.talon.one/docs/product/loyalty-programs/overview) for more information.
- name: Loyalty cards
description: |
Represents loyalty cards.
[Loyalty cards](https://docs.talon.one/docs/product/loyalty-programs/card-based/card-based-overview) allow your customers to collect and spend loyalty points within a card-based loyalty program.
- name: Referrals
description: |
Represents a referral code shared between a customer (advocate) and a prospect (friend).
A referral is defined by:
- an advocate: person who invited their friend via referral program.
- a friend: person who receives the invite from an advocate.
- a referral code: code to be redeemed by the advocate(s) once they referred their friend.
See the [docs](https://docs.talon.one/docs/product/campaigns/referrals/referral-overview).
paths:
/v2/customer_sessions/{customerSessionId}:
put:
operationId: updateCustomerSessionV2
summary: Update customer session
description: |
Update or create a [customer
session](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions).
The endpoint responds with the potential promotion rule
[effects](https://docs.talon.one/docs/dev/integration-api/api-effects) that
match the current cart.
For example, use this endpoint to share the contents of a customer's cart
with Talon.One.
> [!note] **Note**
> - The currency for the session and the cart items in it is the currency set for the Application linked to this session.
> - [Archived campaigns](https://docs.talon.one/docs/product/campaigns/managing-campaigns#archiving-a-campaign) are not considered for rule evaluation.
> [!note] To make request processing idempotent for this endpoint, include the `Idempotency-Key` header with an idempotency key in requests. Also:
> - Requests with the `Idempotency-Key` header are logged in the Talon.One access logs.
> - Responses for idempotent requests are stored in the database and expire 24 hours after the request is sent.
> - Idempotency keys are typically UUID keys and should not exceed 255 characters in length.
### Session management
To use this endpoint, start by learning about [customer
sessions](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions)
and their states and refer to the `state` parameter documentation the
request body schema docs below.
### Sessions and customer profiles
- To link a session to a customer profile, set the `profileId` parameter in
the request body to a customer profile's `integrationId`.
- While you can create an anonymous session with `profileId=""`, we
recommend you use a guest ID instead.
- A profile can be linked to simultaneous sessions in different
Applications. Either:
- Use unique session integration IDs or,
- Use the same session integration ID across all of the Applications.
> [!note] **Note**
> - If the specified profile does not exist, an empty profile is **created automatically**.
> You can update it with [Update customer profile](https://docs.talon.one/integration-api#tag/Customer-profiles/operation/updateCustomerProfileV2).
> - Updating a customer session returns a response with the new integration state. Use the `responseContent` property to save yourself extra API calls.
> For example, you can get the customer profile details directly without extra requests.
> - We recommend sending requests sequentially. See [Managing parallel requests](https://docs.talon.one/docs/dev/getting-started/integration-tutorial#managing-parallel-requests).
For more information, see:
- The introductory video in [Getting started](https://docs.talon.one/docs/dev/getting-started/overview).
- The [integration tutorial](https://docs.talon.one/docs/dev/tutorials/integrating-talon-one).
security:
- api_key_v1: []
tags:
- Customer sessions
parameters:
- name: dry
in: query
description: |
Indicates whether to persist the changes. Changes are ignored when `dry=true`.
When set to `true`:
- The endpoint considers **only** the payload that you pass when **closing** the session.
When you do not use the `dry` parameter, the endpoint behaves as a typical PUT endpoint. Each update builds upon the previous ones.
- You can use the `evaluableCampaignIds` body property to select specific campaigns to run.
[See the docs](https://docs.talon.one/docs/dev/integration-api/dry-requests).
example: false
required: false
schema:
type: boolean
- name: customerSessionId
in: path
required: true
description: |
The `integration ID` of the customer session. You set this ID when you create a customer session.
You can see existing customer session integration IDs in the Campaign Manager's **Sessions** menu, or via the
[List Application session](https://docs.talon.one/management-api#tag/Customer-data/operation/getApplicationSessions) endpoint.
**Notes**: - There is no length limit for this ID. - It must be URL-encoded. For example, replace spaces with `%20`. [Learn more](https://www.w3schools.com/tags/ref_urlencode.asp).
example: session1
schema:
type: string
- name: now
in: query
required: false
description: |
A timestamp value of a future date that acts as a current date when
included in the query.
Use this parameter, for example, to test campaigns that would be
evaluated for this customer session in the future (say, [scheduled
campaigns](https://docs.talon.one/docs/product/campaigns/settings/managing-campaign-schedule)).
> [!note] **Note**
> - It must be an RFC3339 timestamp string.
> - It can **only** be a date in the future.
> - It can **only** be used if the `dry` parameter in the query is set to `true`.
example: '2024-05-29T15:04:05+07:00'
schema:
type: string
format: date-time
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationRequest'
examples:
Full request:
summary: Full request
x-vertical: none
value:
customerSession:
profileId: URNGV8294NV
storeIntegrationId: STORE-001
evaluableCampaignIds:
- 10
- 12
couponCodes:
- XMAS-20-2021
referralCode: NT2K54D9
loyaltyCards:
- loyalty-card-1
state: open
cartItems:
- name: Air Glide
sku: SKU1241028
quantity: 1
price: 99.99
category: shoes
product:
name: sample_product
weight: 1130
height: 0
width: 0
length: 0
attributes:
image: 11.jpeg
material: leather
additionalCosts:
shipping:
price: 9
experimentVariantAllocations:
- experimentID: 1
variantID: 2
additionalCosts:
shipping:
price: 9
identifiers:
- d41306257915f83fe01e54092ae470f631161ea16fcf4415842eed41470386ea
attributes:
ShippingCity: Berlin
responseContent:
- customerSession
- customerProfile
eCommerce:
x-vertical: ecommerce
summary: 'Example: ecommerce'
description: |
Update a customer session with multiple cart items and attributes,
including SKUs, prices, and more.
value:
customerSession:
profileId: 382370BKDB946
cartItems:
- name: Wireless Bluetooth Headphones
sku: AUDIO-WH350
quantity: 1
price: 79.99
weight: 310
- name: USB-C Charging Cable
sku: CABLE-USBC-2M
quantity: 2
price: 15.99
weight: 40
responseContent:
- customerSession
- customerProfile
QSR & dining:
x-vertical: qsr
summary: 'Example: QSR & dining'
description: |
Update a customer session as a customer builds a combo meal, including
quantities, categories, and more.
value:
customerSession:
profileId: 382370BKDB946
cartItems:
- name: Cheeseburger
sku: BURGER-001
quantity: 1
price: 8.99
category: Main
- name: French Fries
sku: SIDE-002
quantity: 1
price: 3.49
category: Side
- name: Cola
sku: DRINK-003
quantity: 1
price: 2.49
category: Beverage
responseContent:
- customerSession
- customerProfile
- loyalty
Financial services:
x-vertical: finance
summary: 'Example: Financial services'
description: |
Update a customer session when a cardholder completes a purchase.
value:
customerSession:
profileId: customer-789
cartItems:
- name: Card Purchase - Electronics Store
sku: TXN-CC-001
quantity: 1
price: 250
attributes:
CardType: credit
MerchantCategory: electronics
TransactionType: card_payment
responseContent:
- customerSession
- customerProfile
- loyalty
Travel & hospitality:
x-vertical: travel
summary: 'Example: Travel & hospitality'
description: |
Update a customer session when a guest books a hotel stay to
automatically award bonus loyalty points for stays that exceed
the minimum night count.
value:
customerSession:
profileId: customer-321
cartItems:
- name: Deluxe Room - 5 nights
sku: HOTEL-ROOM-DLX
quantity: 5
price: 189
attributes:
CheckInDate: '2026-06-10'
CheckOutDate: '2026-06-15'
StayNights: 5
PropertyType: hotel
responseContent:
- customerSession
- customerProfile
- loyalty
description: body
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationStateV2'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized - Invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseWithStatus'
'409':
description: Too many requests or limit reached - Avoid parallel requests. See the [docs](https://docs.talon.one/docs/dev/tutorials/integrating-talon-one#managing-parallel-requests).
content:
application/json:
schema:
properties:
message:
type: string
example: Too many requests are updating this session at the same time
errors:
type: array
items: {}
StatusCode:
type: integer
example: 409
get:
operationId: getCustomerSession
summary: Get customer session
description: |
Get the details of the given customer session.
You can get the same data via other endpoints that also apply changes, which can help you save requests and increase performance. See:
- [Update customer session](#tag/Customer-sessions/operation/updateCustomerSessionV2)
- [Update customer profile](#tag/Customer-profiles/operation/updateCustomerProfileV2)
security:
- api_key_v1: []
tags:
- Customer sessions
parameters:
- name: customerSessionId
in: path
required: true
description: |
The `integration ID` of the customer session. You set this ID when you create a customer session.
You can see existing customer session integration IDs in the Campaign Manager's **Sessions** menu, or via the
[List Application session](https://docs.talon.one/management-api#tag/Customer-data/operation/getApplicationSessions) endpoint.
**Notes**: - There is no length limit for this ID. - It must be URL-encoded. For example, replace spaces with `%20`. [Learn more](https://www.w3schools.com/tags/ref_urlencode.asp).
example: session1
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationCustomerSessionResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized - Invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseWithStatus'
/v2/customer_sessions/{customerSessionId}/returns:
post:
operationId: returnCartItems
summary: Return cart items
description: |
Create a new return request for the specified cart items.
This endpoint automatically changes the session state from `closed` to
`partially_returned`.
> [!note] This will roll back any effects associated with these cart items.
> For more information, see [our documentation on session
> states](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions#customer-session-states)
> and [this tutorial](https://docs.talon.one/docs/dev/tutorials/partially-returning-a-session).
> [!note] To make request processing idempotent for this endpoint, include the `Idempotency-Key` header with an idempotency key in requests. Also:
> - Requests with the `Idempotency-Key` header are logged in the Talon.One access logs.
> - Responses for idempotent requests are stored in the database and expire 24 hours after the request is sent.
> - Idempotency keys are typically UUID keys and should not exceed 255 characters in length.
security:
- api_key_v1: []
tags:
- Customer sessions
parameters:
- name: dry
in: query
description: |
Indicates whether to persist the changes. Changes are ignored when `dry=true`.
example: false
required: false
schema:
type: boolean
- name: customerSessionId
in: path
required: true
description: |
The `integration ID` of the customer session. You set this ID when you create a customer session.
You can see existing customer session integration IDs in the Campaign Manager's **Sessions** menu, or via the
[List Application session](https://docs.talon.one/management-api#tag/Customer-data/operation/getApplicationSessions) endpoint.
example: session1
schema:
type: string
- name: runRuleEngine
in: query
description: |
When set to `true`, reevaluates the updated session after items are returned. Only reevaluates campaigns where `reevaluateOnReturn` is set to `true` and which produced an effect when the session was closed.
example: false
required: false
schema:
type: boolean
requestBody:
$ref: '#/components/requestBodies/ReturnIntegrationRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationStateV2'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized - Invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseWithStatus'
/v2/customer_sessions/{customerSessionId}/reopen:
put:
operationId: reopenCustomerSession
summary: Reopen customer session
description: |
Reopen a closed [customer
session](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions).
For example, if a session has been completed but still needs to be edited,
you can reopen it with this endpoint.
A reopen session is treated like a standard open session.
When reopening a session:
- The `talon_session_reopened` event is triggered. You can see it in the **Events** view in the Campaign Manager.
- The session state is updated to `open`.
- Any modified budgets and triggered effects are rolled back when the session closes.
- Depending on the [return policy](https://docs.talon.one/docs/product/loyalty-programs/managing-loyalty-programs#return-policy)
in your loyalty programs, points are rolled back in the following ways:
- Pending points are rolled back automatically.
- If **Active points deduction** setting is enabled, any points that were earned and activated when the session closed
are rolled back.
- If **Negative balance** is enabled, the rollback can create a negative points balance.
<details>
<summary><strong>Effects and budgets unimpacted by a session reopening</strong></summary>
<div>
<p>The following effects and budgets remain in the state they were in when the session closed:</p>
<ul>
<li>Add free item effect</li>
<li>Award giveaway</li>
<li>Coupon and referral creation</li>
<li>Coupon reservation</li>
<li>Custom effect</li>
<li>Update attribute value</li>
<li>Update cart item attribute value</li>
</ul>
</div>
</details>
To see an example of a rollback, see the
[Cancelling a session with campaign budgets](https://docs.talon.one/docs/dev/tutorials/rolling-back-effects) tutorial.
> [!note] If your order workflow requires you to create a new session
> instead of reopening a session, use the
> [Update customer session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2)
> endpoint to cancel a closed session and create a new one.
> [!note] To make request processing idempotent for this endpoint, include the `Idempotency-Key` header with an idempotency key in requests. Also:
> - Requests with the `Idempotency-Key` header are logged in the Talon.One access logs.
> - Responses for idempotent requests are stored in the database and expire 24 hours after the request is sent.
> - Idempotency keys are typically UUID keys and should not exceed 255 characters in length.
security:
- api_key_v1: []
tags:
- Customer sessions
parameters:
- name: customerSessionId
in: path
required: true
description: |
The `integration ID` of the customer session. You set this ID when you create a customer session.
You can see existing customer session integration IDs in the Campaign Manager's **Sessions** menu, or via the
[List Application session](https://docs.talon.one/management-api#tag/Customer-data/operation/getApplicationSessions) endpoint.
example: session1
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ReopenSessionResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized - Invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseWithStatus'
/v2/customer_profiles/{integrationId}:
put:
operationId: updateCustomerProfileV2
summary: Update customer profile
description: |
Update or create a [Customer
Profile](https://docs.talon.one/docs/dev/concepts/entities/customer-profiles).
This endpoint triggers the Rule Builder.
You can use this endpoint to:
- Set attributes on the given customer profile. Ensure you create the attributes in the Campaign Manager, first.
- Modify the audience the customer profile is a member of.
> [!note] **Note**
> - Updating a customer profile returns a response with the requested integration state.
> - The [Has joined an audience](https://docs.talon.one/docs/product/rules/conditions/available-conditions#audience-conditions) and
> [Has left an audience](https://docs.talon.one/docs/product/rules/conditions/available-conditions#audience-conditions) conditions
> only trigger through this endpoint.
> - You can use the `responseContent` property to save yourself extra API calls. For example, you can get
> the customer profile details directly without extra requests.
> - We recommend sending requests sequentially.
> See [Managing parallel requests](https://docs.talon.one/docs/dev/getting-started/integration-tutorial#managing-parallel-requests).
> - [Archived campaigns](https://docs.talon.one/docs/product/campaigns/managing-campaigns#archiving-a-campaign) are not considered in rule evaluation when `runRuleEngine` is `true`.
> [!note] To make request processing idempotent for this endpoint, include the `Idempotency-Key` header with an idempotency key in requests. Also:
> - Requests with the `Idempotency-Key` header are logged in the Talon.One access logs.
> - Responses for idempotent requests are stored in the database and expire 24 hours after the request is sent.
> - Idempotency keys are typically UUID keys and should not exceed 255 characters in length.
security:
- api_key_v1: []
tags:
- Customer profiles
parameters:
- in: path
# --- truncated at 32 KB (387 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/talon-one/refs/heads/main/openapi/talon-one-integration-api-openapi.yml