Skip to main content

Management API best practices 

Use these best practices to build a reliable and efficient integration with the Talon.One Management API.

Rate limits​

The Management API allows up to three requests per second per endpoint.

  • Keep all Management API calls out of user-facing flows. Reserve it for back-office operations: reporting pipelines, coupon generation for support agents, scheduled data imports. Never call Management API endpoints from checkout or other real-time paths.
  • Stay comfortably under the limit. Design automations to run at two requests per second or fewer to leave headroom.
  • Handle 429 responses. If you receive a 429 Too Many Requests, wait before retrying. Use exponential backoff with jitter: randomize the delay to avoid synchronized retry waves.
  • Notify Talon.One before bulk operations. If you plan a large data migration, mass import, or when you have a large sales event approaching, contact support@talon.one at least five business days in advance so the infrastructure can be prepared. This also applies after the initial integration phase.

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 1 second before making a read request. If the response still reflects the previous state, retry with backoff.

API key management​

Management API keys are tied to the user account that created them. If that user is deactivated through manual offboarding or an SSO or IdP change, all their keys stop working immediately, breaking any automation that depends on them.

  • Use a dedicated account for automation keys. Create a non-personal user (a bot or service account) and use it to create all Management API keys used by automated systems. This decouples key validity from individual staff lifecycles.
  • Set an expiration date when creating every key.
  • Rotate keys on a schedule aligned with your InfoSec policy.
  • Store keys immediately on creation. A key is shown only once: if you lose it, you must create a new one.
  • Never embed keys in client-side code. Always call the Management API from a backend environment.

See Manage Management API keys.

Large data operations​

Management API endpoints for imports and exports can handle large datasets. Apply these practices to keep operations efficient and predictable.

  • Use pagination for large result sets. Pass the pageSize and skip parameters to page through results. Avoid fetching all records in a single call.
  • Use batch endpoints where available. Endpoints such as Create loyalty cards, Create coupons asynchronously and Create coupon deletion job are more efficient than making one request per record.
  • Schedule long-running operations off-peak. Imports and exports are excluded from the standard 5-minute timeout cap but still consume backend resources. Run them during low-traffic periods to avoid contention with Integration API traffic.

Health monitoring​

Use the Application API health endpoint to monitor the health of your API connection in steady state.

StatusMeaning
OKOnly successful requests in the last 5 minutes.
WARNINGAt least one failed request in the last 5 minutes.
ERRORMore than 50% of requests failed.
CRITICALAll requests failed.
NONENo Integration API requests recorded in the last 5 minutes.

This endpoint reflects Integration API traffic only, not Management API traffic. Use it for steady-state monitoring while your integration is active. Do not use it to decide when to restore traffic after an outage: while the circuit breaker is open and no requests are flowing, the status returns NONE, which cannot confirm recovery.

On this page