Skip to content
Reward Loyalty
Reward Loyalty
Buy Now
ESC

Searching...

Quick Links

Type to search • Press ↑ ↓ to navigate • Enter to select

Keep typing to search...

No results found

No documentation matches ""

Documentation
Back to Home Buy Reward Loyalty

Production Checklist.

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

Mar 8, 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 a nightly reporting job.
  • Store keys in environment variables or a secrets manager.
  • Keep partner keys server-side only. Never expose them in browser code or mobile apps.
  • Remember that full keys are shown once and are 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 only for the resources the integration actually mutates.
  • 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

The purchase and redemption flows are not idempotent.

  • POST /partner/transactions/purchase can award points more than once if you replay the same logical order.
  • POST /partner/transactions/redeem can deduct points more than once if you replay the same logical redemption.

Recommended practice:

  • Treat a confirmed success response as final.
  • Purchase returns 201; redemption returns 200.
  • If you get a timeout or ambiguous network failure, reconcile before replaying.
  • Track your own external order IDs or redemption IDs.
  • Pass those IDs in the note field where supported so reconciliation is possible later.

Example:

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,
  "note": "Order #12345"
}

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 is especially useful 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 explicitly.

Error Handling

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

  • no_retry: stop and surface the failure
  • fix_request: correct the payload
  • backoff: retry with exponential backoff
  • 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

Every response includes rate-limit headers:

  • 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 a dead-letter or retry queue for backoff errors.
  • Alert on repeated AUTH_INVALID_KEY, AUTH_INSUFFICIENT_SCOPE, and RATE_LIMITED responses.

Final Launch Checklist

  • Feature flag enabled in the correct environment
  • Partner Agent API permission enabled where required
  • Correct key type chosen
  • Scopes minimized and verified via /health
  • Retry logic implemented
  • Non-idempotent purchase and redemption flows reconciled by external reference
  • Notes populated with external identifiers where supported
  • Pagination implemented
  • Rate-limit handling implemented
  • Error branches tested

Related Topics