# Point of sale systems

> You can integrate Talon.One with your point of sale (POS) system to enable real-time campaign, coupon, and loyalty logic at checkout.

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

A point of sale integration connects in-store transaction systems
to Talon.One and offers the following benefits:

- **Unified promotions**: Run consistent offers across online and in-store channels.
- **Real-time validation**: Apply discounts and loyalty effects during checkout.
- **Centralized reporting**: Capture redemptions and outcomes for analytics.
- **Flexible architecture**: Support online, offline, and hybrid POS models.

:::note
For Shopify, we provide a dedicated [POS
integration](/docs/dev/technology-partners/shopify/set-up-shopify-app.md#enable-pos-support)
as part of the Talon.One Shopify app. This integration is designed to work seamlessly
with Shopify's POS system and offers a streamlined setup process.
:::

## Integration modes

Because POS systems differ in architecture, latency tolerance, and connectivity,
integrations should be designed to maintain real-time responsiveness while ensuring
data consistency when offline. As a result, choosing the right integration mode
depends on your business setup and the environment of your POS terminals.

| Mode          | Description                                                                      | Ideal context                          |
|---------------|----------------------------------------------------------------------------------|----------------------------------------|
| **Connected** | POS communicates directly with Talon.One in real time using the Integration API. | Reliable network, online checkout.     |
| **Hybrid**    | Middleware buffers requests and syncs the POS and Talon.One asynchronously.      | Distributed POS or multi-store setups. |
| **Offline**   | Transactions are stored locally and are synced at regular intervals.             | Limited or intermittent connectivity.  |

## Best practices

### Planning stage

Follow these best practices during the planning stage:

1. Understand Talon.One's fundamental [entities](/docs/dev/concepts/entities/entities-overview.md)
   and how they relate to POS concepts.

    <details>
      <summary>See how Talon.One concepts map to typical POS concepts</summary>

     | Concept                                                                           | Description                                                                                                                                                                                                                                                                               |
     |-----------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
     | [Customer session](/docs/dev/concepts/entities/customer-sessions.md)              | Represents shopping carts and checkout operations. It typically maps to POS interactions.                                                                                                                                                                                                 |
     | [Customer profile](/docs/dev/concepts/entities/customer-profiles.md)              | Represents a customer's data in Talon.One, including their loyalty points.                                                                                                                                                                                                                |
     | [Store](/docs/dev/concepts/entities/stores.md)                                    | Represents a physical or digital sales channel. Creating and connecting stores to campaigns and passing the `storeIntegrationId` at checkout time enables store-specific campaign targeting. It also enables you to leverage store metadata such as region, store type, and opening date. |
     | [Attribute](/docs/dev/concepts/attributes.md)                                     | Represents context-specific data needed by the POS system.                                                                                                                                                                                                                                |
     | [Event](/docs/dev/concepts/entities/events.md)                                    | Represents a single occurrence of a customer action related to a session or profile. You can create custom events containing one or more attributes.                                                                                                                                      |
     | [Effect](/docs/product/rules/effects/overview.md)                                 | Allows you to communicate any data from Talon.One to your POS system in the form of a structured effect. Common effects include `setDiscount`, `setDiscountPerItem`, `acceptCoupon`, `rejectCoupon`, `addFreeItem`, and `customEffect`.                                                   |
     | [Coupon](/docs/product/campaigns/coupons/coupon-page-overview.md)                 | Represents a coupon and how it was entered, validated, redeemed, or rejected.                                                                                                                                                                                                             |
     | [Loyalty program](/docs/product/loyalty-programs/overview.md)                     | Represents how loyalty points are earned and redeemed.                                                                                                                                                                                                                                    |
     | [Cart item catalog](/docs/product/account/dev-tools/manage-cart-item-catalogs.md) | Optional product catalog that allows you to synchronize your product information management (PIM) system with Talon.One. This improves promotion evaluation and integration in hybrid or offline modes.                                                                                   |
     | [Strikethrough pricing](/docs/product/rules/strikethrough-pricing.md)             | In offline mode, strikethrough pricing acts as the source of truth for discounted prices, custom labels, and metadata that the POS can ingest.                                                                                                                                            |

    </details>

- Universal IDs: Use consistent universal identifiers for customer sessions,
  customer profiles, and loyalty cards across all channels.
- [Attributes](/docs/dev/concepts/attributes.md): Define all the necessary attributes
  (for example, session, profile, or cart item) early in the project.
- [Stores](/docs/dev/concepts/entities/stores.md): Pass a `storeIntegrationId` with
  associated metadata, `is_live`, `channel_type`, `region`, and `opening_date`, to
  enable store-specific campaigns and provide future flexibility without modifying
  core integration.
- Pricing: The POS should send prices as part of the session data.
- Rule translation for hybrid or offline flows: Plan how Talon.One rules are
  translated into local evaluation rules the POS can interpret.
  Use [strikethrough pricing](/docs/product/rules/strikethrough-pricing.md) as the
  source of truth for discounted prices,
  custom labels, and metadata.
  Propagate updates to this data via [strikethrough pricing updates](/docs/product/applications/application-notifications/overview.md#strikethrough-pricing-updates),
  [Application notifications](/docs/product/applications/application-notifications/create-application-notifications.md),
  and [campaign-related changes](/docs/product/applications/application-notifications/overview#campaign-related-changes) notifications
  to let the POS ingest and store the pre-calculated outcomes for low-latency or
  offline usage.

### Implementation stage

Follow these best practices during the implementation stage:

1. Minimize latency:
   - Optimize payload size by excluding non-essential attributes.
   - Cache static data like cart item attributes locally.
   - Use connection pooling and retry logic with exponential backoff.

1. Handle offline transactions:
   - Implement a local fallback mechanism for when Talon.One is unreachable.
   - Queue unsent sessions and replay them after connectivity is restored.
   - Consider implementing simple fallback promotions or standard discounts.

1. Maintain data integrity:
   - Use consistent identifiers such as `integrationId`, `SKU`, and `storeId` across systems.
   - Verify response integrity and effects returned from Talon.One.
   - Validate time synchronization between POS and backend systems.

1. Secure communication:
   - Use HTTPS for all requests.
   - Use scoped API keys per environment (staging or production).
   - Avoid embedding credentials directly in POS clients. Use a secure middleware proxy.

## API endpoints

The following endpoints are the most relevant for POS integration:

| Endpoint                                                                                            | Purpose                                                                                                                                                                                                                                                                                      |
|:----------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Update customer session](/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2) | Send customer session data such as cart items and coupons to Talon.One and receive effects. This is a core endpoint for POS interactions.                                                                                                                              |
| [Track event](/integration-api#tag/Events/operation/trackEventV2)                                   | Used for actions or specific data points required for campaign evaluation.                                                                                                                                                                                                                   |
| [List customer data](/integration-api#tag/Customer-profiles/operation/getCustomerInventory)         | Used to retrieve inventory or profile-related data linked to a customer profile.                                                                                                                                                                                                             |
| [Management API](/docs/dev/management-api/overview.md)                                              | Used for back-office operations, such as creating and managing campaigns and coupons. It is subject to a soft rate limit of three requests per second and is also used to sync campaign definitions and coupon details to external systems or local POS instances for offline functionality. |

## Troubleshooting and optimization

When integrating Talon.One with your POS system, you can encounter challenges
related to latency, data consistency, and error handling. Here are some tips to
help you troubleshoot and optimize your integration:

### Operational oversight and troubleshooting

Typical issues include:

- Promotion not displaying or applying: Verify whether the POS supports displaying specific
  effects such as upsell messages or GWP qualification notifications.
  Check Talon.One, middleware, and POS logs for error codes or reasons.
- Offline scenario issues: Confirm adherence to established offline fallback procedures
  such as manual overrides.
- Coupon rejection: Investigate specific rejection reasons from Talon.One's API and the
  POS system.
- Campaign evaluation errors: Check if the required session, cart item, or profile custom attributes
  such as `storeId` and `channel` are passed and if campaign targeting conditions are met in
  Talon.One.
- Data synchronization failures: For batch or asynchronous integrations, monitor logs
  for issues in transferring campaign definitions, product data, or transaction data
  between systems.
- Performance bottlenecks: High API call volumes during peak times can lead to
  performance issues. Review logs if a specific set of sessions is the root cause,
  and design potential optimizations such as batching, improving Talon.One rules, and
  asynchronous processing.

### Offline management and fraud prevention

Consider the following when managing offline scenarios and implementing fraud prevention measures:

- Offline fallback: Confirm adherence to established offline fallback procedures
  (for example, manual overrides or campaign definition translations on the POS).
- Fraud mitigation: Be vigilant about omnichannel coupon fraud in hybrid scenarios due
  to asynchronous syncing, which creates a window for double redemption. Implement or
  plan for mechanisms to prevent and reconcile such instances. Continuously enhance fraud
  prevention for manual overrides or delayed transaction syncing.

## Related pages

- [Integration API overview](/docs/dev/integration-api/overview.md)
- [Shopify POS integration](/docs/dev/technology-partners/shopify/set-up-shopify-app.md#enable-pos-support)