# Agentic commerce

> Agentic commerce represents a transformative approach to commerce, where AI agents handle the entire shopping experience for a shopper, from product discovery to checkout.

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

To increase the value of agentic commerce, Talon.One offers the
[Unified Incentives Protocol](https://uip.dev/) (UIP). UIP is a set of
platform-agnostic standards that expose loyalty and promotion data in a unified way,
in all phases of the shopping lifecycle.

## Universal Commerce Protocol (UCP)

[UCP](https://ucp.dev/) is Google's approach to
establishing a framework for seamless, secure, and standardized interactions between
businesses and AI agents such as Gemini.

Talon.One provides the following UCP extensions to enhance agentic commerce experiences:

| Extension                                     | Description                                                                                                                                           | Latest version |
|-----------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|----------------|
| [Loyalty extension](#loyalty-extension)       | Enables businesses to expose loyalty program data to AI agents, allowing them to manage loyalty points, tiers, and memberships on behalf of shoppers. | `2026-01-23`   |
| [Promotions extension](#promotions-extension) | Enables businesses to expose discount and promotions data to AI agents, allowing them to manage promotions on behalf of shoppers.                     | `2026-01-28`   |

### Prerequisites

Before you use Talon.One's UCP extensions, ensure the following:

- You have read the [UCP core concepts](https://ucp.dev/documentation/core-concepts/)
  and the [UCP specification](https://ucp.dev/specification/overview/).
- You have created a UCP profile located at `/.well-known/ucp` to let AI agents
  discover and interact with your business.

### Loyalty extension

Use Talon.One's [UCP loyalty extension](https://uip.dev/specification/ucp/loyalty) to
let AI agents support complex
[profile](/docs/product/loyalty-programs/profile-based/profile-based-overview.md)
or [card-based](/docs/product/loyalty-programs/card-based/card-based-overview.md)
loyalty scenarios involving loyalty program memberships, multi-wallet programs, tiers,
and more.

<StepsContainer>

#### Enable the required UCP capabilities

Google offers a number of [UCP capabilities](https://ucp.dev/specification/overview/#capabilities)
that the Talon.One loyalty extension requires:

1. Enable the `dev.ucp.shopping.checkout` capability. Talon.One relies on this capability
   to be aware of the session data.
1. Enable the `dev.ucp.common.identity_linking` capability.
   Talon.One's loyalty extension requires identity information to link a shopper to their
   loyalty profile.
1. This guide focuses on REST endpoints to handle UCP requests for these capabilities,
   so ensure you reference an endpoint in your UCP profile.

```json title=".well-known/ucp" {8-10,17,23}
{
  "ucp": {
    "version": "2026-01-11",
    "services": {
      "dev.ucp.shopping": {
        "version": "2026-01-11",
        "spec": "https://ucp.dev/specification/overview",
        "rest": {
          "schema": "https://ucp.dev/services/shopping/rest.openapi.json",
          "endpoint": "https://business.example.com/ucp/v1"
        },
      },
      ...
    },
    "capabilities": [
      {
        "name": "dev.ucp.shopping.checkout",
        "version": "2026-01-11",
        "spec": "https://ucp.dev/specification/checkout",
        "schema": "https://ucp.dev/schemas/shopping/checkout.json"
      },
      {
       "name": "dev.ucp.common.identity_linking",
       "version": "2026-01-11",
       "specs": {
         ...
       }
      },
      ...
    ]
  },
  "payment": {
    ...
  },
  ...
}
```

#### Enable the Talon.One UCP loyalty extension

To enable the loyalty extension, reference it in your UCP profile's `capabilities` array:

```json title=".well-known/ucp"
{
    "capabilities": [
      {
        "name": "dev.uip.shopping.loyalty",
        "version": "2026-01-23",
        "extends": "dev.ucp.shopping.checkout",
        "spec": "https://uip.dev/specification/ucp/loyalty",
        "schema": "https://uip.dev/schemas/ucp/shopping/loyalty.json"
      }
    ]
}
```

#### Inject loyalty data in your UCP responses

Once your UCP profile includes Talon.One's loyalty extension, implement extra logic in
your backend services to include loyalty-related data in your responses for relevant [UCP
operations](https://ucp.dev/specification/checkout-rest/#operations).
Retrieve loyalty data with the
[Integration API's loyalty endpoints](https://docs.talon.one/integration-api#tag/Loyalty)
and structure that data according to the
[loyalty extension schema](https://uip.dev/schemas/ucp/shopping/loyalty.json).

For example, for the [`Create checkout` operation](https://ucp.dev/specification/checkout/#create-checkout),
you can fetch the user's loyalty point balance from Talon.One and include it in the
checkout session creation response:

<Tabs groupId="group1">
<TabItem value="req" label="Request" default>

```json title="Create checkout operation"
POST /checkout-sessions HTTP/1.1
UCP-Agent: profile="https://platform.example/profile"
Content-Type: application/json

{
  "line_items": [
    {
      "item": {
        "id": "item_123",
        "title": "Red T-Shirt",
        "price": 2500
      },
      "id": "li_1",
      "quantity": 2
    }
  ]
}
```

</TabItem>
<TabItem value="resp" label="Response">

```json title="Create checkout operation response with loyalty information" {56}
HTTP/1.1 201 Created
Content-Type: application/json

{
  "ucp": {
    "version": "2026-01-11",
    "capabilities": [
      {
        "name": "dev.ucp.shopping.checkout",
        "version": "2026-01-11"
      },
      {
        "name": "dev.uip.shopping.loyalty",
        "version": "2026-01-23"
      }
    ]
  },
  "id": "chk_1234567890",
  "status": "incomplete",
  "currency": "USD",
  "line_items": [
    {
      "id": "li_1",
      "item": {
        "id": "item_123",
        "title": "Red T-Shirt",
        "price": 2500
      },
      "quantity": 2,
      "totals": [
        {
          "type": "subtotal",
          "amount": 5000
        },
        {
          "type": "total",
          "amount": 5000
        }
      ]
    }
  ],
  "totals": [
    {
      "type": "subtotal",
      "amount": 5000
    },
    {
      "type": "tax",
      "amount": 400
    },
    {
      "type": "total",
      "amount": 5400
    }
  ],
  "loyalty": {
    "memberships": [
      {
        "type": "profile",
        "id": "PROFILE_123"
      },
    ],
    "programs": [
      {
        "id": "program_id1",
        "name": "My Program",
        "membership": "$.loyalty.memberships[0]",
        "wallets": [
          {
            "id": "main_wallet",
            "unit": "points",
            "balances": {
              "active": 130,
              "pending": 30,
              "total": 160
            },
            "earnings": {
              "active": 30,
              "pending": 30,
              "total": 60
            },
            "tier": {
              "current": {
                "id": 123,
                "name": "Obsidian"
              },
              "next": {
                "id": 125,
                "name": "Purple"
              },
              "unitsToNext": 40
            }
          },
          {
            "id": "support_wallet",
            "unit": "points",
            "balances": {
              "active": 1000,
              "pending": 0
            }
          }
        ]
      }
    ],
    "earnings": [
      {
        "title": "20 points",
        "target": "items",
        "method": "each",
        "amount": 20,
        "allocations": [
          {
            "path": "$.line_items[0]",
            "amount": 20
          }
        ],
        "wallet": "$.loyalty.programs[0].wallets[0]",
        "activeFrom": "2026-01-24T11:00:22Z"
      },
    ]
  }
}
```

</TabItem>
</Tabs>

</StepsContainer>

### Promotions extension

Use Talon.One's UCP promotions extension to let AI agents use discounts,
coupons, gift cards, and other promotions on behalf of shoppers.

<StepsContainer>

#### Enable the required UCP capabilities

Google offers a number of [UCP capabilities](https://ucp.dev/specification/overview/#capabilities)
that the Talon.One promotions extension requires:

1. Enable the `dev.ucp.shopping.checkout` capability. Talon.One relies on this capability
   to be aware of the session data.
1. This guide focuses on REST endpoints to handle UCP requests for this capability,
   so ensure you reference an endpoint in your UCP profile.

```json title=".well-known/ucp" {8-10,17}
{
  "ucp": {
    "version": "2026-01-11",
    "services": {
      "dev.ucp.shopping": {
        "version": "2026-01-11",
        "spec": "https://ucp.dev/specification/overview",
        "rest": {
          "schema": "https://ucp.dev/services/shopping/rest.openapi.json",
          "endpoint": "https://business.example.com/ucp/v1"
        },
      },
      ...
    },
    "capabilities": [
      {
        "name": "dev.ucp.shopping.checkout",
        "version": "2026-01-11",
        "spec": "https://ucp.dev/specification/checkout",
        "schema": "https://ucp.dev/schemas/shopping/checkout.json"
      },
      ...
    ]
  },
  "payment": {
    ...
  },
  ...
}
```

#### Enable the Talon.One UCP promotions extension

To enable the promotions extension, reference it in your UCP profile's `capabilities` array:

```json title=".well-known/ucp"
{
    "capabilities": [
      {
        "name": "dev.uip.shopping.promotions",
        "version": "2026-01-28",
        "extends": "dev.ucp.shopping.checkout",
        "spec": "https://uip.dev/specification/ucp/promotions",
        "schema": "https://uip.dev/schemas/ucp/shopping/promotions.json"
      }
    ]
}
```

#### Inject promotion data in your UCP responses

Once your UCP profile includes Talon.One's promotions extension, implement extra logic in
your backend services to include promotion-related data in your responses for relevant [UCP
operations](https://ucp.dev/specification/checkout-rest/#operations).

For example, you can do the following:
- Retrieve code data with the [List customer data](https://docs.talon.one/integration-api#tag/Customer-profiles/operation/getCustomerInventory) endpoint.
- Retrieve the applied discounts and the value of codes with the [Update customer session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2) endpoint.

For example, for the [`Create checkout` operation](https://ucp.dev/specification/checkout/#create-checkout),
you can fetch the user's applied discounts and return this data as UCP:

<Tabs groupId="group1">
<TabItem value="req" label="Request" default>

```json title="Create checkout operation"
POST /checkout-sessions HTTP/1.1
UCP-Agent: profile="https://platform.example/profile"
Content-Type: application/json

{
  "line_items": [
    {
      "item": {
        "id": "item_123",
        "title": "Red T-Shirt",
        "price": 2500
      },
      "id": "li_1",
      "quantity": 2
    }
  ]
}
```

</TabItem>
<TabItem value="resp" label="Response">

```json title="Create checkout operation response with promotions information" {75}
HTTP/1.1 201 Created
Content-Type: application/json

{{
  "ucp": {
    "version": "2026-01-11",
    "capabilities": [
      {
        "name": "dev.ucp.shopping.checkout",
        "version": "2026-01-11"
      },
      {
        "name": "dev.uip.shopping.loyalty",
        "version": "2026-01-23"
      }
    ]
  },
  "id": "chk_1234567890",
  "status": "incomplete",
  "currency": "USD",
  "line_items": [
    {
      "id": "li_1",
      "item": {
        "id": "item_123",
        "title": "Red T-Shirt",
        "price": 2500
      },
      "quantity": 2,
      "totals": [
        {
          "type": "subtotal",
          "amount": 5000
        },
        {
          "type": "total",
          "amount": 5000
        }
      ]
    },
     {
      "id": "li_2",
      "item": {
        "id": "item_456",
        "title": "Blue T-Shirt",
        "price": 2000
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 2000
        },
        {
          "type": "total",
          "amount": 2000
        }
      ]
    }
  ],
  "totals": [
    {
      "type": "subtotal",
      "amount": 7000
    },
    {
      "type": "tax",
      "amount": 560
    },
    {
      "type": "total",
      "amount": 7560
    }
  ],
  "promotions": {
    "codes": [
      {
        "type": "referral",
        "code": "123456"
      }
    ],
    "discounts": [
      {
        "title": "10€ session discount",
        "target": "cart",
        "amount": 100
      },
      {
        "title": "10€ per item discount",
        "target": "item",
        "method": "each",
        "amount": 200,
        "allocations": [
          {
            "path": "$.line_items[0]",
            "amount": 100
          },
          {
            "path": "$.line_items[1]",
            "amount": 100
          }
        ]
      },
      {
        "title": "10€ bundle prorata discount",
        "target": "bundle",
        "method": "across",
        "amount": 100,
        "allocations": [
          {
            "path": "$.line_items[0]",
            "amount": 60
          },
          {
            "path": "$.line_items[1]",
            "amount": 40
          }
        ]
      }
    ],
    "free_items": [
      {
        "title": "Free item with referral",
        "code": "$.promotions.codes[0]",
        "path": "$.line_items[0]",
        "quantity": 1,
        "amount": 200
      }
    ]
  }
}
```

</TabItem>
</Tabs>

</StepsContainer>

### Upgrade a Talon.One UCP extension

When a new version of an extension is released, update the `version` field in your UCP
profile accordingly. You can find the latest version on [uip.dev](https://uip.dev).

## Related pages

- [Unified Commerce Protocol overview](https://ucp.dev/)
- [Unified Incentives Protocol overview](https://uip.dev/)