# Grocery

> Talon.One fits seamlessly into the grocery ecosystem where promotions drive traffic and cart size. It empowers grocery retailers to run loyalty programs, personalized promotions, and supplier-funded campaigns across web, app, and point-of-sale channels. This works even with catalogs of 100,000+ items and hundreds of active promotions running at once.

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

This page outlines integration approaches and use cases tailored to grocery
retail scenarios ranging from full-service supermarkets to convenience stores and
online grocery platforms.

## Use cases

### Loyalty programs

#### Tiered points

Create a [loyalty program](/docs/product/loyalty-programs/overview.md) with
[tiers](/docs/product/loyalty-programs/profile-based/use-loyalty-tiers.md)
that reset each month. The reward reflects that month's spend rather than
historical loyalty. This creates a recurring incentive to reach the next
threshold instead of rewarding spend that would have happened anyway.
Configure an [absolute expiration date](/docs/product/loyalty-programs/profile-based/use-loyalty-tiers.md#absolute-expiration-date)
so tiers reevaluate monthly. Use the
[match current balance](/docs/product/loyalty-programs/profile-based/use-loyalty-tiers.md#match-current-balance)
downgrade method so each tier reflects only that month's spend.

For example, a grocery retailer sets three monthly spend thresholds: €100, €250, and
€500. Reaching a threshold in one month unlocks a 3%, 5%, or 10% bonus, respectively, on the
customer's spend the following month. Each month resets, so customers need to
reach the threshold again to keep earning the bonus.

#### Cashback to loyalty card

Use a [card-based loyalty program](/docs/product/loyalty-programs/card-based/card-based-overview.md)
to let customers collect and spend points on a loyalty card. Award
points that represent a percentage of a customer's spend as cashback that
customers can spend directly at a [point of sale (POS) system](/docs/dev/technology-partners/pos/overview).

For example, a grocery retailer awards points equal to 2% of a customer's spend to
their loyalty card after each purchase. The customer redeems the balance
directly at checkout on their next visit.

### Gamification

#### Purchase streak missions

Set up [achievements](/docs/product/achievements/overview.md) for your campaigns to
run short time-limited missions that encourage repeat visits. This works well
for convenience stores since customers already visit multiple times a week.

For example, a five-day purchase streak awards bonus points that increase with each
consecutive day. It ends with a coupon for a free item.

### Promotions

#### Mass and gated promotions

Mass promotions discount anchor products like milk or eggs for any customer
with no sign-in required. Use
[cart item catalogs](/docs/product/account/dev-tools/manage-cart-item-catalogs.md)
to tag products by category so the discount applies automatically. For example, a weekly leaflet promotion discounts dairy products for all
shoppers.

Gated promotions unlock broader discounts once a customer joins the loyalty
program. Use a [coupon](/docs/product/campaigns/coupons/create-coupons.md)
to gate the offer behind sign-up. For example, a €5 welcome coupon is reserved for customers who register
in the app.

#### Member pricing

Use [price types](/docs/product/account/dev-tools/manage-price-types.md) to target specific audiences by displaying a personalized price on a product listing before checkout. This
lets an online grocery retailer show member-only pricing without requiring the
customer to complete a transaction first.

For example, a loyalty member browsing a delivery app sees a discounted
member price on a product listing while a non-member sees the standard
price.

### Referrals

#### Referral bonuses

Every customer gets a unique
[referral code](/docs/product/campaigns/referrals/referral-overview.md) they
can share with friends. Once redeemed, Talon.One links the
[advocate and friend](/docs/product/tutorials/loyalty/loyalty-points-for-referral.md).
This awards a separate bonus to each.

For example, an online grocery retailer grants the advocate 50 loyalty points after a
friend's first completed order. The friend receives a coupon for €10 off
their first order in return.

To manage spend, some grocery retailers cap the total referral
[budget](/docs/product/campaigns/settings/manage-campaign-budgets.md) at €50
per advocate. The advocate's fourth successful referral then earns a
different bonus. This encourages the advocate to keep referring even after reaching the €50 cap.

### Store-based offers

#### Franchise-level campaigns

Set
[budgets](/docs/product/campaigns/settings/manage-campaign-budgets.md) at
the [store](/docs/product/applications/display-stores.md) level so that
franchisees in individual locations can run their own offers without
affecting the group's overall spend.

For example, a franchise network runs a national promotion that gives
every customer double loyalty points on breakfast items like eggs, milk,
and coffee before 10 a.m. Individual franchisees can still add their own
store-specific offers within their own store budget.

### Supplier-funded campaigns

#### CPG-funded placement

Consumer Packaged Goods (CPG) suppliers (such as beverage or snack brands)
often help pay for a campaign in return for better shelf placement or
advertising. Use [custom effects](/docs/product/account/dev-tools/manage-custom-effects.md)
to track how much each supplier contributes. Export this data from
[campaign insights](/docs/product/campaigns/analytics/campaign-insights.md)
and share it with the supplier as a report.

For example, a grocery chain runs a promotion funded by a beverage supplier
in return for higher shelf placement. The grocery chain also sends the
supplier a report showing how the promotion affected sales.

## API endpoints

The [Integration API][iapi] is the primary API for real-time interaction
with Talon.One.

The endpoints you work with depend on your use case. These are generally the
most relevant endpoints for grocery integrations:

| Endpoint                                                                                             | Description                                                                                                                       |
| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| [Update customer session][update-session]                                                            | Update the customer session with the latest data when the customer completes a purchase. |
| [Update customer profile][update-profile]                                                            | Set custom attributes, for example, category spend or dietary preference, for a customer profile. You can also use this endpoint to modify the audience in which the customer is a member. |
| [Track advanced event][track]                                                                        | Trigger custom events on real-time customer actions, for example loyalty program sign-up or app registration.                      |
| [Create coupon reservation][coupon]                                                                   | Create coupon codes for the customer profile, for example as a loyalty sign-up or referral bonus.                                     |

## Concepts

Here's an explanation of some specific Talon.One concepts that are relevant
for grocery use cases:

| Concept                                                                    | Description                                                                                                       |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| [Customer session](/docs/dev/concepts/entities/customer-sessions.md)       | A customer's cart. For example, a shopper building an order in your app.                                          |
| [Event](/docs/dev/concepts/entities/events.md)                             | A single occurrence of a customer action, for example, joining a loyalty program or redeeming a coupon.           |
| [Cart items](/docs/product/account/dev-tools/manage-cart-item-catalogs.md) | Products added to an order, for example, milk, eggs, or bread. Each item can include attributes like `category` or `SKU`. |
| [Custom attributes](/docs/dev/concepts/attributes.md#custom-attributes)   | Product-specific or order metadata. For example, `category` or `dietaryPreference`.                               |

[iapi]: /docs/dev/integration-api/overview.md
[track]: /integration-api#tag/Events/operation/trackEventV3
[update-session]: /integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2
[update-profile]: /integration-api#tag/Customer-profiles/operation/updateCustomerProfileV2
[coupon]: /integration-api#tag/Coupons/operation/createCouponReservation