Talon.One Customer profiles API

openapi: 3.2.0
info:
  title: Talon One Customer profiles API
  version: '1.0'
  description: 'Operations tagged Customer profiles across 2 of this provider''s published API definitions: talon-one-integration-api-openapi.yml, talon-one-shopify-integration-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://yourbaseurl.talon.one
- url: https://shopify-integration.europe-west1.talon.one
tags:
- name: Customer profiles
  description: 'Represents the customer''s information. For instance, their contact information.

    '
paths:
  /v2/customer_profiles/{integrationId}:
    put:
      operationId: updateCustomerProfileV2
      summary: Update customer profile
      description: 'Update or create a [Customer

        Profile](https://docs.talon.one/docs/dev/concepts/entities/customer-profiles).

        This endpoint triggers the Rule Builder.


        You can use this endpoint to:

        - Set attributes on the given customer profile. Ensure you create the attributes in the Campaign Manager, first.

        - Modify the audience the customer profile is a member of.


        > [!note] **Note**

        > - Updating a customer profile returns a response with the requested integration state.

        > - The [Has joined an audience](https://docs.talon.one/docs/product/rules/conditions/available-conditions#audience-conditions) and

        >   [Has left an audience](https://docs.talon.one/docs/product/rules/conditions/available-conditions#audience-conditions) conditions

        >   only trigger through this endpoint.

        > - You can use the `responseContent` property to save yourself extra API calls. For example, you can get

        >   the customer profile details directly without extra requests.

        > - We recommend sending requests sequentially.

        >   See [Managing parallel requests](https://docs.talon.one/docs/dev/getting-started/integration-tutorial#managing-parallel-requests).

        > - [Archived campaigns](https://docs.talon.one/docs/product/campaigns/managing-campaigns#archiving-a-campaign) are not considered in rule evaluation when `runRuleEngine` is `true`.


        > [!note] To make request processing idempotent for this endpoint, include the `Idempotency-Key` header with an idempotency key in requests. Also:

        > - Requests with the `Idempotency-Key` header are logged in the Talon.One access logs.

        > - Responses for idempotent requests are stored in the database and expire 24 hours after the request is sent.

        > - Idempotency keys are typically UUID keys and should not exceed 255 characters in length.

        '
      security:
      - api_key_v1: []
      tags:
      - Customer profiles
      parameters:
      - 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.

          **Note**: It must be URL-encoded. For example, replace spaces with `%20`. [Learn more](https://www.w3schools.com/tags/ref_urlencode.asp).

          '
        example: customer1
        schema:
          type: string
      - name: runRuleEngine
        in: query
        description: 'Indicates whether to run the Rule Engine.


          If `true`, the response includes:

          - The effects generated by the triggered campaigns are returned in the `effects` property.

          - The created coupons and referral objects.


          If `false`:

          - The rules are not executed and the `effects` property is always empty.

          - The response time improves.

          - You cannot use `responseContent` in the body.

          '
        example: false
        required: false
        schema:
          type: boolean
          default: false
      - name: dry
        in: query
        description: '(Only works when `runRuleEngine=true`) Indicates whether to persist the changes. Changes are ignored when `dry=true`.


          When set to `true`, you can use the `evaluableCampaignIds` body property to select specific campaigns to run.

          '
        example: false
        required: false
        schema:
          type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerProfileIntegrationRequestV2'
            examples:
              Full request:
                summary: Full request
                x-vertical: none
                value:
                  attributes:
                    Language: english
                    ShippingCountry: DE
                  evaluableCampaignIds:
                  - 10
                  - 12
                  responseContent:
                  - triggeredCampaigns
                  - customerProfile
                  audiencesChanges:
                    adds:
                    - 2
                    - 4
                    deletes:
                    - 7
              eCommerce:
                x-vertical: ecommerce
                summary: 'Example: ecommerce'
                description: Create a new customer with basic information and sign-up date.
                value:
                  attributes:
                    Name: Chris Taylor
                    Email: chris.taylor@example.com
                    SignupDate: '2026-01-21T15:04:05+07:00'
                    PaymentMethod: Bank transfer
              QSR & dining:
                x-vertical: qsr
                summary: 'Example: QSR & dining'
                description: 'Update a customer profile with dietary preferences and ordering behaviors to personalize offers.

                  '
                value:
                  attributes:
                    Name: Jane Doe
                    Email: jane.doe@example.com
                    DietaryPreferences: vegetarian
              Financial services:
                x-vertical: finance
                summary: 'Example: Financial services'
                description: 'Update a customer profile with account type and card details to enable

                  personalized cashback campaigns.

                  '
                value:
                  attributes:
                    Name: Alex Johnson
                    Email: alex.johnson@example.com
                    AccountType: premium_checking
                    PreferredCard: credit
              Travel & hospitality:
                x-vertical: travel
                summary: 'Example: Travel & hospitality'
                description: 'Update a traveler profile with a churn risk score to identify travelers who

                  haven''t booked a flight in several months and offer time-sensitive rewards.

                  '
                value:
                  attributes:
                    Name: Maria Chen
                    Email: maria.chen@example.com
                    ChurnRisk: 0.872
        description: body
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerProfileIntegrationResponseV2'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '409':
          description: Too many requests or limit reached - Avoid parallel requests. See the [docs](https://docs.talon.one/docs/dev/tutorials/integrating-talon-one#managing-parallel-requests).
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                    example: Too many requests are updating this profile at the same time
                  errors:
                    type: array
                    items: {}
                  StatusCode:
                    type: integer
                    example: 409
    servers:
    - url: https://yourbaseurl.talon.one
  /v2/customer_profiles:
    put:
      operationId: updateCustomerProfilesV2
      summary: Update multiple customer profiles
      description: 'Update (or create) up to 1000 [customer

        profiles](https://docs.talon.one/docs/dev/concepts/entities/customer-profiles)

        in 1 request.


        The `integrationId` must be any identifier that remains stable for

        the customer. Do not use an ID that the customer can update

        themselves. For example, you can use a database ID.


        A customer profile [can be linked to one or more

        sessions](https://docs.talon.one/integration-api#tag/Customer-sessions).


        > [!note] This endpoint does not trigger the Rule Engine.

        > To trigger the Rule Engine for customer profile updates,

        > use the [Update customer profile](#tag/Customer-profiles/operation/updateCustomerProfileV2) endpoint.


        > [!note] To make request processing idempotent for this endpoint, include the `Idempotency-Key` header with an idempotency key in requests. Also:

        > - Requests with the `Idempotency-Key` header are logged in the Talon.One access logs.

        > - Responses for idempotent requests are stored in the database and expire 24 hours after the request is sent.

        > - Idempotency keys are typically UUID keys and should not exceed 255 characters in length.

        '
      security:
      - api_key_v1: []
      tags:
      - Customer profiles
      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'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MultipleCustomerProfileIntegrationRequest'
        description: body
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultipleCustomerProfileIntegrationResponseV2'
        '204':
          description: No content
          content:
            application/json:
              schema:
                type: string
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithStatus'
    servers:
    - url: https://yourbaseurl.talon.one
  /v1/customer_data/{integrationId}:
    delete:
      operationId: deleteCustomerData
      summary: Delete customer's personal data
      description: 'Delete all attributes on the customer profile and on entities that reference

        this customer profile.


        > [!warning] **Warning**

        > - Customer data is deleted from all Applications in the

        >   [environment](https://docs.talon.one/docs/product/applications/overview#application-environments)

        >   that the API key belongs to. For example, if you use this endpoint with an API key that belongs

        >   to a sandbox Application, customer data will be deleted from all sandbox Applications.

        >   This is because customer data is shared between Applications from the same environment.

        > - To preserve performance, we recommend avoiding deleting customer data

        >   during peak-traffic hours.

        '
      security:
      - api_key_v1: []
      tags:
      - Customer profiles
      parameters:
      - name: integrationId
        in: path
        required: true
        description: 'The integration ID of the customer profile. You can get the `integrationId` of a profile using:

          - A customer session integration ID with the [Update customer session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2) endpoint.

          - The Management API with the [List application''s customers](https://docs.talon.one/management-api#tag/Customer-data/operation/getApplicationCustomers) endpoint.

          '
        example: customer1
        schema:
          type: string
      responses:
        '204':
          description: No Content
        '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'
    servers:
    - url: https://yourbaseurl.talon.one
  /v1/customer_profiles/{integrationId}/inventory:
    get:
      operationId: getCustomerInventory
      summary: List customer data
      description: 'Return the customer inventory regarding entities referencing this customer profile''s `integrationId`.


        Typical entities returned are: customer profile information, referral codes, loyalty points, loyalty cards and reserved coupons.

        Reserved coupons also include redeemed coupons.

        '
      security:
      - api_key_v1: []
      tags:
      - Customer profiles
      parameters:
      - name: integrationId
        in: path
        required: true
        description: 'The integration ID of the customer profile. You can get the `integrationId` of a profile using:

          - A customer session integration ID with the [Update customer session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2) endpoint.

          - The Management API with the [List application''s customers](https://docs.talon.one/management-api#tag/Customer-data/operation/getApplicationCustomers) endpoint.

          '
        example: customer1
        schema:
          type: string
      - name: profile
        in: query
        required: false
        description: Set to `true` to include customer profile information in the response.
        example: false
        schema:
          type: boolean
      - name: referrals
        in: query
        required: false
        description: Set to `true` to include referral information in the response.
        example: false
        schema:
          type: boolean
      - name: coupons
        in: query
        required: false
        description: Set to `true` to include coupon information in the response.
        example: false
        schema:
          type: boolean
      - name: loyalty
        in: query
        required: false
        description: Set to `true` to include loyalty information in the response.
        example: false
        schema:
          type: boolean
      - name: giveaways
        in: query
        required: false
        description: Set to `true` to include giveaways information in the response.
        example: false
        schema:
          type: boolean
      - name: achievements
        in: query
        required: false
        description: Set to `true` to include achievement information in the response.
        example: false
        schema:
          type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerInventory'
        '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'
    servers:
    - url: https://yourbaseurl.talon.one
  /api/v1/customer:
    get:
      summary: Retrieve customer data (Headless stores)
      description: "Fetches the Talon.One customer profile for a Shopify customer in a [headless store](https://shopify.dev/docs/storefronts/headless/getting-started). The response is also stored in a customer metafield in Shopify. \n\nThe response schema is identical to the [List customer data](https://docs.talon.one/integration-api#tag/Customer-profiles/operation/getCustomerInventory) endpoint of the Integration API.\n\nIf you call this endpoint repeatedly with the same customer access token, the endpoint sends a cached response for the given customer. The cache clears after 10 seconds. This is done to reduce data load.        \n"
      operationId: getCustomerHeadless
      tags:
      - Customer profiles
      security:
      - ShopifyCustomerAccessToken: []
      parameters:
      - $ref: '#/components/parameters/ShopifyShopDomain'
      responses:
        '200':
          description: OK. For details, see the response of the [List customer data](https://docs.talon.one/integration-api#tag/Customer-profiles/operation/getCustomerInventory) endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCustomerResponse'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                MissingShopDomainHeader:
                  summary: Missing X-Shopify-Shop-Domain header
                  value:
                    success: false
                    message: missing X-Shopify-Shop-Domain header
                InvalidConfig:
                  summary: Missing `api_url` or `api_key` in the config
                  value:
                    success: false
                    message: Invalid config
        '401':
          description: Unauthorized. Authentication failed or token does not grant access for the requested store.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                NoAuthHeaderOrMalformed:
                  summary: Missing or malformed Authorization header
                  value:
                    success: false
                    message: Unauthorized
                ShopIdMismatch:
                  summary: Token's shop ID does not match the configured shop ID for the given X-Shopify-Shop-Domain
                  value:
                    success: false
                    message: Unauthorized
        '403':
          description: Forbidden. The provided token is invalid, expired, or does not have the necessary permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InvalidJWT:
                  summary: Invalid or expired JWT token
                  value:
                    success: false
                    message: Invalid JWT token
        '404':
          description: Not found. The requested resource (config or customer) could not be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ConfigNotFound:
                  summary: Configuration not found
                  value:
                    success: false
                    message: Config not found
                CustomerNotFoundInT1:
                  summary: Customer profile not found
                  value:
                    success: false
                    message: Customer not found
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  summary: Internal Server Error
                  value:
                    success: false
                    message: Internal Server Error
    servers:
    - url: https://shopify-integration.europe-west1.talon.one
  /api/v1/customer-profile:
    get:
      summary: Retrieve customer data (Theme-based stores)
      description: "Fetches the Talon.One customer profile for a Shopify customer in a [theme-based store](https://shopify.dev/docs/storefronts/themes). The response is also stored in a customer metafield in Shopify. \n\nThe response schema is identical to the [List customer data](https://docs.talon.one/integration-api#tag/Customer-profiles/operation/getCustomerInventory) endpoint of the Integration API.\n\nIf you call this endpoint repeatedly with the same customer JWT token, the endpoint sends a cached response for the given customer. The cache clears after 10 seconds. This is done to reduce data load.        \n"
      operationId: getCustomerThemeBased
      tags:
      - Customer profiles
      security:
      - ShopifyJWT: []
      responses:
        '200':
          description: OK. For details, see the response of the [List customer data](https://docs.talon.one/integration-api#tag/Customer-profiles/operation/getCustomerInventory) endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCustomerResponse'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InvalidConfig:
                  summary: Missing `api_url` or `api_key` in the config
                  value:
                    success: false
                    message: Invalid config
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                MissingAuthorizationHeader:
                  summary: Missing Authorization header
                  value:
                    success: false
                    message: Unauthorized
        '403':
          description: Forbidden. The provided token is invalid, expired, or does not have the necessary permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InvalidJWT:
                  summary: Invalid or expired JWT token. Missing required fields.
                  value:
                    success: false
                    message: Invalid JWT token
        '404':
          description: Not found. The requested resource (config or customer) could not be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ConfigNotFound:
                  summary: Configuration not found
                  value:
                    success: false
                    message: Config not found
                CustomerNotFoundInT1:
                  summary: Customer profile not found
                  value:
                    success: false
                    message: Customer not found
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  summary: Internal Server Error
                  value:
                    success: false
                    message: Internal Server Error
    servers:
    - url: https://shopify-integration.europe-west1.talon.one
components:
  schemas:
    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.
    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.
    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.
    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.
    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.
    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.
    ResponseContentObject:
      type: object
      properties:
        responseContent:
          type: array
          description: 'Extends the response with the chosen data entities. Use this property to get as much data back as needed from one request instead of sending extra requests to other endpoints.

            '
          example:
          - triggeredCampaigns
          - customerProfile
          items:
            type: string
            enum:
            - customerProfile
            - triggeredCampaigns
            - loyalty
            - event
            - awardedGiveaways
            - ruleFailureReasons
            - campaignEligibility
            - achievements
    EvaluableCampaignIds:
      type: object
      properties:
        evaluableCampaignIds:
          type: array
          items:
            type: integer
          description: 'When using the `dry` query parameter, use this property to list the campaign to be evaluated by the Rule Engine.


            These campaigns will be evaluated, even if they are disabled, allowing you to test specific campaigns before activating them.

            '
          title: Campaigns to evaluate
          example:
          - 10
          - 12
    UserEntity:
      type: object
      required:
      - userId
      properties:
        userId:
          type: integer
          description: The ID of the user associated with this entity.
          example: 388
    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
    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.
    InventoryReferral:
      allOf:
      - $ref: '#/components/schemas/Referral'
      - type: object
        required:
        - referredCustomers
        properties:
          referredCustomers:
            type: array
            description: An array of referred customers.
            items:
              type: string
    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 u

# --- truncated at 32 KB (168 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/talon-one/refs/heads/main/openapi/talon-one-customer-profiles-api-openapi.yml