Overview

Idempotency ensures that performing the same API action multiple times results in the same outcome as performing it once. This is crucial for reward issuance and currency allocation APIs, where network retries or partial failures could otherwise lead to duplicate rewards or points being issued. Capillary APIs implement idempotency using unique request identifiers, allowing safe retries and preventing duplicate processing.

Key Features

• Unique Request Identifier:
  Each API call that should be idempotent includes a unique identifier (requestId or uniqueId) in the request payload.
• Duplicate Detection:
  If the same identifier is used in multiple requests, the system recognizes the duplicate and ensures the operation is only processed once.
• Partial Success Handling:
  In scenarios where only part of a bulk operation succeeds, you can safely retry the request with the same identifier. The system will only process the remaining items, not duplicate the already successful ones.

Usage in APIs

1. Issue Rewards APIs (Single and Bulk)

• Parameter: requestId (string, required for idempotency)

• Where to Use:

  • In the request body for each reward in bulk issuance.
  • In single reward issuance, as a top-level parameter.

• Behavior:

  • If a request with the same requestId is received again, the API will not issue the reward again, ensuring no duplicates.
  • In bulk issuance, each reward can have its own requestId for granular control.

• Example:

  JSON

  {
      "mobile": "919825752814",
      "brand": "testOrg_marvel_20230822_147",
      "transactionNumber": "2344s4",
      "rewards": [
          {
              "rewardId": 125099,
              "quantity": 2,
              "requestId": "req3"
          },
          {
              "rewardId": 125101,
              "quantity": 2,
              "requestId": "req4"
          }
      ]
  }

• Partial Success:
  If only some rewards are issued (e.g., due to limits), retrying with the same requestId will only process the remaining rewards, not duplicate the successful ones.
  See example scenarios

• References:
  Idempotency Check for Issuing Reward

2. Issue Reward Currency API (Points and Alternate Currencies)

• Parameter: uniqueId (string, required for idempotency)

• Where to Use:

  • In the request body for each manual currency allocation.

• Behavior:

  • If a request with the same uniqueId is received again, the API will not issue the currency again.

• Example:

  JSON

  {
      "orgId": 12345,
      "programId": 67890,
      "awardStrategyId": 111,
      "expiryStrategyId": 222,
      "sourceValue": 1000,
      "eventName": "TransactionAdd",
      "eventSourceId": "BILL123",
      "lookupParams": {
          "entityType": "CUSTOMER",
          "identifierType": "mobile",
          "identifierValue": "919876543210"
      },
      "uniqueId": "currency-issue-001"
  }

• References:
  Issue Reward Currency API

3. Points Redemption APIs

• Observation:
  The knowledge sources do not explicitly mention an idempotency parameter for the Points Redemption APIs (v1.1). These APIs focus on validation and redemption using codes, and do not document a requestId or uniqueId for idempotency.
  Points (v1.1) API

Best Practices

• Always generate a unique requestId or uniqueId for each idempotent API call.
• For retries (due to network errors or partial failures), use the same identifier to ensure safe, non-duplicative processing.
• If you need to re-issue a reward or currency, use a new identifier.

Error Handling

• If a duplicate request is detected (same requestId or uniqueId), the API will not process the operation again and will return the original response or an error indicating a duplicate request.

Summary

Idempotency in Capillary APIs is implemented via unique request identifiers, ensuring that reward issuance and currency allocation are safe from duplication even in the face of retries or partial failures. This mechanism is critical for robust, reliable integrations with Capillary’s loyalty and rewards platform.