Skip to content

Earn 30% on every license you refer. Join the affiliate program

$349
Get it · $349 Try demo
Sign in

Production checklist.

Launch-safety checklist for Agent API integrations, including idempotency, retries, key management, and reconciliation.

Oct 4, 2026

Use this checklist before you put a POS, e-commerce connector, or automation into production.

Key management

  • Use separate keys per environment. Do not share one key across local, staging, and production.
  • Use separate keys per integration surface when practical. A POS terminal fleet should not share the same key as an overnight reporting job.
  • Store keys in environment variables or a secrets manager.
  • Keep partner keys server-side. Never expose them in browser code or mobile apps.
  • Remember that the full key appears once and is never recoverable.
  • Rotate keys by creating the replacement first, updating the integration, then revoking the old key.

Scope hygiene

  • Start with least privilege.
  • Give write scopes for the resources the integration mutates, and no others.
  • Use member keys for member wallet operations and partner keys for partner-owned business actions.
  • Verify the final granted scopes by calling GET /api/agent/v1/health.

Transaction safety

Purchases can be made retry-safe. Redemptions and deductions cannot.

  • POST /partner/transactions/purchase with source_reference awards points once per business and sale reference, however many times you send it.
  • POST /partner/transactions/purchase without source_reference keeps its original behavior and can award points more than once if you replay the same order.
  • POST /partner/transactions/redeem can deduct points more than once if you replay the same logical redemption.
  • POST /partner/transactions/deduct can deduct points more than once if you replay the same logical deduction.

Send source_reference on every purchase an unattended system posts. A till, a middleware queue, and an automation platform all retry on their own after a timeout, and only the reference tells the app that the second call is the same sale.

POST /api/agent/v1/partner/transactions/purchase HTTP/1.1
Host: your-domain.com
Accept: application/json
Content-Type: application/json
X-Agent-Key: rl_agent_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0

{
  "card_id": "3598a5db-f008-477c-ac4d-5365c662ad62",
  "member_identifier": "[email protected]",
  "purchase_amount": "24.50",
  "currency": "EUR",
  "source_completed_at": "2026-08-26T09:41:07+02:00",
  "source_reference": "pos:store-1:till-3:98441",
  "note": "Order #12345"
}

The first call returns 201 with replayed: false. An identical retry returns 200 with replayed: true and the original transaction id, points, and balance, even after the card, the member, the staff member, or the Integration API key has changed since. See Record a purchase for the full field and response contract.

Recommended practice:

  • Treat a confirmed success response as final.
  • Build the reference from facts the source system already owns: platform, store, till, and sale id. Never put an email address, a phone number, a customer name, or a credential in it.
  • Reuse the same reference for every retry of one sale, and never for two sales.
  • On 503 with retry_strategy: backoff, resend the identical request with exponential backoff.
  • On 409 PURCHASE_REFERENCE_CONFLICT, stop: that reference is already recorded with different sale facts. Fix the sending system rather than retrying.
  • For redemptions and deductions, which have no reference of their own, reconcile an ambiguous failure before replaying.
  • Track your own external order IDs or redemption IDs.
  • Pass those IDs in the note field where the endpoint accepts one, so you can reconcile later.
  • For deductions, use the reference field to link to the external system (e.g., giftcard:order:12345).

Keep your APP key recoverable

Retry-safe purchases protect each stored sale record with the installation's APP_KEY. Rotate keys in this order:

  1. Move the current APP_KEY into APP_PREVIOUS_KEYS before deploying the new one.
  2. Clear and rebuild the configuration cache.
  3. Keep the old key configured while sale records still reference it. An exact retry moves each record to the new key on its own.
  4. Back up the database, the current APP_KEY, and every still-used previous key together, as one recovery set.

Removing a key that stored sale records still need turns their retries into 503 PURCHASE_CLAIM_KEY_UNAVAILABLE with retry_strategy: contact_support. No points are awarded twice, and restoring the key from backup repairs it. Losing every matching key cannot be repaired from the database alone.

Notes and reconciliation

Use the note field whenever the endpoint supports it.

Good values:

  • Order #12345
  • POS ticket 98441
  • Shopify order gid://shopify/Order/123456789
  • Cashier session 2026-03-08-07

This matters most for:

  • purchase reconciliation
  • reward-redemption investigation
  • stamp-adjustment audits
  • support tickets

Pagination and filtering

Do not assume list endpoints return all records in one response.

  • per_page defaults to 25
  • per_page maxes at 100
  • transaction list filters from and to accept Y-m-d

Example:

GET /api/agent/v1/partner/transactions?from=2026-03-01&to=2026-03-08&per_page=100 HTTP/1.1
Host: your-domain.com
Accept: application/json
X-Agent-Key: rl_agent_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9t0

Build pagination loops that handle every page.

Error handling

Your client should branch on retry_strategy, not HTTP status alone.

  • no_retry: stop and surface the failure
  • fix_request: correct the payload
  • backoff: honor Retry-After and use exponential backoff for operations that are safe to repeat. Reconcile other writes before retrying
  • contact_support: alert a human

Required launch-time tests:

  • invalid key
  • wrong scope
  • wrong role
  • resource not found
  • insufficient points or balance
  • rate limit exceeded
  • partner Agent API disabled

Rate limits

Authenticated requests that reach rate limiting include the headers below. Authentication and feature-gate failures may omit them. On 429, honor Retry-After; a successful response's reset timestamp is not an exact window boundary:

  • X-RateLimit-Limit
  • X-RateLimit-Remaining
  • X-RateLimit-Reset

On 429 RATE_LIMITED, honor Retry-After. Do not hammer the API after a rate-limit response.

Operational monitoring

  • Log outbound request IDs and your own order or ticket references.
  • Monitor Activity logs for unexpected automation behavior.
  • Keep failed writes for reconciliation. Automatically retry only operations that are safe to repeat.
  • Alert on repeated AUTH_INVALID_KEY, AUTH_INSUFFICIENT_SCOPE, and RATE_LIMITED responses.

Final launch checklist

  • Enable the feature flag in the correct environment
  • Enable the partner Agent API permission where required
  • Choose the correct key type and select its required write preset explicitly; the Partner key creation form selects View only
  • Minimize scopes and verify them via /health
  • Implement retry logic
  • Send source_reference on every unattended purchase, and reconcile redemptions and deductions by external reference
  • Back up the current APP_KEY and every still-used previous key with the database
  • Populate notes with external identifiers where supported
  • Implement pagination
  • Handle rate limits
  • Test every error branch