Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Management Applications API
version: ''
description: "The Management API allows you to programmatically do what the Campaign Manager\ndoes. Use this API for back-office operations such as campaign\nand coupon management, maintenance jobs, and bulk operations.\n\nFor more background information about this API, see\n[Management API overview](https://docs.talon.one/docs/dev/management-api/overview).\n\n> [!note] **Are you looking for a different API?**\n> - To integrate with Talon.One directly and send real-time data, see the [Integration API](https://docs.talon.one/integration-api).\n> - To integrate with Talon.One from a CEP or CDP platform, see the [Third-party API](https://docs.talon.one/third-party-api).\n\n## Authentication\n\nManagement API keys are scoped to a user account and become invalid if the user is\ndeactivated or removed from the organization. Use a dedicated service account to\ncreate keys for production integrations.\n\nFor details on generating and managing API keys, see\n[Manage Management API keys](https://docs.talon.one/docs/product/account/dev-tools/manage-mapi-keys).\n\n## Security\n\nConsider the following recommendations:\n- Store API keys securely via environment variables or by using a secret management system.\n- Only call this API from backend services.\n- Implement HTTPS for all communication with the API to ensure data privacy and security.\n- Create [user roles](https://docs.talon.one/docs/product/account/account-settings/manage-roles)\n reflecting your own company hierarchies.\n\n## Response codes and error handling\n\nTalon.One uses conventional HTTP response codes to indicate the success or failure of an API request.\nCodes in the `2xx` range indicate success. Codes in the `4xx` range indicate the request failed based\non the information provided. Codes in the `5xx` range indicate an error with Talon.One servers.\n\nError responses include a `message` that summarizes what went wrong. Use it for logging and debugging.\n\nWhen a request has one or more specific problems, the `errors` array lists each one separately:\n- `title` gives a short description of the problem\n- `source` shows where the error originated, for example, using a `pointer` property indicating the\n problematic property in the request body.\n\n| Code | Description | Action |\n|------|-------------|--------|\n| `2xx` | Success | None. |\n| `400` | Bad request | Fix the request (for example, a missing or invalid parameter). Not retryable. |\n| `401` | Unauthorized | Provide a valid API key. Not retryable. |\n| `404` | Not found | Check the resource path or ID. Not retryable. |\n| `409` | Conflict | If you are creating a resource, use a unique resource name/ID. Generally not retryable. |\n| `429` | Rate limit exceeded | Retry with exponential backoff. |\n| `5xx` | Server error | Retry with exponential backoff. |\n\n## URL encoding\n\nEncode all path and query parameter values that contain special characters. This applies to\ncustomer profile IDs, session IDs, coupon codes, and any other user-supplied string passed as\na URL segment or query parameter.\n\nFor example, encode a `10$OFF_NOW` coupon code as `10%24OFF_NOW` before\nincluding it in a request URL.\n\nRequests with unencoded special characters may be misrouted or return unexpected errors.\n\nFor more information, see [HTML URL Encoding Reference](https://www.w3schools.com/tags/ref_urlencode.asp).\n\n## MCP server (closed beta)\n\nTalon.One provides an MCP server that gives AI agents\nread-only access to your campaigns, customers, coupons, and loyalty programs,\nso they can answer questions about your campaigns and customers in plain language.\n\nAgents can explain campaign rule logic, check campaign status and budgets, analyze customer point\nbalances and tier status, and investigate failed API requests.\n\nTo connect, append `/v1/mcp/entrypoint` to your Talon.One deployment URL and authenticate with an MCP\nconnection API key generated in **Campaign Manager > Account > Tools > MCP Connections**.\n\nThe server is compatible with Claude Desktop, Claude Code, Cursor, Gemini CLI, ChatGPT CLI,\nCodex CLI, and other stdio-compatible MCP clients.\n\nFor more information, see [Talon.One MCP server](https://docs.talon.one/docs/dev/mcp).\n\n## Rate limiting\n\nThis API is **not** meant to be used in real-time integrations that directly serve your end users.\nIt supports a maximum of **3 requests per second** for each of these endpoints.\nFor real-time integrations use the [Integration API](https://docs.talon.one/integration-api).\n"
servers:
- url: https://yourbaseurl.talon.one
security:
- manager_auth: []
- management_key: []
tags:
- name: Applications
description: 'Represents an Application in the Campaign Manager.
An Application is the target of every Integration API request to Talon.One.
One Application can hold various API keys used for Integration API requests.
You may have multiple Applications within one account,
for example staging and production, or different international markets.
See the [docs](https://docs.talon.one/docs/product/applications/overview).
'
paths:
/v1/applications:
get:
operationId: getApplications
summary: List Applications
description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.
List all the Applications in the current account.'
tags:
- Applications
parameters:
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/sort'
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/Application'
/v1/applications/{applicationId}:
get:
operationId: getApplication
summary: Get Application
description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.
Get the Application specified by the ID.'
tags:
- Applications
parameters:
- $ref: '#/components/parameters/applicationId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Application'
/v1/applications/{applicationId}/health_report:
get:
operationId: getApplicationApiHealth
summary: Get Application health
description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.
Display the health of the Application and show the last time the Application
was used.
You can also find this information in the Campaign Manager. In your Application, click **Settings** > **Integration API Keys**.
See the [docs](https://docs.talon.one/docs/dev/tutorials/monitoring-integration-status).
'
tags:
- Applications
parameters:
- $ref: '#/components/parameters/applicationId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ApplicationApiHealth'
/v1/applications/{applicationId}/cart_item_filters:
get:
operationId: listApplicationCartItemFilters
summary: List Application cart item filters
description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.
Return all the Application cart item filters for a specific Application.'
tags:
- Applications
parameters:
- $ref: '#/components/parameters/applicationId'
- name: pageSize
in: query
required: false
description: The number of items in the response.
example: 50
schema:
type: integer
minimum: 1
maximum: 50
default: 50
- $ref: '#/components/parameters/skip'
- name: name
in: query
description: 'Filter by the display name of the Application cart item filter in the Application.
**Note**: If no `name` is provided, all the Application cart item filters in the Application are returned.
'
example: cartItemFilter1
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
required:
- data
properties:
hasMore:
type: boolean
data:
type: array
items:
$ref: '#/components/schemas/ApplicationCIF'
/v1/applications/{applicationId}/cart_item_filters/{cartItemFilterId}/expressions/{expressionId}:
get:
operationId: getApplicationCartItemFilterExpression
summary: Get Application cart item filter expression
description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.
Get an Application cart item filter expression for a specific Application.'
tags:
- Applications
parameters:
- $ref: '#/components/parameters/applicationId'
- name: cartItemFilterId
in: path
description: The ID of the Application cart item filter. You can get this ID with the [List Application cart item filters](https://docs.talon.one/management-api#tag/Applications/operation/listApplicationCartItemFilters) endpoint.
example: 20
required: true
schema:
type: integer
- name: expressionId
in: path
description: The ID of the Application cart item filter expression.
example: 19
required: true
schema:
type: integer
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/ApplicationCIFExpression'
components:
schemas:
BestPriorPriceSettings:
type: object
description: The best prior price settings for this Application.
properties:
enableBestPriorPrice:
type: boolean
description: When set to `true`, the best prior price feature is enabled in this Application and its [price history](https://docs.talon.one/management-api#tag/Catalogs/operation/priceHistory) is recorded.
example: true
AttributesMandatory:
type: object
description: Arbitrary settings associated with attributes.
properties:
campaigns:
type: array
items:
type: string
description: List of mandatory attributes for campaigns.
coupons:
type: array
items:
type: string
description: List of mandatory attributes for campaigns.
BaseLoyaltyProgram:
type: object
properties:
title:
type: string
description: The display title for the Loyalty Program.
example: Point collection
description:
type: string
description: Description of our Loyalty Program.
example: Customers collect 10 points per 1$ spent
subscribedApplications:
type: array
description: A list containing the IDs of all applications that are subscribed to this Loyalty Program.
example:
- 132
- 97
items:
type: integer
defaultValidity:
type: string
description: 'The default duration after which new loyalty points should expire. Can be ''unlimited'' or a specific time.
The time format is a number followed by one letter indicating the time unit, like ''30s'', ''40m'', ''1h'', ''5D'', ''7W'', or 10M''. These rounding suffixes are also supported:
- ''_D'' for rounding down. Can be used as a suffix after ''D'', and signifies the start of the day.
- ''_U'' for rounding up. Can be used as a suffix after ''D'', ''W'', and ''M'', and signifies the end of the day, week, and month.
'
example: 2W_U
defaultPending:
type: string
description: 'The default duration of the pending time after which points should be valid. Accepted values: ''immediate'', ''on_action'' or a specific time.
The time format is a number followed by one letter indicating the time unit, like ''30s'', ''40m'', ''1h'', ''5D'', ''7W'', or 10M''. These rounding suffixes are also supported:
- ''_D'' for rounding down. Can be used as a suffix after ''D'', and signifies the start of the day.
- ''_U'' for rounding up. Can be used as a suffix after ''D'', ''W'', and ''M'', and signifies the end of the day, week, and month.
'
example: immediate
allowSubledger:
type: boolean
description: Indicates if this program supports subledgers inside the program.
example: false
usersPerCardLimit:
type: integer
minimum: 0
example: 111
description: 'The max amount of user profiles with whom a card can be shared. This can be set to 0 for no limit.
This property is only used when `cardBased` is `true`.
'
sandbox:
type: boolean
description: Indicates if this program is a live or sandbox program. Programs of a given type can only be connected to Applications of the same type.
title: Sandbox
example: true
programJoinPolicy:
type: string
enum:
- not_join
- points_activated
- points_earned
description: "The policy that defines when the customer joins the loyalty program.\n - `not_join`: The customer does not join the loyalty program but can still earn and spend loyalty points.\n\n **Note**: The customer does not have a program join date.\n - `points_activated`: The customer joins the loyalty program only when their earned loyalty points become active for the first time.\n - `points_earned`: The customer joins the loyalty program when they earn loyalty points for the first time.\n"
tiersExpirationPolicy:
type: string
enum:
- tier_start_date
- program_join_date
- customer_attribute
- absolute_expiration
description: "The policy that defines how tier expiration, used to reevaluate the customer's current tier, is determined.\n - `tier_start_date`: The tier expiration is relative to when the customer joined the current tier.\n - `program_join_date`: The tier expiration is relative to when the customer joined the loyalty program.\n - `customer_attribute`: The tier expiration is determined by a custom customer attribute.\n - `absolute_expiration`: The tier is reevaluated at the start of each tier cycle. For this policy, it is required to provide a `tierCycleStartDate`.\n"
tierCycleStartDate:
type: string
format: date-time
description: 'Timestamp at which the tier cycle starts for all customers in the loyalty program.
**Note**: This is only required when the tier expiration policy is set to `absolute_expiration`.
'
example: '2021-09-12T10:12:42Z'
tiersExpireIn:
type: string
description: 'The amount of time after which the tier expires and is reevaluated.
The time format is an **integer** 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 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: 27W_U
tiersDowngradePolicy:
type: string
enum:
- one_down
- balance_based
description: "The policy that defines how customer tiers are downgraded in the loyalty program after tier reevaluation.\n - `one_down`: If the customer doesn't have enough points to stay in the current tier, they are downgraded by one tier.\n - `balance_based`: The customer's tier is reevaluated based on the amount of active points they have at the moment.\n"
cardCodeSettings:
$ref: '#/components/schemas/CodeGeneratorSettings'
returnPolicy:
type: string
enum:
- only_pending
- within_balance
- unlimited
description: 'The policy that defines the rollback of points in case of a partially returned, cancelled, or reopened [customer session](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions).
- `only_pending`: Only pending points can be rolled back.
- `within_balance`: Available active points can be rolled back if there aren''t enough pending points. The active balance of the customer cannot be negative.
- `unlimited`: Allows negative balance without any limit.
'
AccountEntity:
type: object
required:
- accountId
properties:
accountId:
type: integer
description: The ID of the account that owns this entity.
example: 3886
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'
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'
Application:
allOf:
- $ref: '#/components/schemas/Entity'
- $ref: '#/components/schemas/MutableEntity'
- $ref: '#/components/schemas/AccountEntity'
- $ref: '#/components/schemas/UpdateApplication'
- type: object
required:
- loyaltyPrograms
properties:
loyaltyPrograms:
type: array
description: An array containing all the loyalty programs to which this application is subscribed.
items:
$ref: '#/components/schemas/LoyaltyProgram'
LoyaltyTier:
allOf:
- $ref: '#/components/schemas/Entity'
- $ref: '#/components/schemas/LoyaltyProgramEntity'
- $ref: '#/components/schemas/NewLoyaltyTier'
NewLoyaltyTier:
type: object
description: A tier in a loyalty program.
required:
- name
- minPoints
properties:
name:
type: string
description: The name of the tier.
example: Gold
minPoints:
type: number
minimum: 0
maximum: 999999999999.99
description: The minimum amount of points required to enter the tier.
example: 300
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
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
ApplicationApiHealth:
type: object
description: Report of health of the API connection of an application.
required:
- summary
- lastUsed
properties:
summary:
type: string
description: 'One-word summary of the health of the API connection of an application. Possible values are:
- `OK`: The Application has received only successful API requests in the last 5 minutes.
- `WARNING`: The Application received at least one failed request in the last 5 minutes.
- `ERROR`: More than 50% of received requests failed.
- `CRITICAL`: All received requests failed.
- `NONE`: During the last 5 minutes, the Application hasn''t recorded any integration API requests.
'
enum:
- OK
- WARNING
- ERROR
- CRITICAL
- NONE
lastUsed:
type: string
format: date-time
description: time of last request relevant to the API health test.
example: '2021-09-12T10:12:42Z'
AttributesSettings:
type: object
description: Arbitrary settings associated with attributes.
properties:
mandatory:
$ref: '#/components/schemas/AttributesMandatory'
NewApplicationCIFExpression:
type: object
properties:
cartItemFilterId:
type: integer
description: The ID of the Application cart item filter.
example: 216
createdBy:
type: integer
description: The ID of the user who created the Application cart item filter.
example: 216
expression:
type: array
description: Arbitrary additional JSON data associated with the Application cart item filter.
example:
expr:
- filter
- - .
- Session
- CartItems
- - - Item
- - catch
- false
- - contains
- - .
- Item
- Category
- Kitchen
items: {}
NewApplicationCIF:
type: object
required:
- name
properties:
name:
type: string
description: The name of the Application cart item filter used in API requests.
example: Filter items by product
description:
type: string
description: A short description of the Application cart item filter.
example: This filter allows filtering by shoes
activeExpressionId:
type: integer
description: The ID of the expression that the Application cart item filter uses.
example: 1
modifiedBy:
type: integer
description: The ID of the user who last updated the Application cart item filter.
example: 334
createdBy:
type: integer
description: The ID of the user who created the Application cart item filter.
example: 216
modified:
type: string
format: date-time
description: Timestamp of the most recent update to the Application cart item filter.
ApplicationCIF:
allOf:
- $ref: '#/components/schemas/Entity'
- $ref: '#/components/schemas/NewApplicationCIF'
- type: object
required:
- applicationId
properties:
applicationId:
type: integer
description: The ID of the Application that owns this entity.
example: 322
UpdateApplication:
type: object
properties:
name:
type: string
description: The name of this application.
minLength: 1
example: My Application
description:
type: string
description: A longer description of the application.
example: A test Application
timezone:
type: string
description: A string containing an IANA timezone descriptor.
minLength: 1
example: Europe/Berlin
currency:
type: string
description: The default currency for new customer sessions.
minLength: 1
example: EUR
caseSensitivity:
type: string
enum:
- sensitive
- insensitive-uppercase
- insensitive-lowercase
description: The case sensitivity behavior to check coupon codes in the campaigns of this Application.
example: sensitive
attributes:
type: object
description: Arbitrary properties associated with this campaign.
limits:
type: array
description: Default limits for campaigns created in this application.
items:
$ref: '#/components/schemas/LimitConfig'
defaultDiscountScope:
type: string
example: sessionTotal
description: 'The default scope to apply `setDiscount` effects on if no scope was provided with the effect.
'
enum:
- sessionTotal
- cartItems
- additionalCosts
enableCascadingDiscounts:
type: boolean
description: Indicates if discounts should cascade for this Application.
example: true
enableFlattenedCartItems:
type: boolean
example: true
description: 'Indicates if cart items of quantity larger than one should be separated into different items of quantity one.
'
attributesSettings:
$ref: '#/components/schemas/AttributesSettings'
sandbox:
type: boolean
description: Indicates if this is a live or sandbox Application.
example: true
enablePartialDiscounts:
type: boolean
description: Indicates if this Application supports partial discounts.
example: false
defaultDiscountAdditionalCostPerItemScope:
type: string
description: 'The default scope to apply `setDiscountPerItem` effects on if no scope was provided with the effect.
'
example: price
enum:
- price
- itemTotal
- additionalCosts
defaultEvaluationGroupId:
type: integer
description: The ID of the default campaign evaluation group to which new campaigns will be added unless a different group is selected when creating the campaign.
example: 3
defaultCartItemFilterId:
type: integer
description: The ID of the default Cart-Item-Filter for this application.
example: 3
enableCampaignStateManagement:
type: boolean
description: 'Indicates whether the campaign staging and revisions feature is enabled for the Application.
**Important:** After this feature is enabled, it cannot be disabled.
'
example: false
bestPriorPriceSettings:
$ref: '#/components/schemas/BestPriorPriceSettings'
required:
- name
- timezone
- currency
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
LoyaltyProgram:
allOf:
- $ref: '#/components/schemas/Entity'
- $ref: '#/components/schemas/BaseLoyaltyProgram'
- type: object
description: A Loyalty Program
required:
- id
- name
- title
- description
- accountID
- defaultValidity
- defaultPending
- subscribedApplications
- allowSubledger
- timezone
- cardBased
- sandbox
properties:
id:
type: integer
description: The ID of loyalty program.
example: 139
accountID:
type: integer
description: The ID of the Talon.One account that owns this program.
example: 1
name:
type: string
description: The internal name for the Loyalty Program. This is an immutable value.
example: my_program
tiers:
type: array
description: The tiers in this loyalty program.
items:
$ref: '#/components/schemas/LoyaltyTier'
example:
- name: Gold
minPoints: 300
id: 3
created: '2021-06-10T09:05:27.993483Z'
programID: 139
- name: Silver
minPoints: 200
id: 2
created: '2021-06-10T09:04:59.355258Z'
programID: 139
- name: Bronze
minPoints: 100
id: 1
created: '2021-06-10T09:04:39.355258Z'
programID: 139
timezone:
type: string
description: A string containing an IANA timezone descriptor.
example: Europe/Berlin
minLength: 1
cardBased:
type: boolean
description: 'Defines the type of loyalty program:
- `true`: the program is a card-based.
- `false`: the program is profile-based.
'
default: false
example: true
canUpdateTiers:
type: boolean
description: '`True` if the tier definitions can be updated.
'
# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/talon-one/refs/heads/main/openapi/talon-one-applications-api-openapi.yml