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. ### 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.
Effects and budgets unimpacted by a session reopening

The following effects and budgets remain in the state they were in when the session closed:

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. 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. > - 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`. security: - api_key_v1: [] tags: - Customer profiles parameters: - in: path required: true name: integrationId description: | The integration identifier for this customer profile. Must be: - Unique within the deployment. - Stable for the customer. Do not use an ID that the customer can update themselves. For example, you can use a database ID. Once set, you cannot update this identifier. **Note**: It must be URL-encoded. For example, replace spaces with `%20`. [Learn more](https://www.w3schools.com/tags/ref_urlencode.asp). example: customer1 schema: type: string - name: runRuleEngine in: query description: | Indicates whether to run the Rule Engine. If `true`, the response includes: - The effects generated by the triggered campaigns are returned in the `effects` property. - The created coupons and referral objects. If `false`: - The rules are not executed and the `effects` property is always empty. - The response time improves. - You cannot use `responseContent` in the body. example: false required: false schema: type: boolean default: false - name: dry in: query description: | (Only works when `runRuleEngine=true`) Indicates whether to persist the changes. Changes are ignored when `dry=true`. When set to `true`, you can use the `evaluableCampaignIds` body property to select specific campaigns to run. example: false required: false schema: type: boolean requestBody: content: application/json: schema: $ref: '#/components/schemas/CustomerProfileIntegrationRequestV2' examples: Full request: summary: Full request x-vertical: none value: attributes: Language: english ShippingCountry: DE evaluableCampaignIds: - 10 - 12 responseContent: - triggeredCampaigns - customerProfile audiencesChanges: adds: - 2 - 4 deletes: - 7 eCommerce: x-vertical: ecommerce summary: 'Example: ecommerce' description: Create a new customer with basic information and sign-up date. value: attributes: Name: Chris Taylor Email: chris.taylor@example.com SignupDate: 2026-01-21T15:04:05+07:00 PaymentMethod: Bank transfer QSR & dining: x-vertical: qsr summary: 'Example: QSR & dining' description: | Update a customer profile with dietary preferences and ordering behaviors to personalize offers. value: attributes: Name: Jane Doe Email: jane.doe@example.com DietaryPreferences: vegetarian Financial services: x-vertical: finance summary: 'Example: Financial services' description: | Update a customer profile with account type and card details to enable personalized cashback campaigns. value: attributes: Name: Alex Johnson Email: alex.johnson@example.com AccountType: premium_checking PreferredCard: credit Travel & hospitality: x-vertical: travel summary: 'Example: Travel & hospitality' description: | Update a traveler profile with a churn risk score to identify travelers who haven't booked a flight in several months and offer time-sensitive rewards. value: attributes: Name: Maria Chen Email: maria.chen@example.com ChurnRisk: 0.872 description: body required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CustomerProfileIntegrationResponseV2' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '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 profile at the same time errors: type: array items: {} StatusCode: type: integer example: 409 /v2/customer_profiles: put: operationId: updateCustomerProfilesV2 summary: Update multiple customer profiles description: | Update (or create) up to 1000 [customer profiles](https://docs.talon.one/docs/dev/concepts/entities/customer-profiles) in 1 request. The `integrationId` must be any identifier that remains stable for the customer. Do not use an ID that the customer can update themselves. For example, you can use a database ID. A customer profile [can be linked to one or more sessions](https://docs.talon.one/integration-api#tag/Customer-sessions). > [!note] This endpoint does not trigger the Rule Engine. > To trigger the Rule Engine for customer profile updates, > use the [Update customer profile](#tag/Customer-profiles/operation/updateCustomerProfileV2) endpoint. security: - api_key_v1: [] tags: - Customer profiles parameters: - name: silent in: query description: | Possible values: `yes` or `no`. - `yes`: Increases the performance of the API call by returning a 204 response. - `no`: Returns a 200 response that contains the updated customer profiles. example: yes required: false schema: type: string default: yes requestBody: content: application/json: schema: $ref: '#/components/schemas/MultipleCustomerProfileIntegrationRequest' description: body required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/MultipleCustomerProfileIntegrationResponseV2' '204': description: No content content: application/json: schema: type: string '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '401': description: Unauthorized - Invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' /v2/audiences: post: operationId: createAudienceV2 summary: Create audience description: | Create an audience. The audience can be created directly from scratch or can come from third party platforms. > [!note] Audiences can also be created from scratch via the Campaign Manager. See the [docs](https://docs.talon.one/docs/product/audiences/creating-audiences). To create an audience from an existing audience from a [technology partner](https://docs.talon.one/docs/dev/technology-partners/overview): 1. Set the `integration` property to `mparticle`, `segment` etc., depending on a third-party platform. 1. Set `integrationId` to the ID of this audience in a third-party platform. To create an audience from an existing audience in another platform: 1. Do not use the `integration` property. 1. Set `integrationId` to the ID of this audience in the 3rd-party platform. To create an audience from scratch, only set the `name` property. Once you create your first audience, audience-specific rule conditions are enabled in the Rule Builder. security: - api_key_v1: [] tags: - Audiences requestBody: content: application/json: schema: $ref: '#/components/schemas/NewAudience' examples: Full request: summary: Full request x-vertical: none value: name: Travel audience sandbox: true description: Travel audience 18-27 subscribedApplicationsIds: - 3 - 13 integration: mparticle integrationId: 382370BKDB946 createdIn3rdParty: false lastUpdate: 2022-04-26T11:02:38Z eCommerce: x-vertical: ecommerce summary: 'Example: ecommerce' description: Create an audience for high-value customers. value: name: VIP Customers description: Customers with high lifetime value and frequent purchases sandbox: false createdIn3rdParty: false QSR & dining: x-vertical: qsr summary: 'Example: QSR & dining' description: | Creating an audience for customers who frequently order breakfast items during morning hours. This audience can be targeted with breakfast promotions, early-bird offers, or morning loyalty bonuses. value: name: Breakfast Regulars description: Customers who order breakfast items 3+ times per week during weekday mornings sandbox: false createdIn3rdParty: false Financial services: x-vertical: finance summary: 'Example: Financial services' description: | Create an audience for customers who recently opened an account to target them with welcome bonuses or first-transaction cashback rewards. value: name: New Account Holders description: Customers who opened an account within the last 30 days sandbox: false createdIn3rdParty: false Travel & hospitality: x-vertical: travel summary: 'Example: Travel & hospitality' description: | Create an audience for luxury-oriented travelers so tour operators can automatically trigger personalized offers, such as complimentary spa vouchers, when they initiate a booking. value: name: Luxury Seekers description: Travelers who consistently book premium accommodations and high-end tour packages sandbox: false createdIn3rdParty: false description: body required: true responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/Audience' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '409': description: Conflict. An Audience with this ID already exists for this integration. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' /v2/audiences/{audienceId}: delete: operationId: deleteAudienceV2 summary: Delete audience description: | Delete an audience. > [!warning] This endpoint also removes any associations recorded between a customer profile and this audience. > [!note] Audiences can also be deleted via the Campaign Manager. See the [docs](https://docs.talon.one/docs/product/audiences/managing-audiences#deleting-an-audience). tags: - Audiences security: - api_key_v1: [] parameters: - name: audienceId in: path required: true description: The ID of the audience. example: 10 schema: type: integer responses: '204': description: No Content '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' put: operationId: updateAudienceV2 summary: Update audience name description: | Update the name of the given audience created by a third-party integration. Sending a request to this endpoint does **not** trigger the Rule Engine. To update the audience's members, use the [Update customer profile](#tag/Customer-profiles/operation/updateCustomerProfileV2) endpoint. security: - api_key_v1: [] tags: - Audiences parameters: - name: audienceId in: path required: true description: The ID of the audience. example: 10 schema: type: integer requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateAudience' description: body required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Audience' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' /v2/audiences/{audienceId}/memberships: delete: operationId: deleteAudienceMembershipsV2 summary: Delete audience memberships description: | Remove all members from this audience. security: - api_key_v1: [] tags: - Audiences parameters: - name: audienceId in: path required: true description: The ID of the audience. example: 10 schema: type: integer responses: '204': description: No Content '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' /v2/customer_audiences: post: operationId: updateCustomerProfileAudiences summary: Update multiple customer profiles' audiences description: | Add customer profiles to or remove them from an audience. The endpoint supports 1000 audience actions (`add` or `remove`) per request. > [!note] You can also do this using the > [Update audience](https://docs.talon.one/docs/product/rules/effects/using-effects#updating-an-audience) > effect. security: - api_key_v1: [] tags: - Audiences requestBody: content: application/json: schema: $ref: '#/components/schemas/CustomerProfileAudienceRequest' description: body required: true responses: '204': description: No Content '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' /v2/audience_customers/{audienceId}/attributes: put: operationId: updateAudienceCustomersAttributes summary: Update profile attributes for all customers in audience description: | Update the specified profile attributes to the provided values for all customers in the specified audience. security: - api_key_v1: [] tags: - Audiences parameters: - name: audienceId in: path required: true description: The ID of the audience. example: 10 schema: type: integer requestBody: $ref: '#/components/requestBodies/AttributeQuery' responses: '204': description: No Content '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' /v2/loyalty_programs/{loyaltyProgramId}/cards/{loyaltyCardId}/link_profile: post: operationId: linkLoyaltyCardToProfile summary: Link customer profile to card description: | [Loyalty cards](https://docs.talon.one/docs/product/loyalty-programs/card-based/card-based-overview) allow customers to collect and spend loyalty points within a [card-based loyalty program](https://docs.talon.one/docs/product/loyalty-programs/overview#loyalty-program-types). They are useful to gamify loyalty programs and can be used with or without customer profiles linked to them. Link a customer profile to a given loyalty card for the card to be set as **Registered**. This affects how it can be used. See the [docs](https://docs.talon.one/docs/product/loyalty-programs/card-based/managing-loyalty-cards#linking-customer-profiles-to-a-loyalty-card). > [!note] You can link as many customer profiles to a given loyalty card as the > [**card user limit**](https://docs.talon.one/docs/product/loyalty-programs/card-based/creating-cb-programs) > allows. tags: - Loyalty cards security: - api_key_v1: [] parameters: - name: loyaltyProgramId in: path description: | Identifier of the card-based loyalty program containing the loyalty card. You can get the ID with the [List loyalty programs](https://docs.talon.one/management-api#tag/Loyalty/operation/getLoyaltyPrograms) endpoint. example: 33 required: true schema: type: integer - name: loyaltyCardId in: path description: | Identifier of the loyalty card. You can get the identifier with the [List loyalty cards](https://docs.talon.one/management-api#tag/Loyalty-cards/operation/getLoyaltyCards) endpoint. **Important**: The loyalty card ID requires [URL encoding](https://www.w3schools.com/tags//ref_urlencode.asp) if it contains special characters. For example, you must encode `NewCard2026%` as `NewCard2026%25`. example: summer-loyalty-card-0543 required: true schema: type: string minLength: 4 maxLength: 108 requestBody: content: application/json: schema: $ref: '#/components/schemas/LoyaltyCardRegistration' description: body required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/LoyaltyCard' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' /v2/loyalty_programs/{loyaltyProgramId}/cards/{loyaltyCardId}/unlink_profile: post: operationId: unlinkLoyaltyCardFromProfile summary: Unlink customer profile from a loyalty card description: | Unlink a customer profile from a [registered](https://docs.talon.one/docs/product/loyalty-programs/card-based/managing-loyalty-cards#linking-customer-profiles-to-a-loyalty-card) loyalty card. To get the `integrationId` of a customer profile, you can use the [Update customer session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2) endpoint. tags: - Loyalty cards security: - api_key_v1: [] parameters: - name: loyaltyProgramId in: path description: | The identifier of the card-based loyalty program containing the loyalty card. You can get this ID using the [List loyalty programs](https://docs.talon.one/management-api#tag/Loyalty/operation/getLoyaltyPrograms) endpoint. example: 33 required: true schema: type: integer - name: loyaltyCardId in: path description: | The identifier of the loyalty card. You can get this ID using the [List loyalty cards](https://docs.talon.one/management-api#tag/Loyalty-cards/operation/getLoyaltyCards) endpoint. **Important**: The loyalty card ID requires [URL encoding](https://www.w3schools.com/tags//ref_urlencode.asp) if it contains special characters. For example, you must encode `NewCard2026%` as `NewCard2026%25`. example: summer-loyalty-card-0543 required: true schema: type: string minLength: 4 maxLength: 108 requestBody: content: application/json: schema: $ref: '#/components/schemas/LoyaltyCardRegistration' description: body required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/LoyaltyCard' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' /v1/integration/campaigns: get: operationId: integrationGetAllCampaigns summary: List all running campaigns description: | Retrieve all running campaigns for the specified Application. You can filter the results by providing specific campaign IDs or a range of start and end dates. security: - api_key_v1: [] tags: - Campaigns parameters: - name: pageSize in: query required: false description: The number of items in the response. example: 50 schema: type: integer minimum: 1 maximum: 1000 default: 50 - $ref: '#/components/parameters/skip' - name: campaignIds in: query required: false description: | Filter by one or more campaign IDs, separated by a comma. **Note:** If no campaigns are specified, data for all the campaigns in the Application is returned. example: - '11' - '20' style: form explode: false schema: type: array items: type: string - name: startAfter in: query description: | Filter results to only include campaigns that start on or after the specified timestamp. **Note:** - It must be an RFC3339 timestamp string. - You can include a time component in your string, for example, `T23:59:59` to specify the end of the day. The time zone setting considered is `UTC`. If you do not include a time component, a default time value of `T00:00:00` (midnight) in `UTC` is considered. example: 2024-05-29T15:04:05+07:00 schema: type: string format: date-time - name: startBefore in: query description: | Filter results to only include campaigns that start on or before the specified timestamp. **Note:** - It must be an RFC3339 timestamp string. - You can include a time component in your string, for example, `T23:59:59` to specify the end of the day. The time zone setting considered is `UTC`. If you do not include a time component, a default time value of `T00:00:00` (midnight) in `UTC` is considered. example: 2024-05-29T15:04:05+07:00 schema: type: string format: date-time - name: endAfter in: query description: | Filter results to only include campaigns that end on or after the specified timestamp. **Note:** - It must be an RFC3339 timestamp string. - You can include a time component in your string, for example, `T23:59:59` to specify the end of the day. The time zone setting considered is `UTC`. If you do not include a time component, a default time value of `T00:00:00` (midnight) in `UTC` is considered. example: 2024-05-29T15:04:05+07:00 schema: type: string format: date-time - name: endBefore in: query description: | Filter results to only include campaigns that end on or before the specified timestamp. **Note:** - It must be an RFC3339 timestamp string. - You can include a time component in your string, for example, `T23:59:59` to specify the end of the day. The time zone setting considered is `UTC`. If you do not include a time component, a default time value of `T00:00:00` (midnight) in `UTC` is considered. example: 2024-05-29T15:04:05+07:00 schema: type: string format: date-time - name: storeId in: query required: false description: Filter results to campaigns linked to the specified store ID. example: 23 schema: type: integer - name: audienceId in: query required: false description: Filter results to campaigns linked to the specified audience ID. example: 7 schema: type: integer responses: '200': description: OK content: application/json: schema: type: object required: - hasMore - data properties: hasMore: type: boolean data: type: array items: $ref: '#/components/schemas/IntegrationCampaign' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' /v2/events: post: operationId: trackEventV2 summary: Track event description: | Trigger a custom event. To use this endpoint: 1. [Create a custom event](https://docs.talon.one/docs/dev/concepts/entities/events#creating-a-custom-event) in the Campaign Manager. 1. In a rule, add the **Check for event types** [condition](https://docs.talon.one/docs/dev/concepts/entities/events#use-an-event-in-a-rule) and select the event you created. 1. Trigger the event with this endpoint. You can [list](https://docs.talon.one/docs/product/applications/display-events#list-events) the received events in the **Events** view of the Campaign Manager. For example, you can use this endpoint to trigger an event when a customer shares a link to a product. See our [tutorial](https://docs.talon.one/docs/product/tutorials/referrals/incentivizing-product-link-sharing). > [!note] **Note** > - `profileId` is required even though the schema does not specify it. > - If the customer profile ID is new, a new profile is automatically created but the `customer_profile_created` [built-in event ](https://docs.talon.one/docs/dev/concepts/entities/events) is **not** triggered. > - 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. security: - api_key_v1: [] tags: - Events parameters: - name: silent in: query description: | Possible values: `yes` or `no`. - `yes`: Increases the performance of the API call by returning a 204 response. - `no`: Returns a 200 response that contains the updated customer profiles. example: yes required: false schema: type: string default: yes - 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: forceCompleteEvaluation in: query description: | Forces evaluation for all matching campaigns regardless of the [campaign evaluation mode](https://docs.talon.one/docs/product/applications/managing-campaign-evaluation#setting-campaign-evaluation-mode). Requires `dry=true`. example: false required: false schema: type: boolean default: false requestBody: $ref: '#/components/requestBodies/IntegrationEventV2Request' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/IntegrationEventV2Response' '204': description: No content content: application/json: schema: type: string '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '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 profile at the same time errors: type: array items: {} StatusCode: type: integer example: 409 /v1/referrals: post: operationId: createReferral summary: Create referral code for an advocate description: | Creates a referral code for an advocate. The code will be valid for the referral campaign for which is created, indicated in the `campaignId` parameter, and will be associated with the profile specified in the `advocateProfileIntegrationId` parameter as the advocate's profile. > [!note] Any [referral limits](https://docs.talon.one/docs/product/campaigns/settings/managing-campaign-budgets#referral-limits) > set are ignored when you use this endpoint. security: - api_key_v1: [] tags: - Referrals requestBody: content: application/json: schema: $ref: '#/components/schemas/NewReferral' description: body required: true responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/Referral' '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' /v1/referrals_for_multiple_advocates: post: operationId: createReferralsForMultipleAdvocates summary: Create referral codes for multiple advocates description: | Creates unique referral codes for multiple advocates. The code will be valid for the referral campaign for which it is created, indicated in the `campaignId` parameter, and one referral code will be associated with one advocate using the profile specified in the `advocateProfileIntegrationId` parameter as the advocate's profile. > [!note] Any [referral limits](https://docs.talon.one/docs/product/campaigns/settings/managing-campaign-budgets#referral-limits) > set are ignored when you use this endpoint. security: - api_key_v1: [] tags: - Referrals parameters: - name: silent in: query description: | Possible values: `yes` or `no`. - `yes`: Increases the performance of the API call by returning a 204 response. - `no`: Returns a 200 response that contains the updated customer profiles. example: yes required: false schema: type: string default: yes requestBody: content: application/json: schema: $ref: '#/components/schemas/NewReferralsForMultipleAdvocates' description: body required: true responses: '201': description: Created content: application/json: schema: type: object required: - totalResultSize - data properties: totalResultSize: type: integer example: 1 data: type: array items: $ref: '#/components/schemas/Referral' '204': description: No Content '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '401': description: Unauthorized - Invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' /v1/customer_data/{integrationId}: delete: operationId: deleteCustomerData summary: Delete customer's personal data description: | Delete all attributes on the customer profile and on entities that reference this customer profile. > [!warning] **Warning** > - Customer data is deleted from all Applications in the > [environment](https://docs.talon.one/docs/product/applications/overview#application-environments) > that the API key belongs to. For example, if you use this endpoint with an API key that belongs > to a sandbox Application, customer data will be deleted from all sandbox Applications. > This is because customer data is shared between Applications from the same environment. > - To preserve performance, we recommend avoiding deleting customer data > during peak-traffic hours. security: - api_key_v1: [] tags: - Customer profiles parameters: - name: integrationId in: path required: true description: | The integration ID of the customer profile. You can get the `integrationId` of a profile using: - A customer session integration ID with the [Update customer session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2) endpoint. - The Management API with the [List application's customers](https://docs.talon.one/management-api#tag/Customer-data/operation/getApplicationCustomers) endpoint. example: customer1 schema: type: string responses: '204': description: No Content '401': description: Unauthorized - Invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' /v1/coupon_reservations/{couponValue}: post: operationId: createCouponReservation summary: Create coupon reservation description: | Create a coupon reservation for the specified customer profiles on the specified coupon. You can also create a reservation via the Campaign Manager using the [Create coupon code reservation](https://docs.talon.one/docs/product/rules/effects/using-effects#reserving-a-coupon-code) effect. > [!note] **Note** > - If the **Reservation mandatory** option was selected when creating the > specified coupon, the endpoint creates a **hard** reservation, meaning only users who have > this coupon code reserved can redeem it. > > Otherwise, the endpoint creates a **soft** reservation, meaning the coupon > is associated with the specified customer profiles (they show up when using > the [List customer data](https://docs.talon.one/integration-api#tag/Customer-profiles/operation/getCustomerInventory) > endpoint), but any user can redeem it. > > This can be useful, for example, to display a _coupon wallet_ for customers > when they visit your store. > - If the **Coupon visibility** option was selected when creating the > specified coupon, the coupon code is implicitly soft-reserved for all customers, and the code > will be returned for all customer profiles in the [List customer > data](https://docs.talon.one/integration-api#tag/Customer-profiles/operation/getCustomerInventory) endpoint. > - This endpoint overrides the coupon reservation limit set when > [the coupon is created](https://docs.talon.one/docs/product/campaigns/coupons/creating-coupons). To ensure that coupons cannot be reserved after the reservation limit is reached, use the [Create coupon code reservation](https://docs.talon.one/docs/product/rules/effects/using-effects#reserving-a-coupon-code) effect in the Rule Builder and the [Update customer session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2) endpoint. To delete a reservation, use the [Delete reservation](https://docs.talon.one/integration-api#tag/Coupons/operation/deleteCouponReservation) endpoint. security: - api_key_v1: [] tags: - Coupons parameters: - name: couponValue in: path description: | The code of the coupon. **Important:** The coupon code requires [URL encoding](https://www.w3schools.com/tags//ref_urlencode.asp) if it contains special characters. For example, you must encode `SUMMER25%OFF` as `SUMMER25%25OFF`. example: SUMMER10 required: true schema: type: string requestBody: $ref: '#/components/requestBodies/CouponReservations' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/Coupon' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '401': description: Unauthorized - Invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' delete: operationId: deleteCouponReservation summary: Delete coupon reservations description: | Remove all the coupon reservations from the provided customer profile integration IDs and the provided coupon code. security: - api_key_v1: [] tags: - Coupons parameters: - name: couponValue in: path description: | The code of the coupon. **Important:** The coupon code requires [URL encoding](https://www.w3schools.com/tags//ref_urlencode.asp) if it contains special characters. For example, you must encode `SUMMER25%OFF` as `SUMMER25%25OFF`. example: SUMMER10 required: true schema: type: string requestBody: $ref: '#/components/requestBodies/CouponReservations' responses: '204': description: No Content '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '401': description: Unauthorized - Invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' /v1/coupon_reservations/customerprofiles/{couponValue}: get: operationId: getReservedCustomers summary: List customers that have this coupon reserved description: | Return all customers that have this coupon marked as reserved. This includes hard and soft reservations. security: - api_key_v1: [] tags: - Coupons parameters: - name: couponValue in: path description: | The code of the coupon. **Important:** The coupon code requires [URL encoding](https://www.w3schools.com/tags//ref_urlencode.asp) if it contains special characters. For example, you must encode `SUMMER25%OFF` as `SUMMER25%25OFF`. example: SUMMER10 required: true schema: type: string responses: '200': description: OK content: application/json: schema: type: object required: - totalResultSize - data properties: totalResultSize: type: integer example: 1 data: type: array items: $ref: '#/components/schemas/CustomerProfile' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '401': description: Unauthorized - Invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' /v1/customer_profiles/{integrationId}/inventory: get: operationId: getCustomerInventory summary: List customer data description: | Return the customer inventory regarding entities referencing this customer profile's `integrationId`. Typical entities returned are: customer profile information, referral codes, loyalty points, loyalty cards and reserved coupons. Reserved coupons also include redeemed coupons. security: - api_key_v1: [] tags: - Customer profiles parameters: - name: integrationId in: path required: true description: | The integration ID of the customer profile. You can get the `integrationId` of a profile using: - A customer session integration ID with the [Update customer session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2) endpoint. - The Management API with the [List application's customers](https://docs.talon.one/management-api#tag/Customer-data/operation/getApplicationCustomers) endpoint. example: customer1 schema: type: string - name: profile in: query required: false description: Set to `true` to include customer profile information in the response. example: false schema: type: boolean - name: referrals in: query required: false description: Set to `true` to include referral information in the response. example: false schema: type: boolean - name: coupons in: query required: false description: Set to `true` to include coupon information in the response. example: false schema: type: boolean - name: loyalty in: query required: false description: Set to `true` to include loyalty information in the response. example: false schema: type: boolean - name: giveaways in: query required: false description: Set to `true` to include giveaways information in the response. example: false schema: type: boolean - name: achievements in: query required: false description: Set to `true` to include achievement information in the response. example: false schema: type: boolean responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CustomerInventory' '401': description: Unauthorized - Invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' /v1/customer_profiles/{integrationId}/achievements: get: operationId: getCustomerAchievements summary: List customer's available achievements description: | Retrieve all the achievements available to a given customer and their progress in them. security: - api_key_v1: [] tags: - Achievements parameters: - in: path required: true name: integrationId description: | The integration identifier for this customer profile. Must be: - Unique within the deployment. - Stable for the customer. Do not use an ID that the customer can update themselves. For example, you can use a database ID. Once set, you cannot update this identifier. example: customer1 schema: type: string - name: campaignIds in: query required: false description: | Filter by one or more Campaign IDs, separated by a comma. **Note:** If no campaigns are specified, data for all the campaigns in the Application is returned. example: - '11' - '20' style: form explode: false schema: type: array items: type: string - name: achievementIds in: query required: false description: | Filter by one or more Achievement IDs, separated by a comma. **Note:** If no achievements are specified, data for all the achievements in the Application is returned. example: - '11' - '20' style: form explode: false schema: type: array items: type: string - name: achievementStatus in: query required: false description: | Filter by status of the achievement. **Note:** If the achievement status is not specified, only data for all active achievements in the Application is returned. style: form explode: false schema: type: array items: type: string enum: - active - scheduled example: - active - scheduled - name: currentProgressStatus in: query required: false description: | Filter by customer progress status in the achievement. style: form explode: false schema: type: array items: type: string enum: - inprogress - completed - not_started example: - inprogress - completed - $ref: '#/components/parameters/pageSize' - $ref: '#/components/parameters/skip' responses: '200': description: OK content: application/json: schema: type: object required: - totalResultSize - data properties: totalResultSize: type: integer example: 1 data: type: array items: $ref: '#/components/schemas/AchievementStatusEntry' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' /v1/customer_profiles/{integrationId}/achievements/{achievementId}: get: operationId: getCustomerAchievementHistory summary: List customer's achievement history description: | Retrieve all progress history of a given customer in the given achievement. security: - api_key_v1: [] tags: - Achievements parameters: - in: path required: true name: integrationId description: | The integration identifier for this customer profile. Must be: - Unique within the deployment. - Stable for the customer. Do not use an ID that the customer can update themselves. For example, you can use a database ID. Once set, you cannot update this identifier. example: customer1 schema: type: string - in: path required: true name: achievementId description: | The achievement identifier. example: 321 schema: type: integer - name: progressStatus in: query required: false description: | Filter by customer progress status in the achievement. style: form explode: false schema: type: array items: type: string enum: - inprogress - completed - expired example: - inprogress - completed - name: startDate description: Timestamp that filters the results to only contain achievements created on or after the start date. in: query example: 2024-05-29T15:04:05+07:00 schema: type: string format: date-time - name: endDate description: Timestamp that filters the results to only contain achievements created before or on the end date. in: query example: 2024-05-29T15:04:05+07:00 schema: type: string format: date-time - $ref: '#/components/parameters/pageSize' - $ref: '#/components/parameters/skip' responses: '200': description: OK content: application/json: schema: type: object required: - totalResultSize - data properties: totalResultSize: type: integer example: 1 data: type: array items: $ref: '#/components/schemas/AchievementProgress' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' /v1/loyalty_programs/{loyaltyProgramId}/cards/{loyaltyCardId}/balances: get: operationId: getLoyaltyCardBalances summary: Get card's point balances description: | Retrieve loyalty balances for the given loyalty card in the specified loyalty program with filtering options applied. If no filtering options are applied, all loyalty balances for the given loyalty card are returned. security: - api_key_v1: [] tags: - Loyalty cards parameters: - name: loyaltyProgramId in: path description: | Identifier of the card-based loyalty program containing the loyalty card. You can get the ID with the [List loyalty programs](https://docs.talon.one/management-api#tag/Loyalty/operation/getLoyaltyPrograms) endpoint. example: 33 required: true schema: type: integer - name: loyaltyCardId in: path description: | Identifier of the loyalty card. You can get the identifier with the [List loyalty cards](https://docs.talon.one/management-api#tag/Loyalty-cards/operation/getLoyaltyCards) endpoint. **Important**: The loyalty card ID requires [URL encoding](https://www.w3schools.com/tags//ref_urlencode.asp) if it contains special characters. For example, you must encode `NewCard2026%` as `NewCard2026%25`. example: summer-loyalty-card-0543 required: true schema: type: string minLength: 4 maxLength: 108 - name: endDate in: query required: false description: | Used to return expired, active, and pending loyalty balances before this timestamp. You can enter any past, present, or future timestamp value. > [!note] **Note** > - This must be an RFC3339 timestamp string. > - You can include a time component in your string, for example, `T23:59:59` to specify the end of the day. The time zone setting > considered is `UTC`. If you do not include a time component, a default time value of `T00:00:00` (midnight) in `UTC` is considered. example: 2024-05-29T15:04:05+07:00 schema: type: string format: date-time - name: subledgerId in: query required: false description: Filter results by one or more subledger IDs. Must be exact match. example: - subledger1 - subledger2 style: form explode: true schema: type: array items: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/LoyaltyCardBalances' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' /v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}/balances: get: operationId: getLoyaltyBalances summary: Get customer's loyalty balances description: | Retrieve loyalty ledger balances for the given Integration ID in the specified loyalty program. You can filter balances by date and subledger ID, and include tier-related information in the response. > [!note] If no filtering options are applied, you retrieve all loyalty > balances on the current date for the given integration ID. Loyalty balances are calculated when Talon.One receives your request using the points stored in our database, so retrieving a large number of balances at once can impact performance. For more information, see: - [Managing card-based loyalty program data](https://docs.talon.one/docs/product/loyalty-programs/card-based/managing-loyalty-cards) - [Managing profile-based loyalty program data](https://docs.talon.one/docs/product/loyalty-programs/profile-based/managing-pb-lp-data) security: - api_key_v1: [] tags: - Loyalty parameters: - name: loyaltyProgramId in: path required: true description: | Identifier of the profile-based loyalty program. You can get the ID with the [List loyalty programs](https://docs.talon.one/management-api#tag/Loyalty/operation/getLoyaltyPrograms) endpoint. example: 33 schema: type: integer - in: path required: true name: integrationId description: | The integration identifier for this customer profile. Must be: - Unique within the deployment. - Stable for the customer. Do not use an ID that the customer can update themselves. For example, you can use a database ID. Once set, you cannot update this identifier. example: customer1 schema: type: string - name: endDate in: query required: false description: | Used to return expired, active, and pending loyalty balances before this timestamp. You can enter any past, present, or future timestamp value. > [!note] **Note** > - This must be an RFC3339 timestamp string. > - You can include a time component in your string, for example, `T23:59:59` to specify the end of the day. The time zone setting > considered is `UTC`. If you do not include a time component, a default time value of `T00:00:00` (midnight) in `UTC` is considered. example: 2024-05-29T15:04:05+07:00 schema: type: string format: date-time - name: subledgerId in: query required: false description: The ID of the subledger by which we filter the data. example: subledger1 schema: type: string - name: includeTiers in: query required: false description: | Indicates whether tier information is included in the response. When set to `true`, the response includes information about the current tier and the number of points required to move to next tier. example: false schema: type: boolean default: false - name: includeProjectedTier in: query required: false description: | Indicates whether the customer's projected tier information is included in the response. When set to `true`, the response includes information about the customer's active points and the name of the projected tier. **Note** We recommend filtering by `subledgerId` for better performance. example: false schema: type: boolean default: false responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/LoyaltyBalancesWithTiers' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' /v1/loyalty_programs/{loyaltyProgramId}/cards/{loyaltyCardId}/transactions: get: operationId: getLoyaltyCardTransactions summary: List card's transactions description: | Retrieve loyalty transaction logs for the given loyalty card in the specified loyalty program with filtering options applied. If no filtering options are applied, the last 50 loyalty transactions for the given loyalty card are returned. security: - api_key_v1: [] tags: - Loyalty cards parameters: - name: loyaltyProgramId in: path description: | Identifier of the card-based loyalty program containing the loyalty card. You can get the ID with the [List loyalty programs](https://docs.talon.one/management-api#tag/Loyalty/operation/getLoyaltyPrograms) endpoint. example: 33 required: true schema: type: integer - name: loyaltyCardId in: path description: | Identifier of the loyalty card. You can get the identifier with the [List loyalty cards](https://docs.talon.one/management-api#tag/Loyalty-cards/operation/getLoyaltyCards) endpoint. **Important**: The loyalty card ID requires [URL encoding](https://www.w3schools.com/tags//ref_urlencode.asp) if it contains special characters. For example, you must encode `NewCard2026%` as `NewCard2026%25`. example: summer-loyalty-card-0543 required: true schema: type: string minLength: 4 maxLength: 108 - name: subledgerId in: query required: false description: Filter results by one or more subledger IDs. Must be exact match. example: - subledger1 - subledger2 style: form explode: true schema: type: array items: type: string - name: loyaltyTransactionType in: query required: false description: | Filter results by loyalty transaction type: - `manual`: Loyalty transaction that was done manually. - `session`: Loyalty transaction that resulted from a customer session. - `import`: Loyalty transaction that was imported from a CSV file. example: manual schema: type: string enum: - manual - session - import - name: startDate in: query required: false description: | Date and time from which results are returned. Results are filtered by transaction creation date. > [!note] **Note** > - This must be an RFC3339 timestamp string. > - You can include a time component in your string, for example, `T23:59:59` to specify the end of the day. The time zone setting > considered is `UTC`. If you do not include a time component, a default time value of `T00:00:00` (midnight) in `UTC` is considered. example: 2024-05-29T15:04:05+07:00 schema: type: string format: date-time - name: endDate in: query required: false description: | Date and time by which results are returned. Results are filtered by transaction creation date. > [!note] **Note** > - This must be an RFC3339 timestamp string. > - You can include a time component in your string, for example, `T23:59:59` to specify the end of the day. The time zone setting > considered is `UTC`. If you do not include a time component, a default time value of `T00:00:00` (midnight) in `UTC` is considered. example: 2024-05-29T15:04:05+07:00 schema: type: string format: date-time - name: customerSessionIDs in: query required: false description: | Filter the results by a list of customer session IDs. To include multiple IDs, repeat the parameter for each one, for example, `?customerSessionIDs=id1&customerSessionIDs=id2`. The response contains only data associated with the specified sessions. example: - session_integration_id_1 - session_integration_id_1 schema: type: array items: type: string - name: transactionUUIDs in: query required: false description: | Filter the results by a list of transaction UUIDs. To include multiple IDs, repeat the parameter for each one, for example, `?transactionUUIDs=uuid1&transactionUUIDs=uuid2`. The response contains only data associated with the specified transactions. example: - dc608634-0100-40d9-b371-e964476bbe0f - 9e829590-05cf-407b-b4c0-5f28468a81e1 schema: type: array items: type: string - name: pageSize in: query required: false description: The number of items in the response. example: 50 schema: type: integer minimum: 1 maximum: 1000 default: 50 - $ref: '#/components/parameters/skip' - name: awaitsActivation in: query required: false description: | If `true`: Filters results to include only point transactions that have action-based activation and have not expired. If `false`: Returns a `400` response. example: true schema: type: boolean responses: '200': description: OK content: application/json: schema: type: object required: - hasMore - data properties: hasMore: type: boolean example: true data: type: array items: $ref: '#/components/schemas/CardLedgerTransactionLogEntryIntegrationAPI' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' /v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}/transactions: get: operationId: getLoyaltyProgramProfileTransactions summary: List customer's loyalty transactions description: | Retrieve paginated results of loyalty transaction logs for the given Integration ID in the specified loyalty program. You can filter transactions by date. If no filters are applied, the last 50 loyalty transactions for the given integration ID are returned. > [!note] To retrieve all loyalty program transaction logs in a given > loyalty program, use the [List loyalty program transactions](https://docs.talon.one/management-api#tag/Loyalty/operation/getLoyaltyProgramTransactions) > endpoint. security: - api_key_v1: [] tags: - Loyalty parameters: - name: loyaltyProgramId in: path required: true description: | Identifier of the profile-based loyalty program. You can get the ID with the [List loyalty programs](https://docs.talon.one/management-api#tag/Loyalty/operation/getLoyaltyPrograms) endpoint. example: 33 schema: type: integer - in: path required: true name: integrationId description: | The integration identifier for this customer profile. Must be: - Unique within the deployment. - Stable for the customer. Do not use an ID that the customer can update themselves. For example, you can use a database ID. Once set, you cannot update this identifier. example: customer1 schema: type: string - name: customerSessionIDs in: query required: false description: | Filter the results by a list of customer session IDs. To include multiple IDs, repeat the parameter for each one, for example, `?customerSessionIDs=id1&customerSessionIDs=id2`. The response contains only data associated with the specified sessions. example: - session_integration_id_1 - session_integration_id_1 schema: type: array items: type: string - name: transactionUUIDs in: query required: false description: | Filter the results by a list of transaction UUIDs. To include multiple IDs, repeat the parameter for each one, for example, `?transactionUUIDs=uuid1&transactionUUIDs=uuid2`. The response contains only data associated with the specified transactions. example: - dc608634-0100-40d9-b371-e964476bbe0f - 9e829590-05cf-407b-b4c0-5f28468a81e1 schema: type: array items: type: string - name: subledgerId in: query required: false description: The ID of the subledger by which we filter the data. example: subledger1 schema: type: string - name: loyaltyTransactionType in: query required: false description: | Filter results by loyalty transaction type: - `manual`: Loyalty transaction that was done manually. - `session`: Loyalty transaction that resulted from a customer session. - `import`: Loyalty transaction that was imported from a CSV file. example: manual schema: type: string enum: - manual - session - import - name: startDate in: query required: false description: | Date and time from which results are returned. Results are filtered by transaction creation date. > [!note] **Note** > - This must be an RFC3339 timestamp string. > - You can include a time component in your string, for example, `T23:59:59` to specify the end of the day. The time zone setting > considered is `UTC`. If you do not include a time component, a default time value of `T00:00:00` (midnight) in `UTC` is considered. example: 2024-05-29T15:04:05+07:00 schema: type: string format: date-time - name: endDate in: query required: false description: | Date and time by which results are returned. Results are filtered by transaction creation date. > [!note] **Note** > - This must be an RFC3339 timestamp string. > - You can include a time component in your string, for example, `T23:59:59` to specify the end of the day. The time zone setting > considered is `UTC`. If you do not include a time component, a default time value of `T00:00:00` (midnight) in `UTC` is considered. example: 2024-05-29T15:04:05+07:00 schema: type: string format: date-time - name: pageSize in: query required: false description: The number of items in the response. example: 50 schema: type: integer minimum: 1 maximum: 1000 default: 50 - $ref: '#/components/parameters/skip' - name: awaitsActivation in: query required: false description: | If `true`: Filters results to include only point transactions that have action-based activation and have not expired. If `false`: Returns a `400` response. example: true schema: type: boolean responses: '200': description: OK content: application/json: schema: type: object required: - hasMore - data properties: hasMore: type: boolean example: true data: type: array items: $ref: '#/components/schemas/LedgerTransactionLogEntryIntegrationAPI' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' /v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}/delete_transactions: post: operationId: deleteLoyaltyTransactionsFromLedgers summary: Delete customer's transactions from loyalty ledgers description: | Delete a customer's transactions in all loyalty ledgers or a specified ledger. > [!note] To retrieve loyalty transaction logs for a specific customer in a given loyalty program, > use the [List customer's loyalty transactions](https://docs.talon.one/integration-api#tag/Loyalty/operation/getLoyaltyProgramProfileTransactions) > endpoint. security: - api_key_v1: [] tags: - Loyalty parameters: - name: loyaltyProgramId in: path required: true description: | Identifier of the profile-based loyalty program. You can get the ID with the [List loyalty programs](https://docs.talon.one/management-api#tag/Loyalty/operation/getLoyaltyPrograms) endpoint. example: 33 schema: type: integer - name: integrationId in: path required: true description: | The integration ID of the customer profile. You can get the `integrationId` of a profile using: - A customer session integration ID with the [Update customer session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2) endpoint. - The Management API with the [List application's customers](https://docs.talon.one/management-api#tag/Customer-data/operation/getApplicationCustomers) endpoint. example: customer1 schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DeleteLoyaltyTransactionsRequest' responses: '204': description: No Content '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' /v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}/join: post: operationId: joinLoyaltyProgram summary: Join customer profile to loyalty program description: | Join a customer profile to the specified loyalty program. If the customer profile does not exist, it will be created first using the provided `integrationId`, then joined to the loyalty program. > [!note] This endpoint only works with profile-based loyalty programs. **Behavior**: - If the loyalty program does not exist, the request fails. - If the customer profile is already joined to the loyalty program, the request fails. - If the customer profile does not exist, it is created and then joined to the loyalty program. security: - api_key_v1: [] tags: - Loyalty parameters: - name: loyaltyProgramId in: path required: true description: | Identifier of the profile-based loyalty program. You can get the ID with the [List loyalty programs](https://docs.talon.one/management-api#tag/Loyalty/operation/getLoyaltyPrograms) endpoint. example: 33 schema: type: integer - name: integrationId in: path required: true description: | The integration ID of the customer profile. You can get the `integrationId` of a profile using: - A customer session integration ID with the [Update customer session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2) endpoint. - The Management API with the [List application's customers](https://docs.talon.one/management-api#tag/Customer-data/operation/getApplicationCustomers) endpoint. example: customer1 schema: type: string responses: '200': description: OK '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' /v1/loyalty_programs/{loyaltyProgramId}/cards/{loyaltyCardId}/points: get: operationId: getLoyaltyCardPoints summary: List card's unused loyalty points description: | Get paginated results of loyalty points for a given loyalty card identifier in a card-based loyalty program. This endpoint returns only the balances of unused points on a loyalty card. You can filter points by status: - `active`: Points ready to be redeemed. - `pending`: Points with a start date in the future. - `expired`: Points with an expiration date in the past. security: - api_key_v1: [] tags: - Loyalty cards parameters: - name: loyaltyProgramId in: path description: | Identifier of the card-based loyalty program containing the loyalty card. You can get the ID with the [List loyalty programs](https://docs.talon.one/management-api#tag/Loyalty/operation/getLoyaltyPrograms) endpoint. example: 33 required: true schema: type: integer - name: loyaltyCardId in: path description: | Identifier of the loyalty card. You can get the identifier with the [List loyalty cards](https://docs.talon.one/management-api#tag/Loyalty-cards/operation/getLoyaltyCards) endpoint. **Important**: The loyalty card ID requires [URL encoding](https://www.w3schools.com/tags//ref_urlencode.asp) if it contains special characters. For example, you must encode `NewCard2026%` as `NewCard2026%25`. example: summer-loyalty-card-0543 required: true schema: type: string minLength: 4 maxLength: 108 - name: status in: query required: false description: Filter points based on their status. example: active schema: type: string enum: - active - pending - expired default: active - name: subledgerId in: query required: false description: Filter results by one or more subledger IDs. Must be exact match. example: - subledger1 - subledger2 style: form explode: true schema: type: array items: type: string - name: customerSessionIDs in: query required: false description: | Filter the results by a list of customer session IDs. To include multiple IDs, repeat the parameter for each one, for example, `?customerSessionIDs=id1&customerSessionIDs=id2`. The response contains only data associated with the specified sessions. example: - session_integration_id_1 - session_integration_id_1 schema: type: array items: type: string - name: transactionUUIDs in: query required: false description: | Filter the results by a list of transaction UUIDs. To include multiple IDs, repeat the parameter for each one, for example, `?transactionUUIDs=uuid1&transactionUUIDs=uuid2`. The response contains only data associated with the specified transactions. example: - dc608634-0100-40d9-b371-e964476bbe0f - 9e829590-05cf-407b-b4c0-5f28468a81e1 schema: type: array items: type: string - name: pageSize in: query required: false description: The number of items in the response. example: 50 schema: type: integer minimum: 1 maximum: 1000 default: 50 - $ref: '#/components/parameters/skip' - name: sort in: query required: false description: | The field by which results should be sorted. You can enter one of the following values: - `startDate`: Sorts the results by the start date of the points. - `expiryDate`: Sorts the results by the expiry date of the points. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with `-`. **Note:** You can only sort by one field at a time. example: startDate schema: type: string enum: - startDate - expiryDate responses: '200': description: OK content: application/json: schema: type: object required: - hasMore - data properties: hasMore: type: boolean example: true data: type: array items: $ref: '#/components/schemas/CardLedgerPointsEntryIntegrationAPI' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' /v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}/points: get: operationId: getLoyaltyProgramProfilePoints summary: List customer's unused loyalty points description: | Get paginated results of loyalty points for a given Integration ID in the specified profile-based loyalty program. This endpoint returns only the balances of unused points linked to a customer profile. You can filter points by status: - `active`: Points ready to be redeemed. - `pending`: Points with a start date in the future. - `expired`: Points with an expiration date in the past. security: - api_key_v1: [] tags: - Loyalty parameters: - name: loyaltyProgramId in: path required: true description: | Identifier of the profile-based loyalty program. You can get the ID with the [List loyalty programs](https://docs.talon.one/management-api#tag/Loyalty/operation/getLoyaltyPrograms) endpoint. example: 33 schema: type: integer - in: path required: true name: integrationId description: | The integration identifier for this customer profile. Must be: - Unique within the deployment. - Stable for the customer. Do not use an ID that the customer can update themselves. For example, you can use a database ID. Once set, you cannot update this identifier. example: customer1 schema: type: string - name: status in: query required: false description: Filter points based on their status. example: active schema: type: string enum: - active - pending - expired default: active - name: subledgerId in: query required: false description: | Filter the results by a list of subledger IDs. To include multiple IDs, repeat the parameter for each one, for example, `?subledgerId=id1&subledgerId=id2`. The response contains only data associated with the specified subledgers. example: - subledger1 - subledger2 schema: type: array items: type: string - name: customerSessionIDs in: query required: false description: | Filter the results by a list of customer session IDs. To include multiple IDs, repeat the parameter for each one, for example, `?customerSessionIDs=id1&customerSessionIDs=id2`. The response contains only data associated with the specified sessions. example: - session_integration_id_1 - session_integration_id_1 schema: type: array items: type: string - name: transactionUUIDs in: query required: false description: | Filter the results by a list of transaction UUIDs. To include multiple IDs, repeat the parameter for each one, for example, `?transactionUUIDs=uuid1&transactionUUIDs=uuid2`. The response contains only data associated with the specified transactions. example: - dc608634-0100-40d9-b371-e964476bbe0f - 9e829590-05cf-407b-b4c0-5f28468a81e1 schema: type: array items: type: string - name: pageSize in: query required: false description: The number of items in the response. example: 50 schema: type: integer minimum: 1 maximum: 1000 default: 50 - $ref: '#/components/parameters/skip' - name: sort in: query required: false description: | The field by which results should be sorted. You can enter one of the following values: - `startDate`: Sorts the results by the start date of the points. - `expiryDate`: Sorts the results by the expiry date of the points. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with `-`. **Note:** You can only sort by one field at a time. example: startDate schema: type: string enum: - startDate - expiryDate responses: '200': description: OK content: application/json: schema: type: object required: - hasMore - data properties: hasMore: type: boolean example: true data: type: array items: $ref: '#/components/schemas/LedgerPointsEntryIntegrationAPI' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' /v1/loyalty_programs/{loyaltyProgramId}/activate_points: post: operationId: activateLoyaltyPoints summary: Activate loyalty points description: | Activate points when a defined action occurs. You can activate pending points using one of the following parameters: - `sessionId`: Activates all points earned in the specified session. - `transactionUUIDs`: Activates points earned in the transactions specified by the given UUIDs. tags: - Loyalty security: - api_key_v1: [] parameters: - name: loyaltyProgramId in: path description: | The identifier for the loyalty program. You can get the ID with the [List loyalty programs](https://docs.talon.one/management-api#tag/Loyalty/operation/getLoyaltyPrograms) endpoint. example: 33 required: true schema: type: integer requestBody: $ref: '#/components/requestBodies/ActivateLoyaltyPoints' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ActivateLoyaltyPointsResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' /v1/loyalty_programs/{loyaltyProgramId}/cards: post: operationId: generateLoyaltyCard summary: Generate loyalty card description: | Generate a loyalty card in a specified [card-based loyalty program](https://docs.talon.one/docs/product/loyalty-programs/card-based/card-based-overview). To link the card to one or more customer profiles, use the `customerProfileIds` parameter in the request body. > [!note] **Note** > - The number of customer profiles linked to the loyalty card cannot exceed > the loyalty program's `usersPerCardLimit`. To find the program's limit, use > the [Get loyalty program](https://docs.talon.one/management-api#tag/Loyalty/operation/getLoyaltyProgram) > endpoint. > - If the loyalty program has a defined code format, it will be used for the > loyalty card identifier. security: - api_key_v1: [] tags: - Loyalty cards parameters: - name: loyaltyProgramId in: path description: | Identifier of the card-based loyalty program containing the loyalty card. You can get the ID with the [List loyalty programs](https://docs.talon.one/management-api#tag/Loyalty/operation/getLoyaltyPrograms) endpoint. example: 33 required: true schema: type: integer requestBody: content: application/json: schema: $ref: '#/components/schemas/GenerateLoyaltyCard' description: body required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/LoyaltyCard' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' /v1/best_prior_price: post: operationId: bestPriorPrice summary: Fetch best prior price x-scalar-stability: experimental description: | Returns the best prior price based on historical pricing data for the specified SKUs within a defined timeframe. tags: - Catalogs requestBody: $ref: '#/components/requestBodies/BestPriorPrice' responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/BestPriorPriceResponse' /v1/catalogs/{catalogId}/sync: put: operationId: syncCatalog summary: Sync cart item catalog description: | Perform the following actions for a given cart item catalog: - Add an item to the catalog. - Add multiple items to the catalog. - Update the attributes of an item in the catalog. - Update the attributes of multiple items in the catalog. - Remove an item from the catalog. - Remove multiple items from the catalog. You can either add, update, or delete up to 1000 cart items in a single request. Each item synced to a catalog must have a unique `SKU`. > [!important] You can perform only one type of action in a single sync request. Syncing items with duplicate `SKU` values in a single request returns an error message with a `400` status code. For more information, read [managing cart item catalogs](https://docs.talon.one/docs/product/account/dev-tools/managing-cart-item-catalogs). ### Filtering cart items Use [cart item attributes](https://docs.talon.one/docs/product/account/dev-tools/managing-attributes) to filter items and select the ones you want to edit or delete when editing or deleting more than one item at a time. The `filters` array contains an object with the following properties: - `attr`: A [cart item attribute](https://docs.talon.one/docs/product/account/dev-tools/managing-attributes) connected to the catalog. It is applied to all items in the catalog. - `op`: The filtering operator indicating the relationship between the value of each cart item in the catalog and the value of the `value` property for the attribute selected in `attr`. The value of `op` can be one of the following: - `EQ`: Equal to `value` - `LT`: Less than `value` - `LE`: Less than or equal to `value` - `GT`: Greater than `value` - `GE`: Greater than or equal to `value` - `IN`: One of the comma-separated values that `value` is set to. **Note:** `GE`, `LE`, `GT`, `LT` are for numeric values only. - `value`: The value of the attribute selected in `attr`. ### Payload examples Synchronization actions are sent as `PUT` requests. See the structure for each action:
Adding an item to the catalog
```json { "actions": [ { "payload": { "attributes": { "color": "Navy blue", "type": "shoes" }, "replaceIfExists": true, "sku": "SKU1241028", "price": 100, "product": { "name": "sneakers" } }, "type": "ADD" } ] } ```
Adding multiple items to the catalog
```json { "actions": [ { "payload": { "attributes": { "color": "Navy blue", "type": "shoes" }, "replaceIfExists": true, "sku": "SKU1241027", "price": 100, "product": { "name": "sneakers" } }, "type": "ADD" }, { "payload": { "attributes": { "color": "Navy blue", "type": "shoes" }, "replaceIfExists": true, "sku": "SKU1241028", "price": 100, "product": { "name": "sneakers" } }, "type": "ADD" } ] } ```
Updating the attributes of an item in the catalog
```json { "actions": [ { "payload": { "attributes": { "age": 11, "origin": "germany" }, "createIfNotExists": false, "sku": "SKU1241028", "product": { "name": "sneakers" } }, "type": "PATCH" } ] } ```
Updating the attributes of multiple items in the catalog
```json { "actions": [ { "payload": { "attributes": { "color": "red" }, "filters": [ { "attr": "color", "op": "EQ", "value": "blue" } ] }, "type": "PATCH_MANY" } ] } ```
Removing an item from the catalog
```json { "actions": [ { "payload": { "sku": "SKU1241028" }, "type": "REMOVE" } ] } ```
Removing multiple items from the catalog
```json { "actions": [ { "payload": { "filters": [ { "attr": "color", "op": "EQ", "value": "blue" } ] }, "type": "REMOVE_MANY" } ] } ```
Removing shoes of sizes above 45 from the catalog

Let's imagine that we have a shoe store and we have decided to stop selling shoes larger than size 45. We can remove from the catalog all the shoes of sizes above 45 with a single action:

```json { "actions": [ { "payload": { "filters": [ { "attr": "size", "op": "GT", "value": "45" } ] }, "type": "REMOVE_MANY" } ] } ```
tags: - Catalogs security: - api_key_v1: [] parameters: - name: catalogId description: The ID of the catalog. You can find the ID in the Campaign Manager in **Account** > **Tools** > **Cart item catalogs**. example: 30 in: path required: true schema: type: integer requestBody: content: application/json: schema: $ref: '#/components/schemas/CatalogSyncRequest' description: body required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Catalog' '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' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' /v3/events: post: operationId: trackEventV3 summary: Track advanced event description: | Trigger an advanced event. Advanced events are idempotent, uniquely identifiable events. They can also reference a previously closed session to add more context for rule evaluation. To use this endpoint: 1. [Create a custom event](https://docs.talon.one/docs/dev/concepts/entities/events#creating-a-custom-event) in the Campaign Manager. 1. In a rule, add the **Check for event types** [condition](https://docs.talon.one/docs/dev/concepts/entities/events#use-an-event-in-a-rule) and select the event you created. 1. Trigger the event with this endpoint. You can [list](https://docs.talon.one/docs/product/applications/display-events#list-events) the received events in the **Events** view of the Campaign Manager. For example, you can use this endpoint to trigger an event when a customer shares a link to a product. See our [tutorial](https://docs.talon.one/docs/product/tutorials/referrals/incentivizing-product-link-sharing). > [!note] **Note** > - If the customer profile does not exist, it will be created. However, the `customer_profile_created` [built-in event](https://docs.talon.one/docs/dev/concepts/entities/events) is **not** triggered. > - 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. security: - api_key_v1: [] tags: - Events parameters: - name: silent in: query description: | Possible values: `yes` or `no`. - `yes`: Increases the performance of the API call by returning a 204 response. - `no`: Returns a 200 response that contains the updated customer profiles. example: yes required: false schema: type: string default: yes - 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: forceCompleteEvaluation in: query description: | Forces evaluation for all matching campaigns regardless of the [campaign evaluation mode](https://docs.talon.one/docs/product/applications/managing-campaign-evaluation#setting-campaign-evaluation-mode). Requires `dry=true`. example: false required: false schema: type: boolean default: false requestBody: $ref: '#/components/requestBodies/IntegrationEventV3Request' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/IntegrationEventV3Response' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '401': description: Unauthorized - Invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '409': description: An advanced event already exists, 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 profile at the same time errors: type: array items: {} StatusCode: type: integer example: 409 /v3/events/{integrationId}: get: operationId: getEventV3 summary: Get advanced event description: | Retrieve an advanced event by its identifier. security: - api_key_v1: [] tags: - Events parameters: - name: integrationId in: path description: The unique ID of the advanced event. required: true example: pe_12345 schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/EventV3' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' webhooks: {} components: securitySchemes: api_key_v1: type: apiKey name: Authorization in: header description: | To authenticate with the Integration API, generate an API key in the Campaign Manager and prefix it with `ApiKey-v1`. To generate an API key: 1. Sign in to the Campaign Manager and open the Application of your choice, or create one. 1. Click **Settings** > **Integration API Keys**. 1. Click **Create API Key** and give it a name and an expiration date, then click **Create API Key**. **Tip**: Avoid choosing expiration dates that fall at the end of the year or during other high-traffic periods. You can now use the API key in the HTTP header, prefixing it with `ApiKey-v1`: ``` Authorization: ApiKey-v1 dbc644d33aa74d582bd9479c59e16f970fe13bf3 ``` Or use it inside [an SDK](https://docs.talon.one/docs/dev/sdks/overview), for example, with the JAVA SDK: ``` iApi.getApiClient().setApiKeyPrefix("ApiKey-v1"); iApi.getApiClient().setApiKey("dbc644d33aa74d582bd9479c59e16f970fe13bf3"); ``` schemas: Entity: type: object required: - id - created properties: id: type: integer description: The internal ID of this entity. example: 6 created: type: string format: date-time description: The time this entity was created. example: 2020-06-10T09:05:27.993483Z IntegrationEntity: type: object required: - integrationId - created properties: integrationId: type: string format: string example: URNGV8294NV maxLength: 1000 description: The integration ID set by your integration layer. created: type: string format: date-time description: The time this entity was created. example: 2020-02-07T08:15:22Z ApplicationEntity: type: object required: - applicationId properties: applicationId: type: integer description: The ID of the Application that owns this entity. example: 322 IntegrationProfileEntity: type: object properties: profileId: type: string description: | ID of the customer profile set by your integration layer. **Note:** If the customer does not yet have a known `profileId`, we recommend you use a guest `profileId`. example: URNGV8294NV IntegrationStoreEntity: type: object properties: storeIntegrationId: type: string minLength: 1 maxLength: 1000 description: The integration ID of the store. You choose this ID when you create a store. example: STORE-001 EvaluableCampaignIds: type: object properties: evaluableCampaignIds: type: array items: type: integer description: | When using the `dry` query parameter, use this property to list the campaign to be evaluated by the Rule Engine. These campaigns will be evaluated, even if they are disabled, allowing you to test specific campaigns before activating them. title: Campaigns to evaluate example: - 10 - 12 Product: type: object description: The specific properties of the product this item belongs to, if available. required: - name properties: name: type: string description: The product the item belongs to. example: sample_product AdditionalCost: type: object required: - price properties: price: title: Price of additional cost type: number example: 4.5 PriceDetail: type: object properties: price: type: number format: float description: The value of this price type. example: 90 adjustmentContextId: type: string description: The context identifier of the selected price adjustment. example: summer25 adjustmentReferenceId: type: string format: uuid description: The reference identifier of the selected price adjustment for this SKU. example: 68851723-e6fa-488f-ace9-112581e6c19b adjustmentEffectiveFrom: type: string format: date-time description: The date and time from which the price adjustment is effective. example: 2025-05-25T00:00:00Z adjustmentEffectiveUntil: type: string format: date-time description: The date and time until which the price adjustment is effective. example: 2025-05-30T00:00:00Z CartItem: type: object required: - sku - quantity properties: name: title: Name of item type: string description: Name of item. example: Air Glide sku: title: SKU of item type: string description: Stock keeping unit of item. minLength: 1 example: SKU1241028 quantity: title: Quantity of item type: integer description: | Number of units of this item. Due to [cart item flattening](https://docs.talon.one/docs/product/rules/understanding-cart-item-flattening), if you provide a quantity greater than 1, the item will be split in as many items as the provided quantity. This will impact the number of **per-item** effects triggered from your campaigns. minimum: 1 example: 1 returnedQuantity: title: Returned quantity of item type: integer readOnly: true description: Number of returned items, calculated internally based on returns of this item. example: 1 remainingQuantity: title: Remaining quantity of item type: integer readOnly: true description: Remaining quantity of the item, calculated internally based on returns of this item. example: 1 price: title: Price of item type: number description: | Price of the item in the currency defined by your Application. This field is required if this item is not part of a [catalog](https://docs.talon.one/docs/product/account/dev-tools/managing-cart-item-catalogs). If it is part of a catalog, setting a price here overrides the price from the catalog. example: 99.99 category: title: Item category type: string description: Type, group or model of the item. example: shoes product: $ref: '#/components/schemas/Product' title: Item product weight: title: Weight of item type: number description: Weight of item in grams. example: 1130 height: title: Height of item type: number description: Height of item in mm. width: title: Width of item type: number description: Width of item in mm. length: title: Length of item type: number description: Length of item in mm. position: title: Position of Cart Item type: number readOnly: true description: Position of the Cart Item in the Cart (calculated internally). attributes: title: Item attributes type: object description: | Use this property to set a value for the attributes of your choice. [Attributes](https://docs.talon.one/docs/dev/concepts/attributes) represent any information to attach to this cart item. Custom _cart item_ attributes must be created in the Campaign Manager before you set them with this property. **Note:** Any previously defined attributes that you do not include in the array will be removed. example: image: 11.jpeg material: leather additionalCosts: type: object description: | Use this property to set a value for the additional costs of this item, such as a shipping cost. They must be created in the Campaign Manager before you set them with this property. See [Managing additional costs](https://docs.talon.one/docs/product/account/dev-tools/managing-additional-costs). additionalProperties: $ref: '#/components/schemas/AdditionalCost' example: shipping: price: 9 catalogItemID: title: The catalog item ID type: integer readOnly: true description: The catalog item ID. selectedPriceType: title: Price Type type: string readOnly: true description: The selected price type for this cart item (e.g. the price for members only). example: member adjustmentReferenceId: title: Price Adjustment ID type: string format: uuid readOnly: true description: The reference ID of the selected price adjustment for this cart item. Only returned if the selected price resulted from a price adjustment. example: 68851723-e6fa-488f-ace9-112581e6c19b adjustmentEffectiveFrom: title: Price Adjustment Start Date type: string format: date-time readOnly: true description: The date and time from which the price adjustment is effective. Only returned if the selected price resulted from a price adjustment that contains this field. example: 2021-09-12T10:12:42Z adjustmentEffectiveUntil: title: Price Adjustment Expiry Date type: string format: date-time readOnly: true description: The date and time until which the price adjustment is effective. Only returned if the selected price resulted from a price adjustment that contains this field. example: 2021-09-12T10:12:42Z prices: readOnly: true type: object description: | A map of keys and values representing the price types and related price adjustment details for this cart item. The keys correspond to the `priceType` names. additionalProperties: $ref: '#/components/schemas/PriceDetail' example: member: price: 90 adjustmentReferenceId: 68851723-e6fa-488f-ace9-112581e6c19b effectiveFrom: 2025-05-25T00:00:00Z effectiveUntil: 2025-05-30T00:00:00Z base: price: 100 ExperimentVariantAllocation: type: object required: - experimentID - variantID properties: experimentID: description: The ID of the experiment. type: integer example: 1 variantID: description: The ID of the variant to be allocated. type: integer example: 2 NewCustomerSessionV2: description: The representation of the customer session. allOf: - $ref: '#/components/schemas/IntegrationProfileEntity' - $ref: '#/components/schemas/IntegrationStoreEntity' - $ref: '#/components/schemas/EvaluableCampaignIds' - type: object properties: couponCodes: type: array items: type: string maxLength: 100 description: | Any coupon codes entered. **Important - for requests only**: - If you [create a coupon budget](https://docs.talon.one/docs/product/campaigns/settings/managing-campaign-budgets/#budget-types) for your campaign, ensure the session contains a coupon code by the time you close it. - In requests where `dry=false`, providing an empty array discards any previous coupons. To avoid this, omit the parameter entirely. title: Coupons entered in session example: - XMAS-20-2021 referralCode: type: string description: | Any referral code entered. **Important - for requests only**: - If you [create a referral budget](https://docs.talon.one/docs/product/campaigns/settings/managing-campaign-budgets/#budget-types) for your campaign, ensure the session contains a referral code by the time you close it. - In requests where `dry=false`, providing an empty value discards the previous referral code. To avoid this, omit the parameter entirely. title: Referral code entered in session maxLength: 100 example: NT2K54D9 loyaltyCards: type: array maxItems: 1 items: type: string description: Identifier of a loyalty card. example: - loyalty-card-1 state: type: string enum: - open - closed - partially_returned - cancelled default: open example: open description: | Indicates the current state of the session. Sessions can be created as `open` or `closed`. The state transitions are: 1. `open` -> `closed` 2. `open` -> `cancelled` 3. Either: - `closed` -> `cancelled` (**only** via [Update customer session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2)) or - `closed` -> `partially_returned` (**only** via [Return cart items](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/returnCartItems)) - `closed` -> `open` (**only** via [Reopen customer session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/reopenCustomerSession)) 4. `partially_returned` -> `cancelled` For more information, see [Customer session states](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions). title: Customer's session state cartItems: type: array description: | The items to add to this session. **Do not exceed 1000 items** and ensure the sum of all cart item's `quantity` **does not exceed 10.000** per request. title: Customer session's cart items items: $ref: '#/components/schemas/CartItem' experimentVariantAllocations: type: array description: | The experiment variant allocations to add to this session. title: Experiment variant allocations items: $ref: '#/components/schemas/ExperimentVariantAllocation' additionalCosts: type: object description: | Use this property to set a value for the additional costs of this session, such as a shipping cost. They must be created in the Campaign Manager before you set them with this property. See [Managing additional costs](https://docs.talon.one/docs/product/account/dev-tools/managing-additional-costs). additionalProperties: $ref: '#/components/schemas/AdditionalCost' example: shipping: price: 9 identifiers: type: array maxItems: 5 items: type: string title: Session identifiers description: | Session custom identifiers that you can set limits on or use inside your rules. For example, you can use IP addresses as identifiers to potentially identify devices and limit discounts abuse in case of customers creating multiple accounts. See the [tutorial](https://docs.talon.one/docs/dev/tutorials/using-identifiers). **Important**: Ensure the session contains an identifier by the time you close it if: - You [create a unique identifier budget](https://docs.talon.one/docs/product/campaigns/settings/managing-campaign-budgets/#budget-types) for your campaign. - Your campaign has [coupons](https://docs.talon.one/docs/product/campaigns/coupons/coupon-page-overview). - We recommend passing an anonymized (hashed) version of the identifier value. example: - d41306257915f83fe01e54092ae470f631161ea16fcf4415842eed41470386ea attributes: type: object additionalProperties: true description: | Use this property to set a value for the attributes of your choice. Attributes represent any information to attach to your session, like the shipping city. You can use [built-in attributes](https://docs.talon.one/docs/dev/concepts/attributes#built-in-attributes) or [custom ones](https://docs.talon.one/docs/dev/concepts/attributes#custom-attributes). Custom attributes must be created in the Campaign Manager before you set them with this property. example: ShippingCity: Berlin CustomerSessionV2: allOf: - $ref: '#/components/schemas/Entity' - $ref: '#/components/schemas/IntegrationEntity' - $ref: '#/components/schemas/ApplicationEntity' - $ref: '#/components/schemas/NewCustomerSessionV2' - type: object properties: firstSession: type: boolean description: Indicates whether this is the first session for the customer's profile. It's always `true` for anonymous sessions. title: First session ever? example: true updateCount: type: integer description: The number of times the session was updated. When the session is created, this value is initialized to `1`. title: Update count example: 3 total: type: number title: Session Total description: The total value of cart items and additional costs in the session, before any discounts are applied. example: 134.99 cartItemTotal: type: number title: Cart Items Total description: The total value of cart items, before any discounts are applied. example: 99.99 additionalCostTotal: type: number title: Additional Costs Total description: The total value of additional costs, before any discounts are applied. example: 20 cartItemAdditionalCostTotal: readOnly: true type: number title: Cart Item Additional Cost Total description: The total value of additional costs applied to individual items, before any discounts are applied. example: 15 updated: type: string format: date-time description: Timestamp of the most recent event received on this session. title: Last activity on the session example: 2020-02-08T14:15:22Z required: - profileId - firstSession - updateCount - coupon - referral - state - cartItems - integrationId - applicationId - attributes - total - cartItemTotal - additionalCostTotal - cartItemAdditionalCostTotal - updated EffectEntity: type: object description: Definition of all properties that are present on all effects, independent of their type. required: - campaignId - rulesetId - ruleIndex - ruleName - effectType properties: experimentId: type: integer description: The ID of the experiment that campaign belongs to. example: 12 campaignId: type: integer description: The ID of the campaign that triggered this effect. example: 244 rulesetId: type: integer description: The ID of the ruleset that was active in the campaign when this effect was triggered. example: 73 ruleIndex: type: integer description: The position of the rule that triggered this effect within the ruleset. example: 2 ruleName: type: string description: The name of the rule that triggered this effect. example: Give 20% discount effectType: type: string description: The type of effect that was triggered. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects). example: rejectCoupon triggeredByCoupon: type: integer example: 4928 description: The ID of the coupon that was being evaluated when this effect was triggered. triggeredForCatalogItem: type: integer example: 786 description: The ID of the catalog item that was being evaluated when this effect was triggered. conditionIndex: type: integer example: 786 description: The index of the condition that was triggered. evaluationGroupID: type: integer example: 3 description: The ID of the evaluation group. For more information, see [Managing campaign evaluation](https://docs.talon.one/docs/product/applications/managing-campaign-evaluation). evaluationGroupMode: type: string example: stackable description: The evaluation mode of the evaluation group. For more information, see [Managing campaign evaluation](https://docs.talon.one/docs/product/applications/managing-campaign-evaluation). campaignRevisionId: type: integer example: 1 description: The revision ID of the campaign that was used when triggering the effect. campaignRevisionVersionId: type: integer example: 5 description: The revision version ID of the campaign that was used when triggering the effect. selectedPriceType: type: string example: member description: The selected price type for the SKU targeted by this effect. selectedPrice: type: number example: 100 description: The value of the selected price type to apply to the SKU targeted by this effect, before any discounts are applied. adjustmentReferenceId: type: string format: uuid example: 68851723-e6fa-488f-ace9-112581e6c19b description: The reference identifier of the selected price adjustment for this SKU. This is only returned if the `selectedPrice` resulted from a price adjustment. AcceptCouponEffectProps: type: object title: acceptCoupon description: |- This effect indicates that the coupon code supplied was valid. You should handle this effect by clearing any messages from previous `rejectCoupon` effects and informing the user that the coupon is valid. The code is automatically redeemed when you close the session. Other effects, such as [setDiscount](https://docs.talon.one/docs/dev/integration-api/api-effects#setdiscount), provide more information about the actual rewards received. example: value: COUP-XYZ789 required: - value properties: value: type: string description: The coupon code that was accepted. AcceptReferralEffectProps: type: object title: acceptReferral description: |- This effect indicates that the referral code supplied is valid. You should handle this effect by informing the user that the referral code is valid. The code is automatically redeemed when you close the session. Other effects will provide more information about the actual reward. example: value: REF-ABC123 required: - value properties: value: type: string description: The referral code provided in the session. RedeemReferralEffectProps: type: object deprecated: true title: redeemReferral description: | This effect is **deprecated**. It has been replaced by the `acceptReferral` effect. This effect indicates that the referral code is valid and has been redeemed. example: id: 12 value: REF-ABC123 required: - id - value properties: id: type: integer description: The id of the referral code that was redeemed. value: type: string description: The referral code that was redeemed. RejectCouponEffectProps: type: object title: rejectCoupon description: |- This effect indicates that the coupon code supplied couldn't be used. You should handle this effect by informing their user the coupon code is invalid. example: value: COUP-XYZ789 rejectionReason: CouponRejectedCondition conditionIndex: 2 effectIndex: 0 details: Coupon usage limit reached campaignExclusionReason: CampaignGaveLowerDiscount required: - value - rejectionReason properties: value: type: string description: The coupon code that was rejected. rejectionReason: type: string description: |- The reason why the code was rejected. - `CampaignLimitReached`: The campaign-wide coupon code redemption limit has been reached. - `CouponExpired`: The coupon is expired. - `CouponLimitReached`: The coupon redemption limit or a campaign budget was reached. - `CouponNotFound`: The coupon code is incorrect. - `CouponPartOfNotRunningCampaign`: The campaign the coupon belongs to is currently not active. The campaignId field contains the ID of that campaign. - `CouponRecipientDoesNotMatch`: The given coupon value does not match the recipient or the coupon is linked to a `recipientIntegrationID` but there is no profile in the session. - `CouponRejectedByCondition`: Other conditions failed in the rule or all conditions passed but the `Coupon code is valid` condition is not present. - `CouponStartDateInFuture`: The coupon isn't active yet. - `EffectCouldNotBeApplied`: One of the effects in the campaign wasn't applied because a limit for that effect was reached (most common use case will be `setDiscount` cannot be applied because a discount limit is reached). - `ProfileLimitReached`: The profile-specific coupon redemption limit has been reached. - `CouponPartOfNotTriggeredCampaign`: The campaign the coupon belongs to was not triggered during evaluation (an exclusive or stackable campaign). The `campaignId` field contains the ID of that campaign. - `CouponReservationRequired`: The coupon's `isReservationMandatory` property is `true`, but the profile does not have a reservation. - `ProfileRequired`: The coupon's `isReservationMandatory` property is `true` or a [campaign profile budget](https://docs.talon.one/docs/product/campaigns/settings/manage-campaign-budgets) was set, but no profile exists in the session. conditionIndex: type: integer description: The index of the condition that caused the rejection of the coupon. effectIndex: type: integer description: The index of the effect that caused the rejection of the coupon. details: type: string description: More details about the failure. campaignExclusionReason: type: string example: CampaignGaveLowerDiscount description: |- The reason why the campaign the coupon belongs to was excluded during [campaign evaluation](https://docs.talon.one/docs/product/applications/manage-campaign-evaluation), when `rejectionReason` was `CouponPartOfNotTriggeredCampaign`. Its possible values are: - `CampaignGaveLowerDiscount`: The required campaign and coupon conditions were met, but another campaign in a [Highest discount value](https://docs.talon.one/docs/product/applications/manage-campaign-evaluation#set-campaign-evaluation-mode) group offered a higher discount value. - `CampaignIsNotFirst`: The campaign was not evaluated because another campaign in a [First campaign](https://docs.talon.one/docs/product/applications/manage-campaign-evaluation#set-campaign-evaluation-mode) group was picked and evaluated first. - `CampaignNotInEvaluationSet`: The campaign did not meet other evaluation requirements, for example, because the coupon is part of an archived campaign. RejectReferralEffectProps: type: object title: rejectReferral description: This effect indicates that the provided referral code is invalid. example: value: REF-ABC123 rejectionReason: ReferralRejectedCondition conditionIndex: 1 effectIndex: 0 details: Referral code already used campaignExclusionReason: CampaignGaveLowerDiscount required: - value - rejectionReason properties: value: type: string description: The referral code that was rejected rejectionReason: type: string description: |- The reason why the code was rejected. - `AdvocateNotFound`: The advocate was not found. - `CampaignLimitReached`: The campaign-wide referral code redemption limit has been reached. - `EffectCouldNotBeApplied`: One of the effects in the campaign wasn't applied because a limit for that effect was reached (most common use case will be `setDiscount` can not be applied because a discount limit is reached). - `ProfileLimitReached`: The profile-specific referral code redemption limit has been reached. - `ReferralCustomerAlreadyReferred`: The friend is already referred. - `ReferralExpired`: The transferred referral code is expired. - `ReferralLimitReached`: The referral code redemption limit has been reached. - `ReferralNotFound`: The transferred referral code is wrong. - `ReferralPartOfNotRunningCampaign`: The campaign the referral code belongs to is currently not active. The campaign ID field shows the ID of that campaign. - `ReferralRecipientDoesNotMatch`: The given referral code value does not match the recipient. - `ReferralRecipientIdSameAsAdvocate`: The recipient (friend) has the same id as the advocate. - `ReferralRejectedByCondition`: The referral code is valid and in an active campaign, but there were other conditions in that campaign's rules that were not met. - `ReferralStartDateInFuture`: The transferred referral code isn't active yet. - `ReferralPartOfNotTriggeredCampaign`: The campaign the referral code belongs to was not triggered during evaluation (an exclusive or stackable campaign). The campaign ID field shows the ID of that campaign. conditionIndex: type: integer description: The index of the condition that caused the rejection of the referral. effectIndex: type: integer description: The index of the effect that caused the rejection of the referral. details: type: string description: More details about the failure. campaignExclusionReason: type: string example: CampaignGaveLowerDiscount description: |- The reason why the campaign the referral belongs to was excluded during [campaign evaluation](https://docs.talon.one/docs/product/applications/manage-campaign-evaluation), when `rejectionReason` was `CouponPartOfNotTriggeredCampaign`. Its possible values are: - `CampaignGaveLowerDiscount`: The required campaign and referral conditions were met, but another campaign in a [Highest discount value](https://docs.talon.one/docs/product/applications/manage-campaign-evaluation#set-campaign-evaluation-mode) group offered a higher discount value. - `CampaignIsNotFirst`: The campaign was not evaluated because another campaign in a [First campaign](https://docs.talon.one/docs/product/applications/manage-campaign-evaluation#set-campaign-evaluation-mode) group was picked and evaluated first. - `CampaignNotInEvaluationSet`: The campaign did not meet other evaluation requirements, for example, because the referral is part of an archived campaign. CouponCreatedEffectProps: type: object title: couponCreated description: |- This effect indicates that a coupon was created. For referrals and retention marketing, a common use case is to generate a coupon that can only be redeemed by one specific customer. Handle this effect by notifying the recipient about their new coupon code. example: value: COUP-NEW123 profileId: customer_profile_id_1 required: - value - profileId properties: value: type: string description: The coupon code that was created. profileId: type: string description: The integration identifier of the customer for whom this coupon was created. ReferralCreatedEffectProps: type: object title: referralCreated description: The `referralCreated` effect behaves similarly to [couponCreated](https://docs.talon.one/docs/dev/integration-api/api-effects#couponcreated). If the `friendProfileIntegrationId` parameter is empty, the referral code can be redeemed by anyone. example: value: REF-NEW456 required: - value properties: value: type: string description: The referral code provided in the session. SetDiscountEffectProps: type: object title: setDiscount description: |- This effect indicates that a discount should be set on the total shopping cart value of the current order with the given label and amount. The discount should overwrite any existing discount with the same name. The most recent integration state update always returns the latest values for **all** effects, effectively overwriting any previous effects. Enabling [partial discounts](https://docs.talon.one/docs/product/applications/manage-general-settings#partial-discounts) allows a rule that would fail because of insufficient budget to pass. The rule still fails when the budget reaches `0`. Use the `desiredValue` property to identify the original value of the discount. example: name: 10% Off value: 2.5 scope: sessionTotal desiredValue: 2.5 required: - name - value properties: name: type: string description: The name or description of this discount. value: type: number description: The monetary value of the effective discount. scope: type: string description: |- What the discount applies to. Possible values: - `cartItems`: Discount on the price of the items. - `additionalCosts`: Discount on the [additional costs](https://docs.talon.one/docs/product/account/dev-tools/manage-additional-costs) of the items. - `sessionTotal`: Discount on the total value of the customer session. **Note:** [Cascading discounts](https://docs.talon.one/docs/product/applications/manage-general-settings#cascading-discounts) must be enabled for this property to be returned. desiredValue: type: number description: _(Partial discounts enabled only)_ The monetary value of the discount to be applied without considering budget limitations. SetDiscountPerItemEffectProps: type: object title: setDiscountPerItem description: |- This effect schema is returned when you use the **Discount individual items**, **Discount individual items pro rata**, or **Discount individual item in bundles** effect in a rule. It indicates that a discount per item should be applied on the specific item specified in the effect. The properties it contains depends on: - Whether you used a pro rata effect or not. - Whether you used an effect with bundles or not. - Whether the partial discount feature is enabled. example: name: 'Discount on item #1' value: 1.5 position: 1 subPosition: 1 desiredValue: 1.5 scope: price totalDiscount: 1.5 desiredTotalDiscount: 1.5 bundleIndex: 1 bundleName: my_bundle targetedItemPosition: 1 targetedItemSubPosition: 1 excludedFromPriceHistory: false required: - name - value - position properties: name: type: string description: The description of this discount. `#number` is equal to the `position` property. value: type: number description: The monetary value of the effective discount applied to the item. position: type: number description: The index of the item in the `cartItem` object on which this discount should be applied. subPosition: type: number description: The index of the item unit in its line item. desiredValue: type: number description: _(Partial discounts enabled only)_ The monetary value of the discount to be applied to the item without considering budget limitations. scope: type: string description: |- What the discount applies to. Possible values: - `price`: discount on the price of the item. - `additionalCosts`: discount on the [additional cost](https://docs.talon.one/docs/product/account/dev-tools/manage-additional-costs) of the item. - `itemTotal`: discount on the sum of price + additional cost of the item. totalDiscount: type: number description: _(Pro rata discounts only)_ The monetary value of the total effective discount desiredTotalDiscount: type: number description: _(Pro rata discounts only)_ The monetary value of the total discount to be applied without considering budget limitations bundleIndex: type: integer description: _(Discounts with bundles only)_ The position of the specific item bundle in the list of bundles created from the same bundle definition. bundleName: type: string description: _(Discounts with bundles only)_ The name of the bundle definition. targetedItemPosition: type: number description: _(Discounting individual item in bundles only)_ The index of the targeted bundle item on which the applied discount is based. targetedItemSubPosition: type: number description: _(Discounting individual item in bundles only)_ The sub-position of the targeted bundle item on which the applied discount is based. excludedFromPriceHistory: type: boolean description: When set to `true`, the applied discount is excluded from the item's price history. SetDiscountPerAdditionalCostEffectProps: type: object title: setDiscountPerAdditionalCost description: |- This effect indicates that a discount that should be applied on a specific additional cost. It is triggered whenever a rule containing a **Discount additional cost** effect is validated. Enabling [partial rewards](https://docs.talon.one/docs/product/applications/manage-general-settings#partial-rewards) allows a rule that would fail because of insufficient budget to pass. The rule still fails when the budget reaches 0. Use the `desiredValue` property to identify the original amount of loyalty points. example: name: Shipping discount additionalCostId: 1 additionalCost: shipping value: 4.99 desiredValue: 4.99 required: - name - value - additionalCostId - additionalCost properties: name: type: string description: The name of the discount. additionalCostId: type: integer description: The identifier of the additional cost. additionalCost: type: string description: The API name of the additional cost. value: type: number description: The monetary value of the discount to apply. desiredValue: type: number description: _(Partial discounts enabled only)_ The monetary value of the discount to be applied without considering budget limitations. TriggerWebhookEffectProps: type: object title: triggerWebhook description: This effect is triggered when a rule containing a [webhook effect](https://docs.talon.one/docs/product/rules/effects/available-effects#webhooks) is validated. The details are shared with you for your information only. It usually doesn't require an action on your side. example: webhookId: 7 webhookName: My Webhook required: - webhookId - webhookName properties: webhookId: type: number description: The internal ID of the webhook. webhookName: type: string description: The name of the webhook. LoyaltyCardIdentifier: type: string description: | The identifier of the loyalty card, which must match the regular expression `^[A-Za-z0-9._%+@-]+$`. maxLength: 108 minLength: 4 pattern: ^[A-Za-z0-9._%+@-]+$ example: summer-loyalty-card-0543 AddLoyaltyPointsEffectProps: type: object title: addLoyaltyPoints description: |- This effect indicates that a defined amount of loyalty points was successfully added to the customer's profile or to a loyalty card. If you use the [Add loyalty points per item effect](https://docs.talon.one/docs/product/rules/effects/available-effects#reward-effects), use the `cartItemPosition` property to identify which item to add the loyalty points for. Enabling [partial rewards](https://docs.talon.one/docs/product/applications/manage-general-settings#partial-rewards) allows a rule that would fail because of insufficient budget to pass. The rule still fails when the budget reaches 0. Use the `desiredValue` property to identify the original amount of loyalty points. If you use **Add loyalty points per item** and if the session contains some cart items with _quantity > 1_, use the `cartItemSubPosition` property to identify the item unit in its line item. See the example below for more information. If your list of cart items is a [bundle definition](https://docs.talon.one/docs/product/rules/create-and-manage-bundles), use the `bundleIndex` and `bundleName` properties to identify the bundle containing the items for which loyalty points are added. If you have set custom activation and expiration dates for the loyalty points, use the `startDate` and `expiryDate` properties to identify when the reward will be active and when will expire. If the loyalty program is [profile-based](https://docs.talon.one/docs/product/loyalty-programs/overview#loyalty-program-types), use the `recipientIntegrationId` property to identify the user who receives the loyalty points. If the loyalty program is [card-based](https://docs.talon.one/docs/product/loyalty-programs/overview#loyalty-program-types), use the `cardIdentifier` property to identify the loyalty card on which these points are added. The points only persist when the session is closed. example: name: Points for purchase programId: 5 subLedgerId: main value: 100 desiredValue: 100 recipientIntegrationId: URNGV8294NV startDate: 2024-01-01T00:00:00Z expiryDate: 2025-01-01T00:00:00Z transactionUUID: 8c2d3670-6ea5-4e9e-b5c6-e7e7b4a10111 cartItemPosition: 1 cartItemSubPosition: 1 cardIdentifier: loyalty-card-001 bundleIndex: 1 bundleName: my_bundle awaitsActivation: false validityDuration: 12M required: - name - programId - subLedgerId - value - recipientIntegrationId - transactionUUID properties: name: type: string description: The reason of this loyalty point addition. programId: type: integer description: The ID of the loyalty program where these points were added. subLedgerId: type: string description: The ID of the subledger within the loyalty program where these points were added. value: type: number description: The amount of points that were added. desiredValue: type: number description: (Partial rewards enabled only) The amount of loyalty points to be awarded without considering budget limitations. recipientIntegrationId: type: string maxLength: 1000 description: The user for whom these points were added. example: URNGV8294NV startDate: type: string format: date-time description: The date after which the added points will be valid. expiryDate: type: string format: date-time description: The date after which the added points will expire. transactionUUID: type: string description: The identifier of this loyalty point transaction. cartItemPosition: type: number description: (_Add points per cart item_ only.) The index of the item in the `cartItem` object for which these points were added. cartItemSubPosition: type: number description: (_Add points per cart item_ ) The index of the item unit in its line item. cardIdentifier: $ref: '#/components/schemas/LoyaltyCardIdentifier' description: The identifier of the card on which these points were added. bundleIndex: type: integer description: _(With bundles only)_ The position of the specific bundle in the list of bundles created from the same bundle definition. bundleName: type: string description: _(With bundles only)_ The name of the bundle definition. awaitsActivation: type: boolean description: Indicates whether the points have an action-based start date. This property is returned only for point transactions with an action-based start date. validityDuration: type: string description: The duration for which the points remain active, calculated relative to their start date. DeductLoyaltyPointsEffectProps: type: object title: deductLoyaltyPoints description: |- This effect is triggered when a customer redeems loyalty points. The points are deducted from their active point balance. If the loyalty program is card-based, use the `cardIdentifier` property to identify the loyalty card from which these points are deducted. The Rule Engine deducts points in this order: - Points with the earliest expiry date are deducted first, regardless of when they were added. - Points with an unlimited expiry date are deducted last. - For points with an unlimited expiry date, the points awarded first are deducted first. The points only persist when the session is closed. example: ruleTitle: Deduct points on return programId: 5 subLedgerId: main value: 50 transactionUUID: 9f3e4781-7fb6-5f0f-c6d7-f8f8c5b21222 name: Points deducted for return cardIdentifier: loyalty-card-001 required: - ruleTitle - programId - subLedgerId - value - transactionUUID - name properties: ruleTitle: type: string description: The title of the rule that contained triggered this points deduction. programId: type: integer description: The ID of the loyalty program from which these points were deducted. subLedgerId: type: string description: The ID of the subledger within the loyalty program from which these points were deducted. value: type: number description: The amount of points that were deducted. transactionUUID: type: string description: The identifier of this loyalty point transaction. name: type: string description: The reason of this loyalty points deduction. cardIdentifier: $ref: '#/components/schemas/LoyaltyCardIdentifier' description: The identifier of the card from which these points were deducted. ChangeLoyaltyTierLevelEffectProps: type: object title: changeLoyaltyTierLevel description: |- This effect indicates that a customer's loyalty tier has been upgraded. This effect is generated only when the [Add loyalty points](https://docs.talon.one/docs/product/rules/effects/use-effects#add-loyalty-points) and the [Add loyalty points per cart item](https://docs.talon.one/docs/product/rules/effects/use-effects#add-loyalty-points-per-cart-item) effects are triggered for a particular customer, and, as a result, the customer's loyalty tier is upgraded. example: ruleTitle: Tier upgrade on purchase programId: 5 subLedgerId: main previousTierName: Silver newTierName: Gold expiryDate: 2025-12-31T23:59:59Z required: - ruleTitle - programId - subLedgerId - newTierName properties: ruleTitle: type: string description: The title of the rule that triggered the tier upgrade. programId: type: integer description: The ID of the loyalty program where the points were added. subLedgerId: type: string description: The ID of the subledger within the loyalty program where the points were added. previousTierName: type: string description: The name of the tier from which the user was upgraded. newTierName: type: string description: The name of the tier to which the user has been upgraded. expiryDate: type: string format: date-time description: The expiration date of the new tier. AddFreeItemEffectProps: type: object title: addFreeItem description: |- This effect indicates that a free item should be added to the shopping cart in the current session. In this example, add the SKU to the shopping cart and set its price to `0`. The effect of a successful referral can mean a free item for someone else, such as the referrer. example: sku: SKU1241028 name: Free Gift Item desiredQuantity: 1 required: - sku - name properties: sku: type: string description: SKU of the item that needs to be added. example: SKU1241028 name: type: string description: Description of the effect. desiredQuantity: type: integer description: The original quantity in case a partial reward was applied. ShowNotificationEffectProps: type: object title: showNotification description: |- You can use notifications to inform customers of certain events. There are four types of notification messages: - `Info` - `Offer` - `Error` - `Misc` It is up to you to use the Rule Builder to decide why and when to show notifications. Notifications can be used as both rule effects and failure effects. A common use case is to display the notification at the top of the cart view in your web app. You can use the notification type to vary the styling of the notification message. example: notificationType: info title: Discount applied body: You have received a 10% discount on your order. required: - notificationType - title - body properties: notificationType: type: string description: The type of notification. title: type: string description: The title of the notification. body: type: string description: The body of the notification. UpdateAttributeEffectProps: type: object title: updateAttribute description: This effect indicates that a rule containing an [Update attribute value](https://docs.talon.one/docs/product/rules/effects/available-effects#update-effects) or [Update cart item attribute value](https://docs.talon.one/docs/product/rules/effects/available-effects#update-effects) was validated. You should update the value of the attribute in your system based on the content of the returned effect. example: path: Session.Attributes.loyaltyTier value: Gold required: - path - value properties: path: type: string description: The entity type and the attribute name. value: description: The new value of the attribute. RollbackCouponEffectProps: type: object title: rollbackCoupon description: |- This effect indicates that a coupon code redemption has been rolled back. The coupon becomes redeemable again. The effect is triggered when you [cancel](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions#manage-the-sessions-state) a session where a coupon was accepted. See an example of use in the [cancelling a session tutorial](https://docs.talon.one/docs/dev/tutorials/roll-back-effects). example: value: COUP-XYZ789 required: - value properties: value: type: string description: The coupon code whose redemption has been rolled back. RollbackReferralEffectProps: type: object title: rollbackReferral description: |- This effect indicates that the redemption of the referral code has been rolled back. It triggers when a closed session that redeemed a referral is gets cancelled. The code becomes redeemable again. For more information about session states, see [Managing states](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions#customer-session-states). example: value: REF-ABC123 required: - value properties: value: type: string description: The referral code to be rolled back. RollbackDiscountEffectProps: type: object title: rollbackDiscount description: |- This effect indicates that a discounted session, cart item, or additional cost has been cancelled or partially returned. This effect can only happen when you set the status of a session to `cancel` or the status changes to `partially_returned`. If the session contains some cart items with _quantity > 1_, use the `cartItemSubPosition` property to identify the specific item unit in its line item. See the example below. example: name: 10% Off value: 2.5 cartItemPosition: 1 cartItemSubPosition: 1 additionalCostId: 1 additionalCost: shipping scope: sessionTotal required: - name - value properties: name: type: string description: The name of the discount effect that was rolled back. value: type: number description: The monetary value of the discount that was rolled back. cartItemPosition: type: number description: The index of the item in the `cartItem` object whose discount was rolled back, or the unit containing the additional cost whose discount was rolled back. cartItemSubPosition: type: number description: The index of the item unit in its line item for which the discount was rolled back. additionalCostId: type: integer description: _Only when rolling back [setDiscountPerAdditionalCost](https://docs.talon.one/docs/dev/integration-api/api-effects#setdiscountperadditionalcost) and [setDiscountPerAdditionalCostPerItem](https://docs.talon.one/docs/dev/integration-api/api-effects#setdiscountperadditionalcostperitem)_ The ID of the additional cost to be discounted. additionalCost: type: string description: The API name of the additional cost whose discount was rolled back. scope: type: string description: |- The scope of the rolled back discount. - For a discount per session, it can be one of `cartItems`, `additionalCosts` or `sessionTotal` - For a discount per item, it can be one of `price`, `additionalCosts` or `itemTotal` RollbackAddedLoyaltyPointsEffectProps: type: object title: rollbackAddedLoyaltyPoints description: |- This effect is triggered in the following cases: - A session was cancelled in which loyalty points have been added. - A session was partially returned and loyalty point were added by the returned items. See [returning items](https://docs.talon.one/docs/dev/tutorials/partially-return-a-session). If you use the [Add loyalty points per item effect](https://docs.talon.one/docs/product/rules/effects/available-effects#reward-effects), use the `cartItemPosition` property to identify which items the loyalty points were rolled back for. If you use **Add loyalty points per item** and if the session contains some cart items with _quantity > 1_, use the `cartItemSubPosition` property to identify the item unit in its line item. If the loyalty program is [profile-based](https://docs.talon.one/docs/product/loyalty-programs/overview#loyalty-program-types), use the `recipientIntegrationId` property to identify the user for whom the loyalty points are rolled back. If the loyalty program is [card-based](https://docs.talon.one/docs/product/loyalty-programs/overview#loyalty-program-types), use the `cardIdentifier` property to identify the loyalty card where the points were originally added. example: programId: 5 subLedgerId: main value: 100 recipientIntegrationId: URNGV8294NV transactionUUID: 8c2d3670-6ea5-4e9e-b5c6-e7e7b4a10111 cartItemPosition: 1 cartItemSubPosition: 1 cardIdentifier: loyalty-card-001 required: - programId - subLedgerId - value - recipientIntegrationId - transactionUUID properties: programId: type: integer description: The ID of the loyalty program where these points were rolled back. subLedgerId: type: string description: The ID of the subledger within the loyalty program where these points were rolled back. value: type: number description: The amount of points that were rolled back. recipientIntegrationId: type: string maxLength: 1000 description: The user for whom these points were rolled back. example: URNGV8294NV transactionUUID: type: string description: The identifier of this loyalty point transaction. cartItemPosition: type: number description: (_Add points per cart item_ only.) The index of the item in the `cartItem` object for which these points were rolled back. cartItemSubPosition: type: number description: (_Add points per cart item_ ) The index of the item unit in its line item. cardIdentifier: $ref: '#/components/schemas/LoyaltyCardIdentifier' description: The identifier of the card on which these points were originally added. RollbackDeductedLoyaltyPointsEffectProps: type: object title: rollbackDeductedLoyaltyPoints description: |- This effect is triggered in the following cases: - A session is _cancelled_ and this session deducted loyalty points. The rollback action returns the redeemed loyalty points to the customer. - A session is impacted by a _partial return_. Only added loyalty points that are still **pending** are rolled back. - A session in which loyalty points were spent is reopened. See the [session states](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions#customer-session-states). If you set custom activation and expiration dates for the loyalty points, use the `startDate` and `expiryDate` properties to identify when the reward will be active and when will expire. If the loyalty program is [profile-based](https://docs.talon.one/docs/product/loyalty-programs/profile-based/profile-based-overview), use the `recipientIntegrationId` property to identify the user who receives the loyalty points. If the loyalty program is [card-based](https://docs.talon.one/docs/product/loyalty-programs/overview#loyalty-program-types), use the `cardIdentifier` property to identify the loyalty card where the points are reimbursed. example: programId: 5 subLedgerId: main value: 50 recipientIntegrationId: URNGV8294NV startDate: 2024-01-01T00:00:00Z expiryDate: 2025-01-01T00:00:00Z transactionUUID: 9f3e4781-7fb6-5f0f-c6d7-f8f8c5b21222 cardIdentifier: loyalty-card-001 required: - programId - subLedgerId - value - recipientIntegrationId - transactionUUID properties: programId: type: integer description: The ID of the loyalty program where these points were reimbursed. subLedgerId: type: string description: The ID of the subledger within the loyalty program where these points were reimbursed. value: type: number description: The amount of points that were reimbursed. recipientIntegrationId: type: string maxLength: 1000 description: The user for whom these points were reimbursed. example: URNGV8294NV startDate: type: string format: date-time description: The date after which the reimbursed points will be valid. expiryDate: type: string format: date-time description: The date after which the reimbursed points will expire. transactionUUID: type: string description: The identifier of this loyalty point transaction. cardIdentifier: $ref: '#/components/schemas/LoyaltyCardIdentifier' description: The identifier of the card from which these points were originally deducted. ShowBundleMetadataEffectProps: type: object deprecated: true title: showBundleMetadata description: |- This effect is **deprecated**. The `ShowBundleMetadata` effect contains information that allows you to associate the discounts from a rule in a bundle campaign with specific cart items. This way you can distinguish from "normal" discounts that were not the result of a product bundle. example: description: Buy 2 get 1 free bundle bundleAttributes: - category - brand itemsIndices: - 0 - 1 - 2 required: - description - bundleAttributes - itemsIndices properties: description: type: string description: Description of the product bundle. bundleAttributes: type: array items: type: string description: The cart item attributes that determined which items are being bundled together. itemsIndices: type: array items: type: number description: The indices in the cart items array of the bundled items. AwardGiveawayEffectProps: type: object title: awardGiveaway description: This effect indicates the awarded giveaway item and to which profile the item was awarded. Learn more about [giveaways](https://docs.talon.one/docs/product/giveaways/overview). example: poolId: 2 poolName: My pool recipientIntegrationId: URNGV8294NV giveawayId: 5 code: 57638t-67439hty required: - poolId - poolName - recipientIntegrationId - giveawayId - code properties: poolId: type: integer description: The internal ID of the giveaway pool. example: 2 poolName: type: string description: The name of the giveaway pool. example: My pool recipientIntegrationId: type: string maxLength: 1000 description: The integration ID of the customer that receives the giveaway. example: URNGV8294NV giveawayId: type: integer description: The internal ID of the giveaway. example: 5 code: type: string description: The giveaway code to be rewarded. example: 57638t-67439hty WillAwardGiveawayEffectProps: type: object title: willAwardGiveaway description: |- The equivalent of the `awardGiveaway` effect but returned when updating a session with any state other than `closed`. This ensures no giveaway codes are leaked when they are still not guaranteed to be awarded. For more information about session states, see [Manage the session's state](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions#manage-the-sessions-state). example: poolId: 2 poolName: My pool recipientIntegrationId: URNGV8294NV required: - poolId - poolName - recipientIntegrationId properties: poolId: type: integer description: The internal ID of the giveaway pool. example: 2 poolName: type: string description: The name of the giveaway pool. example: My pool recipientIntegrationId: type: string maxLength: 1000 description: The integration ID of the customer that receives the giveaway. example: URNGV8294NV ErrorEffectProps: type: object title: error description: This effect is triggered whenever an error occurs during rule evaluation. This effect only provides information about what the error is. example: message: An unexpected error occurred during rule evaluation. required: - message properties: message: type: string description: The error message. CustomEffectProps: type: object title: customEffect description: |- If you want to return data as an effect but no effect matches your use case, you can [create a custom effect](https://docs.talon.one/docs/dev/tutorials/create-custom-effects). Custom effects can be used as both rule effects and failure effects. The structure of a custom effect depends on your specifications but is always named `customEffect`. example: effectId: 1 name: my_custom_effect cartItemPosition: 1 cartItemSubPosition: 2 bundleIndex: 1 bundleName: my_bundle payload: key: value required: - effectId - name - payload properties: effectId: type: integer description: The ID of the custom effect that was triggered. example: 1 name: type: string description: The type of the custom effect. example: my_custom_effect cartItemPosition: type: number description: The index of the item in the cart item list to which the custom effect is applied. example: 1 cartItemSubPosition: type: number description: | For cart items with quantity > 1, the sub position indicates to which item unit the custom effect is applied. example: 2 bundleIndex: type: integer description: The position of the bundle in a list of item bundles created from the same bundle definition. example: 1 bundleName: type: string description: The name of the bundle definition. example: my_bundle payload: description: The JSON payload of the custom effect. type: object x-arbitraryJSON: true SetDiscountPerAdditionalCostPerItemEffectProps: type: object title: setDiscountPerAdditionalCostPerItem description: |- This effect indicates that a discount of a specific additional cost within a specific item should be applied. It gets triggered whenever a rule containing a **Discount additional cost per item** effect is validated. Use this effect when **all** items in the cart have an additional cost. If one of more items do not have an additional cost, the rule will fail. example: name: 'Shipping discount on item #1' additionalCostId: 1 value: 4.99 position: 1 subPosition: 1 additionalCost: shipping desiredValue: 4.99 required: - name - value - additionalCostId - additionalCost - position properties: name: type: string description: The description of this discount. `#number` is appended to the name. It is equal to the `position` property. additionalCostId: type: integer description: The identifier of the additional cost to be discounted. value: type: number description: The monetary value of the effective discount applied to the item's additional cost. position: type: number description: The index of the item in the `cartItem` object containing the additional cost that this discount applies to. subPosition: type: number description: The index of the item unit in its line item. additionalCost: type: string description: The API name of the additional cost to be discounted. desiredValue: type: number description: _[(Partial discounts enabled only)](https://docs.talon.one/docs/product/applications/manage-general-settings#partial-discounts)_. The monetary value of the discount to be applied to the additional cost without considering budget limitations. ReserveCouponEffectProps: type: object title: reserveCoupon description: |- This effect indicates that the given coupon code was reserved for the given customer. Talon.One provides soft and hard reservations. For more information, see [Reserve a coupon code](https://docs.talon.one/docs/product/rules/effects/use-effects#reserve-a-coupon-code). example: couponValue: COUP-XYZ789 profileIntegrationId: customer_profile_id_1 isNewReservation: true required: - couponValue - profileIntegrationId - isNewReservation properties: couponValue: type: string description: The coupon code that was created. profileIntegrationId: type: string description: The integration identifier of the customer for whom this coupon was reserved. isNewReservation: type: boolean description: Indicates whether this is a new coupon reservation or not. AddToAudienceEffectProps: type: object title: addToAudience description: This effect is triggered when a rule containing an [Update audience](https://docs.talon.one/docs/product/rules/effects/use-effects#update-an-audience) effect with **Add customer to an audience** selected is validated. It indicates that a customer was added to an audience and is returned when a customer session is opened, updated, or closed. example: audienceId: 10 audienceName: My audience profileIntegrationId: URNGV8294NV profileId: 150 properties: audienceId: type: integer description: The internal ID of the audience. example: 10 audienceName: type: string description: The name of the audience. example: My audience profileIntegrationId: type: string description: The ID of the customer profile in the third-party integration platform. example: URNGV8294NV profileId: type: integer description: The internal ID of the customer profile. example: 150 RemoveFromAudienceEffectProps: type: object title: removeFromAudience description: This effect is triggered when a rule containing an [Update audience](https://docs.talon.one/docs/product/rules/effects/use-effects#update-an-audience) effect with **Remove customer from an audience** selected is validated. It indicates that a customer was removed from an audience and is returned when a customer session is opened, updated, or closed. example: audienceId: 10 audienceName: My audience profileIntegrationId: URNGV8294NV profileId: 150 properties: audienceId: type: integer description: The internal ID of the audience. example: 10 audienceName: type: string description: The name of the audience. example: My audience profileIntegrationId: type: string description: The ID of the customer profile in the third-party integration platform. example: URNGV8294NV profileId: type: integer description: The internal ID of the customer profile. example: 150 IncreaseAchievementProgressEffectProps: type: object title: increaseAchievementProgress description: |- This effect indicates that the customer's progress in an achievement was updated during the current session. It is triggered when a rule using the [Update customer progress](https://docs.talon.one/docs/product/rules/effects/use-effects#update-customer-progress) effect is successfully validated. For [on-completion achievements](https://docs.talon.one/docs/product/campaigns/achievements/achievements-overview#recurring-on-completion-achievements), any customer progress exceeding the target automatically starts a new iteration. This generates a new `progressTrackerId` for each iteration, and there can be multiple progress updates for the same achievement from a single validation of this effect. example: achievementId: 10 achievementName: FreeCoffee10Orders progressTrackerId: 42 delta: 1 value: 7 target: 10 isJustCompleted: false required: - achievementId - achievementName - delta - value - target - isJustCompleted properties: achievementId: type: integer description: The internal ID of the achievement. example: 10 achievementName: type: string description: The name of the achievement. example: FreeCoffee10Orders progressTrackerId: type: integer description: |- The internal ID of the customer progress tracker. For [on-completion achievements](https://docs.talon.one/docs/product/campaigns/achievements/achievements-overview#recurring-on-completion-achievements), this effect generates a unique ID for each iteration. delta: type: number description: The value by which the customer's current progress in the achievement has increased. value: type: number description: The current progress of the customer in the achievement. target: type: number description: The target value to complete the achievement. isJustCompleted: type: boolean description: Indicates if the customer has completed the achievement in the current session. RollbackIncreasedAchievementProgressEffectProps: type: object title: rollbackIncreasedAchievementProgress description: |- This effect indicates that the customer's progress in an achievement was rolled back. The Rule Engine triggers this effect when you cancel or [reopen a customer session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/reopenCustomerSession) that previously validated the [Update customer progress](https://docs.talon.one/docs/product/rules/effects/use-effects#update-customer-progress) effect and triggered the [increaseAchievementProgress](https://docs.talon.one/docs/dev/integration-api/api-effects#increaseachievementprogress) API effect. The effect is also triggered for completed achievements if the **Allow progress rollback for completed achievements** setting is enabled. You can enable this through the [Campaign Manager](https://docs.talon.one/docs/product/campaigns/achievements/manage-achievements) or the [Management API](https://docs.talon.one/management-api#tag/Achievements/operation/createAchievement) by setting the `achievementAllowRollbackAfterCompletion` property to `true`. This setting only applies to one-time and recurring on expiration achievements. example: achievementId: 10 achievementName: FreeCoffee10Orders progressTrackerId: 42 decreaseProgressBy: 1 currentProgress: 6 target: 10 required: - achievementId - achievementName - progressTrackerId - decreaseProgressBy - currentProgress - target properties: achievementId: type: integer description: The internal ID of the achievement. example: 10 achievementName: type: string description: The name of the achievement. example: FreeCoffee10Orders progressTrackerId: type: integer description: The internal ID of the achievement progress tracker. decreaseProgressBy: type: number description: The value by which the customer's current progress in the achievement has decreased. currentProgress: type: number description: The current progress of the customer in the achievement. target: type: number description: The target value to complete the achievement. LoyaltyLedgerEntryExpiryDateChange: type: object description: The properties specific to effects for changing the expiry dates of loyalty ledger entries. required: - transactionUUID - newExpiryDate properties: transactionUUID: type: string format: uuid description: The identifier of the transaction affected by the extension or update. previousExpiryDate: type: string format: date-time description: Expiry date of the transactions before applying the extension or update. newExpiryDate: type: string format: date-time description: Expiry date of the transaction after applying the extension or update. ExtendLoyaltyPointsExpiryDateEffectProps: type: object title: extendLoyaltyPointsExpiryDate description: | If loyalty points have an expiry date, this effect extends the expiry of all active and pending point transactions by a selected duration. example: programId: 5 subLedgerId: main extensionDuration: 12h affectedTransactions: [] required: - programId - subLedgerId - extensionDuration - previousExpirationDate properties: programId: type: integer description: ID of the loyalty program that contains these points. subLedgerId: type: string description: API name of the loyalty program subledger that contains these points. extensionDuration: type: string description: | Time frame by which the expiry date extends. The time format is either: - immediate, or - an **integer** followed by a letter indicating the time unit. Examples: `immediate`, `30s`, `40m`, `1h`, `5D`, `7W`, `10M`, `15Y`. Available units: - `s`: seconds - `m`: minutes - `h`: hours - `D`: days - `W`: weeks - `M`: months - `Y`: years You can round certain units up or down: - `_D` for rounding down days only. Signifies the start of the day. - `_U` for rounding up days, weeks, months and years. Signifies the end of the day, week, month or year. example: 12h affectedTransactions: type: array description: List of transactions affected by the expiry date update. items: $ref: '#/components/schemas/LoyaltyLedgerEntryExpiryDateChange' SetLoyaltyPointsExpiryDateEffectProps: type: object title: setLoyaltyPointsExpiryDate description: | This effect updates the expiry date of all active, pending, and unlimited point transactions to a specific date. example: programId: 5 subLedgerId: main newExpiryDate: 2024-07-24T14:15:22Z affectedTransactions: [] required: - programId - subLedgerId - newExpiryDate properties: programId: type: integer description: ID of the loyalty program that contains these points. subLedgerId: type: string description: API name of the loyalty program subledger that contains these points. newExpiryDate: type: string format: date-time description: The specified expiry date and time for all active and pending point transactions in the loyalty program subledger. example: 2024-07-24T14:15:22Z affectedTransactions: type: array description: List of transactions affected by the expiry date update. items: $ref: '#/components/schemas/LoyaltyLedgerEntryExpiryDateChange' Effect: allOf: - $ref: '#/components/schemas/EffectEntity' - type: object description: A generic effect that is fired by a triggered campaign. The props property will contain information specific to the specific effect type. required: - props properties: props: oneOf: - $ref: '#/components/schemas/AcceptCouponEffectProps' - $ref: '#/components/schemas/AcceptReferralEffectProps' - $ref: '#/components/schemas/RedeemReferralEffectProps' - $ref: '#/components/schemas/RejectCouponEffectProps' - $ref: '#/components/schemas/RejectReferralEffectProps' - $ref: '#/components/schemas/CouponCreatedEffectProps' - $ref: '#/components/schemas/ReferralCreatedEffectProps' - $ref: '#/components/schemas/SetDiscountEffectProps' - $ref: '#/components/schemas/SetDiscountPerItemEffectProps' - $ref: '#/components/schemas/SetDiscountPerAdditionalCostEffectProps' - $ref: '#/components/schemas/TriggerWebhookEffectProps' - $ref: '#/components/schemas/AddLoyaltyPointsEffectProps' - $ref: '#/components/schemas/DeductLoyaltyPointsEffectProps' - $ref: '#/components/schemas/ChangeLoyaltyTierLevelEffectProps' - $ref: '#/components/schemas/AddFreeItemEffectProps' - $ref: '#/components/schemas/ShowNotificationEffectProps' - $ref: '#/components/schemas/UpdateAttributeEffectProps' - $ref: '#/components/schemas/RollbackCouponEffectProps' - $ref: '#/components/schemas/RollbackReferralEffectProps' - $ref: '#/components/schemas/RollbackDiscountEffectProps' - $ref: '#/components/schemas/RollbackAddedLoyaltyPointsEffectProps' - $ref: '#/components/schemas/RollbackDeductedLoyaltyPointsEffectProps' - $ref: '#/components/schemas/ShowBundleMetadataEffectProps' - $ref: '#/components/schemas/AwardGiveawayEffectProps' - $ref: '#/components/schemas/WillAwardGiveawayEffectProps' - $ref: '#/components/schemas/ErrorEffectProps' - $ref: '#/components/schemas/CustomEffectProps' - $ref: '#/components/schemas/SetDiscountPerAdditionalCostPerItemEffectProps' - $ref: '#/components/schemas/ReserveCouponEffectProps' - $ref: '#/components/schemas/AddToAudienceEffectProps' - $ref: '#/components/schemas/RemoveFromAudienceEffectProps' - $ref: '#/components/schemas/IncreaseAchievementProgressEffectProps' - $ref: '#/components/schemas/RollbackIncreasedAchievementProgressEffectProps' - $ref: '#/components/schemas/ExtendLoyaltyPointsExpiryDateEffectProps' - $ref: '#/components/schemas/SetLoyaltyPointsExpiryDateEffectProps' IntegrationCustomerSessionResponse: type: object properties: customerSession: $ref: '#/components/schemas/CustomerSessionV2' effects: type: array description: | The returned effects. **Note:** This endpoint returns only the effects that are valid after any rollback effects and their corresponding non-rollback effects are removed. items: $ref: '#/components/schemas/Effect' ErrorSource: type: object description: | The source of the current error, exactly one of `pointer`, `parameter` or `line` will be defined. properties: pointer: type: string description: Pointer to the path in the payload that caused this error. parameter: type: string description: Query parameter that caused this error. line: type: string description: Line number in uploaded multipart file that caused this error. 'N/A' if unknown. resource: type: string description: Pointer to the resource that caused this error. APIError: type: object required: - source - title properties: title: type: string description: Short description of the problem. details: type: string description: Longer description of this specific instance of the problem. source: $ref: '#/components/schemas/ErrorSource' ErrorResponse: type: object required: - message properties: message: type: string description: A message describing the error. errors: type: array description: An array of individual problems encountered during the request. items: $ref: '#/components/schemas/APIError' ErrorResponseWithStatus: type: object properties: message: type: string errors: type: array description: An array of individual problems encountered during the request. items: $ref: '#/components/schemas/APIError' StatusCode: type: integer description: The error code IntegrationRequest: type: object description: The body of a V2 integration API request (customer session update). Next to the customer session details, this contains an optional listing of extra properties that should be returned in the response. required: - customerSession properties: customerSession: $ref: '#/components/schemas/NewCustomerSessionV2' description: The customer session update details. responseContent: type: array description: | Extends the response with the chosen data entities. Use this property to get as much data as you need in one _Update customer session_ request instead of sending extra requests to other endpoints. **Note:** To retrieve loyalty card details, your request must include a loyalty card ID. example: - customerSession - customerProfile items: type: string enum: - customerSession - customerProfile - coupons - triggeredCampaigns - referral - loyalty - event - awardedGiveaways - ruleFailureReasons - previousReturns - campaignEligibility - achievements CustomerProfileEntity: type: object required: - id - created properties: id: type: integer description: The internal ID of the customer profile. example: 6 created: type: string format: date-time description: The time the customer profile was created. example: 2020-06-10T09:05:27.993483Z NewCustomerProfile: type: object properties: attributes: type: object additionalProperties: true description: Arbitrary properties associated with this item. example: Language: english ShippingCountry: DE LoyaltyMembership: type: object required: - loyaltyProgramId properties: joined: type: string format: date-time title: Loyalty program joined at description: The moment in which the loyalty program was joined. example: 2012-03-20T14:15:22Z loyaltyProgramId: type: integer title: Loyalty program ID description: The ID of the loyalty program belonging to this entity. example: 323414846 AudienceMembership: type: object required: - id - name properties: id: type: integer title: Audience ID description: The ID of the audience belonging to this entity. example: 2 name: type: string title: Audience Name description: The Name of the audience belonging to this entity. example: Travel audience CustomerProfile: allOf: - $ref: '#/components/schemas/CustomerProfileEntity' - $ref: '#/components/schemas/IntegrationEntity' - $ref: '#/components/schemas/NewCustomerProfile' - type: object properties: accountId: type: integer title: Profile belongs to Account description: The ID of the Talon.One account that owns this profile. example: 31 closedSessions: type: integer title: Closed sessions description: The total number of closed sessions. Does not include closed sessions that have been cancelled or reopened. See the [docs](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions#customer-session-states). example: 3 totalSales: type: number description: | The total amount of money spent by the customer **before** discounts are applied. The total sales amount excludes the following: - Cancelled or reopened sessions. - Returned items. example: 299.99 title: Total Sales loyaltyMemberships: type: array deprecated: true description: | **DEPRECATED. Always returns `null`.** A list of loyalty programs joined by the customer. items: $ref: '#/components/schemas/LoyaltyMembership' title: Loyalty programed joined example: null audienceMemberships: type: array description: The audiences the customer belongs to. items: $ref: '#/components/schemas/AudienceMembership' title: Audience memberships lastActivity: type: string format: date-time title: Last activity description: | Timestamp of the most recent event received from this customer. This field is updated on calls that trigger the Rule Engine and that are not [dry requests](https://docs.talon.one/docs/dev/integration-api/dry-requests/#overlay). For example, [reserving a coupon](https://docs.talon.one/integration-api#tag/Coupons/operation/createCouponReservation) for a customer doesn't impact this field. example: 2020-02-08T14:15:20Z sandbox: type: boolean description: | An indicator of whether the customer is part of a sandbox or live Application. See the [docs](https://docs.talon.one/docs/product/applications/overview#application-environments). title: Sandbox example: false required: - accountId - closedSessions - totalSales - lastActivity - attributes LoyaltyProgramEntity: type: object required: - programID properties: programID: type: integer description: The ID of the loyalty program that owns this entity. example: 125 programName: type: string description: The integration name of the loyalty program that owns this entity. example: Loyalty_program programTitle: type: string description: The Campaign Manager-displayed name of the loyalty program that owns this entity. example: Loyalty program UpdateLoyaltyCard: type: object required: - status properties: status: type: string description: | Status of the loyalty card. Can be `active` or `inactive`. example: active blockReason: type: string description: | Reason for transferring and blocking the loyalty card. example: Current card lost. Customer needs a new card. LoyaltyCardProfileRegistration: type: object required: - integrationId - timestamp properties: integrationId: type: string maxLength: 1000 description: Integration ID of the customer profile linked to the card. example: R195412 timestamp: type: string format: date-time description: Timestamp the customer profile was linked to the card. example: 2021-09-12T10:12:42Z LoyaltyProgramBalance: type: object required: - currentBalance - pendingBalance - expiredBalance - spentBalance - tentativeCurrentBalance description: The balance in a Loyalty Program for some Customer. properties: currentBalance: type: number title: Current balance description: Sum of currently active points. example: 100 pendingBalance: type: number title: Pending balance description: Sum of pending points. example: 10 negativeBalance: type: number title: Negative balance description: Sum of negative points. This implies that `currentBalance` is `0`. example: 10 expiredBalance: type: number deprecated: true title: Expired balance description: | **DEPRECATED** Value is shown as 0. example: 0 spentBalance: type: number deprecated: true title: Spent balance description: | **DEPRECATED** Value is shown as 0. example: 0 tentativeCurrentBalance: type: number title: Tentative current balance description: | The tentative points balance, reflecting the `currentBalance` and all point additions and deductions within the current open customer session. When the session is closed, the effects are applied and the `currentBalance` is updated to this value. **Note:** Tentative balances are specific to the current session and do not take into account other open sessions for the given customer. example: 100 tentativePendingBalance: type: number title: Tentative pending balance description: | The tentative points balance, reflecting the `pendingBalance` and all point additions with a future activation date within the current open customer session. When the session is closed, the effects are applied and the `pendingBalance` is updated to this value. **Note:** Tentative balances are specific to the current session and do not take into account other open sessions for the given customer. example: 20 tentativeNegativeBalance: type: number title: Tentative negative balance description: | The tentative negative balance after all additions and deductions from the current customer session are applied to `negativeBalance`. When the session is closed, the tentative effects are applied and `negativeBalance` is updated to this value. **Note:** Tentative balances are specific to the current session and do not take into account other open sessions for the given customer. example: 100 Tier: type: object required: - id - name properties: id: type: integer description: The internal ID of the tier. example: 11 name: type: string description: The name of the tier. example: bronze startDate: type: string format: date-time description: Date and time when the customer moved to this tier. This value uses the loyalty program's time zone setting. example: 2021-05-03T12:32:00Z07:00 expiryDate: type: string format: date-time description: Date when tier level expires in the RFC3339 format (in the Loyalty Program's timezone). example: 2022-08-02T15:04:05Z07:00 downgradePolicy: type: string enum: - one_down - balance_based description: | The policy that defines how customer tiers are downgraded in the loyalty program after tier reevaluation. - `one_down`: If the customer doesn't have enough points to stay in the current tier, they are downgraded by one tier. - `balance_based`: The customer's tier is reevaluated based on the amount of active points they have at the moment. LedgerInfo: allOf: - $ref: '#/components/schemas/LoyaltyProgramBalance' - type: object properties: currentTier: $ref: '#/components/schemas/Tier' description: Tier for which the ledger is eligible. example: bronze pointsToNextTier: type: number description: Points required to move up a tier. example: 20 nextTierName: type: string description: | The name of the next higher tier level in the loyalty program. **Note**: - Returns `null` if the customer has reached the highest available tier. - Returns the lowest level tier name if the customer is not currently assigned to any tier. example: Silver LoyaltyCard: allOf: - $ref: '#/components/schemas/Entity' - $ref: '#/components/schemas/LoyaltyProgramEntity' - $ref: '#/components/schemas/UpdateLoyaltyCard' - type: object required: - identifier - usersPerCardLimit properties: identifier: $ref: '#/components/schemas/LoyaltyCardIdentifier' usersPerCardLimit: type: integer minimum: 0 example: 111 description: | The max amount of customer profiles that can be linked to the card. 0 means unlimited. profiles: type: array description: Integration IDs of the customers profiles linked to the card. items: $ref: '#/components/schemas/LoyaltyCardProfileRegistration' ledger: $ref: '#/components/schemas/LedgerInfo' description: Displays point balances of the card in the main ledger of the loyalty program. subledgers: type: object description: Displays point balances of the card in the subledgers of the loyalty program. additionalProperties: $ref: '#/components/schemas/LedgerInfo' modified: type: string format: date-time description: Timestamp of the most recent update of the loyalty card. example: 2021-09-12T10:12:42Z oldCardIdentifier: $ref: '#/components/schemas/LoyaltyCardIdentifier' description: The identifier of the card from which the points were transferred. example: summer-loyalty-card-0543 newCardIdentifier: $ref: '#/components/schemas/LoyaltyCardIdentifier' description: The identifier of the card to which the points were transferred. example: autumn-loyalty-card-5822 batchId: description: The ID of the batch in which the loyalty card was created. type: string example: wdefpov LoyaltyProgramLedgers: type: object description: Customer-specific information about loyalty points. required: - ledger - title - name - id properties: id: type: integer description: The internal ID of loyalty program. example: 5 title: description: Visible name of loyalty program. type: string example: My loyalty program name: description: Internal name of loyalty program. type: string example: program1 joinDate: description: | The date on which the customer joined the loyalty program in RFC3339. **Note**: This is in the loyalty program's time zone. type: string format: date-time example: 2024-04-30T15:04:05Z07:00 ledger: $ref: '#/components/schemas/LedgerInfo' title: Customer's current loyalty program status description: Information about the main ledger in the loyalty program. subLedgers: type: object description: A map containing information about each loyalty subledger. additionalProperties: $ref: '#/components/schemas/LedgerInfo' Loyalty: type: object description: Customer-specific information about loyalty points. required: - programs properties: cards: title: Point balances of the loyalty cards used. description: Displays information about the balances of the loyalty cards. type: array items: $ref: '#/components/schemas/LoyaltyCard' programs: type: object title: Customer's current loyalty program balance. description: Displays information about point balances in profile-based programs. additionalProperties: $ref: '#/components/schemas/LoyaltyProgramLedgers' EntityWithTalangVisibleID: type: object required: - id - created properties: id: type: integer description: Unique ID for this entity. example: 4 created: type: string format: date-time description: The exact moment this entity was created. example: 2020-06-10T09:05:27.993483Z UserEntity: type: object required: - userId properties: userId: type: integer description: The ID of the user associated with this entity. example: 388 CodeGeneratorSettings: type: object properties: validCharacters: type: array description: | List of characters used to generate the random parts of a code. example: - A - B - C - D - E - F - G - H - I - J - K - L - M - N - O - P - Q - R - S - T - U - V - W - X - Y - Z - '0' - '1' - '2' - '3' - '4' - '5' - '6' - '7' - '8' - '9' items: type: string couponPattern: type: string description: | The pattern used to generate codes, such as coupon codes, referral codes, and loyalty cards. The character `#` is a placeholder and is replaced by a random character from the `validCharacters` set. maxLength: 100 minLength: 3 pattern: ^[A-Za-z0-9._%+@#-]+$ example: SUMMER-####-#### additionalProperties: false required: - couponPattern - validCharacters LimitConfig: type: object required: - action - limit - entities properties: action: type: string description: | The limitable action to which this limit applies. For example: - `setDiscount` - `setDiscountEffect` - `redeemCoupon` - `createCoupon` example: createCoupon limit: type: number minimum: 0 example: 1000 description: The value to set for the limit. period: description: The period on which the budget limit recurs. type: string enum: - daily - weekly - monthly - yearly example: yearly entities: type: array description: The entity that this limit applies to. example: - Coupon items: type: string enum: - Coupon - Referral - Profile - Identifier - Store - Session BaseCampaign: type: object properties: name: type: string title: Campaign Name description: A user-facing name for this campaign. minLength: 1 example: Summer promotions description: type: string title: Campaign Description description: A detailed description of the campaign. example: Campaign for all summer 2021 promotions startTime: type: string format: date-time description: Timestamp when the campaign will become active. example: 2021-07-20T22:00:00Z endTime: type: string format: date-time description: Timestamp when the campaign will become inactive. example: 2021-09-22T22:00:00Z attributes: type: object description: Arbitrary properties associated with this campaign. state: type: string enum: - enabled - disabled - archived default: enabled example: enabled description: | A disabled or archived campaign is not evaluated for rules or coupons. activeRulesetId: type: integer description: | [ID of Ruleset](https://docs.talon.one/management-api#tag/Campaigns/operation/getRulesets) this campaign applies on customer session evaluation. example: 6 tags: type: array description: A list of tags for the campaign. example: - summer maxItems: 50 items: type: string minLength: 1 maxLength: 50 reevaluateOnReturn: type: boolean title: Reevaluate on return description: Indicates whether this campaign should be reevaluated when a customer returns an item. example: true features: type: array description: The features enabled in this campaign. example: - coupons - referrals items: type: string enum: - coupons - referrals - loyalty - giveaways - strikethrough - achievements - advancedEvents couponSettings: $ref: '#/components/schemas/CodeGeneratorSettings' referralSettings: $ref: '#/components/schemas/CodeGeneratorSettings' limits: type: array description: | The set of [budget limits](https://docs.talon.one/docs/product/campaigns/settings/managing-campaign-budgets) for this campaign. items: $ref: '#/components/schemas/LimitConfig' campaignGroups: type: array description: | The IDs of the [campaign groups](https://docs.talon.one/docs/product/account/managing-campaign-groups) this campaign belongs to. example: - 1 - 3 items: type: integer type: type: string title: Type enum: - cartItem - advanced default: advanced example: advanced description: | The campaign type. Possible type values: - `cartItem`: Type of campaign that can apply effects only to cart items. - `advanced`: Type of campaign that can apply effects to customer sessions and cart items. linkedStoreIds: type: array description: | A list of store IDs that you want to link to the campaign. **Note:** Campaigns with linked store IDs will only be evaluated when there is a [customer session update](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2) that references a linked store. items: type: integer example: - 1 - 2 - 3 couponAttributes: type: object description: Arbitrary properties associated with coupons in this campaign. required: - name - state - tags - limits - features CampaignBudget: type: object required: - action - limit - counter properties: action: type: string description: | The limitable action to which this limit applies. For example: - `setDiscount` - `setDiscountEffect` - `redeemCoupon` - `createCoupon` example: createCoupon limit: type: number minimum: 0 example: 1000 description: The value to set for the limit. counter: type: number minimum: 0 example: 42 description: The number of occurrences of the limited action in the context of the campaign. AdditionalCampaignProperties: type: object properties: budgets: type: array items: $ref: '#/components/schemas/CampaignBudget' description: | A list of all the budgets that are defined by this campaign and their usage. **Note:** Budgets that are not defined do not appear in this list and their usage is not counted until they are defined. couponRedemptionCount: type: integer deprecated: true description: | This property is **deprecated**. The count should be available under *budgets* property. Number of coupons redeemed in the campaign. example: 163 referralRedemptionCount: type: integer deprecated: true description: | This property is **deprecated**. The count should be available under *budgets* property. Number of referral codes redeemed in the campaign. example: 3 discountCount: type: number deprecated: true description: | This property is **deprecated**. The count should be available under *budgets* property. Total amount of discounts redeemed in the campaign. example: 288 discountEffectCount: type: integer deprecated: true description: | This property is **deprecated**. The count should be available under *budgets* property. Total number of times discounts were redeemed in this campaign. example: 343 couponCreationCount: type: integer deprecated: true description: | This property is **deprecated**. The count should be available under *budgets* property. Total number of coupons created by rules in this campaign. example: 16 customEffectCount: type: integer deprecated: true description: | This property is **deprecated**. The count should be available under *budgets* property. Total number of custom effects triggered by rules in this campaign. example: 0 referralCreationCount: type: integer deprecated: true description: | This property is **deprecated**. The count should be available under *budgets* property. Total number of referrals created by rules in this campaign. example: 8 addFreeItemEffectCount: type: integer deprecated: true description: | This property is **deprecated**. The count should be available under *budgets* property. Total number of times the [add free item effect](https://docs.talon.one/docs/dev/integration-api/api-effects#addfreeitem) can be triggered in this campaign. example: 0 awardedGiveawaysCount: type: integer deprecated: true description: | This property is **deprecated**. The count should be available under *budgets* property. Total number of giveaways awarded by rules in this campaign. example: 9 createdLoyaltyPointsCount: type: number deprecated: true description: | This property is **deprecated**. The count should be available under *budgets* property. Total number of loyalty points created by rules in this campaign. example: 9 createdLoyaltyPointsEffectCount: type: integer deprecated: true description: | This property is **deprecated**. The count should be available under *budgets* property. Total number of loyalty point creation effects triggered by rules in this campaign. example: 2 redeemedLoyaltyPointsCount: type: number deprecated: true description: | This property is **deprecated**. The count should be available under *budgets* property. Total number of loyalty points redeemed by rules in this campaign. example: 8 redeemedLoyaltyPointsEffectCount: type: integer deprecated: true description: | This property is **deprecated**. The count should be available under *budgets* property. Total number of loyalty point redemption effects triggered by rules in this campaign. example: 9 callApiEffectCount: type: integer deprecated: true description: | This property is **deprecated**. The count should be available under *budgets* property. Total number of webhooks triggered by rules in this campaign. example: 0 reservecouponEffectCount: type: integer deprecated: true description: | This property is **deprecated**. The count should be available under *budgets* property. Total number of reserve coupon effects triggered by rules in this campaign. example: 9 lastActivity: type: string format: date-time example: 2022-11-10T23:00:00Z description: Timestamp of the most recent event received by this campaign. updated: type: string format: date-time example: 2022-10-97T35:00:00Z description: | Timestamp of the most recent update to the campaign's property. Updates to external entities used in this campaign are **not** registered by this property, such as collection or coupon updates. createdBy: type: string description: Name of the user who created this campaign if available. example: John Doe updatedBy: type: string description: Name of the user who last updated this campaign if available. example: Jane Doe templateId: type: integer description: The ID of the Campaign Template this Campaign was created from. example: 3 frontendState: type: string description: The campaign state displayed in the Campaign Manager. enum: - expired - scheduled - running - disabled - archived - staged example: running storesImported: type: boolean description: Indicates whether the linked stores were imported via a CSV file. example: true valueMapsIds: type: array description: A list of value map IDs for the campaign. items: type: integer example: - 100 - 215 experimentId: type: integer description: The ID of the Experiment this Campaign is part of. example: 1 required: - state - description - type - frontendState - storesImported CampaignVersions: type: object properties: revisionFrontendState: type: string description: The campaign revision state displayed in the Campaign Manager. enum: - revised - pending example: revised activeRevisionId: type: integer description: | ID of the revision that was last activated on this campaign. example: 6 activeRevisionVersionId: type: integer description: | ID of the revision version that is active on the campaign. example: 6 version: type: integer description: | Incrementing number representing how many revisions have been activated on this campaign, starts from 0 for a new campaign. example: 6 currentRevisionId: type: integer description: | ID of the revision currently being modified for the campaign. example: 6 currentRevisionVersionId: type: integer description: | ID of the latest version applied on the current revision. example: 6 stageRevision: type: boolean description: | Flag for determining whether we use current revision when sending requests with staging API key. example: false default: false Campaign: allOf: - $ref: '#/components/schemas/EntityWithTalangVisibleID' - $ref: '#/components/schemas/ApplicationEntity' - $ref: '#/components/schemas/UserEntity' - $ref: '#/components/schemas/BaseCampaign' - $ref: '#/components/schemas/AdditionalCampaignProperties' - $ref: '#/components/schemas/CampaignVersions' - type: object required: - reevaluateOnReturn IntegrationCampaignBase: allOf: - $ref: '#/components/schemas/ApplicationEntity' - type: object required: - id - name - state - tags - features properties: id: type: integer description: Unique ID of Campaign. example: 4 name: type: string title: Campaign Name description: The name of the campaign. minLength: 1 example: Summer promotions description: type: string title: Campaign Description description: A detailed description of the campaign. example: Campaign for all summer 2021 promotions startTime: type: string format: date-time description: Timestamp when the campaign will become active. example: 2021-07-20T22:00:00Z endTime: type: string format: date-time description: Timestamp when the campaign will become inactive. example: 2021-09-22T22:00:00Z attributes: type: object description: Arbitrary properties associated with this campaign. state: type: string enum: - enabled default: enabled example: enabled description: | The state of the campaign. tags: type: array description: A list of tags for the campaign. example: - summer maxItems: 50 items: type: string minLength: 1 maxLength: 50 features: type: array description: The features enabled in this campaign. example: - coupons - referrals items: type: string enum: - coupons - referrals - loyalty - giveaways - strikethrough - achievements CampaignEligibilityFailureDetails: type: object description: The details about why the customer was not eligible for the campaign in the current session. required: - failureCode properties: failureCode: type: string description: A code identifying why the customer was not eligible for the campaign. enum: - ALL_RULES_FAILED - SKIPPED - AUDIENCE_NOT_MATCHED CampaignEligibilityDetails: type: object required: - passed properties: passed: type: boolean description: Indicates whether the customer was eligible for the campaign in the current session. couponCode: type: string description: The coupon code used to check a customer's eligibility for the campaign in the current session, if applicable. details: $ref: '#/components/schemas/CampaignEligibilityFailureDetails' description: The details about why the customer was not eligible for the campaign in the current session. Only returned when `passed` is `false`. RuleMetadata: type: object required: - title properties: title: type: string description: A short description of the rule. example: Give discount via coupon displayName: type: string description: A customer-facing name for the rule. example: 20% off all shoes! displayDescription: type: string description: | A customer-facing description that explains the details of the rule. For example, this property can contain details about eligibility requirements, reward timelines, or terms and conditions. example: Get a 20% discount on all shoes during Thanksgiving! Offer valid till Dec 5 only. relatedData: type: string description: | Any additional data associated with the rule, such as an image URL, vendor name, or a content management system (CMS) ID. example: https://example.com/discounts/20-off-shoes.png RuleEligibilityFailureDetails: type: object description: The details about why the customer was not eligible for the rule in the current session. required: - failureCode - details properties: failureCode: type: string description: A code identifying why the customer was not eligible for the rule in the current session. enum: - CONDITION_NOT_MET - EFFECT_FAILED couponID: type: integer description: | The ID of the coupon that was being evaluated when the rule failed. example: 4928 couponValue: type: string description: | The coupon code that was being evaluated when the rule failed. referralID: type: integer description: | The ID of the referral that was being evaluated when the rule failed. referralValue: type: string description: | The referral code that was being evaluated when the rule failed. conditionIndex: type: integer description: The index of the condition that caused the rule to fail. effectIndex: type: integer description: The index of the effect that caused the rule to fail. details: type: string description: Additional details about the failure. RuleEligibility: type: object description: The customer's eligibility for a rule in the current session, based on whether all of the rule's conditions were met. required: - passed properties: passed: type: boolean description: Indicates whether the customer was eligible for the rule in the current session, based on whether all of the rule's conditions were met. example: true couponCode: type: string description: The coupon code used to check a customer's eligibility for the rule in the current session, if applicable. details: $ref: '#/components/schemas/RuleEligibilityFailureDetails' description: The details about why the customer was not eligible for the rule in the current session. Only returned when `passed` is `false`. RuleMetadataEligibility: allOf: - $ref: '#/components/schemas/RuleMetadata' - type: object required: - eligibility properties: eligibility: type: array items: $ref: '#/components/schemas/RuleEligibility' CampaignEligibilityExperiment: type: object description: | The identifiers for the [experiment](https://docs.talon.one/management-api#tag/Experiments) and the variant assigned to the customer profile. Only returned when the customer profile has been assigned to a variant in an experiment campaign. required: - id - variantId properties: id: type: integer format: int64 description: The ID of the experiment. variantId: type: integer format: int64 description: The ID of the variant assigned to the customer profile. CampaignEligibility: allOf: - $ref: '#/components/schemas/IntegrationCampaignBase' - type: object description: | A list of campaigns and their evaluation status for the current customer session. For experiment campaigns, the experiment and variant assigned to the customer profile are returned through the `experiment` field. Customer profiles with no variant assignment are not included. **Note**: - This response can **only** be included if the `dry` parameter in the query is set to `true`. - Do not include `triggeredCampaigns` or `ruleFailureReasons` in `responseContent` to avoid duplicate results. required: - eligibility - rules properties: eligibility: type: array description: The customer's eligibility for each campaign in the current customer session. items: $ref: '#/components/schemas/CampaignEligibilityDetails' rules: type: array description: A list of rules containing customer-facing details of the rewards defined in the campaign. items: $ref: '#/components/schemas/RuleMetadataEligibility' experiment: $ref: '#/components/schemas/CampaignEligibilityExperiment' RuleFailureReason: type: object description: Details about why a rule failed. required: - campaignID - campaignName - rulesetID - ruleIndex - ruleName properties: campaignID: type: integer description: The ID of the campaign that contains the rule that failed. campaignName: type: string description: The name of the campaign that contains the rule that failed. rulesetID: type: integer description: The ID of the ruleset that contains the rule that failed. couponID: type: integer description: The ID of the coupon that was being evaluated at the time of the rule failure. example: 4928 couponValue: type: string description: The code of the coupon that was being evaluated at the time of the rule failure. referralID: type: integer description: The ID of the referral that was being evaluated at the time of the rule failure. referralValue: type: string description: The code of the referral that was being evaluated at the time of the rule failure. ruleIndex: type: integer description: The index of the rule that failed within the ruleset. ruleName: type: string description: The name of the rule that failed within the ruleset. conditionIndex: type: integer description: The index of the condition that failed. effectIndex: type: integer description: The index of the effect that failed. details: type: string description: More details about the failure. evaluationGroupID: type: integer example: 3 description: The ID of the evaluation group. For more information, see [Managing campaign evaluation](https://docs.talon.one/docs/product/applications/managing-campaign-evaluation). evaluationGroupMode: type: string example: stackable description: The evaluation mode of the evaluation group. For more information, see [Managing campaign evaluation](https://docs.talon.one/docs/product/applications/managing-campaign- CouponEntity: type: object required: - id - created properties: id: type: integer description: The internal ID of the coupon. example: 6 created: type: string format: date-time description: The time the coupon was created. example: 2020-06-10T09:05:27.993483Z CampaignEntity: type: object required: - campaignId properties: campaignId: type: integer title: Campaign ID description: The ID of the campaign that owns this entity. example: 211 CouponValue: type: object properties: value: type: string title: Coupon Code description: The coupon code. minLength: 4 example: XMAS-20-2021 CouponConstraints: type: object properties: usageLimit: type: integer minimum: 0 maximum: 999999 example: 100 description: | The number of times the coupon code can be redeemed. `0` means unlimited redemptions but any campaign usage limits will still apply. discountLimit: type: number minimum: 0 maximum: 1000000000000000 example: 30 description: | The total discount value that the code can give. Typically used to represent a gift card value. reservationLimit: type: integer minimum: 0 maximum: 999999 example: 45 description: | The number of reservations that can be made with this coupon code. startDate: type: string format: date-time example: 2020-01-24T14:15:22Z description: Timestamp at which point the coupon becomes valid. expiryDate: type: string format: date-time example: 2023-08-24T14:15:22Z description: Expiration date of the coupon. Coupon never expires if this is omitted. CouponLimitConfigs: type: object properties: limits: type: array description: | Limits configuration for a coupon. These limits will override the limits set from the campaign. **Note:** Only usable when creating a single coupon which is not tied to a specific recipient. Only per-profile limits are allowed to be configured. items: $ref: '#/components/schemas/LimitConfig' Coupon: allOf: - $ref: '#/components/schemas/CouponEntity' - $ref: '#/components/schemas/CampaignEntity' - $ref: '#/components/schemas/CouponValue' - $ref: '#/components/schemas/CouponConstraints' - $ref: '#/components/schemas/CouponLimitConfigs' - type: object required: - value - usageCounter - usageLimit properties: usageCounter: type: integer title: Total coupon redemptions example: 10 description: The number of times the coupon has been successfully redeemed. discountCounter: type: number title: Discounts Given description: The amount of discounts given on rules redeeming this coupon. Only usable if a coupon discount budget was set for this coupon. example: 10 discountRemainder: type: number title: Coupon Discount Remainder description: The remaining discount this coupon can give. example: 5 reservationCounter: type: number title: Number of reservations description: The number of times this coupon has been reserved. example: 1 attributes: type: object title: Attributes of coupon description: Custom attributes associated with this coupon. referralId: type: integer title: Advocate ID description: The integration ID of the referring customer (if any) for whom this coupon was created as an effect. example: 326632952 recipientIntegrationId: title: Recipient ID example: URNGV8294NV type: string maxLength: 1000 description: The Integration ID of the customer that is allowed to redeem this coupon. importId: title: Import ID type: integer description: The ID of the Import which created this coupon. example: 4 reservation: title: Reservation Type type: boolean example: false description: | Defines the reservation type: - `true`: The coupon can be reserved for multiple customers. - `false`: The coupon can be reserved only for one customer. It is a personal code. default: true batchId: title: Batch ID type: string description: The id of the batch the coupon belongs to. example: 32535-43255 isReservationMandatory: title: Is reservation mandatory type: boolean example: false description: An indication of whether the code can be redeemed only if it has been reserved first. default: false implicitlyReserved: title: Is coupon implicitly reserved for all customers description: An indication of whether the coupon is implicitly reserved for all customers. type: boolean example: false ReferralConstraints: type: object properties: startDate: type: string format: date-time title: Referral code valid from description: Timestamp at which point the referral code becomes valid. example: 2020-11-10T23:00:00Z expiryDate: type: string format: date-time title: Referral code valid until description: Expiration date of the referral code. Referral never expires if this is omitted. example: 2021-11-10T23:00:00Z usageLimit: type: integer title: Referral code Usage Limit description: | The number of times a referral code can be used. `0` means no limit but any campaign usage limits will still apply. minimum: 0 maximum: 999999 example: 1 NewReferral: allOf: - $ref: '#/components/schemas/ReferralConstraints' - type: object required: - campaignId - advocateProfileIntegrationId properties: campaignId: type: integer title: Referral's Campaign ID description: ID of the campaign from which the referral received the referral code. example: 78 advocateProfileIntegrationId: type: string title: Advocate's Profile ID description: The Integration ID of the Advocate's Profile. maxLength: 1000 example: URNGV8294NV friendProfileIntegrationId: type: string title: Friend's Profile ID description: An optional Integration ID of the Friend's Profile. example: BZGGC2454PA attributes: type: object description: Arbitrary properties associated with this item. example: channel: web ImportEntity: type: object properties: importId: type: integer description: The ID of the Import which created this referral. example: 4 Referral: allOf: - $ref: '#/components/schemas/Entity' - $ref: '#/components/schemas/NewReferral' - $ref: '#/components/schemas/ImportEntity' - type: object required: - code - usageCounter - usageLimit properties: code: type: string title: Referral code description: The referral code. minLength: 4 example: 27G47Y54VH9L usageCounter: type: integer title: Referral code Usages description: The number of times this referral code has been successfully used. example: 1 batchId: type: string title: Batch ID description: The ID of the batch the referrals belong to. example: tqyrgahe Giveaway: allOf: - $ref: '#/components/schemas/Entity' - type: object required: - id - created - code - poolId properties: code: type: string description: The code value of this giveaway. example: GIVEAWAY1 poolId: type: integer description: The ID of the pool to return giveaway codes from. example: 1 startDate: format: date-time description: Timestamp at which point the giveaway becomes valid. type: string example: 2022-01-02T15:04:05Z07:00 endDate: format: date-time description: Timestamp at which point the giveaway becomes invalid. type: string example: 2023-01-02T15:04:05Z07:00 attributes: type: object description: Arbitrary properties associated with this giveaway. used: type: boolean description: Indicates whether this giveaway code was given before. example: true importId: type: integer description: The ID of the Import which created this giveaway. example: 4 profileIntegrationId: type: string description: The third-party integration ID of the customer profile that was awarded the giveaway, if the giveaway was awarded. example: R195412 profileId: type: integer description: The internal ID of the customer profile that was awarded the giveaway, if the giveaway was awarded and an internal ID exists. example: 1 AchievementProgress: type: object description: The current progress of the customer in the achievement. required: - status - progress properties: status: type: string enum: - inprogress - completed - expired - not_started example: completed description: The status of the achievement. progress: type: number example: 10 description: The current progress of the customer in the achievement. startDate: format: date-time description: Timestamp at which the customer started the achievement. type: string example: 2024-01-01T15:04:05Z07:00 completionDate: format: date-time description: Timestamp at which point the customer completed the achievement. type: string example: 2024-01-15T15:04:05Z07:00 endDate: format: date-time description: Timestamp at which point the achievement ends and resets for the customer. type: string example: 2024-02-01T15:04:05Z07:00 CustomerAchievement: type: object description: A customer's progress in an achievement, together with the achievement definition. required: - id - name - title - target - description - recurrencePolicy - activationPolicy - isCappedByTarget - allowRollbackAfterCompletion properties: id: type: integer example: 3 description: The internal ID of the achievement. name: type: string pattern: ^[a-zA-Z]\w+$ example: FreeCoffee10Orders maxLength: 1000 minLength: 1 description: | The internal name of the achievement used in API requests. title: type: string description: The display name of the achievement in the Campaign Manager. example: 50% off on 50th purchase. description: type: string format: string description: The description of the achievement in the Campaign Manager. example: 50% off for every 50th purchase in a year. target: type: number example: 10 description: The required number of actions or the transactional milestone to complete the achievement. recurrencePolicy: type: string enum: - no_recurrence - on_expiration - on_completion example: no_recurrence description: | The policy that determines if and how the achievement recurs. - `no_recurrence`: The achievement can be completed only once. - `on_expiration`: The achievement resets after it expires and becomes available again. - `on_completion`: When the customer progress status reaches `completed`, the achievement resets and becomes available again. activationPolicy: type: string enum: - user_action - fixed_schedule example: fixed_schedule description: | The policy that determines how the achievement starts, ends, or resets. - `user_action`: The achievement ends or resets relative to when the customer started the achievement. - `fixed_schedule`: The achievement starts, ends, or resets for all customers following a fixed schedule. fixedStartDate: type: string format: date-time example: 2024-01-15T15:04:05Z07:00 description: | The achievement's start date when `activationPolicy` is equal to `fixed_schedule`. **Note:** It is an RFC3339 timestamp string. endDate: type: string format: date-time example: 2024-02-15T15:04:05Z07:00 description: | The achievement's end date. If defined, customers cannot participate in the achievement after this date. **Note:** It is an RFC3339 timestamp string. allowRollbackAfterCompletion: type: boolean description: When `true`, customer progress can be rolled back in completed achievements. example: false currentProgress: $ref: '#/components/schemas/AchievementProgress' IntegrationResponse: type: object description: | Contains entities that might be valuable in Talon.One integrations. required: - effects - createdCoupons - createdReferrals properties: customerProfile: $ref: '#/components/schemas/CustomerProfile' description: The customer profile associated with the event. loyalty: $ref: '#/components/schemas/Loyalty' description: The loyalty program status of the customer. triggeredCampaigns: type: array description: The campaigns that were triggered as a result of processing the event. items: $ref: '#/components/schemas/Campaign' campaignEligibility: type: array description: | A list of campaigns and their evaluation status for the current customer session. **Note**: - This response can **only** be included if the `dry` parameter in the query is set to `true`. - Do not include `triggeredCampaigns` or `ruleFailureReasons` in `responseContent` to avoid duplicate results. items: $ref: '#/components/schemas/CampaignEligibility' effects: type: array description: The effects generated by the rules in your running campaigns. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects). items: $ref: '#/components/schemas/Effect' ruleFailureReasons: description: | The reasons why certain rules were not triggered during the event processing. type: array items: $ref: '#/components/schemas/RuleFailureReason' createdCoupons: type: array description: The coupons that were created during the event processing. items: $ref: '#/components/schemas/Coupon' createdReferrals: type: array description: The referrals that were created during the event processing. items: $ref: '#/components/schemas/Referral' awardedGiveaways: type: array description: The giveaways that were awarded during the event processing. items: $ref: '#/components/schemas/Giveaway' achievements: type: array description: The achievements progress of the customer. items: $ref: '#/components/schemas/CustomerAchievement' InventoryReferral: allOf: - $ref: '#/components/schemas/Referral' - type: object required: - referredCustomers properties: referredCustomers: type: array description: An array of referred customers. items: type: string IntegrationCoupon: allOf: - $ref: '#/components/schemas/Coupon' - type: object required: - profileRedemptionCount properties: profileRedemptionCount: type: integer title: Coupon redemptions for the profile description: The number of times the coupon was redeemed by the profile. example: 5 IntegrationEvent: allOf: - $ref: '#/components/schemas/IntegrationProfileEntity' - $ref: '#/components/schemas/IntegrationStoreEntity' - type: object properties: type: type: string title: Event Type description: The name of the event. Must be a [custom event](https://docs.talon.one/docs/dev/concepts/entities/events#custom-events), not a built-in event. minLength: 1 example: pageViewed attributes: type: object description: Arbitrary additional JSON data associated with the event. example: myAttribute: myValue required: - type - attributes EventV3Entity: type: object properties: integrationId: type: string description: | The unique ID of the event. Only one event with this ID can be registered. minLength: 1 example: 175KJPS947296 LedgerEntry: allOf: - $ref: '#/components/schemas/Entity' - $ref: '#/components/schemas/IntegrationProfileEntity' - type: object description: Entry in the point ledger. required: - eventId - accountId - profileId - loyaltyProgramId - amount - reason - expiryDate properties: accountId: type: integer description: The ID of the Talon.One account that owns this profile. loyaltyProgramId: type: integer description: ID of the ledger. example: 323414846 eventId: type: integer description: ID of the related event. example: 3 amount: type: integer description: Amount of loyalty points. example: 100 reason: type: string description: reason for awarding/deducting points. example: Customer appeasement. expiryDate: type: string format: date-time description: Expiration date of the points. example: 2022-04-26T11:02:38Z referenceId: type: integer description: The ID of the balancing ledgerEntry. CouponRejectionReason: description: Holds a reference to the campaign, the coupon and the reason for which that coupon was rejected. Should only be present when there is a 'rejectCoupon' effect. type: object required: - campaignId - couponId - reason properties: campaignId: type: integer example: 244 couponId: type: integer example: 4928 reason: type: string enum: - CouponNotFound - CouponPartOfNotRunningCampaign - CampaignLimitReached - ProfileLimitReached - CouponRecipientDoesNotMatch - CouponExpired - CouponStartDateInFuture - CouponRejectedByCondition - EffectCouldNotBeApplied - CouponPartOfNotTriggeredCampaign - CouponReservationRequired - ProfileRequired example: CouponNotFound ReferralRejectionReason: description: Holds a reference to the campaign, the referral and the reason for which that referral was rejected. Should only be present when there is a 'rejectReferral' effect. type: object required: - campaignId - referralId - reason properties: campaignId: type: integer referralId: type: integer reason: type: string enum: - ReferralNotFound - ReferralRecipientIdSameAsAdvocate - ReferralPartOfNotRunningCampaign - ReferralLimitReached - CampaignLimitReached - ProfileLimitReached - ReferralRecipientDoesNotMatch - ReferralExpired - ReferralStartDateInFuture - ReferralRejectedByCondition - EffectCouldNotBeApplied - ReferralPartOfNotTriggeredCampaign example: ReferralNotFound Meta: type: object properties: campaigns: description: Maps each evaluated campaign ID to a key-value list of that campaigns attributes. Campaigns without attributes will be omitted. type: object coupons: description: Maps the coupon value to a key-value list of that coupons attributes. type: object couponRejectionReason: $ref: '#/components/schemas/CouponRejectionReason' referralRejectionReason: $ref: '#/components/schemas/ReferralRejectionReason' warnings: description: Contains warnings about possible misuse. type: object Event: allOf: - $ref: '#/components/schemas/Entity' - $ref: '#/components/schemas/ApplicationEntity' - $ref: '#/components/schemas/IntegrationEvent' - $ref: '#/components/schemas/EventV3Entity' - type: object required: - effects properties: sessionId: type: string title: Session ID of Event description: The ID of the session that this event occurred in. example: 175KJPS947296 effects: type: array description: | An array of effects generated by the rules of the enabled campaigns of the Application. You decide how to apply them in your system. See the list of [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects). items: type: array items: {} ledgerEntries: type: array description: Ledger entries for the event. items: $ref: '#/components/schemas/LedgerEntry' meta: $ref: '#/components/schemas/Meta' EventV3Connections: type: object properties: connectedSessionId: type: string description: The ID of the session to reference. The session must be in `closed` state. Otherwise, the API call will fail. minLength: 1 example: 175KJPS947296 EventV3: allOf: - $ref: '#/components/schemas/EventV3Connections' - $ref: '#/components/schemas/Entity' - $ref: '#/components/schemas/ApplicationEntity' - $ref: '#/components/schemas/IntegrationEvent' - $ref: '#/components/schemas/EventV3Entity' - type: object required: - effects properties: effects: type: array description: | An array of effects generated by the rules of the enabled campaigns of the Application. You decide how to apply them in your system. See the list of [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects). items: type: array items: {} AccountEntity: type: object required: - accountId properties: accountId: type: integer description: The ID of the account that owns this entity. example: 3886 ReturnedCartItem: type: object properties: position: description: The index of the cart item in the provided customer session's `cartItems` property. type: integer example: 2 quantity: description: | Number of cart items to return. type: integer example: 1 sku: description: The SKU of the cart item in the provided customer session's `cartItems` property. type: string example: SKU1241028 minLength: 1 NewReturn: type: object required: - returnedCartItems properties: returnedCartItems: type: array description: List of cart items to be returned. items: $ref: '#/components/schemas/ReturnedCartItem' Return: allOf: - $ref: '#/components/schemas/Entity' - $ref: '#/components/schemas/ApplicationEntity' - $ref: '#/components/schemas/AccountEntity' - $ref: '#/components/schemas/NewReturn' - type: object required: - eventId - sessionId - sessionIntegrationId properties: eventId: title: Event ID type: integer description: The event ID of that was generated for this return. example: 123 sessionId: title: Session ID type: integer description: The internal ID of the session this return was requested on. example: 123 sessionIntegrationId: title: Session Integration ID type: string maxLength: 1000 description: The integration ID of the session this return was requested on. example: 0c0e0207-eb30-4e06-a56c-2b7c8a64953c profileId: title: Profile ID type: integer description: The internal ID of the profile this return was requested on. example: 123 profileIntegrationId: title: Profile Integration ID type: string maxLength: 1000 description: The integration ID of the profile this return was requested on. example: 0c0e0207-eb30-4e06-a56c-2b7c8a64953c createdBy: title: Created By type: integer description: ID of the user who requested this return. example: 123 IntegrationStateV2: allOf: - $ref: '#/components/schemas/IntegrationResponse' - type: object description: | Contains all entities that might interest Talon.One integrations. properties: referral: $ref: '#/components/schemas/InventoryReferral' description: The referral that was processed. coupons: type: array description: The coupons that were processed. items: $ref: '#/components/schemas/IntegrationCoupon' event: $ref: '#/components/schemas/Event' description: The event that was processed. advancedEvent: $ref: '#/components/schemas/EventV3' description: The advanced event that was processed. customerSession: $ref: '#/components/schemas/CustomerSessionV2' description: The session that was processed. return: $ref: '#/components/schemas/Return' description: The return that was processed. previousReturns: type: array description: The previous returns associated with the event. items: $ref: '#/components/schemas/Return' ReturnIntegrationRequest: type: object description: The body of a return integration API request. Next to the cart items details, this contains an optional listing of extra properties that should be returned in the response. required: - return properties: return: $ref: '#/components/schemas/NewReturn' description: The returned cart items details. responseContent: type: array description: | Extends the response with the chosen data entities. Use this property to get as much data as you need in one _Update customer session_ request instead of sending extra requests to other endpoints. example: - customerSession - customerProfile items: type: string enum: - customerSession - customerProfile - coupons - triggeredCampaigns - referral - loyalty - event - previousReturns ReopenSessionResponse: type: object description: | This is the response type returned by the Reopen customer sessions endpoint. It contains the rolled back effects. required: - effects properties: effects: type: array description: The effects generated by the rules in your running campaigns. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects). items: $ref: '#/components/schemas/Effect' ResponseContentObject: type: object properties: responseContent: type: array description: | Extends the response with the chosen data entities. Use this property to get as much data back as needed from one request instead of sending extra requests to other endpoints. example: - triggeredCampaigns - customerProfile items: type: string enum: - customerProfile - triggeredCampaigns - loyalty - event - awardedGiveaways - ruleFailureReasons - campaignEligibility - achievements ProfileAudiencesChanges: type: object required: - adds - deletes properties: adds: title: Audiences to join type: array items: type: integer description: The IDs of the audiences for the customer to join. example: - 2 - 4 deletes: title: Audiences to leave type: array items: type: integer description: The IDs of the audiences for the customer to leave. example: - 7 CustomerProfileIntegrationRequestV2: allOf: - $ref: '#/components/schemas/NewCustomerProfile' - $ref: '#/components/schemas/EvaluableCampaignIds' - $ref: '#/components/schemas/ResponseContentObject' - type: object description: The body of a V2 integration API request (customer profile update). Next to the customer profile details, this contains an optional listing of extra properties that should be returned in the response. properties: audiencesChanges: $ref: '#/components/schemas/ProfileAudiencesChanges' type: object description: Audiences memberships changes for this profile. CustomerProfileIntegrationResponseV2: type: object description: | This is the response type returned by the updateCustomerProfileV2 endpoint. required: - effects - createdCoupons - createdReferrals properties: customerProfile: $ref: '#/components/schemas/CustomerProfile' event: $ref: '#/components/schemas/Event' loyalty: $ref: '#/components/schemas/Loyalty' triggeredCampaigns: type: array items: $ref: '#/components/schemas/Campaign' ruleFailureReasons: type: array items: $ref: '#/components/schemas/RuleFailureReason' campaignEligibility: type: array items: $ref: '#/components/schemas/CampaignEligibility' awardedGiveaways: type: array items: $ref: '#/components/schemas/Giveaway' effects: type: array description: The effects generated by the rules in your running campaigns. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects). items: $ref: '#/components/schemas/Effect' createdCoupons: type: array items: $ref: '#/components/schemas/Coupon' createdReferrals: type: array items: $ref: '#/components/schemas/Referral' MultipleCustomerProfileIntegrationRequestItem: allOf: - $ref: '#/components/schemas/NewCustomerProfile' - type: object description: | The body of a V2 integration API request (customer profile update). Next to the customer profile details, this contains an optional listing of extra properties that should be returned in the response. required: - integrationId properties: integrationId: description: | The identifier of this profile, set by your integration layer. It must be unique within the account. To get the `integrationId` of the profile from a `sessionId`, use the [Update customer session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2). type: string example: R195412 maxLength: 1000 MultipleCustomerProfileIntegrationRequest: type: object properties: customerProfiles: type: array items: $ref: '#/components/schemas/MultipleCustomerProfileIntegrationRequestItem' CustomerProfileUpdateV2Response: type: object description: | Contains the updated customer profiles entities. This is the response type returned by the V2 PUT customer_profiles endpoint required: - customerProfile properties: customerProfile: $ref: '#/components/schemas/CustomerProfile' MultipleCustomerProfileIntegrationResponseV2: type: object properties: integrationStates: type: array items: $ref: '#/components/schemas/CustomerProfileUpdateV2Response' NewInternalAudience: type: object required: - name properties: name: type: string minLength: 1 description: The human-friendly display name for this audience. example: Travel audience sandbox: type: boolean description: Indicates if this is a live or sandbox Application. example: true description: type: string description: A description of the audience. example: Travel audience 18-27 subscribedApplicationsIds: type: array description: A list of the IDs of the Applications that are connected to this audience. uniqueItems: true items: type: integer example: - 3 - 13 NewAudience: allOf: - $ref: '#/components/schemas/NewInternalAudience' - type: object required: - name properties: integration: type: string description: | The Talon.One-supported [3rd-party platform](https://docs.talon.one/docs/dev/technology-partners/overview) that this audience was created in. For example, `mParticle`, `Segment`, `Shopify`, `Braze`, or `Iterable`. **Note:** If you do not integrate with any of these platforms, do not use this property. example: mparticle integrationId: type: string minLength: 1 maxLength: 1000 description: | The ID of this audience in the third-party integration. **Note:** To create an audience that doesn't come from a 3rd party platform, do not use this property. example: 382370BKDB946 createdIn3rdParty: type: boolean description: Determines if this audience is a 3rd party audience or not. example: false lastUpdate: type: string format: date-time description: The last time that the audience memberships changed. example: 2022-04-26T11:02:38Z Audience: allOf: - $ref: '#/components/schemas/AccountEntity' - $ref: '#/components/schemas/Entity' - $ref: '#/components/schemas/NewAudience' UpdateAudience: type: object required: - name properties: name: type: string minLength: 1 description: The human-friendly display name for this audience. example: Travel audience subscribedApplicationsIds: type: array description: A list of the IDs of the Applications that are connected to this audience. items: type: integer uniqueItems: true example: - 3 - 13 CustomerProfileAudienceRequestItem: type: object required: - action - profileIntegrationId - audienceId properties: action: type: string enum: - add - delete description: | Defines the action to perform: - `add`: Adds the customer profile to the audience. **Note**: If the customer profile does not exist, it will be created. The profile will not be visible in any Application until a session or profile update is received for that profile. - `delete`: Removes the customer profile from the audience. example: add profileIntegrationId: type: string description: The ID of this customer profile in the third-party integration. example: R195412 maxLength: 1000 audienceId: type: integer description: The ID of the audience. You get it via the `id` property when [creating an audience](#tag/Audiences/operation/createAudienceV2). example: 748 CustomerProfileAudienceRequest: type: object properties: data: type: array items: $ref: '#/components/schemas/CustomerProfileAudienceRequestItem' AttributeQuery: type: object description: Object representing a set of of attributes and their respective values. example: my_attribute_1: some value my_attribute_2: some other value my_attribute_3: some other value LoyaltyCardRegistration: type: object required: - integrationId properties: integrationId: type: string title: Customer Profile ID description: The integrationId of the customer profile. example: R195412 IntegrationCampaign: allOf: - $ref: '#/components/schemas/IntegrationCampaignBase' - type: object required: - rules properties: rules: type: array description: A list of rules containing customer-facing details of the rewards defined in the campaign. items: $ref: '#/components/schemas/RuleMetadata' linkedStoreIds: type: array description: A list of store IDs linked to this campaign. items: type: integer example: - 1 - 2 linkedAudienceIds: type: array description: A list of audience IDs linked to this campaign. items: type: integer example: - 3 - 4 InventoryCoupon: allOf: - $ref: '#/components/schemas/Coupon' - type: object required: - state - profileRedemptionCount properties: profileRedemptionCount: type: integer title: Number of coupon usages per profile description: The number of times the coupon was redeemed by the profile. example: 5 state: type: string example: active description: | Can be: - `active`: The coupon can be used. It is a reserved coupon that is not pending, used, or expired, and it has a non-exhausted limit counter. **Note:** This coupon state is returned for [scheduled campaigns](https://docs.talon.one/docs/product/campaigns/settings/managing-campaign-schedule), but the coupon cannot be used until the campaign is **running**. - `used`: The coupon has been redeemed and cannot be used again. It is not pending and has reached its redemption limit or was redeemed by the profile before expiration. - `expired`: The coupon was never redeemed, and it is now expired. It is non-pending, non-active, and non-used by the profile. - `pending`: The coupon will be usable in the future. - `disabled`: The coupon is part of a non-active campaign. EventAttributesEntity: type: object required: - type properties: type: type: string title: Event Type description: The name of the event. Must be a [custom event](https://docs.talon.one/docs/dev/concepts/entities/events#custom-events), not a built-in event. minLength: 1 example: pageViewed attributes: type: object description: Arbitrary additional JSON properties associated with the event. They must be created in the Campaign Manager before setting them with this property. See [creating custom attributes](https://docs.talon.one/docs/product/account/dev-tools/managing-attributes#creating-a-custom-attribute). example: myAttribute: myValue EventV2: allOf: - $ref: '#/components/schemas/IntegrationProfileEntity' - $ref: '#/components/schemas/IntegrationStoreEntity' - $ref: '#/components/schemas/EvaluableCampaignIds' - $ref: '#/components/schemas/EventAttributesEntity' IntegrationEventV2Request: allOf: - $ref: '#/components/schemas/EventV2' - $ref: '#/components/schemas/ResponseContentObject' - type: object properties: loyaltyCards: type: array maxItems: 1 items: type: string description: Identifiers of the loyalty cards used during this event. example: - loyalty-card-1 MutableEntity: type: object required: - modified properties: modified: type: string format: date-time description: The time this entity was last modified. example: 2021-09-12T10:12:42Z AudienceIntegrationID: type: object properties: integrationId: type: string minLength: 1 maxLength: 1000 description: The ID of this audience in the third-party integration. example: 382370BKDB946 IntegrationEventV2Response: allOf: - $ref: '#/components/schemas/IntegrationResponse' - type: object description: | This is the response type returned by the trackEventV2 endpoint. properties: event: $ref: '#/components/schemas/Event' description: The event that was processed. NewReferralsForMultipleAdvocates: allOf: - $ref: '#/components/schemas/ReferralConstraints' - type: object required: - campaignId - advocateProfileIntegrationIds - usageLimit properties: campaignId: type: integer title: Referral's Campaign ID description: The ID of the campaign from which the referral received the referral code. example: 45 advocateProfileIntegrationIds: type: array title: Advocate Profile List description: An array containing all the respective advocate profiles. example: - URNGV8294NV - DRPVV9476AF items: type: string maxItems: 1000 minItems: 1 attributes: type: object description: Arbitrary properties associated with this referral code. example: channel: web validCharacters: type: array description: | List of characters used to generate the random parts of a code. By default, the list of characters is equivalent to the `[A-Z, 0-9]` regular expression. example: - A - B - C - D - E - F - G - H - I - J - K - L - M - N - O - P - Q - R - S - T - U - V - W - X - Y - Z items: type: string referralPattern: type: string description: | The pattern used to generate referrals. The character `#` is a placeholder and is replaced by a random character from the `validCharacters` set. example: REF-###-### maxLength: 100 minLength: 3 CouponReservations: type: object required: - integrationIDs properties: integrationIDs: type: array description: List of customer integration IDs. example: - URNGV8294NV - BZGGC2454PA maxItems: 1000 items: type: string AchievementProgressWithDefinition: allOf: - $ref: '#/components/schemas/AchievementProgress' - type: object required: - achievementId - name - title - description - achievementRecurrencePolicy - achievementActivationPolicy - campaignId properties: achievementId: type: integer example: 3 description: The internal ID of the achievement. name: type: string pattern: ^[a-zA-Z]\w+$ example: FreeCoffee10Orders maxLength: 1000 minLength: 1 description: | The internal name of the achievement used in API requests. title: type: string description: The display name of the achievement in the Campaign Manager. example: 50% off on 50th purchase. description: type: string format: string description: The description of the achievement in the Campaign Manager. example: 50% off for every 50th purchase in a year. campaignId: type: integer description: The ID of the campaign the achievement belongs to. example: 3 target: type: number example: 10 description: The required number of actions or the transactional milestone to complete the achievement. achievementRecurrencePolicy: type: string enum: - no_recurrence - on_expiration - on_completion example: no_recurrence description: | The policy that determines if and how the achievement recurs. - `no_recurrence`: The achievement can be completed only once. - `on_expiration`: The achievement resets after it expires and becomes available again. - `on_completion`: When the customer progress status reaches `completed`, the achievement resets and becomes available again. achievementActivationPolicy: type: string enum: - user_action - fixed_schedule example: fixed_schedule description: | The policy that determines how the achievement starts, ends, or resets. - `user_action`: The achievement ends or resets relative to when the customer started the achievement. - `fixed_schedule`: The achievement starts, ends, or resets for all customers following a fixed schedule. achievementFixedStartDate: type: string format: date-time example: 2024-01-15T15:04:05Z07:00 description: | The achievement's start date when `achievementActivationPolicy` is equal to `fixed_schedule`. **Note:** It is an RFC3339 timestamp string. achievementEndDate: type: string format: date-time example: 2024-02-15T15:04:05Z07:00 description: | The achievement's end date. If defined, customers cannot participate in the achievement after this date. **Note:** It is an RFC3339 timestamp string. achievementAllowRollbackAfterCompletion: type: boolean description: When `true`, customer progress can be rolled back in completed achievements. example: false CustomerInventory: type: object properties: profile: $ref: '#/components/schemas/CustomerProfile' loyalty: $ref: '#/components/schemas/Loyalty' referrals: type: array items: $ref: '#/components/schemas/InventoryReferral' coupons: type: array description: | The coupons reserved by this profile. This array includes hard and soft reservations. items: $ref: '#/components/schemas/InventoryCoupon' giveaways: type: array items: $ref: '#/components/schemas/Giveaway' achievements: type: array items: $ref: '#/components/schemas/AchievementProgressWithDefinition' TimePoint: type: object required: - hour - minute - second description: | The absolute duration after which the achievement ends and resets for a particular customer profile. **Note**: The duration follows the time zone of the Application this achievement belongs to. properties: month: type: integer minimum: 1 maximum: 12 description: | The achievement ends and resets in this month. **Note**: Only applicable if the period is set to `Y`. example: 11 dayOfMonth: type: integer minimum: 1 maximum: 31 description: | The achievement ends and resets on this day of the month. **Note**: Only applicable if the period is set to `Y` or `M`. example: 23 dayOfWeek: type: integer minimum: 1 maximum: 7 description: | The achievement ends and resets on this day of the week. `1` represents `Monday` and `7` represents `Sunday`. **Note**: Only applicable if the period is set to `W`. hour: type: integer description: The achievement ends and resets at this hour. example: 23 minute: type: integer description: The achievement ends and resets at this minute. example: 59 second: type: integer description: The achievement ends and resets at this second. example: 59 example: month: 11 dayOfMonth: 23 hour: 23 minute: 59 second: 59 AchievementBase: type: object properties: name: type: string pattern: ^[a-zA-Z]\w+$ example: Order50Discount maxLength: 1000 minLength: 1 description: | The internal name of the achievement used in API requests. **Note**: The name should start with a letter. This cannot be changed after the achievement has been created. title: type: string description: The display name for the achievement in the Campaign Manager. example: 50% off on 50th purchase. description: type: string format: string description: A description of the achievement. example: 50% off for every 50th purchase in a year. target: type: number description: The required number of actions or the transactional milestone to complete the achievement. example: 50 period: type: string description: | The relative duration after which the achievement ends and resets for a particular customer profile. **Note**: The `period` does not start when the achievement is created. The period is a **positive real number** followed by one letter indicating the time unit. Examples: `30s`, `40m`, `1h`, `5D`, `7W`, `10M`, `15Y`. Available units: - `s`: seconds - `m`: minutes - `h`: hours - `D`: days - `W`: weeks - `M`: months - `Y`: years You can also round certain units down to the beginning of period and up to the end of period.: - `_D` for rounding down days only. Signifies the start of the day. Example: `30D_D` - `_U` for rounding up days, weeks, months and years. Signifies the end of the day, week, month or year. Example: `23W_U` **Note**: You can either use the round down and round up option or set an absolute period. example: 1Y periodEndOverride: $ref: '#/components/schemas/TimePoint' deprecated: true recurrencePolicy: type: string enum: - no_recurrence - on_expiration - on_completion example: no_recurrence description: | The policy that determines if and how the achievement recurs. - `no_recurrence`: The achievement can be completed only once. - `on_expiration`: The achievement resets after it expires and becomes available again. - `on_completion`: When the customer progress status reaches `completed`, the achievement resets and becomes available again. activationPolicy: type: string enum: - user_action - fixed_schedule example: fixed_schedule description: | The policy that determines how the achievement starts, ends, or resets. - `user_action`: The achievement ends or resets relative to when the customer started the achievement. - `fixed_schedule`: The achievement starts, ends, or resets for all customers following a fixed schedule. fixedStartDate: type: string format: date-time example: 2024-01-15T15:04:05Z07:00 description: | The achievement's start date when `activationPolicy` is set to `fixed_schedule`. **Note:** It must be an RFC3339 timestamp string. endDate: type: string format: date-time example: 2024-02-15T15:04:05Z07:00 description: | The achievement's end date. If defined, customers cannot participate in the achievement after this date. **Note:** It must be an RFC3339 timestamp string. allowRollbackAfterCompletion: type: boolean description: When `true`, customer progress can be rolled back in completed achievements. example: false CreateAchievement: allOf: - $ref: '#/components/schemas/AchievementBase' - type: object required: - name - title - description - target AchievementStatusEntry: allOf: - $ref: '#/components/schemas/Entity' - $ref: '#/components/schemas/CreateAchievement' - type: object properties: campaignId: type: integer description: The ID of the campaign the achievement belongs to. example: 1 status: type: string enum: - active - scheduled example: active description: The status of the achievement. currentProgress: $ref: '#/components/schemas/AchievementProgress' LoyaltyBalance: type: object description: Point balance of a ledger in the Loyalty Program. properties: activePoints: type: number title: Current Balance description: Total amount of points awarded to this customer and available to spend. example: 286 pendingPoints: type: number title: Total pending points description: Total amount of points awarded to this customer but not available until their start date. example: 50 spentPoints: type: number title: Total spent points description: Total amount of points already spent by this customer. example: 150 expiredPoints: type: number title: Total expired points description: Total amount of points awarded but never redeemed. They cannot be used anymore. example: 286 negativePoints: type: number title: Current negative balance description: Total amount of negative points. This implies that `activePoints` is `0`. example: 286 LoyaltyBalances: type: object description: List of loyalty balances for a ledger and its subledgers. properties: balance: $ref: '#/components/schemas/LoyaltyBalance' title: Loyalty points balance of a ledger subledgerBalances: type: object description: Map of the loyalty balances of the subledgers of a ledger. additionalProperties: $ref: '#/components/schemas/LoyaltyBalance' example: mysubledger: activePoints: 286 pendingPoints: 50 spentPoints: 150 expiredPoints: 25 negativePoints: 0 LoyaltyCardBalances: allOf: - $ref: '#/components/schemas/LoyaltyBalances' - type: object description: List of customer profiles linked to the loyalty card. properties: profiles: type: array description: Customer profiles linked to the loyalty card. items: $ref: '#/components/schemas/LoyaltyCardProfileRegistration' ProjectedTier: type: object required: - projectedActivePoints properties: projectedActivePoints: type: number description: The active points of the customer when their current tier expires. example: 198 stayInTierPoints: type: number description: | The number of points the customer needs to stay in the current tier. **Note**: This is included in the response when the customer is projected to be downgraded. example: 2 projectedTierName: type: string description: The name of the tier the user will enter once their current tier expires. example: Tier 1 LoyaltyBalanceWithTier: allOf: - $ref: '#/components/schemas/LoyaltyBalance' - type: object properties: currentTier: $ref: '#/components/schemas/Tier' description: Customer's current tier. example: bronze projectedTier: $ref: '#/components/schemas/ProjectedTier' pointsToNextTier: type: number description: The number of points required to move up a tier. example: 20 nextTierName: type: string description: | The name of the next higher tier level in the loyalty program. **Note**: - Returns `null` if the customer has reached the highest available tier. - Returns the lowest level tier name if the customer is not currently assigned to any tier. example: Silver LoyaltyBalancesWithTiers: type: object description: List of loyalty balances for a ledger and its subledgers. properties: balance: $ref: '#/components/schemas/LoyaltyBalanceWithTier' title: Loyalty points balance of a ledger subledgerBalances: type: object description: Map of the loyalty balances of the subledgers of a ledger. additionalProperties: $ref: '#/components/schemas/LoyaltyBalanceWithTier' example: mysubledger: activePoints: 286 pendingPoints: 50 spentPoints: 150 expiredPoints: 25 negativePoints: 0 CardLedgerTransactionLogEntryIntegrationAPI: type: object description: Log entry for a given loyalty card transaction. required: - transactionUUID - created - programId - cardIdentifier - type - name - startDate - expiryDate - subledgerId - amount - id properties: transactionUUID: type: string description: Unique identifier of the transaction in the UUID format. example: ce59f12a-f53b-4014-a745-636d93f2bd3f created: type: string format: date-time description: Date and time the loyalty card transaction occurred. example: 2022-01-02T15:04:05Z07:00 programId: type: integer description: ID of the loyalty program. example: 324 cardIdentifier: $ref: '#/components/schemas/LoyaltyCardIdentifier' customerSessionId: type: string description: ID of the customer session where the transaction occurred. maxLength: 255 example: 05c2da0d-48fa-4aa1-b629-898f58f1584d type: type: string enum: - addition - subtraction description: | Type of transaction. Possible values: - `addition`: Signifies added points. - `subtraction`: Signifies deducted points. maxLength: 255 example: addition name: type: string description: Name or reason of the loyalty ledger transaction. maxLength: 255 example: Reward 10% points of a purchase's current total startDate: type: string description: | When points become active. Possible values: - `immediate`: Points are active immediately. - `on_action`: Points become active based on the customer's action. - a timestamp value: Points become active at a given date and time. maxLength: 64 example: 2022-01-02T15:04:05Z07:00 expiryDate: type: string description: | Date when points expire. Possible values are: - `unlimited`: Points have no expiration date. - `timestamp value`: Points expire on the given date. example: 2022-08-02T15:04:05Z07:00 subledgerId: type: string description: ID of the subledger. maxLength: 64 example: sub-123 amount: type: number description: Amount of loyalty points added or deducted in the transaction. example: 10.25 id: type: integer description: ID of the loyalty ledger transaction. example: 123 rulesetId: type: integer description: The ID of the ruleset containing the rule that triggered this effect. example: 11 ruleName: type: string description: The name of the rule that triggered this effect. example: Add 2 points validityDuration: type: string description: | The duration for which the points remain active, relative to the activation date. **Note**: This only applies to points for which `awaitsActivation` is `true` and `expiryDate` is not set. example: 30D LoyaltyLedgerEntryFlags: type: object description: A map of flags providing additional details about the entry. properties: createsNegativeBalance: type: boolean description: Set to true if the entry creates negative balance. LedgerTransactionLogEntryIntegrationAPI: type: object description: Log entry for a given loyalty profile transaction. required: - transactionUUID - created - programId - type - name - startDate - expiryDate - subledgerId - amount - id properties: transactionUUID: type: string description: Unique identifier of the transaction in the UUID format. example: ce59f12a-f53b-4014-a745-636d93f2bd3f created: type: string format: date-time description: Date and time the loyalty transaction occurred. example: 2022-01-02T15:04:05Z07:00 programId: type: integer description: ID of the loyalty program. example: 324 customerSessionId: type: string description: ID of the customer session where the transaction occurred. maxLength: 255 example: 05c2da0d-48fa-4aa1-b629-898f58f1584d type: type: string enum: - addition - subtraction description: | Type of transaction. Possible values: - `addition`: Signifies added points. - `subtraction`: Signifies deducted points. maxLength: 255 example: addition name: type: string description: Name or reason of the loyalty ledger transaction. maxLength: 255 example: Reward 10% points of a purchase's current total startDate: type: string description: | When points become active. Possible values: - `immediate`: Points are immediately active. - `on_action`: Points become active based on the customer's action. - a timestamp value: Points become active at a given date and time. maxLength: 64 example: 2022-01-02T15:04:05Z07:00 expiryDate: type: string description: | Date when points expire. Possible values are: - `unlimited`: Points have no expiration date. - `timestamp value`: Points expire on the given date. example: 2022-08-02T15:04:05Z07:00 subledgerId: type: string description: ID of the subledger. maxLength: 64 example: sub-123 amount: type: number description: Amount of loyalty points added or deducted in the transaction. example: 10.25 id: type: integer description: ID of the loyalty ledger transaction. example: 123 rulesetId: type: integer description: The ID of the ruleset containing the rule that triggered this effect. example: 11 ruleName: type: string description: The name of the rule that triggered this effect. example: Add 2 points flags: $ref: '#/components/schemas/LoyaltyLedgerEntryFlags' description: The flags of the transaction, when applicable. The `createsNegativeBalance` flag indicates whether the transaction results in a negative balance. validityDuration: type: string description: | The duration for which the points remain active, relative to the activation date. **Note**: This only applies to points for which `awaitsActivation` is `true` and `expiryDate` is not set. example: 30D DeleteLoyaltyTransactionsRequest: type: object description: Request to delete transactions based on the specified scope. additionalProperties: false required: - scope properties: scope: type: string description: | `AllSubledgers` deletes all transactions for the specified customer profile from all ledgers in the loyalty program. `SelectedSubledgers` deletes all transactions for the specified customer profile only from the given ledgers in the loyalty program. enum: - AllSubledgers - SelectedSubledgers example: SelectedSubledgers subledgerIds: type: - array - 'null' description: | The IDs of the ledgers from which to delete the customer's transactions. This parameter is required if the `scope` is set to `SelectedSubledgers`. To specify the main ledger, provide an empty string (""). items: type: string example: - subledger1 - subledger2 CardLedgerPointsEntryIntegrationAPI: type: object description: Loyalty card points with start and expiry dates. required: - id - transactionUUID - created - programId - name - startDate - expiryDate - subledgerId - amount properties: id: type: integer description: ID of the transaction that adds loyalty points. example: 123 transactionUUID: type: string description: Unique identifier of the transaction in the UUID format. example: ce59f12a-f53b-4014-a745-636d93f2bd3f created: type: string format: date-time description: Date and time the loyalty card points were added. example: 2022-01-02T15:04:05Z07:00 programId: type: integer description: ID of the loyalty program. example: 324 customerProfileID: type: string description: Integration ID of the customer profile linked to the card. example: URNGV8294NV customerSessionId: type: string description: ID of the customer session where points were added. maxLength: 255 example: 05c2da0d-48fa-4aa1-b629-898f58f1584d name: type: string description: Name or reason of the transaction that adds loyalty points. maxLength: 255 example: Reward 10% points of a purchase's current total startDate: type: string description: | When points become active. Possible values: - `immediate`: Points are active immediately. - `timestamp value`: Points become active at a given date and time. maxLength: 64 example: 2022-01-02T15:04:05Z07:00 expiryDate: type: string description: | Date when points expire. Possible values are: - `unlimited`: Points have no expiration date. - `timestamp value`: Points expire on the given date and time. example: 2022-08-02T15:04:05Z07:00 subledgerId: type: string description: ID of the subledger. maxLength: 64 example: sub-123 amount: type: number description: Amount of loyalty points added in the transaction. example: 10.25 validityDuration: type: string description: | The duration for which the points remain active, relative to the activation date. **Note**: This only applies to points for which `awaitsActivation` is `true` and `expiryDate` is not set. example: 30D LedgerPointsEntryIntegrationAPI: type: object description: Loyalty profile points with start and expiry dates. required: - id - transactionUUID - created - programId - name - startDate - expiryDate - subledgerId - amount properties: id: type: integer description: ID of the transaction that adds loyalty points. example: 123 transactionUUID: type: string description: Unique identifier of the transaction in the UUID format. example: ce59f12a-f53b-4014-a745-636d93f2bd3f created: type: string format: date-time description: Date and time the loyalty points were added. example: 2022-01-02T15:04:05Z07:00 programId: type: integer description: ID of the loyalty program. example: 324 customerSessionId: type: string description: ID of the customer session where points were added. maxLength: 255 example: 05c2da0d-48fa-4aa1-b629-898f58f1584d name: type: string description: Name or reason of the transaction that adds loyalty points. maxLength: 255 example: Reward 10% points of a purchase's current total startDate: type: string description: | When points become active. Possible values: - `immediate`: Points are active immediately. - `timestamp value`: Points become active at a given date and time. maxLength: 64 example: 2022-01-02T15:04:05Z07:00 expiryDate: type: string description: | Date when points expire. Possible values are: - `unlimited`: Points have no expiration date. - `timestamp value`: Points expire on the given date and time. example: 2022-08-02T15:04:05Z07:00 subledgerId: type: string description: ID of the subledger. maxLength: 64 example: sub-123 amount: type: number description: Amount of loyalty points added in the transaction. example: 10.25 validityDuration: type: string description: | The duration for which the points remain active, relative to the activation date. **Note**: This only applies to points for which `awaitsActivation` is `true` and `expiryDate` is not set. example: 30D LabelTargetNone: type: object description: Represents the target type when no entity is selected. properties: type: type: string enum: - NONE required: - type AudienceReference: allOf: - type: object required: - id properties: id: type: integer description: The ID of the audience. integration: type: string description: The third-party integration of the audience. - $ref: '#/components/schemas/AudienceIntegrationID' LabelTargetAudience: type: object description: | Represents the targeted audience. properties: type: type: string enum: - AUDIENCE audience: $ref: '#/components/schemas/AudienceReference' required: - type - audience LabelTarget: type: object oneOf: - $ref: '#/components/schemas/LabelTargetNone' - $ref: '#/components/schemas/LabelTargetAudience' ActivateLoyaltyPoints: type: object description: Activate loyalty points additionalProperties: false properties: transactionUUIDs: type: array items: type: string format: uuid minItems: 1 maxItems: 50 uniqueItems: true description: | An array of transaction UUIDs used to activate specific pending point transactions. If provided, do not include the `sessionId` parameter. example: - 8f1a8d7c-9c3e-4a5e-9f0d-2c5f7a3b1cde sessionId: type: string minLength: 1 description: | The ID of the session containing the pending point transactions to activate. If provided, do not include the `transactionUUIDs` parameter. example: ac08cc3c43470426591ad75b2d685ec04_v2 LoyaltyLedgerEntry: type: object description: A single row of the ledger, describing one addition or deduction. required: - programID - type - amount - created - name - subLedgerID properties: created: type: string format: date-time example: 2021-07-20T22:00:00Z programID: type: integer example: 5 customerProfileID: type: string example: URNGV8294NV cardID: type: integer example: 241 customerSessionID: type: string example: t2gy5s-47274 eventID: type: integer example: 5 type: type: string description: | The type of the ledger transaction. Possible values are: - `addition` - `subtraction` - `expire` - `expiring` (for expiring points ledgers) example: addition amount: type: number example: 100 startDate: type: string format: date-time example: 2021-07-20T22:00:00Z expiryDate: type: string format: date-time example: 2022-07-20T22:00:00Z name: type: string description: A name referencing the condition or effect that added this entry, or the specific name provided in an API call. example: Add points on purchase subLedgerID: type: string description: This specifies if we are adding loyalty points to the main ledger or a subledger. example: mysubledger userID: type: integer description: This is the ID of the user who created this entry, if the addition or subtraction was done manually. example: 499 archived: type: boolean description: Indicates if the entry belongs to the archived session. example: false flags: $ref: '#/components/schemas/LoyaltyLedgerEntryFlags' description: A map of flags providing additional details about the entry. validityDuration: type: string description: | The duration for which the points remain active, relative to the activation date. **Note**: This only applies to points for which `awaitsActivation` is `true` and `expiryDate` is not set. example: 30D ActivateLoyaltyPointsResponse: type: object properties: ledgerEntries: type: array description: Updated ledger entries after activation. items: $ref: '#/components/schemas/LoyaltyLedgerEntry' GenerateLoyaltyCard: type: object description: The parameters necessary to generate a loyalty card. properties: status: type: string enum: - active - inactive default: active description: Status of the loyalty card. example: active customerProfileIds: type: array description: Integration IDs of the customer profiles linked to the card. items: type: string example: - R195412 - G244519 cardIdentifier: $ref: '#/components/schemas/LoyaltyCardIdentifier' example: status: inactive customerProfileIds: - R195412 - G244519 cardIdentifier: summer-loyalty-card-0543 attributes: preferredReward: discount enrollmentSource: mobile BestPriorTarget: type: object required: - targetType description: Specifies the target for which the best prior price calculation is taken into consideration. properties: targetType: type: string enum: - NONE - AUDIENCE description: The type of price target. example: AUDIENCE audienceID: type: integer description: The AudienceID of an audience. Must be used with "AUDIENCE" target type. example: 4 BestPriorPriceRequest: type: object required: - skus - timeframeEndDate - timeframe - timeframeEndDateType properties: skus: type: array minItems: 1 description: List of product SKUs to check when determining the best prior price. items: type: string example: - SKU1241028 - SKU7345278 timeframeEndDate: type: string format: date-time description: The end date and time that defines the latest time for retrieving historical SKU prices. example: 2020-11-10T23:00:00Z timeframe: type: string description: The number of days prior to the timeframeEndDate. Only prices within this look back period are considered for the best prior price evaluation. example: '30' timeframeEndDateType: type: string enum: - strict - price - sale description: | Sets the timeframe for retrieving historical pricing data. Can be one of the following values: - `strict`: The timeframe ends at the `timeframeEndDate` value. - `price`: The timeframe ends at the start of current price value and takes the prices prior to the start of the current price value into account. - `sale`: The timeframe ends at the start of current `contextId` and takes the prices prior to the start of the `contextId` into account. example: sale target: $ref: '#/components/schemas/BestPriorTarget' InfluencingCampaignDetails: type: object description: Details about a campaign that influenced the final price. properties: campaignId: type: integer description: Identifier of the campaign that influenced the final price. discountValue: type: number description: Discount value applied by the campaign. required: - campaignId - discountValue AdjustmentDetails: type: object description: Details about an applied price adjustment. properties: referenceId: type: string description: The reference identifier used during an `ADD_PRICE_ADJUSTMENT` action. example: 68851723-e6fa-488f-ace9-112581e6c19b selectedPriceType: type: string description: The selected price type for the SKU targeted by this effect. example: member value: type: number description: The value of the applied price adjustment. required: - referenceId - selectedPriceType - value BestPriorPriceMetadata: type: object description: Auxiliary data for found price observation. properties: influencingCampaignDetails: type: array description: Details about campaigns that influenced the final price. items: $ref: '#/components/schemas/InfluencingCampaignDetails' adjustmentDetails: $ref: '#/components/schemas/AdjustmentDetails' type: object description: Details about the applied price adjustment. required: - influencingCampaignDetails BestPriorPrice: type: object required: - id - sku - observedAt - price - contextIds - metadata - target properties: id: type: integer description: The ID of the historical price. example: 1 sku: type: string description: sku example: SKU7345278 observedAt: type: string format: date-time description: The date and time when the price was observed. example: 2025-11-10T23:00:00Z contextIds: type: array items: type: string description: | The identifiers of the relevant context at the time the price was observed. Includes the context IDs of any price adjustments and of the campaigns that influenced the final price. example: - SpringSale - SummerSale2025 contextId: type: string deprecated: true default: '' description: | This property is **deprecated**. Use `contextIds` instead. Defaults to an empty string. example: '' price: type: number description: Price of the item. example: 99.99 metadata: $ref: '#/components/schemas/BestPriorPriceMetadata' target: $ref: '#/components/schemas/LabelTarget' BestPriorPriceResponse: type: array items: $ref: '#/components/schemas/BestPriorPrice' NewCatalog: allOf: - type: object required: - name - description properties: name: type: string description: The cart item catalog name. example: seafood description: type: string description: A description of this cart item catalog. example: seafood catalog subscribedApplicationsIds: type: array description: A list of the IDs of the applications that are subscribed to this catalog. example: - 1 - 2 - 3 items: type: integer Catalog: allOf: - $ref: '#/components/schemas/Entity' - $ref: '#/components/schemas/AccountEntity' - $ref: '#/components/schemas/MutableEntity' - $ref: '#/components/schemas/NewCatalog' - type: object required: - version - createdBy properties: version: type: integer description: The current version of this catalog. example: 6 createdBy: type: integer description: The ID of user who created this catalog. example: 6 AddItemCatalogAction: type: object description: | The specific properties of the "ADD" catalog sync action. required: - sku properties: sku: type: string description: The unique SKU of the item to add. example: SKU1241028 price: type: number description: Price of the item. example: 99.99 attributes: type: object description: The attributes of the item to add. example: origin: germany color: blue product: $ref: '#/components/schemas/Product' replaceIfExists: type: boolean default: false description: | Indicates whether to replace the attributes of the item if the same SKU exists. **Note**: When set to `true`: - If you do not provide a new `price` value, the existing `price` value is retained. - If you do not provide a new `product` value, the `product` value is set to `null`. example: false PatchItemCatalogAction: type: object description: | The specific properties of the "PATCH" catalog sync action. **Note:** - If you do not provide a new `price` value, the existing `price` value is retained. - If you do not provide a new `product` value, the `product` value is set to `null`. required: - sku properties: sku: type: string description: The unique SKU of the item to patch. price: type: number description: Price of the item. example: 99.99 attributes: type: object description: The attributes of the item to patch. product: $ref: '#/components/schemas/Product' createIfNotExists: type: boolean default: false description: Indicates whether to create an item if the SKU does not exist. CatalogActionFilter: type: object description: The properties for a single filtering condition in a catalog sync action. required: - attr - op - value properties: attr: description: The name of the attribute to filter on. type: string op: description: The filtering operator. type: string enum: - EQ - LT - LE - GT - GE - IN value: description: The value to filter for. PatchManyItemsCatalogAction: type: object description: The specific properties of the "PATCH_MANY" catalog sync action. properties: price: type: number description: Price of the item. example: 99.99 filters: type: array items: $ref: '#/components/schemas/CatalogActionFilter' description: | The list of filters used to select the items to patch, joined by `AND`. **Note:** Every item in the catalog will be modified if there are no filters. attributes: type: object description: The attributes of the items to patch. RemoveItemCatalogAction: type: object description: The specific properties of the "REMOVE" catalog sync action. required: - sku properties: sku: type: string description: The unique SKU of the item to remove. RemoveManyItemsCatalogAction: type: object description: The specific properties of the "REMOVE_MANY" catalog sync action. properties: filters: type: array items: $ref: '#/components/schemas/CatalogActionFilter' description: | The list of filters used to select the items to patch, joined by `AND`. **Note:** Every item in the catalog will be removed if there are no filters. NewPriceAdjustment: type: object required: - priceType - referenceId properties: priceType: type: string description: The price type (e.g. the price for members only) to apply to a given SKU. example: member price: type: - number - 'null' description: The value of the price type applied to the SKU. When set to `null`, the defined price type no longer applies to the SKU. example: 100 referenceId: type: string description: A unique reference identifier, e.g. a UUID. example: 68851723-e6fa-488f-ace9-112581e6c19b minLength: 1 calculatedAt: type: string format: date-time description: The time at which this price was calculated. If provided, this is used to determine the most recent price adjustment to choose if price adjustments overlap. Defaults to internal creation time if not provided. example: 2021-09-12T10:12:42Z effectiveFrom: type: string format: date-time description: The date and time from which the price adjustment is effective. example: 2021-09-12T10:12:42Z effectiveUntil: type: string format: date-time description: The date and time until which the price adjustment is effective. example: 2021-09-12T10:12:42Z contextId: type: string description: Identifier of the context of this price adjustment (e.g. summer sale). example: Summer2025 AddPriceAdjustmentCatalogAction: type: object description: | The specific properties of the "ADD_PRICE_ADJUSTMENT" catalog sync action. **Note:** You can only use this object if the `Beta` **price types** feature is enabled for your Application. To enable it, contact your Technical Account Manager. required: - sku - adjustments properties: sku: type: string description: The SKU of the item for which the price is being adjusted. example: SKU1241028 adjustments: type: array description: A list of adjustments to apply to a given item. items: $ref: '#/components/schemas/NewPriceAdjustment' minItems: 1 maxItems: 100 CatalogAction: type: object description: Definition of all the properties that are needed for a single catalog sync action. required: - type - payload oneOf: - properties: type: const: ADD description: The type of sync action. payload: $ref: '#/components/schemas/AddItemCatalogAction' description: The payload of sync action. required: - type - payload example: type: ADD payload: sku: T123 attributes: type: shoes color: blue replaceIfExists: true - properties: type: const: PATCH payload: $ref: '#/components/schemas/PatchItemCatalogAction' required: - type - payload - properties: type: const: PATCH_MANY payload: $ref: '#/components/schemas/PatchManyItemsCatalogAction' required: - type - payload - properties: type: const: REMOVE payload: $ref: '#/components/schemas/RemoveItemCatalogAction' required: - type - payload - properties: type: const: REMOVE_MANY payload: $ref: '#/components/schemas/RemoveManyItemsCatalogAction' required: - type - payload - properties: type: const: ADD_PRICE_ADJUSTMENT payload: $ref: '#/components/schemas/AddPriceAdjustmentCatalogAction' required: - type - payload CatalogSyncRequest: type: object required: - actions properties: actions: type: array maxItems: 1000 minItems: 1 items: $ref: '#/components/schemas/CatalogAction' version: type: integer minimum: 1 description: The version number of the catalog to apply the actions on. example: 244 IntegrationProfileEntityV3: type: object required: - profileId properties: profileId: type: string description: | ID of the customer profile set by your integration layer. **Note:** If the customer does not yet have a known `profileId`, we recommend you use a guest `profileId`. example: URNGV8294NV NewEventV3Entity: type: object required: - integrationId properties: integrationId: type: string description: | The unique ID of the event. Only one event with this ID can be registered. minLength: 1 example: 175KJPS947296 EventV3RequestEntity: allOf: - $ref: '#/components/schemas/IntegrationProfileEntityV3' - $ref: '#/components/schemas/IntegrationStoreEntity' - $ref: '#/components/schemas/EvaluableCampaignIds' - $ref: '#/components/schemas/EventAttributesEntity' - $ref: '#/components/schemas/NewEventV3Entity' - $ref: '#/components/schemas/EventV3Connections' IntegrationEventV3Request: allOf: - $ref: '#/components/schemas/EventV3RequestEntity' - type: object properties: loyaltyCards: type: array maxItems: 1 items: type: string description: Identifiers of the loyalty cards used during this event. example: - loyalty-card-1 responseContent: type: array description: | Optional list of requested information to be present on the response related to the tracking custom event. example: - triggeredCampaigns - customerProfile items: type: string enum: - customerProfile - triggeredCampaigns - loyalty - advancedEvent - awardedGiveaways - ruleFailureReasons IntegrationEventV3Response: allOf: - $ref: '#/components/schemas/IntegrationResponse' - type: object description: | This is the response type returned by the trackEventV3 endpoint. properties: advancedEvent: $ref: '#/components/schemas/EventV3' description: The advanced event that was processed. requestBodies: ReturnIntegrationRequest: content: application/json: schema: $ref: '#/components/schemas/ReturnIntegrationRequest' description: body required: true AttributeQuery: content: application/json: schema: $ref: '#/components/schemas/AttributeQuery' description: body required: true IntegrationEventV2Request: content: application/json: schema: $ref: '#/components/schemas/IntegrationEventV2Request' examples: Full request: summary: Full request x-vertical: none value: profileId: URNGV8294NV storeIntegrationId: STORE-001 evaluableCampaignIds: - 10 - 12 type: pageViewed attributes: myAttribute: myValue responseContent: - triggeredCampaigns - customerProfile loyaltyCards: - loyalty-card-1 eCommerce: x-vertical: ecommerce summary: 'Example: ecommerce' description: Track a custom event such as newsletter sign-up. value: profileId: customer-123 type: newsletter_signup attributes: SubscriptionType: weekly responseContent: - customerProfile - triggeredCampaigns QSR & dining: x-vertical: qsr summary: 'Example: QSR & dining' description: | Record a customer's first app sign-in so you can automatically trigger a welcome reward or bonus loyalty points. value: profileId: customer-456 type: app_first_signin attributes: SignupChannel: mobile_app DeviceType: ios responseContent: - customerProfile - triggeredCampaigns - loyalty Financial services: x-vertical: finance summary: 'Example: Financial services' description: | Track when a customer completes identity verification on a cryptocurrency platform to trigger a reward, such as EUR 10 in cryptocurrency. value: profileId: customer-789 type: identity_verification_completed attributes: VerificationLevel: full_kyc Platform: mobile_app responseContent: - customerProfile - triggeredCampaigns Travel & hospitality: x-vertical: travel summary: 'Example: Travel & hospitality' description: | Track when a customer attends their fifth show in a year to automatically assign a unique voucher code to their account as an omnichannel reward. value: profileId: customer-321 type: show_attendance attributes: Venue: Grand Theater EventCategory: live_music AttendanceCount: 5 responseContent: - customerProfile - triggeredCampaigns description: body required: true CouponReservations: content: application/json: schema: $ref: '#/components/schemas/CouponReservations' description: body required: true ActivateLoyaltyPoints: content: application/json: schema: $ref: '#/components/schemas/ActivateLoyaltyPoints' examples: Full request: summary: Full request x-vertical: none value: transactionUUIDs: - 8f1a8d7c-9c3e-4a5e-9f0d-2c5f7a3b1cde sessionId: ac08cc3c43470426591ad75b2d685ec04_v2 UsingTransactionUUIDs: summary: Activate points using transaction UUIDs value: transactionUUIDs: - 8f1a8d7c-9c3e-4a5e-9f0d-2c5f7a3b1cde - 12b3c456-78d9-4e0f-a1b2-3456789abcde UsingSessionId: summary: Activate points using sessionID value: sessionId: ac08cc3c43470426591ad75b2d685ec04_v2 description: body required: true BestPriorPrice: content: application/json: schema: $ref: '#/components/schemas/BestPriorPriceRequest' description: body required: true IntegrationEventV3Request: content: application/json: schema: $ref: '#/components/schemas/IntegrationEventV3Request' description: body required: true parameters: skip: name: skip in: query required: false description: The number of items to skip when paging through large result sets. example: 100 schema: type: integer pageSize: name: pageSize in: query required: false description: The number of items in the response. example: 1000 schema: type: integer minimum: 1 maximum: 1000 default: 1000