Skip to main content

Integration API best practices 

Use these best practices to build a reliable, secure, and efficient integration with Talon.One.

Resilience​

Design your integration to keep operating even when Talon.One is temporarily unreachable. Apply these patterns in order:

  1. Tight timeouts: Set a short timeout on every Integration API call. Fail fast rather than letting requests queue indefinitely.
  2. Bounded retries with exponential backoff and jitter: On a timeout or a 5xx error, retry a limited number of times with increasing delays and randomized jitter to avoid thundering herd during recovery.
  3. Circuit breaker: After a threshold of consecutive failures, open the circuit: stop calling Talon.One entirely and switch directly to your fallback. Close the circuit again after a recovery period.
  4. Fallback behavior: Define what your system does when the circuit is open. Fail open to a safe default: no promotions, a generic discount, or a cached response. Prefer fallback behaviours that never block the checkout process.
  5. Avoid immediate reads after writes: After updating a customer session, tracking an event, or updating a customer profile, avoid immediately calling endpoints that read the updated data. Some endpoints read from replica databases, which can take a short time to reflect recent writes. Wait for the write request to complete, then wait up to one second before making a read request. If the response still reflects the previous state, retry with backoff.

Performance​

Get more from each response​

Certain endpoints allow you to customize the response to get additional data from one call. Use this to increase performance in your integration layer.

When using the Update customer session endpoint or Update customer profile endpoint, you can set the responseContent property to a number of values, such as customerProfile, triggeredCampaigns, loyalty and more.

The response returns an extra property for each entity you use in responseContent.

Example

Imagine that we must update a session using the Update customer session endpoint and that our workflow requires us to fetch the customer profile data to complete some logic after this.

In theory, we should use the Update customer session and Get customer profile data endpoints.

We can skip the Get customer profile data call by setting the responseContent property to customerProfile in the Update customer session endpoint to get everything we need in one call.

Setting responseContent=["customerProfile","event"] in the request returns the following example payload:

{
  "customerSession": {
    "integrationId": "2354382gy",
    "created": "2021-08-24T14:15:22Z",
    "applicationId": 32
  },
  "customerProfile": {
    "id": 0,
    "created": "2019-08-24T14:15:22Z",
    "integrationId": "string",
    "accountId": 0,
    "closedSessions": 0,
    "totalSales": 0
  },
  "event": {
    "id": 0,
    "created": "2019-08-24T14:15:22Z",
    "applicationId": 0,
    "profileId": "string",
    "type": "string"
  }
}

Dry runs​

A dry request is a test request that is evaluated by Talon.One but not executed. To mark an Integration API request as dry, add the dry=true query parameter to a supported endpoint. No data about the request or its response is stored in Talon.One's database.

You can also use the now query parameter to simulate a request at a specific point in time. This is useful for testing time-related campaigns, such as a campaign that triggers on a specific date or time.

Dry requests help you simulate what if scenarios:

  • What if the end user adds this product to their cart?
  • What if the end user applies this coupon to their order?
  • Will a time-related campaign trigger on a specific future date for a specific session?

You can also check the output of a rule without affecting any of the analytics data that Talon.One generates.

  1. Your end user is looking at a product page.
  2. You fire a customer session update, pretending that the end user already put this item in their cart.
  3. If the API response includes a per-item discount for this cart item, the discounted price gets rendered on the page.
  • Send the complete cart state on every dry run. Bundle thresholds, cross-line-item rules, and tiered discounts all require the full cart. Do not send deltas.
  • Call dry runs at meaningful cart changes. Trigger them when items are added or coupons are applied, not on every user interaction such as each keystroke or page load.
  • Implement an intelligent caching solution on your side. Avoid calling the Talon.One API on every single page visit.

Security​

API key management​

  • Store API keys immediately on creation. A key is shown only once: if you lose it, you must create a new one.
  • Use separate keys per environment. Use sandbox keys for testing and live keys only in production.
  • Set an expiration date when creating every key. Talon.One sends email notifications to Admin users 30 days, 14 days, and 24 hours before expiry.
  • Rotate keys on a schedule aligned with your InfoSec policy.
  • Never embed keys in client-side code. Always call the Integration API from a backend environment.

See Integration API keys.

User account management​

See Manage users and manage roles.

Customer sessions and customer profiles​

Session integrity​

  • Serialize updates per session and profile. Sending parallel updates to the same customer session or profile causes 409 conflicts and race conditions. Apply updates sequentially from your backend or middleware.
  • Consider how to handle profile IDs and session IDs. Never use a shared integration ID. When it comes to profile IDs, consider the trade-offs from the integration checklist.
  • Always close sessions at checkout. A session in an open state is not committed. Send the final session update with state: closed at checkout, right before the user proceeds to the payment page.

Customer profile data​

  • Identify profiles with stable IDs. Avoid using email or phone numbers as profile Ids.
  • Consider GDPR. If GDPR is mandatory in your region, integrate the Delete customer's personal data endpoint.

Data extraction​

Keep Talon.One's data retention period in mind and implement automated raw data extraction from Talon.One for your own in-house reporting.

On this page