openapi: 3.2.0 info: title: Talon One Loyalty cards API version: '' description: 'Operations tagged Loyalty cards 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 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. ' paths: /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' servers: - url: https://yourbaseurl.talon.one /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' servers: - url: https://yourbaseurl.talon.one /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' servers: - url: https://yourbaseurl.talon.one /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' servers: - url: https://yourbaseurl.talon.one /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' servers: - url: https://yourbaseurl.talon.one /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' get: operationId: getLoyaltyCards summary: List loyalty cards 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. For the given card-based loyalty program, list the loyalty cards that match your filter criteria. ' tags: - Loyalty cards parameters: - $ref: '#/components/parameters/pageSize' - $ref: '#/components/parameters/skip' - $ref: '#/components/parameters/sort' - 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: identifier description: 'The card code by which to filter loyalty cards in the response. **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-054 in: query required: false schema: type: string minLength: 4 - name: profileId in: query description: Filter results by customer profile ID. example: 44 required: false schema: type: integer minimum: 1 - name: batchId in: query description: Filter results by loyalty card batch ID. example: UY83CTT4 required: false schema: type: string 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/LoyaltyCard' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' security: - api_key_v1: [] servers: - url: https://yourbaseurl.talon.one /v1/loyalty_programs/{loyaltyProgramId}/import_cards: post: operationId: importLoyaltyCards summary: Import loyalty cards 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. Upload a CSV file containing the loyalty cards that you want to use in your card-based loyalty program. Send the file as multipart data. It contains the following columns for each card: - `identifier` (required): The identifier of the loyalty card, which must match the regular expression `^[A-Za-z0-9._%+@-]+$`. - `state` (required): The state of the loyalty card. It can be `active` or `inactive`. - `customerprofileids` (optional): An array of strings representing the identifiers of the customer profiles linked to the loyalty card. The identifiers should be separated with a semicolon (;). - `attributes` (optional): A JSON object that contains the loyalty card''s custom attributes and their values. These attributes must be created and connected to this loyalty program before they can be assigned to the cards through this endpoint. > [!note] Your CSV file must contain less than 500,000 rows. Requests time out after 30 seconds. ## Example ```csv identifier,state,customerprofileids,attributes 123-456-789AT,active,Alexa001;UserA,''{""my_attributes"": ""10_off""}" ``` ' 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: required: true content: multipart/form-data: schema: type: object properties: upFile: description: The CSV file containing the data that is being imported. type: string format: binary responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Import' '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}/cards/batch: post: operationId: createBatchLoyaltyCards summary: Create loyalty cards 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. Create a batch of loyalty cards in a specified [card-based loyalty program](https://docs.talon.one/docs/product/loyalty-programs/overview#loyalty-program-types). Customers can use loyalty cards to collect and spend loyalty points. > [!important] **Note** > - The specified card-based loyalty program must have a defined card code > format that is used to generate the loyalty card codes. > - Trying to create more than 20,000 loyalty cards in a single request > returns an error message with a `400` status code. ' 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/LoyaltyCardBatch' description: body required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/LoyaltyCardBatchResponse' '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}/export_card_balances: get: operationId: exportLoyaltyCardBalances summary: Export all card transaction logs 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. Download a CSV file containing the balances of all cards in the loyalty program. > [!tip] If the exported CSV file is too large to view, you can > [split it into multiple files](https://www.google.com/search?q=split+CSV+into+multiple+files). The CSV file contains the following columns: - `loyaltyProgramID`: The ID of the loyalty program. - `loyaltySubledger`: The name of the subdleger, when applicatble. - `cardIdentifier`: The identifier of the loyalty card, which must match the regular expression `^[A-Za-z0-9._%+@-]+$`. - `cardState`:The state of the loyalty card. It can be `active` or `inactive`. - `currentBalance`: The current point balance. - `pendingBalance`: The number of pending points. - `expiredBalance`: The number of expired points. - `spentBalance`: The number of spent points. ' 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: 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: balances in: query required: false description: 'Filters which balance fields are included in the CSV export. By default, all balance fields are included. When this parameter is provided, only the listed fields contain values and the rest are returned empty. Accepted values: - `currentBalance` - `pendingBalance` - `expiredBalance` - `spentBalance` - `negativeBalance` Multiple values must be provided as a comma-separated list. **Note:** - The `negativeBalance` value is not supported for card balance exports. - Providing an unsupported or invalid value returns a `400 Bad Request` error. ' example: currentBalance,pendingBalance schema: type: string responses: '200': description: OK content: application/csv: schema: type: string format: csv examples: response: value: 'loyaltyProgramID,loyaltySubledger,cardIdentifier,cardState,currentBalance,pendingBalance,expiredBalance,spentBalance 40,,111,active,10,0,0,0,5 ' '400': description: Bad request content: application/csv: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '401': description: Unauthorized content: application/csv: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' security: - manager_auth: [] - management_key: [] servers: - url: https://yourbaseurl.talon.one /v1/loyalty_programs/{loyaltyProgramId}/cards/export: get: operationId: exportLoyaltyCards summary: Export loyalty cards 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. Download a CSV file containing the loyalty cards from a specified loyalty program. > [!tip] If the exported CSV file is too large to view, you can > [split it into multiple files](https://www.google.com/search?q=split+CSV+into+multiple+files). The CSV file contains the following columns: - `identifier`: The unique identifier of the loyalty card. - `created`: The date and time the loyalty card was created. - `status`: The status of the loyalty card. - `userpercardlimit`: The maximum number of customer profiles that can be linked to the card. - `customerprofileids`: Integration IDs of the customer profiles linked to the card. - `blockreason`: The reason for transferring and blocking the loyalty card. - `generated`: An indicator of whether the loyalty card was generated. - `batchid`: The ID of the batch the loyalty card is in. - `attributes`: The custom attributes of this loyalty card. ' 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: batchId in: query description: Filter results by loyalty card batch ID. example: UY83CTT4 required: false schema: type: string - name: createdBefore in: query description: 'Only return loyalty cards created before this timestamp. **Note:** This must be an RFC3339 timestamp string. ' required: false example: '2024-05-29T15:04:05+07:00' schema: type: string format: date-time - name: createdAfter in: query description: 'Only return loyalty cards created after this timestamp. **Note:** This must be an RFC3339 timestamp string. ' required: false example: '2024-04-15T15:04:05+07:00' schema: type: string format: date-time - name: dateFormat in: query description: Determines the format of dates in the export document. example: excel required: false schema: type: string enum: - excel - ISO8601 responses: '200': description: OK content: application/csv: schema: type: string format: csv examples: response: value: 'identifier,created,status,userpercardlimit,customerprofileids,blockreason,generated,batchid,attributes CARD-1234,2020-06-10T09:05:27.993483Z,active,3,[''profile1''],card limit reached,false,gwedcbfp,{"ForumPosts": 17} ' '400': description: Bad request content: application/csv: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '401': description: Unauthorized content: application/csv: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' security: - manager_auth: [] - management_key: [] servers: - url: https://yourbaseurl.talon.one /v1/loyalty_programs/{loyaltyProgramId}/cards/{loyaltyCardId}: delete: operationId: deleteLoyaltyCard summary: Delete loyalty card 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. Delete the given loyalty card.' 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 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' security: - manager_auth: [] - management_key: [] put: operationId: updateLoyaltyCard summary: Update loyalty card 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. Update the details of a specific loyalty card. You can set the card''s status to `active` or `inactive` through this endpoint. At least one of `status` or `attributes` must be provided.' 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 requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateLoyaltyCardRequest' 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' security: - manager_auth: [] - management_key: [] get: operationId: getLoyaltyCard summary: Get loyalty card 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 given loyalty card.' 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 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' security: - manager_auth: [] - management_key: [] servers: - url: https://yourbaseurl.talon.one /v1/loyalty_programs/{loyaltyProgramId}/cards/{loyaltyCardId}/add_points: put: operationId: addLoyaltyCardPoints summary: Add points to card 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. Add points to the given loyalty card in the specified card-based loyalty program. ' 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. **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: 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. ' example: summer-loyalty-card-0543 required: true schema: type: string minLength: 4 maxLength: 108 requestBody: $ref: '#/components/requestBodies/AddLoyaltyPoints' 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' security: - manager_auth: [] - management_key: [] servers: - url: https://yourbaseurl.talon.one /v1/loyalty_programs/{loyaltyProgramId}/cards/{loyaltyCardId}/deduct_points: put: operationId: deductLoyaltyCardPoints summary: Deduct points from card 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. Deduct points from the given loyalty card in the specified card-based loyalty program. ' 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 requestBody: $ref: '#/components/requestBodies/DeductLoyaltyPoints' 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' security: - manager_auth: [] - management_key: [] servers: - url: https://yourbaseurl.talon.one /v1/loyalty_programs/{loyaltyProgramId}/cards/{loyaltyCardId}/export_log: get: operationId: exportLoyaltyCardLedger summary: Export card's ledger log 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. Download a CSV file containing a loyalty card ledger log of the loyalty program. > [!tip] If the exported CSV file is too large to view, you can > [split it into multiple files](https://www.google.com/search?q=split+CSV+into+multiple+files). ' 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: rangeStart in: query required: true description: 'Only return results from after this timestamp. > [!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: rangeEnd in: query required: true description: 'Only return results from before this timestamp. > [!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: dateFormat in: query description: Determines the format of dates in the export document. example: excel required: false schema: type: string enum: - excel - ISO8601 responses: '200': description: OK content: application/csv: schema: type: string format: csv '401': description: Unauthorized content: application/csv: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' '404': description: Not found content: application/csv: schema: $ref: '#/components/schemas/ErrorResponseWithStatus' security: - manager_auth: [] - management_key: [] servers: - url: https://yourbaseurl.talon.one /v1/loyalty_programs/{loyaltyProgramId}/cards/{loyaltyCardId}/logs: get: operationId: getLoyaltyCardTransactionLogs summary: List card's 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 the transaction logs for the given [loyalty card](https://docs.talon.one/docs/product/loyalty-programs/card-based/card-based-overview) within the specified [card-based loyalty program](https://docs.talon.one/docs/product/loyalty-programs/overview#loyalty-program-types) with filtering options applied. > [!note] For most use cases, especially real-time integrations, use the Integration API endpoint: > [List card''s transactions](https://docs.talon.one/integration-api#tag/Loyalty-cards/operation/getLoyaltyCardTransactions). If no filtering options are applied, the last 50 loyalty transactions for the given loyalty card are returned. ' 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: 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 - $ref: '#/components/parameters/pageSize' - $ref: '#/components/parameters/skip' - name: subledgerId in: query required: false description: The ID of the subledger by which we filter the data. example: subledger1 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 responses: '200': description: OK content: application/json: schema: type: object required: - data - hasMore properties: hasMore: type: boolean description: true means there is more data in the source collection to request.. example: true data: type: array description: List of loyalty card transaction logs. items: $ref: '#/components/schemas/CardLedgerTransactionLogEntry' '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}/cards/{loyaltyCardId}/transfer: put: operationId: transferLoyaltyCard summary: Transfer card data 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\nTransfer loyalty card data, such as linked customers, loyalty balances and\ntransactions, from a given loyalty card to a new, automatically created\nloyalty card.\n\n> [!important] **Note**\n> - The original card is automatically blocked once the new card is created,\n and it cannot be activated again.\n> - The default status of the new card is _active_.\n" 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 requestBody: content: application/json: schema: $ref: '#/components/schemas/TransferLoyaltyCard' 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' security: - manager_auth: [] - management_key: [] servers: - url: https://yourbaseurl.talon.one components: schemas: 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 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. 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' 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 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:\n - `immediate`: Points are active immediately.\n - `timestamp value`: Points become active at a given date and time.\n" maxLength: 64 example: 2022-01-02T15:04:05Z07:00 expiryDate: type: string description: "Date when points expire. Possible values are:\n - `unlimited`: Points have no expiration date.\n - `timestamp value`: Points expire on the given date and time.\n" 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 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 LoyaltyCardRegistration: type: object required: - integrationId properties: integrationId: type: string title: Customer Profile ID description: The integrationId of the customer profile. example: R195412 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 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.\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" 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 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 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 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:\n - `addition`: Signifies added points.\n - `subtraction`: Signifies deducted points.\n" 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:\n - `immediate`: Points are active immediately.\n - `on_action`: Points become active based on the customer's action.\n - a timestamp value: Points become active at a given date and time.\n" maxLength: 64 example: 2022-01-02T15:04:05Z07:00 expiryDate: type: string description: "Date when points expire. Possible values are:\n - `unlimited`: Points have no expiration date.\n - `timestamp value`: Points expire on the given date.\n" 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 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' 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' 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 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 AccountEntity: type: object required: - accountId properties: accountId: type: integer description: The ID of the account that owns this entity. example: 3886 UserEntity: type: object required: - userId properties: userId: type: integer description: The ID of the user associated with this entity. example: 388 LoyaltyCardBatch: allOf: - type: object required: - numberOfCards properties: numberOfCards: type: integer description: Number of loyalty cards in the batch. example: 5000 batchId: type: string description: ID of the loyalty card batch. minLength: 4 maxLength: 20 pattern: ^[A-Za-z0-9_-]*$ example: hwernpjz status: type: string enum: - active - inactive default: active description: Status of the loyalty cards in the batch. example: active cardCodeSettings: $ref: '#/components/schemas/CodeGeneratorSettings' TransferLoyaltyCard: type: object required: - newCardIdentifier properties: newCardIdentifier: $ref: '#/components/schemas/LoyaltyCardIdentifier' blockReason: type: string description: 'Reason for transferring and blocking the loyalty card. ' example: Current card lost. Customer needs a new card. 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 AddLoyaltyPoints: type: object description: Points to add. required: - points properties: points: type: number exclusiveMinimum: 0 maximum: 999999999999.99 description: Amount of loyalty points. example: 300 name: type: string description: Name / reason for the point addition. example: Compensation validityDuration: type: string description: 'The time format is either: - `unlimited` or, - an **integer** followed by one letter indicating the time unit. Examples: `unlimited`, `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. If passed, `validUntil` should be omitted. ' example: 5D validUntil: type: string format: date-time description: 'Date and time when points should expire. The value should be provided in RFC 3339 format. If passed, `validityDuration` should be omitted. ' example: '2021-07-20T22:00:00Z' pendingDuration: type: string description: 'The amount of time before the points are considered valid. The time format is either: - `immediate` or, - `on_action` or, - an **integer** followed by one letter indicating the time unit. Examples: `immediate`, `30s`, `40m`, `1h`, `5D`, `7W`, `10M`, `15Y`, `on_action`. 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 pendingUntil: type: string format: date-time description: 'Date and time after the points are considered valid. The value should be provided in RFC 3339 format. If passed, `pendingDuration` should be omitted. ' example: '2021-07-20T22:00:00Z' subledgerId: type: string description: ID of the subledger the points are added to. If there is no existing subledger with this ID, the subledger is created automatically. example: sub-123 applicationId: type: integer description: ID of the Application that is connected to the loyalty program. It is displayed in your Talon.One deployment URL. example: 322 UpdateLoyaltyCardRequest: type: object additionalProperties: false properties: status: type: string description: 'Status of the loyalty card. Can be `active` or `inactive`. ' example: active Import: allOf: - $ref: '#/components/schemas/Entity' - $ref: '#/components/schemas/AccountEntity' - $ref: '#/components/schemas/UserEntity' - type: object required: - amount - entity properties: entity: type: string example: AttributeAllowedList description: 'The name of the entity that was imported. ' amount: type: integer minimum: 0 example: 10 description: The number of values that were imported. LoyaltyCardBatchResponse: type: object required: - numberOfCardsGenerated - batchId properties: numberOfCardsGenerated: type: integer description: Number of loyalty cards in the batch. example: 5000 batchId: type: string description: ID of the loyalty card batch. example: hwernpjz DeductLoyaltyPoints: type: object description: Points to deduct. required: - points properties: points: type: number exclusiveMinimum: 0 maximum: 999999999999.99 description: Amount of loyalty points. example: 300 name: type: string description: Name / reason for the point deduction. example: Penalty subledgerId: type: string description: ID of the subledger the points are deducted from. example: sub-123 applicationId: type: integer description: ID of the Application that is connected to the loyalty program. example: 322 CardLedgerTransactionLogEntry: 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' applicationId: type: integer description: The ID of the Application that owns this entity. example: 322 sessionId: description: 'The **internal** ID of the session. ' type: integer example: 233 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:\n - `addition`: Signifies added points.\n - `subtraction`: Signifies deducted points.\n" 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:\n - `immediate`: Points are immediately active.\n - a timestamp value: Points become active at a given date and time.\n" maxLength: 64 example: 2022-01-02T15:04:05Z07:00 expiryDate: type: string description: "Date when points expire. Possible values are:\n - `unlimited`: Points have no expiration date.\n - `timestamp value`: Points become active from the given date.\n" 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 entry. example: 123 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 sort: name: sort in: query required: false description: 'The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with `-`. **Note:** You may not be able to use all fields for sorting. This is due to performance limitations. ' example: name schema: type: string requestBodies: AddLoyaltyPoints: content: application/json: schema: $ref: '#/components/schemas/AddLoyaltyPoints' description: body required: true DeductLoyaltyPoints: content: application/json: schema: $ref: '#/components/schemas/DeductLoyaltyPoints' description: body required: true 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\nand prefix it with `ApiKey-v1`.\n\nTo generate an API key:\n\n1. Sign in to the Campaign Manager and open the Application of your choice, or create one.\n1. Click **Settings** > **Integration API Keys**.\n1. Click **Create API Key** and give it a name and an expiration date, then click **Create API Key**.\n\n **Tip**: Avoid choosing expiration dates that fall at the end of\n the year or during other high-traffic periods.\n\n\nYou can now use the API key in the HTTP header, prefixing it with `ApiKey-v1`:\n\n```\nAuthorization: ApiKey-v1 dbc644d33aa74d582bd9479c59e16f970fe13bf3\n```\n\nOr use it inside [an SDK](https://docs.talon.one/docs/dev/sdks/overview), for example, with the JAVA SDK:\n\n```\niApi.getApiClient().setApiKeyPrefix(\"ApiKey-v1\");\niApi.getApiClient().setApiKey(\"dbc644d33aa74d582bd9479c59e16f970fe13bf3\");\n```\n" manager_auth: type: apiKey name: Authorization in: header description: 'This authentication scheme relies on a bearer token that you can use to access all the endpoints of the Management API. To create the token: 1. Get a bearer token by calling the [createSession](#tag/Sessions/operation/createSession) endpoint. 1. Use the `token` property of the response in the HTTP header of your next queries: `Authorization: Bearer $TOKEN`. A token is valid for 3 months. In accordance with best pratices, use your generated token for all your API requests. Do **not** regenerate a token for each request. > [!note] > We recommend that you use a [Management API key](https://docs.talon.one/management-api#section/Authentication/management_key) > instead of a bearer token. ' management_key: type: apiKey name: Authorization in: header description: "The API key authentication gives you access to the endpoints selected by\nthe admin who created the key.\n\nUsing an API key is the recommended authentication method.\n\nThe key must be generated by an admin and given to the developer that\nrequires it:\n\n1. Sign in to the Campaign Manager and click **Account** > **Tools** >\n**Management API Keys**.\n1. Click **Create Key** and give it a name.\n1. Set an expiration date.\n **Tip**: Avoid choosing expiration dates that fall at the end of the year or during other high-traffic periods.\n1. Choose the endpoints the key should give access to.\n1. Click **Create Key**.\n1. Share it with your developer.\n\nThe developer can now use the API key in the HTTP header, prefixing it\nwith `ManagementKey-v1`:\n\n```\nAuthorization: ManagementKey-v1 bd9479c59e16f9dbc644d33aa74d58270fe13bf3\n```\n" x-refined-from: - talon-one-integration-api-openapi.yml - talon-one-management-api-openapi.yml