# Talon.One

[Talon.One](https://www.talon.one/) is a platform for creating, managing, and analyzing promotional marketing campaigns.

commercetools Frontend comes with an out-of-the-box Talon.One extension to integrate Talon.One in your commercetools Frontend project.

In this document, we'll walk you through how to set up the Talon.One extension and show an example use case.

**Prerequisites**

- Set up the [extension for commercetools commerce APIs](/frontend-development/using-the-commercetools-extension.md)
- A [Talon.One account](https://www.talon.one/book-a-demo)
- A [Talon.One Integration API key](https://docs.talon.one/docs/product/applications/managing-third-party-api-keys#creating-a-third-party-api-key)
- The URL of your Talon.One deployment (for example, `companyname.talon.one`)

If the `promotion-talon-one` extension is not available in your commercetools Frontend project at this path `packages/PROJECT_NAME/backend`, before proceeding with the following configurations, you must:

1. Copy the `promotion-talon-one` extension from [the scaffold repository](https://github.com/FrontasticGmbH/scaffold-b2c/tree/main/backend/promotion-talon-one) to your project.
2. [Register the extension in your project](/frontend-development/extensions.md#define-extensions).

## Out-of-the-box features

The following Talon.One features are supported:

- [Customer profiles](https://docs.talon.one/docs/dev/concepts/entities/customer-profiles)
- [Customer sessions](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions)
- [Discounts](https://docs.talon.one/docs/dev/integration-api/api-effects#discounts)
- [Gift items](https://docs.talon.one/docs/dev/integration-api/api-effects#addfreeitem)
- [Coupon codes](https://docs.talon.one/docs/dev/concepts/entities/campaigns#coupons)

## Get started

To start using the Talon.One extension in your commercetools Frontend project, follow these steps:

1. [Add the following project configuration fields to the project schema](/frontend-development/api-hub-configuration.md#add-project-configuration-fields-to-the-project-schema) from the Studio.

   ```json title="Add Talon.One project configuration fields"
   {
     "name": "Talon.One extension",
     "fields": [
       {
         "label": "HOST",
         "field": "EXTENSION_TALON_ONE_HOST",
         "type": "string",
         "translatable": false,
         "required": true
       },
       {
         "label": "API Key",
         "field": "EXTENSION_TALON_API_KEY_{CURRENCY}",
         "type": "string",
         "translatable": false,
         "required": true
       }
     ]
   }
   ```

   In Talon.One, [Applications](https://docs.talon.one/docs/product/applications/overview) are environments where you create and manage your campaigns. Each Application has a single currency type and can have one or more API keys.

   If your [Project](/api/projects/project.md) contains multiple currencies, you will need to create a Talon.One Application, including API key, for each currency you wish to support.

2. [Set the Talon.One configuration values](/frontend-development/api-hub-configuration.md#enter-project-configuration-values-in-project-settings) from the Studio:

   - In the **HOST** field, enter your Talon.One deployment URL (for example, `companyname.talon.one`).
   - In the **API Key** field, enter the [API key](https://docs.talon.one/docs/product/applications/managing-third-party-api-keys#creating-a-third-party-api-key) of your Talon.One Application.

## Example

The following example shows how you can use Talon.One to apply discounts to a [Cart](/search.md?urn=ctp:api:type:Cart). In our example, we will make changes to the `addToCart` action inside `/backend/commerce-commercetools/actionControllers/CartController.ts`.

First, we start a session by instantiating the `TalonOnePromotionApi` class, then update the Cart [Line Items](/api/carts-orders-overview.md#line-items) in the session, and finally, apply any returned effects.

```typescript highlightLines="23-28,31,34"
export const addToCart: ActionHook = async (
  request: Request,
  actionContext: ActionContext
) => {
  const cartApi = getCartApi(request, actionContext);

  const body: {
    variant?: { sku?: string; count: number };
  } = JSON.parse(request.body);

  const lineItem: LineItem = {
    variant: {
      sku: body.variant?.sku || undefined,
      price: undefined,
    },
    count: +body.variant?.count || 1,
  };

  let cart = await CartFetcher.fetchCart(cartApi, request, actionContext);
  cart = await cartApi.addToCart(cart, lineItem);

  // Instantiate a Talon.One API session.
  const promotionApi = new TalonOnePromotionApi(
    actionContext.frontasticContext,
    cart.cartId, // Talon.One Session ID
    getLocale(request),
    getCurrency(request)
  );

  // Update the Cart Line Items in the Talon.One session.
  const promo = await promotionApi.updateCartItems(cart);

  // Apply any returned effects using DirectDiscounts.
  await cartApi.applyDiscountEffects(cart, promo.effects);

  const cartId = cart.cartId;

  const response: Response = {
    statusCode: 200,
    body: JSON.stringify(cart),
    sessionData: {
      ...request.sessionData,
      cartId,
    },
  };

  return response;
};
```

In the preceding example, the `applyDiscountEffects` method applies [DirectDiscounts](/api/projects/carts.md#directdiscount) to the Cart based on the [effects returned from Talon.One](https://docs.talon.one/docs/product/rules/effects/overview).

## Additional features

You can access additional features such as [giveaways](https://docs.talon.one/docs/product/giveaways/overview), [loyalty programs](https://docs.talon.one/docs/product/loyalty-programs/overview), and [referrals](https://docs.talon.one/docs/product/campaigns/referrals/referral-overview) by using the methods provided in the `/backend/promotion-talon-one/apis/IntegrationApi.ts` file. You can also add new methods and apply your own custom logic.

## Related pages

- [Area overview page with navigation](/frontend-development.md)
- [Previous page: Nosto](/frontend-development/nosto.md)
- [Search documentation and API specs](/search.md)