Talon.One Applications API

openapi: 3.2.0
info:
  title: Management Applications API
  version: ''
  description: 'The Management API allows you to programmatically do what the Campaign Manager

    does.'
servers:
- url: https://yourbaseurl.talon.one
security:
- manager_auth: []
- management_key: []
tags:
- name: Applications
  description: 'Represents an Application in the Campaign Manager.

    An Application is the target of every Integration API request to Talon.One.


    One Application can hold various API keys used for Integration API requests.


    You may have multiple Applications within one account,

    for example staging and production, or different international markets.


    See the docs.'
paths:
  /v1/applications:
    get:
      operationId: getApplications
      summary: List Applications
      description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.


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


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


        Display the health of the Application and show the last time the Application

        was used.


        You can also find this information in the Campaign Manager. In your Application, click **Settings** > **Integration API Keys**.

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


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


          **Note**: If no `name` is provided, all the Application cart item filters in the Application are returned.

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


        Get an Application cart item filter expression for a specific Application.'
      tags:
      - Applications
      parameters:
      - $ref: '#/components/parameters/applicationId'
      - name: cartItemFilterId
        in: path
        description: The ID of the Application cart item filter. You can get this ID with the [List Application cart item filters](https://docs.talon.one/management-api#tag/Applications/operation/listApplicationCartItemFilters) endpoint.
        example: 20
        required: true
        schema:
          type: integer
      - name: expressionId
        in: path
        description: The ID of the Application cart item filter expression.
        example: 19
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationCIFExpression'
components:
  parameters:
    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
    skip:
      name: skip
      in: query
      required: false
      description: The number of items to skip when paging through large result sets.
      example: 100
      schema:
        type: integer
    pageSize:
      name: pageSize
      in: query
      required: false
      description: The number of items in the response.
      example: 1000
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 1000
    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
  schemas:
    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.
    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: {}
    AccountEntity:
      type: object
      required:
      - accountId
      properties:
        accountId:
          type: integer
          description: The ID of the account that owns this entity.
          example: 3886
    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
    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.
    LoyaltyProgramEntity:
      type: object
      required:
      - programID
      properties:
        programID:
          type: integer
          description: The ID of the loyalty program that owns this entity.
          example: 125
        programName:
          type: string
          description: The integration name of the loyalty program that owns this entity.
          example: Loyalty_program
        programTitle:
          type: string
          description: The Campaign Manager-displayed name of the loyalty program that owns this entity.
          example: Loyalty program
    CodeGeneratorSettings:
      type: object
      properties:
        validCharacters:
          type: array
          description: 'List of characters used to generate the random parts of a code.

            '
          example:
          - A
          - B
          - C
          - D
          - E
          - F
          - G
          - H
          - I
          - J
          - K
          - L
          - M
          - N
          - O
          - P
          - Q
          - R
          - S
          - T
          - U
          - V
          - W
          - X
          - Y
          - Z
          - '0'
          - '1'
          - '2'
          - '3'
          - '4'
          - '5'
          - '6'
          - '7'
          - '8'
          - '9'
          items:
            type: string
        couponPattern:
          type: string
          description: 'The pattern used to generate codes, such as coupon codes, referral codes, and loyalty cards. The character `#` is a placeholder and is replaced by a random character from the `validCharacters` set.

            '
          maxLength: 100
          minLength: 3
          pattern: ^[A-Za-z0-9._%+@#-]+$
          example: SUMMER-####-####
      additionalProperties: false
      required:
      - couponPattern
      - validCharacters
    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
    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'
    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
    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'
    AttributesSettings:
      type: object
      description: Arbitrary settings associated with attributes.
      properties:
        mandatory:
          $ref: '#/components/schemas/AttributesMandatory'
    LoyaltyTier:
      allOf:
      - $ref: '#/components/schemas/Entity'
      - $ref: '#/components/schemas/LoyaltyProgramEntity'
      - $ref: '#/components/schemas/NewLoyaltyTier'
    BaseLoyaltyProgram:
      type: object
      properties:
        title:
          type: string
          description: The display title for the Loyalty Program.
          example: Point collection
        description:
          type: string
          description: Description of our Loyalty Program.
          example: Customers collect 10 points per 1$ spent
        subscribedApplications:
          type: array
          description: A list containing the IDs of all applications that are subscribed to this Loyalty Program.
          example:
          - 132
          - 97
          items:
            type: integer
        defaultValidity:
          type: string
          description: 'The default duration after which new loyalty points should expire. Can be ''unlimited'' or a specific time.

            The time format is a number followed by one letter indicating the time unit, like ''30s'', ''40m'', ''1h'', ''5D'', ''7W'', or 10M''. These rounding suffixes are also supported:

            - ''_D'' for rounding down. Can be used as a suffix after ''D'', and signifies the start of the day.

            - ''_U'' for rounding up. Can be used as a suffix after ''D'', ''W'', and ''M'', and signifies the end of the day, week, and month.

            '
          example: 2W_U
        defaultPending:
          type: string
          description: 'The default duration of the pending time after which points should be valid. Accepted values: ''immediate'', ''on_action'' or a specific time.

            The time format is a number followed by one letter indicating the time unit, like ''30s'', ''40m'', ''1h'', ''5D'', ''7W'', or 10M''. These rounding suffixes are also supported:

            - ''_D'' for rounding down. Can be used as a suffix after ''D'', and signifies the start of the day.

            - ''_U'' for rounding up. Can be used as a suffix after ''D'', ''W'', and ''M'', and signifies the end of the day, week, and month.

            '
          example: immediate
        allowSubledger:
          type: boolean
          description: Indicates if this program supports subledgers inside the program.
          example: false
        usersPerCardLimit:
          type: integer
          minimum: 0
          example: 111
          description: 'The max amount of user profiles with whom a card can be shared. This can be set to 0 for no limit.

            This property is only used when `cardBased` is `true`.

            '
        sandbox:
          type: boolean
          description: Indicates if this program is a live or sandbox program. Programs of a given type can only be connected to Applications of the same type.
          title: Sandbox
          example: true
        programJoinPolicy:
          type: string
          enum:
          - not_join
          - points_activated
          - points_earned
          description: "The policy that defines when the customer joins the loyalty program.\n  - `not_join`: The customer does not join the loyalty program but can still earn and spend loyalty points.\n\n     **Note**: The customer does not have a program join date.\n  - `points_activated`: The customer joins the loyalty program only when their earned loyalty points become active for the first time.\n  - `points_earned`: The customer joins the loyalty program when they earn loyalty points for the first time.\n"
        tiersExpirationPolicy:
          type: string
          enum:
          - tier_start_date
          - program_join_date
          - customer_attribute
          - absolute_expiration
          description: "The policy that defines how tier expiration, used to reevaluate the customer's current tier, is determined.\n - `tier_start_date`: The tier expiration is relative to when the customer joined the current tier.\n - `program_join_date`: The tier expiration is relative to when the customer joined the loyalty program.\n - `customer_attribute`: The tier expiration is determined by a custom customer attribute.\n - `absolute_expiration`: The tier is reevaluated at the start of each tier cycle. For this policy, it is required to provide a `tierCycleStartDate`.\n"
        tierCycleStartDate:
          type: string
          format: date-time
          description: 'Timestamp at which the tier cycle starts for all customers in the loyalty program.


            **Note**: This is only required when the tier expiration policy is set to `absolute_expiration`.

            '
          example: '2021-09-12T10:12:42Z'
        tiersExpireIn:
          type: string
          description: 'The amount of time after which the tier expires and is reevaluated.


            The time format is an **integer** followed by one letter indicating the time unit.

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


            Available units:


            - `s`: seconds

            - `m`: minutes

            - `h`: hours

            - `D`: days

            - `W`: weeks

            - `M`: months

            - `Y`: years


            You can round certain units up or down:

            - `_D` for rounding down days only. Signifies the start of the day.

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

            '
          example: 27W_U
        tiersDowngradePolicy:
          type: string
          enum:
          - one_down
          - balance_based
          description: "The policy that defines how customer tiers are downgraded in the loyalty program after tier reevaluation.\n - `one_down`: If the customer doesn't have enough points to stay in the current tier, they are downgraded by one tier.\n - `balance_based`: The customer's tier is reevaluated based on the amount of active points they have at the moment.\n"
        cardCodeSettings:
          $ref: '#/components/schemas/CodeGeneratorSettings'
        returnPolicy:
          type: string
          enum:
          - only_pending
          - within_balance
          - unlimited
          description: 'The policy that defines the rollback of points in case of a partially returned, cancelled, or reopened [customer session](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions).

            - `only_pending`: Only pending points can be rolled back.

            - `within_balance`: Available active points can be rolled back if there aren''t enough pending points. The active balance of the customer cannot be negative.

            - `unlimited`: Allows negative balance without any limit.

            '
    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'
    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'
    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
    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
    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
    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
  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\nthe admin who created the key.\n\nUsing an API key is the recommended authentication method.\n\nThe key must be generated by an admin and given to the developer that\nrequires it:\n\n1. Sign in to the Campaign Manager and click **Account** > **Tools** >\n**Management API Keys**.\n1. Click **Create Key** and give it a name.\n1. Set an expiration date.\n   **Tip**: Avoid choosing expiration dates that fall at the end of the year or during other high-traffic periods.\n1. Choose the endpoints the key should give access to.\n1. Click **Create Key**.\n1. Share it with your developer.\n\nThe developer can now use the API key in the HTTP header, prefixing it\nwith `ManagementKey-v1`:\n\n```\nAuthorization: ManagementKey-v1 bd9479c59e16f9dbc644d33aa74d58270fe13bf3\n```\n"