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 requests​

Dry requests are test requests that are evaluated by Talon.One but not executed. These requests are also refered to as dry runs.

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 and Authentication.

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.

Idempotency​

Idempotency ensures that a request only produces its result once, regardless of how many time this request is sent. This prevents duplicate processing in the case of connection errors, failures, or retries.

Talon.One supports idempotent requests for certain Integration API POST and PUT endpoints. Other request types such as GET and DELETE are idempotent by definition.

Where supported, the endpoint description contains a note indicating idempotency support. If you require idempotent processing for an endpoint where it is not yet supported, contact your Customer Success Manager.

To make processing idempotent, generate a unique idempotency key and include it in the Idempotency-Key header in requests. You can verify that a request was processed idempotently by checking whether an idempotency key HTTP header returned in the response. Header examples: Idempotency-Key, Idempotent-Replayed (where the value is set to true), X-Idempotency-Created-At, X-Idempotency-Expires-At, X-Idempotency-Fingerprint.

Also, note the following:

  • Requests with the Idempotency-Key header are logged in the Talon.One access logs.
  • Responses for idempotent requests are stored in the database and expire 24 hours after the request is sent.
  • Idempotency keys are typically UUID keys and should not exceed 255 characters in length.
  • By default, idempotency keys are valid for 24 hours after first use.
  • Idempotency is not supported for dry requests.
  • In the case of replay, where a stored response is re-executed, selected response headers are preserved.

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