openapi: 3.1.0
info:
  title: Management API
  version: ''
  description: |
    The Management API allows you to programmatically do what the Campaign Manager
    does. Use this API for back-office operations such as campaign
    and coupon management, maintenance jobs, and bulk operations.

    For more background information about this API, see:
    - [Management API overview](https://docs.talon.one/docs/dev/management-api/overview)
    - [Management API best practices](https://docs.talon.one/docs/dev/management-api/best-practices)

    > [!note] **Are you looking for a different API?**
    > - To integrate with Talon.One directly and send real-time data, see the [Integration API](https://docs.talon.one/integration-api).
    > - To integrate with Talon.One from a CEP or CDP platform, see the [Third-party API](https://docs.talon.one/third-party-api).

    ## Authentication

    Management API keys are scoped to a user account and become invalid if the user is
    deactivated or removed from the organization. Use a dedicated service account to
    create keys for production integrations.

    For more information, see
    [Management API best practices](https://docs.talon.one/docs/dev/management-api/best-practices#api-key-management).

    ## Security

    Consider the following recommendations:
    - Store API keys securely via environment variables or by using a secret management system.
    - Only call this API from backend services.
    - Implement HTTPS for all communication with the API to ensure data privacy and security.
    - Create [user roles](https://docs.talon.one/docs/product/account/account-settings/manage-roles)
      reflecting your own company hierarchies.

    ## Response codes and error handling

    Talon.One uses conventional HTTP response codes to indicate the success or failure of an API request.
    Codes in the `2xx` range indicate success. Codes in the `4xx` range indicate the request failed based
    on the information provided. Codes in the `5xx` range indicate an error with Talon.One servers.

    Error responses include a `message` that summarizes what went wrong. Use it for logging and debugging.

    When a request has one or more specific problems, the `errors` array lists each one separately:
    - `title` gives a short description of the problem
    - `source` shows where the error originated, for example, using a `pointer` property indicating the
      problematic property in the request body.

    | Code | Description | Action |
    |------|-------------|--------|
    | `2xx` | Success | None. |
    | `400` | Bad request | Fix the request (for example, a missing or invalid parameter). Not retryable. |
    | `401` | Unauthorized | Provide a valid API key. Not retryable. |
    | `404` | Not found | Check the resource path or ID. Not retryable. |
    | `409` | Conflict | If you are creating a resource, use a unique resource name/ID. Generally not retryable. |
    | `429` | Rate limit exceeded | Retry with exponential backoff. |
    | `5xx` | Server error | Retry with exponential backoff. |

    ## URL encoding

    Encode all path and query parameter values that contain special characters. This applies to
    customer profile IDs, session IDs, coupon codes, and any other user-supplied string passed as
    a URL segment or query parameter.

    For example, encode a `10$OFF_NOW` coupon code as `10%24OFF_NOW` before
    including it in a request URL.

    Requests with unencoded special characters may be misrouted or return unexpected errors.

    For more information, see [HTML URL Encoding Reference](https://www.w3schools.com/tags/ref_urlencode.asp).

    ## MCP server (closed beta)

    Talon.One provides an MCP server that gives AI agents
    read-only access to your campaigns, customers, coupons, and loyalty programs,
    so they can answer questions about your campaigns and customers in plain language.

    Agents can explain campaign rule logic, check campaign status and budgets, analyze customer point
    balances and tier status, and investigate failed API requests.

    To connect, append `/v1/mcp/entrypoint` to your Talon.One deployment URL and authenticate with an MCP
    connection API key generated in **Campaign Manager > Account > Tools > MCP Connections**.

    The server is compatible with Claude Desktop, Claude Code, Cursor, Gemini CLI, ChatGPT CLI,
    Codex CLI, and other stdio-compatible MCP clients.

    For more information, see [Talon.One MCP server](https://docs.talon.one/docs/dev/mcp).

    ## Rate limiting

    This API is **not** meant to be used in real-time integrations that directly serve your end users.
    It supports a maximum of **3 requests per second** for each of these endpoints.

    For more information, see [Management API best practices](https://docs.talon.one/docs/dev/management-api/best-practices#rate-limits).

    > [!note]
    > For real-time integrations use the [Integration API](https://docs.talon.one/integration-api).
servers:
  - url: https://yourbaseurl.talon.one
security:
  - manager_auth: []
  - management_key: []
tags:
  - name: Accounts and users
    description: |
      Represents account and user management, including billing email addresses and user invitations.
  - name: Achievements
    description: |
      Represents achievements that reward a customer profile for performing a number of specific actions or reaching a transactional milestone within a defined period.
      For example, you can use achievements to award your customers when they purchase five cups of coffee in one week or when they purchase items worth $3000 in three months.
      See the [docs](https://docs.talon.one/docs/product/achievements/overview) for more information.
  - name: Additional costs
    description: |
      Represents an extra fee applied to the cart, for example, shipping fees or processing fees.
      See the [docs](https://docs.talon.one/docs/product/account/dev-tools/managing-additional-costs) for more information.
  - name: Analytics
    description: |
      Represents analytics used to retrieve statistical data about the performance of campaigns within an Application.
  - name: Applications
    description: |
      Represents an Application in the Campaign Manager.
      An Application is the target of every Integration API request to Talon.One.
      One Application can hold various API keys used for Integration API requests.
      You may have multiple Applications within one account, for example staging and production, or different international markets.
      See the [docs](https://docs.talon.one/docs/product/applications/overview) for more information.
  - name: Attributes
    description: |
      Represents a piece of information related to one of the entities available in the Campaign Manager. Use them to create highly customized rules.
      See the [docs](https://docs.talon.one/docs/product/account/dev-tools/managing-attributes) for more information.
  - name: Audiences
    description: |
      Represents lists of customer profiles that allow you to target specific groups of customers in your campaigns.
      Audiences can be synced from customer data platforms or created directly in Talon.One.
      See the [docs](https://docs.talon.one/docs/product/audiences/overview) for more information.
  - name: Campaign access groups
    description: |
      Represents the campaign access groups you can create in your Applications to organize your campaigns based on the type of campaign or the team in charge.

      See the [docs](https://docs.talon.one/docs/product/account/account-settings/managing-campaign-groups) for more information.
  - name: Campaign templates
    description: |
      Represents templates used to generate campaigns from.
  - name: Campaigns
    description: |
      Represents the primary resource used to control the behavior of the Talon.One Rule Engine. They combine rulesets, coupons, and limits into a single unit.
      See the [docs](https://docs.talon.one/docs/product/campaigns/overview) for more information.
  - name: Catalogs
    description: |
      Represents a catalog of cart items with unique SKUs. Cart item catalogs allow you to synchronize your entire inventory with Talon.One.
      See the [docs](https://docs.talon.one/docs/product/account/dev-tools/managing-cart-item-catalogs) for more information.
  - name: Collections
    description: |
      Represents a collection of arbitrary values that you can use inside rules. For example, a list of SKUs.
      See the [docs](https://docs.talon.one/docs/product/campaigns/managing-collections) for more information.
  - name: Coupons
    description: |
      Represents unique codes belonging to a particular campaign. Coupons don't define any behavior on their own.
      Instead the campaign ruleset can include rules that validate coupons and carry out particular effects.
      See the [docs](https://docs.talon.one/docs/product/campaigns/coupons/coupon-page-overview) for more information.
  - name: Customer data
    description: |
      Represents the data of a customer, including sessions and events used for reporting and debugging in the Campaign Manager.
  - name: Events
    description: |
      Represents a single occurrence of a specific customer action, for example, updating the cart or signing up for a newsletter.
      There are 2 types of [events](https://docs.talon.one/docs/dev/concepts/entities/events):
      - **Built-in events:** They are triggered by various endpoints, such as
        the [Update customer session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2)
        endpoint. [Learn more](https://docs.talon.one/docs/dev/concepts/entities/events#built-in-events).
      - **Custom events:** They are triggered by the [Track advanced event](https://docs.talon.one/integration-api#tag/Events/operation/trackEventV3) endpoint. [Learn more](https://docs.talon.one/docs/dev/concepts/entities/events#advanced-events).
  - name: Experiments
    description: |
      Represents an A/B testing configuration within a campaign that splits customer sessions across multiple variants to compare rule effects against each other.
  - name: Giveaways
    description: |
      Represents a program that rewards customers with giveaways, such as free gift cards.
      See the [docs](https://docs.talon.one/docs/product/giveaways/overview) for more information.
  - name: Logs
    description: |
      Represents the Talon.One logs, which contain all incoming and outgoing requests.
  - 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 docs](https://docs.talon.one/docs/product/loyalty-programs/overview) for more information.
  - name: Loyalty cards
    description: |
      Represents loyalty cards, which allow your customers to collect and spend loyalty points within a card-based loyalty program.
      See the [docs](https://docs.talon.one/docs/product/loyalty-programs/card-based/card-based-overview) for more information.
  - name: Referrals
    description: |
      Represents a referral code shared between a customer (advocate) and a prospect (friend).

      A referral is defined by:
      - an advocate: person who invited their friend via referral program.
      - a friend: person who receives the invite from an advocate.
      - a referral code: code to be redeemed by the advocate(s) once they referred their friend.

      See the [docs](https://docs.talon.one/docs/product/campaigns/referrals/referral-overview).
  - name: Roles
    description: |
      Represents a set of permissions assigned to a user.

      See the [docs](https://docs.talon.one/docs/product/account/account-settings/managing-roles).
  - name: Sessions
    description: |
      Represents a session used for authentication purposes.
      Create one with the [Create session](#tag/Sessions/operation/createSession) endpoint.
  - name: Store budgets
    description: Represents store budgets. You can set a store budget to limit the total amount an individual store can spend in a campaign.
  - name: Stores
    description: |
      Represents physical or digital stores, branches, and franchises.
  - name: Value maps
    description: Represents the value maps that the user can create within a campaign ruleset.
  - name: Webhooks
    description: |
      Represents webhooks, which send information from Talon.One to the URI of your choice.

      See the [docs](https://docs.talon.one/docs/dev/getting-started/webhooks) for more information.
paths:
  /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.

        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] **Note**
        > - For most use cases, especially real-time integrations, use the Integration API endpoint:
            [Get customer's loyalty balances](https://docs.talon.one/integration-api#tag/Loyalty/operation/getLoyaltyBalances).
        > - 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)
      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'
  /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),
        and include the UUIDs of transactions referenced by deductions. 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
          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 used to filter the data. Leave this value empty ("") to query the main ledger.
          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: includeReferences
          in: query
          required: false
          description: |
            Whether to include the UUIDs of transactions referenced by deductions.

            **Note:** Enabling this can decrease query performance, especially
            when no date filter is applied to a large transaction history.
          example: true
          schema:
            type: boolean
            default: false
        - 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/LedgerTransactionLogEntryManagementAPI'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v1/applications:
    get:
      operationId: getApplications
      summary: List Applications
      description: |-
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        List all the Applications in the current account.
      tags:
        - Applications
      parameters:
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/sort'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - totalResultSize
                  - data
                properties:
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Application'
  /v1/applications/{applicationId}:
    get:
      operationId: getApplication
      summary: Get Application
      description: |-
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        Get the Application specified by the ID.
      tags:
        - Applications
      parameters:
        - $ref: '#/components/parameters/applicationId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
  /v1/applications/{applicationId}/campaigns:
    get:
      operationId: getCampaigns
      summary: List campaigns
      description: |
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        List the campaigns of the specified application that match your filter criteria.
      tags:
        - Campaigns
      parameters:
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/applicationId'
        - name: campaignState
          in: query
          description: |
            Filter results by the state of the campaign.

            - `enabled`: Campaigns that are scheduled, running (activated), or expired.
            - `running`: Campaigns that are running (activated).
            - `disabled`: Campaigns that are disabled.
            - `expired`: Campaigns that are expired.
            - `archived`: Campaigns that are archived.
          example: enabled
          required: false
          schema:
            type: string
            enum:
              - enabled
              - disabled
              - archived
              - scheduled
              - running
              - expired
              - staged
        - name: name
          in: query
          description: Filter results performing case-insensitive matching against the name of the campaign.
          example: campaign1
          required: false
          schema:
            type: string
        - name: tags
          in: query
          description: |
            Filter results performing case-insensitive matching against the tags of the campaign.
          example:
            - tag1
            - tag2
          required: false
          schema:
            type: array
            items:
              type: string
        - name: createdBefore
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the campaign creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: createdAfter
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the campaign creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: startBefore
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the campaign start time timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: startAfter
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the campaign start time timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: endBefore
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the campaign end time timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: endAfter
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the campaign end time timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: campaignGroupId
          in: query
          description: Filter results to campaigns owned by the specified campaign access group ID.
          example: 12
          required: false
          schema:
            type: integer
        - name: templateId
          in: query
          description: The ID of the campaign template this campaign was created from.
          example: 18
          schema:
            type: integer
        - name: storeId
          in: query
          description: Filter results to campaigns linked to the specified store ID.
          example: 23
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - totalResultSize
                  - data
                properties:
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Campaign'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
    post:
      operationId: createCampaign
      summary: Create campaign
      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 campaign. A campaign is part of an Application and contains a set of rules.
      tags:
        - Campaigns
      parameters:
        - $ref: '#/components/parameters/applicationId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewCampaign'
        description: body
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Campaign'
  /v1/applications/{applicationId}/campaigns/{campaignId}/revisions/current:
    get:
      operationId: getCurrentRevision
      summary: Get current revision version
      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 current revision version for the given campaign.

        **Note:** The [Campaign staging and revisions](https://docs.talon.one/docs/product/applications/manage-general-settings#campaign-staging-and-revisions) feature must be enabled for your Application.
        For more information, see [Revise campaigns](https://docs.talon.one/docs/product/campaigns/revise-campaigns).
      tags:
        - Campaigns
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Revision'
  /v1/applications/{applicationId}/campaigns/{campaignId}:
    get:
      operationId: getCampaign
      summary: Get campaign
      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 given campaign.
      tags:
        - Campaigns
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Campaign'
    put:
      operationId: updateCampaign
      summary: Update campaign
      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 given campaign.

        > [!important] You cannot use this endpoint to update campaigns if [campaign staging and
        > revisions](https://docs.talon.one/docs/product/applications/managing-general-settings#campaign-staging-and-revisions)
        > is enabled for your Application.
      tags:
        - Campaigns
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCampaign'
        description: body
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Campaign'
    delete:
      operationId: deleteCampaign
      summary: Delete campaign
      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 campaign.
      tags:
        - Campaigns
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
      responses:
        '204':
          description: No Content
  /v1/applications/{applicationId}/campaigns/{campaignId}/copy:
    post:
      operationId: copyCampaignToApplications
      summary: Copy the campaign into the specified Application
      description: |-
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        Copy the campaign into all specified Applications.
      tags:
        - Campaigns
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampaignCopy'
        description: body
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - totalResultSize
                  - data
                properties:
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Campaign'
  /v1/applications/{applicationId}/campaigns_search:
    post:
      operationId: getCampaignByAttributes
      summary: List campaigns that match the given attributes
      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 a list of all the campaigns that match a set of attributes.
      tags:
        - Campaigns
      parameters:
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/applicationId'
        - name: campaignState
          in: query
          description: |
            Filter results by the state of the campaign.

            - `enabled`: Campaigns that are scheduled, running (activated), or expired.
            - `running`: Campaigns that are running (activated).
            - `disabled`: Campaigns that are disabled.
            - `expired`: Campaigns that are expired.
            - `archived`: Campaigns that are archived.
          example: enabled
          required: false
          schema:
            type: string
            enum:
              - enabled
              - disabled
              - archived
              - scheduled
              - running
              - expired
              - staged
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampaignSearch'
        description: body
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - totalResultSize
                  - data
                properties:
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Campaign'
  /v1/applications/{applicationId}/campaigns/{campaignId}/rulesets:
    get:
      operationId: getRulesets
      summary: List campaign rulesets
      description: |
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        List all rulesets of this campaign. A ruleset is a revision of the rules of a campaign.
        **Important:** The response also includes deleted rules.
        You should only consider the latest revision of the returned rulesets.
      tags:
        - Campaigns
      parameters:
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - totalResultSize
                  - data
                properties:
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Ruleset'
  /v1/applications/{applicationId}/campaigns/{campaignId}/rulesets/{rulesetId}:
    get:
      operationId: getRuleset
      summary: Get ruleset
      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 specified ruleset.
      tags:
        - Campaigns
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
        - name: rulesetId
          in: path
          description: The ID of the ruleset.
          example: 29
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ruleset'
  /v2/applications/{applicationId}/campaigns/{campaignId}/rulesets:
    post:
      operationId: createRulesetV2
      summary: Create ruleset (V2)
      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 ruleset from promotion and strikethrough rules in the V2 JSON block format. A ruleset is a revision of all the rules of a campaign.

        Only the first block of a rule can be a condition. Every other block must be an effect.
      tags:
        - Campaigns
      x-scalar-stability: experimental
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
      requestBody:
        $ref: '#/components/requestBodies/NewRulesetV2'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RulesetV2'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v2/applications/{applicationId}/campaigns/{campaignId}/rulesets/{rulesetId}:
    get:
      operationId: getRulesetV2
      summary: Get ruleset (V2)
      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 specified ruleset as a JSON object.
      tags:
        - Campaigns
      x-scalar-stability: experimental
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
        - name: rulesetId
          in: path
          description: The ID of the ruleset.
          example: 29
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RulesetV2'
  /v1/applications/{applicationId}/campaigns/{campaignId}/coupons:
    post:
      operationId: createCoupons
      summary: Create coupons
      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 coupons according to some pattern. Up to 20.000 coupons can be created without a unique prefix. When a unique prefix is provided, up to 200.000 coupons can be created.
      tags:
        - Coupons
      parameters:
        - name: silent
          in: query
          description: |
            Possible values: `yes` or `no`.
            - `yes`: Increases the performance of the API call by returning a 204 response.
            - `no`: Returns a 200 response that contains the updated customer profiles.
          example: 'yes'
          required: false
          schema:
            type: string
            default: 'yes'
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewCoupons'
        description: body
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - totalResultSize
                  - data
                properties:
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Coupon'
        '204':
          description: No Content
    put:
      operationId: updateCouponBatch
      summary: Update coupons
      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 all coupons or a specific batch of coupons in the given campaign.

        You can find the `batchId` on the **Coupons** page of your campaign in the
        Campaign Manager, or you can use [List coupons](#tag/Coupons/operation/getCouponsWithoutTotalCount).

        > [!note] **Note**
        > - Only send sequential requests to this endpoint.
        > - Requests to this endpoint time out after 30 minutes. If you hit a timeout, contact our support team.
        > - With this `PUT` endpoint, if you do not explicitly set a value for the `startDate` and `expiryDate` properties in your request, it is automatically set to `null`.

        To update a specific coupon, use [Update coupon](#tag/Coupons/operation/updateCoupon).
      tags:
        - Coupons
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCouponBatch'
        description: body
        required: true
      responses:
        '204':
          description: No Content
    delete:
      operationId: deleteCoupons
      summary: Delete coupons
      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.

        Deletes all the coupons matching the specified criteria.
      tags:
        - Coupons
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
        - name: value
          in: query
          description: Filter results performing case-insensitive matching against the coupon code. Both the code and the query are folded to remove all non-alpha-numeric characters.
          example: SUMMER10
          required: false
          schema:
            type: string
        - name: createdBefore
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: createdAfter
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: startsAfter
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon start date timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: startsBefore
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon start date timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: expiresAfter
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon expiration date timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: expiresBefore
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon expiration date timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: valid
          in: query
          description: |
            - `expired`: Matches coupons in which the expiration date is set and in the past.
            - `validNow`: Matches coupons in which start date is null or in the past and expiration date is null or in the future.
            - `validFuture`: Matches coupons in which start date is set and in the future.
          example: validNow
          required: false
          schema:
            type: string
            enum:
              - expired
              - validNow
              - validFuture
        - name: batchId
          in: query
          description: Filter results by batches of coupons
          example: nfinccze
          required: false
          schema:
            type: string
        - name: usable
          in: query
          description: |
            - `true`: only coupons where `usageCounter < usageLimit` will be returned.
            - `false`: only coupons where `usageCounter >= usageLimit` will be returned.
          example: 'false'
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
        - name: referralId
          in: query
          description: Filter the results by matching them with the ID of a referral. This filter shows the coupons created by redeeming a referral code.
          example: 47
          required: false
          schema:
            type: integer
        - name: recipientIntegrationId
          in: query
          description: |
            Filter results by match with a profile ID specified in the coupon's `RecipientIntegrationId` field.
          example: customer1
          required: false
          schema:
            type: string
        - name: exactMatch
          in: query
          description: Filter results to an exact case-insensitive matching against the coupon code
          example: false
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '204':
          description: No Content
  /v1/applications/{applicationId}/campaigns/{campaignId}/coupons_with_recipients:
    post:
      operationId: createCouponsForMultipleRecipients
      summary: Create coupons for multiple recipients
      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 coupons according to some pattern for up to 1000 recipients.
      tags:
        - Coupons
      parameters:
        - name: silent
          in: query
          description: |
            Possible values: `yes` or `no`.
            - `yes`: Increases the performance of the API call by returning a 204 response.
            - `no`: Returns a 200 response that contains the updated customer profiles.
          example: 'yes'
          required: false
          schema:
            type: string
            default: 'yes'
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewCouponsForMultipleRecipients'
        description: body
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - totalResultSize
                  - data
                properties:
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Coupon'
        '204':
          description: No Content
  /v1/applications/{applicationId}/campaigns/{campaignId}/coupons_async:
    post:
      operationId: createCouponsAsync
      summary: Create coupons asynchronously
      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 up to 5,000,000 coupons asynchronously. You should typically use this enpdoint when you create at least 20,001 coupons. You receive an email when the creation is complete.

        If you want to create less than 20,001 coupons, you can use the [Create coupons](https://docs.talon.one/management-api#tag/Coupons/operation/createCoupons) endpoint.
      tags:
        - Coupons
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewCouponCreationJob'
        description: body
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncCouponCreationResponse'
  /v1/applications/{applicationId}/campaigns/{campaignId}/coupons_deletion_jobs:
    post:
      operationId: createCouponsDeletionJob
      summary: Creates a coupon deletion job
      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.

        This endpoint handles creating a job to delete coupons asynchronously.
      tags:
        - Coupons
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewCouponDeletionJob'
        description: body
        required: true
      responses:
        '202':
          description: The deletion request has been accepted and will be processed asynchronously
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncCouponDeletionJobResponse'
  /v1/applications/{applicationId}/campaigns/{campaignId}/coupons/no_total:
    get:
      operationId: getCouponsWithoutTotalCount
      summary: List coupons
      description: |
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        List all the coupons matching the specified criteria.
      tags:
        - Coupons
      parameters:
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
        - name: value
          in: query
          description: Filter results performing case-insensitive matching against the coupon code. Both the code and the query are folded to remove all non-alpha-numeric characters.
          example: SUMMER10
          required: false
          schema:
            type: string
        - name: createdBefore
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: createdAfter
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: valid
          in: query
          description: |
            Either "expired", "validNow", or "validFuture". The first option matches coupons in which the expiration date is set and in the past. The second matches coupons in which start date is null or in the past and expiration date is null or in the future, the third matches coupons in which start date is set and in the future.
          example: validNow
          required: false
          schema:
            type: string
            enum:
              - expired
              - validNow
              - validFuture
        - name: usable
          in: query
          description: |
            Either "true" or "false". If "true", only coupons where `usageCounter < usageLimit` will be returned, "false" will return only coupons where `usageCounter >= usageLimit`.
          example: 'false'
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
        - name: redeemed
          in: query
          description: |
            - `true`: only coupons where `usageCounter > 0` will be returned.
            - `false`: only coupons where `usageCounter = 0` will be returned.
            - This field cannot be used in conjunction with the `usable` query parameter.
          example: 'false'
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
        - name: referralId
          in: query
          description: Filter the results by matching them with the ID of a referral. This filter shows the coupons created by redeeming a referral code.
          example: 47
          required: false
          schema:
            type: integer
        - name: recipientIntegrationId
          in: query
          description: Filter results by match with a profile ID specified in the coupon's RecipientIntegrationId field.
          example: customer1
          required: false
          schema:
            type: string
        - name: batchId
          in: query
          description: Filter results by batches of coupons
          example: nfinccze
          required: false
          schema:
            type: string
        - name: exactMatch
          in: query
          description: Filter results to an exact case-insensitive matching against the coupon code.
          example: false
          required: false
          schema:
            type: boolean
            default: false
        - name: expiresBefore
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon expiration date timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: expiresAfter
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon expiration date timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: startsBefore
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon start date timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: startsAfter
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon start date timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: valuesOnly
          in: query
          description: Filter results to only return the coupon codes (`value` column) without the associated coupon data.
          example: false
          required: false
          schema:
            type: boolean
            default: false
      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/Coupon'
  /v1/applications/{applicationId}/campaigns/{campaignId}/coupons/{couponId}:
    put:
      operationId: updateCoupon
      summary: Update coupon
      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 specified coupon.

        > [!note]
        > With this `PUT` endpoint, if you do not explicitly set a value for the `startDate`, `expiryDate`,
        > and `recipientIntegrationId` properties in your request, it is automatically set to `null`.
      tags:
        - Coupons
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
        - name: couponId
          in: path
          description: |
            The internal ID of the coupon code. You can find this value in the `id` property from the
            [List coupons](https://docs.talon.one/management-api#tag/Coupons/operation/getCouponsWithoutTotalCount) endpoint response.
          example: '1194'
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCoupon'
        description: body
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Coupon'
    delete:
      operationId: deleteCoupon
      summary: Delete coupon
      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 specified coupon.
      tags:
        - Coupons
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
        - name: couponId
          in: path
          description: |
            The internal ID of the coupon code. You can find this value in the `id` property from the
            [List coupons](https://docs.talon.one/management-api#tag/Coupons/operation/getCouponsWithoutTotalCount) endpoint response.
          example: '1194'
          required: true
          schema:
            type: string
      responses:
        '204':
          description: No Content
  /v1/applications/{applicationId}/campaigns/{campaignId}/coupons_search_advanced/no_total:
    post:
      operationId: searchCouponsAdvancedWithoutTotalCount
      summary: List coupons that match the given attributes in campaign (without total count)
      description: |
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        List the coupons whose attributes match the query criteria in the given campaign.

        The match is successful if all the attributes of the request are found in a
        coupon, even if the coupon has more attributes that are not present on the request.

        > [!note] The total count is not included in the response.
      tags:
        - Coupons
      parameters:
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
        - name: value
          in: query
          description: Filter results performing case-insensitive matching against the coupon code. Both the code and the query are folded to remove all non-alpha-numeric characters.
          example: SUMMER10
          required: false
          schema:
            type: string
        - name: createdBefore
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: createdAfter
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: valid
          in: query
          description: |
            Either "expired", "validNow", or "validFuture". The first option matches coupons in which the expiration date is set and in the past. The second matches coupons in which start date is null or in the past and expiration date is null or in the future, the third matches coupons in which start date is set and in the future.
          example: validNow
          required: false
          schema:
            type: string
            enum:
              - expired
              - validNow
              - validFuture
        - name: usable
          in: query
          description: |
            Either "true" or "false". If "true", only coupons where `usageCounter < usageLimit` will be returned, "false" will return only coupons where `usageCounter >= usageLimit`.
          example: 'false'
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
        - name: referralId
          in: query
          description: Filter the results by matching them with the ID of a referral. This filter shows the coupons created by redeeming a referral code.
          example: 47
          required: false
          schema:
            type: integer
        - name: recipientIntegrationId
          in: query
          description: Filter results by match with a profile ID specified in the coupon's RecipientIntegrationId field.
          example: customer1
          required: false
          schema:
            type: string
        - name: exactMatch
          in: query
          description: Filter results to an exact case-insensitive matching against the coupon code.
          example: false
          required: false
          schema:
            type: boolean
            default: false
        - name: batchId
          in: query
          description: Filter results by batches of coupons
          example: nfinccze
          required: false
          schema:
            type: string
      requestBody:
        $ref: '#/components/requestBodies/AttributeQuery'
      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/Coupon'
  /v1/applications/{applicationId}/coupons_search_advanced/no_total:
    post:
      operationId: searchCouponsAdvancedApplicationWideWithoutTotalCount
      summary: List coupons that match the given attributes (without total count)
      description: |
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        List the coupons whose attributes match the query criteria in all the
        campaigns of the given Application.

        The match is successful if all the attributes of the request are found in a
        coupon, even if the coupon has more attributes that are not present on the request.

        > [!note] The total count is not included in the response.
      tags:
        - Coupons
      parameters:
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/applicationId'
        - name: value
          in: query
          description: Filter results performing case-insensitive matching against the coupon code. Both the code and the query are folded to remove all non-alpha-numeric characters.
          example: SUMMER10
          required: false
          schema:
            type: string
        - name: createdBefore
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: createdAfter
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: valid
          in: query
          description: |
            Either "expired", "validNow", or "validFuture". The first option matches coupons in which the expiration date is set and in the past. The second matches coupons in which start date is null or in the past and expiration date is null or in the future, the third matches coupons in which start date is set and in the future.
          example: validNow
          required: false
          schema:
            type: string
            enum:
              - expired
              - validNow
              - validFuture
        - name: usable
          in: query
          description: |
            Either "true" or "false". If "true", only coupons where `usageCounter < usageLimit` will be returned, "false" will return only coupons where `usageCounter >= usageLimit`.
          example: 'false'
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
        - name: referralId
          in: query
          description: Filter the results by matching them with the ID of a referral. This filter shows the coupons created by redeeming a referral code.
          example: 47
          required: false
          schema:
            type: integer
        - name: recipientIntegrationId
          in: query
          description: Filter results by match with a profile ID specified in the coupon's RecipientIntegrationId field.
          example: customer1
          required: false
          schema:
            type: string
        - name: batchId
          in: query
          description: Filter results by batches of coupons
          example: nfinccze
          required: false
          schema:
            type: string
        - name: exactMatch
          in: query
          description: Filter results to an exact case-insensitive matching against the coupon code.
          example: false
          required: false
          schema:
            type: boolean
            default: false
        - name: campaignState
          in: query
          description: |
            Filter results by the state of the campaign.

            - `enabled`: Campaigns that are scheduled, running (activated), or expired.
            - `running`: Campaigns that are running (activated).
            - `disabled`: Campaigns that are disabled.
            - `expired`: Campaigns that are expired.
            - `archived`: Campaigns that are archived.
          example: enabled
          required: false
          schema:
            type: string
            enum:
              - enabled
              - disabled
              - archived
              - scheduled
              - running
              - expired
              - staged
      requestBody:
        $ref: '#/components/requestBodies/AttributeQuery'
      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/Coupon'
  /v1/applications/{applicationId}/campaigns/{campaignId}/referrals/{referralId}:
    delete:
      operationId: deleteReferral
      summary: Delete referral
      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 specified referral.
      tags:
        - Referrals
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
        - name: referralId
          in: path
          description: The ID of the referral code.
          example: '2154'
          required: true
          schema:
            type: string
      responses:
        '204':
          description: No Content
    put:
      operationId: updateReferral
      summary: Update referral
      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 specified referral.
      tags:
        - Referrals
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
        - name: referralId
          in: path
          description: The ID of the referral code.
          example: '2154'
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateReferral'
        description: body
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Referral'
  /v1/applications/{applicationId}/campaigns/{campaignId}/referrals/no_total:
    get:
      operationId: getReferralsWithoutTotalCount
      summary: List referrals
      description: |-
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        List all referrals of the specified campaign.
      tags:
        - Referrals
      parameters:
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
        - name: code
          in: query
          description: Filter results performing case-insensitive matching against the referral code. Both the code and the query are folded to remove all non-alpha-numeric characters.
          example: JVM8JH8F
          required: false
          schema:
            type: string
        - name: createdBefore
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the referral creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: createdAfter
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the referral creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: valid
          in: query
          description: |
            Either "expired", "validNow", or "validFuture". The first option matches referrals in which the expiration date is set and in the past. The second matches referrals in which start date is null or in the past and expiration date is null or in the future, the third matches referrals in which start date is set and in the future.
          example: validNow
          required: false
          schema:
            type: string
            enum:
              - expired
              - validNow
              - validFuture
        - name: usable
          in: query
          description: |
            Either "true" or "false". If "true", only referrals where `usageCounter < usageLimit` will be returned, "false" will return only referrals where `usageCounter >= usageLimit`.
          example: 'false'
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
        - name: advocate
          in: query
          required: false
          description: Filter results by match with a profile ID specified in the referral's AdvocateProfileIntegrationId field.
          example: customer1
          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/Referral'
  /v1/campaign_groups:
    get:
      operationId: getCampaignGroups
      summary: List campaign access groups
      description: |-
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        List the campaign access groups in the current account.
      tags:
        - Campaign access groups
      parameters:
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/sort'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - totalResultSize
                  - data
                properties:
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CampaignGroup'
  /v1/campaign_groups/{campaignGroupId}:
    get:
      operationId: getCampaignGroup
      summary: Get campaign access group
      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 a campaign access group specified by its ID.
      tags:
        - Campaign access groups
      parameters:
        - name: campaignGroupId
          in: path
          description: The ID of the campaign access group.
          example: 37
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignGroup'
  /v1/campaign_templates:
    get:
      operationId: getCampaignTemplates
      summary: List campaign templates
      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 a list of campaign templates.
      tags:
        - Campaign templates
      parameters:
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/sort'
        - name: state
          in: query
          description: Filter results by the state of the campaign template.
          example: draft
          required: false
          schema:
            type: string
            enum:
              - draft
              - enabled
              - disabled
        - name: name
          in: query
          description: Filter results performing case-insensitive matching against the name of the campaign template.
          example: template1
          required: false
          schema:
            type: string
        - name: tags
          in: query
          description: |
            Filter results performing case-insensitive matching against the tags of the campaign template. When used in conjunction with the "name" query parameter, a logical OR will be performed to search both tags and name for the provided values.
          example: tag1
          required: false
          schema:
            type: string
        - in: query
          description: Filter results by user ID.
          example: 34
          required: false
          name: userId
          schema:
            type: integer
      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/CampaignTemplate'
  /v1/applications/{applicationId}/experiments:
    get:
      operationId: listExperiments
      summary: List experiments
      description: |-
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        List all experiments of the specified Application that match your filter criteria.
      tags:
        - Experiments
      parameters:
        - name: applicationId
          in: path
          required: true
          description: The ID of the Application. It is displayed in your Talon.One deployment URL.
          example: 42
          schema:
            type: integer
        - 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
        - name: skip
          in: query
          required: false
          description: The number of items to skip when paging through large result sets.
          example: 100
          schema:
            type: integer
        - 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
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - totalResultSize
                properties:
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Experiment'
  /v1/applications/{applicationId}/experiments/{experimentId}:
    get:
      operationId: getExperiment
      summary: Get experiment in Application
      description: |-
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        Retrieve the given experiment associated with the Application.
      tags:
        - Experiments
      parameters:
        - name: applicationId
          in: path
          required: true
          description: The ID of the Application. It is displayed in your Talon.One deployment URL.
          example: 42
          schema:
            type: integer
        - name: experimentId
          in: path
          description: The ID of the experiment.
          example: 1
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Experiment'
  /v1/applications/{applicationId}/create_campaign_from_template:
    post:
      operationId: createCampaignFromTemplate
      summary: Create campaign from campaign template
      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.

        Use the campaign template referenced in the request body to create
        a new campaign in one of the connected Applications.

        If the template was created from a campaign with rules referencing [campaign collections](https://docs.talon.one/docs/product/campaigns/managing-collections),
        the corresponding collections for the new campaign are created automatically.
      tags:
        - Campaign templates
      parameters:
        - $ref: '#/components/parameters/applicationId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTemplateCampaign'
        description: body
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTemplateCampaignResponse'
  /v1/loyalty_programs:
    get:
      operationId: getLoyaltyPrograms
      summary: List loyalty programs
      description: |-
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        List the loyalty programs of the account.
      tags:
        - Loyalty
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - totalResultSize
                  - data
                properties:
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/LoyaltyProgram'
  /v1/loyalty_programs/{loyaltyProgramId}:
    get:
      operationId: getLoyaltyProgram
      summary: Get loyalty program
      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 specified [loyalty
        program](https://docs.talon.one/docs/product/loyalty-programs/overview).

        To list all loyalty programs in your Application, use [List loyalty
        programs](#tag/Loyalty/operation/getLoyaltyPrograms).

        To list the loyalty programs that a customer profile is part of, use
        [List customer data](https://docs.talon.one/integration-api#tag/Customer-profiles/operation/getCustomerInventory).
      tags:
        - Loyalty
      parameters:
        - name: loyaltyProgramId
          in: path
          required: true
          description: |
            Identifier of 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: 8
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoyaltyProgram'
  /v1/loyalty_programs/{loyaltyProgramId}/dashboard:
    get:
      operationId: getDashboardStatistics
      summary: Get statistics for loyalty dashboard
      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 statistics displayed on the specified loyalty program's
        dashboard, such as the total active points, pending points, spent points, and expired
        points.

        > [!important] The returned data does not include the current day. All statistics
        > are updated daily at 11:59 PM in the loyalty program time zone.
      tags:
        - Loyalty
      parameters:
        - name: loyaltyProgramId
          in: path
          required: true
          description: |
            Identifier of 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: 8
          schema:
            type: integer
        - name: subledgerId
          in: query
          required: false
          description: The ID of the subledger by which we filter the data.
          example: subledger1
          schema:
            type: string
        - 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
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - totalResultSize
                  - data
                properties:
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/LoyaltyDashboardData'
  /v1/loyalty_programs/{loyaltyProgramId}/import_points:
    post:
      operationId: importLoyaltyPoints
      summary: Import loyalty points
      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 points you want to import into a
        given loyalty program.

        Send the file as multipart data.

        Depending on the type of loyalty program, you can import points into a given
        customer profile or loyalty card.

        The CSV file contains the following columns:

        - `customerprofileid` (optional): For profile-based loyalty programs, the
          integration ID of the customer profile where the loyalty points are
          imported.
          **Note**: If the customer profile does not exist, it will be created. The profile will not be visible in any Application
          until a session or profile update is received for that profile.
        - `identifier` (optional): For card-based loyalty programs, the identifier of the loyalty card where the loyalty points are imported.
        - `amount`: The amount of points to award to the customer profile.
        - `startdate` (optional): The earliest date when the points can be redeemed. The points are `active` from this date until the expiration date.
          This parameter accepts one of the following values:
            - A timestamp string in RFC3339 format.
            - `immediate`
            - `on_action`
          **Note**: Empty or missing values default to `immediate`.
        - `expirydate` (optional): The latest date when the points can be redeemed.
          The points are `expired` after this date.
          **Note**: It must be an RFC3339 timestamp string or string `unlimited`. Empty or missing values are considered `unlimited`.
          If passed, `validityDuration` should be omitted.
        - `validityDuration` (optional): The duration for which the points remain active, relative to the
          activation date. The time format is an **integer** followed by one letter indicating the time unit.<br />
          Examples: `30s`, `40m`, `1h`, `5D`, `7W`, `10M`, `15Y`.

          Available units:

          - `s`: seconds
          - `m`: minutes
          - `h`: hours
          - `D`: days
          - `W`: weeks
          - `M`: months
          - `Y`: years

          You can round certain units up or down:

          - `_D` for rounding down days only. Signifies the start of the day.
          - `_U` for rounding up days, weeks, months and years. Signifies the end of
          the day, week, month or year.

          If passed, `expirydate` should be omitted.
        - `subledgerid` (optional): The ID of the subledger that should received the points.
        - `reason` (optional): The reason why these points are awarded.

        You can use the time zone of your choice. It is converted to UTC internally by Talon.One.

        > [!note] For existing customer profiles and loyalty cards, the imported
        > points are added to any previous active or pending points, depending on the
        > value provided for `startdate`. If `startdate` matches the current date, the
        > imported points are _active_. If it is later, the points are _pending_ until
        > the date provided for `startdate` is reached.

        > [!note] We recommend limiting your file size to 500 MB.

        ## Example for profile-based programs

        ```text
        customerprofileid,amount,startdate,expirydate,subledgerid,reason
        URNGV8294NV,100,2009-11-10T23:00:00Z,2009-11-11T23:00:00Z,subledger1,appeasement
        ```

        ## Example for card-based programs

        ```text
        identifier,amount,startdate,expirydate,subledgerid,reason
        summer-loyalty-card-0543,100,2009-11-10T23:00:00Z,2009-11-11T23:00:00Z,subledger1,appeasement
        ```
      tags:
        - Loyalty
      parameters:
        - name: loyaltyProgramId
          in: path
          required: true
          description: |
            Identifier of 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: 8
          schema:
            type: integer
        - name: notificationsEnabled
          in: query
          description: |
            Indicates whether the points import triggers notifications about its effects. For example, a notification is sent if the import upgrades a customer's tier or offsets their negative points balance.

            This parameter is optional and defaults to `true`.
          example: true
          required: false
          schema:
            type: boolean
      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'
  /v1/loyalty_programs/{loyaltyProgramId}/import_customers_tiers:
    post:
      operationId: importLoyaltyCustomersTiers
      summary: Import customers into loyalty tiers
      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 existing customers to be assigned to existing
        tiers.

        Send the file as multipart data.

        > [!important] This endpoint only works with loyalty programs with advanced
        > tiers (with expiration and downgrade policy) feature enabled.

        The CSV file should contain the following columns:

        - `subledgerid` (optional): The ID of the subledger. If this field is empty,
        the main ledger will be used.
        - `customerprofileid`: The integration ID of the customer profile to whom
        the tier should be assigned.
        - `tiername`: The name of an existing tier to assign to the customer.
        - `expirydate`: The expiry date of the tier when the tier is
        reevaluated. It should be a future date.

        About customer assignment to a tier:

        - If the customer isn't already in a tier, the customer is assigned to the
        specified tier during the tier import.
        - If the customer is already in the tier that's specified in the CSV file,
        only the expiry date is updated.

        > [!note] We recommend importing customers into the tier that matches their
        > current balance. If a customer is imported into a lower tier, any session
        > or points update automatically upgrades them to the tier they qualify for.

        To update a customer's tier, you can
        [add](/management-api#tag/Loyalty/operation/addLoyaltyPoints) or
        [deduct](/management-api#tag/Loyalty/operation/removeLoyaltyPoints) their
        loyalty points.

        You can use the time zone of your choice. It is converted to UTC internally
        by Talon.One.

        > [!note] We recommend limiting your file size to 500 MB.

        ## Example

        ```csv
        subledgerid,customerprofileid,tiername,expirydate
        SUB1,alexa,Gold,2024-03-21T07:32:14Z
        ,george,Silver,2025-04-16T21:12:37Z
        SUB2,avocado,Bronze,2026-05-03T11:47:01Z
        ```
      tags:
        - Loyalty
      parameters:
        - name: loyaltyProgramId
          in: path
          required: true
          description: |
            Identifier of 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: 8
          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'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v1/loyalty_programs/{loyaltyProgramId}/import_join_dates:
    post:
      operationId: importLoyaltyJoinDates
      summary: Import join dates for a loyalty program
      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 customer profile IDs and their join dates for the
        specified loyalty program. Send the file as multipart data.

        > [!important] This endpoint only works with profile-based loyalty programs.

        The CSV file **must** contain the following columns:

        - `customerprofileid`: The integration ID of the customer profile whose join
          date you want to update.
        - `joindate`: The join date for the customer in RFC3339 format. You
          can use the time zone of your choice. It is converted to UTC internally
          by Talon.One.

        **Note**:
        - Customer profiles must already exist. If a referenced profile does not exist, the import fails with a `400` error.
        - If a join date already exists for a profile, the uploaded date replaces it.
        - If a join date is in the future at the time of the import, the import fails with a `400` error.

        > [!note] We recommend limiting your file size to 500 MB.

        ## Example

        ```csv
        customerprofileid,joindate
        customer1,2024-03-21T07:32:14Z
        customer2,2025-04-16T21:12:37Z
        customer3,2026-05-03T11:47:01Z
        ```
      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: 8
          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'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}:
    get:
      operationId: getLoyaltyPoints
      summary: Get customer's full loyalty ledger
      deprecated: true
      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 loyalty ledger for this profile integration ID.

        To get the `integrationId` of the profile from a `sessionId`, use the
        [Update customer session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2) endpoint.

        **Important:** To get loyalty transaction logs for a given Integration ID in a loyalty program,
        we recommend using the Integration API's [Get customer's loyalty logs](https://docs.talon.one/integration-api#tag/Loyalty/operation/getLoyaltyProgramProfileTransactions).
      tags:
        - Loyalty
      parameters:
        - name: loyaltyProgramId
          in: path
          description: The identifier for the loyalty program.
          example: '45'
          required: true
          schema:
            type: string
        - 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
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoyaltyLedger'
  /v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}/add_points:
    put:
      operationId: addLoyaltyPoints
      summary: Add points to customer profile
      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 in the specified loyalty program for the given customer.

        To get the `integrationId` of the profile from a `sessionId`, use the
        [Update customer session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2) endpoint.
      tags:
        - Loyalty
      parameters:
        - name: loyaltyProgramId
          in: path
          description: The identifier for the loyalty program.
          example: '45'
          required: true
          schema:
            type: string
        - 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
      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'
  /v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}/deduct_points:
    put:
      operationId: removeLoyaltyPoints
      summary: Deduct points from customer profile
      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 specified loyalty program and specified customer
        profile.

        > [!note] **Note**
        > - Only active points can be deducted.
        > - Only pending points are rolled back when a session is cancelled or reopened.

        To get the `integrationId` of the profile from a `sessionId`, use the
        [Update customer session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2)
        endpoint.
      tags:
        - Loyalty
      parameters:
        - name: loyaltyProgramId
          in: path
          description: The identifier for the loyalty program.
          example: '45'
          required: true
          schema:
            type: string
        - 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
      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'
  /v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}/export_log:
    get:
      operationId: exportLoyaltyLedger
      summary: Export customer's 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 a customer's transaction logs 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 generated file can contain the following columns:

        - `customerprofileid`: The ID of the profile.
        - `customersessionid`: The ID of the customer session.
        - `rulesetid`: The ID of the rule set.
        - `rulename`: The name of the rule.
        - `programid`: The ID of the loyalty program.
        - `type`: The transaction type, such as `addition` or `subtraction`.
        - `name`: The reason for the transaction.
        - `subledgerid`: The ID of the subledger, when applicable.
        - `startdate`: The start date of the program.
        - `expirydate`: The expiration date of the program.
        - `id`: The ID of the transaction.
        - `created`: The timestamp of the creation of the loyalty program.
        - `amount`: The number of points in that transaction.
        - `archived`: Whether the session related to the transaction is archived.
        - `campaignid`: The ID of the campaign.
        - `flags`: The flags of the transaction, when applicable. The `createsNegativeBalance` flag indicates whether the transaction results in a negative balance.
        - `transactionUUID`: Unique identifier of the transaction in the UUID format.
        - `validityDuration`: The duration for which the points remain active, relative to the activation date.
        - `remainingAmount`: The current unused amount of points, when applicable to `addition` transactions.
      tags:
        - Loyalty
      parameters:
        - 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
        - name: loyaltyProgramId
          in: path
          description: The identifier for the loyalty program.
          example: '45'
          required: true
          schema:
            type: string
        - 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
      responses:
        '200':
          description: OK
          content:
            application/csv:
              schema:
                type: string
                format: csv
              examples:
                response:
                  value: |
                    customerprofileid,customersessionid,rulesetid,rulename,programid,type,name,subledgerid,startdate,expirydate,id,created,amount,archived,campaignid,flags,transactionuuid,validityDuration,remainingAmount
                    8NHOS78H,06b0fafb-ccbf-42c7-b44b-d858e8b525022,1691,test,37,subtraction,10% of current total,,immediate,unlimited,60803,2022-11-29 16:16:10,100.00,false,5,createsNegativeBalance,8c122fb1-1874-4ee2-b7e2-e7b5f8b7b801,"",
                    EB780RDN,06b0fafb-ccbf-42c7-b44b-d858e8b525022,1691,test,37,addition,Reimbursed loyalty points,,on_action,unlimited,60804,2022-11-29 16:16:23,100.00,false,5,,8c122fb1-1874-4ee2-b7e2-e7b5f8b7b801,"30D",100.00
  /v1/loyalty_programs/{loyaltyProgramId}/export_join_dates:
    get:
      operationId: exportLoyaltyJoinDates
      summary: Export customers' loyalty program join dates
      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 join dates of all customers 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 generated file can contain the following columns:

        - `loyaltyProgramID`: The ID of the loyalty program.
        - `profileIntegrationID`: The integration ID of the customer profile.
        - `joinDate`: The customer's loyalty program join date in RFC3339 format.
      tags:
        - Loyalty
      parameters:
        - name: loyaltyProgramId
          in: path
          description: The identifier of the loyalty program.
          example: '45'
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/csv:
              schema:
                type: string
                format: csv
              examples:
                response:
                  value: |
                    loyaltyProgramID,profileIntegrationID,joinDate
                    40,8786NTHSAO8,2024-05-29T15:04:05Z
                    40,2735HATHOH8,2023-11-13T07:12:34Z
        '400':
          description: Bad request
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '401':
          description: Unauthorized
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v1/loyalty_programs/{loyaltyProgramId}/export_customers_tiers:
    get:
      operationId: exportCustomersTiers
      summary: Export customers' tier 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.

        Download a CSV file containing the tier information for customers of the specified loyalty program.

        The generated file contains the following columns:

        - `programid`: The identifier of the loyalty program. It is displayed in your Talon.One deployment URL.
        - `subledgerid`: The ID of the subledger associated with the loyalty program. This column is empty if the loyalty program has no subledger. In this case, refer to the export file name to get the ID of the loyalty program.
        - `customerprofileid`: The ID used to integrate customer profiles with the loyalty program.
        - `tiername`: The name of the tier.
        - `startdate`: The tier start date in RFC3339.
        - `expirydate`: The tier expiry date in RFC3339.

        You can filter the results by providing the following optional input parameters:

        - `subledgerIds` (optional): Filter results by an array of subledger IDs. If no value is provided, all subledger data for the specified loyalty program will be exported.
        - `tierNames` (optional): Filter results by an array of tier names. If no value is provided, all tier data for the specified loyalty program will be exported.
      tags:
        - Loyalty
      parameters:
        - name: loyaltyProgramId
          in: path
          description: The identifier for the loyalty program.
          example: '45'
          required: true
          schema:
            type: string
        - name: subledgerIds
          in: query
          required: false
          description: An array of subledgers IDs to filter the export by.
          example:
            - subledger1
            - subledger2
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
        - name: tierNames
          in: query
          required: false
          description: An array of tier names to filter the export by.
          example:
            - tier1
            - tier2
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: OK
          content:
            application/csv:
              schema:
                type: string
                format: csv
              examples:
                response:
                  value: |
                    programid,subledgerid,customerprofileid,tiername,startdate,expirydate
                    1,SUB1,Dinesh,Golden,2023-08-02T15:04:05Z07:00,2024-08-02T15:04:05Z07:00
                    1,SUB2,Gilfoyle,Silver,2023-03-21T03:45:12Z05:00,2026-03-21T03:45:12Z05:00
  /v1/loyalty_programs/{loyaltyProgramId}/statistics:
    get:
      operationId: getLoyaltyStatistics
      summary: Get loyalty program statistics
      deprecated: true
      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.

        > [!warning] This endpoint is deprecated.

        To retrieve statistics for a loyalty program, use the
        [Get statistics for loyalty dashboard](/management-api#tag/Loyalty/operation/getDashboardStatistics)
        endpoint.

        Retrieve the statistics of the specified loyalty program, such as the
        total active points, pending points, spent points, and expired points.
      tags:
        - Loyalty
      parameters:
        - name: loyaltyProgramId
          in: path
          required: true
          description: |
            Identifier of 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: 8
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoyaltyDashboardData'
  /v1/loyalty_programs/{loyaltyProgramId}/export_customer_balances:
    get:
      operationId: exportLoyaltyBalances
      summary: Export customer loyalty balances
      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 balance of each customer 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 generated file contains the following columns:

        - `loyaltyProgramID`: The ID of the loyalty program.
        - `loyaltySubledger`: The name of the subledger, when applicable.
        - `profileIntegrationID`: The integration ID of the customer profile.
        - `currentBalance`: The current point balance.
        - `pendingBalance`: The number of pending points.
        - `expiredBalance`: The number of expired points.
        - `spentBalance`: The number of spent points.
        - `currentTier`: The tier that the customer is in at the time of the export.
        - `negativeBalance`: The number of negative points. Only contains a value when requested via `balances` and the program uses negative points.
      tags:
        - Loyalty
      parameters:
        - name: loyaltyProgramId
          in: path
          description: The identifier for the loyalty program.
          example: '45'
          required: true
          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.
            > - This parameter does not affect the `currentTier` field in the CSV file, which shows the customer's tier at the time of export.
          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. `currentBalance`
            is always returned.

            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.
          example: currentBalance,pendingBalance
          schema:
            type: string
        - name: subledgerIds
          in: query
          required: false
          description: |
            Filters the results to specific subledgers.

            **Note:**
            - When this parameter is not provided, the export includes all subledgers
              and main ledger data for the specified loyalty program.
          example:
            - subledger1
            - subledger2
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: OK
          content:
            application/csv:
              schema:
                type: string
                format: csv
              examples:
                response:
                  value: |
                    loyaltyProgramID,loyaltySubledger,profileIntegrationID,currentBalance,pendingBalance,expiredBalance,spentBalance,currentTier,negativeBalance
                    40,,8786NTHSAO8,10.00,0.00,0.00,0.00,First,0.00
                    40,,2735HATHOH8,20.00,0.00,0.00,0.00,First,0.00
        '400':
          description: Bad request
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '401':
          description: Unauthorized
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v1/loyalty_programs/{loyaltyProgramId}/export_customer_balance:
    get:
      operationId: exportLoyaltyBalance
      summary: Export customer loyalty balance to CSV
      deprecated: true
      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.

        To export customer loyalty balances to CSV, use the [Export customer loyalty
        balances to CSV](/management-api#tag/Loyalty/operation/exportLoyaltyBalances) endpoint.

        Download a CSV file containing the balance of each customer 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).
      tags:
        - Loyalty
      parameters:
        - name: loyaltyProgramId
          in: path
          description: The identifier for the loyalty program.
          example: '45'
          required: true
          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: balances
          in: query
          required: false
          description: |
            Filters which balance fields are included in the CSV export. `currentBalance`
            is always returned.

            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.
          example: currentBalance,pendingBalance
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/csv:
              schema:
                type: string
                format: csv
        '400':
          description: Bad request
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '401':
          description: Unauthorized
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v1/loyalty_programs/{loyaltyProgramId}/transactions:
    get:
      operationId: getLoyaltyProgramTransactions
      summary: List loyalty program transactions
      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 loyalty program transaction logs in a given loyalty program with
        filtering options applied. Manual and imported transactions are also
        included.

        > [!note] **Note**
        > - If no filters are applied, the last 50 loyalty transactions for the given loyalty program are returned.
        > - To get loyalty transaction logs for a given Integration ID in
        >   a loyalty program, we recommend using the Integration API's [Get customer's loyalty
        >   logs](https://docs.talon.one/integration-api#tag/Loyalty/operation/getLoyaltyProgramProfileTransactions).
      tags:
        - Loyalty
      parameters:
        - name: loyaltyProgramId
          in: path
          required: true
          description: |
            Identifier of 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: 8
          schema:
            type: integer
        - 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: 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
        - 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/LoyaltyProgramTransaction'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v1/loyalty_programs/{loyaltyProgramId}/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'
  /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'
  /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'
  /v1/loyalty_programs/{loyaltyProgramId}/cards:
    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'
  /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'
  /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'
    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'
    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'
  /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'
  /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'
  /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).

        The generated file can contain the following columns:

        - `cardidentifier`: The identifier of the loyalty card.
        - `applicationid`: The ID of the Application.
        - `sessionid`: The ID of the session.
        - `customersessionid`: The integration ID of the customer session.
        - `rulesetid`: The ID of the rule set.
        - `rulename`: The name of the rule.
        - `programid`: The ID of the loyalty program.
        - `type`: The transaction type, such as `addition` or `subtraction`.
        - `name`: The reason for the transaction.
        - `subledgerid`: The ID of the subledger, when applicable.
        - `startdate`: The start date of the points.
        - `expirydate`: The expiration date of the points.
        - `id`: The ID of the transaction.
        - `created`: The timestamp of the transaction creation.
        - `amount`: The number of points in that transaction.
        - `archived`: Whether the session related to the transaction is archived.
        - `campaignid`: The ID of the campaign.
        - `transactionUUID`: Unique identifier of the transaction in the UUID format.
        - `validityDuration`: The duration for which the points remain active, relative to the activation date.
        - `remainingAmount`: The current unused amount of points, when applicable to `addition` transactions.
      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
              examples:
                response:
                  value: |
                    cardidentifier,applicationid,sessionid,customersessionid,rulesetid,rulename,programid,type,name,subledgerid,startdate,expirydate,id,created,amount,archived,campaignid,transactionuuid,validityDuration,remainingAmount
                    summer-card-0543,1,10,session-123,1691,test,37,addition,Add points,,immediate,unlimited,60804,2022-11-29 16:16:23,100.00,false,5,8c122fb1-1874-4ee2-b7e2-e7b5f8b7b801,"",100.00
        '401':
          description: Unauthorized
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '404':
          description: Not found
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /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'
  /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.

        Transfer loyalty card data, such as linked customers, loyalty balances and
        transactions, from a given loyalty card to a new, automatically created
        loyalty card.

        > [!important] **Note**
        > - The original card is automatically blocked once the new card is created,
            and it cannot be activated again.
        > - The default status of the new card is _active_.
      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'
  /v1/giveaways/pools:
    get:
      operationId: listGiveawaysPool
      summary: List giveaway pools
      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 all the giveaway pools for an account.
      tags:
        - Giveaways
      parameters:
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/sort'
        - name: withTotalResultSize
          in: query
          description: |
            When this flag is set, the result includes the total number of results for this query. This might decrease performance on large data sets.

            - When `true`: `totalResultSize` contains the total number of results for this query.
            - When `false`: Only `hasMore` is returned, and it is set to `true` when there are more results than shown on the page.
          example: false
          schema:
            type: boolean
        - name: applicationIds
          in: query
          required: false
          description: Filter by one or more Application IDs, separated by a comma.
          example: 23,44
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  hasMore:
                    type: boolean
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/GiveawaysPool'
  /v1/giveaways/pools/{poolId}:
    get:
      operationId: getGiveawaysPool
      summary: Get giveaway pool
      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 details of a specified giveaway pool.
      tags:
        - Giveaways
      parameters:
        - name: poolId
          description: The ID of the pool. You can find it in the Campaign Manager, in the **Incentives** section.
          in: path
          example: 6
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GiveawaysPool'
  /v1/giveaways/pools/{poolId}/import:
    post:
      operationId: importPoolGiveaways
      summary: Import giveaway codes into a giveaway pool
      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 giveaway codes that should be created. Send
        the file as multipart data.

        The CSV file contains the following columns:

        - `code` (required): The code of your giveaway, for instance, a gift card redemption code.
        - `startdate`:  The start date in RFC3339 of the code redemption period.
        - `enddate`: The last date in RFC3339 of the code redemption period.
        - `attributes`: A JSON object describing _custom_ giveaway attribute names and their values, enclosed with double quotation marks.<br />
          For example, if you created a [custom attribute](https://docs.talon.one/docs/dev/concepts/attributes#custom-attributes)
          called `provider` associated with the giveaway entity, the object in the CSV file, when opened in a text editor, must be: `"{"provider": "myPartnerCompany"}"`.

        The `startdate` and `enddate` have nothing to do with the _validity_ of the
        codes. They are only used by the Rule Engine to award the codes or not.

        You can use the time zone setting of your choice. The values are converted
        to UTC internally by Talon.One.

        > [!note] **Note**
        > - We recommend limiting your file size to 500MB.
        > - You can import the same code multiple times. Duplicate codes are treated and distributed to customers as unique codes.

        ## Example

        ```text
        code,startdate,enddate,attributes
        GIVEAWAY1,2020-11-10T23:00:00Z,2022-11-11T23:00:00Z,"{""provider"":
        ""Amazon""}"
        GIVEAWAY2,2020-11-10T23:00:00Z,2022-11-11T23:00:00Z,"{""provider"":
        ""Amazon""}"
        GIVEAWAY3,2021-01-10T23:00:00Z,2022-11-11T23:00:00Z,"{""provider"":
        ""Aliexpress""}"
        ```
      tags:
        - Giveaways
      parameters:
        - name: poolId
          description: The ID of the pool. You can find it in the Campaign Manager, in the **Giveaways** section.
          in: path
          example: 8
          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'
  /v1/giveaways/pools/{poolId}/export:
    get:
      operationId: exportPoolGiveaways
      summary: Export giveaway codes of a giveaway pool
      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 giveaway codes of a specific giveaway
        pool.

        > [!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:

        - `id`: The internal ID of the giveaway.
        - `poolid`: The internal ID of the giveaway pool.
        - `code`: The giveaway code.
        - `startdate`: The validity start date in RFC3339 of the giveaway (can be empty).
        - `enddate`: The validity end date in RFC3339 of the giveaway (can be empty).
        - `attributes`: Any custom attributes associated with the giveaway code (can be empty).
        - `used`: An indication of whether the giveaway is already awarded.
        - `importid`: The ID of the import which created the giveaway.
        - `created`: The creation time of the giveaway code.
        - `profileintegrationid`: The third-party integration ID of the customer
           profile that was awarded the giveaway. Can be empty if the giveaway was not
           awarded.
        - `profileid`: The internal ID of the customer profile that was awarded the
           giveaway. Can be empty if the giveaway was not awarded or an internal ID
           does not exist.
      tags:
        - Giveaways
      parameters:
        - name: poolId
          description: The ID of the pool. You can find it in the Campaign Manager, in the **Giveaways** section.
          in: path
          example: 8
          required: true
          schema:
            type: integer
        - name: createdBefore
          description: Timestamp that filters the results to only contain giveaways created before this date. Must be an RFC3339 timestamp string.
          in: query
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: createdAfter
          description: Timestamp that filters the results to only contain giveaways created after this date. Must be an RFC3339 timestamp string.
          in: query
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: OK
          content:
            application/csv:
              schema:
                type: string
                format: csv
              examples:
                response:
                  value: |
                    id,poolid,code,startdate,enddate,attributes,used,importid,created,profileintegrationid,profileid
                    1,7,af18bc3839799451fb6d6b6467cf4c25e,2023-04-11T12:47:47Z,2024-04-11T12:47:47Z,"{""attribute"": ""value""}",true,2,2023-04-11T12:47:47Z,R195412,35
        '400':
          description: Bad request
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v1/collections:
    get:
      operationId: listAccountCollections
      summary: List collections in account
      description: |-
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        List account-level collections in the account.
      tags:
        - Collections
      parameters:
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/sort'
        - name: withTotalResultSize
          in: query
          description: |
            When this flag is set, the result includes the total number of results for this query. This might decrease performance on large data sets.

            - When `true`: `totalResultSize` contains the total number of results for this query.
            - When `false`: Only `hasMore` is returned, and it is set to `true` when there are more results than shown on the page.
          example: false
          schema:
            type: boolean
        - name: name
          in: query
          description: Filter by collection name.
          example: collection1
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  hasMore:
                    type: boolean
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CollectionWithoutPayload'
        '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'
    post:
      operationId: createAccountCollection
      summary: Create account-level collection
      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 an account-level collection.
      tags:
        - Collections
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewCollection'
        description: body
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '409':
          description: Conflict. A collection with this name already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v1/collections/{collectionId}:
    get:
      operationId: getAccountCollection
      summary: Get account-level collection
      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 a given account-level collection.
      tags:
        - Collections
      parameters:
        - name: collectionId
          in: path
          required: true
          description: The ID of the collection. You can get it with the [List collections in account](#tag/Collections/operation/listAccountCollections) endpoint.
          example: 22
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
    put:
      operationId: updateAccountCollection
      summary: Update account-level collection
      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.

        Edit the description of a given account-level collection and enable or disable the collection in the specified Applications.
      tags:
        - Collections
      parameters:
        - name: collectionId
          in: path
          required: true
          description: The ID of the collection. You can get it with the [List collections in account](#tag/Collections/operation/listAccountCollections) endpoint.
          example: 22
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCollection'
        description: body
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '409':
          description: Conflict. A collection with this name already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
    delete:
      operationId: deleteAccountCollection
      summary: Delete account-level collection
      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 a given account-level collection.
      tags:
        - Collections
      parameters:
        - name: collectionId
          in: path
          required: true
          description: The ID of the collection. You can get it with the [List collections in account](#tag/Collections/operation/listAccountCollections) endpoint.
          example: 22
          schema:
            type: integer
      responses:
        '204':
          description: No Content
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v1/collections/{collectionId}/items:
    get:
      operationId: getCollectionItems
      summary: Get collection items
      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 items from a given collection.

        You can retrieve items from both account-level collections and campaign-level collections using this endpoint.
      tags:
        - Collections
      parameters:
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - name: collectionId
          in: path
          required: true
          description: The ID of the collection. You can get it with the [List collections in account](#tag/Collections/operation/listAccountCollections) endpoint.
          example: 22
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - hasMore
                  - data
                properties:
                  hasMore:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CollectionItem'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v1/applications/{applicationId}/collections:
    get:
      operationId: listCollectionsInApplication
      summary: List collections in Application
      description: |-
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        List campaign-level collections from all campaigns in a given Application.
      tags:
        - Collections
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/sort'
        - name: withTotalResultSize
          in: query
          description: |
            When this flag is set, the result includes the total number of results for this query. This might decrease performance on large data sets.

            - When `true`: `totalResultSize` contains the total number of results for this query.
            - When `false`: Only `hasMore` is returned, and it is set to `true` when there are more results than shown on the page.
          example: false
          schema:
            type: boolean
        - name: name
          in: query
          description: Filter by collection name.
          example: collection1
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  hasMore:
                    type: boolean
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CollectionWithoutPayload'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v1/applications/{applicationId}/campaigns/{campaignId}/collections:
    get:
      operationId: listCollections
      summary: List collections in campaign
      description: |-
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        List collections in a given campaign.
      tags:
        - Collections
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/sort'
        - name: withTotalResultSize
          in: query
          description: |
            When this flag is set, the result includes the total number of results for this query. This might decrease performance on large data sets.

            - When `true`: `totalResultSize` contains the total number of results for this query.
            - When `false`: Only `hasMore` is returned, and it is set to `true` when there are more results than shown on the page.
          example: false
          schema:
            type: boolean
        - name: name
          in: query
          description: Filter by collection name.
          example: collection1
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  hasMore:
                    type: boolean
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CollectionWithoutPayload'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
    post:
      operationId: createCollection
      summary: Create campaign-level collection
      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 campaign-level collection in a given campaign.
      tags:
        - Collections
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewCampaignCollection'
        description: body
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
  /v1/applications/{applicationId}/campaigns/{campaignId}/collections/{collectionId}:
    get:
      operationId: getCollection
      summary: Get campaign-level collection
      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 a given campaign-level collection.
      tags:
        - Collections
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
        - name: collectionId
          in: path
          required: true
          description: The ID of the collection. You can get it with the [List collections in Application](#tag/Collections/operation/listCollectionsInApplication) endpoint.
          example: 44
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
    put:
      operationId: updateCollection
      summary: Update campaign-level collection's description
      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.

        Edit the description of a given campaign-level collection.
      tags:
        - Collections
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
        - name: collectionId
          in: path
          required: true
          description: The ID of the collection. You can get it with the [List collections in Application](#tag/Collections/operation/listCollectionsInApplication) endpoint.
          example: 44
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCampaignCollection'
        description: body
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
    delete:
      operationId: deleteCollection
      summary: Delete campaign-level collection
      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 a given campaign-level collection.
      tags:
        - Collections
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
        - name: collectionId
          in: path
          required: true
          description: The ID of the collection. You can get it with the [List collections in Application](#tag/Collections/operation/listCollectionsInApplication) endpoint.
          example: 44
          schema:
            type: integer
      responses:
        '204':
          description: No Content
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v1/collections/{collectionId}/import:
    post:
      operationId: importAccountCollection
      summary: Import data into existing account-level collection
      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 collection of string values that should be
        attached as payload for collection.

        The file should be sent as multipart data.

        The import **replaces** the initial content of the collection.

        The CSV file **must** only contain the following column:

        - `item`: the values in your collection.

        A collection is limited to 500,000 items.

        ## Example

        ```
        item
        Adidas
        Nike
        Asics
        ```

        > [!note] Before sending a request to this endpoint, ensure the data in the
        > CSV to import is different from the data currently stored in the collection.
      tags:
        - Collections
      parameters:
        - name: collectionId
          in: path
          required: true
          description: The ID of the collection. You can get it with the [List collections in account](#tag/Collections/operation/listAccountCollections) endpoint.
          example: 22
          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'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v1/applications/{applicationId}/campaigns/{campaignId}/collections/{collectionId}/import:
    post:
      operationId: importCollection
      summary: Import data into existing campaign-level collection
      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 collection of string values that should be
        attached as payload for collection.

        The file should be sent as multipart data.

        The import **replaces** the initial content of the collection.

        The CSV file **must** only contain the following column:

        - `item`: the values in your collection.

        A collection is limited to 500,000 items.

        ## Example

        ```
        item
        Adidas
        Nike
        Asics
        ```

        > [!note] Before sending a request to this endpoint, ensure the data in the
        > CSV to import is different from the data currently stored in the collection.
      tags:
        - Collections
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
        - name: collectionId
          in: path
          required: true
          description: The ID of the collection. You can get it with the [List collections in Application](#tag/Collections/operation/listCollectionsInApplication) endpoint.
          example: 44
          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'
  /v1/collections/{collectionId}/export:
    get:
      operationId: exportAccountCollectionItems
      summary: Export account-level collection's items
      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 items from a given account-level collection.

        > [!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:
        - Collections
      parameters:
        - name: collectionId
          in: path
          required: true
          description: The ID of the collection. You can get it with the [List collections in account](#tag/Collections/operation/listAccountCollections) endpoint.
          example: 22
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/csv:
              schema:
                type: string
                format: csv
              examples:
                response:
                  value: |
                    item
                    SKU1
                    SKU2
                    SKU3
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '404':
          description: Not found
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v1/applications/{applicationId}/campaigns/{campaignId}/collections/{collectionId}/export:
    get:
      operationId: exportCollectionItems
      summary: Export campaign-level collection's items
      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 items from a given campaign-level collection.

        > [!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:
        - Collections
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
        - name: collectionId
          in: path
          required: true
          description: The ID of the collection. You can get it with the [List collections in Application](#tag/Collections/operation/listCollectionsInApplication) endpoint.
          example: 44
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/csv:
              schema:
                type: string
                format: csv
              examples:
                response:
                  value: |
                    item
                    SKU1
                    SKU2
                    SKU3
        '401':
          description: Unauthorized
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '404':
          description: Not found
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v1/applications/{applicationId}/health_report:
    get:
      operationId: getApplicationApiHealth
      summary: Get Application health
      description: |
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        Display the health of the Application and show the last time the Application
        was used.

        You can also find this information in the Campaign Manager. In your Application, click **Settings** > **Integration API Keys**.
        See the [docs](https://docs.talon.one/docs/dev/tutorials/monitoring-integration-status).
      tags:
        - Applications
      parameters:
        - $ref: '#/components/parameters/applicationId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationApiHealth'
  /v1/applications/{applicationId}/access_logs/no_total:
    get:
      operationId: getAccessLogsWithoutTotalCount
      summary: Get access logs for Application
      description: |
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        Retrieve the list of API calls sent to the specified Application.
      tags:
        - Logs
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - name: path
          in: query
          description: Only return results where the request path matches the given regular expression.
          example: pattern1
          schema:
            type: string
        - name: method
          in: query
          description: Only return results where the request method matches the given regular expression.
          example: get
          schema:
            type: string
            enum:
              - get
              - put
              - post
              - delete
              - patch
        - name: status
          in: query
          description: Filter results by HTTP status codes.
          example: success
          required: false
          schema:
            type: string
            enum:
              - success
              - error
        - 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
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/sort'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - hasMore
                  - data
                properties:
                  hasMore:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AccessLogEntry'
  /v1/applications/{applicationId}/campaigns/{campaignId}/analytics:
    get:
      operationId: getCampaignAnalytics
      summary: Get analytics of campaigns
      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 statistical data about the performance of the given campaign.
      tags:
        - Campaigns
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
        - 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: granularity
          in: query
          description: The time interval between the results in the returned time-series.
          example: 1 hour
          schema:
            type: string
            enum:
              - 1 hour
              - 1 day
              - 1 week
              - 1 month
              - 1 year
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - totalResultSize
                  - data
                properties:
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CampaignAnalytics'
  /v1/applications/{applicationId}/customers:
    get:
      operationId: getApplicationCustomers
      summary: List application's customers
      description: |-
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        List all the customers of the specified application.
      tags:
        - Customer data
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - name: integrationId
          in: query
          description: Filter results performing an exact matching against the profile integration identifier.
          example: customer1
          required: false
          schema:
            type: string
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - name: withTotalResultSize
          in: query
          description: |
            When this flag is set, the result includes the total number of results for this query. This might decrease performance on large data sets.

            - When `true`: `totalResultSize` contains the total number of results for this query.
            - When `false`: Only `hasMore` is returned, and it is set to `true` when there are more results than shown on the page.
          example: false
          schema:
            type: boolean
        - name: withLoyaltyMemberships
          in: query
          description: When set to `true`, the `loyaltyProgramJoinDates` property returns the dates on which each customer joined the profile-based loyalty programs they are part of. This might decrease performance on large data sets.
          example: false
          schema:
            type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  totalResultSize:
                    type: integer
                    example: 1
                  hasMore:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApplicationCustomer'
  /v1/applications/{applicationId}/customer_search:
    post:
      operationId: getApplicationCustomersByAttributes
      summary: List application customers matching the given attributes
      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 a list of the application customers matching the provided criteria.

        The match is successful if all the attributes of the request are found in a profile, even if the profile has more attributes that are not present on the request.
      tags:
        - Customer data
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - name: withTotalResultSize
          in: query
          description: |
            When this flag is set, the result includes the total number of results for this query. This might decrease performance on large data sets.

            - When `true`: `totalResultSize` contains the total number of results for this query.
            - When `false`: Only `hasMore` is returned, and it is set to `true` when there are more results than shown on the page.
          example: false
          schema:
            type: boolean
        - name: withLoyaltyMemberships
          in: query
          description: When set to `true`, the `loyaltyProgramJoinDates` property returns the dates on which each customer joined the profile-based loyalty programs they are part of. This might decrease performance on large data sets.
          example: false
          schema:
            type: boolean
      requestBody:
        $ref: '#/components/requestBodies/CustomerProfileSearchQuery'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  hasMore:
                    type: boolean
                  totalResultSize:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApplicationCustomer'
  /v1/customer_search/no_total:
    post:
      operationId: getCustomersByAttributes
      summary: List customer profiles matching the given attributes
      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 a list of the customer profiles matching the provided criteria.

        The match is successful if all the attributes of the request are found in a profile, even if the profile has more attributes that are not present on the request.
      tags:
        - Customer data
      parameters:
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - name: sandbox
          in: query
          description: Indicates whether you are pointing to a sandbox or live customer.
          example: false
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        $ref: '#/components/requestBodies/CustomerProfileSearchQuery'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  hasMore:
                    type: boolean
                  totalResultSize:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomerProfile'
  /v1/customers/{customerId}:
    get:
      operationId: getCustomerProfile
      summary: Get customer profile
      description: |
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        Return the details of the specified customer profile.

        > [!note]
        > You can retrieve the same information via the Integration API, which can save you extra API requests. Consider these options:
        > - Request the customer profile to be part of the response content using
        >   [Update Customer Session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2).
        > - Send an empty update with the [Update Customer Profile](https://docs.talon.one/integration-api#tag/Customer-profiles/operation/updateCustomerProfileV2) endpoint with `runRuleEngine=false`.
      tags:
        - Customer data
      parameters:
        - name: customerId
          in: path
          description: |
            The value of the `id` property of a customer profile. Get it with the
            [List Application's customers](https://docs.talon.one/management-api#tag/Customer-data/operation/getApplicationCustomers) endpoint.
          example: 3778
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerProfile'
  /v1/customers/no_total:
    get:
      operationId: getCustomerProfiles
      summary: List customer profiles
      description: |-
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        List all customer profiles.
      tags:
        - Customer data
      parameters:
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - name: sandbox
          in: query
          description: Indicates whether you are pointing to a sandbox or live customer.
          example: false
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - hasMore
                  - data
                properties:
                  hasMore:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomerProfile'
  /v1/applications/{applicationId}/customers/{customerId}:
    get:
      operationId: getApplicationCustomer
      summary: Get application's customer
      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 customers of the specified application.
      tags:
        - Customer data
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - name: customerId
          in: path
          description: |
            The value of the `id` property of a customer profile. Get it with the
            [List Application's customers](https://docs.talon.one/management-api#tag/Customer-data/operation/getApplicationCustomers) endpoint.
          example: 3778
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationCustomer'
  /v1/applications/{applicationId}/customer_activity_reports/no_total:
    get:
      operationId: getCustomerActivityReportsWithoutTotalCount
      summary: Get Activity Reports for Application Customers
      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.

        Fetch summary reports for all application customers based on a time range. Instead of having the total number of results
        in the response, this endpoint only mentions whether there are more results.
      tags:
        - Customer data
      parameters:
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/sort'
        - 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
        - $ref: '#/components/parameters/applicationId'
        - name: name
          in: query
          description: Only return reports matching the customer name.
          example: customer1
          required: false
          schema:
            type: string
        - name: integrationId
          in: query
          description: Filter results performing an exact matching against the profile integration identifier.
          example: customer1
          required: false
          schema:
            type: string
        - name: campaignName
          in: query
          description: Only return reports matching the campaign name.
          example: campaign1
          required: false
          schema:
            type: string
        - name: advocateName
          in: query
          description: Only return reports matching the current customer referrer name.
          example: advocate1
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - hasMore
                  - data
                properties:
                  hasMore:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomerActivityReport'
  /v1/applications/{applicationId}/customer_activity_reports/{customerId}:
    get:
      operationId: getCustomerActivityReport
      summary: Get customer's activity report
      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.

        Fetch the summary report of a given customer in the given application, in a time range.
      tags:
        - Customer data
      parameters:
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - 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
        - $ref: '#/components/parameters/applicationId'
        - name: customerId
          in: path
          description: |
            The value of the `id` property of a customer profile. Get it with the
            [List Application's customers](https://docs.talon.one/management-api#tag/Customer-data/operation/getApplicationCustomers) endpoint.
          example: 3778
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerActivityReport'
  /v1/applications/{applicationId}/customers/{customerId}/analytics:
    get:
      operationId: getCustomerAnalytics
      summary: Get customer's analytics report
      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.

        Fetch analytics for a given customer in the given application.
      tags:
        - Customer data
      parameters:
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/applicationId'
        - name: customerId
          in: path
          description: |
            The value of the `id` property of a customer profile. Get it with the
            [List Application's customers](https://docs.talon.one/management-api#tag/Customer-data/operation/getApplicationCustomers) endpoint.
          example: 3778
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerAnalytics'
  /v1/applications/{applicationId}/sessions:
    get:
      operationId: getApplicationSessions
      summary: List Application sessions
      description: |
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        List all the sessions of the specified Application.
      tags:
        - Customer data
      parameters:
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/sort'
        - name: partialMatch
          in: query
          required: false
          description: |-
            Enables partial matching for a single text search field. When enabled, the search term matches anywhere within the field value (case-insensitive). Minimum 3 characters required for partial matches; shorter inputs automatically fall back to exact match.

            **Note:** Use with one of: `integrationId`, `profile`, `coupon`, `referral`, or `storeIntegrationId`.
          example: false
          schema:
            type: boolean
            default: false
        - name: profile
          in: query
          required: false
          description: Filter by sessions with this profile integration ID. By default, requires exact match. Use `partialMatch=true` to search for partial matches (minimum 3 characters).
          example: customer1
          schema:
            type: string
        - name: state
          in: query
          required: false
          description: Filter by sessions with this state. Must be exact match.
          example: open
          schema:
            type: string
            enum:
              - open
              - closed
              - partially_returned
              - cancelled
        - name: createdBefore
          in: query
          description: Only return events created before this date. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: createdAfter
          in: query
          description: Only return events created after this date. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: coupon
          in: query
          required: false
          description: Filter by sessions with this coupon. By default, requires exact match. Use `partialMatch=true` to search for partial matches (minimum 3 characters).
          example: SUMMER10
          schema:
            type: string
        - name: referral
          in: query
          required: false
          description: Filter by sessions with this referral. By default, requires exact match. Use `partialMatch=true` to search for partial matches (minimum 3 characters).
          example: WPCNAQ5C
          schema:
            type: string
        - name: integrationId
          in: query
          required: false
          description: Filter by sessions with this integration ID. By default, requires exact match. Use `partialMatch=true` to search for partial matches (minimum 3 characters).
          example: STORE-123-REGION-WEST
          schema:
            type: string
        - name: storeIntegrationId
          in: query
          required: false
          description: The integration ID of the store. You choose this ID when you create a store. By default, requires exact match. Use `partialMatch=true` to search for partial matches (minimum 3 characters).
          example: store1
          schema:
            type: string
        - $ref: '#/components/parameters/applicationId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  hasMore:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApplicationSession'
  /v1/applications/{applicationId}/sessions_search:
    post:
      operationId: getApplicationSessionsByCustomerAttributes
      summary: List Application sessions matching the given customer attributes
      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 a list of the Application sessions matching the provided customer profile
        attributes.

        The match is successful if all the attributes of the request are found in a
        profile, even if the profile has more attributes that are not present on the
        request.
      tags:
        - Customer data
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - name: withTotalResultSize
          in: query
          description: |
            When this flag is set, the result includes the total number of results for this query. This might decrease performance on large data sets.
            - When `true`: `totalResultSize` contains the total number of results for this query.
            - When `false`: Only `hasMore` is returned, and it is set to `true` when there are more results than shown on the page.
          example: false
          schema:
            type: boolean
      requestBody:
        $ref: '#/components/requestBodies/CustomerProfileSearchQuery'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  hasMore:
                    type: boolean
                  totalResultSize:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApplicationSession'
  /v1/applications/{applicationId}/sessions/{sessionId}:
    get:
      operationId: getApplicationSession
      summary: Get Application session
      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 details of the given session.
        You can list the sessions with the [List Application sessions](https://docs.talon.one/management-api#tag/Customer-data/operation/getApplicationSessions) endpoint.
      tags:
        - Customer data
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - name: sessionId
          in: path
          description: |
            The **internal** ID of the session. You can get the ID with the [List Application sessions](https://docs.talon.one/management-api#tag/Customer-data/operation/getApplicationSessions) endpoint.
          example: 2533
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationSession'
  /v1/applications/{applicationId}/events/no_total:
    get:
      operationId: getApplicationEventsWithoutTotalCount
      summary: List Applications events
      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.

        Lists all events recorded for an application. Instead of having the total number of results in the response, this endpoint only mentions whether there are more results.
      tags:
        - Customer data
      parameters:
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/sort'
        - name: type
          in: query
          required: false
          description: Comma-separated list of types by which to filter events. Must be exact match(es).
          example: talon_session_created,talon_session_updated
          schema:
            type: string
        - name: createdBefore
          in: query
          description: Only return events created before this date. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: createdAfter
          in: query
          description: Only return events created after this date. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: session
          in: query
          required: false
          description: Session integration ID filter for events. Must be exact match.
          example: session1
          schema:
            type: string
        - name: profile
          in: query
          required: false
          description: Profile integration ID filter for events. Must be exact match.
          example: profile1
          schema:
            type: string
        - name: customerName
          in: query
          required: false
          description: Customer name filter for events. Will match substrings case-insensitively.
          example: customer1
          schema:
            type: string
            minLength: 2
        - name: customerEmail
          in: query
          required: false
          description: Customer e-mail address filter for events. Will match substrings case-insensitively.
          example: john@doe.com
          schema:
            type: string
            minLength: 2
        - name: couponCode
          in: query
          required: false
          description: Coupon code
          example: SUMMER10
          schema:
            type: string
        - name: referralCode
          in: query
          required: false
          description: Referral code
          example: WPCNAQ5C
          schema:
            type: string
        - name: ruleQuery
          in: query
          description: Rule name filter for events
          example: rule1
          required: false
          schema:
            type: string
        - name: campaignQuery
          in: query
          description: Campaign name filter for events
          example: campaign1
          required: false
          schema:
            type: string
        - name: effectType
          in: query
          description: The type of effect that was triggered. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          example: rejectCoupon
          required: false
          schema:
            type: string
        - $ref: '#/components/parameters/applicationId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - hasMore
                  - data
                properties:
                  hasMore:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApplicationEvent'
  /v1/applications/{applicationId}/event_types:
    get:
      operationId: getApplicationEventTypes
      summary: List Applications event types
      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 all of the distinct values of the Event `type` property for events recorded in the application.

        See also: [Track an event](https://docs.talon.one/integration-api#tag/Events/operation/trackEventV2)
      tags:
        - Customer data
      parameters:
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/applicationId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - totalResultSize
                  - data
                properties:
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      type: string
  /v1/audiences:
    get:
      operationId: getAudiences
      summary: List audiences
      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 all audiences created in the account. To create an audience, use [Create audience](https://docs.talon.one/integration-api#tag/Audiences/operation/createAudienceV2).
      tags:
        - Audiences
      parameters:
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/sort'
        - name: withTotalResultSize
          in: query
          description: |
            When this flag is set, the result includes the total number of results for this query. This might decrease performance on large data sets.

            - When `true`: `totalResultSize` contains the total number of results for this query.
            - When `false`: Only `hasMore` is returned, and it is set to `true` when there are more results than shown on the page.
          example: false
          schema:
            type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  hasMore:
                    type: boolean
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Audience'
  /v1/audiences/analytics:
    get:
      operationId: getAudiencesAnalytics
      summary: List audience analytics
      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 a list of audience IDs and their member count.
      tags:
        - Audiences
      parameters:
        - $ref: '#/components/parameters/sort'
        - name: audienceIds
          in: query
          required: true
          description: The IDs of one or more audiences, separated by commas, by which to filter results. Do not provide more than 1000 audience IDs.
          example: audience1
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  hasMore:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AudienceAnalytics'
  /v1/audiences/{audienceId}/memberships:
    get:
      operationId: getAudienceMemberships
      summary: List audience members
      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 a paginated list of the customer profiles in a given audience.

        A maximum of 1000 customer profiles per page is allowed.
      tags:
        - Audiences
      parameters:
        - name: audienceId
          in: path
          required: true
          description: The ID of the audience.
          example: 10
          schema:
            type: integer
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/sort'
        - name: profileQuery
          in: query
          description: The filter to select a profile.
          example: profile1
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  hasMore:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomerProfile'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v1/audiences/{audienceId}/memberships/import:
    post:
      operationId: importAudiencesMemberships
      summary: Import audience members
      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 integration IDs of the members you want to
        add to an audience.

        The file should be sent as multipart data and should contain only the
        following column (required):

        - `profileintegrationid`: The integration ID of the customer profile.

        The import **replaces** the previous list of audience members.

        > [!note] We recommend limiting your file size to 500 MB.

        ## Example

        ```text
        profileintegrationid
        charles
        alexa
        ```
      tags:
        - Audiences
      parameters:
        - name: audienceId
          in: path
          required: true
          description: The ID of the audience.
          example: 10
          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'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v1/audiences/{audienceId}/memberships/export:
    get:
      operationId: exportAudiencesMemberships
      summary: Export audience members
      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 integration IDs of the members of an
        audience.

        > [!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 file contains the following column:

        - `profileintegrationid`: The integration ID of the customer profile.
      tags:
        - Audiences
      parameters:
        - name: audienceId
          in: path
          required: true
          description: The ID of the audience.
          example: 10
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/csv:
              schema:
                type: string
                format: csv
              examples:
                response:
                  value: |
                    profileintegrationid
                    URNGV8294NV
                    BZGGC2454PA
        '400':
          description: Bad request
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '404':
          description: Not found
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v1/applications/{applicationId}/profile/{integrationId}/friends:
    get:
      operationId: getApplicationCustomerFriends
      summary: List friends referred by customer profile
      description: |
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        List the friends referred by the specified customer profile in this Application.
      tags:
        - Referrals
      parameters:
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/applicationId'
        - name: withTotalResultSize
          in: query
          description: |
            When this flag is set, the result includes the total number of results for this query. This might decrease performance on large data sets.

            - When `true`: `totalResultSize` contains the total number of results for this query.
            - When `false`: Only `hasMore` is returned, and it is set to `true` when there are more results than shown on the page.
          example: false
          schema:
            type: boolean
        - name: integrationId
          in: path
          required: true
          description: The Integration ID of the Advocate's Profile.
          example: advocate1
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  hasMore:
                    type: boolean
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApplicationReferee'
  /v1/applications/{applicationId}/price_history:
    post:
      operationId: priceHistory
      summary: Get summary of price history
      x-scalar-stability: experimental
      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.

        Fetch the historical price data for a given SKU within a defined timeframe.
      tags:
        - Catalogs
      parameters:
        - $ref: '#/components/parameters/applicationId'
      requestBody:
        $ref: '#/components/requestBodies/PriceHistory'
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceHistoryResponse'
  /v1/applications/{applicationId}/price_history/exclusions:
    post:
      operationId: excludePriceHistory
      summary: Exclude price records from price history
      x-scalar-stability: experimental
      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.

        Select a batch of historical price IDs to exclude from [best prior price calculation](https://docs.talon.one/integration-api#tag/Catalogs/operation/bestPriorPrice). All IDs in the batch must be valid `id` values obtained from the [Get summary of price history](https://docs.talon.one/management-api#tag/Catalogs/operation/priceHistory.responses.200.history) endpoint, must belong to the specified Application, must not already be excluded from best prior price calculation, and must not be associated with a scheduled strikethrough pricing notification.
      tags:
        - Catalogs
      parameters:
        - $ref: '#/components/parameters/applicationId'
      requestBody:
        $ref: '#/components/requestBodies/ExcludePriceObservations'
      responses:
        '200':
          description: Ok
  /v1/attributes:
    post:
      operationId: createAttribute
      summary: Create custom attribute
      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 _custom attribute_ in this account.
        [Custom attributes](https://docs.talon.one/docs/dev/concepts/attributes) allow you
        to add data to Talon.One domain entities like campaigns, coupons,
        customers and so on.

        These attributes can then be given values when creating/updating these entities, and these values can be
        used in your campaign rules.

        For example, you could define a `zipCode` field for customer sessions,
        and add a rule to your campaign that only allows certain ZIP codes.

        These attributes are shared across all Applications in your account and are never required.
      tags:
        - Attributes
      requestBody:
        $ref: '#/components/requestBodies/NewAttribute'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attribute'
    get:
      operationId: getAttributes
      summary: List custom attributes
      description: |
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        Return all the custom attributes for the account.
      tags:
        - Attributes
      parameters:
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/sort'
        - name: entity
          in: query
          required: false
          description: Returned attributes will be filtered by supplied entity.
          example: entity1
          schema:
            type: string
        - name: applicationIds
          in: query
          required: false
          description: Returned attributes will be filtered by supplied application ids
          example: 1,2,3
          schema:
            type: string
        - name: loyaltyProgramIds
          in: query
          required: false
          description: Returned attributes will be filtered by the specified loyalty program ids, separated by commas. You can only use this parameter when `entity` is `LoyaltyCard`.
          example: 1,2
          schema:
            type: string
        - name: type
          in: query
          required: false
          description: Returned attributes will be filtered by supplied type
          example: string
          schema:
            type: string
        - name: kind
          in: query
          required: false
          description: Returned attributes will be filtered by supplied kind (builtin or custom)
          example: builtin
          schema:
            type: string
            enum:
              - builtin
              - custom
            x-generate-enum-go: true
        - name: search
          in: query
          required: false
          description: Returned attributes will be filtered by searching case insensitive through Attribute name, description and type
          example: string
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - totalResultSize
                  - data
                properties:
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Attribute'
  /v1/attributes/{attributeId}:
    get:
      operationId: getAttribute
      summary: Get custom attribute
      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 specified custom attribute.
      tags:
        - Attributes
      parameters:
        - name: attributeId
          in: path
          required: true
          description: The ID of the attribute. You can find the ID in the Campaign Manager's URL when you display the details of an attribute in **Account** > **Tools** > **Attributes**.
          example: 31
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attribute'
    put:
      operationId: updateAttribute
      summary: Update custom attribute
      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 an existing custom attribute. Once created, the only property of a custom attribute that can be
        changed is the description.

        To change the `type` or `name` property of a custom attribute, create a new attribute and
        update any relevant integrations and rules to use the new attribute.
      tags:
        - Attributes
      parameters:
        - name: attributeId
          in: path
          required: true
          description: The ID of the attribute. You can find the ID in the Campaign Manager's URL when you display the details of an attribute in **Account** > **Tools** > **Attributes**.
          example: 31
          schema:
            type: integer
      requestBody:
        $ref: '#/components/requestBodies/NewAttribute'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attribute'
  /v1/attributes/{attributeId}/allowed_list/import:
    post:
      operationId: importAllowedList
      summary: Import allowed values for attribute
      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 a list of [picklist
        values](https://docs.talon.one/docs/product/account/dev-tools/managing-attributes#picklist-values)
        for the specified attribute.

        The file should be sent as multipart data.

        The import **replaces** the previous list of allowed values for this
        attribute, if any.

        The CSV file **must** only contain the following column:

        - `item`: The values in your allowed list, for example a list of SKUs.

        An allowed list is limited to 500,000 items.

        ## Example

        ```text
        item
        CS-VG-04032021-UP-50D-10
        CS-DV-04042021-UP-49D-12
        CS-DG-02082021-UP-50G-07
        ```
      tags:
        - Attributes
      parameters:
        - name: attributeId
          in: path
          required: true
          description: The ID of the attribute. You can find the ID in the Campaign Manager's URL when you display the details of an attribute in **Account** > **Tools** > **Attributes**.
          example: 31
          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'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v1/catalogs/{catalogId}/items:
    get:
      operationId: listCatalogItems
      summary: List items in a catalog
      description: |
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        Return a paginated list of cart items in the given catalog.
      tags:
        - Catalogs
      parameters:
        - name: catalogId
          description: The ID of the catalog. You can find the ID in the Campaign Manager in **Account** > **Tools** > **Cart item catalogs**.
          example: 30
          in: path
          required: true
          schema:
            type: integer
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - name: withTotalResultSize
          in: query
          description: |
            When this flag is set, the result includes the total number of results for this query. This might decrease performance on large data sets.

            - When `true`: `totalResultSize` contains the total number of results for this query.
            - When `false`: Only `hasMore` is returned, and it is set to `true` when there are more results than shown on the page.
          example: false
          schema:
            type: boolean
        - name: sku
          in: query
          description: Filter results by one or more SKUs. Must be exact match.
          example:
            - SKU-1
            - SKU-2
          style: form
          schema:
            type: array
            items:
              type: string
        - name: productNames
          in: query
          description: Filter results by one or more product names. Must be exact match.
          example:
            - product1
            - product2
          style: form
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  hasMore:
                    type: boolean
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CatalogItem'
  /v1/additional_costs:
    post:
      operationId: createAdditionalCost
      summary: Create additional cost
      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 an [additional cost](https://docs.talon.one/docs/product/account/dev-tools/managing-additional-costs).

        These additional costs are shared across all applications in your account, and are never required.
      tags:
        - Additional costs
      requestBody:
        $ref: '#/components/requestBodies/NewAdditionalCost'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountAdditionalCost'
    get:
      operationId: getAdditionalCosts
      summary: List additional costs
      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.

        Returns all the defined additional costs for the account.
      tags:
        - Additional costs
      parameters:
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/sort'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - totalResultSize
                  - data
                properties:
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AccountAdditionalCost'
  /v1/additional_costs/{additionalCostId}:
    get:
      operationId: getAdditionalCost
      summary: Get additional cost
      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.

        Returns the additional cost.
      tags:
        - Additional costs
      parameters:
        - name: additionalCostId
          description: |
            The ID of the additional cost. You can find the ID the the Campaign Manager's URL when you display the details of the cost in **Account** > **Tools** > **Additional costs**.
          example: 2
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountAdditionalCost'
    put:
      operationId: updateAdditionalCost
      summary: Update additional cost
      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.

        Updates an existing additional cost. Once created, the only property of an additional cost that cannot be changed is the `name` property (or **API name** in the Campaign Manager). This restriction is in place to prevent accidentally breaking live integrations.
      tags:
        - Additional costs
      parameters:
        - name: additionalCostId
          description: |
            The ID of the additional cost. You can find the ID the the Campaign Manager's URL when you display the details of the cost in **Account** > **Tools** > **Additional costs**.
          example: 2
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        $ref: '#/components/requestBodies/NewAdditionalCost'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountAdditionalCost'
  /v1/webhooks:
    get:
      operationId: getWebhooks
      summary: List webhooks
      description: |-
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        List all webhooks.
      tags:
        - Webhooks
      parameters:
        - name: applicationIds
          in: query
          description: |
            Checks if the given catalog or its attributes are referenced in the specified Application ID.

            **Note**: If no Application ID is provided, we check for all connected Applications.
          example: '33'
          required: false
          schema:
            type: string
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - name: creationType
          in: query
          description: Filter results by creation type.
          example: webhooks
          required: false
          schema:
            type: string
            enum:
              - templateWebhooks
              - webhooks
        - name: visibility
          in: query
          description: Filter results by visibility.
          example: visible
          required: false
          schema:
            type: string
            enum:
              - visible
              - hidden
        - name: outgoingIntegrationsTypeId
          in: query
          description: Filter results by outgoing integration type ID.
          example: 15
          required: false
          schema:
            type: integer
        - name: title
          in: query
          description: Filter results performing case-insensitive matching against the webhook title.
          example: title1
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - totalResultSize
                  - data
                properties:
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookWithOutgoingIntegrationDetails'
  /v1/webhooks/{webhookId}:
    get:
      operationId: getWebhook
      summary: Get webhook
      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.

        Returns a webhook by its id.
      tags:
        - Webhooks
      parameters:
        - name: webhookId
          description: |
            The ID of the webhook. You can find the ID in the Campaign Manager's URL when you display the details of the webhook in **Account** > **Webhooks**.
          example: 11
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
  /v1/message_logs:
    get:
      operationId: getMessageLogs
      summary: List message log entries
      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 all message log entries.
      tags:
        - Logs
      parameters:
        - name: messageID
          in: query
          description: Filter results by message ID.
          example: message1
          required: false
          schema:
            type: string
        - name: changeType
          in: query
          description: Filter results by change type.
          example: CampaignEvaluationTreeChanged
          required: false
          schema:
            type: string
            enum:
              - CampaignEvaluationTreeChanged
              - CampaignNotification
              - CouponCreated
              - CouponUpdated
              - CouponDeleted
              - AsyncCouponsCreated
              - CouponsDeleted
              - CouponsUpdated
              - CouponCodeExpiring
              - StrikethroughPrice
              - LoyaltyPointsAdded
              - LoyaltyPointsDeducted
              - LoyaltyPointsExpiring
              - LoyaltyPointsPendingToActive
              - LoyaltyAddedDeductedPointsBalances
              - LoyaltyCardAddedDeductedPointsBalances
              - TierWillDowngrade
              - TierUpgrade
              - TierDowngrade
              - LoyaltyCardPointsAdded
              - LoyaltyCardPointsDeducted
              - LoyaltyCardPointsExpiring
        - name: notificationIDs
          in: query
          description: Filter results by notification ID (include up to 30 values, separated by a comma).
          example: 23,46
          required: false
          schema:
            type: string
        - name: createdBefore
          in: query
          description: Filter results where request and response times to return entries before parameter value, expected to be an RFC3339 timestamp string. Use UTC time.
          required: false
          example: '2024-05-29T15:04:05Z'
          schema:
            type: string
            format: date-time
        - name: createdAfter
          in: query
          description: Filter results where request and response times to return entries after parameter value, expected to be an RFC3339 timestamp string. Use UTC time.
          required: false
          example: '2024-05-29T15:04:05Z'
          schema:
            type: string
            format: date-time
        - name: cursor
          in: query
          description: |
            A specific unique value in the database. If this value is not given, the server fetches results starting with the first record.
          example: U3dhZ2dlciByb2Nrcw==
          required: false
          schema:
            type: string
            format: byte
        - name: pageSize
          in: query
          description: The maximum number of message log entries to return.
          example: 50
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 50
        - name: period
          in: query
          description: |
            Filter results by time period. Choose between the available relative time frames.
          example: 15m
          required: false
          schema:
            type: string
            enum:
              - 15m
              - 30m
              - 1h
              - 4h
              - 1d
              - 2d
        - in: query
          name: isSuccessful
          description: |
            Indicates whether to return log entries with either successful or unsuccessful HTTP response codes. When set to`true`, only log entries with `2xx` response codes are returned. When set to `false`, only log entries with `4xx` and `5xx` response codes are returned.
          example: false
          required: false
          schema:
            type: boolean
        - in: query
          name: entityType
          description: |
            The entity type the log is related to.
          example: application
          required: true
          schema:
            type: string
            enum:
              - application
              - loyalty_program
              - webhook
        - name: applicationId
          in: query
          description: Filter results by Application ID.
          example: 19
          required: false
          schema:
            type: number
        - name: campaignId
          in: query
          description: Filter results by campaign ID.
          example: 49
          schema:
            type: number
        - in: query
          name: loyaltyProgramId
          description: Identifier of the loyalty program.
          example: 40
          required: false
          schema:
            type: integer
        - in: query
          name: responseCode
          description: Filter results by response status code.
          example: 200
          required: false
          schema:
            type: integer
        - in: query
          name: webhookIDs
          description: Filter results by webhook ID (include up to 30 values, separated by a comma).
          example: 23,46
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageLogEntries'
  /v1/event_types:
    get:
      operationId: getEventTypes
      summary: List event types
      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.

        Fetch all event type definitions for your account.
      tags:
        - Events
      parameters:
        - name: name
          in: query
          description: Filter results to event types with the given name. This parameter implies `includeOldVersions`.
          example: event1
          schema:
            type: string
        - name: includeOldVersions
          in: query
          description: Include all versions of every event type.
          example: false
          schema:
            type: boolean
            default: false
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/sort'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - totalResultSize
                  - data
                properties:
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/EventType'
  /v1/applications/{applicationId}/campaigns/{campaignId}/import_coupons:
    post:
      operationId: importCoupons
      summary: Import coupons
      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 coupons that should be created. The file
        should be sent as multipart data.

        The CSV file contains the following columns:

        - `value` (required): The coupon code. Must be at least 3 characters long. We recommend using alphanumeric characters.
          There is no maximum length but limiting the code to 30 characters
          ensures it is fully readable in the Campaign Manager.
          The code should be unique unless you set `skipDuplicates` to `true`.
        - `expirydate`: The end date in RFC3339 of the code redemption period.
        - `startdate`: The start date in RFC3339 of the code redemption period.
        - `recipientintegrationid`: The integration ID of the recipient of the coupon.
          Only the customer with this integration ID can redeem this code. Available only for personal codes.
        - `limitval`: The maximum number of redemptions of this code. For unlimited redemptions, use `0`. Defaults to `1` when not provided.
        - `discountlimit`: The total discount value that the code can give. This is typically used to represent a gift card value.
        - `attributes`: A JSON object describing _custom_ coupon attribute names and their values, enclosed with double quotation marks.<br />
          For example, if you created a [custom attribute](https://docs.talon.one/docs/dev/concepts/attributes#custom-attributes)
          called `category` associated with the coupon entity, the object in the CSV file, when opened in a text editor, must be: `"{"category": "10_off"}"`.

        You can use the time zone of your choice. It is converted to UTC internally by Talon.One.

        > [!note] We recommend limiting your file size to 500 MB.

        ## Example

        ```text
        "value","expirydate","startdate","recipientintegrationid","limitval","attributes","discountlimit"
        COUP1,2018-07-01T04:00:00Z,2018-05-01T04:00:00Z,cust123,1,"{""Category"":
        ""10_off""}",2.4
        ```

        Once imported, you can find the `batchId` in the Campaign Manager or by using [List coupons](#tag/Coupons/operation/getCouponsWithoutTotalCount).
      tags:
        - Coupons
      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
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
        - name: skipDuplicates
          in: query
          required: false
          description: |
            An indicator of whether to skip duplicate coupon values instead of causing an error.
            Duplicate values are ignored when `skipDuplicates=true`.
          example: false
          schema:
            type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Import'
  /v1/applications/{applicationId}/export_coupons:
    get:
      operationId: exportCoupons
      summary: Export coupons
      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 coupons that match the given properties.

        > [!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 can contain the following columns:

        - `accountid`: The ID of your deployment.
        - `applicationid`: The ID of the Application this coupon is related to.
        - `attributes`: A json object describing _custom_ referral attribute names and their values.
        - `batchid`: The ID of the batch this coupon is part of.
        - `campaignid`: The ID of the campaign this coupon is related to.
        - `counter`: The number of times this coupon has been redeemed.
        - `created`: The creation date in RFC3339 of the coupon code.
        - `deleted`: Whether the coupon code is deleted.
        - `deleted_changelogid`: The ID of the delete event in the logs.
        - `discount_counter`: The amount of discount given by this coupon.
        - `discount_limitval`: The maximum discount amount that can be given be this coupon.
        - `expirydate`: The end date in RFC3339 of the code redemption period.
        - `id`: The internal ID of the coupon code.
        - `importid`: The ID of the import job that created this coupon.
        - `is_reservation_mandatory`: Whether this coupon requires a reservation to be redeemed.
        - `limits`: The limits set on this coupon.
        - `limitval`: The maximum number of redemptions of this code.
        - `recipientintegrationid`: The integration ID of the recipient of the coupon.
           Only the customer with this integration ID can redeem this code. Available only for personal codes.
        - `referralid`: The ID of the referral code that triggered the creation of this coupon (create coupon effect).
        - `reservation`: Whether the coupon can be reserved for multiple customers.
        - `reservation_counter`: How many times this coupon has been reserved.
        - `reservation_limitval`: The maximum of number of reservations this coupon can have.
        - `startdate`: The start date in RFC3339 of the code redemption period.
        - `value`: The coupon code.
      tags:
        - Coupons
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - name: campaignId
          in: query
          description: Filter results by campaign ID.
          example: 49
          schema:
            type: number
        - $ref: '#/components/parameters/sort'
        - name: value
          in: query
          description: Filter results performing case-insensitive matching against the coupon code. Both the code and the query are folded to remove all non-alpha-numeric characters.
          example: SUMMER10
          required: false
          schema:
            type: string
        - name: createdBefore
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: createdAfter
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: valid
          in: query
          description: |
            Either "expired", "validNow", or "validFuture". The first option matches coupons in which the expiration date is set and in the past. The second matches coupons in which start date is null or in the past and expiration date is null or in the future, the third matches coupons in which start date is set and in the future.
          example: validNow
          required: false
          schema:
            type: string
            enum:
              - expired
              - validNow
              - validFuture
        - name: usable
          in: query
          description: |
            Either "true" or "false". If "true", only coupons where `usageCounter < usageLimit` will be returned, "false" will return only coupons where `usageCounter >= usageLimit`.
          example: 'false'
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
        - name: referralId
          in: query
          description: Filter the results by matching them with the ID of a referral. This filter shows the coupons created by redeeming a referral code.
          example: 47
          required: false
          schema:
            type: integer
        - name: recipientIntegrationId
          in: query
          description: Filter results by match with a profile id specified in the coupon's RecipientIntegrationId field.
          example: customer1
          required: false
          schema:
            type: string
        - name: batchId
          in: query
          description: Filter results by batches of coupons
          example: nfinccze
          required: false
          schema:
            type: string
        - name: exactMatch
          in: query
          description: Filter results to an exact case-insensitive matching against the coupon code.
          example: false
          required: false
          schema:
            type: boolean
            default: false
        - name: dateFormat
          in: query
          description: Determines the format of dates in the export document.
          example: excel
          required: false
          schema:
            type: string
            enum:
              - excel
              - ISO8601
        - name: campaignState
          in: query
          description: |
            Filter results by the state of the campaign.

            - `enabled`: Campaigns that are scheduled, running (activated), or expired.
            - `running`: Campaigns that are running (activated).
            - `disabled`: Campaigns that are disabled.
            - `expired`: Campaigns that are expired.
            - `archived`: Campaigns that are archived.
          example: enabled
          required: false
          schema:
            type: string
            enum:
              - enabled
              - disabled
              - archived
              - scheduled
              - running
              - expired
              - staged
        - name: valuesOnly
          in: query
          description: Filter results to only return the coupon codes (`value` column) without the associated coupon data.
          example: false
          required: false
          schema:
            type: boolean
            default: false
        - name: deletedBefore
          in: query
          description: |-
            Timestamp that filters the results to only contain coupons deleted before this date. Must be an RFC3339 timestamp string. You can use any time zone setting. Talon.One will convert to UTC internally.

            **Note:** Only coupons deleted in the last 7 days will appear in the results.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: deletedAfter
          in: query
          description: |-
            Timestamp that filters the results to only contain coupons deleted after this date. Must be an RFC3339 timestamp string. You can use any time zone setting. Talon.One will convert to UTC internally.

            **Note:** Only coupons deleted in the last 7 days will appear in the results.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: OK
          content:
            application/csv:
              schema:
                type: string
                format: csv
              examples:
                response:
                  value: |
                    id,created,campaignid,value,expirydate,startdate,attributes,applicationid,deleted,deleted_changelogid,accountid,referralid,recipientintegrationid,importid,batchid,reservation,limits,limitval,counter,discount_counter,discount_limitval
                    20191301,2022-04-26T11:02:38Z,3882,COUP1,2022-04-27T10:56:47Z,2022-04-26T10:56:47Z,"{""test"": ""premium""}",270,,0,1,,cust123,671,axghjfdy,,"[]",1,0,0,1.5
  /v1/applications/{applicationId}/export_referrals:
    get:
      operationId: exportReferrals
      summary: Export referrals
      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 referrals that match the given
        parameters.

        > [!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:

        - `code`: The referral code.
        - `advocateprofileintegrationid`: The profile ID of the advocate.
        - `startdate`: The start date in RFC3339 of the code redemption period.
        - `expirydate`: The end date in RFC3339 of the code redemption period.
        - `limitval`: The maximum number of redemptions of this code. Defaults to `1` when left blank.
        - `attributes`: A json object describing _custom_ referral attribute names and their values.
      tags:
        - Referrals
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - name: campaignId
          in: query
          description: Filter results by campaign ID.
          example: 49
          schema:
            type: number
        - name: createdBefore
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the referral creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: createdAfter
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the referral creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: valid
          in: query
          description: |
            - `expired`: Matches referrals in which the expiration date is set and in the past.
            - `validNow`: Matches referrals in which start date is null or in the past and expiration date is null or in the future.
            - `validFuture`: Matches referrals in which start date is set and in the future.
          example: validNow
          required: false
          schema:
            type: string
            enum:
              - expired
              - validNow
              - validFuture
        - name: usable
          in: query
          description: |
            - `true`, only referrals where `usageCounter < usageLimit` will be returned.
            - `false`, only referrals where `usageCounter >= usageLimit` will be returned.
          example: 'true'
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
        - name: batchId
          in: query
          description: Filter results by batches of referrals
          example: nfinccze
          schema:
            type: string
        - 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: |
                    id,created,campaignid,advocateprofileintegrationid,friendprofileintegrationid,startdate,expirydate,code,importid,attributes,batchid,counter,limitval
                    687,2021-09-10 09:21:06,3882,UGAV4628K,,,,3LFC-4BPC,,"{}",pimcxobg,0,9999
  /v1/applications/{applicationId}/export_effects:
    get:
      operationId: exportEffects
      summary: Export triggered effects
      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 triggered effects that match the given
        attributes.

        > [!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 generated file can contain the following columns:

        - `applicationid`: The ID of the Application.
        - `campaignid`: The ID of the campaign.
        - `couponid`: The ID of the coupon, when applicable to the effect.
        - `created`: The timestamp of the effect.
        - `event_type`: The name of the event. See the [docs](https://docs.talon.one/docs/dev/concepts/entities/events).
        - `eventid`: The internal ID of the effect.
        - `name`: The effect name. See the [docs](https://docs.talon.one/docs/dev/integration-api/api-effects).
        - `profileintegrationid`: The ID of the customer profile, when applicable.
        - `props`: The [properties](https://docs.talon.one/docs/dev/integration-api/api-effects) of the effect.
        - `ruleindex`: The index of the rule.
        - `rulesetid`: The ID of the rule set.
        - `sessionid`: The internal ID of the session that triggered the effect.
        - `profileid`: The internal ID of the customer profile.
        - `sessionintegrationid`: The integration ID of the session.
        - `total_revenue`: The total revenue.
        - `store_integration_id`: The integration ID of the store. You choose this ID when you create a store.
        - `reward_id`: The ID of the reward whose rule generated this effect, when applicable.
        - `reward_integration_id`: The integration ID of the specific customer reward whose usage produced this effect, when applicable.
      tags:
        - Analytics
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - name: campaignId
          in: query
          description: Filter results by campaign ID.
          example: 49
          schema:
            type: number
        - name: createdBefore
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: createdAfter
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          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
              examples:
                response:
                  value: |
                    created,name,applicationid,campaignid,rulesetid,ruleindex,sessionintegrationid,profileintegrationid,sessionid,profileid,eventid,event_type,total_revenue,props,couponid,store_id,store_integration_id,reward_id,reward_integration_id
                    2021-06-02T21:14:16Z,rejectCoupon,270,0,0,0,newsession1,,9168,0,95797,talon_session_created,265.00,"{""value"": ""XMAS20"", ""rejectionReason"": ""CouponNotFound""}",,115,STORE-001,,
                    2021-09-01T13:04:04Z,setDiscountPerItem,270,3882,13599,0,test_flattening_2,integid_4,9707,4800,98806,talon_session_updated,405.00,"{""name"": ""10% off per item#1"", ""value"": 11.0, ""position"": 1}",,116,STORE-002,,
                    2024-05-29T15:04:05Z,setDiscount,270,0,0,0,newsession3,integid_5,9711,4803,98810,talon_session_closed,120.00,"{""name"": ""10% reward discount"", ""value"": 12.0}",,116,STORE-002,7,reward-unlock-123
  /v1/applications/{applicationId}/export_customer_sessions:
    get:
      operationId: exportCustomerSessions
      summary: Export customer sessions
      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 customer sessions that match the request.

        > [!important] Archived sessions cannot be exported. See the [retention
        > policy](https://docs.talon.one/docs/dev/server-infrastructure-and-data-retention).

        > [!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).

        - `id`: The internal ID of the session.
        - `firstsession`: Whether this is a first session.
        - `integrationid`: The integration ID of the session.
        - `applicationid`: The ID of the Application.
        - `profileid`: The internal ID of the customer profile.
        - `profileintegrationid`: The integration ID of the customer profile.
        - `created`: The timestamp when the session was created.
        - `state`: The [state](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions#customer-session-states)
           of the session.
        - `cartitems`: The cart items in the session.
        - `discounts`: The discounts in the session.
        - `total`: The total value of cart items and additional costs in the session, before any discounts are applied.
        - `attributes`: The attributes set in the session.
        - `closedat`: Timestamp when the session was closed.
        - `cancelledat`: Timestamp when the session was cancelled.
        - `referral`: The referral code in the session.
        - `identifiers`: The identifiers in the session.
        - `additional_costs`: The [additional costs](https://docs.talon.one/docs/product/account/dev-tools/managing-additional-costs)
           in the session.
        - `updated`: Timestamp of the last session update.
        - `store_integration_id`: The integration ID of the store.
        - `coupons`: Coupon codes in the session.
      tags:
        - Analytics
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - name: createdBefore
          in: query
          description: Filter results comparing the parameter value, expected to 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: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: updatedBefore
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: updatedAfter
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: profileIntegrationId
          in: query
          description: Only return sessions for the customer that matches this customer integration ID.
          example: customer1
          required: false
          schema:
            type: string
        - name: dateFormat
          in: query
          description: Determines the format of dates in the export document.
          example: excel
          required: false
          schema:
            type: string
            enum:
              - excel
              - ISO8601
        - name: customerSessionState
          in: query
          description: Filter results by state.
          example: open
          required: false
          schema:
            type: string
            enum:
              - open
              - closed
              - partially_returned
              - cancelled
      responses:
        '200':
          description: OK
          content:
            application/csv:
              schema:
                type: string
                format: csv
              examples:
                response:
                  value: |
                    id,firstsession,integrationid,applicationid,profileid,profileintegrationid,created,state,cartitems,discounts,total,attributes,closedat,cancelledat,referral,identifiers,additional_costs,updated,store_integration_id,coupons
                    12328,true,62791173fbf323ee5cfd96f3,270,6111,dxclwds,2022-05-09T13:05:31Z,open,"[{""sku"": ""B00004TKVY"", ""name"": ""Gravel bike - \""Aisle of Man\"""", ""price"": 1800, ""weight"": 6, ""category"": ""gravelbikes"", ""position"": 0, ""quantity"": 1, ""attributes"": {""color"": [""black,white""], ""material"": ""titanium""}, ""returnedQuantity"": 0, ""remainingQuantity"": 1}]","{}",1850.00,"{""ShippingCost"": 50, ""PaymentMethod"": ""creditcard"", ""ShippingMethod"": ""Standard""}",0001-01-01T00:00:00Z,0001-01-01T00:00:00Z,,"null","{""ShippingCost"": {""price"": 50}}",2022-05-09T13:13:28Z,"STORE-001","[""SORRY5QMUJRWA""]"
  /v1/applications/{applicationId}/campaigns/{campaignId}/import_referrals:
    post:
      operationId: importReferrals
      summary: Import referrals
      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 referrals that should be created.

        The file should be sent as multipart data.

        The CSV file contains the following columns:

        - `code` (required): The referral code.
        - `advocateprofileintegrationid` (required): The profile ID of the advocate.
        - `startdate`: The start date in RFC3339 of the code redemption period.
        - `expirydate`: The end date in RFC3339 of the code redemption period.
        - `limitval`: The maximum number of redemptions of this code. Defaults to `1` when left blank.
        - `attributes`: A JSON object describing _custom_ referral attribute names and their values, enclosed with double quotation marks.<br />
          For example, if you created a [custom attribute](https://docs.talon.one/docs/dev/concepts/attributes#custom-attributes)
          called `category` associated with the referral entity, the object in the CSV file, when opened in a text editor, must be: `"{"category": "10_off"}"`.

        You can use the time zone of your choice. It is converted to UTC internally by Talon.One.

        > [!important] When you import a CSV file with referrals,
        > a [customer profile](https://docs.talon.one/docs/dev/concepts/entities/customer-profiles)
        > is **not** automatically created for each `advocateprofileintegrationid`
        > column value. Use the [Update customer profile](https://docs.talon.one/integration-api#tag/Customer-profiles/operation/updateCustomerProfileV2)
        > endpoint or the [Update multiple customer profiles](https://docs.talon.one/integration-api#tag/Customer-profiles/operation/updateCustomerProfilesV2)
        > endpoint to create the customer profiles.

        > [!note] We recommend limiting your file size to 500 MB.

        ## Example

        ```text
        code,startdate,expirydate,advocateprofileintegrationid,limitval,attributes
        REFERRAL_CODE1,2020-11-10T23:00:00Z,2021-11-11T23:00:00Z,integid_4,1,"{""my_attribute"":
        ""10_off""}"
        REFERRAL_CODE2,2020-11-10T23:00:00Z,2021-11-11T23:00:00Z,integid1,1,"{""my_attribute"":
        ""20_off""}"
        ```
      tags:
        - Referrals
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
      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'
  /v1/users:
    get:
      operationId: getUsers
      summary: List users in account
      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 all users in your account.
      tags:
        - Accounts and users
      parameters:
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/sort'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - totalResultSize
                  - data
                properties:
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
  /v1/users/{userId}:
    get:
      operationId: getUser
      summary: Get user
      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 data (including an invitation code) for a user. Non-admin users can only get their own profile.
      tags:
        - Accounts and users
      parameters:
        - name: userId
          in: path
          description: The ID of the user.
          example: 33
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
    put:
      operationId: updateUser
      summary: Update user
      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 user.
      tags:
        - Accounts and users
      parameters:
        - name: userId
          in: path
          description: The ID of the user.
          example: 33
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUser'
        description: body
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
    delete:
      operationId: deleteUser
      summary: Delete user
      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 a specific user.
      tags:
        - Accounts and users
      parameters:
        - name: userId
          in: path
          description: The ID of the user.
          example: 33
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: No Content
  /v1/provisioning/okta:
    get:
      operationId: oktaEventHandlerChallenge
      summary: Validate Okta API ownership
      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.

        Validate the ownership of the API through a challenge-response mechanism.

        This challenger endpoint is used by Okta to confirm that communication between Talon.One and Okta is correctly configured and accessible
        for provisioning and deprovisioning of Talon.One users, and that only Talon.One can receive and respond to events from Okta.
      tags:
        - Accounts and users
      responses:
        '200':
          description: OK
  /v1/provisioning/scim/Groups:
    get:
      operationId: scimGetGroups
      summary: List SCIM groups
      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 a paginated list of groups created using the SCIM protocol with an identity provider, for example, Microsoft Entra ID.
        In Talon.One, a `Group` corresponds to a [role](https://docs.talon.one/docs/product/account/account-settings/managing-roles), and `members` are the [users](https://docs.talon.one/docs/product/account/account-settings/managing-users) assigned to that role.
      tags:
        - Accounts and users
      responses:
        '200':
          description: List of SCIM groups
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimGroupsListResponse'
    post:
      operationId: scimCreateGroup
      summary: Create SCIM group
      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 new Talon.One group using the SCIM Group provisioning protocol with an identity provider, for example, Microsoft Entra ID, and assign members from the payload to the new group.
        In Talon.One, a `Group` corresponds to a [role](https://docs.talon.one/docs/product/account/account-settings/managing-roles), and `members` are the [users](https://docs.talon.one/docs/product/account/account-settings/managing-users) assigned to that role.
      tags:
        - Accounts and users
      requestBody:
        $ref: '#/components/requestBodies/ScimNewGroup'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimGroup'
  /v1/provisioning/scim/Groups/{groupId}:
    get:
      operationId: scimGetGroup
      summary: Get SCIM group
      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 data for a specific group created using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID.
        In Talon.One, a `Group` corresponds to a [role](https://docs.talon.one/docs/product/account/account-settings/managing-roles), and `members` are the [users](https://docs.talon.one/docs/product/account/account-settings/managing-users) assigned to that role.
      tags:
        - Accounts and users
      parameters:
        - name: groupId
          in: path
          description: The ID of the group.
          example: 44
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Group details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimGroup'
    delete:
      operationId: scimDeleteGroup
      summary: Delete SCIM group
      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 a specific group created using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID.
        In Talon.One, a `Group` corresponds to a [role](https://docs.talon.one/docs/product/account/account-settings/managing-roles), and `members` are the [users](https://docs.talon.one/docs/product/account/account-settings/managing-users) assigned to that role.
      tags:
        - Accounts and users
      parameters:
        - name: groupId
          in: path
          description: The ID of the group.
          example: 44
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: No Content
    put:
      operationId: scimReplaceGroupAttributes
      summary: Update SCIM group
      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 group created using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID. This endpoint replaces all attributes of the given group with the attributes provided in the request payload.
        In Talon.One, a `Group` corresponds to a [role](https://docs.talon.one/docs/product/account/account-settings/managing-roles), and `members` are the [users](https://docs.talon.one/docs/product/account/account-settings/managing-users) assigned to that role.
      tags:
        - Accounts and users
      parameters:
        - name: groupId
          in: path
          description: The ID of the group.
          example: 44
          required: true
          schema:
            type: integer
      requestBody:
        $ref: '#/components/requestBodies/ScimNewGroup'
      responses:
        '200':
          description: Group details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimGroup'
    patch:
      operationId: scimPatchGroup
      summary: Update SCIM group attributes
      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 certain attributes of a group created using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID. This endpoint allows for selective adding, removing, or replacing of specific group attributes while other attributes remain unchanged.
        In Talon.One, a `Group` corresponds to a [role](https://docs.talon.one/docs/product/account/account-settings/managing-roles), and `members` are the [users](https://docs.talon.one/docs/product/account/account-settings/managing-users) assigned to that role.
      tags:
        - Accounts and users
      parameters:
        - name: groupId
          in: path
          description: The ID of the group.
          example: 44
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScimPatchRequest'
        description: body
        required: true
      responses:
        '200':
          description: Group details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimGroup'
  /v1/provisioning/scim/Users:
    get:
      operationId: scimGetUsers
      summary: List SCIM users
      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 a paginated list of users that have been provisioned using the SCIM protocol with an identity provider, for example, Microsoft Entra ID.
      tags:
        - Accounts and users
      responses:
        '200':
          description: List of SCIM users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimUsersListResponse'
    post:
      operationId: scimCreateUser
      summary: Create SCIM user
      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 new Talon.One user using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID.
      tags:
        - Accounts and users
      requestBody:
        $ref: '#/components/requestBodies/ScimNewUser'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimUser'
  /v1/provisioning/scim/Users/{userId}:
    get:
      operationId: scimGetUser
      summary: Get SCIM user
      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 data for a specific Talon.One user created using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID.
      tags:
        - Accounts and users
      parameters:
        - name: userId
          in: path
          description: The ID of the user.
          example: 33
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: User details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimUser'
    delete:
      operationId: scimDeleteUser
      summary: Delete SCIM user
      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 a specific Talon.One user created using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID.
      tags:
        - Accounts and users
      parameters:
        - name: userId
          in: path
          description: The ID of the user.
          example: 33
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: No Content
    put:
      operationId: scimReplaceUserAttributes
      summary: Update SCIM user
      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 Talon.One user created using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID.

        This endpoint replaces all attributes of the specific user with the attributes provided in the request payload.
      tags:
        - Accounts and users
      parameters:
        - name: userId
          in: path
          description: The ID of the user.
          example: 33
          required: true
          schema:
            type: integer
      requestBody:
        $ref: '#/components/requestBodies/ScimNewUser'
      responses:
        '200':
          description: User details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimUser'
    patch:
      operationId: scimPatchUser
      summary: Update SCIM user attributes
      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 certain attributes of a specific Talon.One user created using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID.

        This endpoint allows for selective adding, removing, or replacing specific attributes while leaving other attributes unchanged.
      tags:
        - Accounts and users
      parameters:
        - name: userId
          in: path
          description: The ID of the user.
          example: 33
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScimPatchRequest'
        description: body
        required: true
      responses:
        '200':
          description: User details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimUser'
  /v1/provisioning/scim/ResourceTypes:
    get:
      operationId: scimGetResourceTypes
      summary: List supported SCIM resource types
      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 a list of resource types supported by the SCIM provisioning protocol.

        Resource types define the various kinds of resources that can be managed via the SCIM API, such as users, groups, or custom-defined resources.
      tags:
        - Accounts and users
      responses:
        '200':
          description: List of resource types
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimResourceTypesListResponse'
  /v1/provisioning/scim/ServiceProviderConfig:
    get:
      operationId: scimGetServiceProviderConfig
      summary: Get SCIM service provider configuration
      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 configuration settings of the SCIM service provider. It provides details about the features and capabilities supported by the SCIM API, such as the different operation settings.
      tags:
        - Accounts and users
      responses:
        '200':
          description: Service configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimServiceProviderConfigResponse'
  /v1/provisioning/scim/Schemas:
    get:
      operationId: scimGetSchemas
      summary: List supported SCIM schemas
      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 a list of schemas supported by the SCIM provisioning protocol.

        Schemas define the structure and attributes of the different resources that can be managed via the SCIM API, such as users, groups, and any custom-defined resources.
      tags:
        - Accounts and users
      responses:
        '200':
          description: List of schemas supported by the SCIM provisioning protocol
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimSchemasListResponse'
  /v1/users/delete:
    post:
      operationId: deleteUserByEmail
      summary: Delete user by email address
      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 a specific user](https://docs.talon.one/docs/product/account/account-settings/managing-users#deleting-a-user) by their email address.
      tags:
        - Accounts and users
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteUserRequest'
        description: body
        required: true
      responses:
        '204':
          description: No Content
  /v1/users/activate:
    post:
      operationId: activateUserByEmail
      summary: Enable user by email address
      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.

        Enable a [disabled user](https://docs.talon.one/docs/product/account/account-settings/managing-users#disabling-a-user) by their email address.
      tags:
        - Accounts and users
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivateUserRequest'
        description: body
        required: true
      responses:
        '204':
          description: No Content
  /v1/users/deactivate:
    post:
      operationId: deactivateUserByEmail
      summary: Disable user by email address
      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.

        [Disable a specific user](https://docs.talon.one/docs/product/account/account-settings/managing-users#disabling-a-user) by their email address.
      tags:
        - Accounts and users
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeactivateUserRequest'
        description: body
        required: true
      responses:
        '204':
          description: No Content
  /v1/users/invite:
    post:
      operationId: inviteUserExternal
      summary: Invite user from identity provider
      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.

        [Invite a user](https://docs.talon.one/docs/product/account/account-settings/managing-users#inviting-a-user) from an external identity provider to Talon.One by sending an invitation to their email address.
      tags:
        - Accounts and users
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewExternalInvitation'
        description: body
        required: true
      responses:
        '204':
          description: Invitation email sent
  /v1/changes:
    get:
      operationId: getChanges
      summary: Get audit logs for an account
      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 audit logs displayed in **Accounts > Audit logs**.
      tags:
        - Logs
      parameters:
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/sort'
        - name: applicationId
          in: query
          description: Filter results by Application ID.
          example: 19
          required: false
          schema:
            type: number
        - name: entityPath
          in: query
          description: Filter results on a case insensitive matching of the url path of the entity
          example: example/url/path
          required: false
          schema:
            type: string
        - in: query
          description: Filter results by user ID.
          example: 34
          required: false
          name: userId
          schema:
            type: integer
        - name: createdBefore
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the change creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: createdAfter
          in: query
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the change creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          required: false
          example: '2024-05-29T15:04:05+07:00'
          schema:
            type: string
            format: date-time
        - name: withTotalResultSize
          in: query
          description: |
            When this flag is set, the result includes the total number of results for this query. This might decrease performance on large data sets.

            - When `true`: `totalResultSize` contains the total number of results for this query.
            - When `false`: Only `hasMore` is returned, and it is set to `true` when there are more results than shown on the page.
          example: false
          schema:
            type: boolean
        - name: managementKeyId
          in: query
          description: Filter results that match the given management key ID.
          example: 16
          required: false
          schema:
            type: integer
        - name: includeOld
          in: query
          description: When this flag is set to false, the state without the change will not be returned. The default value is true.
          example: false
          schema:
            type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  totalResultSize:
                    type: integer
                    example: 1
                  hasMore:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Change'
  /v2/invites:
    post:
      operationId: createInviteV2
      summary: Invite user
      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 new user in the account and send an invitation to their email
        address.

        > [!note] The invitation token is valid for 24 hours after the email has
        > been sent. You can resend an invitation to a user with the [Resend
        > invitation email](https://docs.talon.one/management-api#tag/Accounts-and-users/operation/createInviteEmail)
        > endpoint.
      tags:
        - Accounts and users
      requestBody:
        $ref: '#/components/requestBodies/NewInvitation'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /v1/invite_emails:
    post:
      operationId: createInviteEmail
      summary: Resend invitation email
      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.

        Resend an email invitation to an existing user.

        > [!note] The invitation token is valid for 24 hours after the email has been sent.
      tags:
        - Accounts and users
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewInviteEmail'
        description: body
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewInviteEmail'
  /v1/password_recovery_emails:
    post:
      operationId: createPasswordRecoveryEmail
      summary: Request a password reset
      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.

        Send an email with a password recovery link to the email address of an
        existing account.

        > [!note] The password recovery link expires 30 minutes after this endpoint is triggered.
      tags:
        - Accounts and users
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewPasswordEmail'
        description: body
        required: true
      responses:
        '204':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewPasswordEmail'
  /v1/reset_password:
    post:
      operationId: resetPassword
      summary: Reset password
      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.

        Consumes the supplied password reset token and updates the password for
        the associated account.
      tags:
        - Accounts and users
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewPassword'
        description: body
        required: true
      responses:
        '204':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewPassword'
  /v1/accounts/{accountId}:
    get:
      operationId: getAccount
      summary: Get account details
      description: |
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        Return the details of your companies Talon.One account.
      tags:
        - Accounts and users
      parameters:
        - name: accountId
          in: path
          description: |
            The identifier of the account. Retrieve it via the
            [List users in account](https://docs.talon.one/management-api#tag/Accounts-and-users/operation/getUsers) endpoint in the `accountId`
            property.
          example: 28
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
  /v1/accounts/{accountId}/analytics:
    get:
      operationId: getAccountAnalytics
      summary: Get account analytics
      description: |
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        Return the analytics of your Talon.One account.
      tags:
        - Accounts and users
      parameters:
        - name: accountId
          in: path
          description: |
            The identifier of the account. Retrieve it via the
            [List users in account](https://docs.talon.one/management-api#tag/Accounts-and-users/operation/getUsers) endpoint in the `accountId`
            property.
          example: 28
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountAnalytics'
  /v1/sessions:
    post:
      operationId: createSession
      summary: Create session
      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 session to use the Management API endpoints.

        Use the value of the `token` property provided in the response as bearer
        token in other API calls.

        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.

        This endpoint has a rate limit of 3 to 6 requests per second per account,
        depending on your setup.

        > [!note]
        > Instead of using a session, you can also use the <a href="https://docs.talon.one/docs/product/account/dev-tools/managing-mapi-keys">Management API key feature</a>
        > in the Campaign Manager to decide which endpoints can be used with a given key.
      tags:
        - Sessions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginParams'
        description: body
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
    delete:
      operationId: destroySession
      summary: Destroy session
      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.

        Destroys the session.
      tags:
        - Sessions
      responses:
        '204':
          description: No Content
  /v1/exports:
    get:
      operationId: getExports
      summary: Get exports
      description: |
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        List all past exports
      tags:
        - Logs
      parameters:
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - name: applicationId
          in: query
          description: Filter results by Application ID.
          example: 19
          required: false
          schema:
            type: number
        - name: campaignId
          in: query
          description: Filter by the campaign ID on which the limit counters are used.
          example: 8
          required: false
          schema:
            type: integer
        - name: entity
          in: query
          required: false
          description: The name of the entity type that was exported.
          example: Coupon
          schema:
            type: string
            enum:
              - Coupon
              - Referral
              - Effect
              - CustomerSession
              - LoyaltyLedger
              - LoyaltyLedgerLog
              - Collection
              - AudienceMembership
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - totalResultSize
                  - data
                properties:
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Export'
  /v2/roles:
    get:
      operationId: listAllRolesV2
      summary: List roles
      description: |
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        List the roles defined in the deployment.

        The roles returned depend on the role of the user calling this endpoint:
        - If the user has an admin role, all roles defined in the deployment are returned.
        - If the user does not have an admin role, only the roles currently assigned to this user are returned.

        If your identity provider provisions roles through SCIM, any admin roles it defines are not included in this list.

        To view the details of a specific role, use the [Get role](https://docs.talon.one/management-api#tag/Roles/operation/getRoleV2) endpoint.
      tags:
        - Roles
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - totalResultSize
                  - data
                properties:
                  totalResultSize:
                    type: integer
                    description: The total number of roles returned.
                    example: 1
                  data:
                    type: array
                    description: The list of roles.
                    items:
                      $ref: '#/components/schemas/RoleV2'
  /v2/roles/{roleId}:
    get:
      operationId: getRoleV2
      summary: Get role
      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 details of a specific role. To see all the roles, use the [List roles](/management-api#tag/Roles/operation/listAllRolesV2) endpoint.
      tags:
        - Roles
      parameters:
        - name: roleId
          in: path
          description: |
            The ID of role.

            **Note**: To find the ID of a role, use the [List roles](/management-api#tag/Roles/operation/listAllRolesV2) endpoint.
          example: 9
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleV2'
    put:
      operationId: updateRoleV2
      summary: Update role
      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 a specific role.
      tags:
        - Roles
      parameters:
        - name: roleId
          in: path
          description: |
            The ID of role.

            **Note**: To find the ID of a role, use the [List roles](/management-api#tag/Roles/operation/listAllRolesV2) endpoint.
          example: 9
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoleV2Base'
        description: body
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleV2'
  /v1/applications/{applicationId}/campaigns/{campaignId}/value_maps/{valueMapId}/export:
    get:
      operationId: exportCampaignValueMap
      summary: Export campaign value map
      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 all the value map items in a campaign. If
        there are multiple versions of the value map, only the items of the current
        version are exported.

        > [!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 generated file can contain the following columns:

        - `identifier`: The value of the attribute in the targeted item, for example, an item's SKU.
        - `value`: The value that is associated with the identifier, for example, the item's price.
      tags:
        - Value maps
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
        - name: valueMapId
          required: true
          in: path
          description: |
            The ID of the value map.
          example: 17
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/csv:
              schema:
                type: string
                format: csv
              examples:
                response:
                  value: |
                    identifier,value
                    sku-123,10.11
                    sku-234,595
        '400':
          description: Bad request
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '401':
          description: Unauthorized
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v1/applications/{applicationId}/stores:
    get:
      operationId: listStores
      summary: List stores
      description: |-
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        List all stores for a specific Application.
      tags:
        - Stores
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/sort'
        - name: withTotalResultSize
          in: query
          description: |
            When this flag is set, the result includes the total number of results for this query. This might decrease performance on large data sets.

            - When `true`: `totalResultSize` contains the total number of results for this query.
            - When `false`: Only `hasMore` is returned, and it is set to `true` when there are more results than shown on the page.
          example: false
          schema:
            type: boolean
        - name: campaignId
          in: query
          description: Filter results by campaign ID.
          example: 49
          schema:
            type: number
        - name: name
          description: The name of the store.
          example: store1
          required: false
          in: query
          schema:
            type: string
        - name: integrationId
          description: The integration ID of the store.
          example: storeId1
          required: false
          in: query
          schema:
            type: string
        - name: query
          description: Filter results by `name` or `integrationId`.
          example: name
          required: false
          in: query
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  hasMore:
                    type: boolean
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Store'
    post:
      operationId: createStore
      summary: Create store
      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 new store in a specific Application.
      tags:
        - Stores
      parameters:
        - $ref: '#/components/parameters/applicationId'
      requestBody:
        $ref: '#/components/requestBodies/NewStore'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Store'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict. A store with this integration ID already exists for this application.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v1/applications/{applicationId}/stores/{storeId}:
    get:
      operationId: getStore
      summary: Get store
      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 store details for a specific store ID.
      tags:
        - Stores
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - name: storeId
          required: true
          in: path
          description: |
            The ID of the store.
            You can get this ID with the [List stores](#tag/Stores/operation/listStores) endpoint.
          example: '17'
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Store'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
    put:
      operationId: updateStore
      summary: Update store
      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 store details for a specific store ID.
      tags:
        - Stores
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - name: storeId
          required: true
          in: path
          description: |
            The ID of the store.
            You can get this ID with the [List stores](#tag/Stores/operation/listStores) endpoint.
          example: '17'
          schema:
            type: string
      requestBody:
        $ref: '#/components/requestBodies/NewStore'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Store'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
    delete:
      operationId: deleteStore
      summary: Delete store
      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 specified store.
      tags:
        - Stores
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - name: storeId
          required: true
          in: path
          description: |
            The ID of the store.
            You can get this ID with the [List stores](#tag/Stores/operation/listStores) endpoint.
          example: '17'
          schema:
            type: string
      responses:
        '204':
          description: No Content
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v1/applications/{applicationId}/campaigns/{campaignId}/stores/export:
    get:
      operationId: exportCampaignStores
      summary: Export stores
      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 stores linked to a specific campaign.

        > [!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 column:

        - `store_integration_id`: The identifier of the store.
      tags:
        - Stores
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
      responses:
        '200':
          description: OK
          content:
            application/csv:
              schema:
                type: string
                format: csv
              examples:
                response:
                  value: |
                    store_integration_id
                    STORE-001
                    STORE-002
                    STORE-003
        '400':
          description: Bad request
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '404':
          description: Not found
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v1/applications/{applicationId}/cart_item_filters:
    get:
      operationId: listApplicationCartItemFilters
      summary: List Application cart item filters
      description: |-
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        Return all the Application cart item filters for a specific Application.
      tags:
        - Applications
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - name: pageSize
          in: query
          required: false
          description: The number of items in the response.
          example: 50
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 50
        - $ref: '#/components/parameters/skip'
        - name: name
          in: query
          description: |
            Filter by the display name of the Application cart item filter in the Application.

            **Note**: If no `name` is provided, all the Application cart item filters in the Application are returned.
          example: cartItemFilter1
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  hasMore:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApplicationCIF'
  /v1/applications/{applicationId}/cart_item_filters/{cartItemFilterId}/expressions/{expressionId}:
    get:
      operationId: getApplicationCartItemFilterExpression
      summary: Get Application cart item filter expression
      description: |-
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        Get an Application cart item filter expression for a specific Application.
      tags:
        - Applications
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - name: cartItemFilterId
          in: path
          description: The ID of the Application cart item filter. You can get this ID with the [List Application cart item filters](https://docs.talon.one/management-api#tag/Applications/operation/listApplicationCartItemFilters) endpoint.
          example: 20
          required: true
          schema:
            type: integer
        - name: expressionId
          in: path
          description: The ID of the Application cart item filter expression.
          example: 19
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationCIFExpression'
  /v1/applications/{applicationId}/campaigns/{campaignId}/stores:
    delete:
      operationId: disconnectCampaignStores
      summary: Disconnect stores
      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.

        Disconnect the stores linked to a specific campaign.
      tags:
        - Stores
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
      responses:
        '204':
          description: No Content
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v1/applications/{applicationId}/campaigns/{campaignId}/stores/import:
    post:
      operationId: importCampaignStores
      summary: Import stores
      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 stores you want to link to a specific campaign.

        Send the file as multipart data.

        The CSV file **must** only contain the following column:
        - `store_integration_id`: The identifier of the store.

        The import **replaces** the previous list of stores linked to the campaign.
      tags:
        - Stores
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
      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'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v1/applications/{applicationId}/campaigns/{campaignId}/stores/budgets:
    post:
      operationId: createCampaignStoreBudget
      summary: Create campaign store budget
      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 new store budget for a given campaign.
      tags:
        - Store budgets
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewCampaignStoreBudget'
        description: body
        required: true
      responses:
        '201':
          description: Created
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      operationId: listCampaignStoreBudgetLimits
      summary: List campaign store budget limits
      description: |-
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        Return the store budget limits for a given campaign.
      tags:
        - Store budgets
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
        - name: action
          in: query
          description: The action that this budget is limiting.
          example: setDiscount
          required: false
          schema:
            type: string
            enum:
              - setDiscount
        - name: period
          in: query
          description: |
            The period to which the limit applies.

            **Note**: For budgets with no period, set this to `overall`.
          example: weekly
          required: false
          schema:
            type: string
            enum:
              - overall
              - daily
              - weekly
              - monthly
              - yearly
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ListCampaignStoreBudgets'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: deleteCampaignStoreBudgets
      summary: Delete campaign store budgets
      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 store budgets for a given campaign.
      tags:
        - Store budgets
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
        - name: action
          in: query
          description: The action that this budget is limiting.
          example: setDiscount
          required: false
          schema:
            type: string
            enum:
              - setDiscount
        - name: period
          in: query
          description: |
            The period to which the limit applies.

            **Note**: For budgets with no period, set this to `overall`.
          example: weekly
          required: false
          schema:
            type: string
            enum:
              - overall
              - daily
              - weekly
              - monthly
              - yearly
      responses:
        '204':
          description: Deleted
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/applications/{applicationId}/campaigns/{campaignId}/stores/budgets/summary:
    get:
      operationId: summarizeCampaignStoreBudget
      summary: Get summary of campaign store budgets
      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.

        Fetch a summary of all store budget information for a given campaign.
      tags:
        - Store budgets
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SummaryCampaignStoreBudget'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/applications/{applicationId}/campaigns/{campaignId}/stores/budgets/import:
    post:
      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
      operationId: importCampaignStoreBudget
      summary: Import campaign store budgets
      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 store budgets for a given campaign.

        Send the file as multipart data.

        The CSV file **must** only contain the following columns:
        - `store_integration_id`: The identifier of the store.
        - `limit`: The budget limit for the store.

        The import **replaces** the previous list of store budgets.
      tags:
        - Store budgets
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
        - name: action
          in: query
          description: The action that this budget is limiting.
          example: setDiscount
          required: false
          schema:
            type: string
            enum:
              - setDiscount
        - name: period
          in: query
          description: |
            The period to which the limit applies.

            **Note**: For budgets with no period, set this to `overall`.
          example: weekly
          required: false
          schema:
            type: string
            enum:
              - overall
              - daily
              - weekly
              - monthly
              - yearly
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Import'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/applications/{applicationId}/campaigns/{campaignId}/stores/budgets/export:
    get:
      operationId: exportCampaignStoreBudgets
      summary: Export campaign store budgets
      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 store budgets for a given campaign.

        > [!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:

        - `store_integration_id`: The identifier of the store.
        - `limit`: The budget limit for the store.
      tags:
        - Store budgets
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
        - name: action
          in: query
          description: The action that this budget is limiting.
          example: setDiscount
          required: false
          schema:
            type: string
            enum:
              - setDiscount
        - name: period
          in: query
          description: |
            The period to which the limit applies.

            **Note**: For budgets with no period, set this to `overall`.
          example: weekly
          required: false
          schema:
            type: string
            enum:
              - overall
              - daily
              - weekly
              - monthly
              - yearly
      responses:
        '200':
          description: OK
          content:
            application/csv:
              schema:
                type: string
                format: csv
              examples:
                response:
                  value: |
                    store_integration_id,limit
                    STORE-001,10
                    STORE-002,20
                    STORE-003,30
        '400':
          description: Bad request
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/applications/{applicationId}/campaigns/{campaignId}/achievements:
    post:
      deprecated: true
      operationId: createAchievement
      summary: Create achievement
      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 new achievement in a specific campaign.
      tags:
        - Achievements
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAchievement'
        description: body
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Achievement'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
    get:
      deprecated: true
      operationId: listAchievements
      summary: List achievements
      description: |-
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        List all the achievements for a specific campaign.
      tags:
        - Achievements
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
        - name: pageSize
          in: query
          required: false
          description: The number of items in the response.
          example: 50
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 50
        - $ref: '#/components/parameters/skip'
        - name: title
          in: query
          description: |
            Filter by the display name for the achievement in the campaign manager.

            **Note**: If no `title` is provided, all the achievements from the campaign are returned.
          example: achievement1
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  hasMore:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Achievement'
  /v1/applications/{applicationId}/campaigns/{campaignId}/achievements/{achievementId}:
    get:
      deprecated: true
      operationId: getAchievement
      summary: Get achievement
      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 details of a specific achievement.
      tags:
        - Achievements
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
        - name: achievementId
          in: path
          description: The ID of the achievement. You can get this ID with the [List achievement](https://docs.talon.one/management-api#tag/Achievements/operation/listAchievements) endpoint.
          example: 45
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Achievement'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
    put:
      deprecated: true
      operationId: updateAchievement
      summary: Update achievement
      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 achievement.
      tags:
        - Achievements
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
        - name: achievementId
          in: path
          description: The ID of the achievement. You can get this ID with the [List achievement](https://docs.talon.one/management-api#tag/Achievements/operation/listAchievements) endpoint.
          example: 45
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAchievement'
        description: body
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Achievement'
        '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'
    delete:
      deprecated: true
      operationId: deleteAchievement
      summary: Delete achievement
      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 specified achievement.
      tags:
        - Achievements
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
        - name: achievementId
          in: path
          description: The ID of the achievement. You can get this ID with the [List achievement](https://docs.talon.one/management-api#tag/Achievements/operation/listAchievements) endpoint.
          example: 45
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: No Content
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v1/applications/{applicationId}/campaigns/{campaignId}/achievements/{achievementId}/export:
    get:
      deprecated: true
      operationId: exportAchievements
      summary: Export achievement customer 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.

        Download a CSV file containing a list of all the customers who have participated in and are currently participating in the given achievement.

        The CSV file contains the following columns:
        - `profileIntegrationID`: The integration ID of the customer profile participating in the achievement.
        - `title`: The display name of the achievement in the Campaign Manager.
        - `target`: The required number of actions or the transactional milestone to complete the achievement.
        - `progress`: The current progress of the customer in the achievement.
        - `status`: The status of the achievement. Can be one of: ['inprogress', 'completed', 'expired'].
        - `startDate`: The date on which the customer profile started the achievement in RFC3339.
        - `endDate`: The date on which the achievement ends and resets for the customer profile in RFC3339.
        - `completionDate`: The date on which the customer profile completed the achievement in RFC3339.
      tags:
        - Achievements
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - $ref: '#/components/parameters/campaignId'
        - name: achievementId
          in: path
          description: The ID of the achievement. You can get this ID with the [List achievement](https://docs.talon.one/management-api#tag/Achievements/operation/listAchievements) endpoint.
          example: 45
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/csv:
              schema:
                type: string
                format: csv
              examples:
                response:
                  value: |
                    profileIntegrationID,title,target,progress,status,startDate,endDate,completionDate
                    user1231,CoffeeFree10Orders,10.00,5,inprogress,2023-12-10T11:42:25+01:00,2024-01-10T11:42:25+01:00,
                    user341,CoffeeFree10Orders,10.00,10,completed,2023-12-10T11:42:25+01:00,2024-01-10T11:42:25+01:00,2023-12-20T10:24:34+01:00
        '400':
          description: Bad request
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '401':
          description: Unauthorized
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '404':
          description: Not found
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v2/achievements:
    get:
      operationId: listAchievementsV2
      summary: List achievements
      description: |
        > [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

        List all achievements.
      tags:
        - Achievements
      parameters:
        - name: pageSize
          in: query
          required: false
          description: The number of items in the response.
          example: 50
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 50
        - name: campaignId
          in: query
          required: false
          style: form
          explode: true
          description: |
            Filter results by one or more campaign IDs.

            To include multiple IDs, repeat the parameter for each one, for example,`?campaignId=123&campaignId=456`.
            The response contains only achievements associated with the specified campaigns.
          schema:
            type: array
            items:
              type: integer
          example:
            - 123
            - 456
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/sort'
        - name: title
          in: query
          description: Filter by the display name of the achievement.
          example: achievement1
          required: false
          schema:
            type: string
        - name: applicationId
          in: query
          description: Filter by the ID of an Application connected to the achievement.
          example: 42
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  hasMore:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AchievementV2'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
    post:
      operationId: createAchievementV2
      summary: Create achievement
      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 new account-level achievement.
      tags:
        - Achievements
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAchievementV2'
        description: body
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AchievementV2'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v2/achievements/{achievementId}:
    get:
      operationId: getAchievementV2
      summary: Get achievement
      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 details of a specific achievement.
      tags:
        - Achievements
      parameters:
        - name: achievementId
          in: path
          required: true
          description: |
            The ID of the achievement.  You can get this ID with the [List achievement](https://docs.talon.one/management-api#tag/Achievements/operation/listAchievementsV2) endpoint.
          example: 45
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AchievementV2'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
    put:
      operationId: updateAchievementV2
      summary: Update achievement
      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 achievement.
      tags:
        - Achievements
      parameters:
        - name: achievementId
          in: path
          required: true
          description: The ID of the achievement. You can get this ID with the [List achievement](https://docs.talon.one/management-api#tag/Achievements/operation/listAchievementsV2) endpoint.
          example: 45
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAchievementV2'
        description: body
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AchievementV2'
        '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'
    delete:
      operationId: deleteAchievementV2
      summary: Delete achievement
      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 a specific achievement.
      tags:
        - Achievements
      parameters:
        - name: achievementId
          in: path
          required: true
          description: The ID of the achievement. You can get this ID with the [List achievement](https://docs.talon.one/management-api#tag/Achievements/operation/listAchievementsV2) endpoint.
          example: 45
          schema:
            type: integer
      responses:
        '204':
          description: No Content
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v2/achievements/{achievementId}/export:
    get:
      operationId: exportAchievementV2
      summary: Export achievement customer 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.

        Download a CSV file containing a list of all the customers who have participated in and are currently participating in the given achievement.

        The CSV file contains the following columns:
        - `profileIntegrationID`: The integration ID of the customer profile participating in the achievement.
        - `title`: The display name of the achievement in the Campaign Manager.
        - `target`: The required number of actions or the transactional milestone to complete the achievement.
        - `progress`: The current progress of the customer in the achievement.
        - `status`: The status of the achievement. Can be one of: ['inprogress', 'completed', 'expired'].
        - `startDate`: The date on which the customer profile started the achievement in RFC3339.
        - `endDate`: The date on which the achievement ends and resets for the customer profile in RFC3339.
        - `completionDate`: The date on which the customer profile completed the achievement in RFC3339.
      tags:
        - Achievements
      parameters:
        - name: achievementId
          in: path
          description: The ID of the achievement. You can get this ID with the [List achievements](https://docs.talon.one/management-api#tag/Achievements/operation/listAchievementsV2) endpoint.
          example: 45
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/csv:
              schema:
                type: string
                format: csv
              examples:
                response:
                  value: |
                    profileIntegrationID,title,target,progress,status,startDate,endDate,completionDate
                    user1231,CoffeeFree10Orders,10.00,5,inprogress,2023-12-10T11:42:25+01:00,2024-01-10T11:42:25+01:00,
                    user341,CoffeeFree10Orders,10.00,10,completed,2023-12-10T11:42:25+01:00,2024-01-10T11:42:25+01:00,2023-12-20T10:24:34+01:00
        '400':
          description: Bad request
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '401':
          description: Unauthorized
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '404':
          description: Not found
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v1/applications/{applicationId}/campaign_analytics/export:
    get:
      operationId: exportApplicationCampaignAnalytics
      summary: Export Application analytics aggregated by campaign
      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 analytics data aggregated by campaign for the
        campaigns of an Application.

        > [!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:

        - `campaign_id`: The ID of the campaign. This column also contains labels
          for the [total and influenced values](https://docs.talon.one/docs/product/campaigns/analytics/application-dashboard#display-the-analytics-data).
        - `start_date`: The start of the aggregation time frame in UTC.
        - `end_date`: The end of the aggregation time frame in UTC.
        - `revenue`: The total, pre-discount value of all items purchased in a customer session.
        - `sessions`: The number of all closed sessions.
        - `average_session_value`: The average customer session value, calculated by dividing the revenue value by the number of sessions.
        - `average_items_per_session`: The number of items from sessions divided by the number of sessions.
        - `coupons`: The number of times a coupon was successfully redeemed in sessions.
        - `discounts`: The total value of discounts given for cart items in sessions.
      tags:
        - Campaigns
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - name: campaignIds
          in: query
          required: false
          description: |
            Filter by one or more Campaign IDs, separated by a comma.

            **Note:** If no campaigns are specified, data for all the campaigns in the Application is returned.
          example:
            - '11'
            - '20'
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
        - name: 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
      responses:
        '200':
          description: OK
          content:
            application/csv:
              schema:
                type: string
                format: csv
              examples:
                response:
                  value: |
                    campaign_id,start_date,end_date,revenue,sessions,average_session_value,average_items_per_session,coupons,discounts
                    Total,2025-02-01T00:00:00+00:00,2025-02-07T00:00:00+00:00,751916.88,5919,127.03,3.96,N/A,N/A
                    Influenced,2025-02-01T00:00:00+00:00,2025-02-07T00:00:00+00:00,525816.00,5246,100.23,4.46,374,47675.73
                    41,2025-02-01T00:00:00+00:00,2025-02-07T00:00:00+00:00,284089.80,3105,91.49,4.62,247,8435.65
                    75,2025-02-01T00:00:00+00:00,2025-02-07T00:00:00+00:00,416001.81,4771,87.19,4.52,0,16768.71
                    178,2025-02-01T00:00:00+00:00,2025-02-07T00:00:00+00:00,313390.53,1098,285.42,4.81,65,16097.05
                    195,2025-02-01T00:00:00+00:00,2025-02-07T00:00:00+00:00,34345.86,595,57.72,4.58,62,6374.32
  /v1/applications/{applicationId}/achievement_progress/{integrationId}:
    get:
      operationId: getCustomerProfileAchievementProgress
      summary: List customer achievements
      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 customer profile, list all the achievements that match your filter criteria.
      tags:
        - Achievements
      parameters:
        - $ref: '#/components/parameters/applicationId'
        - 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: pageSize
          in: query
          required: false
          description: The number of items in the response.
          example: 50
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 50
        - $ref: '#/components/parameters/skip'
        - name: achievementId
          in: query
          description: The ID of the achievement. You can get this ID with the [List achievement](https://docs.talon.one/management-api#tag/Achievements/operation/listAchievements) endpoint.
          example: 41
          required: false
          schema:
            type: integer
        - name: title
          in: query
          required: false
          description: Filter results by the `title` of an achievement.
          example: achievement1
          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/AchievementProgressWithDefinition'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
  /v1/coupon_rejections:
    get:
      operationId: generateCouponRejections
      summary: Summarize coupon redemption failures in session
      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 summary of the reasons for coupon redemption failures in a given customer session.
      tags:
        - Coupons
      parameters:
        - name: sessionIntegrationId
          in: query
          description: The integration ID of the session to summarize.
          example: cc53e4fa-547f-4f5e-8333-76e05c381f67
          required: true
          schema:
            type: string
        - name: applicationId
          in: query
          description: Filter results by Application ID.
          example: 19
          schema:
            type: number
        - name: language
          in: query
          description: |
            The [ISO-639](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) code of the language
            in which the summary will be generated.
          example: en
          schema:
            type: string
        - name: couponCode
          in: query
          description: The coupon code for which to get the rejection reason.
          example: SUMMER2025
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CouponFailureSummary'
webhooks: {}
components:
  securitySchemes:
    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
        the admin who created the key.

        Using an API key is the recommended authentication method.

        The key must be generated by an admin and given to the developer that
        requires it:

        1. Sign in to the Campaign Manager and click **Account** > **Tools** >
        **Management API Keys**.
        1. Click **Create Key** and give it a name.
        1. Set an expiration date.
           **Tip**: Avoid choosing expiration dates that fall at the end of the year or during other high-traffic periods.
        1. Choose the endpoints the key should give access to.
        1. Click **Create Key**.
        1. Share it with your developer.

        The developer can now use the API key in the HTTP header, prefixing it
        with `ManagementKey-v1`:

        ```
        Authorization: ManagementKey-v1 bd9479c59e16f9dbc644d33aa74d58270fe13bf3
        ```
  schemas:
    Entity:
      type: object
      required:
        - id
        - created
      properties:
        id:
          type: integer
          description: The internal ID of this entity.
          example: 6
        created:
          type: string
          format: date-time
          description: The time this entity was created.
          example: '2020-06-10T09:05:27.993483Z'
    IntegrationEntity:
      type: object
      required:
        - integrationId
        - created
      properties:
        integrationId:
          type: string
          format: string
          example: URNGV8294NV
          maxLength: 1000
          description: The integration ID set by your integration layer.
        created:
          type: string
          format: date-time
          description: The time this entity was created.
          example: '2020-02-07T08:15:22Z'
    ApplicationEntity:
      type: object
      required:
        - applicationId
      properties:
        applicationId:
          type: integer
          description: The ID of the Application that owns this entity.
          example: 322
    IntegrationStoreEntity:
      type: object
      properties:
        storeIntegrationId:
          type: string
          minLength: 1
          maxLength: 1000
          description: The integration ID of the store. You choose this ID when you create a store.
          example: STORE-001
    Product:
      type: object
      description: The specific properties of the product this item belongs to, if available.
      required:
        - name
      properties:
        name:
          type: string
          description: The product the item belongs to.
          example: sample_product
    AdditionalCost:
      type: object
      required:
        - price
      properties:
        price:
          title: Price of additional cost
          type: number
          example: 4.5
    PriceDetail:
      type: object
      properties:
        price:
          type: number
          format: float
          description: The value of this price type.
          example: 90
        adjustmentContextId:
          type: string
          description: The context identifier of the selected price adjustment.
          example: summer25
        adjustmentReferenceId:
          type: string
          format: uuid
          description: The reference identifier of the selected price adjustment for this SKU.
          example: 68851723-e6fa-488f-ace9-112581e6c19b
        adjustmentEffectiveFrom:
          type: string
          format: date-time
          description: The date and time from which the price adjustment is effective.
          example: '2025-05-25T00:00:00Z'
        adjustmentEffectiveUntil:
          type: string
          format: date-time
          description: The date and time until which the price adjustment is effective.
          example: '2025-05-30T00:00:00Z'
    CartItem:
      type: object
      required:
        - sku
        - quantity
      properties:
        name:
          title: Name of item
          type: string
          description: Name of item.
          example: Air Glide
        sku:
          title: SKU of item
          type: string
          description: Stock keeping unit of item.
          minLength: 1
          example: SKU1241028
        quantity:
          title: Quantity of item
          type: integer
          description: |
            Number of units of this item. Due to [cart item flattening](https://docs.talon.one/docs/product/rules/understanding-cart-item-flattening),
            if you provide a quantity greater than 1, the item will be split in as many items as the provided quantity.
            This will impact the number of **per-item** effects triggered from your campaigns.
          minimum: 1
          example: 1
        returnedQuantity:
          title: Returned quantity of item
          type: integer
          readOnly: true
          description: Number of returned items, calculated internally based on returns of this item.
          example: 1
        remainingQuantity:
          title: Remaining quantity of item
          type: integer
          readOnly: true
          description: Remaining quantity of the item, calculated internally based on returns of this item.
          example: 1
        price:
          title: Price of item
          type: number
          description: |
            Price of the item in the currency defined by your Application. This field is required if this item is not part of a [catalog](https://docs.talon.one/docs/product/account/dev-tools/managing-cart-item-catalogs). If it is part of a catalog, setting a price here overrides the price from the catalog.
          example: 99.99
        category:
          title: Item category
          type: string
          description: Type, group or model of the item.
          example: shoes
        product:
          $ref: '#/components/schemas/Product'
          title: Item product
        weight:
          title: Weight of item
          type: number
          description: Weight of item in grams.
          example: 1130
        height:
          title: Height of item
          type: number
          description: Height of item in mm.
        width:
          title: Width of item
          type: number
          description: Width of item in mm.
        length:
          title: Length of item
          type: number
          description: Length of item in mm.
        position:
          title: Position of Cart Item
          type: number
          readOnly: true
          description: Position of the Cart Item in the Cart (calculated internally).
        attributes:
          title: Item attributes
          type: object
          description: |
            Use this property to set a value for the attributes of your choice. [Attributes](https://docs.talon.one/docs/dev/concepts/attributes) represent any information to attach to this cart item.

            Custom _cart item_ attributes must be created in the Campaign Manager before you set them with this property.

            **Note:** Any previously defined attributes that you do not include in the array will be removed.
          example:
            image: 11.jpeg
            material: leather
        additionalCosts:
          type: object
          description: |
            Use this property to set a value for the additional costs of this item, such as a shipping cost. They must be created in the Campaign Manager
            before you set them with this property. See [Managing additional costs](https://docs.talon.one/docs/product/account/dev-tools/managing-additional-costs).
          additionalProperties:
            $ref: '#/components/schemas/AdditionalCost'
          example:
            shipping:
              price: 9
        catalogItemID:
          title: The catalog item ID
          type: integer
          readOnly: true
          description: The catalog item ID.
        selectedPriceType:
          title: Price Type
          type: string
          readOnly: true
          description: The selected price type for this cart item (e.g. the price for members only).
          example: member
        adjustmentReferenceId:
          title: Price Adjustment ID
          type: string
          format: uuid
          readOnly: true
          description: The reference ID of the selected price adjustment for this cart item. Only returned if the selected price resulted from a price adjustment.
          example: 68851723-e6fa-488f-ace9-112581e6c19b
        adjustmentEffectiveFrom:
          title: Price Adjustment Start Date
          type: string
          format: date-time
          readOnly: true
          description: The date and time from which the price adjustment is effective. Only returned if the selected price resulted from a price adjustment that contains this field.
          example: '2021-09-12T10:12:42Z'
        adjustmentEffectiveUntil:
          title: Price Adjustment Expiry Date
          type: string
          format: date-time
          readOnly: true
          description: The date and time until which the price adjustment is effective. Only returned if the selected price resulted from a price adjustment that contains this field.
          example: '2021-09-12T10:12:42Z'
        prices:
          readOnly: true
          type: object
          description: |
            A map of keys and values representing the price types and related price adjustment details for this cart item.
            The keys correspond to the `priceType` names.
          additionalProperties:
            $ref: '#/components/schemas/PriceDetail'
          example:
            member:
              price: 90
              adjustmentReferenceId: 68851723-e6fa-488f-ace9-112581e6c19b
              effectiveFrom: '2025-05-25T00:00:00Z'
              effectiveUntil: '2025-05-30T00:00:00Z'
            base:
              price: 100
    EffectEntity:
      type: object
      description: Definition of all properties that are present on all effects, independent of their type.
      required:
        - campaignId
        - rulesetId
        - ruleIndex
        - ruleName
        - effectType
      properties:
        experimentId:
          type: integer
          description: The ID of the experiment that campaign belongs to.
          example: 12
        campaignId:
          type: integer
          description: The ID of the campaign that triggered this effect.
          example: 244
        rulesetId:
          type: integer
          description: The ID of the ruleset that was active in the campaign when this effect was triggered.
          example: 73
        ruleIndex:
          type: integer
          description: The position of the rule that triggered this effect within the ruleset.
          example: 2
        ruleName:
          type: string
          description: The name of the rule that triggered this effect.
          example: Give 20% discount
        effectType:
          type: string
          description: See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          example: rejectCoupon
        triggeredByCoupon:
          type: integer
          example: 4928
          description: The ID of the coupon that was being evaluated when this effect was triggered.
        triggeredForCatalogItem:
          type: integer
          example: 786
          description: The ID of the catalog item that was being evaluated when this effect was triggered.
        conditionIndex:
          type: integer
          example: 786
          description: The index of the condition that was triggered.
        evaluationGroupID:
          type: integer
          example: 3
          description: The ID of the evaluation group. For more information, see [Managing campaign evaluation](https://docs.talon.one/docs/product/applications/managing-campaign-evaluation).
        evaluationGroupMode:
          type: string
          example: stackable
          description: The evaluation mode of the evaluation group. For more information, see [Managing campaign evaluation](https://docs.talon.one/docs/product/applications/managing-campaign-evaluation).
        campaignRevisionId:
          type: integer
          example: 1
          description: The revision ID of the campaign that was used when triggering the effect.
        campaignRevisionVersionId:
          type: integer
          example: 5
          description: The revision version ID of the campaign that was used when triggering the effect.
        selectedPriceType:
          type: string
          example: member
          description: The selected price type for the SKU targeted by this effect.
        selectedPrice:
          type: number
          example: 100
          description: The value of the selected price type to apply to the SKU targeted by this effect, before any discounts are applied.
        adjustmentReferenceId:
          type: string
          format: uuid
          example: 68851723-e6fa-488f-ace9-112581e6c19b
          description: The reference identifier of the selected price adjustment for this SKU. This is only returned if the `selectedPrice` resulted from a price adjustment.
        rewardId:
          type: integer
          example: 7
          description: The ID of the reward that was being evaluated when this effect was triggered.
        rewardIntegrationId:
          type: string
          example: reward-unlock-123
          description: The integration ID of the specific customer reward whose usage produced this effect.
    AcceptCouponEffectProps:
      type: object
      title: acceptCoupon
      description: |-
        This effect indicates that the coupon code supplied was valid.

        You should handle this effect by clearing any messages from previous `rejectCoupon` effects and informing the user that the coupon is valid.

        The code is automatically redeemed when you close the session.

        Other effects, such as [setDiscount](https://docs.talon.one/docs/dev/integration-api/api-effects#setdiscount), provide more information about the actual rewards received.
      example:
        value: COUP-XYZ789
      required:
        - value
      properties:
        value:
          type: string
          description: The coupon code that was accepted.
    RollbackCouponEffectProps:
      type: object
      title: rollbackCoupon
      description: |-
        This effect indicates that a coupon code redemption has been rolled back. The coupon becomes redeemable again.

        The effect is triggered when you [cancel](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions#manage-the-sessions-state) a session where a coupon was accepted. See an example of use in the [cancelling a session tutorial](https://docs.talon.one/docs/dev/tutorials/roll-back-effects).
      example:
        value: COUP-XYZ789
      required:
        - value
      properties:
        value:
          type: string
          description: The coupon code whose redemption has been rolled back.
    EffectRollbackCoupon:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: rollbackCoupon
          description: The `rollbackCoupon` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - rollbackCoupon
              description: An effect discriminator of type `rollbackCoupon`.
            props:
              $ref: '#/components/schemas/RollbackCouponEffectProps'
    EffectAcceptCoupon:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: acceptCoupon
          x-rollback-effect:
            $ref: '#/components/schemas/EffectRollbackCoupon'
          description: The `acceptCoupon` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - acceptCoupon
              description: An effect discriminator of type `acceptCoupon`.
            props:
              $ref: '#/components/schemas/AcceptCouponEffectProps'
    AcceptReferralEffectProps:
      type: object
      title: acceptReferral
      description: |-
        This effect indicates that the referral code supplied is valid.

        You should handle this effect by informing the user that the referral code is valid.

        The code is automatically redeemed when you close the session.

        Other effects will provide more information about the actual reward.
      example:
        value: REF-ABC123
      required:
        - value
      properties:
        value:
          type: string
          description: The referral code provided in the session.
    RollbackReferralEffectProps:
      type: object
      title: rollbackReferral
      description: |-
        This effect indicates that the redemption of the referral code has been rolled back. It triggers when a closed session that redeemed a referral is gets cancelled. The code becomes redeemable again.

        For more information about session states, see [Managing states](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions#customer-session-states).
      example:
        value: REF-ABC123
      required:
        - value
      properties:
        value:
          type: string
          description: The referral code to be rolled back.
    EffectRollbackReferral:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: rollbackReferral
          description: The `rollbackReferral` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - rollbackReferral
              description: An effect discriminator of type `rollbackReferral`.
            props:
              $ref: '#/components/schemas/RollbackReferralEffectProps'
    EffectAcceptReferral:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: acceptReferral
          x-rollback-effect:
            $ref: '#/components/schemas/EffectRollbackReferral'
          description: The `acceptReferral` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - acceptReferral
              description: An effect discriminator of type `acceptReferral`.
            props:
              $ref: '#/components/schemas/AcceptReferralEffectProps'
    AddFreeItemEffectProps:
      type: object
      title: addFreeItem
      description: This effect indicates that a free item should be added to the shopping cart in the current session. In this example, add the SKU to the shopping cart and set its price to `0`.
      example:
        sku: SKU1241028
        name: Free Gift Item
        desiredQuantity: 1
      required:
        - sku
        - name
      properties:
        sku:
          type: string
          description: SKU of the item that needs to be added.
          example: SKU1241028
        name:
          type: string
          description: Description of the effect.
        desiredQuantity:
          type: integer
          description: The original quantity in case a partial reward was applied.
    EffectAddFreeItem:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: addFreeItem
          description: The `addFreeItem` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - addFreeItem
              description: An effect discriminator of type `addFreeItem`.
            props:
              $ref: '#/components/schemas/AddFreeItemEffectProps'
    LoyaltyCardIdentifier:
      type: string
      description: |
        The identifier of the loyalty card, which must match the regular expression `^[A-Za-z0-9._%+@-]+$`.
      maxLength: 108
      minLength: 4
      pattern: ^[A-Za-z0-9._%+@-]+$
      example: summer-loyalty-card-0543
    AddLoyaltyPointsEffectProps:
      type: object
      title: addLoyaltyPoints
      description: |-
        This effect indicates that a defined amount of loyalty points was successfully added to the customer's profile or to a loyalty card.

        If you use the [Add loyalty points per item effect](https://docs.talon.one/docs/product/rules/effects/available-effects#reward-effects), use the `cartItemPosition` property to identify which item to add the loyalty points for.

        Enabling [partial rewards](https://docs.talon.one/docs/product/applications/manage-general-settings#partial-rewards) allows a rule that would fail because of insufficient budget to pass. The rule still fails when the budget reaches 0. Use the `desiredValue` property to identify the original amount of loyalty points.

        If you use **Add loyalty points per item** and if the session contains some cart items with _quantity > 1_, use the `cartItemSubPosition` property to identify the item unit in its line item. See the example below for more information.

        If your list of cart items is a [bundle definition](https://docs.talon.one/docs/product/rules/create-and-manage-bundles), use the `bundleIndex` and `bundleName` properties to identify the bundle containing the items for which loyalty points are added.

        If you have set custom activation and expiration dates for the loyalty points, use the `startDate` and `expiryDate` properties to identify when the reward will be active and when will expire.

        If the loyalty program is [profile-based](https://docs.talon.one/docs/product/loyalty-programs/overview#loyalty-program-types), use the `recipientIntegrationId` property to identify the user who receives the loyalty points. If the loyalty program is [card-based](https://docs.talon.one/docs/product/loyalty-programs/overview#loyalty-program-types), use the `cardIdentifier` property to identify the loyalty card on which these points are added.

        The points only persist when the session is closed.
      example:
        name: Points for purchase
        programId: 5
        subLedgerId: main
        value: 100
        desiredValue: 100
        recipientIntegrationId: URNGV8294NV
        startDate: '2024-01-01T00:00:00Z'
        expiryDate: '2025-01-01T00:00:00Z'
        transactionUUID: 8c2d3670-6ea5-4e9e-b5c6-e7e7b4a10111
        cartItemPosition: 1
        cartItemSubPosition: 1
        cardIdentifier: loyalty-card-001
        bundleIndex: 1
        bundleName: my_bundle
        awaitsActivation: false
        validityDuration: 12M
      required:
        - name
        - programId
        - subLedgerId
        - value
        - recipientIntegrationId
        - transactionUUID
      properties:
        name:
          type: string
          description: The reason of this loyalty point addition.
        programId:
          type: integer
          description: The ID of the loyalty program where these points were added.
        subLedgerId:
          type: string
          description: The ID of the subledger within the loyalty program where these points were added.
        value:
          type: number
          description: The amount of points that were added.
        desiredValue:
          type: number
          description: (Partial rewards enabled only) The amount of loyalty points to be awarded without considering budget limitations.
        recipientIntegrationId:
          type: string
          maxLength: 1000
          description: The user for whom these points were added.
          example: URNGV8294NV
        startDate:
          type: string
          format: date-time
          description: The date after which the added points will be valid.
        expiryDate:
          type: string
          format: date-time
          description: The date after which the added points will expire.
        transactionUUID:
          type: string
          description: The identifier of this loyalty point transaction.
        cartItemPosition:
          type: number
          description: (_Add points per cart item_ only.) The index of the item in the `cartItem` object for which these points were added.
        cartItemSubPosition:
          type: number
          description: (_Add points per cart item_ ) The index of the item unit in its line item.
        cardIdentifier:
          $ref: '#/components/schemas/LoyaltyCardIdentifier'
          description: The identifier of the card on which these points were added.
        bundleIndex:
          type: integer
          description: _(With bundles only)_ The position of the specific bundle in the list of bundles created from the same bundle definition.
        bundleName:
          type: string
          description: _(With bundles only)_ The name of the bundle definition.
        awaitsActivation:
          type: boolean
          description: Indicates whether the points have an action-based start date. This property is returned only for point transactions with an action-based start date.
        validityDuration:
          type: string
          description: The duration for which the points remain active, calculated relative to their start date.
    RollbackAddedLoyaltyPointsEffectProps:
      type: object
      title: rollbackAddedLoyaltyPoints
      description: |-
        This effect is triggered in the following cases:

        - A session was cancelled in which loyalty points have been added.
        - A session was partially returned and loyalty point were added by the returned items. See [returning items](https://docs.talon.one/docs/dev/tutorials/partially-return-a-session).

        If you use the [Add loyalty points per item effect](https://docs.talon.one/docs/product/rules/effects/available-effects#reward-effects), use the `cartItemPosition` property to identify which items the loyalty points were rolled back for.

        If you use **Add loyalty points per item** and if the session contains some cart items with _quantity > 1_, use the `cartItemSubPosition` property to identify the item unit in its line item.

        If the loyalty program is [profile-based](https://docs.talon.one/docs/product/loyalty-programs/overview#loyalty-program-types), use the `recipientIntegrationId` property to identify the user for whom the loyalty points are rolled back. If the loyalty program is [card-based](https://docs.talon.one/docs/product/loyalty-programs/overview#loyalty-program-types), use the `cardIdentifier` property to identify the loyalty card where the points were originally added.
      example:
        programId: 5
        subLedgerId: main
        value: 100
        recipientIntegrationId: URNGV8294NV
        transactionUUID: 8c2d3670-6ea5-4e9e-b5c6-e7e7b4a10111
        cartItemPosition: 1
        cartItemSubPosition: 1
        cardIdentifier: loyalty-card-001
      required:
        - programId
        - subLedgerId
        - value
        - recipientIntegrationId
        - transactionUUID
      properties:
        programId:
          type: integer
          description: The ID of the loyalty program where these points were rolled back.
        subLedgerId:
          type: string
          description: The ID of the subledger within the loyalty program where these points were rolled back.
        value:
          type: number
          description: The amount of points that were rolled back.
        recipientIntegrationId:
          type: string
          maxLength: 1000
          description: The user for whom these points were rolled back.
          example: URNGV8294NV
        transactionUUID:
          type: string
          description: The identifier of this loyalty point transaction.
        cartItemPosition:
          type: number
          description: (_Add points per cart item_ only.) The index of the item in the `cartItem` object for which these points were rolled back.
        cartItemSubPosition:
          type: number
          description: (_Add points per cart item_ ) The index of the item unit in its line item.
        cardIdentifier:
          $ref: '#/components/schemas/LoyaltyCardIdentifier'
          description: The identifier of the card on which these points were originally added.
    EffectRollbackAddedLoyaltyPoints:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: rollbackAddedLoyaltyPoints
          description: The `rollbackAddedLoyaltyPoints` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - rollbackAddedLoyaltyPoints
              description: An effect discriminator of type `rollbackAddedLoyaltyPoints`.
            props:
              $ref: '#/components/schemas/RollbackAddedLoyaltyPointsEffectProps'
    EffectAddLoyaltyPoints:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: addLoyaltyPoints
          x-rollback-effect:
            $ref: '#/components/schemas/EffectRollbackAddedLoyaltyPoints'
          description: The `addLoyaltyPoints` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - addLoyaltyPoints
              description: An effect discriminator of type `addLoyaltyPoints`.
            props:
              $ref: '#/components/schemas/AddLoyaltyPointsEffectProps'
    EffectAddNegativeLoyaltyPoints:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: addNegativeLoyaltyPoints
          description: The `addNegativeLoyaltyPoints` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - addNegativeLoyaltyPoints
              description: An effect discriminator of type `addNegativeLoyaltyPoints`.
    AddToAudienceEffectProps:
      type: object
      title: addToAudience
      description: This effect is triggered when a rule containing an [Update audience](https://docs.talon.one/docs/product/rules/effects/use-effects#update-an-audience) effect with **Add customer to an audience** selected is validated. It indicates that a customer was added to an audience and is returned when a customer session is opened, updated, or closed.
      example:
        audienceId: 10
        audienceName: My audience
        profileIntegrationId: URNGV8294NV
        profileId: 150
      properties:
        audienceId:
          type: integer
          description: The internal ID of the audience.
          example: 10
        audienceName:
          type: string
          description: The name of the audience.
          example: My audience
        profileIntegrationId:
          type: string
          description: The ID of the customer profile in the third-party integration platform.
          example: URNGV8294NV
        profileId:
          type: integer
          description: The internal ID of the customer profile.
          example: 150
    EffectAddToAudience:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: addToAudience
          description: The `addToAudience` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - addToAudience
              description: An effect discriminator of type `addToAudience`.
            props:
              $ref: '#/components/schemas/AddToAudienceEffectProps'
    AwardGiveawayEffectProps:
      type: object
      title: awardGiveaway
      description: This effect indicates the awarded giveaway item and to which profile the item was awarded. Learn more about [giveaways](https://docs.talon.one/docs/product/giveaways/overview).
      example:
        poolId: 2
        poolName: My pool
        recipientIntegrationId: URNGV8294NV
        giveawayId: 5
        code: 57638t-67439hty
      required:
        - poolId
        - poolName
        - recipientIntegrationId
        - giveawayId
        - code
      properties:
        poolId:
          type: integer
          description: The internal ID of the giveaway pool.
          example: 2
        poolName:
          type: string
          description: The name of the giveaway pool.
          example: My pool
        recipientIntegrationId:
          type: string
          maxLength: 1000
          description: The integration ID of the customer that receives the giveaway.
          example: URNGV8294NV
        giveawayId:
          type: integer
          description: The internal ID of the giveaway.
          example: 5
        code:
          type: string
          description: The giveaway code to be rewarded.
          example: 57638t-67439hty
    EffectAwardGiveaway:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: awardGiveaway
          description: The `awardGiveaway` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - awardGiveaway
              description: An effect discriminator of type `awardGiveaway`.
            props:
              $ref: '#/components/schemas/AwardGiveawayEffectProps'
    BoostLoyaltyTierEffectProps:
      type: object
      title: boostLoyaltyTier
      description: This effect indicates that the customer was temporarily placed in a higher loyalty tier for a specified period, without any change to their points balance.
      example:
        programId: 5
        subLedgerId: main
        tierName: Gold
        reason: Summer promotion
        expiryDate: '2025-01-01T00:00:00Z'
        boostUuid: 27b16dbb-fbc7-4c02-99b1-b21b8a94c186
      required:
        - programId
        - subLedgerId
        - tierName
        - expiryDate
        - boostUuid
      properties:
        programId:
          type: integer
          description: The ID of the loyalty program.
        subLedgerId:
          type: string
          description: The ID of the subledger within the loyalty program.
        tierName:
          type: string
          description: The name of the tier to which the customer is temporarily boosted.
        reason:
          type: string
          description: A reason for the tier boost.
        expiryDate:
          type: string
          format: date-time
          description: The date when the tier boost expires.
        boostUuid:
          type: string
          format: uuid
          description: The unique identifier of the tier boost. Used to match the boost to its rollback effect when a session is cancelled.
          example: 27b16dbb-fbc7-4c02-99b1-b21b8a94c186
    RollbackTierBoostEffectProps:
      type: object
      title: rollbackTierBoost
      description: |-
        This effect indicates that a loyalty tier boost was rolled back.

        The Rule Engine triggers this effect when you cancel a customer session
        that previously triggered the
        [boostLoyaltyTier](https://docs.talon.one/docs/dev/integration-api/api-effects#boostloyaltytier)
        API effect. The tier boost is voided and the customer returns to the tier
        determined by their points balance.

        This effect only applies to full session cancellations. Partially returned
        sessions do not trigger a tier boost rollback.
      example:
        programId: 10
        subLedgerId: ''
        tierName: Gold
        boostUuid: 27b16dbb-fbc7-4c02-99b1-b21b8a94c186
      required:
        - programId
        - subLedgerId
        - tierName
        - boostUuid
      properties:
        programId:
          type: integer
          description: The ID of the loyalty program.
          example: 10
        subLedgerId:
          type: string
          description: The ID of the subledger within the loyalty program.
          example: ''
        tierName:
          type: string
          description: The name of the boosted tier that was rolled back.
          example: Gold
        boostUuid:
          type: string
          format: uuid
          description: The unique identifier of the tier boost that was rolled back. Matches the `boostUuid` of the original `boostLoyaltyTier` effect.
          example: 27b16dbb-fbc7-4c02-99b1-b21b8a94c186
    EffectRollbackTierBoost:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: rollbackTierBoost
          description: The `rollbackTierBoost` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - rollbackTierBoost
              description: An effect of type `rollbackTierBoost`.
            props:
              $ref: '#/components/schemas/RollbackTierBoostEffectProps'
    EffectBoostLoyaltyTier:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: boostLoyaltyTier
          x-rollback-effect:
            $ref: '#/components/schemas/EffectRollbackTierBoost'
          description: The `boostLoyaltyTier` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - boostLoyaltyTier
              description: An effect discriminator of type `boostLoyaltyTier`.
            props:
              $ref: '#/components/schemas/BoostLoyaltyTierEffectProps'
    TriggerWebhookEffectProps:
      type: object
      title: triggerWebhook
      description: This effect is triggered when a rule containing a [webhook effect](https://docs.talon.one/docs/product/rules/effects/available-effects#webhooks) is validated. The details are shared with you for your information only. It usually doesn't require an action on your side.
      example:
        webhookId: 7
        webhookName: My Webhook
      required:
        - webhookId
        - webhookName
      properties:
        webhookId:
          type: number
          description: The internal ID of the webhook.
        webhookName:
          type: string
          description: The name of the webhook.
    EffectCallApi:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: callApi
          description: The `callApi` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - callApi
              description: An effect discriminator of type `callApi`.
            props:
              $ref: '#/components/schemas/TriggerWebhookEffectProps'
    ChangeLoyaltyTierLevelEffectProps:
      type: object
      title: changeLoyaltyTierLevel
      description: |-
        This effect indicates that a customer's loyalty tier has been upgraded.

        This effect is generated only when the [Add loyalty points](https://docs.talon.one/docs/product/rules/effects/use-effects#add-loyalty-points) and the [Add loyalty points per cart item](https://docs.talon.one/docs/product/rules/effects/use-effects#add-loyalty-points-per-cart-item) effects are triggered for a particular customer, and, as a result, the customer's loyalty tier is upgraded.
      example:
        ruleTitle: Tier upgrade on purchase
        programId: 5
        subLedgerId: main
        previousTierName: Silver
        newTierName: Gold
        expiryDate: '2025-12-31T23:59:59Z'
      required:
        - ruleTitle
        - programId
        - subLedgerId
        - newTierName
      properties:
        ruleTitle:
          type: string
          description: The title of the rule that triggered the tier upgrade.
        programId:
          type: integer
          description: The ID of the loyalty program where the points were added.
        subLedgerId:
          type: string
          description: The ID of the subledger within the loyalty program where the points were added.
        previousTierName:
          type: string
          description: The name of the tier from which the user was upgraded.
        newTierName:
          type: string
          description: The name of the tier to which the user has been upgraded.
        expiryDate:
          type: string
          format: date-time
          description: The expiration date of the new tier.
    EffectChangeLoyaltyTierLevel:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: changeLoyaltyTierLevel
          description: The `changeLoyaltyTierLevel` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - changeLoyaltyTierLevel
              description: An effect discriminator of type `changeLoyaltyTierLevel`.
            props:
              $ref: '#/components/schemas/ChangeLoyaltyTierLevelEffectProps'
    CouponCreatedEffectProps:
      type: object
      title: couponCreated
      description: |-
        This effect indicates that a coupon was created.

        For referrals and retention marketing, a common use case is to generate a coupon that can only be redeemed by one specific customer.

        Handle this effect by notifying the recipient about their new coupon code.
      example:
        value: COUP-NEW123
        profileId: customer_profile_id_1
      required:
        - value
        - profileId
      properties:
        value:
          type: string
          description: The coupon code that was created.
        profileId:
          type: string
          description: The integration identifier of the customer for whom this coupon was created.
    EffectCouponCreated:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: couponCreated
          description: The `couponCreated` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - couponCreated
              description: An effect discriminator of type `couponCreated`.
            props:
              $ref: '#/components/schemas/CouponCreatedEffectProps'
    CustomEffectProps:
      type: object
      title: customEffect
      description: |-
        If you want to return data as an effect but no effect matches your use case, you can [create a custom effect](https://docs.talon.one/docs/dev/tutorials/create-custom-effects).

        Custom effects can be used as both rule effects and failure effects.

        The structure of a custom effect depends on your specifications but is always named `customEffect`.
      example:
        effectId: 1
        name: my_custom_effect
        cartItemPosition: 1
        cartItemSubPosition: 2
        bundleIndex: 1
        bundleName: my_bundle
        payload:
          key: value
      required:
        - effectId
        - name
        - payload
      properties:
        effectId:
          type: integer
          description: The ID of the custom effect that was triggered.
          example: 1
        name:
          type: string
          description: The type of the custom effect.
          example: my_custom_effect
        cartItemPosition:
          type: number
          description: The index of the item in the cart item list to which the custom effect is applied.
          example: 1
        cartItemSubPosition:
          type: number
          description: |
            For cart items with quantity > 1, the sub position indicates to which item unit the custom effect is applied.
          example: 2
        bundleIndex:
          type: integer
          description: The position of the bundle in a list of item bundles created from the same bundle definition.
          example: 1
        bundleName:
          type: string
          description: The name of the bundle definition.
          example: my_bundle
        payload:
          description: The JSON payload of the custom effect.
          type: object
          x-arbitraryJSON: true
    EffectCustomEffect:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: customEffect
          description: The `customEffect` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - customEffect
              description: An effect discriminator of type `customEffect`.
            props:
              $ref: '#/components/schemas/CustomEffectProps'
    DeductLoyaltyPointsEffectProps:
      type: object
      title: deductLoyaltyPoints
      description: |-
        This effect is triggered when a customer redeems loyalty points. The points are deducted from their active point balance.

        If the loyalty program is card-based, use the `cardIdentifier` property to identify the loyalty card from which these points are deducted.

        The Rule Engine deducts points in this order:

        - Points with the earliest expiry date are deducted first, regardless of when they were added.
        - Points with an unlimited expiry date are deducted last.
        - For points with an unlimited expiry date, the points awarded first are deducted first.

        The points only persist when the session is closed.
      example:
        ruleTitle: Deduct points on return
        programId: 5
        subLedgerId: main
        value: 50
        transactionUUID: 9f3e4781-7fb6-5f0f-c6d7-f8f8c5b21222
        name: Points deducted for return
        cardIdentifier: loyalty-card-001
      required:
        - ruleTitle
        - programId
        - subLedgerId
        - value
        - transactionUUID
        - name
      properties:
        ruleTitle:
          type: string
          description: The title of the rule that contained triggered this points deduction.
        programId:
          type: integer
          description: The ID of the loyalty program from which these points were deducted.
        subLedgerId:
          type: string
          description: The ID of the subledger within the loyalty program from which these points were deducted.
        value:
          type: number
          description: The amount of points that were deducted.
        transactionUUID:
          type: string
          description: The identifier of this loyalty point transaction.
        name:
          type: string
          description: The reason of this loyalty points deduction.
        cardIdentifier:
          $ref: '#/components/schemas/LoyaltyCardIdentifier'
          description: The identifier of the card from which these points were deducted.
    RollbackDeductedLoyaltyPointsEffectProps:
      type: object
      title: rollbackDeductedLoyaltyPoints
      description: |-
        This effect is triggered in the following cases:

        - A session is _cancelled_ and this session deducted loyalty points. The rollback action returns the redeemed loyalty points to the customer.
        - A session is impacted by a _partial return_. Only added loyalty points that are still **pending** are rolled back.
        - A session in which loyalty points were spent is reopened.

        See the [session states](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions#customer-session-states).

        If you set custom activation and expiration dates for the loyalty points, use the `startDate` and `expiryDate` properties to identify when the reward will be active and when will expire.

        If the loyalty program is [profile-based](https://docs.talon.one/docs/product/loyalty-programs/profile-based/profile-based-overview), use the `recipientIntegrationId` property to identify the user who receives the loyalty points. If the loyalty program is [card-based](https://docs.talon.one/docs/product/loyalty-programs/overview#loyalty-program-types), use the `cardIdentifier` property to identify the loyalty card where the points are reimbursed.
      example:
        programId: 5
        subLedgerId: main
        value: 50
        recipientIntegrationId: URNGV8294NV
        startDate: '2024-01-01T00:00:00Z'
        expiryDate: '2025-01-01T00:00:00Z'
        transactionUUID: 9f3e4781-7fb6-5f0f-c6d7-f8f8c5b21222
        cardIdentifier: loyalty-card-001
      required:
        - programId
        - subLedgerId
        - value
        - recipientIntegrationId
        - transactionUUID
      properties:
        programId:
          type: integer
          description: The ID of the loyalty program where these points were reimbursed.
        subLedgerId:
          type: string
          description: The ID of the subledger within the loyalty program where these points were reimbursed.
        value:
          type: number
          description: The amount of points that were reimbursed.
        recipientIntegrationId:
          type: string
          maxLength: 1000
          description: The user for whom these points were reimbursed.
          example: URNGV8294NV
        startDate:
          type: string
          format: date-time
          description: The date after which the reimbursed points will be valid.
        expiryDate:
          type: string
          format: date-time
          description: The date after which the reimbursed points will expire.
        transactionUUID:
          type: string
          description: The identifier of this loyalty point transaction.
        cardIdentifier:
          $ref: '#/components/schemas/LoyaltyCardIdentifier'
          description: The identifier of the card from which these points were originally deducted.
    EffectRollbackDeductedLoyaltyPoints:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: rollbackDeductedLoyaltyPoints
          description: The `rollbackDeductedLoyaltyPoints` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - rollbackDeductedLoyaltyPoints
              description: An effect discriminator of type `rollbackDeductedLoyaltyPoints`.
            props:
              $ref: '#/components/schemas/RollbackDeductedLoyaltyPointsEffectProps'
    EffectDeductLoyaltyPoints:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: deductLoyaltyPoints
          x-rollback-effect:
            $ref: '#/components/schemas/EffectRollbackDeductedLoyaltyPoints'
          description: The `deductLoyaltyPoints` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - deductLoyaltyPoints
              description: An effect discriminator of type `deductLoyaltyPoints`.
            props:
              $ref: '#/components/schemas/DeductLoyaltyPointsEffectProps'
    ErrorEffectProps:
      type: object
      title: error
      description: This effect is triggered whenever an error occurs during rule evaluation. This effect only provides information about what the error is.
      example:
        message: An unexpected error occurred during rule evaluation.
      required:
        - message
      properties:
        message:
          type: string
          description: The error message.
    EffectError:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: error
          description: The `error` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - error
              description: An effect discriminator of type `error`.
            props:
              $ref: '#/components/schemas/ErrorEffectProps'
    LoyaltyLedgerEntryExpiryDateChange:
      type: object
      description: The properties specific to effects for changing the expiry dates of loyalty ledger entries.
      required:
        - transactionUUID
        - newExpiryDate
      properties:
        transactionUUID:
          type: string
          format: uuid
          description: The identifier of the transaction affected by the extension or update.
        previousExpiryDate:
          type: string
          format: date-time
          description: Expiry date of the transactions before applying the extension or update.
        newExpiryDate:
          type: string
          format: date-time
          description: Expiry date of the transaction after applying the extension or update.
    ExtendLoyaltyPointsExpiryDateEffectProps:
      type: object
      title: extendLoyaltyPointsExpiryDate
      description: |
        If loyalty points have an expiry date, this effect extends the expiry of all active and pending point transactions by a selected duration.
      example:
        programId: 5
        subLedgerId: main
        extensionDuration: 12h
        affectedTransactions: []
      required:
        - programId
        - subLedgerId
        - extensionDuration
        - previousExpirationDate
      properties:
        programId:
          type: integer
          description: ID of the loyalty program that contains these points.
        subLedgerId:
          type: string
          description: API name of the loyalty program subledger that contains these points.
        extensionDuration:
          type: string
          description: |
            Time frame by which the expiry date extends.

            The time format is either:
            - immediate, or
            - an **integer** followed by a letter indicating the time unit.

            Examples: `immediate`, `30s`, `40m`, `1h`, `5D`, `7W`, `10M`, `15Y`.

            Available units:

            - `s`: seconds
            - `m`: minutes
            - `h`: hours
            - `D`: days
            - `W`: weeks
            - `M`: months
            - `Y`: years

            You can round certain units up or down:
            - `_D` for rounding down days only. Signifies the start of the day.
            - `_U` for rounding up days, weeks, months and years. Signifies the end of the day, week, month or year.
          example: 12h
        affectedTransactions:
          type: array
          description: List of transactions affected by the expiry date update.
          items:
            $ref: '#/components/schemas/LoyaltyLedgerEntryExpiryDateChange'
    EffectExtendLoyaltyPointsExpiryDate:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: extendLoyaltyPointsExpiryDate
          description: The `extendLoyaltyPointsExpiryDate` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - extendLoyaltyPointsExpiryDate
              description: An effect discriminator of type `extendLoyaltyPointsExpiryDate`.
            props:
              $ref: '#/components/schemas/ExtendLoyaltyPointsExpiryDateEffectProps'
    IncreaseAchievementProgressEffectProps:
      type: object
      title: increaseAchievementProgress
      description: |-
        This effect indicates that the customer's progress in an achievement was updated during the current session. It is triggered when a rule using the [Update customer progress](https://docs.talon.one/docs/product/rules/effects/use-effects#update-customer-progress) effect is successfully validated.

        For [on-completion achievements](https://docs.talon.one/docs/product/achievements/overview#recurring-on-completion-achievements), any customer progress exceeding the target automatically starts a new iteration. This generates a new `progressTrackerId` for each iteration, and there can be multiple progress updates for the same achievement from a single validation of this effect.
      example:
        achievementId: 10
        achievementName: FreeCoffee10Orders
        progressTrackerId: 42
        delta: 1
        value: 7
        target: 10
        isJustCompleted: false
      required:
        - achievementId
        - achievementName
        - delta
        - value
        - target
        - isJustCompleted
      properties:
        achievementId:
          type: integer
          description: The internal ID of the achievement.
          example: 10
        achievementName:
          type: string
          description: The name of the achievement.
          example: FreeCoffee10Orders
        progressTrackerId:
          type: integer
          description: |-
            The internal ID of the customer progress tracker.
            For [on-completion achievements](https://docs.talon.one/docs/product/achievements/overview#recurring-on-completion-achievements), this effect generates a unique ID for each iteration.
        delta:
          type: number
          description: The value by which the customer's current progress in the achievement has increased.
        value:
          type: number
          description: The current progress of the customer in the achievement.
        target:
          type: number
          description: The target value to complete the achievement.
        isJustCompleted:
          type: boolean
          description: Indicates if the customer has completed the achievement in the current session.
    RollbackIncreasedAchievementProgressEffectProps:
      type: object
      title: rollbackIncreasedAchievementProgress
      description: |-
        This effect indicates that the customer's progress in an achievement was rolled back.

        The Rule Engine triggers this effect when you cancel or [reopen a customer session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/reopenCustomerSession) that previously validated the [Update customer progress](https://docs.talon.one/docs/product/rules/effects/use-effects#update-customer-progress) effect and triggered the [increaseAchievementProgress](https://docs.talon.one/docs/dev/integration-api/api-effects#increaseachievementprogress) API effect.

        The effect is also triggered for completed achievements if the **Allow progress rollback for completed achievements** setting is enabled. You can enable this through the [Campaign Manager](https://docs.talon.one/docs/product/achievements/manage-achievements) or the [Management API](https://docs.talon.one/management-api#tag/Achievements/operation/createAchievement) by setting the `achievementAllowRollbackAfterCompletion` property to `true`. This setting only applies to one-time and recurring on expiration achievements.
      example:
        achievementId: 10
        achievementName: FreeCoffee10Orders
        progressTrackerId: 42
        decreaseProgressBy: 1
        currentProgress: 6
        target: 10
      required:
        - achievementId
        - achievementName
        - progressTrackerId
        - decreaseProgressBy
        - currentProgress
        - target
      properties:
        achievementId:
          type: integer
          description: The internal ID of the achievement.
          example: 10
        achievementName:
          type: string
          description: The name of the achievement.
          example: FreeCoffee10Orders
        progressTrackerId:
          type: integer
          description: The internal ID of the achievement progress tracker.
        decreaseProgressBy:
          type: number
          description: The value by which the customer's current progress in the achievement has decreased.
        currentProgress:
          type: number
          description: The current progress of the customer in the achievement.
        target:
          type: number
          description: The target value to complete the achievement.
    EffectRollbackIncreasedAchievementProgress:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: rollbackIncreasedAchievementProgress
          description: The `rollbackIncreasedAchievementProgress` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - rollbackIncreasedAchievementProgress
              description: An effect discriminator of type `rollbackIncreasedAchievementProgress`.
            props:
              $ref: '#/components/schemas/RollbackIncreasedAchievementProgressEffectProps'
    EffectIncreaseAchievementProgress:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: increaseAchievementProgress
          x-rollback-effect:
            $ref: '#/components/schemas/EffectRollbackIncreasedAchievementProgress'
          description: The `increaseAchievementProgress` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - increaseAchievementProgress
              description: An effect discriminator of type `increaseAchievementProgress`.
            props:
              $ref: '#/components/schemas/IncreaseAchievementProgressEffectProps'
    IncreaseAchievementProgressPerItemEffectProps:
      type: object
      title: increaseAchievementProgressPerItem
      description: |-
        This effect schema is returned when you use the **Update customer progress per item** effect in a rule.

        It indicates that the customer's progress in an achievement was updated during the current session for a specific cart item.

        If your list of cart items is a [bundle definition](https://docs.talon.one/docs/product/rules/create-and-manage-bundles), use the `bundleIndex` and `bundleName` properties to identify the bundle containing the item whose progress was updated.

        If the cart item has a quantity greater than one, use the `cartItemSubPosition` property to identify the specific unit within the item's line item.

        For [on-completion achievements](https://docs.talon.one/docs/product/achievements/overview#recurring-on-completion-achievements), any customer progress exceeding the target automatically starts a new iteration. This generates a new `progressTrackerId` for each iteration, and there can be multiple progress updates for the same achievement from a single validation of this effect.
      example:
        achievementId: 10
        achievementName: FreeCoffee10Orders
        progressTrackerId: 42
        delta: 1
        value: 7
        target: 10
        isJustCompleted: false
        cartItemPosition: 1
        cartItemSubPosition: 1
        bundleIndex: 1
        bundleName: my_bundle
      required:
        - achievementId
        - achievementName
        - delta
        - value
        - target
        - isJustCompleted
        - cartItemPosition
      properties:
        achievementId:
          type: integer
          description: The internal ID of the achievement.
          example: 10
        achievementName:
          type: string
          description: The name of the achievement.
          example: FreeCoffee10Orders
        progressTrackerId:
          type: integer
          description: |-
            The internal ID of the customer progress tracker.
            For [on-completion achievements](https://docs.talon.one/docs/product/achievements/overview#recurring-on-completion-achievements), this effect generates a unique ID for each iteration.
        delta:
          type: number
          description: The value by which the customer's current progress in the achievement has increased.
        value:
          type: number
          description: The current progress of the customer in the achievement.
        target:
          type: number
          description: The target value to complete the achievement.
        isJustCompleted:
          type: boolean
          description: Indicates if the customer has completed the achievement in the current session.
        cartItemPosition:
          type: number
          description: The index of the item in the `cartItem` object on which the customer's progress in the achievement was updated.
        cartItemSubPosition:
          type: number
          description: For cart items with `quantity` > 1, indicates which specific unit of the item the effect applies to.
        bundleIndex:
          type: integer
          description: _(With bundles only)_ The position of the specific bundle in the list of bundles created from the same bundle definition. For example, if a customer creates two identical bundles, the first has index `0` and the second has index `1`.
        bundleName:
          type: string
          description: _(With bundles only)_ The name of the bundle definition.
    EffectIncreaseAchievementProgressPerItem:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: increaseAchievementProgressPerItem
          description: The `increaseAchievementProgressPerItem` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - increaseAchievementProgressPerItem
              description: An effect discriminator of type `increaseAchievementProgressPerItem`.
            props:
              $ref: '#/components/schemas/IncreaseAchievementProgressPerItemEffectProps'
    JoinLoyaltyProgramEffectProps:
      type: object
      title: joinLoyaltyProgram
      description: |
        This effect indicates that a customer profile was joined to a profile-based loyalty program with the specified join date.

        > [!note] **Note**
        > - This effect requires a customer profile. It does not work for anonymous sessions.
        > - The effect fails if the customer profile has already joined the loyalty program.
      example:
        programId: 5
        joinDate: '2026-01-02T03:04:05Z'
      required:
        - programId
        - joinDate
      properties:
        programId:
          type: integer
          description: The ID of the loyalty program the customer profile is joined to.
          example: 5
        joinDate:
          type: string
          format: date-time
          description: The date and time when the customer profile joined the loyalty program.
          example: '2026-01-02T03:04:05Z'
    EffectJoinLoyaltyProgram:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: joinLoyaltyProgram
          description: The `joinLoyaltyProgram` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - joinLoyaltyProgram
              description: An effect discriminator of type `joinLoyaltyProgram`.
            props:
              $ref: '#/components/schemas/JoinLoyaltyProgramEffectProps'
    EffectOffsetNegativeLoyaltyPoints:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: offsetNegativeLoyaltyPoints
          description: The `offsetNegativeLoyaltyPoints` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - offsetNegativeLoyaltyPoints
              description: An effect discriminator of type `offsetNegativeLoyaltyPoints`.
    RedeemReferralEffectProps:
      type: object
      deprecated: true
      title: redeemReferral
      description: |
        This effect is **deprecated**. It has been replaced by the `acceptReferral` effect.
        This effect indicates that the referral code is valid and has been redeemed.
      example:
        id: 12
        value: REF-ABC123
      required:
        - id
        - value
      properties:
        id:
          type: integer
          description: The id of the referral code that was redeemed.
        value:
          type: string
          description: The referral code that was redeemed.
    EffectRedeemReferral:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: redeemReferral
          x-rollback-effect:
            $ref: '#/components/schemas/EffectRollbackReferral'
          description: The `redeemReferral` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - redeemReferral
              description: An effect discriminator of type `redeemReferral`.
            props:
              $ref: '#/components/schemas/RedeemReferralEffectProps'
    ReferralCreatedEffectProps:
      type: object
      title: referralCreated
      description: The `referralCreated` effect behaves similarly to [couponCreated](https://docs.talon.one/docs/dev/integration-api/api-effects#couponcreated). If the `friendProfileIntegrationId` parameter is empty, the referral code can be redeemed by anyone.
      example:
        value: REF-NEW456
      required:
        - value
      properties:
        value:
          type: string
          description: The referral code provided in the session.
    EffectReferralCreated:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: referralCreated
          description: The `referralCreated` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - referralCreated
              description: An effect discriminator of type `referralCreated`.
            props:
              $ref: '#/components/schemas/ReferralCreatedEffectProps'
    RejectCouponEffectProps:
      type: object
      title: rejectCoupon
      description: |-
        This effect indicates that the coupon code supplied couldn't be used.

        You should handle this effect by informing their user the coupon code is invalid.
      example:
        value: COUP-XYZ789
        rejectionReason: CouponRejectedCondition
        conditionIndex: 2
        effectIndex: 0
        details: Coupon usage limit reached
        campaignExclusionReason: CampaignGaveLowerDiscount
      required:
        - value
        - rejectionReason
      properties:
        value:
          type: string
          description: The coupon code that was rejected.
        rejectionReason:
          type: string
          description: |-
            The reason why the code was rejected.

            - `CampaignLimitReached`: The campaign-wide coupon code redemption limit has been reached.
            - `CouponExpired`: The coupon is expired.
            - `CouponLimitReached`: The coupon redemption limit or a campaign budget was reached.
            - `CouponNotFound`: The coupon code is incorrect.
            - `CouponPartOfNotRunningCampaign`: The campaign the coupon belongs to is currently not active. The campaignId field contains the ID of that campaign.
            - `CouponRecipientDoesNotMatch`: The given coupon value does not match the recipient or the coupon is linked to a `recipientIntegrationID` but there is no profile in the session.
            - `CouponRejectedByCondition`: Other conditions failed in the rule or all conditions passed but the `Coupon code is valid` condition is not present.
            - `CouponStartDateInFuture`: The coupon isn't active yet.
            - `EffectCouldNotBeApplied`: One of the effects in the campaign wasn't applied because a limit for that effect was reached (most common use case will be `setDiscount` cannot be applied because a discount limit is reached).
            - `ProfileLimitReached`: The profile-specific coupon redemption limit has been reached.
            - `CouponPartOfNotTriggeredCampaign`: The campaign the coupon belongs to was not triggered during evaluation (an exclusive or stackable campaign). The `campaignId` field contains the ID of that campaign.
            - `CouponReservationRequired`: The coupon's `isReservationMandatory` property is `true`, but the profile does not have a reservation.
            - `ProfileRequired`: The coupon's `isReservationMandatory` property is `true` or a [campaign profile budget](https://docs.talon.one/docs/product/campaigns/settings/manage-campaign-budgets) was set, but no profile exists in the session.
        conditionIndex:
          type: integer
          description: The index of the condition that caused the rejection of the coupon.
        effectIndex:
          type: integer
          description: The index of the effect that caused the rejection of the coupon.
        details:
          type: string
          description: More details about the failure.
        campaignExclusionReason:
          type: string
          example: CampaignGaveLowerDiscount
          description: |-
            The reason why the campaign the coupon belongs to was excluded during [campaign evaluation](https://docs.talon.one/docs/product/applications/manage-campaign-evaluation), when `rejectionReason` was `CouponPartOfNotTriggeredCampaign`.
            Its possible values are:

            - `CampaignGaveLowerDiscount`: The required campaign and coupon conditions were met, but another campaign in a [Highest discount value](https://docs.talon.one/docs/product/applications/manage-campaign-evaluation#set-campaign-evaluation-mode) group offered a higher discount value.
            - `CampaignIsNotFirst`: The campaign was not evaluated because another campaign in a [First campaign](https://docs.talon.one/docs/product/applications/manage-campaign-evaluation#set-campaign-evaluation-mode) group was picked and evaluated first.
            - `CampaignNotInEvaluationSet`: The campaign did not meet other evaluation requirements, for example, because the coupon is part of an archived campaign.
    EffectRejectCoupon:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: rejectCoupon
          description: The `rejectCoupon` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - rejectCoupon
              description: An effect discriminator of type `rejectCoupon`.
            props:
              $ref: '#/components/schemas/RejectCouponEffectProps'
    RejectReferralEffectProps:
      type: object
      title: rejectReferral
      description: This effect indicates that the provided referral code is invalid.
      example:
        value: REF-ABC123
        rejectionReason: ReferralRejectedCondition
        conditionIndex: 1
        effectIndex: 0
        details: Referral code already used
        campaignExclusionReason: CampaignGaveLowerDiscount
      required:
        - value
        - rejectionReason
      properties:
        value:
          type: string
          description: The referral code that was rejected
        rejectionReason:
          type: string
          description: |-
            The reason why the code was rejected.

            - `AdvocateNotFound`: The advocate was not found.
            - `CampaignLimitReached`: The campaign-wide referral code redemption limit has been reached.
            - `EffectCouldNotBeApplied`: One of the effects in the campaign wasn't applied because a limit for that effect was reached (most common use case will be `setDiscount` can not be applied because a discount limit is reached).
            - `ProfileLimitReached`: The profile-specific referral code redemption limit has been reached.
            - `ReferralCustomerAlreadyReferred`: The friend is already referred.
            - `ReferralExpired`: The transferred referral code is expired.
            - `ReferralLimitReached`: The referral code redemption limit has been reached.
            - `ReferralNotFound`: The transferred referral code is wrong.
            - `ReferralPartOfNotRunningCampaign`: The campaign the referral code belongs to is currently not active. The campaign ID field shows the ID of that campaign.
            - `ReferralRecipientDoesNotMatch`: The given referral code value does not match the recipient.
            - `ReferralRecipientIdSameAsAdvocate`: The recipient (friend) has the same id as the advocate.
            - `ReferralRejectedByCondition`: The referral code is valid and in an active campaign, but there were other conditions in that campaign's rules that were not met.
            - `ReferralStartDateInFuture`: The transferred referral code isn't active yet.
            - `ReferralPartOfNotTriggeredCampaign`: The campaign the referral code belongs to was not triggered during evaluation (an exclusive or stackable campaign). The campaign ID field shows the ID of that campaign.
        conditionIndex:
          type: integer
          description: The index of the condition that caused the rejection of the referral.
        effectIndex:
          type: integer
          description: The index of the effect that caused the rejection of the referral.
        details:
          type: string
          description: More details about the failure.
        campaignExclusionReason:
          type: string
          example: CampaignGaveLowerDiscount
          description: |-
            The reason why the campaign the referral belongs to was excluded during [campaign evaluation](https://docs.talon.one/docs/product/applications/manage-campaign-evaluation), when `rejectionReason` was `CouponPartOfNotTriggeredCampaign`.
            Its possible values are:

            - `CampaignGaveLowerDiscount`: The required campaign and referral conditions were met, but another campaign in a [Highest discount value](https://docs.talon.one/docs/product/applications/manage-campaign-evaluation#set-campaign-evaluation-mode) group offered a higher discount value.
            - `CampaignIsNotFirst`: The campaign was not evaluated because another campaign in a [First campaign](https://docs.talon.one/docs/product/applications/manage-campaign-evaluation#set-campaign-evaluation-mode) group was picked and evaluated first.
            - `CampaignNotInEvaluationSet`: The campaign did not meet other evaluation requirements, for example, because the referral is part of an archived campaign.
    EffectRejectReferral:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: rejectReferral
          description: The `rejectReferral` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - rejectReferral
              description: An effect discriminator of type `rejectReferral`.
            props:
              $ref: '#/components/schemas/RejectReferralEffectProps'
    RemoveFromAudienceEffectProps:
      type: object
      title: removeFromAudience
      description: This effect is triggered when a rule containing an [Update audience](https://docs.talon.one/docs/product/rules/effects/use-effects#update-an-audience) effect with **Remove customer from an audience** selected is validated. It indicates that a customer was removed from an audience and is returned when a customer session is opened, updated, or closed.
      example:
        audienceId: 10
        audienceName: My audience
        profileIntegrationId: URNGV8294NV
        profileId: 150
      properties:
        audienceId:
          type: integer
          description: The internal ID of the audience.
          example: 10
        audienceName:
          type: string
          description: The name of the audience.
          example: My audience
        profileIntegrationId:
          type: string
          description: The ID of the customer profile in the third-party integration platform.
          example: URNGV8294NV
        profileId:
          type: integer
          description: The internal ID of the customer profile.
          example: 150
    EffectRemoveFromAudience:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: removeFromAudience
          description: The `removeFromAudience` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - removeFromAudience
              description: An effect discriminator of type `removeFromAudience`.
            props:
              $ref: '#/components/schemas/RemoveFromAudienceEffectProps'
    ReserveCouponEffectProps:
      type: object
      title: reserveCoupon
      description: |-
        This effect indicates that the given coupon code was reserved for the given customer.

        Talon.One provides soft and hard reservations. For more information, see [Reserve a coupon code](https://docs.talon.one/docs/product/rules/effects/use-effects#reserve-a-coupon-code).
      example:
        couponValue: COUP-XYZ789
        profileIntegrationId: customer_profile_id_1
        isNewReservation: true
      required:
        - couponValue
        - profileIntegrationId
        - isNewReservation
      properties:
        couponValue:
          type: string
          description: The coupon code that was created.
        profileIntegrationId:
          type: string
          description: The integration identifier of the customer for whom this coupon was reserved.
        isNewReservation:
          type: boolean
          description: Indicates whether this is a new coupon reservation or not.
    EffectReserveCoupon:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: reserveCoupon
          description: The `reserveCoupon` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - reserveCoupon
              description: An effect discriminator of type `reserveCoupon`.
            props:
              $ref: '#/components/schemas/ReserveCouponEffectProps'
    RollbackDiscountEffectProps:
      type: object
      title: rollbackDiscount
      description: |-
        This effect indicates that a discounted session, cart item, or additional cost has been cancelled or partially returned. This effect can only happen when you set the status of a session to `cancel` or the status changes to `partially_returned`.

        If the session contains some cart items with _quantity > 1_, use the `cartItemSubPosition` property to identify the specific item unit in its line item. See the example below.
      example:
        name: 10% Off
        value: 2.5
        cartItemPosition: 1
        cartItemSubPosition: 1
        additionalCostId: 1
        additionalCost: shipping
        scope: sessionTotal
      required:
        - name
        - value
      properties:
        name:
          type: string
          description: The name of the discount effect that was rolled back.
        value:
          type: number
          description: The monetary value of the discount that was rolled back.
        cartItemPosition:
          type: number
          description: The index of the item in the `cartItem` object whose discount was rolled back, or the unit containing the additional cost whose discount was rolled back.
        cartItemSubPosition:
          type: number
          description: The index of the item unit in its line item for which the discount was rolled back.
        additionalCostId:
          type: integer
          description: _Only when rolling back [setDiscountPerAdditionalCost](https://docs.talon.one/docs/dev/integration-api/api-effects#setdiscountperadditionalcost) and [setDiscountPerAdditionalCostPerItem](https://docs.talon.one/docs/dev/integration-api/api-effects#setdiscountperadditionalcostperitem)_ The ID of the additional cost to be discounted.
        additionalCost:
          type: string
          description: The API name of the additional cost whose discount was rolled back.
        scope:
          type: string
          description: |-
            The scope of the rolled back discount.

            - For a discount per session, it can be one of `cartItems`, `additionalCosts` or `sessionTotal`
            - For a discount per item, it can be one of `price`, `additionalCosts` or `itemTotal`
    EffectRollbackDiscount:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: rollbackDiscount
          description: The `rollbackDiscount` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - rollbackDiscount
              description: An effect discriminator of type `rollbackDiscount`.
            props:
              $ref: '#/components/schemas/RollbackDiscountEffectProps'
    RollbackIncreasedAchievementProgressPerItemEffectProps:
      type: object
      title: rollbackIncreasedAchievementProgressPerItem
      description: |-
        This effect schema is returned when you cancel or [reopen a customer session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/reopenCustomerSession) that previously validated the **Update customer progress per item** effect.

        It indicates that the customer's progress in an achievement was rolled back for a specific cart item.

        If your list of cart items is a [bundle definition](https://docs.talon.one/docs/product/rules/create-and-manage-bundles), use the `bundleIndex` and `bundleName` properties to identify the bundle containing the item whose progress was rolled back.

        If the session contains cart items with _quantity > 1_, use the `cartItemSubPosition` property to identify the specific unit within the item's line item.

        The effect is also triggered for completed achievements if the **Allow progress rollback for completed achievements** setting is enabled. You can enable this through the [Campaign Manager](https://docs.talon.one/docs/product/achievements/manage-achievements) or the [Management API](https://docs.talon.one/management-api#tag/Achievements/operation/createAchievement) by setting the `achievementAllowRollbackAfterCompletion` property to `true`. This setting only applies to one-time and recurring on expiration achievements.
      example:
        achievementId: 10
        achievementName: FreeCoffee10Orders
        progressTrackerId: 42
        decreaseProgressBy: 1
        currentProgress: 6
        target: 10
        cartItemPosition: 1
        cartItemSubPosition: 1
        bundleIndex: 1
        bundleName: my_bundle
      required:
        - achievementId
        - achievementName
        - progressTrackerId
        - decreaseProgressBy
        - currentProgress
        - target
        - cartItemPosition
      properties:
        achievementId:
          type: integer
          description: The internal ID of the achievement.
          example: 10
        achievementName:
          type: string
          description: The name of the achievement.
          example: FreeCoffee10Orders
        progressTrackerId:
          type: integer
          description: The internal ID of the achievement progress tracker.
        decreaseProgressBy:
          type: number
          description: The value by which the customer's current progress in the achievement has decreased.
        currentProgress:
          type: number
          description: The current progress of the customer in the achievement.
        target:
          type: number
          description: The target value to complete the achievement.
        cartItemPosition:
          type: number
          description: The index of the item in the `cartItem` object on which the customer's progress in the achievement was updated.
        cartItemSubPosition:
          type: number
          description: For cart items with `quantity` > 1, indicates which specific unit of the item the effect applies to.
        bundleIndex:
          type: integer
          description: _(With bundles only)_ The position of the specific bundle in the list of bundles created from the same bundle definition. For example, if a customer creates two identical bundles, the first has index `0` and the second has index `1`.
        bundleName:
          type: string
          description: _(With bundles only)_ The name of the bundle definition.
    EffectRollbackIncreasedAchievementProgressPerItem:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: rollbackIncreasedAchievementProgressPerItem
          description: The `rollbackIncreasedAchievementProgressPerItem` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - rollbackIncreasedAchievementProgressPerItem
              description: An effect discriminator of type `rollbackIncreasedAchievementProgressPerItem`.
            props:
              $ref: '#/components/schemas/RollbackIncreasedAchievementProgressPerItemEffectProps'
    RollbackUseRewardEffectProps:
      type: object
      title: rollbackUseReward
      description: This effect is triggered when a reward usage has been rolled back by a session cancellation.
      example:
        integrationId: 5c0b5e6d-3f8a-4c2b-9f1e-2a7d6b4c8e90
        rewardId: 5
        applicationId: 1
      required:
        - rewardId
        - integrationId
        - applicationId
      properties:
        integrationId:
          type: string
          description: The integration ID of the customer reward that was rolled back.
          example: 5c0b5e6d-3f8a-4c2b-9f1e-2a7d6b4c8e90
        rewardId:
          type: integer
          description: The ID of the reward that was rolled back.
          example: 5
        applicationId:
          type: integer
          description: The ID of the Application the reward belongs to.
          example: 1
    EffectRollbackUseReward:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: rollbackUseReward
          description: The `rollbackUseReward` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - rollbackUseReward
              description: An effect discriminator of type `rollbackUseReward`.
            props:
              $ref: '#/components/schemas/RollbackUseRewardEffectProps'
    UpdateAttributeEffectProps:
      type: object
      title: set
      description: This effect indicates that a rule containing an [Update attribute value](https://docs.talon.one/docs/product/rules/effects/available-effects#update-effects) or [Update cart item attribute value](https://docs.talon.one/docs/product/rules/effects/available-effects#update-effects) was validated. You should update the value of the attribute in your system based on the content of the returned effect.
      example:
        path: Session.Attributes.loyaltyTier
        value: Gold
      required:
        - path
        - value
      properties:
        path:
          type: string
          description: The entity type and the attribute name.
        value:
          description: The new value of the attribute.
    EffectSet:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: set
          description: The `set` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - set
              description: An effect discriminator of type `set`.
            props:
              $ref: '#/components/schemas/UpdateAttributeEffectProps'
    SetDiscountEffectProps:
      type: object
      title: setDiscount
      description: |-
        This effect indicates that a discount should be set on the total shopping cart value of the current order with the given label and amount.

        The discount should overwrite any existing discount with the same name. The most recent integration state update always returns the latest values for **all** effects, effectively overwriting any previous effects.

        Enabling [partial discounts](https://docs.talon.one/docs/product/applications/manage-general-settings#partial-discounts) allows a rule that would fail because of insufficient budget to pass. The rule still fails when the budget reaches `0`. Use the `desiredValue` property to identify the original value of the discount.
      example:
        name: 10% Off
        value: 2.5
        scope: sessionTotal
        desiredValue: 2.5
      required:
        - name
        - value
      properties:
        name:
          type: string
          description: The name or description of this discount.
        value:
          type: number
          description: The monetary value of the effective discount.
        scope:
          type: string
          description: |-
            What the discount applies to. Possible values:

            - `cartItems`: Discount on the price of the items.
            - `additionalCosts`: Discount on the [additional costs](https://docs.talon.one/docs/product/account/dev-tools/manage-additional-costs) of the items.
            - `sessionTotal`: Discount on the total value of the customer session.

            **Note:** [Cascading discounts](https://docs.talon.one/docs/product/applications/manage-general-settings#cascading-discounts) must be enabled for this property to be returned.
        desiredValue:
          type: number
          description: _(Partial discounts enabled only)_ The monetary value of the discount to be applied without considering budget limitations.
    EffectSetDiscount:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: setDiscount
          x-rollback-effect:
            $ref: '#/components/schemas/EffectRollbackDiscount'
          description: The `setDiscount` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - setDiscount
              description: An effect discriminator of type `setDiscount`.
            props:
              $ref: '#/components/schemas/SetDiscountEffectProps'
    SetDiscountPerAdditionalCostEffectProps:
      type: object
      title: setDiscountPerAdditionalCost
      description: |-
        This effect indicates that a discount that should be applied on a specific additional cost. It is triggered whenever a rule containing a **Discount additional cost** effect is validated.

        Enabling [partial rewards](https://docs.talon.one/docs/product/applications/manage-general-settings#partial-rewards) allows a rule that would fail because of insufficient budget to pass. The rule still fails when the budget reaches 0. Use the `desiredValue` property to identify the original amount of loyalty points.
      example:
        name: Shipping discount
        additionalCostId: 1
        additionalCost: shipping
        value: 4.99
        desiredValue: 4.99
      required:
        - name
        - value
        - additionalCostId
        - additionalCost
      properties:
        name:
          type: string
          description: The name of the discount.
        additionalCostId:
          type: integer
          description: The identifier of the additional cost.
        additionalCost:
          type: string
          description: The API name of the additional cost.
        value:
          type: number
          description: The monetary value of the discount to apply.
        desiredValue:
          type: number
          description: _(Partial discounts enabled only)_ The monetary value of the discount to be applied without considering budget limitations.
    EffectSetDiscountPerAdditionalCost:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: setDiscountPerAdditionalCost
          x-rollback-effect:
            $ref: '#/components/schemas/EffectRollbackDiscount'
          description: The `setDiscountPerAdditionalCost` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - setDiscountPerAdditionalCost
              description: An effect discriminator of type `setDiscountPerAdditionalCost`.
            props:
              $ref: '#/components/schemas/SetDiscountPerAdditionalCostEffectProps'
    SetDiscountPerAdditionalCostPerItemEffectProps:
      type: object
      title: setDiscountPerAdditionalCostPerItem
      description: |-
        This effect indicates that a discount of a specific additional cost within a specific item should be applied. It gets triggered whenever a rule containing a **Discount additional cost per item** effect is validated.

        Use this effect when **all** items in the cart have an additional cost. If one of more items do not have an additional cost, the rule will fail.
      example:
        name: 'Shipping discount on item #1'
        additionalCostId: 1
        value: 4.99
        position: 1
        subPosition: 1
        additionalCost: shipping
        desiredValue: 4.99
      required:
        - name
        - value
        - additionalCostId
        - additionalCost
        - position
      properties:
        name:
          type: string
          description: The description of this discount. `#number` is appended to the name. It is equal to the `position` property.
        additionalCostId:
          type: integer
          description: The identifier of the additional cost to be discounted.
        value:
          type: number
          description: The monetary value of the effective discount applied to the item's additional cost.
        position:
          type: number
          description: The index of the item in the `cartItem` object containing the additional cost that this discount applies to.
        subPosition:
          type: number
          description: The index of the item unit in its line item.
        additionalCost:
          type: string
          description: The API name of the additional cost to be discounted.
        desiredValue:
          type: number
          description: _[(Partial discounts enabled only)](https://docs.talon.one/docs/product/applications/manage-general-settings#partial-discounts)_. The monetary value of the discount to be applied to the additional cost without considering budget limitations.
    EffectSetDiscountPerAdditionalCostPerItem:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: setDiscountPerAdditionalCostPerItem
          x-rollback-effect:
            $ref: '#/components/schemas/EffectRollbackDiscount'
          description: The `setDiscountPerAdditionalCostPerItem` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - setDiscountPerAdditionalCostPerItem
              description: An effect discriminator of type `setDiscountPerAdditionalCostPerItem`.
            props:
              $ref: '#/components/schemas/SetDiscountPerAdditionalCostPerItemEffectProps'
    SetDiscountPerItemEffectProps:
      type: object
      title: setDiscountPerItem
      description: |-
        This effect schema is returned when you use the **Discount individual items**, **Discount individual items pro rata**, or **Discount individual item in bundles** effect in a rule.

        It indicates that a discount per item should be applied on the specific item specified in the effect.

        The properties it contains depends on:

        - Whether you used a pro rata effect or not.
        - Whether you used an effect with bundles or not.
        - Whether the partial discount feature is enabled.
      example:
        name: 'Discount on item #1'
        value: 1.5
        position: 1
        subPosition: 1
        desiredValue: 1.5
        scope: price
        totalDiscount: 1.5
        desiredTotalDiscount: 1.5
        bundleIndex: 1
        bundleName: my_bundle
        targetedItemPosition: 1
        targetedItemSubPosition: 1
        excludedFromPriceHistory: false
      required:
        - name
        - value
        - position
      properties:
        name:
          type: string
          description: The description of this discount. `#number` is equal to the `position` property.
        value:
          type: number
          description: The monetary value of the effective discount applied to the item.
        position:
          type: number
          description: The index of the item in the `cartItem` object on which this discount should be applied.
        subPosition:
          type: number
          description: The index of the item unit in its line item.
        desiredValue:
          type: number
          description: _(Partial discounts enabled only)_ The monetary value of the discount to be applied to the item without considering budget limitations.
        scope:
          type: string
          description: |-
            What the discount applies to. Possible values:

            - `price`: discount on the price of the item.
            - `additionalCosts`: discount on the [additional cost](https://docs.talon.one/docs/product/account/dev-tools/manage-additional-costs) of the item.
            - `itemTotal`: discount on the sum of price + additional cost of the item.
        totalDiscount:
          type: number
          description: _(Pro rata discounts only)_ The monetary value of the total effective discount
        desiredTotalDiscount:
          type: number
          description: _(Pro rata discounts only)_ The monetary value of the total discount to be applied without considering budget limitations
        bundleIndex:
          type: integer
          description: _(Discounts with bundles only)_ The position of the specific item bundle in the list of bundles created from the same bundle definition.
        bundleName:
          type: string
          description: _(Discounts with bundles only)_ The name of the bundle definition.
        targetedItemPosition:
          type: number
          description: _(Discounting individual item in bundles only)_ The index of the targeted bundle item on which the applied discount is based.
        targetedItemSubPosition:
          type: number
          description: _(Discounting individual item in bundles only)_ The sub-position of the targeted bundle item on which the applied discount is based.
        excludedFromPriceHistory:
          type: boolean
          description: When set to `true`, the applied discount is excluded from the item's price history.
    EffectSetDiscountPerItem:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: setDiscountPerItem
          x-rollback-effect:
            $ref: '#/components/schemas/EffectRollbackDiscount'
          description: The `setDiscountPerItem` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - setDiscountPerItem
              description: An effect discriminator of type `setDiscountPerItem`.
            props:
              $ref: '#/components/schemas/SetDiscountPerItemEffectProps'
    SetLoyaltyPointsExpiryDateEffectProps:
      type: object
      title: setLoyaltyPointsExpiryDate
      description: |
        This effect updates the expiry date of all active, pending, and unlimited point transactions to a specific date.
      example:
        programId: 5
        subLedgerId: main
        newExpiryDate: '2024-07-24T14:15:22Z'
        affectedTransactions: []
      required:
        - programId
        - subLedgerId
        - newExpiryDate
      properties:
        programId:
          type: integer
          description: ID of the loyalty program that contains these points.
        subLedgerId:
          type: string
          description: API name of the loyalty program subledger that contains these points.
        newExpiryDate:
          type: string
          format: date-time
          description: The specified expiry date and time for all active and pending point transactions in the loyalty program subledger.
          example: '2024-07-24T14:15:22Z'
        affectedTransactions:
          type: array
          description: List of transactions affected by the expiry date update.
          items:
            $ref: '#/components/schemas/LoyaltyLedgerEntryExpiryDateChange'
    EffectSetLoyaltyPointsExpiryDate:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: setLoyaltyPointsExpiryDate
          description: The `setLoyaltyPointsExpiryDate` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - setLoyaltyPointsExpiryDate
              description: An effect discriminator of type `setLoyaltyPointsExpiryDate`.
            props:
              $ref: '#/components/schemas/SetLoyaltyPointsExpiryDateEffectProps'
    ShowBundleMetadataEffectProps:
      type: object
      deprecated: true
      title: showBundleMetadata
      description: |-
        This effect is **deprecated**.

        The `ShowBundleMetadata` effect contains information that allows you to associate
        the discounts from a rule in a bundle campaign with specific cart items.
        This way you can distinguish from "normal" discounts that were not the result of a product bundle.
      example:
        description: Buy 2 get 1 free bundle
        bundleAttributes:
          - category
          - brand
        itemsIndices:
          - 0
          - 1
          - 2
      required:
        - description
        - bundleAttributes
        - itemsIndices
      properties:
        description:
          type: string
          description: Description of the product bundle.
        bundleAttributes:
          type: array
          items:
            type: string
          description: The cart item attributes that determined which items are being bundled together.
        itemsIndices:
          type: array
          items:
            type: number
          description: The indices in the cart items array of the bundled items.
    EffectShowBundleMetadata:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: showBundleMetadata
          description: The `showBundleMetadata` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - showBundleMetadata
              description: An effect discriminator of type `showBundleMetadata`.
            props:
              $ref: '#/components/schemas/ShowBundleMetadataEffectProps'
    ShowNotificationEffectProps:
      type: object
      title: showNotification
      description: |-
        You can use notifications to inform customers of certain events. There are four types of notification messages:

        - `Info`
        - `Offer`
        - `Error`
        - `Misc`

        It is up to you to use the Rule Builder to decide why and when to show notifications. Notifications can be used as both rule effects and failure effects.

        A common use case is to display the notification at the top of the cart view in your web app. You can use the notification type to vary the styling of the notification message.
      example:
        notificationType: info
        title: Discount applied
        body: You have received a 10% discount on your order.
      required:
        - notificationType
        - title
        - body
      properties:
        notificationType:
          type: string
          description: The type of notification.
        title:
          type: string
          description: The title of the notification.
        body:
          type: string
          description: The body of the notification.
    EffectShowNotification:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: showNotification
          description: The `showNotification` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - showNotification
              description: An effect discriminator of type `showNotification`.
            props:
              $ref: '#/components/schemas/ShowNotificationEffectProps'
    StartAchievementProgressEffectProps:
      type: object
      title: startAchievementProgress
      description: |
        This effect indicates that the customer's progress in an achievement was started during 
        the current session. The Rule Engine creates a progress tracker for the customer, 
        identified by `progressTrackerId`. 

        This effect only starts the customer's progress and does not increase the
        progress. When this effect is returned, the customer progress status is
        `inprogress` and the progress value is `0`.

        You can retrieve the customer's current progress at any time, whether or not
        this effect was returned, in the following ways:
        - Include `achievements` in the `responseContent` property of your request,
          on any endpoint where this property is available, for example
          [Update customer session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2).
        - Use the [List customer's available achievements](https://docs.talon.one/integration-api#tag/Achievements/operation/getCustomerAchievements) endpoint.
        - Use the [List customer's achievement history](https://docs.talon.one/integration-api#tag/Achievements/operation/getCustomerAchievementHistory) endpoint.

        For recurring achievements, this effect is only returned for the first iteration
        and has no effect on the iterations that follow. For 
        [recurring user-action achievements](https://docs.talon.one/docs/product/achievements/overview#recurring-user-action-achievements)
        specifically, this effect also begins the customer's progress period, specified 
        by the `startDate` and `endDate` properties.

        This effect is triggered in the following cases:

        - A rule containing a [Start customer
          progress](https://docs.talon.one/docs/product/rules/effects/use-effects#start-customer-progress)
          effect is validated.
        - A rule containing an [Update customer
          progress](https://docs.talon.one/docs/product/rules/effects/use-effects#update-customer-progress)
          effect is validated for an achievement that the customer has not started
          yet. In this case, the Rule Engine returns the `startAchievementProgress`
          effect first, followed by
          [increaseAchievementProgress](https://docs.talon.one/docs/dev/integration-api/api-effects#increaseachievementprogress),
          which carries the increased customer progress. Use `progressTrackerId` to
          connect the results produced by the two effects.

        **Note:**
        - This effect is not returned if the customer's progress in the achievement has 
          already started, or if the achievement's end date has passed. In these cases, 
          the **Start customer progress** effect fails, an 
          [error](https://docs.talon.one/docs/dev/integration-api/api-effects#error) effect
          is returned, and the customer's progress remains unchanged. Any other effects 
          in the same rule are also not applied.
        - If a rule with this effect fails, include `ruleFailureReasons` in the 
          `responseContent` property of your request to see the reason for failure. 
          The customer's progress is unchanged, so no update is required. The failure 
          reason identifies the campaign, ruleset, and rule that failed, and `details` 
          explains why.
        - There is no rollback effect for the `startAchievementProgress` effect.
      example:
        achievementId: 10
        achievementName: FreeCoffee10Orders
        progressTrackerId: 42
        target: 10
        startDate: '2026-04-16T15:25:37Z'
        endDate: '2026-04-30T11:24:59Z'
      required:
        - achievementId
        - achievementName
        - target
        - startDate
      properties:
        achievementId:
          type: integer
          description: The ID of the achievement.
          example: 10
        achievementName:
          type: string
          description: The name of the achievement.
          example: FreeCoffee10Orders
        progressTrackerId:
          type: integer
          description: |-
            The ID of the customer's progress tracker for this achievement.

            For [on-completion achievements](https://docs.talon.one/docs/product/achievements/overview#recurring-on-completion-achievements), this effect generates a unique ID for each iteration.
          example: 42
        target:
          type: number
          description: The target value to complete the achievement.
          example: 10
        startDate:
          type: string
          format: date-time
          description: Timestamp at which the customer's progress started.
          example: '2026-04-16T15:25:37Z'
        endDate:
          type: string
          format: date-time
          description: |-
            Timestamp at which this progress period ends.

            Only returned for achievements that have a fixed end date. [On-completion achievements](https://docs.talon.one/docs/product/achievements/overview#recurring-on-completion-achievements) have no end date.
          example: '2026-04-30T11:24:59Z'
    EffectStartAchievementProgress:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: startAchievementProgress
          description: The `startAchievementProgress` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - startAchievementProgress
              description: An effect discriminator of type `startAchievementProgress`.
            props:
              $ref: '#/components/schemas/StartAchievementProgressEffectProps'
    UnlockRewardEffectProps:
      type: object
      title: unlockReward
      description: The properties specific to the "unlockReward" effect. This gets triggered whenever a validated rule unlocks a reward for a customer profile.
      example:
        integrationId: reward-unlock-123
        rewardId: 5
        applicationId: 1
        profileIntegrationId: customer1
        unlockedAt: '2024-05-29T15:04:05Z'
        loyaltyCardId: summer-loyalty-card-0543
      required:
        - rewardId
        - integrationId
        - applicationId
        - profileIntegrationId
        - unlockedAt
      properties:
        integrationId:
          type: string
          description: The integration ID assigned to the customer reward unlock.
          example: reward-unlock-123
        rewardId:
          type: integer
          description: The internal ID of the reward that was unlocked.
          example: 5
        applicationId:
          type: integer
          description: The internal ID of the application the reward belongs to.
          example: 1
        profileIntegrationId:
          type: string
          description: The integration ID of the customer profile that unlocked the reward.
          example: customer1
        unlockedAt:
          type: string
          format: date-time
          description: The time the reward was unlocked.
          example: '2024-05-29T15:04:05Z'
        loyaltyCardId:
          $ref: '#/components/schemas/LoyaltyCardIdentifier'
          description: |
            The identifier of the loyalty card that unlocked the reward. Only
            returned when the reward was unlocked with a loyalty card, in which case
            the reward belongs to the card and is available to all customer
            profiles linked to it.
    EffectUnlockReward:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: unlockReward
          description: The `unlockReward` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - unlockReward
              description: An effect discriminator of type `unlockReward`.
            props:
              $ref: '#/components/schemas/UnlockRewardEffectProps'
    UseRewardEffectProps:
      type: object
      title: useReward
      description: This effect is triggered when a rule that uses a customer's unlocked reward is validated during session evaluation.
      example:
        integrationId: 5c0b5e6d-3f8a-4c2b-9f1e-2a7d6b4c8e90
        rewardId: 5
        applicationId: 1
      required:
        - rewardId
        - integrationId
        - applicationId
      properties:
        integrationId:
          type: string
          description: The integration ID of the customer reward that was used.
          example: 5c0b5e6d-3f8a-4c2b-9f1e-2a7d6b4c8e90
        rewardId:
          type: integer
          description: The ID of the reward that was used.
          example: 5
        applicationId:
          type: integer
          description: The ID of the Application the reward belongs to.
          example: 1
    EffectUseReward:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: useReward
          x-rollback-effect:
            $ref: '#/components/schemas/EffectRollbackUseReward'
          description: The `useReward` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - useReward
              description: An effect discriminator of type `useReward`.
            props:
              $ref: '#/components/schemas/UseRewardEffectProps'
    WillAwardGiveawayEffectProps:
      type: object
      title: willAwardGiveaway
      description: |-
        The equivalent of the `awardGiveaway` effect but returned when updating a session with any state other than `closed`. This ensures no giveaway codes are leaked when they are still not guaranteed to be awarded.

        For more information about session states, see [Manage the session's state](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions#manage-the-sessions-state).
      example:
        poolId: 2
        poolName: My pool
        recipientIntegrationId: URNGV8294NV
      required:
        - poolId
        - poolName
        - recipientIntegrationId
      properties:
        poolId:
          type: integer
          description: The internal ID of the giveaway pool.
          example: 2
        poolName:
          type: string
          description: The name of the giveaway pool.
          example: My pool
        recipientIntegrationId:
          type: string
          maxLength: 1000
          description: The integration ID of the customer that receives the giveaway.
          example: URNGV8294NV
    EffectWillAwardGiveaway:
      allOf:
        - $ref: '#/components/schemas/EffectEntity'
        - type: object
          title: willAwardGiveaway
          description: The `willAwardGiveaway` effect and its properties. See [API effects](https://docs.talon.one/docs/dev/integration-api/api-effects).
          required:
            - effectType
            - props
          properties:
            effectType:
              type: string
              enum:
                - willAwardGiveaway
              description: An effect discriminator of type `willAwardGiveaway`.
            props:
              $ref: '#/components/schemas/WillAwardGiveawayEffectProps'
    Effect:
      type: object
      oneOf:
        - $ref: '#/components/schemas/EffectAcceptCoupon'
        - $ref: '#/components/schemas/EffectAcceptReferral'
        - $ref: '#/components/schemas/EffectAddFreeItem'
        - $ref: '#/components/schemas/EffectAddLoyaltyPoints'
        - $ref: '#/components/schemas/EffectAddNegativeLoyaltyPoints'
        - $ref: '#/components/schemas/EffectAddToAudience'
        - $ref: '#/components/schemas/EffectAwardGiveaway'
        - $ref: '#/components/schemas/EffectBoostLoyaltyTier'
        - $ref: '#/components/schemas/EffectCallApi'
        - $ref: '#/components/schemas/EffectChangeLoyaltyTierLevel'
        - $ref: '#/components/schemas/EffectCouponCreated'
        - $ref: '#/components/schemas/EffectCustomEffect'
        - $ref: '#/components/schemas/EffectDeductLoyaltyPoints'
        - $ref: '#/components/schemas/EffectError'
        - $ref: '#/components/schemas/EffectExtendLoyaltyPointsExpiryDate'
        - $ref: '#/components/schemas/EffectIncreaseAchievementProgress'
        - $ref: '#/components/schemas/EffectIncreaseAchievementProgressPerItem'
        - $ref: '#/components/schemas/EffectJoinLoyaltyProgram'
        - $ref: '#/components/schemas/EffectOffsetNegativeLoyaltyPoints'
        - $ref: '#/components/schemas/EffectRedeemReferral'
        - $ref: '#/components/schemas/EffectReferralCreated'
        - $ref: '#/components/schemas/EffectRejectCoupon'
        - $ref: '#/components/schemas/EffectRejectReferral'
        - $ref: '#/components/schemas/EffectRemoveFromAudience'
        - $ref: '#/components/schemas/EffectReserveCoupon'
        - $ref: '#/components/schemas/EffectRollbackAddedLoyaltyPoints'
        - $ref: '#/components/schemas/EffectRollbackCoupon'
        - $ref: '#/components/schemas/EffectRollbackDeductedLoyaltyPoints'
        - $ref: '#/components/schemas/EffectRollbackDiscount'
        - $ref: '#/components/schemas/EffectRollbackIncreasedAchievementProgress'
        - $ref: '#/components/schemas/EffectRollbackIncreasedAchievementProgressPerItem'
        - $ref: '#/components/schemas/EffectRollbackReferral'
        - $ref: '#/components/schemas/EffectRollbackTierBoost'
        - $ref: '#/components/schemas/EffectRollbackUseReward'
        - $ref: '#/components/schemas/EffectSet'
        - $ref: '#/components/schemas/EffectSetDiscount'
        - $ref: '#/components/schemas/EffectSetDiscountPerAdditionalCost'
        - $ref: '#/components/schemas/EffectSetDiscountPerAdditionalCostPerItem'
        - $ref: '#/components/schemas/EffectSetDiscountPerItem'
        - $ref: '#/components/schemas/EffectSetLoyaltyPointsExpiryDate'
        - $ref: '#/components/schemas/EffectShowBundleMetadata'
        - $ref: '#/components/schemas/EffectShowNotification'
        - $ref: '#/components/schemas/EffectStartAchievementProgress'
        - $ref: '#/components/schemas/EffectUnlockReward'
        - $ref: '#/components/schemas/EffectUseReward'
        - $ref: '#/components/schemas/EffectWillAwardGiveaway'
      discriminator:
        propertyName: effectType
        mapping:
          acceptCoupon: '#/components/schemas/EffectAcceptCoupon'
          acceptReferral: '#/components/schemas/EffectAcceptReferral'
          addFreeItem: '#/components/schemas/EffectAddFreeItem'
          addLoyaltyPoints: '#/components/schemas/EffectAddLoyaltyPoints'
          addNegativeLoyaltyPoints: '#/components/schemas/EffectAddNegativeLoyaltyPoints'
          addToAudience: '#/components/schemas/EffectAddToAudience'
          awardGiveaway: '#/components/schemas/EffectAwardGiveaway'
          boostLoyaltyTier: '#/components/schemas/EffectBoostLoyaltyTier'
          callApi: '#/components/schemas/EffectCallApi'
          changeLoyaltyTierLevel: '#/components/schemas/EffectChangeLoyaltyTierLevel'
          couponCreated: '#/components/schemas/EffectCouponCreated'
          customEffect: '#/components/schemas/EffectCustomEffect'
          deductLoyaltyPoints: '#/components/schemas/EffectDeductLoyaltyPoints'
          error: '#/components/schemas/EffectError'
          extendLoyaltyPointsExpiryDate: '#/components/schemas/EffectExtendLoyaltyPointsExpiryDate'
          increaseAchievementProgress: '#/components/schemas/EffectIncreaseAchievementProgress'
          increaseAchievementProgressPerItem: '#/components/schemas/EffectIncreaseAchievementProgressPerItem'
          joinLoyaltyProgram: '#/components/schemas/EffectJoinLoyaltyProgram'
          offsetNegativeLoyaltyPoints: '#/components/schemas/EffectOffsetNegativeLoyaltyPoints'
          redeemReferral: '#/components/schemas/EffectRedeemReferral'
          referralCreated: '#/components/schemas/EffectReferralCreated'
          rejectCoupon: '#/components/schemas/EffectRejectCoupon'
          rejectReferral: '#/components/schemas/EffectRejectReferral'
          removeFromAudience: '#/components/schemas/EffectRemoveFromAudience'
          reserveCoupon: '#/components/schemas/EffectReserveCoupon'
          rollbackAddedLoyaltyPoints: '#/components/schemas/EffectRollbackAddedLoyaltyPoints'
          rollbackCoupon: '#/components/schemas/EffectRollbackCoupon'
          rollbackDeductedLoyaltyPoints: '#/components/schemas/EffectRollbackDeductedLoyaltyPoints'
          rollbackDiscount: '#/components/schemas/EffectRollbackDiscount'
          rollbackIncreasedAchievementProgress: '#/components/schemas/EffectRollbackIncreasedAchievementProgress'
          rollbackIncreasedAchievementProgressPerItem: '#/components/schemas/EffectRollbackIncreasedAchievementProgressPerItem'
          rollbackReferral: '#/components/schemas/EffectRollbackReferral'
          rollbackTierBoost: '#/components/schemas/EffectRollbackTierBoost'
          rollbackUseReward: '#/components/schemas/EffectRollbackUseReward'
          set: '#/components/schemas/EffectSet'
          setDiscount: '#/components/schemas/EffectSetDiscount'
          setDiscountPerAdditionalCost: '#/components/schemas/EffectSetDiscountPerAdditionalCost'
          setDiscountPerAdditionalCostPerItem: '#/components/schemas/EffectSetDiscountPerAdditionalCostPerItem'
          setDiscountPerItem: '#/components/schemas/EffectSetDiscountPerItem'
          setLoyaltyPointsExpiryDate: '#/components/schemas/EffectSetLoyaltyPointsExpiryDate'
          showBundleMetadata: '#/components/schemas/EffectShowBundleMetadata'
          showNotification: '#/components/schemas/EffectShowNotification'
          startAchievementProgress: '#/components/schemas/EffectStartAchievementProgress'
          unlockReward: '#/components/schemas/EffectUnlockReward'
          useReward: '#/components/schemas/EffectUseReward'
          willAwardGiveaway: '#/components/schemas/EffectWillAwardGiveaway'
    ErrorSource:
      type: object
      description: |
        The source of the current error, exactly one of `pointer`, `parameter` or `line` will be defined.
      properties:
        pointer:
          type: string
          description: Pointer to the path in the payload that caused this error.
        parameter:
          type: string
          description: Query parameter that caused this error.
        line:
          type: string
          description: Line number in uploaded multipart file that caused this error. 'N/A' if unknown.
        resource:
          type: string
          description: Pointer to the resource that caused this error.
    APIError:
      type: object
      required:
        - source
        - title
      properties:
        title:
          type: string
          description: Short description of the problem.
        details:
          type: string
          description: Longer description of this specific instance of the problem.
        source:
          $ref: '#/components/schemas/ErrorSource'
    ErrorResponse:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: A message describing the error.
        errors:
          type: array
          description: An array of individual problems encountered during the request.
          items:
            $ref: '#/components/schemas/APIError'
    ErrorResponseWithStatus:
      type: object
      properties:
        message:
          type: string
        errors:
          type: array
          description: An array of individual problems encountered during the request.
          items:
            $ref: '#/components/schemas/APIError'
        StatusCode:
          type: integer
          description: The error code.
    CustomerProfileEntity:
      type: object
      required:
        - id
        - created
      properties:
        id:
          type: integer
          description: The internal ID of the customer profile.
          example: 6
        created:
          type: string
          format: date-time
          description: The time the customer profile was created.
          example: '2020-06-10T09:05:27.993483Z'
    NewCustomerProfile:
      type: object
      properties:
        attributes:
          type: object
          additionalProperties: true
          description: Arbitrary properties associated with this item.
          example:
            Language: english
            ShippingCountry: DE
    LoyaltyMembership:
      type: object
      required:
        - loyaltyProgramId
      properties:
        joined:
          type: string
          format: date-time
          title: Loyalty program joined at
          description: The moment in which the loyalty program was joined.
          example: '2012-03-20T14:15:22Z'
        loyaltyProgramId:
          type: integer
          title: Loyalty program ID
          description: The ID of the loyalty program belonging to this entity.
          example: 323414846
    AudienceMembership:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          title: Audience ID
          description: The ID of the audience belonging to this entity.
          example: 2
        name:
          type: string
          title: Audience Name
          description: The Name of the audience belonging to this entity.
          example: Travel audience
    CustomerProfile:
      allOf:
        - $ref: '#/components/schemas/CustomerProfileEntity'
        - $ref: '#/components/schemas/IntegrationEntity'
        - $ref: '#/components/schemas/NewCustomerProfile'
        - type: object
          properties:
            accountId:
              type: integer
              title: Profile belongs to Account
              description: The ID of the Talon.One account that owns this profile.
              example: 31
            closedSessions:
              type: integer
              title: Closed sessions
              description: The total number of closed sessions. Does not include closed sessions that have been cancelled or reopened. See the [docs](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions#customer-session-states).
              example: 3
            totalSales:
              type: number
              description: |
                The total amount of money spent by the customer **before** discounts are applied.

                The total sales amount excludes the following:
                - Cancelled or reopened sessions.
                - Returned items.
              example: 299.99
              title: Total Sales
            loyaltyMemberships:
              type: array
              deprecated: true
              description: |
                **DEPRECATED. Always returns `null`.** A list of loyalty programs joined by the customer.
              items:
                $ref: '#/components/schemas/LoyaltyMembership'
              title: Loyalty programed joined
              example: null
            audienceMemberships:
              type: array
              description: The audiences the customer belongs to.
              items:
                $ref: '#/components/schemas/AudienceMembership'
              title: Audience memberships
            lastActivity:
              type: string
              format: date-time
              title: Last activity
              description: |
                Timestamp of the most recent event received from this customer.
                This field is updated on calls that trigger the Rule Engine and that are
                not [dry requests](https://docs.talon.one/docs/dev/integration-api/dry-requests/#overlay).

                For example, [reserving a coupon](https://docs.talon.one/integration-api#tag/Coupons/operation/createCouponReservation)
                for a customer doesn't impact this field.
              example: '2020-02-08T14:15:20Z'
            sandbox:
              type: boolean
              description: |
                An indicator of whether the customer is part of a sandbox or live Application. See the [docs](https://docs.talon.one/docs/product/applications/overview#application-environments).
              title: Sandbox
              example: false
          required:
            - accountId
            - closedSessions
            - totalSales
            - lastActivity
            - attributes
    LoyaltyProgramEntity:
      type: object
      required:
        - programID
      properties:
        programID:
          type: integer
          description: The ID of the loyalty program that owns this entity.
          example: 125
        programName:
          type: string
          description: The integration name of the loyalty program that owns this entity.
          example: Loyalty_program
        programTitle:
          type: string
          description: The Campaign Manager-displayed name of the loyalty program that owns this entity.
          example: Loyalty program
    UpdateLoyaltyCard:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          description: |
            Status of the loyalty card. Can be `active` or `inactive`.
          example: active
        blockReason:
          type: string
          description: |
            Reason for transferring and blocking the loyalty card.
          example: Current card lost. Customer needs a new card.
    LoyaltyCardProfileRegistration:
      type: object
      required:
        - integrationId
        - timestamp
      properties:
        integrationId:
          type: string
          maxLength: 1000
          description: Integration ID of the customer profile linked to the card.
          example: R195412
        timestamp:
          type: string
          format: date-time
          description: Timestamp the customer profile was linked to the card.
          example: '2021-09-12T10:12:42Z'
    LoyaltyProgramBalance:
      type: object
      required:
        - currentBalance
        - pendingBalance
        - expiredBalance
        - spentBalance
        - tentativeCurrentBalance
      description: The balance in a Loyalty Program for some Customer.
      properties:
        currentBalance:
          type: number
          title: Current balance
          description: Sum of currently active points.
          example: 100
        pendingBalance:
          type: number
          title: Pending balance
          description: Sum of pending points.
          example: 10
        negativeBalance:
          type: number
          title: Negative balance
          description: Sum of negative points. This implies that `currentBalance` is `0`.
          example: 10
        expiredBalance:
          type: number
          deprecated: true
          title: Expired balance
          description: |
            **DEPRECATED** Value is shown as 0.
          example: 0
        spentBalance:
          type: number
          deprecated: true
          title: Spent balance
          description: |
            **DEPRECATED** Value is shown as 0.
          example: 0
        tentativeCurrentBalance:
          type: number
          title: Tentative current balance
          description: |
            The tentative points balance, reflecting the `currentBalance` and all point additions and deductions within the current open customer session. When the session is closed, the effects are applied and the `currentBalance` is updated to this value.

            **Note:** Tentative balances are specific to the current session and do not take into account other open sessions for the given customer.
          example: 100
        tentativePendingBalance:
          type: number
          title: Tentative pending balance
          description: |
            The tentative points balance, reflecting the `pendingBalance` and all point additions with a future activation date within the current open customer session. When the session is closed, the effects are applied and the `pendingBalance` is updated to this value.

            **Note:** Tentative balances are specific to the current session and do not take into account other open sessions for the given customer.
          example: 20
        tentativeNegativeBalance:
          type: number
          title: Tentative negative balance
          description: |
            The tentative negative balance after all additions and deductions from the current customer session are applied to `negativeBalance`. When the session is closed, the tentative effects are applied and `negativeBalance` is updated to this value.

            **Note:** Tentative balances are specific to the current session and do not take into account other open sessions for the given customer.
          example: 100
    Tier:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          description: The internal ID of the tier.
          example: 11
        name:
          type: string
          description: The name of the tier.
          example: bronze
        startDate:
          type: string
          format: date-time
          description: Date and time when the customer moved to this tier. This value uses the loyalty program's time zone setting.
          example: 2025-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: '2026-08-02T15:04:05+07:00'
        downgradePolicy:
          type: string
          enum:
            - one_down
            - balance_based
          description: |
            The policy that defines how customer tiers are downgraded in the loyalty program after tier reevaluation.
             - `one_down`: If the customer doesn't have enough points to stay in the current tier, they are downgraded by one tier.
             - `balance_based`: The customer's tier is reevaluated based on the amount of active points they have at the moment.
          example: one_down
        source:
          type: string
          enum:
            - boost
            - points
          default: points
          description: |
            Indicates whether the customer's current tier was determined based on their
            points balance or a temporary boost.

            - `points`: The tier reflects the customer's current point balance.
            - `boost`: A temporary tier boost is in effect where the customer is in a higher tier than their points-based tier. The boost expires after a set duration and the customer returns to their points-based tier.
          example: points
        reason:
          type: string
          description: |
            The reason for the tier assignment.
          example: Subscription to newsletter
    LedgerInfo:
      allOf:
        - $ref: '#/components/schemas/LoyaltyProgramBalance'
        - type: object
          properties:
            currentTier:
              $ref: '#/components/schemas/Tier'
              description: Tier for which the ledger is eligible.
            pointsToNextTier:
              type: number
              description: Points required to move up a tier.
              example: 20
            nextTierName:
              type: string
              description: |
                The name of the next higher tier level in the loyalty program.

                **Note**:
                - Returns `null` if the customer has reached the highest available tier.
                - Returns the lowest level tier name if the customer is not currently assigned to any tier.
              example: Silver
    LoyaltyCard:
      allOf:
        - $ref: '#/components/schemas/Entity'
        - $ref: '#/components/schemas/LoyaltyProgramEntity'
        - $ref: '#/components/schemas/UpdateLoyaltyCard'
        - type: object
          required:
            - identifier
            - usersPerCardLimit
          properties:
            identifier:
              $ref: '#/components/schemas/LoyaltyCardIdentifier'
            usersPerCardLimit:
              type: integer
              minimum: 0
              example: 111
              description: |
                The max amount of customer profiles that can be linked to the card. 0 means unlimited.
            profiles:
              type: array
              description: Integration IDs of the customers profiles linked to the card.
              items:
                $ref: '#/components/schemas/LoyaltyCardProfileRegistration'
            ledger:
              $ref: '#/components/schemas/LedgerInfo'
              description: Displays point balances of the card in the main ledger of the loyalty program.
            subledgers:
              type: object
              description: Displays point balances of the card in the subledgers of the loyalty program.
              additionalProperties:
                $ref: '#/components/schemas/LedgerInfo'
            modified:
              type: string
              format: date-time
              description: Timestamp of the most recent update of the loyalty card.
              example: '2021-09-12T10:12:42Z'
            oldCardIdentifier:
              $ref: '#/components/schemas/LoyaltyCardIdentifier'
              description: The identifier of the card from which the points were transferred.
              example: summer-loyalty-card-0543
            newCardIdentifier:
              $ref: '#/components/schemas/LoyaltyCardIdentifier'
              description: The identifier of the card to which the points were transferred.
              example: autumn-loyalty-card-5822
            batchId:
              description: The ID of the batch in which the loyalty card was created.
              type: string
              example: wdefpov
    EntityWithTalangVisibleID:
      type: object
      required:
        - id
        - created
      properties:
        id:
          type: integer
          description: Unique ID for this entity.
          example: 4
        created:
          type: string
          format: date-time
          description: The exact moment this entity was created.
          example: '2020-06-10T09:05:27.993483Z'
    UserEntity:
      type: object
      required:
        - userId
      properties:
        userId:
          type: integer
          description: The ID of the user associated with this entity.
          example: 388
    CodeGeneratorSettings:
      type: object
      properties:
        validCharacters:
          type: array
          description: |
            List of characters used to generate the random parts of a code.
          example:
            - A
            - B
            - C
            - D
            - E
            - F
            - G
            - H
            - I
            - J
            - K
            - L
            - M
            - 'N'
            - O
            - P
            - Q
            - R
            - S
            - T
            - U
            - V
            - W
            - X
            - 'Y'
            - Z
            - '0'
            - '1'
            - '2'
            - '3'
            - '4'
            - '5'
            - '6'
            - '7'
            - '8'
            - '9'
          items:
            type: string
        couponPattern:
          type: string
          description: |
            The pattern used to generate codes, such as coupon codes, referral codes, and loyalty cards. The character `#` is a placeholder and is replaced by a random character from the `validCharacters` set.
          maxLength: 100
          minLength: 3
          pattern: ^[A-Za-z0-9._%+@#-]+$
          example: SUMMER-####-####
      additionalProperties: false
      required:
        - couponPattern
        - validCharacters
    LimitConfig:
      type: object
      required:
        - action
        - limit
        - entities
      properties:
        action:
          type: string
          description: |
            The limitable action to which this limit applies. For example:
            - `setDiscount`
            - `setDiscountEffect`
            - `redeemCoupon`
            - `createCoupon`
          example: createCoupon
        limit:
          type: number
          minimum: 0
          example: 1000
          description: The value to set for the limit.
        period:
          description: The period on which the budget limit recurs.
          type: string
          enum:
            - daily
            - weekly
            - monthly
            - yearly
          example: yearly
        entities:
          type: array
          description: The entity that this limit applies to.
          example:
            - Coupon
          items:
            type: string
            enum:
              - Coupon
              - Referral
              - Profile
              - Identifier
              - Store
              - Session
    BaseCampaign:
      type: object
      properties:
        name:
          type: string
          title: Campaign Name
          description: A user-facing name for this campaign.
          minLength: 1
          example: Summer promotions
        description:
          type: string
          title: Campaign Description
          description: A detailed description of the campaign.
          example: Campaign for all summer 2021 promotions
        startTime:
          type: string
          format: date-time
          description: Timestamp when the campaign will become active.
          example: '2021-07-20T22:00:00Z'
        endTime:
          type: string
          format: date-time
          description: Timestamp when the campaign will become inactive.
          example: '2021-09-22T22:00:00Z'
        attributes:
          type: object
          description: Arbitrary properties associated with this campaign.
        state:
          type: string
          enum:
            - enabled
            - disabled
            - archived
          default: enabled
          example: enabled
          description: |
            A disabled or archived campaign is not evaluated for rules or coupons.
        activeRulesetId:
          type: integer
          description: |
            [ID of Ruleset](https://docs.talon.one/management-api#tag/Campaigns/operation/getRulesets) this
            campaign applies on customer session evaluation.
          example: 6
        tags:
          type: array
          description: A list of tags for the campaign.
          example:
            - summer
          maxItems: 50
          items:
            type: string
            minLength: 1
            maxLength: 50
        reevaluateOnReturn:
          type: boolean
          title: Reevaluate on return
          description: Indicates whether this campaign should be reevaluated when a customer returns an item.
          example: true
        features:
          type: array
          description: The features enabled in this campaign.
          example:
            - coupons
            - referrals
          items:
            type: string
            enum:
              - coupons
              - referrals
              - loyalty
              - giveaways
              - strikethrough
              - achievements
              - advancedEvents
        couponSettings:
          $ref: '#/components/schemas/CodeGeneratorSettings'
        referralSettings:
          $ref: '#/components/schemas/CodeGeneratorSettings'
        limits:
          type: array
          description: |
            The set of [budget limits](https://docs.talon.one/docs/product/campaigns/settings/managing-campaign-budgets) for this campaign.
          items:
            $ref: '#/components/schemas/LimitConfig'
        campaignGroups:
          type: array
          description: |
            The IDs of the [campaign groups](https://docs.talon.one/docs/product/account/managing-campaign-groups) this campaign belongs to.
          example:
            - 1
            - 3
          items:
            type: integer
        type:
          type: string
          title: Type
          enum:
            - cartItem
            - advanced
          default: advanced
          example: advanced
          description: |
            The campaign type. Possible type values:
              - `cartItem`: Type of campaign that can apply effects only to cart items.
              - `advanced`: Type of campaign that can apply effects to customer sessions and cart items.
        linkedStoreIds:
          type: array
          description: |
            A list of store IDs that you want to link to the campaign.

            **Note:** Campaigns with linked store IDs will only be evaluated when there is a
            [customer session update](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2)
            that references a linked store.
          items:
            type: integer
          example:
            - 1
            - 2
            - 3
        couponAttributes:
          type: object
          description: Arbitrary properties associated with coupons in this campaign.
      required:
        - name
        - state
        - tags
        - limits
        - features
    CampaignBudget:
      type: object
      required:
        - action
        - limit
        - counter
      properties:
        action:
          type: string
          description: |
            The limitable action to which this limit applies. For example:
            - `setDiscount`
            - `setDiscountEffect`
            - `redeemCoupon`
            - `createCoupon`
          example: createCoupon
        limit:
          type: number
          minimum: 0
          example: 1000
          description: The value to set for the limit.
        counter:
          type: number
          minimum: 0
          example: 42
          description: The number of occurrences of the limited action in the context of the campaign.
    AdditionalCampaignProperties:
      type: object
      properties:
        budgets:
          type: array
          items:
            $ref: '#/components/schemas/CampaignBudget'
          description: |
            A list of all the budgets that are defined by this campaign and their usage.

            **Note:** Budgets that are not defined do not appear in this list and their usage is
            not counted until they are defined.
        couponRedemptionCount:
          type: integer
          deprecated: true
          description: |
            This property is **deprecated**. The count should be available under *budgets* property.
            Number of coupons redeemed in the campaign.
          example: 163
        referralRedemptionCount:
          type: integer
          deprecated: true
          description: |
            This property is **deprecated**. The count should be available under *budgets* property.
            Number of referral codes redeemed in the campaign.
          example: 3
        discountCount:
          type: number
          deprecated: true
          description: |
            This property is **deprecated**. The count should be available under *budgets* property.
            Total amount of discounts redeemed in the campaign.
          example: 288
        discountEffectCount:
          type: integer
          deprecated: true
          description: |
            This property is **deprecated**. The count should be available under *budgets* property.
            Total number of times discounts were redeemed in this campaign.
          example: 343
        couponCreationCount:
          type: integer
          deprecated: true
          description: |
            This property is **deprecated**. The count should be available under *budgets* property.
            Total number of coupons created by rules in this campaign.
          example: 16
        customEffectCount:
          type: integer
          deprecated: true
          description: |
            This property is **deprecated**. The count should be available under *budgets* property.
            Total number of custom effects triggered by rules in this campaign.
          example: 0
        referralCreationCount:
          type: integer
          deprecated: true
          description: |
            This property is **deprecated**. The count should be available under *budgets* property.
            Total number of referrals created by rules in this campaign.
          example: 8
        addFreeItemEffectCount:
          type: integer
          deprecated: true
          description: |
            This property is **deprecated**. The count should be available under *budgets* property.
            Total number of times the [add free item effect](https://docs.talon.one/docs/dev/integration-api/api-effects#addfreeitem) can be triggered in this campaign.
          example: 0
        awardedGiveawaysCount:
          type: integer
          deprecated: true
          description: |
            This property is **deprecated**. The count should be available under *budgets* property.
            Total number of giveaways awarded by rules in this campaign.
          example: 9
        createdLoyaltyPointsCount:
          type: number
          deprecated: true
          description: |
            This property is **deprecated**. The count should be available under *budgets* property.
            Total number of loyalty points created by rules in this campaign.
          example: 9
        createdLoyaltyPointsEffectCount:
          type: integer
          deprecated: true
          description: |
            This property is **deprecated**. The count should be available under *budgets* property.
            Total number of loyalty point creation effects triggered by rules in this campaign.
          example: 2
        redeemedLoyaltyPointsCount:
          type: number
          deprecated: true
          description: |
            This property is **deprecated**. The count should be available under *budgets* property.
            Total number of loyalty points redeemed by rules in this campaign.
          example: 8
        redeemedLoyaltyPointsEffectCount:
          type: integer
          deprecated: true
          description: |
            This property is **deprecated**. The count should be available under *budgets* property.
            Total number of loyalty point redemption effects triggered by rules in this campaign.
          example: 9
        callApiEffectCount:
          type: integer
          deprecated: true
          description: |
            This property is **deprecated**. The count should be available under *budgets* property.
            Total number of webhooks triggered by rules in this campaign.
          example: 0
        reservecouponEffectCount:
          type: integer
          deprecated: true
          description: |
            This property is **deprecated**. The count should be available under *budgets* property.
            Total number of reserve coupon effects triggered by rules in this campaign.
          example: 9
        lastActivity:
          type: string
          format: date-time
          example: '2022-11-10T23:00:00Z'
          description: Timestamp of the most recent event received by this campaign.
        updated:
          type: string
          format: date-time
          example: '2022-10-27T15:00:00Z'
          description: |
            Timestamp of the most recent update to the campaign's property. Updates to external entities used in this campaign
            are **not** registered by this property, such as collection or coupon updates.
        createdBy:
          type: string
          description: Name of the user who created this campaign if available.
          example: John Doe
        updatedBy:
          type: string
          description: Name of the user who last updated this campaign if available.
          example: Jane Doe
        templateId:
          type: integer
          description: The ID of the Campaign Template this Campaign was created from.
          example: 3
        frontendState:
          type: string
          description: The campaign state displayed in the Campaign Manager.
          enum:
            - expired
            - scheduled
            - running
            - disabled
            - archived
            - staged
          example: running
        storesImported:
          type: boolean
          description: Indicates whether the linked stores were imported via a CSV file.
          example: true
        valueMapsIds:
          type: array
          description: A list of value map IDs for the campaign.
          items:
            type: integer
          example:
            - 100
            - 215
        experimentId:
          type: integer
          description: The ID of the Experiment this Campaign is part of.
          example: 1
      required:
        - state
        - description
        - type
        - frontendState
        - storesImported
    CampaignVersions:
      type: object
      properties:
        revisionFrontendState:
          type: string
          description: The campaign revision state displayed in the Campaign Manager.
          enum:
            - revised
            - pending
          example: revised
        activeRevisionId:
          type: integer
          description: |
            ID of the revision that was last activated on this campaign.
          example: 6
        activeRevisionVersionId:
          type: integer
          description: |
            ID of the revision version that is active on the campaign.
          example: 6
        version:
          type: integer
          description: |
            Incrementing number representing how many revisions have been activated on this campaign. Starts from `0` for a new campaign.
          example: 6
        currentRevisionId:
          type: integer
          description: |
            ID of the revision currently being modified for the campaign.
          example: 6
        currentRevisionVersionId:
          type: integer
          description: |
            ID of the latest version applied on the current revision.
          example: 6
        stageRevision:
          type: boolean
          description: |
            Flag for determining whether we use current revision when sending requests with staging API key.
          example: false
          default: false
    Campaign:
      allOf:
        - $ref: '#/components/schemas/EntityWithTalangVisibleID'
        - $ref: '#/components/schemas/ApplicationEntity'
        - $ref: '#/components/schemas/UserEntity'
        - $ref: '#/components/schemas/BaseCampaign'
        - $ref: '#/components/schemas/AdditionalCampaignProperties'
        - $ref: '#/components/schemas/CampaignVersions'
        - type: object
          required:
            - reevaluateOnReturn
    RuleFailureReason:
      type: object
      description: Details about why a rule failed.
      required:
        - campaignID
        - campaignName
        - rulesetID
        - ruleIndex
        - ruleName
      properties:
        campaignID:
          type: integer
          description: The ID of the campaign that contains the rule that failed.
        campaignName:
          type: string
          description: The name of the campaign that contains the rule that failed.
        rulesetID:
          type: integer
          description: The ID of the ruleset that contains the rule that failed.
        couponID:
          type: integer
          description: The ID of the coupon that was being evaluated at the time of the rule failure.
          example: 4928
        couponValue:
          type: string
          description: The code of the coupon that was being evaluated at the time of the rule failure.
        referralID:
          type: integer
          description: The ID of the referral that was being evaluated at the time of the rule failure.
        referralValue:
          type: string
          description: The code of the referral that was being evaluated at the time of the rule failure.
        rewardId:
          type: integer
          description: The ID of the reward that was being evaluated at the time of the rule failure.
          example: 7
        rewardIntegrationId:
          type: string
          description: The integration ID of the reward that was being evaluated at the time of the rule failure.
          example: 5c0b5e6d-3f8a-4c2b-9f1e-2a7d6b4c8e90
        ruleIndex:
          type: integer
          description: The index of the rule that failed within the ruleset.
        ruleName:
          type: string
          description: The name of the rule that failed within the ruleset.
        conditionIndex:
          type: integer
          description: The index of the condition that failed.
        effectIndex:
          type: integer
          description: The index of the effect that failed.
        details:
          type: string
          description: More details about the failure.
        evaluationGroupID:
          type: integer
          example: 3
          description: The ID of the evaluation group. For more information, see [Managing campaign evaluation](https://docs.talon.one/docs/product/applications/managing-campaign-evaluation).
        evaluationGroupMode:
          type: string
          example: stackable
          description: The evaluation mode of the evaluation group. For more information, see [Managing campaign evaluation](https://docs.talon.one/docs/product/applications/managing-campaign-evaluation).
    CouponEntity:
      type: object
      required:
        - id
        - created
      properties:
        id:
          type: integer
          description: The internal ID of the coupon.
          example: 6
        created:
          type: string
          format: date-time
          description: The time the coupon was created.
          example: '2020-06-10T09:05:27.993483Z'
    CampaignEntity:
      type: object
      required:
        - campaignId
      properties:
        campaignId:
          type: integer
          title: Campaign ID
          description: The ID of the campaign that owns this entity.
          example: 211
    CouponValue:
      type: object
      properties:
        value:
          type: string
          title: Coupon Code
          description: The coupon code.
          minLength: 4
          example: XMAS-20-2021
    CouponConstraints:
      type: object
      properties:
        usageLimit:
          type: integer
          minimum: 0
          maximum: 999999
          example: 100
          description: |
            The number of times the coupon code can be redeemed. `0` means unlimited redemptions but any campaign usage limits will still apply.
        discountLimit:
          type: number
          minimum: 0
          maximum: 1000000000000000
          example: 30
          description: |
            The total discount value that the code can give. Typically used to represent a gift card value.
        reservationLimit:
          type: integer
          minimum: 0
          maximum: 999999
          example: 45
          description: |
            The number of reservations that can be made with this coupon code.
        startDate:
          type: string
          format: date-time
          example: '2020-01-24T14:15:22Z'
          description: Timestamp at which point the coupon becomes valid.
        expiryDate:
          type: string
          format: date-time
          example: '2023-08-24T14:15:22Z'
          description: Expiration date of the coupon. Coupon never expires if this is omitted.
    CouponLimitConfigs:
      type: object
      properties:
        limits:
          type: array
          description: |
            Limits configuration for a coupon. These limits will override the limits
            set from the campaign.

            **Note:** Only usable when creating a single coupon which is not tied to a specific recipient.
            Only per-profile limits are allowed to be configured.
          items:
            $ref: '#/components/schemas/LimitConfig'
    Coupon:
      allOf:
        - $ref: '#/components/schemas/CouponEntity'
        - $ref: '#/components/schemas/CampaignEntity'
        - $ref: '#/components/schemas/CouponValue'
        - $ref: '#/components/schemas/CouponConstraints'
        - $ref: '#/components/schemas/CouponLimitConfigs'
        - type: object
          required:
            - value
            - usageCounter
            - usageLimit
          properties:
            usageCounter:
              type: integer
              title: Total coupon redemptions
              example: 10
              description: The number of times the coupon has been successfully redeemed.
            discountCounter:
              type: number
              title: Discounts Given
              description: The amount of discounts given on rules redeeming this coupon. Only usable if a coupon discount budget was set for this coupon.
              example: 10
            discountRemainder:
              type: number
              title: Coupon Discount Remainder
              description: The remaining discount this coupon can give.
              example: 5
            reservationCounter:
              type: number
              title: Number of reservations
              description: The number of times this coupon has been reserved.
              example: 1
            attributes:
              type: object
              title: Attributes of coupon
              description: Custom attributes associated with this coupon.
            referralId:
              type: integer
              title: Advocate ID
              description: The integration ID of the referring customer (if any) for whom this coupon was created as an effect.
              example: 326632952
            recipientIntegrationId:
              title: Recipient ID
              example: URNGV8294NV
              type: string
              maxLength: 1000
              description: The Integration ID of the customer that is allowed to redeem this coupon.
            importId:
              title: Import ID
              type: integer
              description: The ID of the Import which created this coupon.
              example: 4
            reservation:
              title: Reservation Type
              type: boolean
              example: false
              description: |
                Defines the reservation type:
                - `true`: The coupon can be reserved for multiple customers.
                - `false`: The coupon can be reserved only for one customer. It is a personal code.
              default: true
            batchId:
              title: Batch ID
              type: string
              description: The id of the batch the coupon belongs to.
              example: 32535-43255
            isReservationMandatory:
              title: Is reservation mandatory
              type: boolean
              example: false
              description: An indication of whether the code can be redeemed only if it has been reserved first.
              default: false
            implicitlyReserved:
              title: Is coupon implicitly reserved for all customers
              description: An indication of whether the coupon is implicitly reserved for all customers.
              type: boolean
              example: false
    ReferralConstraints:
      type: object
      properties:
        startDate:
          type: string
          format: date-time
          title: Referral code valid from
          description: Timestamp at which point the referral code becomes valid.
          example: '2020-11-10T23:00:00Z'
        expiryDate:
          type: string
          format: date-time
          title: Referral code valid until
          description: Expiration date of the referral code. Referral never expires if this is omitted.
          example: '2021-11-10T23:00:00Z'
        usageLimit:
          type: integer
          title: Referral code Usage Limit
          description: |
            The number of times a referral code can be used. `0` means no limit but any campaign usage limits will still apply.
          minimum: 0
          maximum: 999999
          example: 1
    NewReferral:
      allOf:
        - $ref: '#/components/schemas/ReferralConstraints'
        - type: object
          required:
            - campaignId
            - advocateProfileIntegrationId
          properties:
            campaignId:
              type: integer
              title: Referral's Campaign ID
              description: ID of the campaign from which the referral received the referral code.
              example: 78
            advocateProfileIntegrationId:
              type: string
              title: Advocate's Profile ID
              description: The Integration ID of the Advocate's Profile.
              maxLength: 1000
              example: URNGV8294NV
            friendProfileIntegrationId:
              type: string
              title: Friend's Profile ID
              description: An optional Integration ID of the Friend's Profile.
              example: BZGGC2454PA
            attributes:
              type: object
              description: Arbitrary properties associated with this item.
              example:
                channel: web
    ImportEntity:
      type: object
      properties:
        importId:
          type: integer
          description: The ID of the Import which created this referral.
          example: 4
    Referral:
      allOf:
        - $ref: '#/components/schemas/Entity'
        - $ref: '#/components/schemas/NewReferral'
        - $ref: '#/components/schemas/ImportEntity'
        - type: object
          required:
            - code
            - usageCounter
            - usageLimit
          properties:
            code:
              type: string
              title: Referral code
              description: The referral code.
              minLength: 4
              example: 27G47Y54VH9L
            usageCounter:
              type: integer
              title: Referral code Usages
              description: The number of times this referral code has been successfully used.
              example: 1
            batchId:
              type: string
              title: Batch ID
              description: The ID of the batch the referrals belong to.
              example: tqyrgahe
    CampaignReference:
      type: object
      required:
        - id
        - applicationId
      properties:
        id:
          type: integer
          description: The ID of the campaign that references this achievement.
          example: 1
        applicationId:
          type: integer
          description: The ID of the Application the campaign belongs to.
          example: 2
    AchievementProgress:
      type: object
      description: The current progress of the customer in the achievement.
      required:
        - status
        - progress
      properties:
        status:
          type: string
          enum:
            - inprogress
            - completed
            - expired
            - not_started
          example: completed
          description: The status of the achievement.
        progress:
          type: number
          example: 10
          description: The current progress of the customer in the achievement.
        startDate:
          format: date-time
          description: Timestamp at which the customer started the achievement.
          type: string
          example: 2024-01-01T15:04:05Z07:00
        completionDate:
          format: date-time
          description: Timestamp at which point the customer completed the achievement.
          type: string
          example: 2024-01-15T15:04:05Z07:00
        endDate:
          format: date-time
          description: Timestamp at which point the achievement ends and resets for the customer.
          type: string
          example: 2024-02-01T15:04:05Z07:00
    EventV3Entity:
      type: object
      properties:
        integrationId:
          type: string
          description: |
            The unique ID of the event. Only one event with this ID can be registered.
          minLength: 1
          example: 175KJPS947296
    AccountEntity:
      type: object
      required:
        - accountId
      properties:
        accountId:
          type: integer
          description: The ID of the account that owns this entity.
          example: 3886
    NewInternalAudience:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          minLength: 1
          description: The human-friendly display name for this audience.
          example: Travel audience
        sandbox:
          type: boolean
          description: Indicates if this is a live or sandbox Application.
          example: true
        description:
          type: string
          description: A description of the audience.
          example: Travel audience 18-27
        subscribedApplicationsIds:
          type: array
          description: A list of the IDs of the Applications that are connected to this audience.
          uniqueItems: true
          items:
            type: integer
          example:
            - 3
            - 13
    NewAudience:
      allOf:
        - $ref: '#/components/schemas/NewInternalAudience'
        - type: object
          required:
            - name
          properties:
            integration:
              type: string
              description: |
                The Talon.One-supported [3rd-party platform](https://docs.talon.one/docs/dev/technology-partners/overview) that this audience was created in.

                For example, `mParticle`, `Segment`, `Shopify`, `Braze`, or `Iterable`.

                **Note:** If you do not integrate with any of these platforms, do not use this property.
              example: mparticle
            integrationId:
              type: string
              minLength: 1
              maxLength: 1000
              description: |
                The ID of this audience in the third-party integration.

                **Note:** To create an audience that doesn't come from a 3rd party platform, do not use this property.
              example: 382370BKDB946
            createdIn3rdParty:
              type: boolean
              description: Determines if this audience is a 3rd party audience or not.
              example: false
            lastUpdate:
              type: string
              format: date-time
              description: The last time that the audience memberships changed.
              example: '2022-04-26T11:02:38Z'
    Audience:
      allOf:
        - $ref: '#/components/schemas/AccountEntity'
        - $ref: '#/components/schemas/Entity'
        - $ref: '#/components/schemas/NewAudience'
    AttributeQuery:
      type: object
      description: Object representing a set of of attributes and their respective values.
      example:
        my_attribute_1: some value
        my_attribute_2: some other value
        my_attribute_3: some other value
    NewAttribute:
      allOf:
        - type: object
          required:
            - entity
            - name
            - title
            - type
            - description
            - suggestions
            - editable
          properties:
            entity:
              type: string
              description: The name of the entity that can have this attribute. When creating or updating the entities of a given type, you can include an `attributes` object with keys corresponding to the `name` of the custom attributes for that type.
              enum:
                - Application
                - Campaign
                - CustomerProfile
                - CustomerSession
                - CartItem
                - Coupon
                - Event
                - Giveaway
                - LoyaltyCard
                - Referral
                - Store
              example: Event
            eventType:
              type: string
              example: pageViewed
            name:
              type: string
              pattern: ^[A-Za-z]\w*$
              description: The attribute name that will be used in API requests and Talang. E.g. if `name == "region"` then you would set the region attribute by including an `attributes.region` property in your request payload.
              example: pageViewed
            title:
              type: string
              pattern: ^[A-Za-z][A-Za-z0-9_.!~*'() -]*$
              description: The human-readable name for the attribute that will be shown in the Campaign Manager. Like `name`, the combination of entity and title must also be unique.
              example: Page view event
            type:
              type: string
              enum:
                - string
                - number
                - boolean
                - time
                - (list string)
                - (list number)
                - (list time)
                - location
                - (list location)
              description: The data type of the attribute, a `time` attribute must be sent as a string that conforms to the [RFC3339](https://www.ietf.org/rfc/rfc3339.txt) timestamp format.
              example: string
            description:
              type: string
              description: A description of this attribute.
              example: Event triggered when a customer displays a page.
            suggestions:
              type: array
              description: A list of suggestions for the attribute.
              maxItems: 50
              items:
                type: string
                minLength: 1
            hasAllowedList:
              type: boolean
              description: Whether or not this attribute has an allowed list of values associated with it.
              default: false
              example: false
            restrictedBySuggestions:
              type: boolean
              description: |
                Whether or not this attribute's value is restricted by suggestions (`suggestions` property)
                or by an allowed list of value (`hasAllowedList` property).
              default: false
              example: false
            editable:
              type: boolean
              description: Whether or not this attribute can be edited.
              example: true
            subscribedApplicationsIds:
              type: array
              description: A list of the IDs of the applications where this attribute is available.
              items:
                type: integer
              example:
                - 1
                - 4
                - 9
            subscribedCatalogsIds:
              type: array
              description: A list of the IDs of the catalogs where this attribute is available.
              items:
                type: integer
              example:
                - 2
                - 5
            allowedSubscriptions:
              type: array
              description: |
                A list of allowed subscription types for this attribute.

                **Note:** This only applies to attributes associated with the `CartItem` entity.
              example:
                - application
                - catalog
              maxItems: 2
              items:
                type: string
                enum:
                  - application
                  - catalog
    Attribute:
      allOf:
        - $ref: '#/components/schemas/Entity'
        - $ref: '#/components/schemas/AccountEntity'
        - $ref: '#/components/schemas/NewAttribute'
        - type: object
          properties:
            eventTypeId:
              type: integer
              example: 22
    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
    MutableEntity:
      type: object
      required:
        - modified
      properties:
        modified:
          type: string
          format: date-time
          description: The time this entity was last modified.
          example: '2021-09-12T10:12:42Z'
    AttributesMandatory:
      type: object
      description: Arbitrary settings associated with attributes.
      properties:
        campaigns:
          type: array
          items:
            type: string
          description: List of mandatory attributes for campaigns.
        coupons:
          type: array
          items:
            type: string
          description: List of mandatory attributes for campaigns.
    AttributesSettings:
      type: object
      description: Arbitrary settings associated with attributes.
      properties:
        mandatory:
          $ref: '#/components/schemas/AttributesMandatory'
    BestPriorPriceSettings:
      type: object
      description: The best prior price settings for this Application.
      properties:
        enableBestPriorPrice:
          type: boolean
          description: When set to `true`, the best prior price feature is enabled in this Application and its [price history](https://docs.talon.one/management-api#tag/Catalogs/operation/priceHistory) is recorded.
          example: true
    UpdateApplication:
      type: object
      properties:
        name:
          type: string
          description: The name of this application.
          minLength: 1
          example: My Application
        description:
          type: string
          description: A longer description of the application.
          example: A test Application
        timezone:
          type: string
          description: A string containing an IANA timezone descriptor.
          minLength: 1
          example: Europe/Berlin
        currency:
          type: string
          description: The default currency for new customer sessions.
          minLength: 1
          example: EUR
        caseSensitivity:
          type: string
          enum:
            - sensitive
            - insensitive-uppercase
            - insensitive-lowercase
          description: The case sensitivity behavior to check coupon codes in the campaigns of this Application.
          example: sensitive
        attributes:
          type: object
          description: Arbitrary properties associated with this campaign.
        limits:
          type: array
          description: Default limits for campaigns created in this application.
          items:
            $ref: '#/components/schemas/LimitConfig'
        defaultDiscountScope:
          type: string
          example: sessionTotal
          description: |
            The default scope to apply `setDiscount` effects on if no scope was provided with the effect.
          enum:
            - sessionTotal
            - cartItems
            - additionalCosts
        enableCascadingDiscounts:
          type: boolean
          description: Indicates if discounts should cascade for this Application.
          example: true
        enableFlattenedCartItems:
          type: boolean
          example: true
          description: |
            Indicates if cart items of quantity larger than one should be separated into different items of quantity one.
        attributesSettings:
          $ref: '#/components/schemas/AttributesSettings'
        sandbox:
          type: boolean
          description: Indicates if this is a live or sandbox Application.
          example: true
        enablePartialDiscounts:
          type: boolean
          description: Indicates if this Application supports partial discounts.
          example: false
        defaultDiscountAdditionalCostPerItemScope:
          type: string
          description: |
            The default scope to apply `setDiscountPerItem` effects on if no scope was provided with the effect.
          example: price
          enum:
            - price
            - itemTotal
            - additionalCosts
        defaultEvaluationGroupId:
          type: integer
          description: The ID of the default campaign evaluation group to which new campaigns will be added unless a different group is selected when creating the campaign.
          example: 3
        defaultCartItemFilterId:
          type: integer
          description: The ID of the default Cart-Item-Filter for this application.
          example: 3
        enableCampaignStateManagement:
          type: boolean
          description: |
            Indicates whether the campaign staging and revisions feature is enabled for the Application.

            **Important:** After this feature is enabled, it cannot be disabled.
          example: false
        bestPriorPriceSettings:
          $ref: '#/components/schemas/BestPriorPriceSettings'
      required:
        - name
        - timezone
        - currency
    BaseLoyaltyProgram:
      type: object
      properties:
        title:
          type: string
          description: The display title for the Loyalty Program.
          example: Point collection
        description:
          type: string
          description: Description of our Loyalty Program.
          example: Customers collect 10 points per 1$ spent
        subscribedApplications:
          type: array
          description: A list containing the IDs of all applications that are subscribed to this Loyalty Program.
          example:
            - 132
            - 97
          items:
            type: integer
        defaultValidity:
          type: string
          description: |
            The default duration after which new loyalty points should expire. Can be 'unlimited' or a specific time.
            The time format is a number followed by one letter indicating the time unit, like '30s', '40m', '1h', '5D', '7W', or 10M'. These rounding suffixes are also supported:
            - '_D' for rounding down. Can be used as a suffix after 'D', and signifies the start of the day.
            - '_U' for rounding up. Can be used as a suffix after 'D', 'W', and 'M', and signifies the end of the day, week, and month.
          example: 2W_U
        defaultPending:
          type: string
          description: |
            The default duration of the pending time after which points should be valid. Accepted values: 'immediate', 'on_action' or a specific time.
            The time format is a number followed by one letter indicating the time unit, like '30s', '40m', '1h', '5D', '7W', or 10M'. These rounding suffixes are also supported:
            - '_D' for rounding down. Can be used as a suffix after 'D', and signifies the start of the day.
            - '_U' for rounding up. Can be used as a suffix after 'D', 'W', and 'M', and signifies the end of the day, week, and month.
          example: immediate
        allowSubledger:
          type: boolean
          description: Indicates if this program supports subledgers inside the program.
          example: false
        usersPerCardLimit:
          type: integer
          minimum: 0
          example: 111
          description: |
            The max amount of user profiles with whom a card can be shared. This can be set to 0 for no limit.
            This property is only used when `cardBased` is `true`.
        sandbox:
          type: boolean
          description: Indicates if this program is a live or sandbox program. Programs of a given type can only be connected to Applications of the same type.
          title: Sandbox
          example: true
        programJoinPolicy:
          type: string
          enum:
            - not_join
            - points_activated
            - points_earned
          description: |
            The policy that defines when the customer joins the loyalty program.
              - `not_join`: The customer does not join the loyalty program but can still earn and spend loyalty points.

                 **Note**: The customer does not have a program join date.
              - `points_activated`: The customer joins the loyalty program only when their earned loyalty points become active for the first time.
              - `points_earned`: The customer joins the loyalty program when they earn loyalty points for the first time.
        tiersExpirationPolicy:
          type: string
          enum:
            - tier_start_date
            - program_join_date
            - customer_attribute
            - absolute_expiration
          description: |
            The policy that defines how tier expiration, used to reevaluate the customer's current tier, is determined.
             - `tier_start_date`: The tier expiration is relative to when the customer joined the current tier.
             - `program_join_date`: The tier expiration is relative to when the customer joined the loyalty program.
             - `customer_attribute`: The tier expiration is determined by a custom customer attribute.
             - `absolute_expiration`: The tier is reevaluated at the start of each tier cycle. For this policy, it is required to provide a `tierCycleStartDate`.
        tierCycleStartDate:
          type: string
          format: date-time
          description: |
            Timestamp at which the tier cycle starts for all customers in the loyalty program.

            **Note**: This is only required when the tier expiration policy is set to `absolute_expiration`.
          example: '2021-09-12T10:12:42Z'
        tiersExpireIn:
          type: string
          description: |
            The amount of time after which the tier expires and is reevaluated.

            The time format is an **integer** followed by one letter indicating the time unit.
            Examples: `30s`, `40m`, `1h`, `5D`, `7W`, `10M`, `15Y`.

            Available units:

            - `s`: seconds
            - `m`: minutes
            - `h`: hours
            - `D`: days
            - `W`: weeks
            - `M`: months
            - `Y`: years

            You can round certain units up or down:
            - `_D` for rounding down days only. Signifies the start of the day.
            - `_U` for rounding up days, weeks, months and years. Signifies the end of the day, week, month or year.
          example: 27W_U
        tiersDowngradePolicy:
          type: string
          enum:
            - one_down
            - balance_based
          description: |
            The policy that defines how customer tiers are downgraded in the loyalty program after tier reevaluation.
             - `one_down`: If the customer doesn't have enough points to stay in the current tier, they are downgraded by one tier.
             - `balance_based`: The customer's tier is reevaluated based on the amount of active points they have at the moment.
        cardCodeSettings:
          $ref: '#/components/schemas/CodeGeneratorSettings'
        returnPolicy:
          type: string
          enum:
            - only_pending
            - within_balance
            - unlimited
          description: |
            The policy that defines the rollback of points in case of a partially returned, cancelled, or reopened [customer session](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions).
            - `only_pending`: Only pending points can be rolled back.
            - `within_balance`: Available active points can be rolled back if there aren't enough pending points. The active balance of the customer cannot be negative.
            - `unlimited`: Allows negative balance without any limit.
    NewLoyaltyTier:
      type: object
      description: A tier in a loyalty program.
      required:
        - name
        - minPoints
      properties:
        name:
          type: string
          description: The name of the tier.
          example: Gold
        minPoints:
          type: number
          minimum: 0
          maximum: 999999999999.99
          description: The minimum amount of points required to enter the tier.
          example: 300
    LoyaltyTier:
      allOf:
        - $ref: '#/components/schemas/Entity'
        - $ref: '#/components/schemas/LoyaltyProgramEntity'
        - $ref: '#/components/schemas/NewLoyaltyTier'
    LoyaltyProgram:
      allOf:
        - $ref: '#/components/schemas/Entity'
        - $ref: '#/components/schemas/BaseLoyaltyProgram'
        - type: object
          description: A Loyalty Program
          required:
            - id
            - name
            - title
            - description
            - accountID
            - defaultValidity
            - defaultPending
            - subscribedApplications
            - allowSubledger
            - timezone
            - cardBased
            - sandbox
          properties:
            id:
              type: integer
              description: The ID of loyalty program.
              example: 139
            accountID:
              type: integer
              description: The ID of the Talon.One account that owns this program.
              example: 1
            name:
              type: string
              description: The internal name for the Loyalty Program. This is an immutable value.
              example: my_program
            tiers:
              type: array
              description: The tiers in this loyalty program.
              items:
                $ref: '#/components/schemas/LoyaltyTier'
              example:
                - name: Gold
                  minPoints: 300
                  id: 3
                  created: '2021-06-10T09:05:27.993483Z'
                  programID: 139
                - name: Silver
                  minPoints: 200
                  id: 2
                  created: '2021-06-10T09:04:59.355258Z'
                  programID: 139
                - name: Bronze
                  minPoints: 100
                  id: 1
                  created: '2021-06-10T09:04:39.355258Z'
                  programID: 139
            timezone:
              type: string
              description: A string containing an IANA timezone descriptor.
              example: Europe/Berlin
              minLength: 1
            cardBased:
              type: boolean
              description: |
                Defines the type of loyalty program:
                - `true`: the program is a card-based.
                - `false`: the program is profile-based.
              default: false
              example: true
            canUpdateTiers:
              type: boolean
              description: |
                `True` if the tier definitions can be updated.
              default: false
              example: true
            canUpdateTierExpirationPolicy:
              type: boolean
              description: |
                `True` if the tier expiration policy can be updated.
              example: true
            canUpgradeToAdvancedTiers:
              type: boolean
              description: |
                `True` if the program can be upgraded to use the `tiersExpireIn` and `tiersDowngradePolicy` properties.
              default: false
              example: true
            canUpdateSubledgers:
              type: boolean
              description: |
                `True` if the `allowSubledger` property can be updated in the loyalty program.
              default: false
              example: true
    Application:
      allOf:
        - $ref: '#/components/schemas/Entity'
        - $ref: '#/components/schemas/MutableEntity'
        - $ref: '#/components/schemas/AccountEntity'
        - $ref: '#/components/schemas/UpdateApplication'
        - type: object
          required:
            - loyaltyPrograms
          properties:
            loyaltyPrograms:
              type: array
              description: An array containing all the loyalty programs to which this application is subscribed.
              items:
                $ref: '#/components/schemas/LoyaltyProgram'
    AudienceIntegrationID:
      type: object
      properties:
        integrationId:
          type: string
          minLength: 1
          maxLength: 1000
          description: The ID of this audience in the third-party integration.
          example: 382370BKDB946
    AchievementProgressWithDefinition:
      allOf:
        - $ref: '#/components/schemas/AchievementProgress'
        - type: object
          required:
            - achievementId
            - name
            - title
            - description
            - achievementRecurrencePolicy
            - achievementActivationPolicy
            - campaignIds
            - referencedByCampaigns
          properties:
            achievementId:
              type: integer
              example: 3
              description: The internal ID of the achievement.
            name:
              type: string
              pattern: ^[a-zA-Z]\w+$
              example: FreeCoffee10Orders
              maxLength: 1000
              minLength: 1
              description: |
                The internal name of the achievement used in API requests.
            title:
              type: string
              description: The display name of the achievement in the Campaign Manager.
              example: 50% off on 50th purchase.
            description:
              type: string
              format: string
              description: The description of the achievement in the Campaign Manager.
              example: 50% off for every 50th purchase in a year.
            campaignId:
              type: integer
              deprecated: true
              description: This property is **deprecated**. Use `campaignIds` (Integration API) or `referencedByCampaigns` (Management API) instead. This field contains the first campaign ID from the related `campaignIds`, and is omitted when `campaignIds` is empty.
              example: 3
            campaignIds:
              type: array
              description: The IDs of the campaigns that reference this achievement, in ascending order.
              items:
                type: integer
              example:
                - 1
                - 14
                - 27
            referencedByCampaigns:
              type: array
              description: The campaigns that reference this achievement, in ascending order of their `id`.
              items:
                $ref: '#/components/schemas/CampaignReference'
            target:
              type: number
              example: 10
              description: The required number of actions or the transactional milestone to complete the achievement.
            achievementRecurrencePolicy:
              type: string
              enum:
                - no_recurrence
                - on_expiration
                - on_completion
              example: no_recurrence
              description: |
                The policy that determines if and how the achievement recurs.
                - `no_recurrence`: The achievement can be completed only once.
                - `on_expiration`: The achievement resets after it expires and becomes available again.
                - `on_completion`: When the customer progress status reaches `completed`, the achievement resets and becomes available again.
            achievementActivationPolicy:
              type: string
              enum:
                - user_action
                - fixed_schedule
              example: fixed_schedule
              description: |
                The policy that determines how the achievement starts, ends, or resets.
                - `user_action`: The achievement ends or resets relative to when the customer started the achievement.
                - `fixed_schedule`: The achievement starts, ends, or resets for all customers following a fixed schedule.
            achievementFixedStartDate:
              type: string
              format: date-time
              example: 2024-01-15T15:04:05Z07:00
              description: |
                The achievement's start date when `achievementActivationPolicy` is equal to `fixed_schedule`.

                **Note:** It is an RFC3339 timestamp string.
            achievementEndDate:
              type: string
              format: date-time
              example: 2024-02-15T15:04:05Z07:00
              description: |
                The achievement's end date. If defined, customers cannot participate in the achievement after this date.

                **Note:** It is an RFC3339 timestamp string.
            achievementAllowRollbackAfterCompletion:
              type: boolean
              description: When `true`, customer progress can be rolled back in completed achievements.
              example: false
    TimePoint:
      type: object
      required:
        - hour
        - minute
        - second
      description: |
        The absolute duration after which the achievement ends and resets for a particular customer profile.

        **Note**: The duration follows the time zone of the Application this achievement belongs to.
      properties:
        month:
          type: integer
          minimum: 1
          maximum: 12
          description: |
            The achievement ends and resets in this month.

            **Note**: Only applicable if the period is set to `Y`.
          example: 11
        dayOfMonth:
          type: integer
          minimum: 1
          maximum: 31
          description: |
            The achievement ends and resets on this day of the month.

            **Note**: Only applicable if the period is set to `Y` or `M`.
          example: 23
        dayOfWeek:
          type: integer
          minimum: 1
          maximum: 7
          description: |
            The achievement ends and resets on this day of the week. `1` represents `Monday` and `7` represents `Sunday`.

            **Note**: Only applicable if the period is set to `W`.
        hour:
          type: integer
          description: The achievement ends and resets at this hour.
          example: 23
        minute:
          type: integer
          description: The achievement ends and resets at this minute.
          example: 59
        second:
          type: integer
          description: The achievement ends and resets at this second.
          example: 59
      example:
        month: 11
        dayOfMonth: 23
        hour: 23
        minute: 59
        second: 59
    AchievementBase:
      type: object
      properties:
        name:
          type: string
          pattern: ^[a-zA-Z]\w+$
          example: Order50Discount
          maxLength: 1000
          minLength: 1
          description: |
            The internal name of the achievement used in API requests.

            **Note**: The name should start with a letter. This cannot be changed after the achievement has been created.
        title:
          type: string
          description: The display name for the achievement in the Campaign Manager.
          example: 50% off on 50th purchase.
        description:
          type: string
          format: string
          description: A description of the achievement.
          example: 50% off for every 50th purchase in a year.
        target:
          type: number
          description: The required number of actions or the transactional milestone to complete the achievement.
          example: 50
        period:
          type: string
          description: |
            The relative duration after which the achievement ends and resets for a particular customer profile.

            **Note**: The `period` does not start when the achievement is created.

            The period is a **positive real number** followed by one letter indicating the time unit.

            Examples: `30s`, `40m`, `1h`, `5D`, `7W`, `10M`, `15Y`.

            Available units:

            - `s`: seconds
            - `m`: minutes
            - `h`: hours
            - `D`: days
            - `W`: weeks
            - `M`: months
            - `Y`: years

            You can also round certain units down to the beginning of period and up to the end of period.:
            - `_D` for rounding down days only. Signifies the start of the day.
            Example: `30D_D`
            - `_U` for rounding up days, weeks, months and years. Signifies the end of the day, week, month or year.
            Example: `23W_U`

            **Note**: You can either use the round down and round up option or set an absolute period.
          example: 1Y
        periodEndOverride:
          $ref: '#/components/schemas/TimePoint'
          deprecated: true
        recurrencePolicy:
          type: string
          enum:
            - no_recurrence
            - on_expiration
            - on_completion
          example: no_recurrence
          description: |
            The policy that determines if and how the achievement recurs.
            - `no_recurrence`: The achievement can be completed only once.
            - `on_expiration`: The achievement resets after it expires and becomes available again.
            - `on_completion`: When the customer progress status reaches `completed`, the achievement resets and becomes available again.
        activationPolicy:
          type: string
          enum:
            - user_action
            - fixed_schedule
          example: fixed_schedule
          description: |
            The policy that determines how the achievement starts, ends, or resets.
            - `user_action`: The achievement ends or resets relative to when the customer started the achievement.
            - `fixed_schedule`: The achievement starts, ends, or resets for all customers following a fixed schedule.
        fixedStartDate:
          type: string
          format: date-time
          example: 2024-01-15T15:04:05Z07:00
          description: |
            The achievement's start date when `activationPolicy` is set to `fixed_schedule`.

            **Note:** It must be an RFC3339 timestamp string.
        endDate:
          type: string
          format: date-time
          example: 2024-02-15T15:04:05Z07:00
          description: |
            The achievement's end date. If defined, customers cannot participate in the achievement after this date.

            **Note:** It must be an RFC3339 timestamp string.
        allowRollbackAfterCompletion:
          type: boolean
          description: When `true`, customer progress can be rolled back in completed achievements.
          example: false
    CreateAchievement:
      allOf:
        - $ref: '#/components/schemas/AchievementBase'
        - type: object
          required:
            - name
            - title
            - description
            - target
    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
    ProjectedTier:
      type: object
      required:
        - projectedActivePoints
      properties:
        projectedActivePoints:
          type: number
          description: The active points of the customer when their current tier expires.
          example: 198
        stayInTierPoints:
          type: number
          description: |
            The number of points the customer needs to stay in the current tier.

            **Note**: This is included in the response when the customer is projected to be downgraded.
          example: 2
        projectedTierName:
          type: string
          description: The name of the tier the user will enter once their current tier expires.
          example: Tier 1
    LoyaltyBalanceWithTier:
      allOf:
        - $ref: '#/components/schemas/LoyaltyBalance'
        - type: object
          properties:
            currentTier:
              $ref: '#/components/schemas/Tier'
              description: Customer's current tier.
            projectedTier:
              $ref: '#/components/schemas/ProjectedTier'
            pointsToNextTier:
              type: number
              description: The number of points required to move up a tier.
              example: 20
            nextTierName:
              type: string
              description: |
                The name of the next higher tier level in the loyalty program.

                **Note**:
                - Returns `null` if the customer has reached the highest available tier.
                - Returns the lowest level tier name if the customer is not currently assigned to any tier.
              example: Silver
    LoyaltyBalancesWithTiers:
      type: object
      description: List of loyalty balances for a ledger and its subledgers.
      properties:
        balance:
          $ref: '#/components/schemas/LoyaltyBalanceWithTier'
          title: Loyalty points balance of a ledger
        subledgerBalances:
          type: object
          description: Map of the loyalty balances of the subledgers of a ledger.
          additionalProperties:
            $ref: '#/components/schemas/LoyaltyBalanceWithTier'
          example:
            mysubledger:
              activePoints: 286
              pendingPoints: 50
              spentPoints: 150
              expiredPoints: 25
              negativePoints: 0
    UpdateLoyaltyCardRequest:
      type: object
      additionalProperties: false
      properties:
        status:
          type: string
          description: |
            Status of the loyalty card. Can be `active` or `inactive`.
          example: active
    LoyaltyLedgerEntryFlags:
      type: object
      description: A map of flags providing additional details about the entry.
      properties:
        createsNegativeBalance:
          type: boolean
          description: Set to true if the entry creates negative balance.
    LedgerTransactionLogEntryIntegrationAPI:
      type: object
      description: Log entry for a given loyalty profile transaction.
      required:
        - transactionUUID
        - created
        - programId
        - type
        - name
        - startDate
        - expiryDate
        - subledgerId
        - amount
        - id
      properties:
        transactionUUID:
          type: string
          description: Unique identifier of the transaction in the UUID format.
          example: ce59f12a-f53b-4014-a745-636d93f2bd3f
        created:
          type: string
          format: date-time
          description: Date and time the loyalty transaction occurred.
          example: 2022-01-02T15:04:05Z07:00
        programId:
          type: integer
          description: ID of the loyalty program.
          example: 324
        customerSessionId:
          type: string
          description: ID of the customer session where the transaction occurred.
          maxLength: 255
          example: 05c2da0d-48fa-4aa1-b629-898f58f1584d
        storeIntegrationId:
          type: string
          minLength: 1
          maxLength: 1000
          description: The integration ID of the store where the transaction occurred. Only set for transactions created by a customer session or event that referenced a store.
          example: STORE-001
        type:
          type: string
          enum:
            - addition
            - subtraction
          description: |
            Type of transaction. Possible values:
              - `addition`: Signifies added points.
              - `subtraction`: Signifies deducted points.
          maxLength: 255
          example: addition
        name:
          type: string
          description: Name or reason of the loyalty ledger transaction.
          maxLength: 255
          example: Reward 10% points of a purchase's current total
        startDate:
          type: string
          description: |
            When points become active. Possible values:
              - `immediate`: Points are immediately active.
              - `on_action`: Points become active based on the customer's action.
              - a timestamp value: Points become active at a given date and time.
          maxLength: 64
          example: 2022-01-02T15:04:05Z07:00
        expiryDate:
          type: string
          description: |
            Date when points expire. Possible values are:
              - `unlimited`: Points have no expiration date.
              - `timestamp value`: Points expire on the given date.
          example: 2022-08-02T15:04:05Z07:00
        subledgerId:
          type: string
          description: ID of the subledger.
          maxLength: 64
          example: sub-123
        amount:
          type: number
          description: Amount of loyalty points added or deducted in the transaction.
          example: 10.25
        id:
          type: integer
          description: ID of the loyalty ledger transaction.
          example: 123
        rulesetId:
          type: integer
          description: The ID of the ruleset containing the rule that triggered this effect.
          example: 11
        ruleName:
          type: string
          description: The name of the rule that triggered this effect.
          example: Add 2 points
        flags:
          $ref: '#/components/schemas/LoyaltyLedgerEntryFlags'
          description: The flags of the transaction, when applicable. The `createsNegativeBalance`  flag indicates whether the transaction results in a negative balance.
        validityDuration:
          type: string
          description: |
            The duration for which the points remain active, relative to the activation date.

            **Note**: This only applies to points for which `awaitsActivation` is `true` and `expiryDate` is not set.
          example: 30D
    LedgerTransactionLogEntryManagementAPI:
      allOf:
        - $ref: '#/components/schemas/LedgerTransactionLogEntryIntegrationAPI'
        - type: object
          properties:
            referenceTransactionUUIDs:
              type: array
              description: |
                UUIDs of the addition transactions from which this subtraction deducted
                loyalty points. Only returned when `includeReferences` is `true` and
                the transaction has references.
              items:
                type: string
              example:
                - a36bca2c-a24a-41ce-9f69-314d20c3373d
                - 7a8e2d7b-521f-48f2-bc4d-67c01f9cf27b
    NewCampaign:
      allOf:
        - $ref: '#/components/schemas/BaseCampaign'
        - type: object
          properties:
            evaluationGroupId:
              type: integer
              title: Evaluation Group ID
              example: 2
              description: The ID of the campaign evaluation group the campaign belongs to.
    IdentifiableEntity:
      type: object
      required:
        - id
      properties:
        id:
          type: integer
          description: Unique ID for this entity. Not to be confused with the Integration ID, which is set by your integration layer and used in most endpoints.
          example: 6
    RevisionActivation:
      type: object
      properties:
        activateAt:
          type: string
          format: date-time
          description: Timestamp when the revision will be activated.
          example: '2026-10-08T09:30:00Z'
    NewRevisionVersion:
      type: object
      properties:
        name:
          type: string
          title: Campaign Name
          description: A user-facing name for this campaign.
          minLength: 1
          example: Summer promotions
        startTime:
          type:
            - string
            - 'null'
          format: date-time
          description: Timestamp when the campaign will become active.
          example: '2021-07-20T22:00:00Z'
        endTime:
          type:
            - string
            - 'null'
          format: date-time
          description: Timestamp when the campaign will become inactive.
          example: '2021-09-22T22:00:00Z'
        attributes:
          type: object
          description: Arbitrary properties associated with this campaign.
        description:
          type:
            - string
            - 'null'
          title: Campaign Description
          description: A detailed description of the campaign.
          example: Campaign for all summer 2021 promotions
        activeRulesetId:
          type:
            - integer
            - 'null'
          description: The ID of the ruleset this campaign will use.
          example: 5
        tags:
          type: array
          description: A list of tags for the campaign.
          maxItems: 50
          items:
            type: string
            minLength: 1
            maxLength: 50
        couponSettings:
          $ref: '#/components/schemas/CodeGeneratorSettings'
        referralSettings:
          $ref: '#/components/schemas/CodeGeneratorSettings'
        limits:
          type: array
          description: The set of limits that will operate for this campaign version.
          items:
            $ref: '#/components/schemas/LimitConfig'
        reevaluateOnReturn:
          type: boolean
          title: Reevaluate on return
          description: Indicates whether this campaign should be reevaluated when a customer returns an item.
          example: true
        features:
          type: array
          description: A list of features for the campaign.
          items:
            type: string
            enum:
              - coupons
              - referrals
              - loyalty
              - giveaways
              - strikethrough
              - achievements
              - advancedEvents
        couponAttributes:
          type: object
          description: Arbitrary properties associated with coupons in this campaign.
    RevisionVersion:
      allOf:
        - $ref: '#/components/schemas/IdentifiableEntity'
        - type: object
          required:
            - accountId
            - applicationId
            - campaignId
            - created
            - createdBy
            - revisionId
            - version
          properties:
            accountId:
              type: integer
              description: The ID of the account that owns this entity.
              example: 3886
            applicationId:
              type: integer
              description: The ID of the Application that owns this entity.
              example: 42
            campaignId:
              type: integer
              description: The ID of the campaign that the revision was created from.
              example: 18
            created:
              type: string
              format: date-time
              description: Timestamp when the revision was created.
              example: '2026-10-01T08:00:00Z'
            createdBy:
              type: integer
              description: The ID of the user who created this revision.
              example: 134
            revisionId:
              type: integer
              description: The ID of the revision.
              example: 6
            version:
              type: integer
              description: |
                Incrementing number representing how many revisions have been activated on this campaign. Starts from `0` for a new campaign.
        - $ref: '#/components/schemas/NewRevisionVersion'
    Revision:
      allOf:
        - $ref: '#/components/schemas/IdentifiableEntity'
        - $ref: '#/components/schemas/RevisionActivation'
        - type: object
          required:
            - created
            - createdBy
            - accountId
            - applicationId
            - campaignId
          properties:
            accountId:
              type: integer
              description: The ID of the account that owns this entity.
              example: 3886
            applicationId:
              type: integer
              description: The ID of the Application that owns this entity.
              example: 42
            campaignId:
              type: integer
              description: The ID of the campaign that the revision was created from.
              example: 18
            created:
              type: string
              format: date-time
              description: Timestamp when the revision was created.
              example: '2026-10-01T08:00:00Z'
            createdBy:
              type: integer
              description: The ID of the user who created this revision.
              example: 134
            activatedAt:
              type: string
              format: date-time
              description: Timestamp when this revision was activated.
              example: '2026-10-08T09:30:00Z'
            activatedBy:
              type: integer
              description: The ID of the user who activated this revision.
              example: 334
            currentVersion:
              $ref: '#/components/schemas/RevisionVersion'
              description: The current version of this revision.
              example:
                id: 6
                accountId: 3886
                applicationId: 42
                campaignId: 18
                created: '2026-10-01T08:00:00Z'
                createdBy: 134
                revisionId: 6
                version: 1
                name: Summer promotions
    UpdateCampaign:
      type: object
      properties:
        name:
          type: string
          title: Campaign Name
          description: A user-facing name for this campaign.
          minLength: 1
          example: Summer promotions
        description:
          type: string
          title: Campaign Description
          description: A detailed description of the campaign.
          example: Campaign for all summer 2021 promotions
        startTime:
          type: string
          format: date-time
          description: Timestamp when the campaign will become active.
          example: '2021-07-20T22:00:00Z'
        endTime:
          type: string
          format: date-time
          description: Timestamp when the campaign will become inactive.
          example: '2021-10-01T02:00:00Z'
        attributes:
          type: object
          description: Arbitrary properties associated with this campaign.
          example:
            myattribute: 20
        state:
          type: string
          enum:
            - enabled
            - disabled
            - archived
          default: enabled
          example: disabled
          description: |
            A disabled or archived campaign is not evaluated for rules or coupons.
        activeRulesetId:
          type: integer
          description: |
            [ID of Ruleset](https://docs.talon.one/management-api#tag/Campaigns/operation/getRulesets) this
            campaign applies on customer session evaluation.
          example: 2
        tags:
          type: array
          description: A list of tags for the campaign.
          maxItems: 50
          example:
            - Summer
            - Shoes
          items:
            type: string
            minLength: 1
            maxLength: 50
        reevaluateOnReturn:
          type: boolean
          title: Reevaluate on return
          description: Indicates whether this campaign should be reevaluated when a customer returns an item.
          example: true
        features:
          type: array
          description: A list of features for the campaign.
          items:
            type: string
            enum:
              - coupons
              - referrals
              - loyalty
              - giveaways
              - strikethrough
              - achievements
              - advancedEvents
          example:
            - coupons
            - loyalty
        couponSettings:
          $ref: '#/components/schemas/CodeGeneratorSettings'
        referralSettings:
          $ref: '#/components/schemas/CodeGeneratorSettings'
        limits:
          type: array
          description: The set of limits that will operate for this campaign.
          items:
            $ref: '#/components/schemas/LimitConfig'
        campaignGroups:
          type: array
          description: |
            The IDs of the [campaign groups](https://docs.talon.one/docs/product/account/account-settings/managing-campaign-groups) this campaign belongs to.
          example:
            - 1
            - 3
          items:
            type: integer
        evaluationGroupId:
          type: integer
          example: 2
          description: The ID of the campaign evaluation group the campaign belongs to.
        type:
          type: string
          enum:
            - cartItem
            - advanced
          default: advanced
          example: advanced
          description: |
            The campaign type. Possible type values:
              - `cartItem`: Type of campaign that can apply effects only to cart items.
              - `advanced`: Type of campaign that can apply effects to customer sessions and cart items.
        linkedStoreIds:
          type: array
          description: |
            A list of store IDs that you want to link to the campaign.

            > [!note] **Note**
            > - Campaigns with linked store IDs will only be evaluated when there is a
            >   [customer session update](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2)
            >   that references a linked store.
            > - If you linked stores to the campaign by uploading a CSV file, you cannot use this property and it should be empty.
            > - Use of this property is limited to 50 stores. To link more than 50 stores, upload them via a CSV file.
          items:
            type: integer
          example:
            - 1
            - 2
            - 3
        couponAttributes:
          type: object
          description: Arbitrary properties associated with coupons in this campaign.
      required:
        - name
        - tags
        - limits
        - features
    CampaignCopy:
      type: object
      required:
        - applicationIds
      properties:
        name:
          type: string
          description: Name of the copied campaign (Defaults to "Copy of original campaign name").
          example: Copy of Summer promotions
        applicationIds:
          type: array
          description: Application IDs of the applications to which a campaign should be copied to.
          items:
            type: integer
          example:
            - 1
            - 2
            - 3
        description:
          type: string
          title: Campaign Description
          description: A detailed description of the campaign.
          example: Campaign for all summer 2021 promotions
        startTime:
          type: string
          format: date-time
          description: Timestamp when the campaign will become active.
          example: '2021-06-01T09:00:27.993483Z'
        endTime:
          type: string
          format: date-time
          description: Timestamp when the campaign will become inactive.
          example: '2021-09-10T01:00:00.993483Z'
        tags:
          type: array
          description: A list of tags for the campaign.
          maxItems: 50
          items:
            type: string
            minLength: 1
            maxLength: 50
          example:
            - Summer
            - Shoes
        evaluationGroupId:
          type: integer
          example: 2
          description: The ID of the campaign evaluation group the campaign belongs to.
    FuncArgDef:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - string
            - boolean
            - number
            - time
            - (list string)
            - (list number)
          description: The type of value this argument expects.
          minLength: 1
        description:
          type: string
          description: A campaigner-friendly description of the argument, this will also be shown in the rule editor.
    TemplateArgDef:
      allOf:
        - $ref: '#/components/schemas/FuncArgDef'
        - type: object
          required:
            - ui
            - title
          properties:
            title:
              type: string
              description: A campaigner friendly name for the argument, this will be shown in the rule editor.
              minLength: 1
            ui:
              type: object
              description: Arbitrary metadata that may be used to render an input for this argument.
            key:
              type: string
              description: The identifier for the associated value within the JSON object.
            picklistID:
              type: integer
              description: ID of the picklist linked to a template.
            restrictedByPicklist:
              type: boolean
              description: Whether or not this attribute's value is restricted by picklist (`picklist` property)
    NewWebhook:
      type: object
      required:
        - title
        - verb
        - url
        - headers
        - params
        - draft
        - enabled
        - applicationIds
      properties:
        applicationIds:
          type: array
          description: |
            The IDs of the Applications in which this webhook is available.
            An empty array means the webhook is available in `All Applications`.
          items:
            type: integer
        title:
          type: string
          pattern: ^[A-Za-z][A-Za-z0-9_.!~*'() -]*$
          description: Name or title for this webhook.
          example: Send message
        description:
          type: string
          description: A description of the webhook.
          example: A webhook to send a coupon to the user.
        draft:
          type: boolean
          description: Indicates if the webhook is a draft.
          example: false
        verb:
          type: string
          enum:
            - POST
            - PUT
            - GET
            - DELETE
            - PATCH
          description: API method for this webhook.
          example: POST
        url:
          type: string
          description: API URL (supports templating using parameters) for this webhook.
          example: www.my-company.com/my-endpoint-name
        headers:
          type: array
          description: List of API HTTP headers for this webhook.
          items:
            type: string
            pattern: ^([^:,]*):([^]*|[^,]*)$
          example:
            - '{"Authorization": "Basic bmF2ZWVua3VtYXIU="}'
            - '{"Content-Type": "application/json"}'
        payload:
          type: string
          description: API payload (supports templating using parameters) for this webhook.
          example: |-
            {
            	"message": "${message}"
            }
        params:
          type: array
          description: Array of template argument definitions.
          items:
            $ref: '#/components/schemas/TemplateArgDef'
          example: []
        enabled:
          type: boolean
          description: Enables or disables webhook from showing in the Rule Builder.
          example: true
        authenticationId:
          type: integer
          description: The ID of the credential that this webhook is using.
          example: 1
    Webhook:
      allOf:
        - $ref: '#/components/schemas/Entity'
        - $ref: '#/components/schemas/MutableEntity'
        - $ref: '#/components/schemas/NewWebhook'
    LabelTargetNone:
      type: object
      description: Target type when no specific audience is selected. Targets all customers who are not members of an audience.
      properties:
        type:
          type: string
          enum:
            - NONE
      required:
        - type
    AudienceReference:
      allOf:
        - type: object
          required:
            - id
          properties:
            id:
              type: integer
              description: The ID of the audience.
            integration:
              type: string
              description: The third-party integration of the audience.
        - $ref: '#/components/schemas/AudienceIntegrationID'
    LabelTargetAudience:
      type: object
      description: |
        Target type when a specific audience is selected.
      properties:
        type:
          type: string
          enum:
            - AUDIENCE
        audience:
          $ref: '#/components/schemas/AudienceReference'
      required:
        - type
        - audience
    LabelTarget:
      type: object
      oneOf:
        - $ref: '#/components/schemas/LabelTargetNone'
        - $ref: '#/components/schemas/LabelTargetAudience'
    CampaignSearch:
      type: object
      required:
        - attributes
      properties:
        attributes:
          type: object
          description: Properties to match against a campaign. All provided attributes will be exactly matched against campaign attributes.
    Binding:
      type: object
      required:
        - name
        - expression
      properties:
        name:
          type: string
          description: A descriptive name for the value to be bound.
          example: Discount percentage
        type:
          type: string
          description: |
            The kind of binding. Possible values are:
            - `bundle`
            - `cartItemFilter`
            - `subledgerBalance`
            - `templateParameter`
          example: templateParameter
        expression:
          type: array
          description: |
            A Talang expression that is evaluated, and its result is bound to the name of
            the binding. The first element must be one of the functions or operators supported
            by Talang, followed by its arguments. The arguments can be strings, numbers, or
            nested expressions. For example:
            - `["list", "10014", "10015"]` calls the `list` function to build a list of strings.
            - `["+", 2, 0]` uses the `+` operator to add two numbers.
          example:
            - identity
            - 10
          items: {}
        valueType:
          type: string
          description: |
            The data type of the value. One of the following:
            - `string`
            - `number`
            - `boolean`
          example: number
        minValue:
          type: number
          description: The minimum value allowed for this placeholder.
          example: 0
        maxValue:
          type: number
          description: The maximum value allowed for this placeholder.
          example: 19.9
        attributeId:
          type: integer
          title: Attribute ID
          description: Identifier of the attribute attached to the placeholder.
          example: 100
        description:
          type: string
          description: Description of the placeholder field and its value in the template. This text can be shown when creating campaigns from this template.
          example: The percentage discount applied to the cart total.
    Rule:
      type: object
      required:
        - title
        - condition
        - effects
      properties:
        id:
          type: string
          format: uuid
          description: A unique identifier for the rule.
          example: 7fa800a8-ac8d-4792-85dc-c4650dcc8f23
        parentId:
          type: string
          format: uuid
          description: The ID of the rule that was copied to create this rule.
          example: 7fa800a8-ac8d-4792-85dc-c4650dcc8f23
        title:
          type: string
          description: A short description of the rule.
          example: Give discount via coupon
        description:
          type: string
          description: A longer, more detailed description of the rule.
          example: Creates a discount when a coupon is valid
        bindings:
          type: array
          description: An array that provides objects with variable names (name) and talang expressions to whose result they are bound (expression) during rule evaluation. The order of the evaluation is decided by the position in the array.
          items:
            $ref: '#/components/schemas/Binding'
        condition:
          type: array
          description: A Talang expression that will be evaluated in the context of the given event.
          minItems: 1
          example:
            - and
            - - couponValid
          items: {}
        effects:
          type: array
          description: An array of effectful Talang expressions in arrays that will be evaluated when a rule matches.
          items:
            type: array
            items: {}
          example:
            - catch
            - - noop
            - - setDiscount
              - 10% off
              - - '*'
                - - '.'
                  - Session
                  - Total
                - - /
                  - 10
                  - 100
    NewRuleset:
      type: object
      required:
        - rules
        - bindings
      properties:
        rules:
          type: array
          description: Set of rules to apply.
          items:
            $ref: '#/components/schemas/Rule'
        strikethroughRules:
          type: array
          description: Set of rules to apply for strikethrough.
          items:
            $ref: '#/components/schemas/Rule'
        bindings:
          type: array
          description: An array that provides objects with variable names (name) and talang expressions to whose result they are bound (expression) during rule evaluation. The order of the evaluation is decided by the position in the array.
          items:
            $ref: '#/components/schemas/Binding'
          example: []
        rbVersion:
          type: string
          description: The version of the rulebuilder used to create this ruleset.
          example: v2
        activate:
          type: boolean
          description: Indicates whether this created ruleset should be activated for the campaign that owns it.
          example: true
    Ruleset:
      allOf:
        - $ref: '#/components/schemas/Entity'
        - $ref: '#/components/schemas/UserEntity'
        - $ref: '#/components/schemas/NewRuleset'
        - type: object
          properties:
            campaignId:
              type: integer
              title: Campaign ID
              description: The ID of the campaign that owns this entity.
              example: 320
            templateId:
              type: integer
              title: Campaign Template ID
              description: The ID of the campaign template that owns this entity.
              example: 3
            activatedAt:
              type: string
              format: date-time
              description: Timestamp indicating when this Ruleset was activated.
    BaseBlock:
      type: object
      title: BaseBlock
      description: Common properties shared by all block types.
      required:
        - type
      properties:
        id:
          type: string
          readOnly: true
          description: Unique identifier for this block.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        type:
          type: string
          description: Identifies the block variant and determines which additional properties are present in it.
        tags:
          type: array
          readOnly: true
          description: Semantic labels attached to this block.
          items:
            type: string
    Block:
      description: Describes a part of the logic of the rule.
      oneOf:
        - $ref: '#/components/schemas/GroupBlock'
        - $ref: '#/components/schemas/AwardDiscountBlock'
        - $ref: '#/components/schemas/PassthroughBlock'
        - $ref: '#/components/schemas/ShowNotificationBlock'
        - $ref: '#/components/schemas/AwardItemBlock'
        - $ref: '#/components/schemas/AwardGiveawayBlock'
        - $ref: '#/components/schemas/CheckAttributeBlock'
        - $ref: '#/components/schemas/CheckAudienceBlock'
        - $ref: '#/components/schemas/CheckLoyaltyBalanceBlock'
        - $ref: '#/components/schemas/CheckCouponBlock'
        - $ref: '#/components/schemas/CheckReferralBlock'
        - $ref: '#/components/schemas/UpdateAudienceMembershipBlock'
        - $ref: '#/components/schemas/UpdateAchievementProgressBlock'
        - $ref: '#/components/schemas/UpdateAttributeValueBlock'
        - $ref: '#/components/schemas/TriggerWebhookBlock'
        - $ref: '#/components/schemas/TriggerCustomEffectBlock'
        - $ref: '#/components/schemas/CheckEventBlock'
        - $ref: '#/components/schemas/CheckAchievementBlock'
        - $ref: '#/components/schemas/CheckBudgetBlock'
        - $ref: '#/components/schemas/CreateCouponBlock'
        - $ref: '#/components/schemas/CreateReferralBlock'
        - $ref: '#/components/schemas/ReserveCouponBlock'
        - $ref: '#/components/schemas/UpdateLoyaltyPointsExpiryBlock'
        - $ref: '#/components/schemas/CheckLoyaltyCardBlock'
        - $ref: '#/components/schemas/CheckTierBlock'
        - $ref: '#/components/schemas/AwardLoyaltyPointsBlock'
        - $ref: '#/components/schemas/RedeemLoyaltyPointsBlock'
      discriminator:
        propertyName: type
        mapping:
          group: '#/components/schemas/GroupBlock'
          awardDiscount: '#/components/schemas/AwardDiscountBlock'
          passthrough: '#/components/schemas/PassthroughBlock'
          showNotification: '#/components/schemas/ShowNotificationBlock'
          awardItem: '#/components/schemas/AwardItemBlock'
          awardGiveaway: '#/components/schemas/AwardGiveawayBlock'
          triggerWebhook: '#/components/schemas/TriggerWebhookBlock'
          checkAttribute: '#/components/schemas/CheckAttributeBlock'
          checkAudience: '#/components/schemas/CheckAudienceBlock'
          checkLoyaltyBalance: '#/components/schemas/CheckLoyaltyBalanceBlock'
          checkCoupon: '#/components/schemas/CheckCouponBlock'
          checkReferral: '#/components/schemas/CheckReferralBlock'
          updateAudienceMembership: '#/components/schemas/UpdateAudienceMembershipBlock'
          updateAchievementProgress: '#/components/schemas/UpdateAchievementProgressBlock'
          updateAttributeValue: '#/components/schemas/UpdateAttributeValueBlock'
          triggerCustomEffect: '#/components/schemas/TriggerCustomEffectBlock'
          checkEvent: '#/components/schemas/CheckEventBlock'
          checkAchievement: '#/components/schemas/CheckAchievementBlock'
          checkBudget: '#/components/schemas/CheckBudgetBlock'
          createCoupon: '#/components/schemas/CreateCouponBlock'
          createReferral: '#/components/schemas/CreateReferralBlock'
          reserveCoupon: '#/components/schemas/ReserveCouponBlock'
          updateLoyaltyPointsExpiry: '#/components/schemas/UpdateLoyaltyPointsExpiryBlock'
          checkLoyaltyCard: '#/components/schemas/CheckLoyaltyCardBlock'
          checkTier: '#/components/schemas/CheckTierBlock'
          awardLoyaltyPoints: '#/components/schemas/AwardLoyaltyPointsBlock'
          redeemLoyaltyPoints: '#/components/schemas/RedeemLoyaltyPointsBlock'
    GroupBlock:
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
        - type: object
          title: GroupBlock
          description: A structural combinator block that groups child blocks using a logical operator. Evaluates to true when its operator condition is satisfied across all child blocks.
          required:
            - operator
            - blocks
          properties:
            operator:
              type: string
              enum:
                - all
                - atLeastOne
                - none
              description: Logical operator applied across child blocks. `all` requires every child to pass, `atLeastOne` requires at least one, `none` requires all to fail.
            blocks:
              type: array
              description: Child blocks evaluated according to the operator.
              items:
                $ref: '#/components/schemas/Block'
            onFailure:
              type: array
              description: Blocks evaluated when this block fails or returns false.
              items:
                $ref: '#/components/schemas/Block'
            onError:
              type: object
              description: Named error handlers evaluated when a specific error occurs.
              additionalProperties:
                type: array
                items:
                  $ref: '#/components/schemas/Block'
    AwardDiscountCartTarget:
      type: object
      title: AwardDiscountCartTarget
      description: Applies the discount to the entire cart as a single unit.
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - cart
          description: A target discriminator of type `cart`.
    AwardDiscountAllItemsTarget:
      type: object
      title: AwardDiscountAllItemsTarget
      description: Applies the discount across all cart items.
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - allItems
          description: A target discriminator of type `allItems`.
        prorated:
          type: boolean
          description: Whether to distribute the discount proportionally across the targeted items.
          example: true
    AwardDiscountGlobalFilterTarget:
      type: object
      title: AwardDiscountGlobalFilterTarget
      description: Applies the discount to items matched by a named Application-level cart-item filter.
      required:
        - type
        - name
      properties:
        type:
          type: string
          enum:
            - globalFilter
          description: A target discriminator of type `globalFilter`.
        name:
          type: string
          description: The name of the Application-level cart-item filter the discount targets.
          example: PremiumItems
        prorated:
          type: boolean
          description: Whether to distribute the discount proportionally across the matched items.
          example: false
    AwardDiscountSelectorTarget:
      type: object
      title: AwardDiscountSelectorTarget
      description: Applies the discount to items matched by a named selector binding.
      required:
        - type
        - name
      properties:
        type:
          type: string
          enum:
            - selector
          description: A target discriminator of type `selector`.
        name:
          type: string
          description: The name of the selector binding the discount targets.
          example: ElectronicsItems
        prorated:
          type: boolean
          description: Whether to distribute the discount proportionally across the selected items.
          example: false
    AwardDiscountBundleItemByIndex:
      type: object
      title: AwardDiscountBundleItemByIndex
      description: Identifies a bundle slot by its zero-based index within the bundle.
      required:
        - type
        - value
      properties:
        type:
          type: string
          enum:
            - byIndex
          description: A bundle-item selector of type `byIndex`.
        value:
          type: integer
          format: int64
          description: The zero-based index of the slot within the bundle.
          example: 0
    AwardDiscountBundleItemByAttribute:
      type: object
      title: AwardDiscountBundleItemByAttribute
      description: Identifies a bundle slot by ranking items by a per-item attribute expression and picking the highest- or lowest-ranked one.
      required:
        - type
        - attribute
        - direction
      properties:
        type:
          type: string
          enum:
            - byAttribute
          description: A bundle-item selector of type `byAttribute`.
        attribute:
          type: string
          description: A per-item attribute expression used to rank bundle items.
          example: '{{$Item.Price}}'
        direction:
          type: string
          enum:
            - highest
            - lowest
          description: Ranking direction. `highest` picks the item with the largest attribute value, `lowest` the smallest.
          example: highest
    AwardDiscountBundleItem:
      description: Selects which slot inside a bundle a discount applies to. The `type` field picks the selection mode.
      oneOf:
        - $ref: '#/components/schemas/AwardDiscountBundleItemByIndex'
        - $ref: '#/components/schemas/AwardDiscountBundleItemByAttribute'
      discriminator:
        propertyName: type
        mapping:
          byIndex: '#/components/schemas/AwardDiscountBundleItemByIndex'
          byAttribute: '#/components/schemas/AwardDiscountBundleItemByAttribute'
    AwardDiscountBundleTarget:
      type: object
      title: AwardDiscountBundleTarget
      description: Applies the discount to items belonging to a named bundle.
      required:
        - type
        - name
      properties:
        type:
          type: string
          enum:
            - bundle
          description: A target discriminator of type `bundle`.
        name:
          type: string
          description: Name of the bundle binding the discount targets.
          example: BogoBundle
        item:
          $ref: '#/components/schemas/AwardDiscountBundleItem'
        prorated:
          type: boolean
          description: Whether to distribute the discount proportionally across the bundle's items.
          example: false
    AdditionalCostReference:
      type: object
      title: AdditionalCostReference
      description: Identifies an additional cost referenced from a rule.
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
          description: The internal identifier of the additional cost.
          example: 42
        name:
          type: string
          description: The additional cost name as used in API requests.
          example: shipping
        title:
          type: string
          description: The human-readable title of the additional cost.
          example: Shipping
    AwardDiscountAdditionalCostTarget:
      type: object
      title: AwardDiscountAdditionalCostTarget
      description: Applies the discount to an additional cost. The `target` field determines which subset of cart items the additional cost contribution is applied to.
      required:
        - type
        - additionalCost
        - target
      properties:
        type:
          type: string
          enum:
            - additionalCost
          description: A target discriminator of type `additionalCost`.
        additionalCost:
          $ref: '#/components/schemas/AdditionalCostReference'
        target:
          description: A subset of cart items whose additional cost the discount applies to. Cannot be another `additionalCost` target.
          oneOf:
            - $ref: '#/components/schemas/AwardDiscountCartTarget'
            - $ref: '#/components/schemas/AwardDiscountAllItemsTarget'
            - $ref: '#/components/schemas/AwardDiscountGlobalFilterTarget'
            - $ref: '#/components/schemas/AwardDiscountSelectorTarget'
          discriminator:
            propertyName: type
            mapping:
              cart: '#/components/schemas/AwardDiscountCartTarget'
              allItems: '#/components/schemas/AwardDiscountAllItemsTarget'
              globalFilter: '#/components/schemas/AwardDiscountGlobalFilterTarget'
              selector: '#/components/schemas/AwardDiscountSelectorTarget'
    AwardDiscountTarget:
      description: Identifies the scope a discount applies to. The `type` field selects the concrete target variant.
      oneOf:
        - $ref: '#/components/schemas/AwardDiscountCartTarget'
        - $ref: '#/components/schemas/AwardDiscountAllItemsTarget'
        - $ref: '#/components/schemas/AwardDiscountGlobalFilterTarget'
        - $ref: '#/components/schemas/AwardDiscountSelectorTarget'
        - $ref: '#/components/schemas/AwardDiscountBundleTarget'
        - $ref: '#/components/schemas/AwardDiscountAdditionalCostTarget'
      discriminator:
        propertyName: type
        mapping:
          cart: '#/components/schemas/AwardDiscountCartTarget'
          allItems: '#/components/schemas/AwardDiscountAllItemsTarget'
          globalFilter: '#/components/schemas/AwardDiscountGlobalFilterTarget'
          selector: '#/components/schemas/AwardDiscountSelectorTarget'
          bundle: '#/components/schemas/AwardDiscountBundleTarget'
          additionalCost: '#/components/schemas/AwardDiscountAdditionalCostTarget'
    AwardDiscountBlock:
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
        - type: object
          title: AwardDiscountBlock
          description: A block that grants a discount when its rule conditions evaluate to `true`. The `target` field determines what the discount applies to (the whole cart, a subset of items, a bundle, an additional cost, etc.); the `value` field is the discount amount.
          required:
            - name
            - value
            - target
            - partial
          properties:
            name:
              type: string
              description: The human-readable label attached to the discount.
              example: 10% Off
            value:
              description: Discount amount. Either a numeric scalar or a `{{expression}}` string that resolves to a number at evaluation time.
              oneOf:
                - type: number
                  example: 10
                - type: string
                  example: '{{$Session.CartTotal * 0.1}}'
            partial:
              type: boolean
              description: Whether to apply a partial discount when the requested value exceeds the configured budget.
              example: false
            target:
              $ref: '#/components/schemas/AwardDiscountTarget'
    PassthroughBlock:
      type: object
      title: PassthroughBlock
      description: A block representing a Talang expression that could not be mapped to a typed block. The expression is preserved in its raw Talang array form for diagnostic and round-trip purposes.
      required:
        - type
        - expression
      properties:
        id:
          type: string
          readOnly: true
          description: Unique identifier for this block.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        type:
          type: string
          enum:
            - passthrough
          description: The type discriminator for this block.
        expression:
          type: array
          description: The raw Talang expression as an array. For a function call, the first element is the function name and subsequent elements are its arguments. For any other expression (for example a bare attribute path or a literal value), this is a single-element array containing that value.
          items: {}
    ShowNotificationBlock:
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
        - type: object
          title: ShowNotificationBlock
          description: A block that displays a notification to the customer with a configurable type, title, and body message.
          required:
            - notificationType
            - title
            - body
          properties:
            notificationType:
              type: string
              description: The type of notification to display.
              example: Info
            title:
              type: string
              description: The notification heading shown to the customer.
              example: You earned a reward!
            body:
              type: string
              description: The notification body text. Supports template placeholders (e.g. "{{$Session.Total}}") evaluated at rule execution time.
              example: You saved $10 on your order.
            onError:
              type: object
              description: Named error handlers evaluated when a specific error occurs.
              additionalProperties:
                type: array
                items:
                  $ref: '#/components/schemas/Block'
    AwardItemBlock:
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
        - type: object
          title: AwardItemBlock
          description: A block that awards a free cart item to the customer. The item is identified by SKU and name and has a configurable quantity.
          required:
            - sku
            - name
            - quantity
          properties:
            sku:
              type: string
              description: The stock keeping unit of the item to award.
              example: SKU1241028
            name:
              type: string
              description: The display name of the item to award.
              example: Free Tote Bag
            quantity:
              type: string
              description: The number of items to award. Supports template placeholders (e.g. "{{$Session.Total / 2}}") for dynamic quantities.
              example: '1'
            partial:
              type: boolean
              description: When set to `true`, applies a partial item reward if the remaining budget is insufficient to award the full reward. When omitted, the Application's partial discounts setting applies.
              example: false
            onFailure:
              type: array
              description: Blocks evaluated when this block fails or returns false.
              items:
                $ref: '#/components/schemas/Block'
            onError:
              type: object
              description: Named error handlers evaluated when a specific error occurs.
              additionalProperties:
                type: array
                items:
                  $ref: '#/components/schemas/Block'
    GiveawayPoolBlockReference:
      allOf:
        - type: object
          description: The giveaway pool from which a giveaway is awarded.
          required:
            - id
          properties:
            id:
              type: integer
              description: The unique identifier of the giveaway pool.
              example: 42
            name:
              type: string
              readOnly: true
              description: The display name of the giveaway pool.
              example: Summer Campaign Pool
    AwardGiveawayBlock:
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
        - type: object
          title: AwardGiveawayBlock
          description: A block that awards a giveaway item from a configured giveaway pool to the specified customer profile.
          required:
            - giveawayPool
            - profile
          properties:
            giveawayPool:
              $ref: '#/components/schemas/GiveawayPoolBlockReference'
              description: The giveaway pool from which an item is awarded.
            profile:
              type: string
              enum:
                - Current
                - Advocate
              description: The customer profile to award the giveaway to. `Current` targets the customer in the current session; `Advocate` targets the person who invited their friend via referral program.
              example: Current
            onError:
              type: object
              description: Named error handlers evaluated when a specific error occurs.
              additionalProperties:
                type: array
                items:
                  $ref: '#/components/schemas/Block'
    WebhookBlockReference:
      allOf:
        - type: object
          description: The webhook to trigger.
          required:
            - id
          properties:
            id:
              type: integer
              description: The unique identifier of the webhook.
              example: 1
            title:
              type: string
              readOnly: true
              description: The display name of the webhook.
              example: Thank you for your order.
    TriggerWebhookBlock:
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
        - type: object
          title: TriggerWebhookBlock
          description: A block that triggers a configured webhook and passes its required parameters.
          required:
            - webhook
          properties:
            webhook:
              $ref: '#/components/schemas/WebhookBlockReference'
              description: The webhook to trigger.
            params:
              type: object
              additionalProperties: true
              description: The webhook's parameters, in configured order. Each property name is the parameter's title, lowercased with spaces replaced by underscores (for example, `Order ID` becomes `order_id`); falls back to `param_0`, `param_1`, and so on if a title is blank or collides with another.
              example:
                order_id: ORD-10293
            onError:
              type: object
              description: Named error handlers evaluated when a specific error occurs.
              additionalProperties:
                type: array
                items:
                  $ref: '#/components/schemas/Block'
    ScalarCheckAttributeBlock:
      type: object
      title: ScalarCheckAttributeBlock
      description: Variant of `CheckAttributeBlock` for operators that compare an attribute against a single value.
      required:
        - value
      properties:
        operator:
          type: string
          description: The comparison operator applied to the attribute.
          enum:
            - equals
            - not(equals)
            - lessThan
            - lessThanOrEqual
            - greaterThan
            - greaterThanOrEqual
            - contains
            - not(contains)
            - matchesRegexp
            - startsWith
            - endsWith
            - oneOf
            - not(oneOf)
            - inCollection
            - not(inCollection)
            - after
            - before
        value:
          description: The comparison value for this operator.
          example: 100
    BetweenCheckAttributeBlock:
      type: object
      title: BetweenCheckAttributeBlock
      description: Variant of `CheckAttributeBlock` for the `between` operator, which requires both a minimum and maximum value.
      required:
        - min
        - max
      properties:
        operator:
          type: string
          description: The range comparison operator. Must be `between`.
          enum:
            - between
        min:
          description: The minimum value allowed for the `between` operator.
          example: 10
        max:
          description: The maximum value allowed for the `between` operator.
          example: 100
    ListCheckAttributeBlock:
      type: object
      title: ListCheckAttributeBlock
      description: Variant of `CheckAttributeBlock` for operators that test list membership against a set of values.
      required:
        - values
      properties:
        operator:
          type: string
          description: The list membership operator applied to the attribute.
          enum:
            - containsOneOf
            - containsNoneOf
            - containsAllOf
        values:
          description: The set of values to match against.
    ListWithCountCheckAttributeBlock:
      type: object
      title: ListWithCountCheckAttributeBlock
      description: Variant of `CheckAttributeBlock` for operators that test list membership with a minimum or exact count threshold.
      required:
        - values
        - count
      properties:
        operator:
          type: string
          description: The list membership operator with a count threshold applied to the attribute.
          enum:
            - containsAtLeast
            - containsExactly
        values:
          description: The set of values to match against.
        count:
          description: The count threshold for this operator.
          example: 2
    UnaryCheckAttributeBlock:
      type: object
      title: UnaryCheckAttributeBlock
      description: Variant of `CheckAttributeBlock` for operators that test a property of the attribute itself with no comparison value.
      properties:
        operator:
          type: string
          description: The unary operator applied to the attribute. These operators require no comparison value.
          enum:
            - empty
            - not(empty)
            - exists
            - not(exists)
            - isTrue
            - isFalse
    WithinCheckAttributeBlock:
      type: object
      title: WithinCheckAttributeBlock
      description: Variant of `CheckAttributeBlock` for the `within` and `not(within)` operators, which require both a start and end value.
      required:
        - start
        - end
      properties:
        operator:
          type: string
          description: The range comparison operator. Must be `within` or `not(within)`.
          enum:
            - within
            - not(within)
        start:
          description: The start value for the `within` operator.
          example: '2021-09-22T22:00:00Z'
        end:
          description: The end value for the `within` operator.
          example: '2021-09-22T22:00:00Z'
        startInclusive:
          type: boolean
          description: When `true`, the `start` value is included in the range for the `within` operator.
          example: true
        endInclusive:
          type: boolean
          description: When `true`, the `end` value is included in the range for the `within` operator.
          example: true
        timezoneInsensitive:
          type: boolean
          description: Indicates whether the `within` operator ignores time zones and compares the wall-clock time only. When `false`, time zones are taken into account.
          example: false
    GeoJSONPoint:
      type: object
      title: GeoJSONPoint
      description: A single point on a map, defined by its longitude and latitude coordinates, following the GeoJSON format.
      required:
        - type
        - coordinates
      properties:
        type:
          type: string
          description: The geometry type discriminator.
          enum:
            - Point
        coordinates:
          type: array
          description: The longitude and latitude coordinates of the point, optionally followed by altitude.
          items:
            type: number
          minItems: 2
          maxItems: 3
          example:
            - 13.405
            - 52.52
    GeoJSONPolygon:
      type: object
      title: GeoJSONPolygon
      description: A shape formed by one or more boundaries, following the GeoJSON format. The first boundary defines the outer edge of the shape; any additional boundaries define holes within the shape.
      required:
        - type
        - coordinates
      properties:
        type:
          type: string
          description: The geometry type discriminator.
          enum:
            - Polygon
        coordinates:
          type: array
          description: The boundaries that make up the shape. Each boundary is a closed loop of longitude and latitude points, where the first and last point are the same.
          items:
            type: array
            items:
              type: array
              items:
                type: number
              minItems: 2
              maxItems: 3
          example:
            - - - 13
                - 52.3
              - - 13.8
                - 52.3
              - - 13.8
                - 52.7
              - - 13
                - 52.7
              - - 13
                - 52.3
    GeoJSONMultiPolygon:
      type: object
      title: GeoJSONMultiPolygon
      description: One or more separate shapes grouped together as a single location, following the GeoJSON format.
      required:
        - type
        - coordinates
      properties:
        type:
          type: string
          description: The geometry type discriminator.
          enum:
            - MultiPolygon
        coordinates:
          type: array
          description: The shapes in this group. Each one follows the same boundary structure as a polygon.
          items:
            type: array
            items:
              type: array
              items:
                type: array
                items:
                  type: number
                minItems: 2
                maxItems: 3
          example:
            - - - - 13
                  - 52.3
                - - 13.8
                  - 52.3
                - - 13.8
                  - 52.7
                - - 13
                  - 52.7
                - - 13
                  - 52.3
    GeoJSONGeometry:
      description: A shape used to represent a geographical location. The `type` field determines the kind of shape.
      oneOf:
        - $ref: '#/components/schemas/GeoJSONPoint'
        - $ref: '#/components/schemas/GeoJSONPolygon'
        - $ref: '#/components/schemas/GeoJSONMultiPolygon'
        - $ref: '#/components/schemas/GeoJSONGeometryCollection'
      discriminator:
        propertyName: type
        mapping:
          Point: '#/components/schemas/GeoJSONPoint'
          Polygon: '#/components/schemas/GeoJSONPolygon'
          MultiPolygon: '#/components/schemas/GeoJSONMultiPolygon'
          GeometryCollection: '#/components/schemas/GeoJSONGeometryCollection'
    GeoJSONGeometryCollection:
      type: object
      title: GeoJSONGeometryCollection
      description: A group of different shapes combined into a single location, following the GeoJSON format.
      required:
        - type
        - geometries
      properties:
        type:
          type: string
          description: The geometry type discriminator.
          enum:
            - GeometryCollection
        geometries:
          type: array
          description: The shapes contained in this group.
          items:
            $ref: '#/components/schemas/GeoJSONGeometry'
    LocationCheckAttributeBlock:
      type: object
      title: LocationCheckAttributeBlock
      description: A block variant of `CheckAttributeBlock` for operators that check whether a geographical location is inside a set of geometric areas.
      required:
        - values
      properties:
        operator:
          type: string
          description: The location membership operator applied to the attribute.
          enum:
            - in
            - not(in)
        values:
          description: The geometric areas to check the location against.
          oneOf:
            - type: array
              items:
                type: object
                required:
                  - geometry
                properties:
                  name:
                    type: string
                    description: A human-readable label for this location.
                    example: Berlin district
                  geometry:
                    $ref: '#/components/schemas/GeoJSONGeometry'
            - type: string
              description: A reference to a list attribute that contains locations.
              example: '{{$Session.AllowedZones}}'
    CheckAttributeBlockBase:
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
        - type: object
          title: CheckAttributeBlockBase
          description: |-
            Shared shape for attribute-comparison blocks: a single attribute evaluated by a named operator.
            The operator determines which additional fields are required:
            - `scalar` requires `value`.
            - `between` requires `min` and `max` values.
            - `list` requires `values`.
            - `list-with-count` requires `values` and `count`.
            - `unary` requires no extra fields.
          required:
            - operator
            - attribute
          properties:
            operator:
              type: string
              enum:
                - equals
                - not(equals)
                - lessThan
                - lessThanOrEqual
                - greaterThan
                - greaterThanOrEqual
                - between
                - contains
                - not(contains)
                - matchesRegexp
                - startsWith
                - endsWith
                - oneOf
                - not(oneOf)
                - inCollection
                - not(inCollection)
                - empty
                - not(empty)
                - exists
                - not(exists)
                - isTrue
                - isFalse
                - containsAtLeast
                - containsExactly
                - containsOneOf
                - containsNoneOf
                - containsAllOf
                - after
                - before
                - within
                - not(within)
                - in
                - not(in)
              description: The comparison operator applied to the attribute.
              example: greaterThan
            attribute:
              description: The attribute path identifier (e.g. "$Session.Total").
              example: $Session.Total
            value:
              description: The comparison value for scalar operators.
              example: 100
            min:
              description: The minimum value allowed for the `between` operator.
              example: 10
            max:
              description: The maximum value allowed for the `between` operator.
              example: 100
            start:
              description: The start value for the `within` operator.
              example: '2021-09-22T22:00:00Z'
            end:
              description: The end value for the `within` operator.
              example: '2021-09-22T22:00:00Z'
            startInclusive:
              type: boolean
              description: When `true`, the `start` value is included in the range for the `within` operator.
              example: true
            endInclusive:
              type: boolean
              description: When `true`, the `end` value is included in the range for the `within` operator.
              example: true
            timezoneInsensitive:
              type: boolean
              description: Indicates whether the `within` operator ignores time zones and compares the wall-clock time only. When `false`, time zones are taken into account.
              example: false
            values:
              description: The set of values to match against for list operators. For location operators (`in`, `not(in)`), an array of objects with a `geometry` (see `GeoJSONGeometry`) and an optional `name`, or a string reference to a list attribute.
              example:
                - name: Berlin district
                  geometry:
                    type: Point
                    coordinates:
                      - 13.405
                      - 52.52
            count:
              description: The count threshold for `containsAtLeast` and `containsExactly` operators.
              example: 2
            onFailure:
              type: array
              description: Promotion blocks evaluated when this block fails or returns false.
              items:
                $ref: '#/components/schemas/Block'
    CheckAttributeBlock:
      allOf:
        - $ref: '#/components/schemas/CheckAttributeBlockBase'
        - type: object
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - checkAttribute
              description: A block discriminator of type `checkAttribute`.
              example: checkAttribute
      oneOf:
        - $ref: '#/components/schemas/ScalarCheckAttributeBlock'
        - $ref: '#/components/schemas/BetweenCheckAttributeBlock'
        - $ref: '#/components/schemas/ListCheckAttributeBlock'
        - $ref: '#/components/schemas/ListWithCountCheckAttributeBlock'
        - $ref: '#/components/schemas/UnaryCheckAttributeBlock'
        - $ref: '#/components/schemas/WithinCheckAttributeBlock'
        - $ref: '#/components/schemas/LocationCheckAttributeBlock'
      discriminator:
        propertyName: operator
        mapping:
          equals: '#/components/schemas/ScalarCheckAttributeBlock'
          not(equals): '#/components/schemas/ScalarCheckAttributeBlock'
          lessThan: '#/components/schemas/ScalarCheckAttributeBlock'
          lessThanOrEqual: '#/components/schemas/ScalarCheckAttributeBlock'
          greaterThan: '#/components/schemas/ScalarCheckAttributeBlock'
          greaterThanOrEqual: '#/components/schemas/ScalarCheckAttributeBlock'
          contains: '#/components/schemas/ScalarCheckAttributeBlock'
          not(contains): '#/components/schemas/ScalarCheckAttributeBlock'
          matchesRegexp: '#/components/schemas/ScalarCheckAttributeBlock'
          startsWith: '#/components/schemas/ScalarCheckAttributeBlock'
          endsWith: '#/components/schemas/ScalarCheckAttributeBlock'
          oneOf: '#/components/schemas/ScalarCheckAttributeBlock'
          not(oneOf): '#/components/schemas/ScalarCheckAttributeBlock'
          inCollection: '#/components/schemas/ScalarCheckAttributeBlock'
          not(inCollection): '#/components/schemas/ScalarCheckAttributeBlock'
          between: '#/components/schemas/BetweenCheckAttributeBlock'
          containsOneOf: '#/components/schemas/ListCheckAttributeBlock'
          containsNoneOf: '#/components/schemas/ListCheckAttributeBlock'
          containsAllOf: '#/components/schemas/ListCheckAttributeBlock'
          containsAtLeast: '#/components/schemas/ListWithCountCheckAttributeBlock'
          containsExactly: '#/components/schemas/ListWithCountCheckAttributeBlock'
          empty: '#/components/schemas/UnaryCheckAttributeBlock'
          not(empty): '#/components/schemas/UnaryCheckAttributeBlock'
          exists: '#/components/schemas/UnaryCheckAttributeBlock'
          not(exists): '#/components/schemas/UnaryCheckAttributeBlock'
          isTrue: '#/components/schemas/UnaryCheckAttributeBlock'
          isFalse: '#/components/schemas/UnaryCheckAttributeBlock'
          after: '#/components/schemas/ScalarCheckAttributeBlock'
          before: '#/components/schemas/ScalarCheckAttributeBlock'
          within: '#/components/schemas/WithinCheckAttributeBlock'
          not(within): '#/components/schemas/WithinCheckAttributeBlock'
          in: '#/components/schemas/LocationCheckAttributeBlock'
          not(in): '#/components/schemas/LocationCheckAttributeBlock'
    AudienceBlockReference:
      allOf:
        - type: object
          description: The audience to check the profile against.
          required:
            - id
          properties:
            id:
              type: integer
              description: The ID of the audience.
              example: 42
            name:
              type: string
              description: The display name of the audience.
              example: Travel audience
              readOnly: true
            integration:
              type: string
              description: |
                The Talon.One-supported [3rd-party platform](https://docs.talon.one/docs/dev/technology-partners/overview) that this audience was created in.

                For example, `mParticle`, `Segment`, `Shopify`, `Braze`, or `Iterable`.

                **Note:** If you do not integrate with any of these platforms, do not use this property.
              example: mparticle
            integrationId:
              type: string
              description: |
                The ID of this audience in the third-party integration.

                **Note:** To create an audience that doesn't come from a 3rd party platform, do not use this property.
              example: 382370BKDB946
    CheckAudienceBlock:
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
        - type: object
          title: CheckAudienceBlock
          description: A block that checks whether a given customer profile is a member of an audience.
          required:
            - operator
            - audience
          properties:
            operator:
              type: string
              enum:
                - member
                - not(member)
                - justJoined
                - justLeft
              description: An indicator of how the block compares its elements.
              example: member
            profile:
              type: string
              enum:
                - Current
                - Advocate
              description: The customer profile to check against the audience. `Current` targets the customer in the current session; `Advocate` targets the person who invited their friend via referral program. Only applies to the `member` and `not(member)` operators; ignored for `justJoined` and `justLeft`.
              example: Current
            audience:
              $ref: '#/components/schemas/AudienceBlockReference'
              description: The audience to check the profile against.
            onFailure:
              type: array
              description: Promotion blocks evaluated when this block fails or returns false.
              items:
                $ref: '#/components/schemas/Block'
    CheckLoyaltyBalanceBlock:
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
        - type: object
          title: CheckLoyaltyBalanceBlock
          description: A block that checks a specific loyalty program's ledger or subledger balance against a numeric value.
          required:
            - operator
            - program
            - subledger
            - balance
            - value
          properties:
            operator:
              type: string
              enum:
                - equals
                - not(equals)
                - lessThan
                - lessThanOrEqual
                - greaterThan
                - greaterThanOrEqual
              description: An indicator of how the block compares the balance to the value.
              example: greaterThanOrEqual
            program:
              type: object
              description: The loyalty program whose ledger balance is checked.
              required:
                - id
              properties:
                id:
                  type: integer
                  description: The ID of the loyalty program.
                  example: 10
                name:
                  type: string
                  description: The internal name of the loyalty program.
                  example: MainProgram
                  readOnly: true
                title:
                  type: string
                  description: The display name of the loyalty program.
                  example: Main Loyalty Program
                  readOnly: true
            subledger:
              type: string
              description: The name of the subledger to check the balance of. Can be empty if this block checks the loyalty program's main ledger balance instead of a subledger. A subledger can only be used when the loyalty program has subledgers enabled.
              example: ''
            balance:
              type: string
              enum:
                - current
                - pending
                - negative
                - tentativeCurrent
              description: |-
                The type of balance to check:
                 - `current` is the sum of currently active points
                 - `pending` is the sum of pending points.
                 - `negative` is the sum of negative points. It cannot be used with a subledger.
                 - `tentativeCurrent` is the tentative points balance
                within the current open customer session.
              example: current
            value:
              type: number
              description: The numeric value to compare the balance against.
              example: 500
            onFailure:
              type: array
              description: Promotion blocks evaluated when this block fails or returns false.
              items:
                $ref: '#/components/schemas/Block'
    CheckCouponBlock:
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
        - type: object
          title: CheckCouponBlock
          description: A block that validates the coupon code value and date.
          required:
            - type
            - redeem
          properties:
            type:
              type: string
              enum:
                - checkCoupon
              description: A block discriminator of type `checkCoupon`.
              example: checkCoupon
            redeem:
              type: boolean
              description: When `true`, the coupon code is redeemed.
              example: true
            onFailure:
              type: array
              description: Promotion blocks evaluated when this block fails or returns false.
              items:
                $ref: '#/components/schemas/Block'
    CheckReferralBlock:
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
        - type: object
          title: CheckReferralBlock
          description: A block that validates the referral code value and date.
          required:
            - type
            - redeem
          properties:
            type:
              type: string
              enum:
                - checkReferral
              description: A block discriminator of type `checkReferral`.
              example: checkReferral
            redeem:
              type: boolean
              description: When `true`, the referral code is redeemed.
              example: true
            onFailure:
              type: array
              description: Promotion blocks evaluated when this block fails or returns false.
              items:
                $ref: '#/components/schemas/Block'
    UpdateAudienceMembershipBlock:
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
        - type: object
          title: UpdateAudienceMembershipBlock
          description: A block that adds a customer to or removes them from an audience.
          required:
            - operator
            - profile
            - audience
          properties:
            operator:
              type: string
              enum:
                - add
                - remove
              description: The action to perform.
              example: add
            profile:
              type: string
              enum:
                - Current
                - Advocate
              description: The customer profile to add or remove from the audience. `Current` targets the customer in the current session; `Advocate` targets the person who invited their friend via referral program.
              example: Current
            audience:
              $ref: '#/components/schemas/AudienceBlockReference'
              description: The audience to add the customer to or remove them from.
    AchievementBlockReference:
      allOf:
        - type: object
          description: The achievement to check for.
          required:
            - id
          properties:
            id:
              type: integer
              description: The ID of the achievement.
              example: 42
            title:
              type: string
              description: The display name for the achievement in the Campaign Manager.
              example: 50% off on 50th purchase.
              readOnly: true
            name:
              type: string
              description: The internal name of the achievement used in API requests.
              example: Order50Discount
              readOnly: true
            target:
              type: number
              description: The required number of actions or the transactional milestone to complete the achievement.
              example: 50
              readOnly: true
    UpdateAchievementProgressBlock:
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
        - type: object
          title: UpdateAchievementProgressBlock
          description: A block that updates the progress of a customer in an achievement.
          required:
            - operator
            - value
            - achievement
          properties:
            operator:
              type: string
              enum:
                - increaseBy
              example: increaseBy
            value:
              description: The value to update the progress by. Either a numeric scalar or a `{{expression}}` string that resolves to a number at evaluation time.
              oneOf:
                - type: number
                  example: 10
                - type: string
                  example: '{{$Session.CartTotal * 0.1}}'
            achievement:
              $ref: '#/components/schemas/AchievementBlockReference'
              description: The achievement to update.
    AttributeBlockReference:
      allOf:
        - type: object
          required:
            - id
            - entity
            - name
          description: The attribute being updated.
          properties:
            id:
              type: integer
              description: The internal ID of the attribute. Reverts to `0` when the attribute is deleted or does not exist.
              example: 100
            entity:
              type: string
              description: The entity type that owns the attribute. Reverts to an empty string when the attribute is deleted or does not exist.
              example: profile
            name:
              type: string
              description: The attribute name as used in API requests.
              example: City
            title:
              type: string
              description: The human-readable name of the attribute.
              example: City
              readOnly: true
            type:
              type: string
              description: The data type of the attribute.
              example: string
              readOnly: true
    UpdateAttributeValueBlock:
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
        - type: object
          title: UpdateAttributeValueBlock
          description: A block that sets or updates an attribute. The `type` may be empty for [built-in attributes](https://docs.talon.one/docs/dev/concepts/attributes).
          required:
            - operator
            - attribute
            - target
          properties:
            operator:
              type: string
              enum:
                - setTo
                - increaseBy
                - decreaseBy
                - multiplyBy
                - divideBy
                - toggle
                - laterBy
                - earlierBy
              description: The update operation applied to the attribute.
              example: setTo
            attribute:
              $ref: '#/components/schemas/AttributeBlockReference'
              description: The attribute being updated.
            value:
              description: The value of the attribute. Omitted when operator is set to `toggle`.
              example: 10
            target:
              type: object
              required:
                - type
              description: The entity or item scope that this effect operates on.
              properties:
                type:
                  type: string
                  enum:
                    - session
                    - profile
                    - advocateProfile
                    - coupon
                    - referral
                    - event
                    - loyaltyCard
                    - allItems
                    - selector
                    - globalFilter
                  description: Identifies the target scope of the attribute update.
                  example: profile
                name:
                  type: string
                  description: Identifies the name of the target when its type is set to `selector` or `globalFilter`.
                  example: Filter items by product
            tags:
              type: array
              description: Semantic labels attached to this block.
              items:
                type: string
    CustomEffectBlockReference:
      allOf:
        - type: object
          description: The custom effect to trigger.
          required:
            - id
          properties:
            id:
              type: integer
              description: The unique identifier of the custom effect.
              example: 1
            name:
              type: string
              readOnly: true
              description: The name of the custom effect, as used in API requests.
              example: sendEmail
            title:
              type: string
              readOnly: true
              description: The display name of the custom effect.
              example: Send email
    TriggerCustomEffectBlock:
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
        - type: object
          title: TriggerCustomEffectBlock
          description: A block that triggers a configured custom effect and passes its required parameters.
          required:
            - customEffect
            - target
          properties:
            customEffect:
              $ref: '#/components/schemas/CustomEffectBlockReference'
              description: The custom effect to trigger.
            params:
              type: object
              additionalProperties: true
              description: The custom effect's parameters, in configured order. Each property name is the parameter's title, lowercased with spaces replaced by underscores (for example, `Order ID` becomes `order_id`); falls back to `param_0`, `param_1`, and so on if a title is blank or collides with another.
              example:
                template_id: TPL-10293
            target:
              type: object
              required:
                - type
              description: The target scope of this effect.
              properties:
                type:
                  type: string
                  enum:
                    - cart
                    - allItems
                    - selector
                    - globalFilter
                    - bundle
                  description: 'The scope the custom effect applies to: - `cart` applies once to the whole cart. - `allItems` applies once per cart item. - `selector` applies once per item matched by the named selector. - `globalFilter` applies once per item matched by the named global item filter. - `bundle` applies once per item in the named bundle.'
                  example: cart
                name:
                  type: string
                  description: The name of the targeted selector or bundle. Only set when `type` is `selector`, `globalFilter`, or `bundle`.
                  example: giftBundle
            onError:
              type: object
              description: Named error handlers evaluated when a specific error occurs.
              additionalProperties:
                type: array
                items:
                  $ref: '#/components/schemas/Block'
    CheckEventBlock:
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
        - type: object
          title: CheckEventBlock
          description: A block that validates the event type.
          required:
            - eventType
          properties:
            eventType:
              type: string
              description: The event type to check against.
              example: profileCreated
            matchers:
              type: array
              items:
                $ref: '#/components/schemas/Block'
            onFailure:
              type: array
              description: Promotion blocks evaluated when this block fails or returns false.
              items:
                $ref: '#/components/schemas/Block'
    CheckAchievementBlock:
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
        - type: object
          title: CheckAchievementBlock
          description: A block that checks the current customer's completion or progress status in an achievement.
          required:
            - operator
            - achievement
          properties:
            operator:
              type: string
              enum:
                - justCompleted
                - started
                - not(started)
                - inProgress
                - not(inProgress)
                - completed
                - not(completed)
              description: The comparison operator applied to the achievement.
              example: justCompleted
            achievement:
              $ref: '#/components/schemas/AchievementBlockReference'
              description: The achievement to check for.
            onFailure:
              type: array
              description: Promotion blocks evaluated when this block fails or returns false.
              items:
                $ref: '#/components/schemas/Block'
    CheckBudgetBlock:
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
        - type: object
          title: CheckBudgetBlock
          description: A block that verifies if a specific budget has sufficient limit available, and whether this limit meets or exceeds a specific value.
          required:
            - operator
            - action
          properties:
            operator:
              type: string
              enum:
                - available
                - enoughFor
              description: The comparison operator applied to the limit. `available` checks if there is budget available for a given limitable action; `enoughFor` checks if the available budget meets or exceeds a specific value limit.
              example: available
            action:
              type: string
              enum:
                - redeemCoupon
                - redeemReferral
                - setDiscount
                - createCoupon
                - createReferral
                - setDiscountEffect
                - createLoyaltyPoints
                - createLoyaltyPointsEffect
                - redeemLoyaltyPoints
                - redeemLoyaltyPointsEffect
                - awardGiveaway
                - addFreeItemEffect
                - customEffect
                - callApi
              description: The limitable action to check.
              example: setDiscount
            value:
              type: number
              description: The value to check against when using the `enoughFor` operator.
              example: 5
            onFailure:
              type: array
              description: Promotion blocks evaluated when this block fails or returns false.
              items:
                $ref: '#/components/schemas/Block'
    CreateCouponBlock:
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
        - type: object
          title: CreateCouponBlock
          description: A block that creates a coupon code.
          required:
            - campaignId
            - recipientId
            - storeInSession
          properties:
            campaignId:
              description: The ID of the campaign in which the coupon code is created.
              oneOf:
                - type: number
                  example: 3
                - type: string
                  example: '{{$Campaign.Id}}'
            recipientId:
              type: string
              description: The integration ID of the customer that is allowed to redeem this coupon.
              example: '{{$Profile.IntegrationId}}'
            storeInSession:
              type: boolean
              description: When `true`, the coupon is stored in the session.
              example: true
            usageLimit:
              description: |
                The number of times the coupon code can be redeemed. `0` means unlimited redemptions, but any campaign usage limits still apply. Either a numeric scalar or a `{{expression}}` string that resolves to a number at evaluation time.
              oneOf:
                - type: number
                  example: 100
                - type: string
                  example: '{{$Session.CartTotal * 0.1}}'
            discountLimit:
              description: |
                The total discount value that the code can give. Typically used to represent a gift card value. Either a numeric scalar or a `{{expression}}` string that resolves to a number at evaluation time.
              oneOf:
                - type: number
                  example: 30
                - type: string
                  example: '{{$Session.CartTotal * 0.1}}'
            startDate:
              description: Timestamp at which point the coupon becomes valid.
              example: '2024-12-24T14:15:22Z'
            expiryDate:
              description: Expiration date of the coupon. Coupon never expires if this is omitted.
              example: '2024-12-24T14:15:22Z'
            attributes:
              description: Custom attributes associated with this coupon code.
            validCharacters:
              type: string
              description: Characters used to generate the random parts of a code.
              example: ABC
            pattern:
              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.
              example: SUMMER-####-####
    CreateReferralBlock:
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
        - type: object
          title: CreateReferralBlock
          description: A block that creates a referral code.
          required:
            - campaignId
            - friendId
            - storeInSession
          properties:
            campaignId:
              description: The ID of the campaign in which the referral code is created. Either a numeric scalar or a `{{expression}}` string that resolves to a number at evaluation time.
              oneOf:
                - type: number
                  example: 3
                - type: string
                  example: '{{$Campaign.Id}}'
            friendId:
              type: string
              description: An optional integration ID of the friend's profile.
              example: '{{$Profile.IntegrationId}}'
            storeInSession:
              type: boolean
              description: When `true`, the referral code is stored in the session.
              example: true
            usageLimit:
              description: |
                The number of times the referral code code can be redeemed. `0` means unlimited redemptions, but any campaign usage limits still apply. Either a numeric scalar or a `{{expression}}` string that resolves to a number at evaluation time.
              oneOf:
                - type: number
                  example: 100
                - type: string
                  example: '{{$Session.CartTotal * 0.1}}'
            startDate:
              description: Timestamp at which point the referral code becomes valid.
              example: '2024-12-24T14:15:22Z'
            expiryDate:
              description: Expiration date of the referral code. Referral code never expires if this is omitted.
              example: '2024-12-24T14:15:22Z'
            attributes:
              description: Custom attributes associated with this referral code.
            validCharacters:
              type: string
              description: Characters used to generate the random parts of a code.
              example: ABC
            pattern:
              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.
              example: SUMMER-####-####
    ReserveCouponBlock:
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
        - type: object
          title: ReserveCouponBlock
          description: A block that reserve a coupon during a customer session.
    UpdateLoyaltyPointsExpiryBlock:
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
        - type: object
          title: UpdateLoyaltyPointsExpiryBlock
          description: A block that changes the expiry date of a customer's existing loyalty points, either to an absolute date or by extending it relative to the current expiry date.
          required:
            - operator
            - program
            - recipient
            - subledger
            - value
          properties:
            operator:
              type: string
              enum:
                - setTo
                - laterBy
              description: '`setTo` sets the expiry to an exact date; `laterBy` extends the current expiry by a relative duration.'
              example: setTo
            program:
              type: object
              description: The loyalty program whose points' expiry is changed.
              required:
                - id
              properties:
                id:
                  type: integer
                  description: The ID of the loyalty program.
                  example: 10
                name:
                  type: string
                  readOnly: true
                  description: The internal name of the loyalty program.
                  example: MainProgram
                title:
                  type: string
                  readOnly: true
                  description: The display name of the loyalty program.
                  example: Main Loyalty Program
            recipient:
              type: string
              enum:
                - Current
                - Advocate
              description: The customer profile whose points are affected. `Current` targets the customer in the current session; `Advocate` targets the person who invited their friend via referral program.
              example: Current
            subledger:
              type: string
              description: The name of the subledger whose points' expiry is changed. Can be empty if this block targets the loyalty program's main ledger instead of a subledger.
              example: main
            value:
              description: An absolute expiry date (ISO 8601) when `operator` is `setTo`, or a relative duration (e.g. `30D`) when `operator` is `laterBy`.
              example: '2026-12-31T00:00:00Z'
            onFailure:
              type: array
              description: Blocks evaluated when this block fails or returns false.
              items:
                $ref: '#/components/schemas/Block'
    CheckLoyaltyCardBlock:
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
        - type: object
          title: CheckLoyaltyCardBlock
          description: A block that verifies whether a loyalty card is linked to the user's profile.
          required:
            - operator
          properties:
            operator:
              type: string
              enum:
                - linked
                - not(linked)
              description: An indicator of how the block compares its elements.
            onFailure:
              type: array
              description: Promotion blocks evaluated when this block fails or returns false.
              items:
                $ref: '#/components/schemas/Block'
    TierBlockReference:
      allOf:
        - type: object
          required:
            - id
            - name
            - minPoints
          properties:
            id:
              type: integer
              description: The ID of the tier.
              example: 42
            name:
              type: string
              description: The display name of the tier.
              example: Bronze
            minPoints:
              type: number
              description: The minimum amount of points required to enter the tier.
              example: 150
            upperLimit:
              type: number
    CheckTierBlock:
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
        - type: object
          title: CheckTierBlock
          description: A block that checks whether a customer profile is a member of a specific tier in a loyalty program.
          required:
            - operator
            - subledger
            - tier
          properties:
            operator:
              type: string
              enum:
                - member
                - not(member)
              description: An indicator of how the block compares its elements.
              example: member
            subledger:
              type: string
              description: |-
                The name of the subledger to check a customer's tier in. Can be empty if this block checks the loyalty program's main ledger instead of a subledger. A subledger can only be used when the loyalty program that the tier is in has subledgers enabled.
                To specify the main ledger, provide an empty string ("").
              example: ''
            tier:
              $ref: '#/components/schemas/TierBlockReference'
              description: The tier to check for.
            onFailure:
              type: array
              description: Promotion blocks evaluated when this block fails or returns false.
              items:
                $ref: '#/components/schemas/Block'
    AwardLoyaltyPointsCartTarget:
      type: object
      title: AwardLoyaltyPointsCartTarget
      description: Awards points to the entire cart as a single unit.
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - cart
          description: A target discriminator of type `cart`.
    AwardLoyaltyPointsAllItemsTarget:
      type: object
      title: AwardLoyaltyPointsAllItemsTarget
      description: Awards points per item in the cart.
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - allItems
          description: A target discriminator of type `allItems`.
    AwardLoyaltyPointsGlobalFilterTarget:
      type: object
      title: AwardLoyaltyPointsGlobalFilterTarget
      description: Awards points per item in a globally filtered subset of items.
      required:
        - type
        - name
      properties:
        type:
          type: string
          enum:
            - globalFilter
          description: A target discriminator of type `globalFilter`.
        name:
          type: string
          description: The name of the Application-level cart item filter the points target.
          example: PremiumItems
    AwardLoyaltyPointsSelectorTarget:
      type: object
      title: AwardLoyaltyPointsSelectorTarget
      description: Awards points per item in a specific selector.
      required:
        - type
        - name
      properties:
        type:
          type: string
          enum:
            - selector
          description: A target discriminator of type `selector`.
        name:
          type: string
          description: The name of the selector binding the points target.
          example: ElectronicsItems
    AwardLoyaltyPointsBundleTarget:
      type: object
      title: AwardLoyaltyPointsBundleTarget
      description: Awards points based on bundle contents.
      required:
        - type
        - name
      properties:
        type:
          type: string
          enum:
            - bundle
          description: A target discriminator of type `bundle`.
        name:
          type: string
          description: Name of the bundle the points target.
          example: BogoBundle
    AwardLoyaltyPointsTarget:
      description: Identifies the scope over which loyalty points are awarded. The `type` field selects the target variant.
      oneOf:
        - $ref: '#/components/schemas/AwardLoyaltyPointsCartTarget'
        - $ref: '#/components/schemas/AwardLoyaltyPointsAllItemsTarget'
        - $ref: '#/components/schemas/AwardLoyaltyPointsGlobalFilterTarget'
        - $ref: '#/components/schemas/AwardLoyaltyPointsSelectorTarget'
        - $ref: '#/components/schemas/AwardLoyaltyPointsBundleTarget'
      discriminator:
        propertyName: type
        mapping:
          cart: '#/components/schemas/AwardLoyaltyPointsCartTarget'
          allItems: '#/components/schemas/AwardLoyaltyPointsAllItemsTarget'
          globalFilter: '#/components/schemas/AwardLoyaltyPointsGlobalFilterTarget'
          selector: '#/components/schemas/AwardLoyaltyPointsSelectorTarget'
          bundle: '#/components/schemas/AwardLoyaltyPointsBundleTarget'
    AwardLoyaltyPointsBlock:
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
        - type: object
          title: AwardLoyaltyPointsBlock
          description: A block that adds loyalty points to a loyalty program and subledger for a recipient. The `target` field determines what the award is based on (the whole cart, a subset of items, or a bundle); the `value` field is the number of awarded points.
          required:
            - name
            - program
            - recipient
            - subledger
            - target
            - value
          properties:
            name:
              type: string
              description: The human-readable label attached to the awarded points.
              example: Bonus
            program:
              type: object
              description: The loyalty program points are added to.
              required:
                - id
              properties:
                id:
                  type: integer
                  description: The ID of the loyalty program.
                  example: 10
                name:
                  type: string
                  readOnly: true
                  description: The internal name of the loyalty program.
                  example: MainProgram
                title:
                  type: string
                  readOnly: true
                  description: The display name of the loyalty program.
                  example: Main Loyalty Program
            recipient:
              type: string
              enum:
                - Current
                - Advocate
              description: The customer profile that receives the points. `Current` targets the customer in the current session; `Advocate` targets the person who invited their friend via referral program.
              example: Current
            subledger:
              type: string
              description: The name of the subledger to add points to. Can be empty if this block adds points to the loyalty program's main ledger instead of a subledger.
              example: main
            target:
              $ref: '#/components/schemas/AwardLoyaltyPointsTarget'
            value:
              description: Number of points to award. Either a numeric scalar or a `{{expression}}` string that resolves to a number at evaluation time.
              oneOf:
                - type: number
                  example: 100
                - type: string
                  example: '{{$Session.CartTotal * 0.1}}'
            partial:
              type: boolean
              description: When `true`, applies a partial points reward when the requested value exceeds the configured budget.
              example: false
            awaitsActivation:
              type: boolean
              description: When `true`, the awarded points require manual or delayed activation before becoming active. Mutually exclusive with `startDate`.
              example: false
            startDate:
              description: Timestamp at which the awarded points become active. Mutually exclusive with `awaitsActivation`.
              example: '2026-12-24T14:15:22Z'
            validityDuration:
              type: string
              description: Relative duration (e.g. `30D`) after which the awarded points expire. Mutually exclusive with `expiryDate`.
              example: 30D
            expiryDate:
              description: Timestamp at which the awarded points expire. Mutually exclusive with `validityDuration`.
              example: '2026-12-31T00:00:00Z'
            pendingDuration:
              type: string
              description: Relative duration (e.g. `3D`) the awarded points remain pending before activation.
              example: 3D
    RedeemLoyaltyPointsBlock:
      allOf:
        - $ref: '#/components/schemas/BaseBlock'
        - type: object
          title: RedeemLoyaltyPointsBlock
          description: A block that deducts a specified amount of points from a customer's loyalty program balance, optionally from a named subledger.
          required:
            - program
            - subledger
            - value
          properties:
            program:
              type: object
              description: The loyalty program whose balance points are deducted from.
              required:
                - id
              properties:
                id:
                  type: integer
                  description: The ID of the loyalty program.
                  example: 10
                name:
                  type: string
                  description: The internal name of the loyalty program.
                  example: MainProgram
                  readOnly: true
                title:
                  type: string
                  description: The display name of the loyalty program.
                  example: Main Loyalty Program
                  readOnly: true
            subledger:
              type: string
              description: The name of the subledger to deduct points from. Can be empty if this block deducts from the loyalty program's main ledger instead of a subledger.
              example: main
            value:
              description: Number of points to deduct. Either a numeric scalar or a `{{expression}}` string that resolves to a number at evaluation time.
              oneOf:
                - type: number
                  example: 50
                - type: string
                  example: '{{$Session.CartTotal * 0.1}}'
            name:
              type: string
              description: A custom description recorded as the reason for the point deduction.
              example: Purchase Deduction
    RuleV2:
      type: object
      title: RuleV2
      description: Shared fields common to all V2 rule types.
      required:
        - title
        - blocks
      properties:
        id:
          type: string
          description: Unique identifier of the rule.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        parentId:
          type: string
          description: ID of the parent rule, if any.
        title:
          type: string
          description: A short description of the rule.
          example: 10% off for loyalty members
        description:
          type: string
          description: A longer description of the rule.
        blocks:
          type: array
          description: The condition and effect blocks that make up this rule.
          items:
            $ref: '#/components/schemas/Block'
    FilterSelectorStep:
      type: object
      title: FilterSelectorStep
      description: Filters only items that match a predicate block.
      required:
        - type
        - predicate
      properties:
        type:
          type: string
          enum:
            - filter
          description: A step discriminator of type `filter`.
          example: filter
        predicate:
          $ref: '#/components/schemas/Block'
    SortSelectorStepField:
      type: object
      title: SortSelectorStepField
      required:
        - expression
        - direction
      properties:
        expression:
          type: string
          description: The attribute path the items are sorted by.
          example: $Item.Price
        direction:
          type: string
          enum:
            - asc
            - desc
          description: The sort direction for this field.
          example: asc
    SortSelectorStep:
      type: object
      title: SortSelectorStep
      description: Sorts items by one or more field expressions.
      required:
        - type
        - fields
      properties:
        type:
          type: string
          enum:
            - sort
          description: A step discriminator of type `sort`.
          example: sort
        fields:
          type: array
          description: One or more fields to sort by, applied in order. Each field has its own direction.
          items:
            $ref: '#/components/schemas/SortSelectorStepField'
    SelectSelectorStep:
      type: object
      title: SelectSelectorStep
      description: 'Picks a subset of the items by count, range, or exact position. The `operator` determines which additional fields are required: - `many` selects items from `from` (`start` or `end`) and is limited by `count`. - `between` selects items between integer indices `from` and `to`. - `one` selects the single item at `index`.'
      required:
        - type
        - operator
      properties:
        type:
          type: string
          enum:
            - select
          description: A step discriminator of type `select`.
          example: select
        operator:
          type: string
          enum:
            - many
            - between
            - one
          description: The selection operator applied to the items.
          example: many
        from:
          description: The starting value of the selection. For the `many` operator this is the string `start` or `end`; for the `between` operator this is an integer start index. No discriminator is needed since the string and integer branches are distinguishable by JSON type alone.
          oneOf:
            - type: string
              enum:
                - start
                - end
              example: start
            - type: integer
              format: int32
              example: 2
        to:
          type: integer
          format: int32
          description: The end index for the `between` operator. The item at this index is not included.
          example: 7
        count:
          type: integer
          format: int32
          description: The maximum number of items to select for the `many` operator.
          example: 5
        index:
          type: integer
          format: int32
          description: The exact position of the item to select for the `one` operator.
          example: 0
        partial:
          type: boolean
          description: Indicates if the step returns fewer items than requested when the source list is shorter than the range needs. Always `true` for the `many` and `between` operators; not present for `one`, which fails instead of returning a partial result.
          example: true
    MapSelectorStep:
      type: object
      title: MapSelectorStep
      description: Transforms each item using an expression.
      required:
        - type
        - expression
      properties:
        type:
          type: string
          enum:
            - map
          description: A step discriminator of type `map`.
          example: map
        expression:
          type: string
          description: The attribute path each item is mapped to.
          example: $Item.Price
    ReduceSelectorStep:
      type: object
      title: ReduceSelectorStep
      description: Aggregates items into a single value.
      required:
        - type
        - operator
      properties:
        type:
          type: string
          enum:
            - reduce
          description: A step discriminator of type `reduce`.
          example: reduce
        operator:
          type: string
          enum:
            - max
            - min
            - sum
            - count
            - empty
          description: |
            The aggregation operator applied to the items produced by the preceding step:
            - `max`, `min`, and `sum` operate on numeric values.
            - `count` returns the number of items.
            - `empty` reports whether the list is empty.
          example: sum
    ReverseSelectorStep:
      type: object
      title: ReverseSelectorStep
      description: Reverses the order of the items.
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - reverse
          description: A step discriminator of type `reverse`.
          example: reverse
    SelectorValueMapRef:
      type: object
      title: SelectorValueMapRef
      description: A reference to a value map by its internal ID.
      required:
        - id
      properties:
        id:
          type: integer
          format: int64
          description: The internal ID of the referenced value map.
          example: 12
    FilterAndMapValuesSelectorStep:
      type: object
      title: FilterAndMapValuesSelectorStep
      description: Keeps items that exist in the value map, and attaches each kept item's mapped value.
      required:
        - type
        - valueMap
      properties:
        type:
          type: string
          enum:
            - filterAndMapValues
          description: A step discriminator of type `filterAndMapValues`.
          example: filterAndMapValues
        valueMap:
          $ref: '#/components/schemas/SelectorValueMapRef'
    SelectorStep:
      description: A single step in a selector item pipeline. The `type` field determines the step variant.
      oneOf:
        - $ref: '#/components/schemas/FilterSelectorStep'
        - $ref: '#/components/schemas/SortSelectorStep'
        - $ref: '#/components/schemas/SelectSelectorStep'
        - $ref: '#/components/schemas/MapSelectorStep'
        - $ref: '#/components/schemas/ReduceSelectorStep'
        - $ref: '#/components/schemas/ReverseSelectorStep'
        - $ref: '#/components/schemas/FilterAndMapValuesSelectorStep'
      discriminator:
        propertyName: type
        mapping:
          filter: '#/components/schemas/FilterSelectorStep'
          sort: '#/components/schemas/SortSelectorStep'
          select: '#/components/schemas/SelectSelectorStep'
          map: '#/components/schemas/MapSelectorStep'
          reduce: '#/components/schemas/ReduceSelectorStep'
          reverse: '#/components/schemas/ReverseSelectorStep'
          filterAndMapValues: '#/components/schemas/FilterAndMapValuesSelectorStep'
    Selector:
      type: object
      title: Selector
      description: A named pipeline of steps (filter, sort, map, etc.) that filters or transforms a list of cart items. Replaces `cartItemFilter` [bindings](https://docs.talon.one/management-api#tag/Campaigns/operation/getRuleset.responses.200.bindings) in V1 rulesets.
      required:
        - name
        - type
        - source
        - steps
      properties:
        name:
          type: string
          description: The name of the selector binding.
          example: discountedCartItems
        type:
          type: string
          enum:
            - selector
          description: A binding of type `selector`.
          example: selector
        source:
          type: string
          description: The attribute path the pipeline draws items from.
          example: $Session.CartItems
        steps:
          type: array
          description: Ordered pipeline steps applied to the source items.
          items:
            $ref: '#/components/schemas/SelectorStep'
    Bundle:
      type: object
      title: Bundle
      description: A named bundle definition consisting of selector sources with matching constraints. Replaces `bundle` [bindings](https://docs.talon.one/management-api#tag/Campaigns/operation/getRuleset.responses.200.bindings) in V1 rulesets.
      required:
        - name
        - type
        - sources
        - counts
      properties:
        id:
          type: string
          description: An identifier derived from the bundle content.
          example: 1b671a64-40d5-491e-99b0-da01ff1f3341
          readOnly: true
        name:
          type: string
          description: The name of the bundle.
          example: meal_deal
        type:
          type: string
          enum:
            - bundle
          description: A binding of type `bundle`.
          example: bundle
        sources:
          type: array
          description: The selector sources of bundle items. Each source is expressed as a `{{$selectorName}}` reference.
          items:
            type: string
          example:
            - '{{$mains}}'
            - '{{$drinks}}'
        counts:
          type: array
          description: The number of items to retrieve from each corresponding source in `sources`.
          items:
            type: integer
            format: int64
          example:
            - 1
            - 2
        matchers:
          type: array
          description: Attribute names that the bundled items must share.
          items:
            type: string
          example:
            - color
    TemplateParameter:
      type: object
      title: TemplateParameter
      description: A named parameter definition that exposes a configurable value in a campaign template. Replaces `templateParameter` [bindings](https://docs.talon.one/management-api#tag/Campaigns/operation/getRuleset.responses.200.bindings) in V1 rulesets.
      required:
        - name
        - value
        - valueType
        - description
      properties:
        name:
          type: string
          description: The name of the template parameter.
          example: minCartTotal
        value:
          description: The parameter's bound value. Its type depends on the `valueType`.
          example: 50
        valueType:
          type: string
          description: The data type of the value, derived from the bound expression (for example `number`, `string`, `boolean`, `percent`, `time`, `(list string)`, or `(list number)`).
          example: number
        minValue:
          type: number
          description: The minimum value allowed for this parameter.
          example: 0
        maxValue:
          type: number
          description: The maximum value allowed for this parameter.
          example: 10000
        description:
          type: string
          description: A human-readable description of the parameter shown when creating campaigns from the template.
          example: Minimum cart total to trigger the campaign.
        attribute:
          type: integer
          format: int64
          description: The ID of the attribute linked to this parameter. Omitted when the parameter is not linked to an attribute.
          example: 42
    RulesetV2:
      type: object
      title: RulesetV2
      description: Ruleset in the V2 JSON block format.
      required:
        - promotionRules
      properties:
        id:
          type: integer
          format: int64
          readOnly: true
          description: Internal ID of this entity.
          example: 6
        created:
          type: string
          format: date-time
          readOnly: true
          description: The time this entity was created.
        userId:
          type: integer
          format: int64
          readOnly: true
          description: The ID of the user that created this ruleset.
          example: 385
        campaignId:
          type: integer
          format: int64
          readOnly: true
          description: The ID of the campaign that owns this entity.
          example: 320
        templateId:
          type: integer
          format: int64
          readOnly: true
          description: The ID of the campaign template that owns this entity.
          example: 3
        activatedAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp indicating when this ruleset was activated.
        promotionRules:
          type: array
          description: Set of promotion rules.
          items:
            $ref: '#/components/schemas/RuleV2'
        strikethroughRules:
          type: array
          description: Set of strikethrough rules.
          items:
            $ref: '#/components/schemas/RuleV2'
        selectors:
          type: array
          readOnly: true
          description: Variable bindings of type selector.
          items:
            $ref: '#/components/schemas/Selector'
        bundles:
          type: array
          description: Variable bindings of type bundle.
          items:
            $ref: '#/components/schemas/Bundle'
        parameters:
          type: array
          description: Variable bindings of type template parameter.
          items:
            $ref: '#/components/schemas/TemplateParameter'
    UpdateCouponBatch:
      allOf:
        - $ref: '#/components/schemas/CouponConstraints'
        - type: object
          additionalProperties: false
          properties:
            attributes:
              type: object
              description: |
                Optional property to set the value of custom coupon attributes. They are defined in the Campaign Manager,
                see [Managing attributes](https://docs.talon.one/docs/product/account/dev-tools/managing-attributes).

                Coupon attributes can also be set to _mandatory_ in your Application [settings](https://docs.talon.one/docs/product/applications/using-attributes#making-attributes-mandatory).
                If your Application uses mandatory attributes, you must use this property to set their value.
            batchID:
              title: Batch ID
              type: string
              description: The ID of the batch the coupon(s) belong to.
    NewCoupons:
      allOf:
        - $ref: '#/components/schemas/CouponConstraints'
        - $ref: '#/components/schemas/CouponLimitConfigs'
        - type: object
          additionalProperties: false
          required:
            - numberOfCoupons
            - usageLimit
          properties:
            numberOfCoupons:
              type: integer
              description: The number of new coupon codes to generate for the campaign. Must be at least 1.
              minimum: 1
              maximum: 20000
              example: 1
            batchId:
              type: string
              description: The batch ID that all coupons created by the request will bear. If omitted, a batch ID is generated automatically.
              example: 3rdparty_fjsieoaa
            uniquePrefix:
              title: Coupon code unique prefix
              type: string
              deprecated: true
              description: |
                **DEPRECATED** To create more than 20,000 coupons in one request, use [Create coupons asynchronously](https://docs.talon.one/management-api#tag/Coupons/operation/createCouponsAsync) endpoint.
              example: ''
            attributes:
              type: object
              description: Arbitrary properties associated with this item.
              example:
                venueId: 12
            recipientIntegrationId:
              title: Receiving customer profile integration ID
              type: string
              maxLength: 1000
              description: The integration ID for this coupon's beneficiary's profile.
              example: URNGV8294NV
            validCharacters:
              type: array
              description: |
                List of characters used to generate the random parts of a code. By default,
                the list of characters is equivalent to the `[A-Z, 0-9]` regular expression.
              items:
                type: string
              example:
                - A
                - B
                - G
                - 'Y'
            couponPattern:
              type: string
              description: |
                The pattern used to generate coupon codes.
                The character `#` is a placeholder and is replaced by a random character from the `validCharacters` set.
              maxLength: 100
              minLength: 3
              example: SUMMER-#####
            isReservationMandatory:
              title: Is reservation mandatory
              type: boolean
              example: false
              description: An indication of whether the code can be redeemed only if it has been reserved first.
              default: false
            implicitlyReserved:
              title: Is coupon implicitly reserved for all customers
              description: An indication of whether the coupon is implicitly reserved for all customers.
              type: boolean
              example: false
            supportRequestId:
              type: integer
              format: int64
              description: The identifier of the support request to link to the coupon creation. The request must exist and not yet be processed.
              example: 42
            supportRequestNote:
              type: string
              description: A note recorded when the linked support request is approved or rejected. Applied when `supportRequestId` is provided.
              example: Approved as compensation for the delayed order.
    NewCouponsForMultipleRecipients:
      allOf:
        - $ref: '#/components/schemas/CouponConstraints'
        - type: object
          additionalProperties: false
          required:
            - recipientsIntegrationIds
            - usageLimit
          properties:
            batchId:
              type: string
              description: The batch ID that all coupons created by the request will bear. If omitted, a batch ID is generated automatically.
              example: 3rdparty_fjsieoaa
            attributes:
              type: object
              description: Arbitrary properties associated with this item.
              example:
                venueId: 12
            recipientsIntegrationIds:
              title: Receiving customer profiles integration IDs
              type: array
              example:
                - URNGV8294NV
                - BZGGC2454PA
              items:
                type: string
              description: The integration IDs for recipients.
              maxItems: 1000
              minItems: 1
            validCharacters:
              type: array
              description: |
                List of characters used to generate the random parts of a code. By default, the list of
                characters is equivalent to the `[A-Z, 0-9]` regular expression.
              example:
                - A
                - B
                - C
                - D
                - E
                - F
                - G
                - H
                - I
                - J
                - K
                - L
                - M
                - 'N'
                - O
                - P
                - Q
                - R
                - S
                - T
                - U
                - V
                - W
                - X
                - 'Y'
                - Z
              items:
                type: string
            couponPattern:
              type: string
              description: |
                The pattern used to generate coupon codes. The character `#` is a placeholder and is replaced by a random character from the `validCharacters` set.
              example: SUMMER-#####
              maxLength: 100
              minLength: 3
    NewCouponCreationJob:
      allOf:
        - $ref: '#/components/schemas/CouponConstraints'
        - type: object
          required:
            - numberOfCoupons
            - usageLimit
            - attributes
          additionalProperties: false
          properties:
            numberOfCoupons:
              type: integer
              description: The number of new coupon codes to generate for the campaign.
              minimum: 1
              maximum: 5000000
              example: 200000
            couponSettings:
              $ref: '#/components/schemas/CodeGeneratorSettings'
            attributes:
              type: object
              description: Arbitrary properties associated with coupons.
            isReservationMandatory:
              type: boolean
              example: false
              description: An indication of whether the code can be redeemed only if it has been reserved first.
              default: false
    AsyncCouponCreationResponse:
      type: object
      required:
        - batchId
      properties:
        batchId:
          type: string
          description: The batch ID that all coupons created by the request will have.
          example: tqyrgahe
    CouponDeletionFilters:
      type: object
      properties:
        createdBefore:
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          type: string
          format: date-time
        createdAfter:
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          type: string
          format: date-time
        startsAfter:
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          type: string
          format: date-time
        startsBefore:
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          type: string
          format: date-time
        valid:
          enum:
            - expired
            - validNow
            - validFuture
          description: |
            - `expired`: Matches coupons in which the expiration date is set and in the past.
            - `validNow`: Matches coupons in which the start date is null or in the past and the expiration date is null or in the future.
            - `validFuture`: Matches coupons in which the start date is set and in the future.
          type: string
        usable:
          type: boolean
          description: |
            - `true`: only coupons where `usageCounter < usageLimit` will be returned.
            - `false`: only coupons where `usageCounter >= usageLimit` will be returned.
            - This field cannot be used in conjunction with the `usable` query parameter.
        redeemed:
          type: boolean
          description: |
            - `true`: only coupons where `usageCounter > 0` will be returned.
            - `false`: only coupons where `usageCounter = 0` will be returned.

            **Note:** This field cannot be used in conjunction with the `usable` query parameter.
        recipientIntegrationId:
          description: |
            Filter results by match with a profile id specified in the coupon's `RecipientIntegrationId` field.
          type: string
        exactMatch:
          description: Filter results to an exact case-insensitive matching against the coupon code
          type: boolean
          default: false
        value:
          description: Filter results by the coupon code
          type: string
        batchId:
          description: Filter results by batches of coupons
          type: string
        referralId:
          description: Filter the results by matching them with the ID of a referral. This filter shows the coupons created by redeeming a referral code.
          type: integer
        expiresAfter:
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          type: string
          format: date-time
        expiresBefore:
          description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the coupon creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
          type: string
          format: date-time
    NewCouponDeletionJob:
      type: object
      required:
        - filters
      properties:
        filters:
          $ref: '#/components/schemas/CouponDeletionFilters'
    AsyncCouponDeletionJobResponse:
      allOf:
        - $ref: '#/components/schemas/IdentifiableEntity'
        - type: object
    UpdateCoupon:
      allOf:
        - $ref: '#/components/schemas/CouponConstraints'
        - $ref: '#/components/schemas/CouponLimitConfigs'
        - type: object
          additionalProperties: false
          properties:
            recipientIntegrationId:
              title: Receiving customer profile integration ID
              type: string
              maxLength: 1000
              description: The integration ID for this coupon's beneficiary's profile.
              example: URNGV8294NV
            attributes:
              type: object
              description: Arbitrary properties associated with this item.
            isReservationMandatory:
              title: Is reservation mandatory
              type: boolean
              example: false
              description: An indication of whether the code can be redeemed only if it has been reserved first.
              default: false
            implicitlyReserved:
              title: Is coupon implicitly reserved for all customers
              description: An indication of whether the coupon is implicitly reserved for all customers.
              type: boolean
              example: false
    UpdateReferral:
      type: object
      additionalProperties: false
      properties:
        friendProfileIntegrationId:
          type: string
          title: Friend's Profile ID
          description: An optional Integration ID of the Friend's Profile.
          example: BZGGC2454PA
          maxLength: 1000
        startDate:
          type: string
          format: date-time
          title: Referral code valid from
          description: Timestamp at which point the referral code becomes valid.
          example: '2020-11-10T23:00:00Z'
        expiryDate:
          type: string
          format: date-time
          title: Referral code valid until
          description: Expiration date of the referral code. Referral never expires if this is omitted.
          example: '2021-11-10T23:00:00Z'
        usageLimit:
          type: integer
          title: Referral code Usage Limit
          description: |
            The number of times a referral code can be used. This can be set to 0 for no limit, but any campaign usage limits will still apply.
          minimum: 0
          maximum: 999999
          example: 1
        attributes:
          type: object
          description: Arbitrary properties associated with this item.
    NewCampaignGroup:
      type: object
      properties:
        name:
          type: string
          description: The name of the campaign access group.
          minLength: 1
          example: Europe access group
        description:
          type: string
          description: A longer description of the campaign access group.
          example: A group that gives access to all the campaigns for the Europe market.
        subscribedApplicationsIds:
          type: array
          description: A list of IDs of the Applications that this campaign access group is enabled for.
          items:
            type: integer
          example:
            - 1
            - 2
            - 3
        campaignIds:
          type: array
          description: A list of IDs of the campaigns that are part of the campaign access group.
          items:
            type: integer
          example:
            - 4
            - 6
            - 8
      required:
        - name
    CampaignGroup:
      allOf:
        - $ref: '#/components/schemas/Entity'
        - $ref: '#/components/schemas/MutableEntity'
        - $ref: '#/components/schemas/AccountEntity'
        - $ref: '#/components/schemas/NewCampaignGroup'
        - type: object
    CampaignTemplateCouponReservationSettings:
      type: object
      properties:
        reservationLimit:
          type: integer
          minimum: 0
          maximum: 999999
          example: 45
          description: |
            The number of reservations that can be made with this coupon code.
        isReservationMandatory:
          title: Is reservation mandatory
          type: boolean
          example: false
          description: An indication of whether the code can be redeemed only if it has been reserved first.
          default: false
    TemplateLimitConfig:
      allOf:
        - $ref: '#/components/schemas/LimitConfig'
    CampaignTemplateParams:
      type: object
      required:
        - name
        - type
        - description
      properties:
        name:
          type: string
          description: Name of the campaign template parameter.
          minLength: 1
          example: discount_value
        type:
          type: string
          enum:
            - string
            - number
            - boolean
            - percent
            - (list string)
            - (list number)
            - time
          description: Defines the type of parameter value.
          example: number
        description:
          type: string
          description: Explains the meaning of this template parameter and the placeholder value that will define it. It is used on campaign creation from this template.
          example: This is a template parameter of type `number`.
        attributeId:
          type: integer
          description: ID of the corresponding attribute.
          example: 42
    CampaignTemplateCollection:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          minLength: 1
          pattern: ^[A-Za-z](\w|\s)*$
          description: The name of this collection.
          example: My collection
        description:
          type: string
          description: A short description of the purpose of this collection.
          example: My collection of SKUs
    UpdateCampaignTemplate:
      type: object
      required:
        - name
        - state
        - description
        - instructions
        - applicationsIds
      properties:
        name:
          type: string
          description: The campaign template name.
          minLength: 1
          example: Discount campaign
        description:
          type: string
          description: Customer-facing text that explains the objective of the template.
          example: This is a template for a discount campaign.
        instructions:
          type: string
          description: Customer-facing text that explains how to use the template. For example, you can use this property to explain the available attributes of this template, and how they can be modified when a user uses this template to create a new campaign.
          example: Use this template for discount campaigns. Set the campaign properties according to the campaign goals, and don't forget to set an end date.
        campaignAttributes:
          type: object
          description: The campaign attributes that campaigns created from this template will have by default.
        couponAttributes:
          type: object
          description: The campaign attributes that coupons created from this template will have by default.
        state:
          type: string
          enum:
            - draft
            - enabled
            - disabled
          description: Only campaign templates in 'available' state may be used to create campaigns.
        activeRulesetId:
          type: integer
          description: The ID of the ruleset this campaign template will use.
          example: 5
        tags:
          type: array
          description: A list of tags for the campaign template.
          maxItems: 50
          example:
            - discount
          items:
            type: string
            minLength: 1
            maxLength: 50
        reevaluateOnReturn:
          type: boolean
          description: Indicates whether campaigns created from this template should be reevaluated when a customer returns an item.
          example: true
        features:
          type: array
          description: A list of features for the campaign template.
          items:
            type: string
            enum:
              - coupons
              - referrals
              - loyalty
              - giveaways
              - strikethrough
              - achievements
              - advancedEvents
        couponSettings:
          $ref: '#/components/schemas/CodeGeneratorSettings'
        couponReservationSettings:
          $ref: '#/components/schemas/CampaignTemplateCouponReservationSettings'
        referralSettings:
          $ref: '#/components/schemas/CodeGeneratorSettings'
        limits:
          type: array
          description: The set of limits that operate for this campaign template.
          items:
            $ref: '#/components/schemas/TemplateLimitConfig'
        templateParams:
          type: array
          description: Fields which can be used to replace values in a rule.
          items:
            $ref: '#/components/schemas/CampaignTemplateParams'
        applicationsIds:
          type: array
          description: A list of IDs of the Applications that are subscribed to this campaign template.
          items:
            type: integer
          example:
            - 1
            - 2
            - 3
        campaignCollections:
          type: array
          description: The campaign collections from the blueprint campaign for the template.
          items:
            $ref: '#/components/schemas/CampaignTemplateCollection'
        defaultCampaignGroupId:
          type: integer
          description: The default campaign group ID.
          example: 42
        campaignType:
          type: string
          enum:
            - cartItem
            - advanced
          default: advanced
          example: advanced
          description: |
            The campaign type. Possible type values:
              - `cartItem`: Type of campaign that can apply effects only to cart items.
              - `advanced`: Type of campaign that can apply effects to customer sessions and cart items.
    CampaignTemplate:
      allOf:
        - $ref: '#/components/schemas/Entity'
        - $ref: '#/components/schemas/AccountEntity'
        - $ref: '#/components/schemas/UserEntity'
        - $ref: '#/components/schemas/UpdateCampaignTemplate'
        - type: object
          required:
            - validApplicationIds
            - applicationIds
            - campaignType
          properties:
            applicationsIds:
              type: array
              items:
                type: integer
              example:
                - 1
                - 2
                - 3
            campaignsCount:
              description: The number of Campaigns created from this template.
              type: integer
              example: 3
            updated:
              type: string
              format: date-time
              description: Timestamp of the most recent update to the campaign template or any of its elements.
              example: '2022-08-24T14:15:22Z'
            updatedBy:
              type: string
              description: Name of the user who last updated this campaign template, if available.
              example: Jane Doe
            validApplicationIds:
              type: array
              description: The IDs of the Applications that are related to this entity.
              items:
                type: integer
              example:
                - 1
                - 2
                - 3
            isUserFavorite:
              type: boolean
              description: A flag indicating whether the user marked the template as a favorite.
              default: false
              example: false
        - type: object
          required:
            - reevaluateOnReturn
    ExperimentVariant:
      allOf:
        - $ref: '#/components/schemas/Entity'
        - type: object
          required:
            - name
            - isPrimary
          properties:
            name:
              type: string
              example: Variant A
            experimentId:
              type: integer
              example: 10
            ruleset:
              $ref: '#/components/schemas/Ruleset'
            weight:
              type: integer
              example: 12
            isPrimary:
              type: boolean
              example: true
            audienceId:
              type: integer
              description: |
                The ID of the audience this variant targets. Only used when the experiment `assignmentType` is `audience`.
              example: 55
    Experiment:
      allOf:
        - $ref: '#/components/schemas/Entity'
        - $ref: '#/components/schemas/ApplicationEntity'
        - type: object
          properties:
            assignmentType:
              type: string
              enum:
                - random
                - external
                - audience
              description: |
                Controls how customers are assigned to experiment variants. - `random`: Talon.One assigns customers randomly based on variant weights. - `external`: Variant assignment is handled externally. - `audience`: Each variant targets a specific audience; customers are assigned based on audience membership.
              example: random
            isVariantAssignmentExternal:
              type: boolean
              deprecated: true
              description: |
                Deprecated. Use `assignmentType` instead. - false - The variant assignment is handled internally by Talon.One. - true - The variant assignment is handled externally.
            campaign:
              $ref: '#/components/schemas/Campaign'
            activated:
              type: string
              format: date-time
              description: |
                The date and time the experiment was activated.
            state:
              type: string
              enum:
                - enabled
                - disabled
                - archived
              default: disabled
              example: enabled
              description: |
                A disabled experiment is not evaluated for rules or coupons.
            variants:
              type: array
              items:
                $ref: '#/components/schemas/ExperimentVariant'
            goalType:
              type: string
              enum:
                - other
                - maximize_revenue
                - optimize_discount_efficiency
                - maximize_items_sold
              description: |
                The goal of the experiment. Determines which single metric is used to decide the winning variant. When set to `other`, multiple metrics are used.
            goalDescription:
              type: string
              description: |
                A description of the experiment goal. Provides context for the AI summary and helps it interpret the outcome of the experiment against the stated goal.
              example: Offering free shipping will increase average order revenue more than a 10% discount
            deletedat:
              type: string
              format: date-time
              description: |
                The date and time the experiment was deleted.
          required:
            - state
            - goalType
    CreateTemplateCampaign:
      type: object
      required:
        - name
        - templateId
      properties:
        name:
          type: string
          title: Campaign Name
          description: A user-facing name for this campaign.
          example: Discount campaign
          minLength: 1
        description:
          type: string
          title: Campaign Description
          description: A detailed description of the campaign.
          example: This template is for discount campaigns.
        templateId:
          type: integer
          description: The ID of the Campaign Template which will be used in order to create the Campaign.
          example: 4
        campaignAttributesOverrides:
          type: object
          description: Custom Campaign Attributes. If the Campaign Template defines the same values, they will be overridden.
        templateParamValues:
          type: array
          description: Actual values to replace the template placeholder values in the Ruleset bindings. Values for all Template Parameters must be provided.
          items:
            $ref: '#/components/schemas/Binding'
        limitOverrides:
          type: array
          description: Limits for this Campaign. If the Campaign Template or Application define default values for the same limits, they will be overridden.
          items:
            $ref: '#/components/schemas/LimitConfig'
        campaignGroups:
          type: array
          description: |
            The IDs of the [campaign groups](https://docs.talon.one/docs/product/account/account-settings/managing-campaign-groups) this campaign belongs to.
          example:
            - 1
            - 3
          items:
            type: integer
        tags:
          type: array
          description: A list of tags for the campaign. If the campaign template has tags, they will be overridden by this list.
          example:
            - summer
          maxItems: 50
          items:
            type: string
            minLength: 1
            maxLength: 50
        evaluationGroupId:
          type: integer
          example: 2
          description: The ID of the campaign evaluation group the campaign belongs to.
        linkedStoreIds:
          type: array
          description: |
            A list of store IDs that are linked to the campaign.

            **Note:** Campaigns with linked store IDs will only be evaluated when there is a
            [customer session update](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2)
            that references a linked store.
          items:
            type: integer
          example:
            - 1
            - 2
            - 3
    UpdateCollection:
      type: object
      properties:
        description:
          type: string
          description: A short description of the purpose of this collection.
          example: My collection of SKUs
        subscribedApplicationsIds:
          type: array
          description: A list of the IDs of the Applications where this collection is enabled.
          example:
            - 1
            - 2
            - 3
          items:
            type: integer
    NewCollection:
      allOf:
        - $ref: '#/components/schemas/UpdateCollection'
        - type: object
          required:
            - name
          properties:
            name:
              type: string
              minLength: 1
              pattern: ^[^[:cntrl:]\s][^[:cntrl:]]*$
              description: The name of this collection.
              example: My collection
    CollectionWithoutPayload:
      allOf:
        - $ref: '#/components/schemas/Entity'
        - $ref: '#/components/schemas/AccountEntity'
        - $ref: '#/components/schemas/MutableEntity'
        - $ref: '#/components/schemas/NewCollection'
        - type: object
          required:
            - createdBy
          properties:
            modifiedBy:
              type: integer
              description: ID of the user who last updated this effect if available.
              example: 48
            createdBy:
              type: integer
              description: ID of the user who created this effect.
              example: 134
            applicationId:
              type: integer
              description: The ID of the Application that owns this entity.
              example: 1
            campaignId:
              type: integer
              description: The ID of the campaign that owns this entity.
              example: 7
    Collection:
      allOf:
        - $ref: '#/components/schemas/CollectionWithoutPayload'
        - type: object
          properties:
            payload:
              type: array
              description: The content of the collection.
              maxItems: 50
              example:
                - KTL-WH-ET-1
                - KTL-BL-ET-1
              items:
                type: string
    CreateTemplateCampaignResponse:
      type: object
      required:
        - campaign
        - ruleset
      properties:
        campaign:
          $ref: '#/components/schemas/Campaign'
        ruleset:
          $ref: '#/components/schemas/Ruleset'
        collections:
          type: array
          items:
            $ref: '#/components/schemas/Collection'
    LoyaltyLedgerEntry:
      type: object
      description: A single row of the ledger, describing one addition or deduction.
      required:
        - programID
        - type
        - amount
        - created
        - name
        - subLedgerID
      properties:
        created:
          type: string
          format: date-time
          example: '2021-07-20T22:00:00Z'
        programID:
          type: integer
          example: 5
        customerProfileID:
          type: string
          example: URNGV8294NV
        cardID:
          type: integer
          example: 241
        customerSessionID:
          type: string
          example: t2gy5s-47274
        eventID:
          type: integer
          example: 5
        type:
          type: string
          description: |
            The type of the ledger transaction. Possible values are:
            - `addition`
            - `subtraction`
            - `expire`
            - `expiring` (for expiring points ledgers)
          example: addition
        amount:
          type: number
          example: 100
        startDate:
          type: string
          format: date-time
          example: '2021-07-20T22:00:00Z'
        expiryDate:
          type: string
          format: date-time
          example: '2022-07-20T22:00:00Z'
        name:
          type: string
          description: A name referencing the condition or effect that added this entry, or the specific name provided in an API call.
          example: Add points on purchase
        subLedgerID:
          type: string
          description: This specifies if we are adding loyalty points to the main ledger or a subledger.
          example: mysubledger
        userID:
          type: integer
          description: This is the ID of the user who created this entry, if the addition or subtraction was done manually.
          example: 499
        archived:
          type: boolean
          description: Indicates if the entry belongs to the archived session.
          example: false
        flags:
          $ref: '#/components/schemas/LoyaltyLedgerEntryFlags'
          description: A map of flags providing additional details about the entry.
        validityDuration:
          type: string
          description: |
            The duration for which the points remain active, relative to the  activation date.

            **Note**: This only applies to points for which `awaitsActivation` is `true` and `expiryDate` is not set.
          example: 30D
        awaitsActivation:
          type: boolean
          description: Indicates whether the points have an action-based start date. This property is returned only for point transactions with an action-based start date.
          example: false
    LoyaltyDashboardPointsBreakdown:
      type: object
      required:
        - createdManually
        - createdViaRuleEngine
      properties:
        createdManually:
          type: number
          example: 125
        createdViaRuleEngine:
          type: number
          example: 9631
    LoyaltyDashboardData:
      type: object
      description: Datapoint for the graphs and cards on a loyalty program dashboard.
      required:
        - date
        - totalActivePoints
        - totalPendingPoints
        - totalSpentPoints
        - totalExpiredPoints
        - totalNegativePoints
        - totalMembers
        - newMembers
        - spentPoints
        - earnedPoints
      properties:
        date:
          type: string
          format: date-time
          description: Date at which data point was collected.
        totalActivePoints:
          type: number
          description: Total of active points for this loyalty program.
          example: 9756
        totalPendingPoints:
          type: number
          description: Total of pending points for this loyalty program.
          example: 548
        totalSpentPoints:
          type: number
          description: Total of spent points for this loyalty program.
          example: 25668
        totalExpiredPoints:
          type: number
          description: Total of expired points for this loyalty program.
          example: 1156
        totalNegativePoints:
          type: number
          description: Total of negative points for this loyalty program.
          example: 32
        totalMembers:
          type: number
          description: Number of loyalty program members.
          example: 2582
        newMembers:
          type: number
          description: Number of members who joined on this day.
          example: 3
        spentPoints:
          $ref: '#/components/schemas/LoyaltyDashboardPointsBreakdown'
          description: Points spent on this day.
        earnedPoints:
          $ref: '#/components/schemas/LoyaltyDashboardPointsBreakdown'
          description: Points that were earned on this day.
    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.
    LoyaltySubLedger:
      type: object
      description: Ledger of Balance in Loyalty Program for a Customer.
      required:
        - total
        - totalActivePoints
        - totalPendingPoints
        - totalSpentPoints
        - totalExpiredPoints
        - totalNegativePoints
      properties:
        total:
          type: number
          deprecated: true
          title: Current Balance (Deprecated)
          description: |
            **DEPRECATED** Use `totalActivePoints` property instead. Total amount of currently active and available points in the customer's balance.
        totalActivePoints:
          type: number
          title: Current Balance
          description: Total amount of currently active and available points in the customer's balance.
        totalPendingPoints:
          type: number
          title: Total pending points
          description: Total amount of pending points, which are not active yet but will become active in the future.
        totalSpentPoints:
          type: number
          title: Total spent points
          description: Total amount of points already spent by this customer.
        totalExpiredPoints:
          type: number
          title: Total expired points
          description: Total amount of points, that expired without ever being spent.
        totalNegativePoints:
          type: number
          title: Total negative points
          description: Total amount of negative points. This implies that `totalActivePoints` is `0`.
        transactions:
          description: List of all events that have happened such as additions, subtractions and expiries.
          type: array
          items:
            $ref: '#/components/schemas/LoyaltyLedgerEntry'
        expiringPoints:
          description: List of all points that will expire.
          type: array
          items:
            $ref: '#/components/schemas/LoyaltyLedgerEntry'
        activePoints:
          description: List of all currently active points.
          type: array
          items:
            $ref: '#/components/schemas/LoyaltyLedgerEntry'
        pendingPoints:
          description: List of all points pending activation.
          type: array
          items:
            $ref: '#/components/schemas/LoyaltyLedgerEntry'
        expiredPoints:
          description: List of expired points.
          type: array
          items:
            $ref: '#/components/schemas/LoyaltyLedgerEntry'
        currentTier:
          $ref: '#/components/schemas/Tier'
          description: Tier for which the ledger is eligible.
    LoyaltyLedger:
      type: object
      description: Ledger of Balance in Loyalty Program for a Customer.
      required:
        - ledger
      properties:
        ledger:
          $ref: '#/components/schemas/LoyaltySubLedger'
          title: Customer's current loyalty program balance.
          description: The balance of the main ledger in the loyalty program.
        subLedgers:
          type: object
          description: A map containing a list of all loyalty subledger balances.
          additionalProperties:
            $ref: '#/components/schemas/LoyaltySubLedger'
          example:
            mysubledger:
              total: 0
              totalActivePoints: 286
              totalPendingPoints: 50
              totalSpentPoints: 150
              totalExpiredPoints: 25
              totalNegativePoints: 0
    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
    LoyaltyProgramTransaction:
      type: object
      required:
        - id
        - transactionUUID
        - created
        - programId
        - type
        - amount
        - name
        - subledgerId
        - startDate
        - expiryDate
      properties:
        id:
          type: integer
          description: ID of the loyalty ledger transaction.
          example: 123
        transactionUUID:
          type: string
          description: Unique identifier of the transaction in the UUID format.
          example: ce59f12a-f53b-4014-a745-636d93f2bd3f
        programId:
          type: integer
          description: ID of the loyalty program.
          example: 324
        campaignId:
          type: integer
          description: ID of the campaign.
          example: 324
        created:
          type: string
          format: date-time
          description: Date and time the loyalty transaction occurred.
          example: 2022-01-02T15:04:05Z07:00
        type:
          type: string
          enum:
            - addition
            - subtraction
          description: |
            Type of transaction. Possible values:
              - `addition`: Signifies added points.
              - `subtraction`: Signifies deducted points.
          maxLength: 255
          example: addition
        amount:
          type: number
          description: Amount of loyalty points added or deducted in the transaction.
          example: 10.25
        name:
          type: string
          description: Name or reason for the loyalty ledger transaction.
          maxLength: 255
          example: Reward 50 points for each $500 purchase
        startDate:
          type: string
          description: |
            When points become active. Possible values:
              - `immediate`: Points are immediately active.
              - `on_action`: Points become active based on the customer's action.
              - a timestamp value: Points become active at a given date and time.
          maxLength: 64
          example: 2022-01-02T15:04:05Z07:00
        expiryDate:
          type: string
          description: |
            When points expire. Possible values:
              - `unlimited`: Points have no expiration date.
              - a timestamp value: Points expire at a given date and time.
          example: 2022-01-02T15:04:05Z07:00
        customerProfileId:
          type: string
          description: Customer profile integration ID used in the loyalty program.
          maxLength: 255
          example: kda0fajs0-fad9f-fd9dfsa9-fd9dasjf9
        cardIdentifier:
          $ref: '#/components/schemas/LoyaltyCardIdentifier'
        subledgerId:
          type: string
          description: ID of the subledger.
          maxLength: 64
          example: sub-123
        customerSessionId:
          type: string
          description: ID of the customer session where the transaction occurred.
          maxLength: 255
          example: 05c2da0d-48fa-4aa1-b629-898f58f1584d
        importId:
          type: integer
          description: ID of the import where the transaction occurred.
          example: 4
        userId:
          type: integer
          description: ID of the user who manually added or deducted points. Applies only to manual transactions.
          example: 5
        userEmail:
          type: string
          description: The email of the Campaign Manager account that manually added or deducted points. Applies only to manual transactions.
          example: john.doe@example.com
        rulesetId:
          type: integer
          description: ID of the ruleset containing the rule that triggered the effect. Applies only for transactions that resulted from a customer session.
          example: 11
        ruleName:
          type: string
          description: Name of the rule that triggered the effect. Applies only for transactions that resulted from a customer session.
          example: 10 points for every $100 spent
        flags:
          $ref: '#/components/schemas/LoyaltyLedgerEntryFlags'
          description: The flags of the transaction, when applicable. The `createsNegativeBalance`  flag indicates whether the transaction results in a negative balance.
        validityDuration:
          type: string
          description: |
            The duration for which the points remain active, relative to the activation date.

            **Note**: This only applies to points for which `awaitsActivation` is `true` and `expiryDate` is not set.
          example: 30D
    LoyaltyCardBatch:
      allOf:
        - type: object
          required:
            - numberOfCards
          properties:
            numberOfCards:
              type: integer
              description: Number of loyalty cards in the batch.
              minimum: 1
              maximum: 20000
              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'
    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
    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:
              - `addition`: Signifies added points.
              - `subtraction`: Signifies deducted points.
          maxLength: 255
          example: addition
        name:
          type: string
          description: Name or reason of the loyalty ledger transaction.
          maxLength: 255
          example: Reward 10% points of a purchase's current total
        startDate:
          type: string
          description: |
            When points become active. Possible values:
              - `immediate`: Points are immediately active.
              - a timestamp value: Points become active at a given date and time.
          maxLength: 64
          example: 2022-01-02T15:04:05Z07:00
        expiryDate:
          type: string
          description: |
            Date when points expire. Possible values are:
              - `unlimited`: Points have no expiration date.
              - `timestamp value`: Points become active from the given date.
          example: 2022-08-02T15:04:05Z07:00
        subledgerId:
          type: string
          description: ID of the subledger.
          maxLength: 64
          example: sub-123
        amount:
          type: number
          description: Amount of loyalty points added or deducted in the transaction.
          example: 10.25
        id:
          type: integer
          description: ID of the loyalty ledger entry.
          example: 123
    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.
    NewGiveawaysPool:
      type: object
      required:
        - name
        - sandbox
      properties:
        name:
          type: string
          description: The name of this giveaway pool.
          example: My giveaway pool
        description:
          type: string
          description: The description of this giveaway pool.
          example: Generic pool
        subscribedApplicationsIds:
          type: array
          description: A list of the IDs of the Applications that this giveaway pool is enabled for.
          items:
            type: integer
          example:
            - 2
            - 4
        sandbox:
          type: boolean
          description: Indicates if this program is a live or sandbox program. Programs of a given type can only be connected to Applications of the same type.
          title: Sandbox
          example: true
    GiveawaysPool:
      description: A giveaway pool is an entity for managing multiple similar giveaways.
      allOf:
        - $ref: '#/components/schemas/Entity'
        - $ref: '#/components/schemas/AccountEntity'
        - $ref: '#/components/schemas/NewGiveawaysPool'
        - type: object
          required:
            - createdBy
          properties:
            modified:
              type: string
              format: date-time
              description: Timestamp of the most recent update to the giveaway pool.
            createdBy:
              type: integer
              description: ID of the user who created this giveaway pool.
            modifiedBy:
              type: integer
              description: ID of the user who last updated this giveaway pool if available.
    CollectionItem:
      allOf:
        - type: object
          required:
            - item
          properties:
            item:
              type: string
    UpdateCampaignCollection:
      type: object
      properties:
        description:
          type: string
          description: A short description of the purpose of this collection.
          example: My collection of SKUs
    NewCampaignCollection:
      allOf:
        - $ref: '#/components/schemas/UpdateCampaignCollection'
        - type: object
          required:
            - name
          properties:
            name:
              type: string
              minLength: 1
              pattern: ^[^[:cntrl:]\s][^[:cntrl:]]*$
              description: The name of this collection.
              example: My collection
    Session:
      type: object
      properties:
        userId:
          type: integer
          description: The ID of the user of this session.
          example: 109
        token:
          type: string
          description: The token to use as a bearer token to query Management API endpoints.
          example: dy_Fa_lQ4iDAnqldJFvVEmnsN8xDTxej19l0LZDBJhQ
        created:
          type: string
          format: date-time
          description: Unix timestamp indicating when the session was first created.
          example: '2021-07-20T22:00:00Z'
      required:
        - userId
        - token
        - created
    ApplicationApiHealth:
      type: object
      description: Report of health of the API connection of an application.
      required:
        - summary
        - lastUsed
      properties:
        summary:
          type: string
          description: |
            One-word summary of the health of the API connection of an application. Possible values are:
            - `OK`: The Application has received only successful API requests in the last 5 minutes.
            - `WARNING`: The Application received at least one failed request in the last 5 minutes.
            - `ERROR`: More than 50% of received requests failed.
            - `CRITICAL`: All received requests failed.
            - `NONE`: During the last 5 minutes, the Application hasn't recorded any integration API requests.
          enum:
            - OK
            - WARNING
            - ERROR
            - CRITICAL
            - NONE
        lastUsed:
          type: string
          format: date-time
          description: time of last request relevant to the API health test.
          example: '2021-09-12T10:12:42Z'
    AccessLogEntry:
      type: object
      description: Log of application accesses.
      required:
        - uuid
        - status
        - method
        - requestUri
        - time
        - requestPayload
        - responsePayload
      properties:
        uuid:
          type: string
          description: UUID reference of request.
          example: 606e7d34-2d36-4d53-ac71-d4442c325985
        status:
          type: integer
          description: HTTP status code of response.
          example: 200
        method:
          type: string
          description: HTTP method of request.
          example: PUT
        requestUri:
          type: string
          description: target URI of request
          example: /v2/customer_sessions/Session136667
        time:
          type: string
          format: date-time
          description: timestamp of request
          example: '2023-01-16T16:00:00.700763Z'
        requestPayload:
          type: string
          description: payload of request
          example: |-
            {
                "customerSession": {
                    "profileId": "customer123",
                    "state": "closed",
            ...
            }
        responsePayload:
          type: string
          description: payload of response
          example: '{"coupons":[],"createdCoupons":[],...}'
    CampaignAnalytics:
      allOf:
        - type: object
          required:
            - date
            - campaignRevenue
            - totalCampaignRevenue
            - campaignRefund
            - totalCampaignRefund
            - campaignDiscountCosts
            - totalCampaignDiscountCosts
            - campaignRefundedDiscounts
            - totalCampaignRefundedDiscounts
            - campaignFreeItems
            - totalCampaignFreeItems
            - referralRedemptions
            - totalReferralRedemptions
            - couponRedemptions
            - totalCouponRedemptions
            - couponRolledbackRedemptions
            - totalCouponRolledbackRedemptions
            - couponsCreated
            - totalCouponsCreated
            - referralsCreated
            - totalReferralsCreated
            - addedLoyaltyPoints
            - totalAddedLoyaltyPoints
            - deductedLoyaltyPoints
            - totalDeductedLoyaltyPoints
          properties:
            date:
              type: string
              format: date-time
              example: '2021-10-12T10:12:42Z'
            campaignRevenue:
              type: number
              description: Amount of revenue in this campaign (for coupon or discount sessions).
              example: 3539.76
            totalCampaignRevenue:
              type: number
              description: Amount of revenue in this campaign since it began (for coupon or discount sessions).
              example: 5784.63
            campaignRefund:
              type: number
              description: Amount of refunds in this campaign (for coupon or discount sessions).
            totalCampaignRefund:
              type: number
              description: Amount of refunds in this campaign since it began (for coupon or discount sessions).
            campaignDiscountCosts:
              type: number
              description: Amount of cost caused by discounts given in the campaign.
            totalCampaignDiscountCosts:
              type: number
              description: Amount of cost caused by discounts given in the campaign since it began.
            campaignRefundedDiscounts:
              type: number
              description: Amount of discounts rolledback due to refund in the campaign.
            totalCampaignRefundedDiscounts:
              type: number
              description: Amount of discounts rolledback due to refund in the campaign since it began.
            campaignFreeItems:
              type: integer
              description: Amount of free items given in the campaign.
            totalCampaignFreeItems:
              type: integer
              description: Amount of free items given in the campaign since it began.
              example: 86
            couponRedemptions:
              type: integer
              description: Number of coupon redemptions in the campaign.
            totalCouponRedemptions:
              type: integer
              description: Number of coupon redemptions in the campaign since it began.
            couponRolledbackRedemptions:
              type: integer
              description: Number of coupon redemptions that have been rolled back (due to canceling closed session) in the campaign.
            totalCouponRolledbackRedemptions:
              type: integer
              description: Number of coupon redemptions that have been rolled back (due to canceling closed session) in the campaign since it began.
            referralRedemptions:
              type: integer
              description: Number of referral redemptions in the campaign.
            totalReferralRedemptions:
              type: integer
              description: Number of referral redemptions in the campaign since it began.
            couponsCreated:
              type: integer
              description: Number of coupons created in the campaign by the rule engine.
            totalCouponsCreated:
              type: integer
              description: Number of coupons created in the campaign by the rule engine since it began.
            referralsCreated:
              type: integer
              description: Number of referrals created in the campaign by the rule engine.
            totalReferralsCreated:
              type: integer
              description: Number of referrals created in the campaign by the rule engine since it began.
            addedLoyaltyPoints:
              type: number
              description: Number of added loyalty points in the campaign in a specific interval.
              example: 250
            totalAddedLoyaltyPoints:
              type: number
              description: Number of added loyalty points in the campaign since it began.
              example: 340
            deductedLoyaltyPoints:
              type: number
              description: Number of deducted loyalty points in the campaign in a specific interval.
              example: 120
            totalDeductedLoyaltyPoints:
              type: number
              description: Number of deducted loyalty points in the campaign since it began.
              example: 220
    ApplicationCustomer:
      allOf:
        - $ref: '#/components/schemas/Entity'
        - $ref: '#/components/schemas/IntegrationEntity'
        - $ref: '#/components/schemas/CustomerProfile'
        - type: object
          required:
            - accountId
          properties:
            accountId:
              type: integer
              description: The ID of the Talon.One account that owns this profile.
            advocateIntegrationId:
              type: string
              maxLength: 1000
              description: The Integration ID of the Customer Profile that referred this Customer in the Application.
            loyaltyProgramJoinDates:
              type: array
              description: The dates on which the customer joined the profile-based loyalty programs they are part of. Returned only when the `withLoyaltyMemberships` query parameter is `true`.
              items:
                $ref: '#/components/schemas/LoyaltyMembership'
    CustomerProfileSearchQuery:
      type: object
      properties:
        attributes:
          type: object
          description: Properties to match against a customer profile. All provided attributes will be exactly matched against profile attributes.
        integrationIDs:
          type: array
          items:
            type: string
        profileIDs:
          type: array
          items:
            type: integer
    CustomerActivityReport:
      description: A summary report of customer activity for a given time range.
      allOf:
        - $ref: '#/components/schemas/IntegrationEntity'
        - type: object
          required:
            - name
            - customerId
            - integrationId
            - created
            - couponRedemptions
            - couponUseAttempts
            - couponFailedAttempts
            - accruedDiscounts
            - accruedRevenue
            - totalOrders
            - totalOrdersNoCoupon
            - campaignName
          properties:
            name:
              type: string
              description: The name for this customer profile.
            customerId:
              type: integer
              description: The internal Talon.One ID of the customer.
            lastActivity:
              type: string
              format: date-time
              description: The last activity of the customer.
            couponRedemptions:
              type: integer
              description: Number of coupon redemptions in all customer campaigns.
            couponUseAttempts:
              type: integer
              description: Number of coupon use attempts in all customer campaigns.
            couponFailedAttempts:
              type: integer
              description: Number of failed coupon use attempts in all customer campaigns.
            accruedDiscounts:
              type: number
              description: Number of accrued discounts in all customer campaigns.
            accruedRevenue:
              type: number
              description: Amount of accrued revenue in all customer campaigns.
            totalOrders:
              type: integer
              description: Number of orders in all customer campaigns.
            totalOrdersNoCoupon:
              type: integer
              description: Number of orders without coupon used in all customer campaigns.
            campaignName:
              type: string
              description: The name of the campaign this customer belongs to.
    CustomerAnalytics:
      description: A summary report of customer activity for a given time range.
      allOf:
        - type: object
          properties:
            acceptedCoupons:
              type: integer
              description: Total accepted coupons for this customer.
            createdCoupons:
              type: integer
              description: Total created coupons for this customer.
            freeItems:
              type: integer
              description: Total free items given to this customer.
            totalOrders:
              type: integer
              description: Total orders made by this customer.
            totalDiscountedOrders:
              type: integer
              description: Total orders made by this customer that had a discount.
            totalRevenue:
              type: number
              description: Total Revenue across all closed sessions.
            totalDiscounts:
              type: number
              description: The sum of discounts that were given across all closed sessions.
          required:
            - acceptedCoupons
            - createdCoupons
            - freeItems
            - totalOrders
            - totalDiscountedOrders
            - totalRevenue
            - totalDiscounts
    ApplicationCustomerEntity:
      type: object
      properties:
        profileId:
          type: integer
          description: The globally unique Talon.One ID of the customer that created this entity.
          example: 138
    ApplicationSession:
      allOf:
        - $ref: '#/components/schemas/Entity'
        - $ref: '#/components/schemas/IntegrationEntity'
        - $ref: '#/components/schemas/IntegrationStoreEntity'
        - $ref: '#/components/schemas/ApplicationEntity'
        - $ref: '#/components/schemas/ApplicationCustomerEntity'
        - type: object
          properties:
            profileintegrationid:
              type: string
              maxLength: 1000
              description: Integration ID of the customer for the session.
              example: 382370BKDB946
            coupon:
              type: string
              description: Any coupon code entered.
              example: BKDB946
            referral:
              type: string
              description: Any referral code entered.
              example: BKDB946
            state:
              type: string
              enum:
                - open
                - closed
                - partially_returned
                - cancelled
              description: |
                Indicates the current state of the session. Sessions can be created as `open` or `closed`. The state transitions are:

                1. `open` -> `closed`
                2. `open` -> `cancelled`
                3. `closed` -> `cancelled` or `partially_returned`
                4. `partially_returned` -> `cancelled`

                For more information, see [Customer session states](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions).
              example: closed
            cartItems:
              type: array
              description: Serialized JSON representation.
              items:
                $ref: '#/components/schemas/CartItem'
            discounts:
              type: object
              description: |
                **API V1 only.** A map of labeled discount values, in the same currency as the session.

                If you are using the V2 endpoints, refer to the `totalDiscounts` property instead.
              additionalProperties:
                type: number
            totalDiscounts:
              type: number
              description: |
                The total sum of the discounts applied to this session.

                **Note:** If more than one session is returned, this value is displayed as `0`.
              example: 100
            total:
              type: number
              description: The total sum of the session before any discounts applied.
              example: 200
            attributes:
              type: object
              description: Arbitrary properties associated with this item.
          required:
            - coupon
            - referral
            - state
            - cartItems
            - discounts
            - total
            - totalDiscounts
    ApplicationStoreEntity:
      type: object
      properties:
        storeId:
          type: integer
          description: The ID of the store.
    ApplicationEvent:
      allOf:
        - $ref: '#/components/schemas/Entity'
        - $ref: '#/components/schemas/ApplicationEntity'
        - $ref: '#/components/schemas/ApplicationCustomerEntity'
        - $ref: '#/components/schemas/ApplicationStoreEntity'
        - $ref: '#/components/schemas/IntegrationStoreEntity'
        - $ref: '#/components/schemas/EventV3Entity'
        - type: object
          required:
            - type
            - attributes
            - effects
          properties:
            sessionId:
              type: integer
              description: The globally unique Talon.One ID of the session that contains this event.
            type:
              type: string
              description: The name of the event. Must be a [custom event](https://docs.talon.one/docs/dev/concepts/entities/events#custom-events), not a built-in event.
            attributes:
              type: object
              description: Additional JSON serialized data associated with the event.
            effects:
              type: array
              description: An array containing the effects that were applied as a result of this event.
              items:
                $ref: '#/components/schemas/Effect'
            ruleFailureReasons:
              type: array
              description: An array containing the rule failure reasons which happened during this event.
              items:
                $ref: '#/components/schemas/RuleFailureReason'
    AudienceAnalytics:
      type: object
      description: The audiences and their member count.
      properties:
        audienceId:
          type: integer
          description: The ID of the audience.
          example: 1
        membersCount:
          type: integer
          description: The member count of the audience.
          example: 1234
    ApplicationReferee:
      allOf:
        - $ref: '#/components/schemas/ApplicationEntity'
        - type: object
          required:
            - sessionId
            - advocateIntegrationId
            - friendIntegrationId
            - code
            - created
          properties:
            sessionId:
              type: string
              description: Integration ID of the session in which the customer redeemed the referral.
            advancedEventIntegrationId:
              type: string
              maxLength: 1000
              description: The unique ID of the advanced event in which the customer redeemed the referral. Omitted when the referral was redeemed through a customer session rather than an advanced event.
              example: advanced_event_1234
            advocateIntegrationId:
              type: string
              maxLength: 1000
              title: Advocate's Profile ID
              description: Integration ID of the Advocate's Profile.
            friendIntegrationId:
              type: string
              maxLength: 1000
              title: Friend's Profile ID
              description: Integration ID of the Friend's Profile.
            code:
              type: string
              description: Advocate's referral code.
            created:
              type: string
              format: date-time
              description: Timestamp of the moment the customer redeemed the referral.
    AchievementAdditionalProperties:
      type: object
      required:
        - campaignId
        - userId
      properties:
        campaignId:
          type: integer
          description: The ID of the campaign the achievement belongs to.
          example: 1
        userId:
          type: integer
          description: ID of the user that created this achievement.
          example: 1234
        createdBy:
          type: string
          description: |
            Name of the user that created the achievement.

            **Note**: This is not available if the user has been deleted.
          example: John Doe
        hasProgress:
          type: boolean
          description: Indicates if a customer has made progress in the achievement.
        status:
          type: string
          enum:
            - inprogress
            - expired
            - not_started
            - completed
          example: inprogress
          description: The status of the achievement.
    Achievement:
      allOf:
        - $ref: '#/components/schemas/Entity'
        - $ref: '#/components/schemas/CreateAchievement'
        - $ref: '#/components/schemas/AchievementAdditionalProperties'
        - type: object
    NewAdditionalCost:
      allOf:
        - type: object
          required:
            - name
            - title
            - description
          properties:
            name:
              type: string
              pattern: ^[A-Za-z]\w*$
              description: The internal name used in API requests.
              example: shippingFee
            title:
              type: string
              pattern: ^[A-Za-z][A-Za-z0-9_.!~*'() -]*$
              description: The human-readable name for the additional cost that will be shown in the Campaign Manager. Like `name`, the combination of entity and title must also be unique.
              example: Shipping fee
            description:
              type: string
              description: A description of this additional cost.
              example: A shipping fee
            subscribedApplicationsIds:
              type: array
              description: A list of the IDs of the applications that are subscribed to this additional cost.
              items:
                type: integer
              example:
                - 3
                - 13
            type:
              type: string
              enum:
                - session
                - item
                - both
              example: session
              description: |
                The type of additional cost. Possible value:
                - `session`: Additional cost will be added per session.
                - `item`: Additional cost will be added per item.
                - `both`: Additional cost will be added per item and session.
              default: session
    AccountAdditionalCost:
      allOf:
        - $ref: '#/components/schemas/Entity'
        - $ref: '#/components/schemas/AccountEntity'
        - $ref: '#/components/schemas/NewAdditionalCost'
    NewApplicationCIF:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: The name of the Application cart item filter used in API requests.
          example: Filter items by product
        description:
          type: string
          description: A short description of the Application cart item filter.
          example: This filter allows filtering by shoes
        activeExpressionId:
          type: integer
          description: The ID of the expression that the Application cart item filter uses.
          example: 1
        modifiedBy:
          type: integer
          description: The ID of the user who last updated the Application cart item filter.
          example: 334
        createdBy:
          type: integer
          description: The ID of the user who created the Application cart item filter.
          example: 216
        modified:
          type: string
          format: date-time
          description: Timestamp of the most recent update to the Application cart item filter.
    ApplicationCIF:
      allOf:
        - $ref: '#/components/schemas/Entity'
        - $ref: '#/components/schemas/NewApplicationCIF'
        - type: object
          required:
            - applicationId
          properties:
            applicationId:
              type: integer
              description: The ID of the Application that owns this entity.
              example: 322
    InfluencingCampaignDetails:
      type: object
      description: Details about a campaign that influenced the final price.
      properties:
        campaignId:
          type: integer
          description: Identifier of the campaign that influenced the final price.
        discountValue:
          type: number
          description: Discount value applied by the campaign.
      required:
        - campaignId
        - discountValue
    AdjustmentDetails:
      type: object
      description: Details about an applied price adjustment.
      properties:
        referenceId:
          type: string
          description: The reference identifier used during an `ADD_PRICE_ADJUSTMENT` action.
          example: 68851723-e6fa-488f-ace9-112581e6c19b
        selectedPriceType:
          type: string
          description: The selected price type for the SKU targeted by this effect.
          example: member
        value:
          type: number
          description: The value of the applied price adjustment.
      required:
        - referenceId
        - selectedPriceType
        - value
    BestPriorPriceMetadata:
      type: object
      description: Auxiliary data for found price observation.
      properties:
        influencingCampaignDetails:
          type: array
          description: Details about campaigns that influenced the final price.
          items:
            $ref: '#/components/schemas/InfluencingCampaignDetails'
        adjustmentDetails:
          $ref: '#/components/schemas/AdjustmentDetails'
          type: object
          description: Details about the applied price adjustment.
      required:
        - influencingCampaignDetails
    PriceHistoryRequest:
      type: object
      required:
        - sku
        - endDate
        - startDate
      properties:
        sku:
          type: string
          description: The SKU of the item for which the historical prices are being retrieved.
          example: SKU1241028
        startDate:
          type: string
          format: date-time
          description: The start date of the period for which historical prices should be retrieved.
          example: '2020-11-10T23:00:00Z'
        endDate:
          type: string
          format: date-time
          description: The end date of the period for which historical prices should be retrieved.
          example: '2020-12-10T23:00:00Z'
    History:
      type: object
      required:
        - id
        - observedAt
        - price
        - contextIds
        - metadata
        - target
      properties:
        id:
          type: integer
          description: The ID of the historical price.
          example: 1
        observedAt:
          type: string
          format: date-time
          description: The date and time when the price was observed.
          example: '2025-11-10T23:00:00Z'
        contextIds:
          type: array
          items:
            type: string
          description: |
            The identifiers of the relevant context (the sales events, e.g. "Spring Sale", "Summer Sale") at the time the price was observed. Includes the context IDs of any price adjustments and of the campaigns that influenced the final price.
          example:
            - SpringSale
            - SummerSale2025
        price:
          type: number
          description: Price of the item.
          example: 99.99
        metadata:
          $ref: '#/components/schemas/BestPriorPriceMetadata'
        target:
          $ref: '#/components/schemas/LabelTarget'
        excludedAt:
          type: string
          format: date-time
          description: The date and time when the historical price ID was excluded.
          example: '2025-11-10T23:00:00Z'
        exclusionReason:
          type: string
          description: The reason for excluding this historical price ID.
          example: Incorrect contextID value
    PriceHistoryResponse:
      type: object
      required:
        - sku
        - history
      properties:
        sku:
          type: string
          description: The SKU of the item for which historical prices should be retrieved.
          example: SKU1241028
        history:
          type: array
          items:
            $ref: '#/components/schemas/History'
    ExcludePriceObservationsRequest:
      type: object
      required:
        - ids
        - reason
      properties:
        ids:
          description: |
            A list of historical price IDs to exclude from best prior price calculation. Must contain between 1 and 1000 IDs. All IDs must be valid `id` values obtained from the [Get summary of price history](https://docs.talon.one/management-api#tag/Catalogs/operation/priceHistory.responses.200.history) endpoint, must belong to the specified Application, and must not already be excluded from best prior price calculation.
          type: array
          items:
            type: integer
            format: int64
            minimum: 1
          minItems: 1
          uniqueItems: true
          maxItems: 1000
        reason:
          description: |
            The reason for excluding these historical price IDs. Applies to all IDs in the batch.
          type: string
          example: Incorrect contextID value.
          minLength: 1
    ItemAttribute:
      allOf:
        - type: object
          required:
            - attributeid
            - name
            - value
          properties:
            attributeid:
              type: integer
              description: The ID of the attribute of the item.
              example: 6
            name:
              type: string
              description: The name of the attribute.
            value:
              description: The value of the attribute.
    CatalogItem:
      allOf:
        - $ref: '#/components/schemas/Entity'
        - type: object
          required:
            - sku
            - catalogid
            - version
          properties:
            sku:
              type: string
              description: The stock keeping unit of the item.
              example: SKU1241028
            price:
              type: number
              description: Price of the item.
              example: 99.99
            catalogid:
              type: integer
              description: The ID of the catalog the item belongs to.
              example: 6
            version:
              type: integer
              minimum: 1
              description: The version of the catalog item.
              example: 5
            attributes:
              type: array
              items:
                $ref: '#/components/schemas/ItemAttribute'
            product:
              $ref: '#/components/schemas/Product'
    WebhookWithOutgoingIntegrationDetails:
      allOf:
        - $ref: '#/components/schemas/Webhook'
        - type: object
          properties:
            outgoingIntegrationTemplateId:
              type: integer
              description: Identifier of the outgoing integration template.
              example: 1
            outgoingIntegrationTypeId:
              type: integer
              description: Identifier of the outgoing integration type.
              example: 1
            outgoingIntegrationTypeName:
              type: string
              description: Name of the outgoing integration.
              example: Braze
    MessageLogRequest:
      type: object
      description: Details of the request.
      required:
        - createdAt
        - request
      properties:
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the request was made.
          example: '2021-07-20T21:59:00Z'
        request:
          type: string
          format: byte
          description: Raw request data.
          example: SGVsbG8sIHdvcmxkIQ==
    MessageLogResponse:
      type: object
      description: Details of the response.
      properties:
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the response was received.
          example: '2021-07-20T22:00:50Z'
        response:
          type: string
          format: byte
          description: Raw response data.
          example: UmVzcG9uc2UgY29udGVudA==
        status:
          type: integer
          description: HTTP status code of the response.
          example: 200
    MessageLogEntry:
      type: object
      description: Message Log.
      required:
        - service
        - createdAt
        - id
        - entityType
      properties:
        id:
          type: string
          description: Unique identifier of the message.
          example: 123e4567-e89b-12d3-a456-426614174000
        service:
          type: string
          description: Name of the service that generated the log entry.
          example: NotificationService
        changeType:
          type: string
          description: Type of change that triggered the notification.
          example: Update
        notificationId:
          type: integer
          description: ID of the notification.
          example: 101
        notificationName:
          type: string
          description: The name of the notification.
          example: My campaign notification
        webhookId:
          type: integer
          description: ID of the webhook.
          example: 101
        webhookName:
          type: string
          description: The name of the webhook.
          example: My webhook
        request:
          $ref: '#/components/schemas/MessageLogRequest'
        response:
          $ref: '#/components/schemas/MessageLogResponse'
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the log entry was created.
          example: '2021-07-20T22:00:00Z'
        entityType:
          type: string
          description: |
            The entity type the log is related to.
          enum:
            - application
            - loyalty_program
            - webhook
          example: loyalty_program
        url:
          type: string
          description: The target URL of the request.
          example: www.my-company.com/my-endpoint-name
        applicationId:
          type: integer
          description: Identifier of the Application.
          example: 5
          minimum: 1
        loyaltyProgramId:
          type: integer
          description: Identifier of the loyalty program.
          example: 2
          minimum: 1
        campaignId:
          type: integer
          description: Identifier of the campaign.
          example: 2
          minimum: 1
    MessageLogEntries:
      type: object
      required:
        - data
      properties:
        nextCursor:
          description: |
            The next value in the database.

            **Note:** If this value is not present, it means that there are no more values in the database for this combination of request parameters.
          type: string
          format: byte
          example: SmJlNERRMHdyNWFsTmRDZDVYU0c=
        data:
          type: array
          description: List of message logs.
          items:
            $ref: '#/components/schemas/MessageLogEntry'
    NewEventType:
      allOf:
        - type: object
          required:
            - title
            - name
          properties:
            title:
              type: string
              minLength: 1
              description: The human-friendly name for this event type.
              example: Survey Completed
            name:
              type: string
              minLength: 1
              description: The integration name for this event type. This will be used in URLs and cannot be changed after an event type has been created.
              example: surveyCompleted
            description:
              type: string
              description: |
                A description of what the event represents.
              example: The survey was submitted by the customer.
    EventType:
      allOf:
        - $ref: '#/components/schemas/Entity'
        - $ref: '#/components/schemas/NewEventType'
    EmailEntity:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
          example: john.doe@example.com
          description: The email address associated with the user profile.
    User:
      allOf:
        - $ref: '#/components/schemas/Entity'
        - $ref: '#/components/schemas/MutableEntity'
        - $ref: '#/components/schemas/EmailEntity'
        - $ref: '#/components/schemas/AccountEntity'
        - type: object
          required:
            - inviteToken
            - state
            - name
            - policy
          properties:
            name:
              type: string
              description: Name of the user.
              example: John Doe
            state:
              type: string
              enum:
                - invited
                - active
                - deactivated
              description: State of the user.
              example: invited
            inviteToken:
              type: string
              description: |
                Invitation token of the user.

                **Note**: If the user has already accepted their invitation, this is `null`.
              example: Gy9b8w1irmQtEPo5RmbMmSPheL5h4
            isAdmin:
              type: boolean
              description: Indicates whether the user is an `admin`.
              example: false
            policy:
              type: object
              format: acl
              description: Access level of the user.
              example:
                Role: 127
                Applications: null
            roles:
              type: array
              description: A list of the IDs of the roles assigned to the user.
              example:
                - 71
              items:
                type: integer
            authMethod:
              type: string
              description: Authentication method for this user.
              example: basic_auth
            applicationNotificationSubscriptions:
              type: object
              description: Application notifications that the user is subscribed to.
              example: {}
            lastSignedIn:
              type: string
              format: date-time
              description: Timestamp when the user last signed in to Talon.One.
              example: '2021-09-12T10:12:42Z'
            lastAccessed:
              type: string
              format: date-time
              description: Timestamp of the user's last activity after signing in to Talon.One.
              example: '2021-09-12T10:14:42Z'
            latestFeedTimestamp:
              type: string
              format: date-time
              description: Timestamp when the user was notified for feed.
              example: '2020-06-01T00:00:00Z'
            additionalAttributes:
              type: object
              description: Additional user attributes, created and used by external identity providers.
              example: {}
    UpdateUser:
      type: object
      properties:
        name:
          type: string
          description: Name of the user.
          example: John Doe
        state:
          type: string
          enum:
            - deactivated
            - active
          description: |
            The state of the user.
              - `deactivated`: The user has been deactivated.
              - `active`: The user is active.

            **Note**: Only `admin` users can update the state of another user.
          example: deactivated
        isAdmin:
          type: boolean
          description: Indicates whether the user is an `admin`.
          example: false
        policy:
          type: string
          description: Indicates the access level of the user.
          example:
            Role: 127
            Applications: null
        roles:
          type: array
          items:
            type: integer
          description: |
            A list of the IDs of the roles assigned to the user.

            **Note**: To find the ID of a role, use the [List roles](/management-api#tag/Roles/operation/listAllRolesV2) endpoint.
          example:
            - 1
            - 3
        applicationNotificationSubscriptions:
          type: object
          description: Application notifications that the user is subscribed to.
    ScimGroupMember:
      type: object
      description: Member of the SCIM group. In Talon.One, the member is a [user](https://docs.talon.one/docs/product/account/account-settings/managing-users) assigned to a specific role.
      properties:
        value:
          type: string
          description: Unique identifier of the member.
          example: '258'
        display:
          type: string
          description: Identifier of the user. This is usually an email address.
          example: john.doe@example.com
    ScimBaseGroup:
      type: object
      description: Define the schema for base fields in a group using the SCIM provisioning protocol. Talon.One uses this schema to create roles.
      properties:
        displayName:
          type: string
          description: Display name of the group (Talon.One role).
          example: Manager
        members:
          type: array
          description: List of members to assign to the new Talon.One role.
          items:
            $ref: '#/components/schemas/ScimGroupMember'
    ScimGroup:
      type: object
      description: |-
        Define the schema for groups created using the SCIM provisioning protocol.
        In Talon.One, a `Group` corresponds to a [role](https://docs.talon.one/docs/product/account/account-settings/managing-roles), and `members` are the [users](https://docs.talon.one/docs/product/account/account-settings/managing-users) assigned to that role.
      allOf:
        - $ref: '#/components/schemas/ScimBaseGroup'
        - type: object
          required:
            - id
          properties:
            id:
              type: string
              description: ID of the group.
              example: '359'
    ScimGroupsListResponse:
      type: object
      description: |-
        List of groups created using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID.
        In Talon.One, a `Group` corresponds to a [role](https://docs.talon.one/docs/product/account/account-settings/managing-roles), and `members` are the [users](https://docs.talon.one/docs/product/account/account-settings/managing-users) assigned to that role.
      required:
        - Resources
      properties:
        Resources:
          type: array
          items:
            $ref: '#/components/schemas/ScimGroup'
        schemas:
          type: array
          description: SCIM schema for the given resource.
          items:
            type: string
            example: urn:ietf:params:scim:api:messages:2.0:ListResponse
        totalResults:
          type: integer
          description: Number of results in the response.
      example:
        Resources:
          - displayName: Manager Role
            id: '283'
            meta:
              resourceType: Group
              created: '2024-06-25T17:43:46+02:00'
            members:
              - value: '15'
                display: john.doe@example.com
            schemas:
              - urn:ietf:params:scim:schemas:core:2.0:Group
        schemas:
          - urn:ietf:params:scim:api:messages:2.0:ListResponse
        totalResults: 1
    ScimPatchOperation:
      type: object
      description: Patch operation that is used to update the information.
      required:
        - op
      properties:
        op:
          type: string
          enum:
            - add
            - remove
            - replace
          description: The method that should be used in the operation.
        path:
          type: string
          description: The path specifying the attribute that should be updated.
        value:
          type: string
          description: The value that should be updated. Required if `op` is `add` or `replace`.
      example:
        op: add
        path: nickName
        value: John
    ScimPatchRequest:
      type: object
      description: SCIM Patch request
      required:
        - Operations
      properties:
        schemas:
          type: array
          description: SCIM schema for the given resource.
          items:
            type: string
            example: urn:ietf:params:scim:api:messages:2.0:PatchOp
        Operations:
          type: array
          items:
            $ref: '#/components/schemas/ScimPatchOperation'
      example:
        Operations:
          - op: replace
            path: active
            value: test
          - op: add
            path: nickName
            value: johndoe
        schemas:
          - urn:ietf:params:scim:api:messages:2.0:PatchOp
    ScimBaseUser:
      type: object
      description: Schema definition for base user fields, provisioned using the SCIM protocol and used by Talon.One.
      properties:
        active:
          type: boolean
          description: Status of the user.
          example: true
        displayName:
          type: string
          description: Display name of the user.
          example: John Doe
        userName:
          type: string
          description: Unique identifier of the user. This is usually an email address.
          example: john.doe@example.com
        name:
          type: object
          description: The components of the user's real name.
          properties:
            formatted:
              type: string
              description: The full name, including all middle names, titles, and suffixes as appropriate, formatted for display.
              example: Mr. John J Doe
    ScimNewUser:
      type: object
      description: Payload for users that are created using the SCIM provisioning protocol with an identity provider, for example, Microsoft Entra ID.
      required:
        - userName
      allOf:
        - $ref: '#/components/schemas/ScimBaseUser'
        - type: object
          description: Additional user properties, that are not processed by Talon.One, but only stored and returned in the User response.
    ScimUser:
      type: object
      description: Schema definition for users that have been provisioned using the SCIM protocol with an identity provider, for example, Microsoft Entra ID.
      allOf:
        - $ref: '#/components/schemas/ScimNewUser'
        - type: object
          required:
            - id
          properties:
            id:
              type: string
              description: ID of the user.
              example: '359'
    ScimUsersListResponse:
      type: object
      description: List of users that have been provisioned using the SCIM protocol with an identity provider, for example, Microsoft Entra ID.
      required:
        - Resources
      properties:
        Resources:
          type: array
          items:
            $ref: '#/components/schemas/ScimUser'
        schemas:
          type: array
          description: SCIM schema for the given resource.
          items:
            type: string
            example: urn:ietf:params:scim:api:messages:2.0:ListResponse
        totalResults:
          type: integer
          description: Number of total results in the response.
      example:
        Resources:
          - active: true
            displayName: John Doe
            id: '283'
            meta:
              resourceType: User
              created: '2024-06-25T17:43:46+02:00'
            userName: john.doe@example.com
            schemas:
              - urn:ietf:params:scim:schemas:core:2.0:User
              - urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
        schemas:
          - urn:ietf:params:scim:api:messages:2.0:ListResponse
        totalResults: 1
    ScimResource:
      type: object
      description: Resource definition for the SCIM provisioning protocol.
      properties:
        id:
          type: string
          description: ID of the resource.
        name:
          type: string
          description: Name of the resource.
        description:
          type: string
          description: Human-readable description of the resource.
      example:
        id: User
        name: User
        description: User Account
    ScimResourceTypesListResponse:
      type: object
      description: List of resource types supported by the SCIM provisioning protocol.
      required:
        - Resources
      properties:
        Resources:
          type: array
          items:
            $ref: '#/components/schemas/ScimResource'
    ScimServiceProviderConfigResponse:
      type: object
      description: Service provider configuration details.
      properties:
        bulk:
          type: object
          description: Configuration related to bulk operations, which allow multiple SCIM requests to be processed in a single HTTP request.
          properties:
            maxOperations:
              type: integer
              description: The maximum number of individual operations that can be included in a single bulk request.
            maxPayloadSize:
              type: integer
              description: The maximum size, in bytes, of the entire payload for a bulk operation request.
            supported:
              type: boolean
              description: Indicates whether the SCIM service provider supports bulk operations.
        changePassword:
          type: object
          description: Configuration settings related to the ability to change user passwords.
          properties:
            supported:
              type: boolean
              description: Indicates whether the service provider supports password changes via the SCIM API.
        documentationUri:
          type: string
          description: The URI that points to the SCIM service provider's documentation, providing further details about the service's capabilities and usage.
        filter:
          type: object
          description: Configuration settings related to filtering SCIM resources based on specific criteria.
          properties:
            maxResults:
              type: integer
              description: The maximum number of resources that can be returned in a single filtered query response.
            supported:
              type: boolean
              description: Indicates whether the SCIM service provider supports filtering operations.
        patch:
          type: object
          description: Configuration settings related to patch operations, which allow partial updates to SCIM resources.
          properties:
            supported:
              type: boolean
              description: Indicates whether the service provider supports patch operations for modifying resources.
        schemas:
          type: array
          description: A list of SCIM schemas that define the structure and data types supported by the service provider.
          items:
            type: string
        sort:
          type: object
          description: Configuration settings related to sorting SCIM resources in query responses.
          properties:
            supported:
              type: boolean
              description: Indicates whether the service provider supports sorting operations for ordered query results.
      example:
        bulk:
          maxOperations: 1000
          maxPayloadSize: 1048576
          supported: true
        changePassword:
          supported: false
        documentationUri: example.com/scim/docs
        filter:
          maxResults: 100
          supported: true
        patch:
          supported: true
        schemas:
          - urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig
        x-sort:
          supported: false
    ScimSchemaResource:
      type: object
      description: Resource schema definition for the SCIM provisioning protocol.
      properties:
        id:
          type: string
          description: ID of the resource.
        name:
          type: string
          description: Name of the resource.
        description:
          type: string
          description: Human-readable description of the schema resource.
        attributes:
          type: array
          items:
            type: object
            description: Key-value attributes of the resource.
      example:
        id: urn:ietf:params:scim:schemas:core:2.0:User
        name: User
        description: User Account
        attributes:
          - name: userName
            required: true
            mutability: readWrite
          - name: profileUrl
            required: false
            mutability: readWrite
    ScimSchemasListResponse:
      type: object
      description: List of resource schemas supported by the SCIM provisioning protocol.
      required:
        - Resources
      properties:
        Resources:
          type: array
          items:
            $ref: '#/components/schemas/ScimSchemaResource'
        schemas:
          type: array
          description: SCIM schema for the given resource.
          items:
            type: string
            example: urn:ietf:params:scim:api:messages:2.0:ListResponse
        totalResults:
          type: integer
          description: Number of total results in the response.
    DeleteUserRequest:
      allOf:
        - $ref: '#/components/schemas/EmailEntity'
    ActivateUserRequest:
      allOf:
        - $ref: '#/components/schemas/EmailEntity'
    DeactivateUserRequest:
      allOf:
        - $ref: '#/components/schemas/EmailEntity'
    NewExternalInvitation:
      type: object
      description: Parameters for inviting a new user from an external identity provider.
      required:
        - email
      properties:
        name:
          type: string
          description: Name of the user.
          example: John Doe
        userGroups:
          type: array
          items:
            type: string
          description: |
            List of user groups in the external identity provider.

            If there are roles in Talon.One whose names match these user groups,
            those roles will be automatically assigned to the user upon invitation.
          example:
            - Managers
            - Customer support
        email:
          type: string
          format: email
          description: Email address of the user.
          example: john.doe@example.com
    Change:
      allOf:
        - $ref: '#/components/schemas/Entity'
        - $ref: '#/components/schemas/UserEntity'
        - type: object
          required:
            - entity
          properties:
            applicationId:
              type: integer
              description: ID of application associated with change.
              example: 359
            entity:
              type: string
              description: API endpoint on which the change was initiated.
              example: /v1/applications/359/campaigns/6727
            old:
              type: object
              description: Resource before the change occurred.
              example: {}
            new:
              type: object
              description: Resource after the change occurred.
              example:
                applicationId": 359
                attributes": {}
                campaignGroups": []
                created": '2022-07-08T13:04:02.972762328Z'
                description": ''
                features":
                  - referrals
                  - loyalty
                id: 6727
            managementKeyId:
              type: integer
              description: ID of management key used to perform changes.
              example: 3
    NewInvitation:
      type: object
      description: Parameters for inviting a new user.
      required:
        - email
      properties:
        name:
          type: string
          description: Name of the user.
          example: John Doe
        email:
          type: string
          format: email
          description: Email address of the user.
          example: john.doe@example.com
        isAdmin:
          type: boolean
          description: Indicates whether the user is an `admin`.
          example: false
        roles:
          type: array
          description: A list of the IDs of the roles assigned to the user.
          items:
            type: integer
            example: 13
        acl:
          type: string
          description: Indicates the access level of the user.
    NewInviteEmail:
      type: object
      required:
        - email
        - token
      properties:
        email:
          type: string
          description: Email address of the user.
          format: email
          example: john.doe@example.com
        token:
          type: string
          description: Invitation token of the user.
          example: Gy9b8w1irmQtEPo5RmbMmSPheL5h4
    LoginParams:
      allOf:
        - $ref: '#/components/schemas/EmailEntity'
        - type: object
          properties:
            password:
              type: string
              description: The password for your account.
              example: admin123456
          required:
            - password
    NewPasswordEmail:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
          minLength: 1
    NewPassword:
      type: object
      required:
        - password
        - resetToken
      properties:
        password:
          type: string
          description: The new password for your account.
          example: Admin&12943!7
        resetToken:
          type: string
          minLength: 1
          example: Z2VgacVNkexLKBUIzsRDDZSGxnIkC53y
    NewAccount:
      type: object
      required:
        - companyName
      properties:
        companyName:
          type: string
          minLength: 1
    Account:
      allOf:
        - $ref: '#/components/schemas/Entity'
        - $ref: '#/components/schemas/MutableEntity'
        - $ref: '#/components/schemas/NewAccount'
        - type: object
          required:
            - domainName
            - state
            - billingEmail
            - applicationCount
            - userCount
            - campaignsActiveCount
            - campaignsInactiveCount
          properties:
            domainName:
              type: string
              description: Subdomain Name for yourcompany.talon.one.
            state:
              type: string
              enum:
                - active
                - deactivated
              description: State of the account (active, deactivated).
            billingEmail:
              type: string
              format: email
              description: The billing email address associated with your company account.
            planName:
              type: string
              description: The name of your booked plan.
            planExpires:
              type: string
              format: date-time
              description: The point in time at which your current plan expires.
            applicationLimit:
              type: integer
              description: The maximum number of Applications covered by your plan.
            userLimit:
              type: integer
              description: The maximum number of Campaign Manager Users covered by your plan.
            campaignLimit:
              type: integer
              description: The maximum number of Campaigns covered by your plan.
            apiLimit:
              type: integer
              description: The maximum number of Integration API calls covered by your plan per billing period.
            applicationCount:
              type: integer
              description: The current number of Applications in your account.
            userCount:
              type: integer
              description: The current number of Campaign Manager Users in your account.
            campaignsActiveCount:
              type: integer
              description: The current number of active Campaigns in your account.
            campaignsInactiveCount:
              type: integer
              description: The current number of inactive Campaigns in your account.
            attributes:
              type: object
              description: Arbitrary properties associated with this campaign.
    AccountAnalytics:
      type: object
      required:
        - applications
        - liveApplications
        - sandboxApplications
        - campaigns
        - activeCampaigns
        - liveActiveCampaigns
        - coupons
        - activeCoupons
        - expiredCoupons
        - referralCodes
        - activeReferralCodes
        - expiredReferralCodes
        - activeRules
        - users
        - roles
        - customAttributes
        - webhooks
        - loyaltyPrograms
        - liveLoyaltyPrograms
        - lastUpdatedAt
      properties:
        applications:
          type: integer
          description: Total number of applications in the account.
          example: 11
        liveApplications:
          type: integer
          description: Total number of live applications in the account.
          example: 6
        sandboxApplications:
          type: integer
          description: Total number of sandbox applications in the account.
          example: 2
        campaigns:
          type: integer
          description: Total number of campaigns in the account.
          example: 35
        activeCampaigns:
          type: integer
          description: Total number of active campaigns in the account.
          example: 15
        liveActiveCampaigns:
          type: integer
          description: Total number of active campaigns in live applications in the account.
          example: 10
        coupons:
          type: integer
          description: Total number of coupons in the account.
          example: 850
        activeCoupons:
          type: integer
          description: Total number of active coupons in the account.
          example: 650
        expiredCoupons:
          type: integer
          description: Total number of expired coupons in the account.
          example: 200
        referralCodes:
          type: integer
          description: Total number of referral codes in the account.
          example: 500
        activeReferralCodes:
          type: integer
          description: Total number of active referral codes in the account.
          example: 100
        expiredReferralCodes:
          type: integer
          description: Total number of expired referral codes in the account.
          example: 400
        activeRules:
          type: integer
          description: Total number of active rules in the account.
          example: 35
        users:
          type: integer
          description: Total number of users in the account.
        roles:
          type: integer
          description: Total number of roles in the account.
          example: 10
        customAttributes:
          type: integer
          description: Total number of custom attributes in the account.
          example: 18
        webhooks:
          type: integer
          description: Total number of webhooks in the account.
          example: 2
        loyaltyPrograms:
          type: integer
          description: Total number of all loyalty programs in the account.
          example: 5
        liveLoyaltyPrograms:
          type: integer
          description: Total number of live loyalty programs in the account.
          example: 5
        lastUpdatedAt:
          type: string
          format: date-time
          description: The point in time when the analytics numbers were updated last.
          example: '2022-12-12T12:12:12Z'
    Export:
      allOf:
        - $ref: '#/components/schemas/Entity'
        - $ref: '#/components/schemas/AccountEntity'
        - $ref: '#/components/schemas/UserEntity'
        - type: object
          required:
            - entity
            - filter
          properties:
            entity:
              type: string
              enum:
                - Coupon
                - Referral
                - Effect
                - CustomerSession
                - LoyaltyLedger
                - LoyaltyLedgerLog
                - Collection
              description: The name of the entity that was exported.
            filter:
              type: object
              description: Map of keys and values that were used to filter the exported rows.
    RoleV2PermissionSet:
      type: object
      required:
        - name
        - logicalOperations
      properties:
        name:
          type: string
          description: Name of the permission set.
          example: Campaign manager permission set
        logicalOperations:
          type: array
          maxItems: 1000
          description: |
            List of logical operations in the permission set.
          items:
            type: string
          example:
            - createCampaignOperations
            - getCampaignOperations
            - deleteCampaignOperations
    RoleV2ApplicationDetails:
      type: object
      description: Details of the permission sets configured for an Application.
      properties:
        application:
          type: string
          description: Name of the Application-related permission set for the given Application.
          example: Application permission set
        campaign:
          type: string
          description: Name of the campaign-related permission set for the given Application.
          example: Campaign manager permission set
        draftCampaign:
          type: string
          description: Name of the draft campaign-related permission set for the given Application.
          example: Campaign read-only permission set
        tools:
          type: string
          description: Name of the tools-related permission set.
          example: Tools permission set
    RoleV2Application:
      type: object
      description: A map of the link between the Application, campaign, or draft campaign-related permission set and the Application ID the permissions apply to.
      additionalProperties:
        $ref: '#/components/schemas/RoleV2ApplicationDetails'
        type: object
      example:
        '1':
          application: Application permission set
        '3':
          campaign: Campaign manager permission set
        '4':
          draftCampaign: Campaign read-only permission set
        '5':
          tools: Tools permission set
    RoleV2LoyaltyGroup:
      type: object
      description: A map of the link between the loyalty program-related permission set and the loyalty program ID the permissions apply to.
      additionalProperties:
        type: string
        description: Name of the loyalty program-related permission set.
      example:
        '10': Loyalty program manager permission set
    RoleV2CampaignAccessGroup:
      type: object
      description: A map of the link between the campaign access group-related permission set and the campaign access group ID the permissions apply to.
      additionalProperties:
        type: string
        description: Name of the campaign access group-related permission set.
      example:
        '5': Campaign access group manager permission set
    RoleV2RolesGroup:
      type: object
      description: A map of target entities to their permission sets.
      properties:
        applications:
          $ref: '#/components/schemas/RoleV2Application'
          type: object
        loyaltyPrograms:
          $ref: '#/components/schemas/RoleV2LoyaltyGroup'
          type: object
        campaignAccessGroups:
          $ref: '#/components/schemas/RoleV2CampaignAccessGroup'
          type: object
        account:
          type: string
          description: Name of the account-level permission set.
          example: Account administration permission set
    RolesV2Thresholds:
      type: object
      description: Support user limits for actions that require admin approval within the given loyalty program.
      properties:
        loyaltyProgramId:
          type: integer
          description: Identifier of 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: 8
        loyaltyPointsLimit:
          type: integer
          description: Maximum number of loyalty points a support user can award without approval.
          example: 100
    RoleV2Permissions:
      type: object
      description: The permissions that this role gives.
      properties:
        permissionSets:
          type: array
          description: List of grouped logical operations referenced by roles.
          maxItems: 500
          items:
            $ref: '#/components/schemas/RoleV2PermissionSet'
            type: object
          example:
            - name: Application permission set
              logicalOperations:
                - getApplicationOperations
                - editApplicationOperations
            - name: Campaign manager permission set
              logicalOperations:
                - getCampaignOperations
                - createCampaignOperations
                - updateCampaignOperations
            - name: Campaign read-only permission set
              logicalOperations:
                - getCampaignOperations
            - name: Loyalty program read-only permission set
              logicalOperations:
                - getLoyaltyProgramOperations
            - name: Campaign access group manager permission set
              logicalOperations:
                - getCampaignAccessGroupOperations
                - updateCampaignAccessGroupOperations
                - deleteCampaignAccessGroupOperations
        roles:
          $ref: '#/components/schemas/RoleV2RolesGroup'
          type: object
        thresholds:
          type: array
          description: Support user limits for actions that require admin approval within the given application.
          items:
            $ref: '#/components/schemas/RolesV2Thresholds'
    RoleV2Base:
      type: object
      properties:
        name:
          type: string
          description: Name of the role.
          example: Campaign and campaign access group manager
        description:
          type: string
          description: Description of the role.
          example: Allows you to create and edit campaigns for specific Applications, delete specific campaign access groups, and view loyalty programs.
        permissions:
          $ref: '#/components/schemas/RoleV2Permissions'
          type: object
          description: The permissions that this role gives.
        members:
          type: array
          items:
            type: integer
          description: A list of user IDs the role is assigned to.
          example:
            - 10
            - 12
    RoleV2Readonly:
      type: object
      properties:
        isReadonly:
          type: boolean
          example: false
          description: Identifies if the role is read-only. For read-only roles, you can only assign or unassign users. You cannot edit any other properties, such as the name, description, or permissions. This property cannot be set for new or existing roles. It is reserved for predefined roles, such as the Talon.One support role.
          default: false
    RoleV2:
      description: Represents a role with its associated permissions and members.
      allOf:
        - $ref: '#/components/schemas/Entity'
        - $ref: '#/components/schemas/MutableEntity'
        - $ref: '#/components/schemas/AccountEntity'
        - $ref: '#/components/schemas/RoleV2Base'
        - $ref: '#/components/schemas/RoleV2Readonly'
    UpdateStore:
      type: object
      required:
        - name
        - description
      properties:
        name:
          type: string
          description: The name of the store.
          example: South US store
          minLength: 1
          maxLength: 200
        description:
          type: string
          description: The description of the store.
          example: This is the description of the store in south US.
        attributes:
          type: object
          description: The attributes of the store.
          example:
            country: USA
            code: 1234
    NewStore:
      allOf:
        - $ref: '#/components/schemas/UpdateStore'
        - type: object
          required:
            - integrationId
          properties:
            integrationId:
              type: string
              format: string
              example: STORE-001
              maxLength: 1000
              minLength: 1
              description: |
                The integration ID of the store. You choose this ID when you create a store.

                **Note**: You cannot edit the `integrationId` after the store has been created.
    Store:
      allOf:
        - $ref: '#/components/schemas/Entity'
        - $ref: '#/components/schemas/NewStore'
        - type: object
          required:
            - updated
            - applicationId
            - integrationId
            - created
          properties:
            created:
              type: string
              format: date-time
              description: The time this entity was created.
              example: '2020-02-07T08:15:22Z'
            applicationId:
              type: integer
              description: The ID of the Application that owns this entity.
              example: 322
            updated:
              type: string
              format: date-time
              description: Timestamp of the most recent update on this entity.
              example: '2021-09-23T10:12:42Z'
            linkedCampaignIds:
              type: array
              description: A list of IDs of the campaigns that are linked with current store.
              items:
                type: integer
              example:
                - 4
                - 6
                - 8
    NewApplicationCIFExpression:
      type: object
      properties:
        cartItemFilterId:
          type: integer
          description: The ID of the Application cart item filter.
          example: 216
        createdBy:
          type: integer
          description: The ID of the user who created the Application cart item filter.
          example: 216
        expression:
          type: array
          description: Arbitrary additional JSON data associated with the Application cart item filter.
          example:
            expr:
              - filter
              - - '.'
                - Session
                - CartItems
              - - - Item
                - - catch
                  - false
                  - - contains
                    - - '.'
                      - Item
                      - Category
                    - Kitchen
          items: {}
    ApplicationCIFExpression:
      allOf:
        - $ref: '#/components/schemas/Entity'
        - $ref: '#/components/schemas/NewApplicationCIFExpression'
        - type: object
          required:
            - applicationId
          properties:
            applicationId:
              type: integer
              description: The ID of the Application that owns this entity.
              example: 322
    ListCampaignStoreBudgetsStore:
      type: object
      required:
        - id
        - integrationId
        - name
      properties:
        id:
          type: integer
        integrationId:
          type: string
        name:
          type: string
    ListCampaignStoreBudgets:
      type: object
      required:
        - store
        - limit
        - action
      properties:
        store:
          $ref: '#/components/schemas/ListCampaignStoreBudgetsStore'
          type: object
        limit:
          type: integer
        action:
          type: string
        period:
          type: string
    NewCampaignStoreBudgetStoreLimit:
      type: object
      required:
        - storeId
        - limit
      properties:
        storeId:
          type: integer
          description: |
            The ID of the store.
            You can get this ID with the [List stores](#tag/Stores/operation/listStores) endpoint.
          example: 17
        limit:
          type: number
          example: 1000
          description: The value to set for the limit.
    NewCampaignStoreBudget:
      type: object
      required:
        - action
        - storeLimits
      properties:
        action:
          type: string
          enum:
            - setDiscount
        storeLimits:
          type: array
          description: The set of budget limits for stores linked to the campaign.
          items:
            $ref: '#/components/schemas/NewCampaignStoreBudgetStoreLimit'
        period:
          type: string
          enum:
            - daily
            - weekly
            - monthly
            - yearly
    SummaryCampaignStoreBudget:
      type: object
      required:
        - action
        - storeCount
        - imported
      properties:
        action:
          type: string
          enum:
            - redeemCoupon
            - redeemReferral
            - setDiscount
            - setDiscountEffect
            - createCoupon
            - createReferral
            - createLoyaltyPoints
            - redeemLoyaltyPoints
            - customEffect
            - createLoyaltyPointsEffect
            - redeemLoyaltyPointsEffect
            - callApi
            - awardGiveaway
            - addFreeItemEffect
            - reserveCoupon
        period:
          type: string
          enum:
            - overall
            - daily
            - weekly
            - monthly
            - yearly
        storeCount:
          type: integer
        imported:
          type: boolean
    UpdateAchievement:
      allOf:
        - $ref: '#/components/schemas/AchievementBase'
    AchievementBaseV2:
      type: object
      properties:
        name:
          type: string
          pattern: ^[a-zA-Z]\w+$
          example: Order50Discount
          maxLength: 1000
          minLength: 1
          description: |
            The internal name of the achievement used in API requests.

            **Note**: The name should start with a letter. This cannot be changed after the achievement has been created.
        title:
          type: string
          description: The display name for the achievement in the Campaign Manager.
          example: 50% off on 50th purchase.
        description:
          type: string
          format: string
          description: A description of the achievement.
          example: 50% off for every 50th purchase in a year.
        target:
          type: number
          description: The required number of actions or the transactional milestone to complete the achievement.
          example: 50
        period:
          type: string
          description: |
            The relative duration after which the achievement ends and resets for a particular customer profile.

            **Note**: The `period` does not start when the achievement is created.

            The period is a **positive real number** followed by one letter indicating the time unit.

            Examples: `30s`, `40m`, `1h`, `5D`, `7W`, `10M`, `15Y`.

            Available units:

            - `s`: seconds
            - `m`: minutes
            - `h`: hours
            - `D`: days
            - `W`: weeks
            - `M`: months
            - `Y`: years

            You can also round certain units down to the beginning of period and up to the end of period.:
            - `_D` for rounding down days only. Signifies the start of the day.
            Example: `30D_D`
            - `_U` for rounding up days, weeks, months and years. Signifies the end of the day, week, month or year.
            Example: `23W_U`

            **Note**: You can either use the round down and round up option or set an absolute period.
          example: 1Y
        recurrencePolicy:
          type: string
          enum:
            - no_recurrence
            - on_expiration
            - on_completion
          example: no_recurrence
          description: |
            The policy that determines if and how the achievement recurs.
            - `no_recurrence`: The achievement can be completed only once.
            - `on_expiration`: The achievement resets after it expires and becomes available again.
            - `on_completion`: When the customer progress status reaches `completed`, the achievement resets and becomes available again.
        activationPolicy:
          type: string
          enum:
            - user_action
            - fixed_schedule
          example: fixed_schedule
          description: |
            The policy that determines how the achievement starts, ends, or resets.
            - `user_action`: The achievement ends or resets relative to when the customer started the achievement.
            - `fixed_schedule`: The achievement starts, ends, or resets for all customers following a fixed schedule.
        fixedStartDate:
          type: string
          format: date-time
          example: '2024-01-15T15:04:05+07:00'
          description: |
            The achievement's start date when `activationPolicy` is set to `fixed_schedule`.

            **Note:** It must be an RFC3339 timestamp string.
        endDate:
          type: string
          format: date-time
          example: '2024-01-15T15:04:05+07:00'
          description: |
            The achievement's end date. If defined, customers cannot participate in the achievement after this date.

            **Note:** It must be an RFC3339 timestamp string.
        allowRollbackAfterCompletion:
          type: boolean
          description: When `true`, customer progress can be rolled back in completed achievements.
          example: false
        subscribedApplications:
          type: array
          description: A list containing the IDs of all applications that are subscribed to A list containing the IDs of all Applications that are connected to this achievement.
          items:
            type: integer
          minItems: 0
          example:
            - 132
            - 97
    AchievementAdditionalPropertiesV2:
      type: object
      required:
        - userId
      properties:
        userId:
          type: integer
          description: The ID of the user that created this achievement.
          example: 1234
        createdBy:
          type: string
          description: |
            Name of the user that created the achievement.

            **Note**: This is not available if the user has been deleted.
          example: John Doe
        periodEndOverride:
          $ref: '#/components/schemas/TimePoint'
          deprecated: true
        hasProgress:
          type: boolean
          description: Indicates if a customer has made progress in the achievement.
        status:
          type: string
          enum:
            - active
            - scheduled
            - expired
          example: active
          description: |
            The status of the achievement.                                                                                              
            - `active`: The achievement is available to customers.
            - `scheduled`: The achievement has a `fixedStartDate` set in the future.
            - `expired`: The achievement's `endDate` is in the past.
    AchievementV2:
      allOf:
        - $ref: '#/components/schemas/Entity'
        - $ref: '#/components/schemas/AchievementBaseV2'
        - $ref: '#/components/schemas/AchievementAdditionalPropertiesV2'
        - type: object
          required:
            - name
            - title
            - description
            - target
            - recurrencePolicy
            - activationPolicy
            - sandbox
            - subscribedApplications
            - timezone
            - referencedByCampaigns
          properties:
            sandbox:
              type: boolean
              description: Indicates if this achievement is a live or sandbox achievement. Achievements of a given type can only be connected to Applications of the same type.
              title: Sandbox
              example: true
            timezone:
              type: string
              description: A string containing an IANA timezone descriptor.
              minLength: 1
              example: Europe/Berlin
            campaignId:
              type: integer
              deprecated: true
              description: This property is **deprecated**. Use `referencedByCampaigns` instead. This field contains the first campaign ID from the related `referencedByCampaigns`, and is omitted when `referencedByCampaigns` is empty.
              example: 3
            referencedByCampaigns:
              type: array
              description: The campaigns that reference this achievement. They are sorted in ascending order by their id.
              items:
                $ref: '#/components/schemas/CampaignReference'
    CreateAchievementV2:
      allOf:
        - $ref: '#/components/schemas/AchievementBaseV2'
        - type: object
          required:
            - name
            - title
            - description
            - target
            - timezone
            - sandbox
          properties:
            sandbox:
              type: boolean
              description: Indicates if this achievement is a live or sandbox achievement. Achievements of a given type can only be connected to Applications of the same type.
              title: Sandbox
              example: true
            timezone:
              type: string
              description: A string containing an IANA timezone descriptor.
              minLength: 1
              example: Europe/Berlin
    UpdateAchievementV2:
      allOf:
        - $ref: '#/components/schemas/AchievementBaseV2'
        - type: object
          required:
            - name
            - title
            - description
            - target
            - subscribedApplications
    CouponFailureSummary:
      type: object
      description: Summary of the reasons for coupon redemption failure.
      required:
        - id
        - eventID
        - couponCode
        - language
        - status
        - summary
        - createdAt
        - updatedAt
      properties:
        id:
          type: integer
          description: ID of the evaluation record.
          example: 1
        eventID:
          type: integer
          description: ID of the event.
          example: 1011
        sessionID:
          type: string
          description: ID of the customer session set by your integration layer.
          example: 1
        profileID:
          type: string
          description: ID of the customer profile set by your integration layer.
          example: a48f10dddb5c9493aad194e49bb9c1dac
        status:
          type: string
          description: Status defines if the coupon code was applied or rejected.
          example: rejected
        couponCode:
          type: string
          description: Coupon code passed for evaluation.
          example: ABC123
        language:
          type: string
          description: Language of the summary.
          example: en
        summary:
          type: string
          description: A summary of the reasons for coupon redemption failure.
          example: Session total was less than the required total.
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the request was made.
          example: '2021-07-20T21:59:00Z'
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the request was last updated.
          example: '2021-07-20T21:59:00Z'
  requestBodies:
    AttributeQuery:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AttributeQuery'
      description: body
      required: true
    AddLoyaltyPoints:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AddLoyaltyPoints'
      description: body
      required: true
    NewRulesetV2:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RulesetV2'
      description: body
      required: true
    DeductLoyaltyPoints:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DeductLoyaltyPoints'
      description: body
      required: true
    CustomerProfileSearchQuery:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CustomerProfileSearchQuery'
      description: body
      required: true
    PriceHistory:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PriceHistoryRequest'
      description: body
      required: true
    ExcludePriceObservations:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExcludePriceObservationsRequest'
      description: body
      required: true
    NewAttribute:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NewAttribute'
      description: body
      required: true
    NewAdditionalCost:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NewAdditionalCost'
      description: body
      required: true
    ScimNewGroup:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ScimBaseGroup'
      description: body
      required: true
    ScimNewUser:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ScimNewUser'
      description: body
      required: true
    NewInvitation:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NewInvitation'
      description: body
      required: true
    NewStore:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NewStore'
      description: body
      required: true
  parameters:
    skip:
      name: skip
      in: query
      required: false
      description: The number of items to skip when paging through large result sets.
      example: 100
      schema:
        type: integer
    applicationId:
      name: applicationId
      in: path
      required: true
      description: The ID of the Application. It is displayed in your Talon.One deployment URL.
      example: 42
      schema:
        type: integer
    campaignId:
      name: campaignId
      in: path
      description: The ID of the campaign. It is displayed in your Talon.One deployment URL.
      example: 18
      required: true
      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