Idempotency Map and Implementation Patterns

Idempotency is a critical design principle in distributed systems, particularly in agentic commerce where multiple agents may retry operations due to network failures, timeouts, or coordination challenges. An Idempotency Map is a systematic approach to ensuring that repeated execution of the same operation produces the same result without unintended side effects.

Idempotency Key Generation Strategy

Every critical operation in the system must be associated with a unique idempotency key. The key generation strategy varies based on the operation type:

Idempotency Table Schema

Xano maintains a dedicated idempotency_log table to track all processed operations:

CREATE TABLE idempotency_log (
  id SERIAL PRIMARY KEY,
  idempotency_key VARCHAR(255) UNIQUE NOT NULL,
  operation_type VARCHAR(100) NOT NULL,
  request_payload JSONB,
  response_payload JSONB,
  status VARCHAR(50) NOT NULL, -- 'processing', 'completed', 'failed'
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW(),
  expires_at TIMESTAMP,
  user_id INTEGER,
  session_id VARCHAR(255),
  INDEX idx_idempotency_key (idempotency_key),
  INDEX idx_user_session (user_id, session_id),
  INDEX idx_expires_at (expires_at)
);

Idempotency Check Flow

The idempotency check process follows a consistent pattern across all critical operations:

1. Request Received: The AI agent or external system sends a request with an idempotency key in the header (Idempotency-Key: {key})

2. Key Lookup: Xano queries the idempotency_log table for the provided key

3. Decision Logic:

   • Key Not Found: Proceed with operation, insert record with status processing
   • Key Found, Status completed: Return cached response from response_payload
   • Key Found, Status processing: Return HTTP 409 Conflict (operation in progress)
   • Key Found, Status failed: Allow retry, update status to processing

4. Operation Execution: Execute the business logic within a database transaction

5. Result Storage: Update the idempotency record with status completed and store the response

6. Response Return: Return the result to the caller

Session-Specific Idempotency Patterns

Session Token Generation

When a user authenticates, Xano generates a JWE token. To prevent duplicate session creation:

• Idempotency Key: session:{userId}:{deviceId}:{timestamp}
• Check: Before creating a new session, verify if an active session exists for the user/device combination
• Action: If active session exists, return existing JWE token instead of creating a new one

Session State Updates

For stateful operations within a session (e.g., updating cart, saving preferences):

• Idempotency Key: session_update:{sessionId}:{operationType}:{sequenceNumber}
• Sequence Number: Monotonically increasing counter to ensure ordered processing
• Conflict Resolution: If a later sequence number has been processed, reject earlier requests

Transaction-Specific Idempotency Patterns

Cart Mandate Creation

The Cart Mandate represents the user's commitment to purchase specific items at a specific price.

• Idempotency Key: Generated from cart contents hash: SHA256(sorted_variant_ids + quantities + prices)
• Validation: Before creating a new mandate, check if an identical cart mandate exists for the session
• Expiration: Cart mandates expire after 30 minutes to prevent stale pricing

Payment Processing

Payment operations are the most critical for idempotency to prevent double-charging.

• Idempotency Key: payment:{orderId}:{amount}:{currency}:{timestamp}
• Payment Gateway Integration: Pass the same idempotency key to the payment gateway (Stripe, Adyen) to ensure end-to-end idempotency
• Reconciliation: Store payment gateway transaction ID in the idempotency log for reconciliation

Order Creation

Orders must be created exactly once per Cart Mandate.

• Idempotency Key: Derived from Cart Mandate ID: order:{cartMandateId}:{userId}
• Foreign Key Constraint: The orders table has a unique constraint on cart_mandate_id to enforce database-level idempotency

Webhook Idempotency Patterns

Webhooks from Shopify and payment gateways may be delivered multiple times. Xano implements webhook idempotency to prevent duplicate processing.

Shopify Webhook Processing

• Idempotency Key: webhook:shopify:{event_id} (from X-Shopify-Event-Id header)
• Verification: Validate webhook signature using HMAC-SHA256
• Deduplication: Check idempotency log before processing the event
• Use Cases:
  • Order creation notifications
  • Payment confirmation (ShopPay gateway Order IDs)
  • Inventory updates
  • Customer data changes

Payment Gateway Webhook Processing

• Idempotency Key: webhook:{gateway}:{transaction_id}:{event_type}
• Event Types: payment.succeeded, payment.failed, refund.processed
• State Machine: Maintain payment state machine to prevent invalid state transitions

Data Synchronization Idempotency

For bidirectional sync between Xano and Shopify (user data, consent history):

User Data Sync

• Idempotency Key: sync:user:{userId}:{version}:{timestamp}
• Version Control: Use optimistic locking with version numbers
• Conflict Resolution: Last-write-wins with timestamp comparison
• Consent History: User consent changes are append-only, never updated

Product Data Sync

• Idempotency Key: sync:product:{upid}:{version}
• Cache Invalidation: Products are not cached per Shopify guidelines, but product snapshots in orders are immutable

Idempotency Expiration and Cleanup

To prevent unbounded growth of the idempotency log:

• Expiration Policy: Idempotency records expire after 24 hours for most operations, 7 days for financial transactions
• Cleanup Job: A scheduled Xano background task runs daily to purge expired records
• Archival: Financial transaction idempotency records are archived to a separate table for audit purposes before deletion

Idempotency in A2A Agent Communication

When agents communicate via the A2A protocol, idempotency is managed at the protocol level:

• Task ID: Each A2A task has a unique task ID that serves as the idempotency key
• Task State: Tasks have states (pending, in_progress, completed, failed)
• Retry Logic: If an agent retries a task, the receiving agent checks the task state and returns the cached result if already completed

Idempotency Monitoring and Alerting

Xano implements monitoring to detect idempotency-related issues:

• Duplicate Detection Rate: Track the percentage of requests that are duplicates
• Idempotency Conflicts: Alert when multiple requests with the same key arrive simultaneously
• Failed Retries: Monitor operations that fail repeatedly with the same idempotency key
• Dashboard Metrics: Display real-time idempotency statistics in the Xano admin dashboard

Next: Migration Plan →