Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Talon One Loyalty API
version: ''
description: 'Operations tagged Loyalty across 2 of this provider''s published API definitions: talon-one-integration-api-openapi.yml, talon-one-management-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://yourbaseurl.talon.one
tags:
- 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.
'
paths:
/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'
servers:
- url: https://yourbaseurl.talon.one
/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'
servers:
- url: https://yourbaseurl.talon.one
/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'
servers:
- url: https://yourbaseurl.talon.one
/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'
servers:
- url: https://yourbaseurl.talon.one
/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. \n\nTo include multiple IDs, repeat the parameter for each one, for example, \n`?customerSessionIDs=id1&customerSessionIDs=id2`.\n\nThe response contains only data associated with the specified sessions.\n"
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.\n\nTo include multiple IDs, repeat the parameter for each one, for example, \n`?transactionUUIDs=uuid1&transactionUUIDs=uuid2`.\n\nThe response contains only data associated with the specified transactions.\n"
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:\n\n- `startDate`: Sorts the results by the start date of the points.\n- `expiryDate`: Sorts the results by the expiry date of the points.\n\nBy default, results are sorted in ascending order. \nTo sort them in descending order, prefix the field name with `-`.\n\n**Note:** You can only sort by one field at a time.\n"
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'
servers:
- url: https://yourbaseurl.talon.one
/v1/loyalty_programs/{loyaltyProgramId}/activate_points:
post:
operationId: activateLoyaltyPoints
summary: Activate loyalty points
description: "Activate points when a defined action occurs.\n\nYou can activate pending points using one of the following parameters:\n- `sessionId`: Activates all points earned in the specified session. \n- `transactionUUIDs`: Activates points earned in the transactions specified by the \ngiven UUIDs. \n"
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'
servers:
- url: https://yourbaseurl.talon.one
/v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}/ledger_balances:
get:
operationId: getLoyaltyLedgerBalances
summary: Get customer's loyalty balances (Management API)
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.\n\nRetrieve loyalty ledger balances for the given Integration ID in the\nspecified loyalty program.\n\nYou can filter balances by date and subledger ID, and include tier-related\ninformation in the response.\n\n> [!note] **Note**\n> - For most use cases, especially real-time integrations, use the Integration API endpoint:\n [Get customer's loyalty balances](https://docs.talon.one/integration-api#tag/Loyalty/operation/getLoyaltyBalances).\n> - If no filtering options are applied, you retrieve all loyalty balances on the current date for the given integration ID.\n\nLoyalty balances are calculated when Talon.One receives your request using\nthe points stored in our database, so retrieving a large number of balances\nat once can impact performance.\n\nFor more information, see:\n\n- [Managing card-based loyalty program\ndata](https://docs.talon.one/docs/product/loyalty-programs/card-based/managing-loyalty-cards)\n\n- [Managing profile-based loyalty program\ndata](https://docs.talon.one/docs/product/loyalty-programs/profile-based/managing-pb-lp-data)\n"
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 used to filter the data. Leave this value empty ("") to query the main ledger.
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'
security:
- manager_auth: []
- management_key: []
servers:
- url: https://yourbaseurl.talon.one
/v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}/ledger_transactions:
get:
operationId: getLoyaltyProgramProfileLedgerTransactions
summary: List customer's loyalty transactions (Management API)
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.
Retrieve paginated results of loyalty transaction logs for the given
Integration ID in the specified loyalty program.
You can filter transactions by date or by ledger (subledger or main ledger). If no filters are applied, the last 50
loyalty transactions for the given integration ID are returned.
> [!note] **Note**
> - For most use cases, especially real-time integrations, use the Integration API endpoint:
> [List customer''s loyalty transactions](https://docs.talon.one/integration-api#tag/Loyalty/operation/getLoyaltyProgramProfileTransactions).
> - 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.
'
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
# --- truncated at 32 KB (133 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/talon-one/refs/heads/main/openapi/talon-one-loyalty-api-openapi.yml