# Integration checklist

> Every integration is unique, but keep in mind the following points.

> For the complete documentation index, see [llms.txt](https://docs.talon.one/llms.txt).

## Planning stage

:::important
Communication with our API endpoints should happen **only from a backend environment** to
avoid exposing sensitive authentication credentials to end users.
:::

<StepsContainer>

### Choose an SDK

Talon.One offers [SDKs for multiple languages](/docs/dev/sdks/overview.md). **Use** them
to integrate with Talon.One via the [Integration API][iapioverview].

### Learn about the two APIs

Talon.One offers two APIs: the **Integration API** and the **Management API**.
They differ in their authentication methods and their purpose.

See [Integration API][iapioverview] and its [best practices](/docs/dev/integration-api/best-practices.md).

### Create your campaigns

Create at least one [campaign](/docs/dev/concepts/entities/campaigns.md) containing one or more
rules to test your integration.

For more information, see the [campaign overview page](/docs/product/campaigns/overview.md)
in our Product docs.

### Create your attributes

[Attributes](/docs/dev/concepts/attributes.md) are an important part of the Talon.One
integration.

Attributes allow you to build any kind of promotion based on product properties. For
example, they can represent the weight of an item, the segment of a user, a payment
method, etc.

Create them in the Campaign Manager and set them within your
[session update](/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2) or
[customer profile update](/integration-api#tag/Customer-profiles/operation/updateCustomerProfileV2) requests.

See:

- [Integration tutorial](/docs/dev/get-started/integration-tutorial.md)
- [Custom attributes](/docs/dev/concepts/attributes.md#custom-attributes)

### Import or migrate data

Depending on the tools that you use in addition to Talon.One, you can import or migrate
your data into Talon.One to create highly targeted promotional campaigns:

- [Import customer data](/docs/dev/tutorials/import-customer-data.md)
- [Import coupons](/docs/dev/tutorials/import-coupon-codes.md)
- [Import loyalty data](/docs/dev/tutorials/import-loyalty-data.md)

</StepsContainer>

## Implementation stage

<StepsContainer>

### Handle customer sessions

:::important
Sessions are a key concept. Read
[Customer sessions](/docs/dev/concepts/entities/customer-sessions.md).
:::

A session represents a customer's cart. In general, integrating with Talon.One
consists in sending
[customer session updates](/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2) requests
to Talon.One.

Ensure you apply the following good practices:

- **Session ID:** Use an immutable ID.
- **Session state:** Update the state of your session depending on your order workflow.

A session is usually created in the `open` state (when a customer adds an item to the
cart) or `closed` state (when they complete an order).

- `open`: The session can be modified as many times as needed. Also:
  - If a closed session is reopened:
    - It is no longer included in the total number of closed sessions.
    - The session data is not factored into [campaign analytics data](/docs/product/campaigns/analytics/application-dashboard).
    - The same effects are rolled back as when a closed session is cancelled.
    - Budgets are reverted in the same way as when a closed session is cancelled.
- `closed`: The session cannot be modified anymore, unless it is [reopened](/integration-api#tag/Customer-sessions/operation/reopenCustomerSession) programmatically. Also:
  - The session data is factored into campaign analytics data.
  - Potential coupons are redeemed.
- `cancelled`: The session had an issue or the `closed` or `partially returned` states are not valid anymore. Also:
  - The session data is not factored into campaign analytics data.
  - Rollback effects undo previous effects triggered when you closed or opened the session.
  - The impact of the session's effects on campaign budgets is reverted, except for [coupon
    creations](/docs/product/campaigns/settings/manage-campaign-budgets#coupon-limits).
  - Attribute value updates are not rolled back.
  - If a closed session is cancelled, it is no longer included in the total
    number of closed sessions.
- `partially returned`: One or more cart items have been returned and the `closed` state
   is not valid anymore. Also:
  - Rollback effects undo previous effects triggered when you closed or opened the session.
    Per-item effects are rolled back for the returned items only.
  - The impact of the session's per-item effects on campaign budgets is reverted for the
    returned items only. Any other effects triggered by the session count towards the set
    campaign budget.
  - Attribute value updates are not rolled back.
  - If a closed session is partially returned, it is included in the total number of
    closed sessions.

:::tip Examples of session states
- `open`: The customer adds items, referral codes, or coupons to their shopping cart.
- `closed`: The customer has completed the payment step (or any final step) of the order workflow.
- `cancelled`: The customer requested a full refund or the payment failed.
- `partially returned`: The customer returned some of the items and expects the corresponding refund.
:::

### Implement with performance in mind

**Do more with one call:** The
[Update customer session](/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2)
and [Update customer profile](/integration-api#tag/Customer-profiles/operation/updateCustomerProfileV2)
endpoints offer a `responseContent` property that you can use to save API calls.
For example, you can use this property to retrieve the customer
profile information without having to use another endpoint.

**Reduce response time:** When you query the `Update customer session` or
`Update customer profile` endpoint but
do not want the request to modify your Application, set the `runRuleEngine` and `dry`
parameters to `true` to send a [dry request](/docs/dev/integration-api/best-practices#dry-requests) and
get faster response times.
You will still see the returned effects but there will be no change to your Application.

**Use a single event for a single customer action:**
When implementing customer actions, consider that each [event](/docs/dev/concepts/entities/events)
represents a single occurrence of a customer action related to a customer session
or customer profile. To avoid receiving too many 409 responses, ensure that
the customer action does not trigger multiple events in parallel.

### Handle customer profiles and sessions

A session can be connected to a profile by passing the integration ID of the customer
as the value of the `profileId` attribute.

Whether to pass a `profileId` for anonymous or guest sessions is a trade-off. Choose the
option that fits your integration:

- **Pass a unique `profileId` per guest**: Recommended when profile-level budgets or
  loyalty are crucial to the integration.
  This approach creates a profile for each guest, so
  you might need to delete unused guest profiles over time.
- **Pass no `profileId`**: Recommended when you don't need profile tracking, profile-level budgets
  or loyalty campaigns. This approach offers performance improvements, but profile-level budgets don't apply
  and campaigns with loyalty enabled are skipped entirely during evaluation.
- **Share a single `profileId` across all guests**: Typically not recommended. Guests would share
  loyalty balances, coupons, and other profile-related data, and updates to the same profile
  are processed one at a time, which can limit performance.

See [Integration API best practices](docs/dev/integration-api/best-practices.md).

### Parse the returned effects

Part of the [customer session update](/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2)
response is the `effects` array. This object
contains additional information regarding _custom attribute values for all
triggered campaigns_ and the reason why potential effects failed.

See the [JSON structure of all effects](/docs/dev/integration-api/api-effects.md).

You can also [create your own effects](/docs/dev/tutorials/create-custom-effects.md),
if needed.

### Deal with error responses

Talon.One receives a bad request, it returns an error code. Ensure that your
system is able to catch them or monitor them. They are available in the
[Integration API reference docs](/integration-api) for each endpoint.

Typical examples of bad requests are when the integration sends an unknown session
attribute or a wrongly formatted coupon attribute.

</StepsContainer>

## Optional steps

<StepsContainer>

### Whitelist IP addresses

After you have created your campaigns, Talon.One can whitelist your IP addresses. Only the
addresses you send to us are able to send API requests or to sign in to the Campaign Manager.

To whitelist IPs, send the list to [support@talon.one](mailto:support@talon.one).

### Set up API key rotation

Rotate your Integration API keys on a schedule aligned with your InfoSec policy.
Use the Management API to create new keys programmatically and automate the rotation process.

See [API key management](/docs/dev/integration-api/best-practices.md#api-key-management).

### Implement a fallback mechanism

Design your integration to keep transactions running if Talon.One is temporarily unreachable.
At minimum, apply tight timeouts, bounded retries with exponential backoff and jitter,
and a circuit breaker that switches to a fallback behavior during an outage.

See [Resilience](/docs/dev/integration-api/best-practices.md#resilience).

### Deal with Talon.One API URL changes

As part of the implementation stage, Talon.One offers the possibility to move your cluster to a preferred Google
Cloud location.

Moving a cluster will change the API URL, such as `mycompany.talon.one/v2/` or
`mycompany.europe-west1.talon.one/v2/`.

We suggest that you ensure your integration supports URL changes.

### Prepare for post-onboarding

As your onboarding phase ends, ensure that your team is ready to operate the integration
in production:

- Know how to reach out to Talon.One in case of issues.
- Know how to troubleshoot integration issues.
- Know how to stay up to date with Talon.One features. See the [What's new](/whats-new) page.
- Set up traffic monitors for response times, 4xx errors, 5xx errors, etc.

</StepsContainer>

[iapioverview]: /docs/dev/integration-api/overview.md