TechPrufer
Get started
Shopify
Shopify logoShopify · Feature trail

API Idempotency for Payment Services

6 posts · Aug 2019 – Jun 2025

What this trail covers

Shopify has established a robust API versioning strategy to ensure stability and predictability for its partners. This involves releasing new API versions quarterly with date-based names (e.g. 2020-01). The platform team builds the infrastructure and tooling to enforce this strategy, which includes managing breaking and non-breaking changes. Breaking changes require thorough impact analysis and stakeholder agreement, while non-breaking changes are tested for forward compatibility. The Payment Service has been enhanced with API idempotency to prevent duplicate charges and ensure reliable transaction outcomes, using idempotency keys, request locking, and a stepwise progress tracking mechanism for mutations.

All Shopify trails
  1. Introducing the commerce payments protocol (2025) - ShopifyThis post introduces the Commerce Payments Protocol, a new system for enabling real-world commerce on-chain. It addresses the limitations of existing crypto payments for commercial purchases by introducing a multi-stage payment commitment process. Key components include an escrow smart contract for authorization and capture, and a new role called 'operator' to facilitate fund movement and manage transaction fees. The protocol defines six core operations: authorize, capture, charge, void, reclaim, and refund, enabling features like delayed settlement, partial captures, and buyer/merchant protection. The initial implementation integrates with the ERC-3009 standard for payer authorization and leverages signing over a hash of payment details to ensure payer intent and prevent tampering by operators. Operators are restricted from modifying payment intents, locking funds in escrow, or impacting other operators' activities.
  2. 10 Tips for Building Resilient Payment Systems - ShopifyThis post details the use of ULIDs (Universally Unique Lexicographically Sortable Identifiers) for idempotency keys in payment services. ULIDs, which contain a timestamp, are preferred over UUIDv4 due to their sortable nature, leading to a 50% decrease in INSERT statement duration in high-throughput systems by working better with b-tree data structures used for indexing.
  3. Navigating Recurring Payments in India: A Backend Perspective - ShopifyThis post details the backend implementation for adapting Shopify's billing platform to new RBI regulations for recurring payments in India. Key contributions include: modeling the e-mandate concept by associating it with the 'source' object and its 'remote_reference', handling both recurring and one-time payments by tokenizing once for recurring payments to avoid user friction, implementing card payments through a PCI compliant server with AFA, and implementing UPI payments leveraging UPI AutoPay and handling its complex transaction limit logic by setting a maximum e-mandate limit of ₹5,000 and treating larger payments as one-time manual payments. It also details the backend logic for handling different payment scenarios for both cards and UPI, including sequence diagrams and entity-relationship diagrams.
  4. High Availability by Offloading Work Into the Background - ShopifyThis post details how Shopify uses background jobs to offload work and improve high availability. It explains the concept of background jobs, their benefits (response times, spikeability, retries, parallelization, prioritization, scheduling, code simplicity), and challenges (breaking changes, no exactly-once delivery, non-transactional queuing). It proposes the outbox pattern as a solution for transactional queuing.
  5. Building Resilient GraphQL APIs Using Idempotency - ShopifyIntroduced API idempotency to the Payment Service to ensure 'exactly once' transactionality. Implemented idempotency keys as first-class GraphQL parameters, request locking based on client + idempotency key to prevent simultaneous duplicates, and an IncomingRequest model to track request progress and store previous responses. Detailed a stepwise execution strategy for mutations, categorizing steps by side effects (no side effects, local side effects, remote side effects) and implementing 'run' and 'recover' functions for fault tolerance. This approach aims to provide clients with the flexibility to retry failed requests without causing duplication or conflicts.