Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Add Idempotency-Key support to mutating API endpoints (#13731)
Damian Legawiec397173a1107d
diff --git a/docs/api-reference/store-api/errors.mdx b/docs/api-reference/store-api/errors.mdxindex 876a4ac9d9..97b3ec5a3b 100644--- a/docs/api-reference/store-api/errors.mdx+++ b/docs/api-reference/store-api/errors.mdx@@ -49,6 +49,7 @@ Validation errors include an additional `details` field with per-field error mes| `401` | Unauthorized | Missing or invalid API key, expired JWT token || `403` | Forbidden | Authenticated but not authorized for this resource || `404` | Not Found | Resource doesn't exist or isn't accessible |+| `409` | Conflict | Resource was modified by another request (concurrent update) || `422` | Unprocessable Content | Validation failed, invalid state transition, payment error || `429` | Too Many Requests | Rate limit exceeded (see [Rate Limiting](/api-reference/store-api/rate-limitting)) |@@ -115,6 +116,13 @@ Validation errors include an additional `details` field with per-field error mes| `digital_link_expired` | 403 | Download link has expired || `download_limit_exceeded` | 403 | Maximum number of downloads reached |+### Concurrency & Idempotency Errors++| Code | Status | Description |+|------|--------|-------------|+| `order_already_updated` | 409 | Order was modified by another concurrent request. Retry with fresh data. |+| `idempotency_key_reused` | 422 | Idempotency key was already used with different request parameters. See [Idempotency](/api-reference/store-api/idempotency). |+### Other Errors| Code | Status | Description |diff --git a/docs/api-reference/store-api/idempotency.mdx b/docs/api-reference/store-api/idempotency.mdxnew file mode 100644index 0000000000..22643d6988--- /dev/null+++ b/docs/api-reference/store-api/idempotency.mdx@@ -0,0 +1,131 @@+---+title: "Idempotency"+sidebarTitle: "Idempotency"+description: "Prevent duplicate operations with idempotency keys"+---++The Store API supports idempotency keys on mutating endpoints. This lets you safely retry requests without risking duplicate side effects — for example, adding an item to cart twice or creating duplicate payments due to network timeouts.++## How It Works++Include an `Idempotency-Key` header with a unique value (e.g., a UUID) on any supported request. The API will:++1. **First request** — process normally and cache the response for 24 hours+2. **Duplicate request** (same key, same parameters) — return the cached response without re-executing the operation+3. **Key reuse with different parameters** — return a `422` error to prevent misuse++```bash+curl -X POST https://api.mystore.com/api/v3/store/orders/or_xxx/line_items \+ -H "Authorization: Bearer spree_pk_xxx" \+ -H "X-Spree-Order-Token: abc123" \+ -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \+ -H "Content-Type: application/json" \+ -d '{"variant_id": "variant_xxx", "quantity": 1}'+```++If the client retries this exact request with the same idempotency key, the API returns the original response with an `Idempotent-Replayed: true` header — without adding the item again.++## Supported Endpoints++| Endpoint | Actions |+|----------|---------|+| `POST /cart` | Cart creation |+| `PATCH /orders/:id` | Order updates |+| `PATCH /orders/:id/next` | Checkout state transition |+| `PATCH /orders/:id/advance` | Checkout advancement |+| `PATCH /orders/:id/complete` | Order completion |+| `POST /orders/:id/line_items` | Adding items to cart |+| `POST /orders/:id/payment_sessions` | Payment session creation |+| `PATCH /orders/:id/payment_sessions/:id/complete` | Payment completion |+| `POST /orders/:id/coupon_codes` | Applying coupon codes |+| `POST /orders/:id/store_credits` | Applying store credits |++Idempotency keys are ignored on `GET`, `DELETE`, and other non-supported actions.++## Key Requirements++- Must be a string of **255 characters or less**+- Should be unique per distinct operation (UUIDs are recommended)+- Keys are scoped per API key — different API keys can use the same idempotency key without conflict+- Cached responses expire after **24 hours**++## Response Headers++When a cached response is replayed, the API sets:++```+Idempotent-Replayed: true+```++You can use this header to detect replayed responses in your application or logging.++## Error Handling++### Key Reuse with Different Parameters++If you send a request with an idempotency key that was previously used with different request parameters (different body, different path), the API returns a `422` error:++```json+{+ "error": {+ "code": "idempotency_key_reused",+ "message": "This Idempotency-Key has already been used with different request parameters."+ }+}+```++### Key Too Long++Keys longer than 255 characters return a `400` error:++```json+{+ "error": {+ "code": "invalid_request",+ "message": "Idempotency-Key must be 255 characters or less."+ }+}+```++### Server Errors++`5xx` responses are **not cached**. If the server fails to process your request, you can safely retry with the same idempotency key and the request will be re-executed.++## SDK Usage++The Spree SDK supports idempotency keys via the `idempotencyKey` option:++```typescript+import { createSpreeClient } from '@spree/sdk'++const client = createSpreeClient({+ baseUrl: 'http://localhost:3000',+ publishableKey: 'spree_pk_xxx',+})++// Add item to cart with idempotency key+await client.store.orders.lineItems.create(orderId, {+ variant_id: 'variant_xxx',+ quantity: 1,+}, {+ idempotencyKey: '550e8400-e29b-41d4-a716-446655440000',+})+```++## Best Practices++- **Generate a new key for each distinct operation.** Use a UUID (v4) or another random identifier. Never reuse keys across different operations.+- **Store the key before sending the request.** If the request fails due to a network error, retry with the same key to ensure the operation is only performed once.+- **Don't use idempotency keys for GET requests.** GET requests are naturally idempotent and the API ignores the header on read-only endpoints.+- **Let keys expire naturally.** Cached responses expire after 24 hours. Don't rely on idempotency keys for longer-term deduplication.++## Relationship with Optimistic Locking++The Store API also uses [optimistic locking](/api-reference/store-api/introduction) via the `state_lock_version` field on orders. These mechanisms complement each other:++| Mechanism | Prevents | Scope |+|-----------|----------|-------|+| **Idempotency keys** | Duplicate operations from retries | Per-request deduplication |+| **Optimistic locking** (`state_lock_version`) | Concurrent modifications | Conflict detection between clients |++Use both together for robust checkout flows: idempotency keys protect against network retries, while `state_lock_version` detects when another client has modified the order.diff --git a/docs/api-reference/store.yaml b/docs/api-reference/store.yamlindex a1e0cf7891..d0aef96c16 100644--- a/docs/api-reference/store.yaml+++ b/docs/api-reference/store.yaml@@ -647,14 +647,14 @@ paths:content:application/json:example:- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImU3NmVjMGNiLTQ4M2YtNGIxZS1hMzI4LWEyNmM3MjEzZDZmYSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzcyNjY5ODA1fQ.NdHVrcagM6ZhS6uZzyyBU3Qz1yyasS3OEjEY5epIlZA+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjRjODFkODk3LTcwZTMtNGZhMC04YTFmLWJjNzlhMzNiYTY5YiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzcyNzA5MTcxfQ.hnd1VlfoJu4G1DrIukQL1clrt9jbSmIcCjehNpZ_fuEuser:id: cus_UkLWZg9DAJemail: [email protected]- first_name: Gaylord- last_name: Abbott- created_at: '2026-03-04T23:16:45.224Z'- updated_at: '2026-03-04T23:16:45.224Z'+ first_name: Micheal+ last_name: Balistreri+ created_at: '2026-03-05T10:12:50.891Z'+ updated_at: '2026-03-05T10:12:50.891Z'addresses: []default_billing_address:default_shipping_address:@@ -727,14 +727,14 @@ paths:content:application/json:example:- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImIyY2MxZjBkLTM4ODEtNDhlYy05NWQwLTRjMWFiYThmNjdjNiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzcyNjY5ODA2fQ.TuNtaQsHENSyeVdaLBdxPikT5Efw_BfFSMNW_YSDhYU+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjAxZjZhYWZkLTYyYjYtNDdjZS05ZGVjLWY0NTViMTI3NDJkZCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzcyNzA5MTcyfQ.BDWAd0gWZi0deHpkyYfZqRyl86MdGJ1qJmhIK9bMxyEuser:id: cus_UkLWZg9DAJemail: [email protected]first_name: Johnlast_name: Doe- created_at: '2026-03-04T23:16:46.619Z'- updated_at: '2026-03-04T23:16:46.619Z'+ created_at: '2026-03-05T10:12:52.344Z'+ updated_at: '2026-03-05T10:12:52.344Z'addresses: []default_billing_address:default_shipping_address:@@ -820,14 +820,14 @@ paths:content:application/json:example:- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImJiNDNhYmEzLTQyZmEtNDBmMS1iOGY0LWM3ZDRlZGFjMDk2MCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzcyNjY5ODA3fQ.LDpIaRzMzrSuM5zPTyNkslNJLMQ6jqjQiYAgkE66RTw+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjFiMTJmYjk0LWZlYjUtNDMyMS1iOGNkLWIzNmJiNGRkNjBlMiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzcyNzA5MTcyfQ.AbD4LOwCN-Te2bPBUAHZYWi8q-6xlInBUycDW9EmyT4user:id: cus_UkLWZg9DAJemail: [email protected]- first_name: Senaida- last_name: Mayer- created_at: '2026-03-04T23:16:47.183Z'- updated_at: '2026-03-04T23:16:47.183Z'+ first_name: Monty+ last_name: Berge+ created_at: '2026-03-05T10:12:52.904Z'+ updated_at: '2026-03-05T10:12:52.904Z'addresses: []default_billing_address:default_shipping_address:@@ -877,6 +877,13 @@ paths:description: Bearer JWT token (optional - for authenticated customers)schema:type: string+ - name: Idempotency-Key+ in: header+ required: false+ description: Unique key for request idempotency. Duplicate requests with the+ same key return the cached response.+ schema:+ type: stringresponses:'201':description: cart created with metadata@@ -884,9 +891,9 @@ paths:application/json:example:id: or_UkLWZg9DAJ- number: R618951168+ number: R935471658state: cart- token: fluIp0nUEC2GAd3Cr6llyw1772666207799+ token: "-E3d_5Ejn1imZYqw-tENWw1772705573567"email:special_instructions:currency: USD@@ -912,8 +919,8 @@ paths:total: '0.0'display_total: "$0.00"completed_at:- created_at: '2026-03-04T23:16:47.800Z'- updated_at: '2026-03-04T23:16:47.800Z'+ created_at: '2026-03-05T10:12:53.568Z'+ updated_at: '2026-03-05T10:12:53.568Z'order_promotions: []line_items: []shipments: []@@ -933,6 +940,27 @@ paths:message: Valid API key requiredschema:"$ref": "#/components/schemas/ErrorResponse"+ '400':+ description: idempotency key too long+ content:+ application/json:+ example:+ error:+ code: invalid_request+ message: Idempotency-Key must be 255 characters or less.+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ '422':+ description: idempotency key reused with different parameters+ content:+ application/json:+ example:+ error:+ code: idempotency_key_reused+ message: This Idempotency-Key has already been used with different+ request parameters.+ schema:+ "$ref": "#/components/schemas/ErrorResponse"requestBody:content:application/json:@@ -998,10 +1026,10 @@ paths:application/json:example:id: or_UkLWZg9DAJ- number: R590937094+ number: R625333279state: cart- token: WpkLzDbMQcxAVEeCjBM34rDPAfPCsfkBbD7- email: [email protected]+ token: vWWRUi67ycMc38uJn9HcHjYViCHZPPL1qRb+ email: [email protected]special_instructions:currency: USDlocale: en@@ -1026,16 +1054,16 @@ paths:total: '110.0'display_total: "$110.00"completed_at:- created_at: '2026-03-04T23:16:48.792Z'- updated_at: '2026-03-04T23:16:48.846Z'+ created_at: '2026-03-05T10:12:54.647Z'+ updated_at: '2026-03-05T10:12:54.720Z'order_promotions: []line_items:- id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 26054- slug: product-26054+ name: Product 23466+ slug: product-23466options_text: ''price: '10.0'display_price: "$10.00"@@ -1054,23 +1082,23 @@ paths:discounted_amount: '10.0'display_discounted_amount: "$10.00"display_compare_at_amount: "$0.00"- created_at: '2026-03-04T23:16:48.826Z'- updated_at: '2026-03-04T23:16:48.826Z'+ created_at: '2026-03-05T10:12:54.690Z'+ updated_at: '2026-03-05T10:12:54.690Z'compare_at_amount:thumbnail_url:option_values: []digital_links: []shipments:- id: ship_UkLWZg9DAJ- number: H56313951793+ number: H16887874614state: pendingtracking: U10000tracking_url:cost: '100.0'display_cost: "$100.00"shipped_at:- created_at: '2026-03-04T23:16:48.831Z'- updated_at: '2026-03-04T23:16:48.844Z'+ created_at: '2026-03-05T10:12:54.696Z'+ updated_at: '2026-03-05T10:12:54.717Z'shipping_method:id: shpm_UkLWZg9DAJname: UPS Ground@@ -1078,7 +1106,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: STATE_ABBR_41- name: Rolanda Runolfsson+ name: Lesha Considineaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -1196,10 +1224,10 @@ paths:application/json:example:id: or_UkLWZg9DAJ- number: R774964510+ number: R767761099state: cart- token: ZUHqTCvwRsnTgU9fNd1VKApe12yKsPJ51is- email: [email protected]+ token: JNzv8nEcTLnNMvhB9SnraBJSpoMHg9SKS5E+ email: [email protected]special_instructions:currency: USDlocale: en@@ -1224,16 +1252,16 @@ paths:total: '110.0'display_total: "$110.00"completed_at:- created_at: '2026-03-04T23:16:49.436Z'- updated_at: '2026-03-04T23:16:49.491Z'+ created_at: '2026-03-05T10:12:55.302Z'+ updated_at: '2026-03-05T10:12:55.361Z'order_promotions: []line_items:- id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 31102- slug: product-31102+ name: Product 35507+ slug: product-35507options_text: ''price: '10.0'display_price: "$10.00"@@ -1252,23 +1280,23 @@ paths:discounted_amount: '10.0'display_discounted_amount: "$10.00"display_compare_at_amount: "$0.00"- created_at: '2026-03-04T23:16:49.468Z'- updated_at: '2026-03-04T23:16:49.468Z'+ created_at: '2026-03-05T10:12:55.337Z'+ updated_at: '2026-03-05T10:12:55.337Z'compare_at_amount:thumbnail_url:option_values: []digital_links: []shipments:- id: ship_UkLWZg9DAJ- number: H86414876171+ number: H44992416560state: pendingtracking: U10000tracking_url:cost: '100.0'display_cost: "$100.00"shipped_at:- created_at: '2026-03-04T23:16:49.474Z'- updated_at: '2026-03-04T23:16:49.489Z'+ created_at: '2026-03-05T10:12:55.342Z'+ updated_at: '2026-03-05T10:12:55.359Z'shipping_method:id: shpm_UkLWZg9DAJname: UPS Ground@@ -1276,7 +1304,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: STATE_ABBR_45- name: Tammie Vandervort+ name: Karma VonRuedenaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -1537,6 +1565,13 @@ paths:description: Order token for guest accessschema:type: string+ - name: Idempotency-Key+ in: header+ required: false+ description: Unique key for request idempotency. Duplicate requests with the+ same key return the cached response.+ schema:+ type: stringresponses:'201':description: coupon code applied (gift card)@@ -1544,10 +1579,10 @@ paths:application/json:example:id: or_UkLWZg9DAJ- number: R101959622+ number: R795624609state: cart- token: MutBdVXkYHt6C9cy2SXL2xpriusqJjw1D6u- email: [email protected]+ token: xztU4oAb2fgekg7W4edpWu8XtDqSEJNxeLm+ email: [email protected]special_instructions:currency: USDlocale: en@@ -1572,16 +1607,16 @@ paths:total: '110.0'display_total: "$110.00"completed_at:- created_at: '2026-03-04T23:16:53.131Z'- updated_at: '2026-03-04T23:16:53.234Z'+ created_at: '2026-03-05T10:12:59.254Z'+ updated_at: '2026-03-05T10:12:59.391Z'order_promotions: []line_items:- id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 8571- slug: product-8571+ name: Product 86861+ slug: product-86861options_text: ''price: '10.0'display_price: "$10.00"@@ -1600,23 +1635,23 @@ paths:discounted_amount: '10.0'display_discounted_amount: "$10.00"display_compare_at_amount: "$0.00"- created_at: '2026-03-04T23:16:53.158Z'- updated_at: '2026-03-04T23:16:53.158Z'+ created_at: '2026-03-05T10:12:59.293Z'+ updated_at: '2026-03-05T10:12:59.293Z'compare_at_amount:thumbnail_url:option_values: []digital_links: []shipments:- id: ship_UkLWZg9DAJ- number: H21319787495+ number: H76099278715state: pendingtracking: U10000tracking_url:cost: '100.0'display_cost: "$100.00"shipped_at:- created_at: '2026-03-04T23:16:53.163Z'- updated_at: '2026-03-04T23:16:53.175Z'+ created_at: '2026-03-05T10:12:59.301Z'+ updated_at: '2026-03-05T10:12:59.319Z'shipping_method:id: shpm_UkLWZg9DAJname: UPS Ground@@ -1624,7 +1659,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: STATE_ABBR_65- name: Alexa Sanford+ name: Geoffrey Streichaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -1646,12 +1681,12 @@ paths:- id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJstate: checkout- response_code: 1-SC-20260304231653225324- number: PPADTIK2+ response_code: 1-SC-20260305101259379006+ number: PCWLUSFQamount: '50.0'display_amount: "$50.00"- created_at: '2026-03-04T23:16:53.229Z'- updated_at: '2026-03-04T23:16:53.229Z'+ created_at: '2026-03-05T10:12:59.384Z'+ updated_at: '2026-03-05T10:12:59.384Z'source_type: store_creditsource_id: credit_UkLWZg9DAJsource:@@ -1803,10 +1838,10 @@ paths:application/json:example:id: or_UkLWZg9DAJ- number: R412628999+ number: R279710927state: cart- token: Au5hNbyeNmsWawGWuZU3ZyXQFo81by52ft2- email: [email protected]+ token: rNhi5SnCA41uVJftQRdgB59whL18tfcXCPN+ email: [email protected]special_instructions:currency: USDlocale: en@@ -1831,16 +1866,16 @@ paths:total: '110.0'display_total: "$110.00"completed_at:- created_at: '2026-03-04T23:16:55.039Z'- updated_at: '2026-03-04T23:16:55.140Z'+ created_at: '2026-03-05T10:13:01.223Z'+ updated_at: '2026-03-05T10:13:01.362Z'order_promotions: []line_items:- id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 116112- slug: product-116112+ name: Product 118355+ slug: product-118355options_text: ''price: '10.0'display_price: "$10.00"@@ -1859,23 +1894,23 @@ paths:discounted_amount: '10.0'display_discounted_amount: "$10.00"display_compare_at_amount: "$0.00"- created_at: '2026-03-04T23:16:55.066Z'- updated_at: '2026-03-04T23:16:55.134Z'+ created_at: '2026-03-05T10:13:01.260Z'+ updated_at: '2026-03-05T10:13:01.356Z'compare_at_amount:thumbnail_url:option_values: []digital_links: []shipments:- id: ship_UkLWZg9DAJ- number: H06232049435+ number: H23651198973state: pendingtracking: U10000tracking_url:cost: '100.0'display_cost: "$100.00"shipped_at:- created_at: '2026-03-04T23:16:55.071Z'- updated_at: '2026-03-04T23:16:55.083Z'+ created_at: '2026-03-05T10:13:01.266Z'+ updated_at: '2026-03-05T10:13:01.282Z'shipping_method:id: shpm_UkLWZg9DAJname: UPS Ground@@ -1883,7 +1918,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: STATE_ABBR_77- name: Vannesa Hermann+ name: Jami Rauaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -2278,10 +2313,10 @@ paths:example:data:- id: or_UkLWZg9DAJ- number: R740767011+ number: R651940569state: cart- token: da7NyignsWUhLWwRHAP6U3ET5rNSSsoZ5Ay- email: [email protected]+ token: PzwGmqwa4ARByDTDVmug7B5Gw7LscyWY9cs+ email: [email protected]special_instructions:currency: USDlocale: en@@ -2306,16 +2341,16 @@ paths:total: '110.0'display_total: "$110.00"completed_at:- created_at: '2026-03-04T23:16:59.684Z'- updated_at: '2026-03-04T23:16:59.765Z'+ created_at: '2026-03-05T10:13:06.071Z'+ updated_at: '2026-03-05T10:13:06.141Z'order_promotions: []line_items:- id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 131061- slug: product-131061+ name: Product 135089+ slug: product-135089options_text: ''price: '10.0'display_price: "$10.00"@@ -2334,23 +2369,23 @@ paths:discounted_amount: '10.0'display_discounted_amount: "$10.00"display_compare_at_amount: "$0.00"- created_at: '2026-03-04T23:16:59.724Z'- updated_at: '2026-03-04T23:16:59.724Z'+ created_at: '2026-03-05T10:13:06.115Z'+ updated_at: '2026-03-05T10:13:06.115Z'compare_at_amount:thumbnail_url:option_values: []digital_links: []shipments:- id: ship_UkLWZg9DAJ- number: H85878272412+ number: H52521760738state: pendingtracking: U10000tracking_url:cost: '100.0'display_cost: "$100.00"shipped_at:- created_at: '2026-03-04T23:16:59.735Z'- updated_at: '2026-03-04T23:16:59.758Z'+ created_at: '2026-03-05T10:13:06.122Z'+ updated_at: '2026-03-05T10:13:06.139Z'shipping_method:id: shpm_UkLWZg9DAJname: UPS Ground@@ -2358,7 +2393,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: STATE_ABBR_100- name: Ofelia Braun+ name: Annamarie Muelleraddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -2483,11 +2518,11 @@ paths:application/json:example:id: cus_UkLWZg9DAJ- email: [email protected]- first_name: Yessenia- last_name: Kuhic- created_at: '2026-03-04T23:17:00.712Z'- updated_at: '2026-03-04T23:17:00.984Z'+ email: [email protected]+ first_name: Milan+ last_name: Beatty+ created_at: '2026-03-05T10:13:07.129Z'+ updated_at: '2026-03-05T10:13:07.402Z'addresses:- id: addr_gbHJdmfrXBfirstname: John@@ -2610,11 +2645,11 @@ paths:application/json:example:id: cus_UkLWZg9DAJ- email: [email protected]+ email: [email protected]first_name: Updatedlast_name: Name- created_at: '2026-03-04T23:17:01.275Z'- updated_at: '2026-03-04T23:17:01.554Z'+ created_at: '2026-03-05T10:13:07.701Z'+ updated_at: '2026-03-05T10:13:07.989Z'addresses:- id: addr_gbHJdmfrXBfirstname: John@@ -2827,7 +2862,7 @@ paths:example:data:- id: gc_UkLWZg9DAJ- code: 57F9EFA15BCD6500+ code: 49C37BFEB54BA9AEstate: activecurrency: USDamount: '10.0'@@ -2841,8 +2876,8 @@ paths:redeemed_at:expired: falseactive: true- created_at: '2026-03-04T23:17:04.681Z'- updated_at: '2026-03-04T23:17:04.681Z'+ created_at: '2026-03-05T10:13:11.189Z'+ updated_at: '2026-03-05T10:13:11.189Z'meta:page: 1limit: 25@@ -2918,7 +2953,7 @@ paths:application/json:example:id: gc_UkLWZg9DAJ- code: D064082470A0FA61+ code: E1A8520D65465E70state: activecurrency: USDamount: '10.0'@@ -2932,8 +2967,8 @@ paths:redeemed_at:expired: falseactive: true- created_at: '2026-03-04T23:17:05.764Z'- updated_at: '2026-03-04T23:17:05.764Z'+ created_at: '2026-03-05T10:13:12.319Z'+ updated_at: '2026-03-05T10:13:12.319Z'schema:"$ref": "#/components/schemas/StoreGiftCard"'404':@@ -2997,6 +3032,13 @@ paths:description: Order token for guest accessschema:type: string+ - name: Idempotency-Key+ in: header+ required: false+ description: Unique key for request idempotency. Duplicate requests with the+ same key return the cached response.+ schema:+ type: stringresponses:'201':description: item added with metadata@@ -3004,10 +3046,10 @@ paths:application/json:example:id: or_UkLWZg9DAJ- number: R053110153+ number: R504722406state: cart- token: yBLLGDVeXLP8sjC2249DNRDPoFHNq2KhNrd- email: [email protected]+ token: QSj7Zxy1tQHMsEGp3qjDqqxmrFPL1eELjZk+ email: [email protected]special_instructions:currency: USDlocale: en@@ -3032,16 +3074,16 @@ paths:total: '29.99'display_total: "$29.99"completed_at:- created_at: '2026-03-04T23:17:07.527Z'- updated_at: '2026-03-04T23:17:07.640Z'+ created_at: '2026-03-05T10:13:14.118Z'+ updated_at: '2026-03-05T10:13:14.248Z'order_promotions: []line_items:- id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 235530- slug: product-235530+ name: Product 235990+ slug: product-235990options_text: ''price: '10.0'display_price: "$10.00"@@ -3060,8 +3102,8 @@ paths:discounted_amount: '10.0'display_discounted_amount: "$10.00"display_compare_at_amount: "$0.00"- created_at: '2026-03-04T23:17:07.569Z'- updated_at: '2026-03-04T23:17:07.569Z'+ created_at: '2026-03-05T10:13:14.152Z'+ updated_at: '2026-03-05T10:13:14.152Z'compare_at_amount:thumbnail_url:option_values: []@@ -3070,8 +3112,8 @@ paths:variant_id: variant_gbHJdmfrXBquantity: 1currency: USD- name: Product 248937- slug: product-248937+ name: Product 24677+ slug: product-24677options_text: ''price: '19.99'display_price: "$19.99"@@ -3090,8 +3132,8 @@ paths:discounted_amount: '19.99'display_discounted_amount: "$19.99"display_compare_at_amount: "$0.00"- created_at: '2026-03-04T23:17:07.617Z'- updated_at: '2026-03-04T23:17:07.617Z'+ created_at: '2026-03-05T10:13:14.216Z'+ updated_at: '2026-03-05T10:13:14.216Z'compare_at_amount:thumbnail_url:option_values: []@@ -3211,10 +3253,10 @@ paths:application/json:example:id: or_UkLWZg9DAJ- number: R270823023+ number: R289193947state: cart- token: 3KZoEEDyhipemxt3Mu751SiPyPXt2BCZUUe- email: [email protected]+ token: znvNeiyfM5khVnD7pwkM8Q5BvJkVNfW8FC9+ email: [email protected]special_instructions:currency: USDlocale: en@@ -3239,16 +3281,16 @@ paths:total: '0.0'display_total: "$0.00"completed_at:- created_at: '2026-03-04T23:17:09.982Z'- updated_at: '2026-03-04T23:17:10.011Z'+ created_at: '2026-03-05T10:13:16.651Z'+ updated_at: '2026-03-05T10:13:16.690Z'order_promotions: []line_items:- id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 287514- slug: product-287514+ name: Product 283574+ slug: product-283574options_text: ''price: '10.0'display_price: "$10.00"@@ -3267,8 +3309,8 @@ paths:discounted_amount: '10.0'display_discounted_amount: "$10.00"display_compare_at_amount: "$0.00"- created_at: '2026-03-04T23:17:10.010Z'- updated_at: '2026-03-04T23:17:10.025Z'+ created_at: '2026-03-05T10:13:16.690Z'+ updated_at: '2026-03-05T10:13:16.710Z'compare_at_amount:thumbnail_url:option_values: []@@ -3367,10 +3409,10 @@ paths:application/json:example:id: or_UkLWZg9DAJ- number: R504751218+ number: R225243737state: cart- token: 2eTdasGo2WpwwcZhp1jizTJGfJqrdvnQeDr- email: [email protected]+ token: y8HRqKBaF1yhrSWd2mSbTnuyNcaP5aNhC2P+ email: [email protected]special_instructions:currency: USDlocale: en@@ -3395,8 +3437,8 @@ paths:total: '0.0'display_total: "$0.00"completed_at:- created_at: '2026-03-04T23:17:10.566Z'- updated_at: '2026-03-04T23:17:10.638Z'+ created_at: '2026-03-05T10:13:17.302Z'+ updated_at: '2026-03-05T10:13:17.366Z'order_promotions: []line_items: []shipments: []@@ -3901,9 +3943,9 @@ paths:application/json:example:id: or_gbHJdmfrXB- number: R264789212+ number: R146344806state: cart- token: rQJarx6iw673mZP6CFJLLjdMokuMxw6b3eU+ token: xarJrfj83gLuxSHx9j9xRT8ZrEtKxvyWKBhemail:special_instructions:currency: USD@@ -3929,16 +3971,16 @@ paths:total: '110.0'display_total: "$110.00"completed_at:- created_at: '2026-03-04T23:17:12.966Z'- updated_at: '2026-03-04T23:17:13.024Z'+ created_at: '2026-03-05T10:13:19.759Z'+ updated_at: '2026-03-05T10:13:19.831Z'order_promotions: []line_items:- id: li_gbHJdmfrXBvariant_id: variant_gbHJdmfrXBquantity: 1currency: USD- name: Product 335231- slug: product-335231+ name: Product 338954+ slug: product-338954options_text: ''price: '10.0'display_price: "$10.00"@@ -3957,23 +3999,23 @@ paths:discounted_amount: '10.0'display_discounted_amount: "$10.00"display_compare_at_amount: "$0.00"- created_at: '2026-03-04T23:17:12.995Z'- updated_at: '2026-03-04T23:17:12.995Z'+ created_at: '2026-03-05T10:13:19.789Z'+ updated_at: '2026-03-05T10:13:19.789Z'compare_at_amount:thumbnail_url:option_values: []digital_links: []shipments:- id: ship_gbHJdmfrXB- number: H22053469571+ number: H26748896837state: pendingtracking: U10000tracking_url:cost: '100.0'display_cost: "$100.00"shipped_at:- created_at: '2026-03-04T23:17:13.007Z'- updated_at: '2026-03-04T23:17:13.021Z'+ created_at: '2026-03-05T10:13:19.802Z'+ updated_at: '2026-03-05T10:13:19.819Z'shipping_method:id: shpm_gbHJdmfrXBname: UPS Ground@@ -3981,7 +4023,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: STATE_ABBR_159- name: Jay O'Hara+ name: Kelly Douglasaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -4102,6 +4144,13 @@ paths:required: falseschema:type: string+ - name: Idempotency-Key+ in: header+ required: false+ description: Unique key for request idempotency. Duplicate requests with the+ same key return the cached response.+ schema:+ type: stringresponses:'200':description: order updated with metadata@@ -4109,10 +4158,10 @@ paths:application/json:example:id: or_UkLWZg9DAJ- number: R229942880+ number: R155308648state: cart- token: z1dfmjcrKrQVFu2cAx7hUwmBMhmMGBkRdd4- email: [email protected]+ token: RUAgF9xa1MCZDMfwiDLHfQjYFek3cqq9rAL+ email: [email protected]special_instructions:currency: USDlocale: en@@ -4137,16 +4186,16 @@ paths:total: '110.0'display_total: "$110.00"completed_at:- created_at: '2026-03-04T23:17:15.684Z'- updated_at: '2026-03-04T23:17:15.756Z'+ created_at: '2026-03-05T10:13:22.610Z'+ updated_at: '2026-03-05T10:13:22.695Z'order_promotions: []line_items:- id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 371247- slug: product-371247+ name: Product 375684+ slug: product-375684options_text: ''price: '10.0'display_price: "$10.00"@@ -4165,23 +4214,23 @@ paths:discounted_amount: '10.0'display_discounted_amount: "$10.00"display_compare_at_amount: "$0.00"- created_at: '2026-03-04T23:17:15.717Z'- updated_at: '2026-03-04T23:17:15.717Z'+ created_at: '2026-03-05T10:13:22.647Z'+ updated_at: '2026-03-05T10:13:22.647Z'compare_at_amount:thumbnail_url:option_values: []digital_links: []shipments:- id: ship_UkLWZg9DAJ- number: H32380232811+ number: H63840183543state: pendingtracking: U10000tracking_url:cost: '100.0'display_cost: "$100.00"shipped_at:- created_at: '2026-03-04T23:17:15.722Z'- updated_at: '2026-03-04T23:17:15.737Z'+ created_at: '2026-03-05T10:13:22.653Z'+ updated_at: '2026-03-05T10:13:22.670Z'shipping_method:id: shpm_UkLWZg9DAJname: UPS Ground@@ -4189,7 +4238,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: STATE_ABBR_178- name: Emelina Senger+ name: Donnie Powlowskiaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -4386,6 +4435,13 @@ paths:required: falseschema:type: string+ - name: Idempotency-Key+ in: header+ required: false+ description: Unique key for request idempotency. Duplicate requests with the+ same key return the cached response.+ schema:+ type: stringresponses:'200':description: order advanced@@ -4393,10 +4449,10 @@ paths:application/json:example:id: or_gbHJdmfrXB- number: R701650727+ number: R471304745state: address- token: j5LZERrRpKUPoaoedscbbycbMgYYVwxuLBL- email: [email protected]+ token: WeB52fhwS8oT3HpbCASPnq6BVDd7fY4Tb9E+ email: [email protected]special_instructions:currency: USDlocale: en@@ -4421,16 +4477,16 @@ paths:total: '110.0'display_total: "$110.00"completed_at:- created_at: '2026-03-04T23:17:17.082Z'- updated_at: '2026-03-04T23:17:17.143Z'+ created_at: '2026-03-05T10:13:24.039Z'+ updated_at: '2026-03-05T10:13:24.112Z'order_promotions: []line_items:- id: li_gbHJdmfrXBvariant_id: variant_gbHJdmfrXBquantity: 1currency: USD- name: Product 415109- slug: product-415109+ name: Product 418691+ slug: product-418691options_text: ''price: '10.0'display_price: "$10.00"@@ -4449,23 +4505,23 @@ paths:discounted_amount: '10.0'display_discounted_amount: "$10.00"display_compare_at_amount: "$0.00"- created_at: '2026-03-04T23:17:17.108Z'- updated_at: '2026-03-04T23:17:17.108Z'+ created_at: '2026-03-05T10:13:24.071Z'+ updated_at: '2026-03-05T10:13:24.071Z'compare_at_amount:thumbnail_url:option_values: []digital_links: []shipments:- id: ship_gbHJdmfrXB- number: H51478134192+ number: H85576470441state: pendingtracking: U10000tracking_url:cost: '100.0'display_cost: "$100.00"shipped_at:- created_at: '2026-03-04T23:17:17.114Z'- updated_at: '2026-03-04T23:17:17.124Z'+ created_at: '2026-03-05T10:13:24.078Z'+ updated_at: '2026-03-05T10:13:24.090Z'shipping_method:id: shpm_gbHJdmfrXBname: UPS Ground@@ -4473,7 +4529,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: STATE_ABBR_188- name: Johnathon Smitham+ name: Grayce Greenaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -4584,6 +4640,13 @@ paths:required: falseschema:type: string+ - name: Idempotency-Key+ in: header+ required: false+ description: Unique key for request idempotency. Duplicate requests with the+ same key return the cached response.+ schema:+ type: stringresponses:'200':description: order advanced@@ -4591,10 +4654,10 @@ paths:application/json:example:id: or_gbHJdmfrXB- number: R552471231+ number: R208602275state: payment- token: eF7y7w9Afz6fSGZ1DVYbjxBtE7XAeV4ZqEg- email: [email protected]+ token: NZRpJcNx44om5oCpjk76gse5mB6AMUrqKm4+ email: [email protected]special_instructions:currency: USDlocale: en@@ -4619,16 +4682,16 @@ paths:total: '29.99'display_total: "$29.99"completed_at:- created_at: '2026-03-04T23:17:18.376Z'- updated_at: '2026-03-04T23:17:18.530Z'+ created_at: '2026-03-05T10:13:25.493Z'+ updated_at: '2026-03-05T10:13:25.652Z'order_promotions: []line_items:- id: li_gbHJdmfrXBvariant_id: variant_gbHJdmfrXBquantity: 1currency: USD- name: Product 444613- slug: product-444613+ name: Product 442561+ slug: product-442561options_text: ''price: '19.99'display_price: "$19.99"@@ -4647,23 +4710,23 @@ paths:discounted_amount: '19.99'display_discounted_amount: "$19.99"display_compare_at_amount: "$0.00"- created_at: '2026-03-04T23:17:18.406Z'- updated_at: '2026-03-04T23:17:18.471Z'+ created_at: '2026-03-05T10:13:25.523Z'+ updated_at: '2026-03-05T10:13:25.588Z'compare_at_amount:thumbnail_url:option_values: []digital_links: []shipments:- id: ship_EfhxLZ9ck8- number: H24101681822+ number: H12198036611state: pendingtracking:tracking_url:cost: '10.0'display_cost: "$10.00"shipped_at:- created_at: '2026-03-04T23:17:18.489Z'- updated_at: '2026-03-04T23:17:18.502Z'+ created_at: '2026-03-05T10:13:25.608Z'+ updated_at: '2026-03-05T10:13:25.623Z'shipping_method:id: shpm_UkLWZg9DAJname: UPS Ground@@ -4671,7 +4734,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: STATE_ABBR_198- name: Leta Schinner+ name: Sudie Kassulkeaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -4781,6 +4844,13 @@ paths:required: falseschema:type: string+ - name: Idempotency-Key+ in: header+ required: false+ description: Unique key for request idempotency. Duplicate requests with the+ same key return the cached response.+ schema:+ type: stringresponses:'200':description: order completed@@ -4788,10 +4858,10 @@ paths:application/json:example:id: or_gbHJdmfrXB- number: R534375768+ number: R220845492state: complete- token: 17ZExg7cPhvUxv2ou4utEPT7Em6GFREvvAW- email: [email protected]+ token: mkDSifyLJoXLS2BpW3TzPUdBXJXkE3mQDah+ email: [email protected]special_instructions:currency: USDlocale: en@@ -4815,17 +4885,17 @@ paths:display_additional_tax_total: "$0.00"total: '29.99'display_total: "$29.99"- completed_at: '2026-03-04T23:17:19.409Z'- created_at: '2026-03-04T23:17:19.151Z'- updated_at: '2026-03-04T23:17:19.409Z'+ completed_at: '2026-03-05T10:13:26.521Z'+ created_at: '2026-03-05T10:13:26.299Z'+ updated_at: '2026-03-05T10:13:26.521Z'order_promotions: []line_items:- id: li_gbHJdmfrXBvariant_id: variant_gbHJdmfrXBquantity: 1currency: USD- name: Product 467244- slug: product-467244+ name: Product 466061+ slug: product-466061options_text: ''price: '19.99'display_price: "$19.99"@@ -4844,23 +4914,23 @@ paths:discounted_amount: '19.99'display_discounted_amount: "$19.99"display_compare_at_amount: "$0.00"- created_at: '2026-03-04T23:17:19.195Z'- updated_at: '2026-03-04T23:17:19.273Z'+ created_at: '2026-03-05T10:13:26.336Z'+ updated_at: '2026-03-05T10:13:26.393Z'compare_at_amount:thumbnail_url:option_values: []digital_links: []shipments:- id: ship_EfhxLZ9ck8- number: H49476442238+ number: H39163777758state: pendingtracking:tracking_url:cost: '10.0'display_cost: "$10.00"shipped_at:- created_at: '2026-03-04T23:17:19.305Z'- updated_at: '2026-03-04T23:17:19.399Z'+ created_at: '2026-03-05T10:13:26.414Z'+ updated_at: '2026-03-05T10:13:26.510Z'shipping_method:id: shpm_UkLWZg9DAJname: UPS Ground@@ -4868,7 +4938,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: STATE_ABBR_204- name: Alona Abshire+ name: Booker Wymanaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -4901,11 +4971,11 @@ paths:payment_method_id: pm_UkLWZg9DAJstate: checkoutresponse_code: '12345'- number: PJQC7TSE+ number: PNHXIEFNamount: '29.99'display_amount: "$29.99"- created_at: '2026-03-04T23:17:19.371Z'- updated_at: '2026-03-04T23:17:19.371Z'+ created_at: '2026-03-05T10:13:26.477Z'+ updated_at: '2026-03-05T10:13:26.477Z'source_type: credit_cardsource_id: card_UkLWZg9DAJsource:@@ -5122,6 +5192,13 @@ paths:description: Order token for guest accessschema:type: string+ - name: Idempotency-Key+ in: header+ required: false+ description: Unique key for request idempotency. Duplicate requests with the+ same key return the cached response.+ schema:+ type: stringresponses:'201':description: payment session created@@ -5131,13 +5208,13 @@ paths:id: ps_gbHJdmfrXBstatus: pendingcurrency: USD- external_id: bogus_259304fc47a0d54c9749cec9+ external_id: bogus_805547682e999cd75581a08dexternal_data:- client_secret: bogus_secret_0d716c78904a6840+ client_secret: bogus_secret_0b63b5be432cd47bcustomer_external_id:expires_at:- created_at: '2026-03-04T23:17:21.852Z'- updated_at: '2026-03-04T23:17:21.852Z'+ created_at: '2026-03-05T10:13:29.167Z'+ updated_at: '2026-03-05T10:13:29.167Z'amount: '110.0'payment_method_id: pm_UkLWZg9DAJorder_id: or_UkLWZg9DAJ@@ -5242,13 +5319,13 @@ paths:id: ps_UkLWZg9DAJstatus: pendingcurrency: USD- external_id: bogus_2710f63f83a12c61889acc1e+ external_id: bogus_65e274969537e434465195c4external_data:client_secret: secret_123customer_external_id:expires_at:- created_at: '2026-03-04T23:17:23.077Z'- updated_at: '2026-03-04T23:17:23.077Z'+ created_at: '2026-03-05T10:13:30.421Z'+ updated_at: '2026-03-05T10:13:30.421Z'amount: '110.0'payment_method_id: pm_UkLWZg9DAJorder_id: or_UkLWZg9DAJ@@ -5305,13 +5382,13 @@ paths:id: ps_UkLWZg9DAJstatus: pendingcurrency: USD- external_id: bogus_7c8aca13719f1243a7d1d86a+ external_id: bogus_5b8b6b69b676b612c3cecdfeexternal_data:client_secret: secret_123customer_external_id:expires_at:- created_at: '2026-03-04T23:17:24.286Z'- updated_at: '2026-03-04T23:17:24.299Z'+ created_at: '2026-03-05T10:13:31.697Z'+ updated_at: '2026-03-05T10:13:31.713Z'amount: '50.0'payment_method_id: pm_UkLWZg9DAJorder_id: or_UkLWZg9DAJ@@ -5392,7 +5469,14 @@ paths:}, {bearerToken: '<token>',})- parameters: []+ parameters:+ - name: Idempotency-Key+ in: header+ required: false+ description: Unique key for request idempotency. Duplicate requests with the+ same key return the cached response.+ schema:+ type: stringresponses:'200':description: payment session completed@@ -5402,13 +5486,13 @@ paths:id: ps_UkLWZg9DAJstatus: completedcurrency: USD- external_id: bogus_abf5f34c64cdd4896f300894+ external_id: bogus_502f06a49c907d6bbc0dcf73external_data:client_secret: secret_123customer_external_id:expires_at:- created_at: '2026-03-04T23:17:24.901Z'- updated_at: '2026-03-04T23:17:24.914Z'+ created_at: '2026-03-05T10:13:32.348Z'+ updated_at: '2026-03-05T10:13:32.362Z'amount: '110.0'payment_method_id: pm_UkLWZg9DAJorder_id: or_UkLWZg9DAJ@@ -5488,11 +5572,11 @@ paths:example:id: pss_gbHJdmfrXBstatus: pending- external_id: bogus_seti_9ccae6ad6e70f20ff2b324e8- external_client_secret: bogus_seti_secret_d40edb7011910397+ external_id: bogus_seti_29be88e7f2812d817d489dfc+ external_client_secret: bogus_seti_secret_e8844b83ad99db1cexternal_data: {}- created_at: '2026-03-04T23:17:26.115Z'- updated_at: '2026-03-04T23:17:26.115Z'+ created_at: '2026-03-05T10:13:33.634Z'+ updated_at: '2026-03-05T10:13:33.634Z'payment_method_id: pm_UkLWZg9DAJpayment_source_id:payment_source_type:@@ -5589,12 +5673,12 @@ paths:example:id: pss_UkLWZg9DAJstatus: pending- external_id: seti_test_e4289b0f3a7de263c51596db- external_client_secret: seti_secret_c96a310dcd14443997b80df2+ external_id: seti_test_076fc26387e6652e157da4ac+ external_client_secret: seti_secret_e1324736e83e1a4b95e713b0external_data:client_secret: secret_123- created_at: '2026-03-04T23:17:27.753Z'- updated_at: '2026-03-04T23:17:27.753Z'+ created_at: '2026-03-05T10:13:35.326Z'+ updated_at: '2026-03-05T10:13:35.326Z'payment_method_id: pm_UkLWZg9DAJpayment_source_id:payment_source_type:@@ -5667,12 +5751,12 @@ paths:example:id: pss_UkLWZg9DAJstatus: completed- external_id: seti_test_66269e5af60aa07090e3a76a- external_client_secret: seti_secret_00facd29ab65ba8453e276ba+ external_id: seti_test_7fba894ce8b3e222e32f3b41+ external_client_secret: seti_secret_6ec0a4115026e56c3286af57external_data:client_secret: secret_123- created_at: '2026-03-04T23:17:28.853Z'- updated_at: '2026-03-04T23:17:28.867Z'+ created_at: '2026-03-05T10:13:36.443Z'+ updated_at: '2026-03-05T10:13:36.459Z'payment_method_id: pm_UkLWZg9DAJpayment_source_id: card_UkLWZg9DAJpayment_source_type: Spree::CreditCard@@ -5755,11 +5839,11 @@ paths:payment_method_id: pm_UkLWZg9DAJstate: checkoutresponse_code: '12345'- number: P2R03K9T+ number: PEU8IPGPamount: '110.0'display_amount: "$110.00"- created_at: '2026-03-04T23:17:30.096Z'- updated_at: '2026-03-04T23:17:30.096Z'+ created_at: '2026-03-05T10:13:37.707Z'+ updated_at: '2026-03-05T10:13:37.707Z'source_type: credit_cardsource_id: card_UkLWZg9DAJsource:@@ -5853,11 +5937,11 @@ paths:payment_method_id: pm_UkLWZg9DAJstate: checkoutresponse_code: '12345'- number: PY9M5M6J+ number: PLS89YIAamount: '110.0'display_amount: "$110.00"- created_at: '2026-03-04T23:17:31.347Z'- updated_at: '2026-03-04T23:17:31.347Z'+ created_at: '2026-03-05T10:13:39.019Z'+ updated_at: '2026-03-05T10:13:39.019Z'source_type: credit_cardsource_id: card_UkLWZg9DAJsource:@@ -5994,18 +6078,20 @@ paths:example:data:- id: prod_UkLWZg9DAJ- name: Product 635842+ name: Product 63183description: |-- Corporis explicabo animi repellat natus at rerum quod dolorum. Ratione accusantium recusandae quo quam soluta. Molestias fugit vitae vero asperiores cum.- Unde molestias consectetur sapiente aut nihil dolorem. Debitis hic consequuntur velit ipsum itaque unde asperiores numquam. Unde totam eaque placeat aut pariatur quis distinctio. Sunt nulla eaque laborum nobis reprehenderit omnis consectetur nihil. Aperiam maxime nostrum non fuga.- Corrupti non quod quos odio maiores pariatur. Maiores magnam maxime cupiditate dolor asperiores. Corrupti quaerat velit fugit libero necessitatibus. Quibusdam quae saepe sequi praesentium.- slug: product-635842+ Consequatur officiis magnam sequi beatae velit esse. Molestiae similique repellat incidunt alias consequuntur assumenda illum dolore. Dolorum in facere laudantium accusamus cupiditate placeat saepe recusandae.+ Iste quidem eveniet facilis temporibus optio illum libero modi. Voluptatibus odit nemo temporibus dolorum quod facilis veritatis. Sunt ea nostrum repellat culpa quos molestias dolores quasi. Numquam veritatis laboriosam earum nostrum voluptatibus non incidunt.+ Earum deleniti tenetur consectetur neque consequatur doloribus distinctio. Doloribus atque quae eveniet enim quod. Pariatur nulla veritatis quasi debitis laborum totam et. Iste delectus provident consectetur veritatis minus facere rerum asperiores. Aperiam minus molestiae voluptate ullam voluptates perferendis reiciendis nihil.+ Iure aliquid mollitia itaque optio facere temporibus. Repellat dolorem fugit ab veritatis id quibusdam. Dicta et cumque corporis aperiam alias id porro nam. Amet ex reprehenderit cumque fuga recusandae voluptates sed. Suscipit vel iure voluptatum aliquid minus.+ Enim dolores ratione praesentium veniam nostrum. Ut repudiandae officiis voluptatem sapiente aperiam. Odit explicabo quis et illum nulla sit. In earum nisi iusto exercitationem praesentium nobis minus.+ slug: product-63183meta_description:meta_keywords:variant_count: 1- available_on: '2025-03-04T23:17:32.018Z'- created_at: '2026-03-04T23:17:32.035Z'- updated_at: '2026-03-04T23:17:32.083Z'+ available_on: '2025-03-05T10:13:39.726Z'+ created_at: '2026-03-05T10:13:39.744Z'+ updated_at: '2026-03-05T10:13:39.801Z'purchasable: truein_stock: falsebackorderable: true@@ -6025,20 +6111,17 @@ paths:price_list_id:original_price:- id: prod_gbHJdmfrXB- name: Product 649791- description: |-- Autem quam quod quisquam eos rem. Alias recusandae et magnam quis distinctio. Architecto excepturi voluptate alias exercitationem non porro aspernatur. Natus assumenda corporis maiores sint tenetur aspernatur inventore.- Reiciendis placeat reprehenderit incidunt ducimus earum deserunt. Molestiae eveniet alias deleniti quia. Minima omnis dolores necessitatibus cupiditate delectus. Qui quibusdam in sequi vitae. Atque maiores nam modi animi aliquam odit.- Porro dolore libero accusantium autem. Voluptatibus rerum minus excepturi sunt quam iure veniam. Quam illo dolor quisquam libero fugit odio. Repudiandae labore perspiciatis laborum suscipit sit incidunt expedita illum. Exercitationem consequuntur inventore earum nulla.- Cum sequi aliquid dolores quia amet assumenda quidem. Ab impedit est repellendus fugit quod nam autem dolores. Officiis accusamus repudiandae similique harum consectetur. Omnis dolore blanditiis quod illum recusandae ullam praesentium assumenda.- Voluptatem autem ad explicabo perferendis eveniet molestias. Nemo dolorum dolor earum enim deleniti. Totam consequatur facere quam molestiae deleniti magni quibusdam.- slug: product-649791+ name: Product 644845+ description: Pariatur iste culpa quo quaerat dolorum optio. Nobis+ possimus laborum autem praesentium cupiditate labore voluptatibus+ sunt. Magni temporibus enim qui in.+ slug: product-644845meta_description:meta_keywords:variant_count: 0- available_on: '2025-03-04T23:17:32.097Z'- created_at: '2026-03-04T23:17:32.112Z'- updated_at: '2026-03-04T23:17:32.130Z'+ available_on: '2025-03-05T10:13:39.807Z'+ created_at: '2026-03-05T10:13:39.820Z'+ updated_at: '2026-03-05T10:13:39.835Z'purchasable: truein_stock: falsebackorderable: true@@ -6137,20 +6220,18 @@ paths:application/json:example:id: prod_UkLWZg9DAJ- name: Product 756903+ name: Product 753365description: |-- Itaque nostrum repudiandae qui ipsa magni dolore rerum. Eius hic ipsum optio enim. Tenetur et illo ipsa alias ut illum sit ullam.- Porro excepturi sint ratione quibusdam est nisi reprehenderit. Similique quos ad perspiciatis aliquam accusamus laboriosam placeat error. Natus sit perspiciatis odit recusandae. Soluta magnam culpa incidunt maxime earum. Officiis quae temporibus repudiandae odio.- Animi iure totam harum ea facere dolor tempore. Harum quo repellendus dolor praesentium nihil odio. Facere laboriosam delectus sint labore id deleniti modi.- Ad tempora molestias quasi tempore corrupti porro. Error provident magnam placeat voluptatem dolor tempore quam. Sunt ut excepturi atque assumenda incidunt laudantium dolore facilis. Architecto repellendus eum debitis consequuntur quidem beatae odit.- Consequuntur ipsa labore alias temporibus sint. Qui laudantium tempore at inventore. Adipisci cumque architecto soluta quibusdam consequatur maxime.- slug: product-756903+ Sunt voluptatum culpa quas sed veritatis. Maxime laborum impedit quasi atque. Laborum sit dolores labore unde aliquid mollitia laboriosam. A provident autem at culpa. Libero sit quae fugit vitae.+ Aut voluptatum assumenda occaecati quia ipsum architecto consequuntur. Nihil quod assumenda doloribus molestiae dolorum. Saepe porro vel quaerat ipsa quo. Inventore occaecati natus accusamus accusantium quo fugiat.+ Quas possimus fuga iure dolorum aut cupiditate exercitationem nisi. Dolores unde consequatur fugit aperiam dignissimos. Laudantium rerum ipsam debitis culpa aliquid minima.+ slug: product-753365meta_description:meta_keywords:variant_count: 1- available_on: '2025-03-04T23:17:32.886Z'- created_at: '2026-03-04T23:17:32.901Z'- updated_at: '2026-03-04T23:17:32.937Z'+ available_on: '2025-03-05T10:13:40.798Z'+ created_at: '2026-03-05T10:13:40.840Z'+ updated_at: '2026-03-05T10:13:40.915Z'purchasable: truein_stock: falsebackorderable: true@@ -6367,15 +6448,15 @@ paths:example:data:- id: ship_UkLWZg9DAJ- number: H36627113843+ number: H99763907331state: pendingtracking: U10000tracking_url:cost: '100.0'display_cost: "$100.00"shipped_at:- created_at: '2026-03-04T23:17:35.557Z'- updated_at: '2026-03-04T23:17:35.570Z'+ created_at: '2026-03-05T10:13:43.668Z'+ updated_at: '2026-03-05T10:13:43.684Z'shipping_method:id: shpm_UkLWZg9DAJname: UPS Ground@@ -6383,7 +6464,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: STATE_ABBR_290- name: Miss Bechtelar+ name: Mechelle Mulleraddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -6480,15 +6561,15 @@ paths:application/json:example:id: ship_UkLWZg9DAJ- number: H57374938407+ number: H66430609348state: pendingtracking: U10000tracking_url:cost: '100.0'display_cost: "$100.00"shipped_at:- created_at: '2026-03-04T23:17:36.753Z'- updated_at: '2026-03-04T23:17:36.766Z'+ created_at: '2026-03-05T10:13:45.022Z'+ updated_at: '2026-03-05T10:13:45.038Z'shipping_method:id: shpm_UkLWZg9DAJname: UPS Ground@@ -6496,7 +6577,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: STATE_ABBR_298- name: Rhona Sporer+ name: Sherell Ebertaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -6585,10 +6666,10 @@ paths:application/json:example:id: or_UkLWZg9DAJ- number: R522739674+ number: R130981873state: delivery- token: DBJz1J5fiTq649JC5vARu66UUn8Hchuih7R- email: [email protected]+ token: dmgW9Kkr3ADhwpYaP99X5Pv23fZProyS8eE+ email: [email protected]special_instructions:currency: USDlocale: en@@ -6613,16 +6694,16 @@ paths:total: '110.0'display_total: "$110.00"completed_at:- created_at: '2026-03-04T23:17:37.952Z'- updated_at: '2026-03-04T23:17:38.017Z'+ created_at: '2026-03-05T10:13:46.236Z'+ updated_at: '2026-03-05T10:13:46.318Z'order_promotions: []line_items:- id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 1077585- slug: product-1077585+ name: Product 1077889+ slug: product-1077889options_text: ''price: '10.0'display_price: "$10.00"@@ -6641,23 +6722,23 @@ paths:discounted_amount: '10.0'display_discounted_amount: "$10.00"display_compare_at_amount: "$0.00"- created_at: '2026-03-04T23:17:37.980Z'- updated_at: '2026-03-04T23:17:37.980Z'+ created_at: '2026-03-05T10:13:46.271Z'+ updated_at: '2026-03-05T10:13:46.271Z'compare_at_amount:thumbnail_url:option_values: []digital_links: []shipments:- id: ship_UkLWZg9DAJ- number: H31129207409+ number: H63529024761state: pendingtracking: U10000tracking_url:cost: '100.0'display_cost: "$100.00"shipped_at:- created_at: '2026-03-04T23:17:37.984Z'- updated_at: '2026-03-04T23:17:38.016Z'+ created_at: '2026-03-05T10:13:46.276Z'+ updated_at: '2026-03-05T10:13:46.317Z'shipping_method:id: shpm_UkLWZg9DAJname: UPS Ground@@ -6665,7 +6746,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: STATE_ABBR_306- name: Alla Doyle+ name: Annamarie Stammaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -6787,6 +6868,13 @@ paths:required: falseschema:type: string+ - name: Idempotency-Key+ in: header+ required: false+ description: Unique key for request idempotency. Duplicate requests with the+ same key return the cached response.+ schema:+ type: stringresponses:'200':description: store credit applied@@ -6794,10 +6882,10 @@ paths:application/json:example:id: or_UkLWZg9DAJ- number: R015206746+ number: R311775774state: cart- token: SZQ3RGwTHXmQ6k63D5e211rXdJofgA8GjKb- email: [email protected]+ token: 8tbpJXcEWeXFg4RuxfyEa93vMPuAB42zyPf+ email: [email protected]special_instructions:currency: USDlocale: en@@ -6822,16 +6910,16 @@ paths:total: '110.0'display_total: "$110.00"completed_at:- created_at: '2026-03-04T23:17:39.174Z'- updated_at: '2026-03-04T23:17:39.233Z'+ created_at: '2026-03-05T10:13:47.547Z'+ updated_at: '2026-03-05T10:13:47.616Z'order_promotions: []line_items:- id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 1091147- slug: product-1091147+ name: Product 109916+ slug: product-109916options_text: ''price: '10.0'display_price: "$10.00"@@ -6850,23 +6938,23 @@ paths:discounted_amount: '10.0'display_discounted_amount: "$10.00"display_compare_at_amount: "$0.00"- created_at: '2026-03-04T23:17:39.212Z'- updated_at: '2026-03-04T23:17:39.212Z'+ created_at: '2026-03-05T10:13:47.589Z'+ updated_at: '2026-03-05T10:13:47.589Z'compare_at_amount:thumbnail_url:option_values: []digital_links: []shipments:- id: ship_UkLWZg9DAJ- number: H66631866452+ number: H79276526862state: pendingtracking: U10000tracking_url:cost: '100.0'display_cost: "$100.00"shipped_at:- created_at: '2026-03-04T23:17:39.218Z'- updated_at: '2026-03-04T23:17:39.231Z'+ created_at: '2026-03-05T10:13:47.596Z'+ updated_at: '2026-03-05T10:13:47.613Z'shipping_method:id: shpm_UkLWZg9DAJname: UPS Ground@@ -6874,7 +6962,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: STATE_ABBR_314- name: Breann Maggio+ name: Patti Riceaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -6896,12 +6984,12 @@ paths:- id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJstate: checkout- response_code: 1-SC-20260304231739553062- number: POPWUXIE+ response_code: 1-SC-20260305101347940643+ number: PB31NPM5amount: '10.0'display_amount: "$10.00"- created_at: '2026-03-04T23:17:39.557Z'- updated_at: '2026-03-04T23:17:39.557Z'+ created_at: '2026-03-05T10:13:47.945Z'+ updated_at: '2026-03-05T10:13:47.945Z'source_type: store_creditsource_id: credit_UkLWZg9DAJsource:@@ -7031,10 +7119,10 @@ paths:application/json:example:id: or_UkLWZg9DAJ- number: R430088395+ number: R291466717state: cart- token: FufYDJ8FrCFcpjK8Stcu1H1t7ABGdNMP4YU- email: [email protected]+ token: Ujg2thaKHpVPLBNERosPBLAyTshKx47KL8p+ email: [email protected]special_instructions:currency: USDlocale: en@@ -7059,16 +7147,16 @@ paths:total: '110.0'display_total: "$110.00"completed_at:- created_at: '2026-03-04T23:17:40.739Z'- updated_at: '2026-03-04T23:17:40.794Z'+ created_at: '2026-03-05T10:13:49.173Z'+ updated_at: '2026-03-05T10:13:49.231Z'order_promotions: []line_items:- id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 1119982- slug: product-1119982+ name: Product 1118228+ slug: product-1118228options_text: ''price: '10.0'display_price: "$10.00"@@ -7087,23 +7175,23 @@ paths:discounted_amount: '10.0'display_discounted_amount: "$10.00"display_compare_at_amount: "$0.00"- created_at: '2026-03-04T23:17:40.771Z'- updated_at: '2026-03-04T23:17:40.771Z'+ created_at: '2026-03-05T10:13:49.208Z'+ updated_at: '2026-03-05T10:13:49.208Z'compare_at_amount:thumbnail_url:option_values: []digital_links: []shipments:- id: ship_UkLWZg9DAJ- number: H05190110867+ number: H36527459684state: pendingtracking: U10000tracking_url:cost: '100.0'display_cost: "$100.00"shipped_at:- created_at: '2026-03-04T23:17:40.778Z'- updated_at: '2026-03-04T23:17:40.792Z'+ created_at: '2026-03-05T10:13:49.213Z'+ updated_at: '2026-03-05T10:13:49.228Z'shipping_method:id: shpm_UkLWZg9DAJname: UPS Ground@@ -7111,7 +7199,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: STATE_ABBR_322- name: Sharmaine Wiegand+ name: Emily Cronaaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -7223,32 +7311,32 @@ paths:- id: txnmy_UkLWZg9DAJname: Categoriesposition: 1- created_at: '2026-03-04T23:16:37.533Z'- updated_at: '2026-03-04T23:16:37.559Z'+ created_at: '2026-03-05T10:12:43.448Z'+ updated_at: '2026-03-05T10:12:43.468Z'root_id: txn_UkLWZg9DAJ- id: txnmy_gbHJdmfrXBname: Brandsposition: 2- created_at: '2026-03-04T23:16:37.560Z'- updated_at: '2026-03-04T23:16:37.572Z'+ created_at: '2026-03-05T10:12:43.469Z'+ updated_at: '2026-03-05T10:12:43.477Z'root_id: txn_gbHJdmfrXB- id: txnmy_EfhxLZ9ck8name: Collectionsposition: 3- created_at: '2026-03-04T23:16:37.573Z'- updated_at: '2026-03-04T23:16:37.653Z'+ created_at: '2026-03-05T10:12:43.479Z'+ updated_at: '2026-03-05T10:12:43.616Z'root_id: txn_EfhxLZ9ck8- id: txnmy_VqXmZF31wYname: taxonomy_11position: 4- created_at: '2026-03-04T23:17:40.834Z'- updated_at: '2026-03-04T23:17:40.843Z'+ created_at: '2026-03-05T10:13:49.272Z'+ updated_at: '2026-03-05T10:13:49.282Z'root_id: txn_OIJLhNcSbf- id: txnmy_uw2YK1rnl0name: taxonomy_12position: 5- created_at: '2026-03-04T23:17:40.844Z'- updated_at: '2026-03-04T23:17:40.852Z'+ created_at: '2026-03-05T10:13:49.283Z'+ updated_at: '2026-03-05T10:13:49.292Z'root_id: txn_AXs1igzRC6meta:page: 1@@ -7328,8 +7416,8 @@ paths:id: txnmy_VqXmZF31wYname: taxonomy_17position: 4- created_at: '2026-03-04T23:17:41.094Z'- updated_at: '2026-03-04T23:17:41.103Z'+ created_at: '2026-03-05T10:13:49.558Z'+ updated_at: '2026-03-05T10:13:49.569Z'root_id: txn_OIJLhNcSbfschema:"$ref": "#/components/schemas/StoreTaxonomy"@@ -7405,8 +7493,8 @@ paths:meta_description:meta_keywords:children_count: 0- created_at: '2026-03-04T23:16:37.544Z'- updated_at: '2026-03-04T23:16:37.556Z'+ created_at: '2026-03-05T10:12:43.458Z'+ updated_at: '2026-03-05T10:12:43.467Z'parent_id:taxonomy_id: txnmy_UkLWZg9DAJdescription: ''@@ -7425,8 +7513,8 @@ paths:meta_description:meta_keywords:children_count: 0- created_at: '2026-03-04T23:16:37.564Z'- updated_at: '2026-03-04T23:16:37.569Z'+ created_at: '2026-03-05T10:12:43.471Z'+ updated_at: '2026-03-05T10:12:43.476Z'parent_id:taxonomy_id: txnmy_gbHJdmfrXBdescription: ''@@ -7445,8 +7533,8 @@ paths:meta_description:meta_keywords:children_count: 2- created_at: '2026-03-04T23:16:37.577Z'- updated_at: '2026-03-04T23:16:37.653Z'+ created_at: '2026-03-05T10:12:43.482Z'+ updated_at: '2026-03-05T10:12:43.616Z'parent_id:taxonomy_id: txnmy_EfhxLZ9ck8description: ''@@ -7465,8 +7553,8 @@ paths:meta_description:meta_keywords:children_count: 0- created_at: '2026-03-04T23:16:37.593Z'- updated_at: '2026-03-04T23:16:37.595Z'+ created_at: '2026-03-05T10:12:43.516Z'+ updated_at: '2026-03-05T10:12:43.520Z'parent_id: txn_EfhxLZ9ck8taxonomy_id: txnmy_EfhxLZ9ck8description: ''@@ -7485,8 +7573,8 @@ paths:meta_description:meta_keywords:children_count: 0- created_at: '2026-03-04T23:16:37.610Z'- updated_at: '2026-03-04T23:16:37.612Z'+ created_at: '2026-03-05T10:12:43.550Z'+ updated_at: '2026-03-05T10:12:43.554Z'parent_id: txn_EfhxLZ9ck8taxonomy_id: txnmy_EfhxLZ9ck8description: ''@@ -7505,8 +7593,8 @@ paths:meta_description:meta_keywords:children_count: 1- created_at: '2026-03-04T23:17:41.545Z'- updated_at: '2026-03-04T23:17:41.593Z'+ created_at: '2026-03-05T10:13:49.994Z'+ updated_at: '2026-03-05T10:13:50.050Z'parent_id:taxonomy_id: txnmy_VqXmZF31wYdescription: ''@@ -7525,8 +7613,8 @@ paths:meta_description:meta_keywords:children_count: 1- created_at: '2026-03-04T23:17:41.553Z'- updated_at: '2026-03-04T23:17:41.593Z'+ created_at: '2026-03-05T10:13:50.004Z'+ updated_at: '2026-03-05T10:13:50.050Z'parent_id: txn_OIJLhNcSbftaxonomy_id: txnmy_VqXmZF31wYdescription: ''@@ -7545,8 +7633,8 @@ paths:meta_description:meta_keywords:children_count: 0- created_at: '2026-03-04T23:17:41.562Z'- updated_at: '2026-03-04T23:17:41.568Z'+ created_at: '2026-03-05T10:13:50.016Z'+ updated_at: '2026-03-05T10:13:50.024Z'parent_id: txn_AXs1igzRC6taxonomy_id: txnmy_VqXmZF31wYdescription: ''@@ -7641,8 +7729,8 @@ paths:meta_description:meta_keywords:children_count: 1- created_at: '2026-03-04T23:17:42.123Z'- updated_at: '2026-03-04T23:17:42.162Z'+ created_at: '2026-03-05T10:13:50.654Z'+ updated_at: '2026-03-05T10:13:50.698Z'parent_id: txn_OIJLhNcSbftaxonomy_id: txnmy_VqXmZF31wYdescription: ''@@ -7763,17 +7851,19 @@ paths:example:data:- id: prod_UkLWZg9DAJ- name: Product 1199087- description: Et doloremque molestiae voluptas eius illum deleniti.- Esse provident maxime culpa praesentium sit. Quidem veniam mollitia- voluptas culpa.- slug: product-1199087+ name: Product 1194924+ description: Dignissimos assumenda voluptatem maiores dolorem fugiat+ aliquid exercitationem cum. In minima a quaerat sapiente dolor.+ Consectetur sint placeat nesciunt et temporibus accusamus. Sequi+ repellat maiores quod cum repellendus quaerat. Et illo optio enim+ atque facilis voluptatum.+ slug: product-1194924meta_description:meta_keywords:variant_count: 0- available_on: '2025-03-04T23:17:42.964Z'- created_at: '2026-03-04T23:17:42.977Z'- updated_at: '2026-03-04T23:17:42.989Z'+ available_on: '2025-03-05T10:13:51.626Z'+ created_at: '2026-03-05T10:13:51.644Z'+ updated_at: '2026-03-05T10:13:51.660Z'purchasable: truein_stock: falsebackorderable: true@@ -7884,9 +7974,9 @@ paths:data:- id: wl_UkLWZg9DAJname: My Wishlist- token: aH354vPCtjrscwZndAxwdyiq- created_at: '2026-03-04T23:17:44.036Z'- updated_at: '2026-03-04T23:17:44.036Z'+ token: xFbe8r4JW2JmLbnWPbU3nf1Z+ created_at: '2026-03-05T10:13:52.806Z'+ updated_at: '2026-03-05T10:13:52.806Z'is_default: falseis_private: truemeta:@@ -7962,9 +8052,9 @@ paths:example:id: wl_gbHJdmfrXBname: Birthday Ideas- token: qaFhpLWeyp2ytNYMTgvPscK9- created_at: '2026-03-04T23:17:45.216Z'- updated_at: '2026-03-04T23:17:45.216Z'+ token: QF1SAfqELzu2zT8FqkEiELNu+ created_at: '2026-03-05T10:13:54.065Z'+ updated_at: '2026-03-05T10:13:54.065Z'is_default: falseis_private: trueschema:@@ -8053,9 +8143,9 @@ paths:example:id: wl_UkLWZg9DAJname: My Wishlist- token: oaG4tDn7ufRAhXe2PEPvZKkH- created_at: '2026-03-04T23:17:46.326Z'- updated_at: '2026-03-04T23:17:46.326Z'+ token: bbJc5dyvARbyYt8dEu9i16Ph+ created_at: '2026-03-05T10:13:55.203Z'+ updated_at: '2026-03-05T10:13:55.203Z'is_default: falseis_private: trueschema:@@ -8117,9 +8207,9 @@ paths:example:id: wl_UkLWZg9DAJname: Updated Name- token: jBdZdCcjTMrw7pYSVTcYaZMu- created_at: '2026-03-04T23:17:47.487Z'- updated_at: '2026-03-04T23:17:47.534Z'+ token: ihAc9ZHb5pQVgBZ4RY8AmBrH+ created_at: '2026-03-05T10:13:56.407Z'+ updated_at: '2026-03-05T10:13:56.459Z'is_default: falseis_private: trueschema:@@ -8231,8 +8321,8 @@ paths:variant_id: variant_gbHJdmfrXBwishlist_id: wl_UkLWZg9DAJquantity: 1- created_at: '2026-03-04T23:17:48.713Z'- updated_at: '2026-03-04T23:17:48.713Z'+ created_at: '2026-03-05T10:13:57.718Z'+ updated_at: '2026-03-05T10:13:57.718Z'variant:id: variant_gbHJdmfrXBproduct_id: prod_gbHJdmfrXB@@ -8241,8 +8331,8 @@ paths:options_text: ''track_inventory: trueimage_count: 0- created_at: '2026-03-04T23:17:48.691Z'- updated_at: '2026-03-04T23:17:48.699Z'+ created_at: '2026-03-05T10:13:57.683Z'+ updated_at: '2026-03-05T10:13:57.698Z'thumbnail:purchasable: truein_stock: falsediff --git a/docs/docs.json b/docs/docs.jsonindex 149079180a..8ea90e1f57 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -424,6 +424,7 @@"api-reference/store-api/introduction","api-reference/store-api/authentication","api-reference/store-api/errors",+ "api-reference/store-api/idempotency","api-reference/store-api/rate-limitting","api-reference/store-api/querying","api-reference/store-api/relations",diff --git a/packages/sdk/.changeset/idempotency-key-support.md b/packages/sdk/.changeset/idempotency-key-support.mdnew file mode 100644index 0000000000..fde7bf867d--- /dev/null+++ b/packages/sdk/.changeset/idempotency-key-support.md@@ -0,0 +1,5 @@+---+"@spree/sdk": patch+---++Add `idempotencyKey` option to `RequestOptions` and auto-generate idempotency keys for all mutating requests (POST, PUT, PATCH, DELETE) when retries are enabled. This enables safe automatic retries on 5xx errors and network failures for all requests, matching Stripe SDK behavior. User-supplied keys take precedence over auto-generated ones.diff --git a/packages/sdk/src/request.ts b/packages/sdk/src/request.tsindex 6f8ebd67ab..33fee8ee3c 100644--- a/packages/sdk/src/request.ts+++ b/packages/sdk/src/request.ts@@ -24,6 +24,8 @@ export interface RequestOptions {currency?: string;/** Country ISO code for market resolution (e.g., 'US', 'DE') */country?: string;+ /** Idempotency key for safe retries of mutating requests (max 255 characters) */+ idempotencyKey?: string;/** Custom headers */headers?: Record<string, string>;}@@ -63,17 +65,21 @@ function sleep(ms: number): Promise<void> {return new Promise((resolve) => setTimeout(resolve, ms));}-function shouldRetryOnStatus(method: string, status: number, config: Required<RetryConfig>): boolean {- const isIdempotent = method === 'GET' || method === 'HEAD';+function generateIdempotencyKey(): string {+ return `spree-sdk-retry-${crypto.randomUUID()}`;+}++function shouldRetryOnStatus(method: string, status: number, config: Required<RetryConfig>, hasIdempotencyKey: boolean): boolean {+ const isIdempotent = method === 'GET' || method === 'HEAD' || hasIdempotencyKey;if (isIdempotent) {return config.retryOnStatus.includes(status);}return status === 429;}-function shouldRetryOnNetworkError(method: string, config: Required<RetryConfig>): boolean {+function shouldRetryOnNetworkError(method: string, config: Required<RetryConfig>, hasIdempotencyKey: boolean): boolean {if (!config.retryOnNetworkError) return false;- return method === 'GET' || method === 'HEAD';+ return method === 'GET' || method === 'HEAD' || hasIdempotencyKey;}export interface RequestConfig {@@ -101,7 +107,7 @@ export function createRequestFn(path: string,options: InternalRequestOptions = {}): Promise<T> {- const { token, orderToken, headers = {}, body, params } = options;+ const { token, orderToken, idempotencyKey, headers = {}, body, params } = options;// Per-request options override client-level defaultsconst locale = options.locale ?? defaults?.locale;@@ -151,6 +157,16 @@ export function createRequestFn(requestHeaders['x-spree-country'] = country;}+ // Auto-generate idempotency key for mutating requests when retries are enabled (Stripe-style).+ // User-supplied keys take precedence over auto-generated ones.+ const isMutating = method !== 'GET' && method !== 'HEAD';+ const effectiveIdempotencyKey = idempotencyKey ?? (isMutating && config.retryConfig ? generateIdempotencyKey() : undefined);++ if (effectiveIdempotencyKey) {+ requestHeaders['Idempotency-Key'] = effectiveIdempotencyKey;+ }++ const hasIdempotencyKey = !!effectiveIdempotencyKey;const maxAttempts = config.retryConfig ? config.retryConfig.maxRetries + 1 : 1;for (let attempt = 0; attempt < maxAttempts; attempt++) {@@ -164,7 +180,7 @@ export function createRequestFn(if (!response.ok) {const isLastAttempt = attempt >= maxAttempts - 1;- if (!isLastAttempt && config.retryConfig && shouldRetryOnStatus(method, response.status, config.retryConfig)) {+ if (!isLastAttempt && config.retryConfig && shouldRetryOnStatus(method, response.status, config.retryConfig, hasIdempotencyKey)) {const retryAfter = response.headers.get('Retry-After');const delay = retryAfter? Math.min(parseInt(retryAfter, 10) * 1000, config.retryConfig.maxDelay)@@ -190,7 +206,7 @@ export function createRequestFn(const isLastAttempt = attempt >= maxAttempts - 1;- if (!isLastAttempt && config.retryConfig && shouldRetryOnNetworkError(method, config.retryConfig)) {+ if (!isLastAttempt && config.retryConfig && shouldRetryOnNetworkError(method, config.retryConfig, hasIdempotencyKey)) {const delay = calculateDelay(attempt, config.retryConfig);await sleep(delay);continue;diff --git a/packages/sdk/tests/retry.test.ts b/packages/sdk/tests/retry.test.tsindex 0995c11187..994062dd77 100644--- a/packages/sdk/tests/retry.test.ts+++ b/packages/sdk/tests/retry.test.ts@@ -103,8 +103,8 @@ describe('Retry logic', () => {});});- describe('POST requests (non-idempotent)', () => {- it('retries POST on 429 only', async () => {+ describe('POST requests (auto-idempotency)', () => {+ it('retries POST on 429', async () => {const mockFetch = vi.fn().mockResolvedValueOnce(errorResponse(429, 'rate_limited', 'Too many requests')).mockResolvedValueOnce(jsonResponse({ token: 'abc', user: { id: '1', email: '[email protected]' } }));@@ -116,11 +116,57 @@ describe('Retry logic', () => {expect(mockFetch).toHaveBeenCalledTimes(2);});- it('does NOT retry POST on 500', async () => {+ it('retries POST on 500 with auto-generated idempotency key', async () => {const mockFetch = vi.fn()- .mockResolvedValueOnce(errorResponse(500, 'server_error', 'Internal error'));+ .mockResolvedValueOnce(errorResponse(500, 'server_error', 'Internal error'))+ .mockResolvedValueOnce(jsonResponse({ token: 'abc', user: { id: '1', email: '[email protected]' } }));++ const client = createSpreeClient({ ...baseConfig, fetch: mockFetch });+ const result = await client.store.auth.login({ email: '[email protected]', password: 'pass' });++ expect(result.token).toBe('abc');+ expect(mockFetch).toHaveBeenCalledTimes(2);+ });++ it('retries POST on network errors with auto-generated idempotency key', async () => {+ const mockFetch = vi.fn()+ .mockRejectedValueOnce(new TypeError('fetch failed'))+ .mockResolvedValueOnce(jsonResponse({ token: 'abc', user: { id: '1', email: '[email protected]' } }));++ const client = createSpreeClient({ ...baseConfig, fetch: mockFetch });+ const result = await client.store.auth.login({ email: '[email protected]', password: 'pass' });++ expect(result.token).toBe('abc');+ expect(mockFetch).toHaveBeenCalledTimes(2);+ });++ it('sends auto-generated Idempotency-Key header on POST', async () => {+ const mockFetch = vi.fn()+ .mockResolvedValueOnce(jsonResponse({ token: 'abc', user: { id: '1', email: '[email protected]' } }));const client = createSpreeClient({ ...baseConfig, fetch: mockFetch });+ await client.store.auth.login({ email: '[email protected]', password: 'pass' });++ const headers = mockFetch.mock.calls[0][1].headers;+ expect(headers['Idempotency-Key']).toMatch(/^spree-sdk-retry-/);+ });++ it('does not send Idempotency-Key on GET', async () => {+ const mockFetch = vi.fn()+ .mockResolvedValueOnce(jsonResponse({ data: [], meta: {} }));++ const client = createSpreeClient({ ...baseConfig, fetch: mockFetch });+ await client.store.products.list();++ const headers = mockFetch.mock.calls[0][1].headers;+ expect(headers['Idempotency-Key']).toBeUndefined();+ });++ it('does NOT retry POST when retries are disabled', async () => {+ const mockFetch = vi.fn()+ .mockResolvedValueOnce(errorResponse(500, 'server_error', 'Internal error'));++ const client = createSpreeClient({ ...baseConfig, fetch: mockFetch, retry: false });await expect(client.store.auth.login({ email: '[email protected]', password: 'pass' })@@ -128,16 +174,26 @@ describe('Retry logic', () => {expect(mockFetch).toHaveBeenCalledTimes(1);});- it('does NOT retry POST on network errors', async () => {+ it('does not send Idempotency-Key when retries are disabled', async () => {const mockFetch = vi.fn()- .mockRejectedValueOnce(new TypeError('fetch failed'));+ .mockResolvedValueOnce(jsonResponse({ token: 'abc', user: { id: '1', email: '[email protected]' } }));++ const client = createSpreeClient({ ...baseConfig, fetch: mockFetch, retry: false });+ await client.store.auth.login({ email: '[email protected]', password: 'pass' });++ const headers = mockFetch.mock.calls[0][1].headers;+ expect(headers['Idempotency-Key']).toBeUndefined();+ });++ it('uses user-supplied key over auto-generated one', async () => {+ const mockFetch = vi.fn()+ .mockResolvedValueOnce(jsonResponse({ number: 'R123', token: 'cart-token' }));const client = createSpreeClient({ ...baseConfig, fetch: mockFetch });+ await client.store.cart.create(undefined, { idempotencyKey: 'my-custom-key' });- await expect(- client.store.auth.login({ email: '[email protected]', password: 'pass' })- ).rejects.toThrow(TypeError);- expect(mockFetch).toHaveBeenCalledTimes(1);+ const headers = mockFetch.mock.calls[0][1].headers;+ expect(headers['Idempotency-Key']).toBe('my-custom-key');});});diff --git a/server/Gemfile.lock b/server/Gemfile.lockindex 0fdb82c5f4..c0a5e28ce2 100644--- a/server/Gemfile.lock+++ b/server/Gemfile.lock@@ -11,7 +11,7 @@ GITPATHremote: ../spree/adminspecs:- spree_admin (5.4.0.beta3)+ spree_admin (5.4.0.beta4)active_link_tobreadcrumbs_on_rails (~> 4.1)chartkick (~> 5.0)@@ -23,7 +23,7 @@ PATHmapkick-rb (~> 0.1)pagy (~> 43.0)ruby-oembed (~> 0.18)- spree (>= 5.4.0.beta3)+ spree (>= 5.4.0.beta4)stimulus-railstailwindcss-rails (>= 4.0)tailwindcss-ruby (>= 4.0)@@ -33,22 +33,22 @@ PATHPATHremote: ../spree/emailsspecs:- spree_emails (5.4.0.beta3)- spree (>= 5.4.0.beta3)+ spree_emails (5.4.0.beta4)+ spree (>= 5.4.0.beta4)PATHremote: ../spreespecs:- spree (5.4.0.beta3)- spree_api (= 5.4.0.beta3)- spree_core (= 5.4.0.beta3)- spree_api (5.4.0.beta3)+ spree (5.4.0.beta4)+ spree_api (= 5.4.0.beta4)+ spree_core (= 5.4.0.beta4)+ spree_api (5.4.0.beta4)alba (~> 3.0)oj (~> 3.16)pagy (~> 43.0)- spree_core (= 5.4.0.beta3)+ spree_core (= 5.4.0.beta4)typelizer (~> 0.9)- spree_core (5.4.0.beta3)+ spree_core (5.4.0.beta4)active_storage_validations (= 1.3.0)acts-as-taggable-onacts_as_list (>= 0.8)@@ -1121,12 +1121,12 @@ CHECKSUMSsimplecov-cobertura (3.1.0) sha256=6d7f38aa32c965ca2174b2e5bd88cb17138eaf629518854976ac50e628925dc5simplecov-html (0.13.2) sha256=bd0b8e54e7c2d7685927e8d6286466359b6f16b18cb0df47b508e8d73c777246simplecov_json_formatter (0.1.4) sha256=529418fbe8de1713ac2b2d612aa3daa56d316975d307244399fa4838c601b428- spree (5.4.0.beta3)- spree_admin (5.4.0.beta3)- spree_api (5.4.0.beta3)- spree_core (5.4.0.beta3)+ spree (5.4.0.beta4)+ spree_admin (5.4.0.beta4)+ spree_api (5.4.0.beta4)+ spree_core (5.4.0.beta4)spree_dev_tools (0.5.3) sha256=64ae7b215ac5d5c5f5890f6fc0dbcb12882b9af305a860f36f95f564ec240a75- spree_emails (5.4.0.beta3)+ spree_emails (5.4.0.beta4)spree_extension (0.1.0) sha256=b648327f4787295e051be4ea0c0a47baec47c2e245bca9c93ecf73605fc3a051spree_i18n (5.3.2) sha256=03b805235ca156644951f6bc3d07cbe43d0aa01134c4a27e3f3304011956f79bspree_stripe (1.5.1)diff --git a/spree/api/app/controllers/concerns/spree/api/v3/error_handler.rb b/spree/api/app/controllers/concerns/spree/api/v3/error_handler.rbindex 801a744592..16043fe85e 100644--- a/spree/api/app/controllers/concerns/spree/api/v3/error_handler.rb+++ b/spree/api/app/controllers/concerns/spree/api/v3/error_handler.rb@@ -50,6 +50,9 @@ module Spree# Rate limiting errorsrate_limit_exceeded: 'rate_limit_exceeded',+ # Idempotency errors+ idempotency_key_reused: 'idempotency_key_reused',+# Request errorsrequest_too_large: 'request_too_large',diff --git a/spree/api/app/controllers/concerns/spree/api/v3/idempotent.rb b/spree/api/app/controllers/concerns/spree/api/v3/idempotent.rbnew file mode 100644index 0000000000..ca1d2f1d4d--- /dev/null+++ b/spree/api/app/controllers/concerns/spree/api/v3/idempotent.rb@@ -0,0 +1,82 @@+module Spree+ module Api+ module V3+ module Idempotent+ extend ActiveSupport::Concern++ IDEMPOTENCY_TTL = 24.hours+ IDEMPOTENCY_HEADER = 'Idempotency-Key'+ MAX_KEY_LENGTH = 255++ MUTATING_METHODS = %w[POST PUT PATCH DELETE].freeze++ included do+ around_action :check_idempotency, if: :mutating_request?+ end++ private++ def check_idempotency+ key = request.headers[IDEMPOTENCY_HEADER]+ return yield if key.blank?++ if key.length > MAX_KEY_LENGTH+ render_error(+ code: ErrorHandler::ERROR_CODES[:invalid_request],+ message: "Idempotency-Key must be #{MAX_KEY_LENGTH} characters or less.",+ status: :bad_request+ )+ return+ end++ cache_key = idempotency_cache_key(key)+ cached = Rails.cache.read(cache_key)++ if cached+ if cached[:fingerprint] != request_fingerprint+ render_error(+ code: ErrorHandler::ERROR_CODES[:idempotency_key_reused],+ message: Spree.t(:idempotency_key_reused),+ status: :unprocessable_content+ )+ return+ end++ self.response_body = cached[:body]+ self.status = cached[:status]+ response.content_type = cached[:content_type] if cached[:content_type]+ response.headers['Idempotent-Replayed'] = 'true'+ return+ end++ yield++ # Cache 2xx and 4xx responses, skip 5xx (transient server errors should be retryable)+ if response.status < 500+ Rails.cache.write(cache_key, {+ body: response.body,+ status: response.status,+ content_type: response.content_type,+ fingerprint: request_fingerprint+ }, expires_in: IDEMPOTENCY_TTL)+ end+ end++ def mutating_request?+ MUTATING_METHODS.include?(request.method)+ end++ def idempotency_cache_key(key)+ owner_id = request.headers['X-Spree-Api-Key'].presence ||+ spree_current_user&.id ||+ request.remote_ip+ "spree:idempotency:#{Digest::SHA256.hexdigest(owner_id.to_s)}:#{Digest::SHA256.hexdigest(key)}"+ end++ def request_fingerprint+ Digest::SHA256.hexdigest("#{request.method}:#{request.path}:#{request.raw_post}")+ end+ end+ end+ end+enddiff --git a/spree/api/app/controllers/spree/api/v3/base_controller.rb b/spree/api/app/controllers/spree/api/v3/base_controller.rbindex e4719007dc..8d3a13ea76 100644--- a/spree/api/app/controllers/spree/api/v3/base_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/base_controller.rb@@ -13,6 +13,7 @@ module Spreeinclude Spree::Api::V3::HttpCachinginclude Spree::Api::V3::SecurityHeadersinclude Spree::Api::V3::ResourceSerializer+ include Spree::Api::V3::Idempotentinclude Pagy::Method# Optional JWT authentication by defaultdiff --git a/spree/api/spec/controllers/concerns/spree/api/v3/idempotent_spec.rb b/spree/api/spec/controllers/concerns/spree/api/v3/idempotent_spec.rbnew file mode 100644index 0000000000..835e5ff7d1--- /dev/null+++ b/spree/api/spec/controllers/concerns/spree/api/v3/idempotent_spec.rb@@ -0,0 +1,98 @@+require 'spec_helper'++RSpec.describe Spree::Api::V3::Idempotent, type: :controller do+ describe Spree::Api::V3::Store::CartController do+ render_views++ include_context 'API v3 Store'++ around do |example|+ original_cache = Rails.cache+ Rails.cache = ActiveSupport::Cache::MemoryStore.new+ example.run+ ensure+ Rails.cache = original_cache+ end++ before do+ request.headers['X-Spree-Api-Key'] = api_key.token+ end++ describe 'idempotency' do+ let(:idempotency_key) { SecureRandom.uuid }++ it 'processes normally without Idempotency-Key header' do+ expect { post :create }.to change(Spree::Order, :count).by(1)+ expect(response).to have_http_status(:created)+ expect(response.headers['Idempotent-Replayed']).to be_nil+ end++ it 'caches and replays the response for duplicate requests' do+ request.headers['Idempotency-Key'] = idempotency_key++ expect { post :create }.to change(Spree::Order, :count).by(1)+ expect(response).to have_http_status(:created)+ first_response = json_response++ expect { post :create }.not_to change(Spree::Order, :count)+ expect(response).to have_http_status(:created)+ expect(response.headers['Idempotent-Replayed']).to eq('true')+ expect(json_response['id']).to eq(first_response['id'])+ end++ it 'rejects reuse of the same key with different request parameters' do+ request.headers['Idempotency-Key'] = idempotency_key++ post :create+ expect(response).to have_http_status(:created)++ post :create, params: { metadata: { source: 'mobile' } }+ expect(response).to have_http_status(:unprocessable_content)+ expect(json_response['error']['code']).to eq('idempotency_key_reused')+ end++ it 'allows different idempotency keys for different requests' do+ request.headers['Idempotency-Key'] = 'key-1'+ expect { post :create }.to change(Spree::Order, :count).by(1)++ request.headers['Idempotency-Key'] = 'key-2'+ expect { post :create }.to change(Spree::Order, :count).by(1)+ end++ it 'scopes cache by API key' do+ request.headers['Idempotency-Key'] = idempotency_key+ post :create+ first_response = json_response++ other_api_key = create(:api_key, :publishable, store: store)+ request.headers['X-Spree-Api-Key'] = other_api_key.token+ request.headers['Idempotency-Key'] = idempotency_key++ expect { post :create }.to change(Spree::Order, :count).by(1)+ expect(response.headers['Idempotent-Replayed']).to be_nil+ expect(json_response['id']).not_to eq(first_response['id'])+ end++ it 'rejects keys longer than 255 characters' do+ request.headers['Idempotency-Key'] = 'a' * 256++ post :create+ expect(response).to have_http_status(:bad_request)+ expect(json_response['error']['code']).to eq('invalid_request')+ end++ it 'does not apply to GET requests' do+ cart = create(:order, store: store)+ request.headers['x-spree-order-token'] = cart.token+ request.headers['Idempotency-Key'] = idempotency_key++ get :show+ expect(response).to have_http_status(:ok)++ get :show+ expect(response).to have_http_status(:ok)+ expect(response.headers['Idempotent-Replayed']).to be_nil+ end+ end+ end+enddiff --git a/spree/api/spec/integration/spree/api/v3/store/cart_spec.rb b/spree/api/spec/integration/spree/api/v3/store/cart_spec.rbindex 61ae6e89f5..f340dc9882 100644--- a/spree/api/spec/integration/spree/api/v3/store/cart_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/store/cart_spec.rb@@ -29,6 +29,8 @@ RSpec.describe 'Cart API', type: :request, swagger_doc: 'api-reference/store.yammetadata: { type: :object, description: 'Write-only key-value metadata (Stripe-style). Not returned in responses.' }}}+ parameter name: 'Idempotency-Key', in: :header, type: :string, required: false,+ description: 'Unique key for request idempotency. Duplicate requests with the same key return the cached response.'response '201', 'cart created (guest)' dolet(:'x-spree-api-key') { api_key.token }@@ -73,6 +75,44 @@ RSpec.describe 'Cart API', type: :request, swagger_doc: 'api-reference/store.yamrun_test!end++ response '400', 'idempotency key too long' do+ let(:'x-spree-api-key') { api_key.token }+ let(:'Idempotency-Key') { 'a' * 256 }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['error']['code']).to eq('invalid_request')+ end+ end++ response '422', 'idempotency key reused with different parameters' do+ let(:'x-spree-api-key') { api_key.token }+ let(:'Idempotency-Key') { 'test-idempotency-key' }++ around do |example|+ original_cache = Rails.cache+ Rails.cache = ActiveSupport::Cache::MemoryStore.new+ example.run+ ensure+ Rails.cache = original_cache+ end++ before do+ post '/api/v3/store/cart',+ headers: { 'x-spree-api-key' => api_key.token, 'Idempotency-Key' => 'test-idempotency-key' },+ as: :json+ end++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['error']['code']).to eq('idempotency_key_reused')+ end+ endendget 'Get current cart' dodiff --git a/spree/api/spec/integration/spree/api/v3/store/coupon_codes_spec.rb b/spree/api/spec/integration/spree/api/v3/store/coupon_codes_spec.rbindex c0a3ff4352..302ba6cf77 100644--- a/spree/api/spec/integration/spree/api/v3/store/coupon_codes_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/store/coupon_codes_spec.rb@@ -31,6 +31,8 @@ RSpec.describe 'Coupon Codes API', type: :request, swagger_doc: 'api-reference/sdescription: 'Order ID'parameter name: 'x-spree-order-token', in: :header, type: :string, required: false,description: 'Order token for guest access'+ parameter name: 'Idempotency-Key', in: :header, type: :string, required: false,+ description: 'Unique key for request idempotency. Duplicate requests with the same key return the cached response.'parameter name: :body, in: :body, schema: {type: :object,properties: {diff --git a/spree/api/spec/integration/spree/api/v3/store/line_items_spec.rb b/spree/api/spec/integration/spree/api/v3/store/line_items_spec.rbindex 3a6ac5ec14..5e2646195c 100644--- a/spree/api/spec/integration/spree/api/v3/store/line_items_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/store/line_items_spec.rb@@ -34,6 +34,8 @@ RSpec.describe 'Line Items API', type: :request, swagger_doc: 'api-reference/stodescription: 'Order ID or number'parameter name: 'x-spree-order-token', in: :header, type: :string, required: false,description: 'Order token for guest access'+ parameter name: 'Idempotency-Key', in: :header, type: :string, required: false,+ description: 'Unique key for request idempotency. Duplicate requests with the same key return the cached response.'parameter name: :body, in: :body, schema: {type: :object,properties: {diff --git a/spree/api/spec/integration/spree/api/v3/store/orders_spec.rb b/spree/api/spec/integration/spree/api/v3/store/orders_spec.rbindex 31b0e582af..ccf2d76805 100644--- a/spree/api/spec/integration/spree/api/v3/store/orders_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/store/orders_spec.rb@@ -108,6 +108,8 @@ RSpec.describe 'Orders API', type: :request, swagger_doc: 'api-reference/store.yparameter name: 'Authorization', in: :header, type: :string, required: falseparameter name: :id, in: :path, type: :string, required: trueparameter name: 'x-spree-order-token', in: :header, type: :string, required: false+ parameter name: 'Idempotency-Key', in: :header, type: :string, required: false,+ description: 'Unique key for request idempotency. Duplicate requests with the same key return the cached response.'parameter name: :body, in: :body, schema: {type: :object,properties: {@@ -204,6 +206,8 @@ RSpec.describe 'Orders API', type: :request, swagger_doc: 'api-reference/store.yparameter name: 'Authorization', in: :header, type: :string, required: falseparameter name: :id, in: :path, type: :string, required: trueparameter name: 'x-spree-order-token', in: :header, type: :string, required: false+ parameter name: 'Idempotency-Key', in: :header, type: :string, required: false,+ description: 'Unique key for request idempotency. Duplicate requests with the same key return the cached response.'response '200', 'order advanced' dolet(:advanceable_order) { create(:order_with_line_items, store: store, user: user) }@@ -246,6 +250,8 @@ RSpec.describe 'Orders API', type: :request, swagger_doc: 'api-reference/store.yparameter name: 'Authorization', in: :header, type: :string, required: falseparameter name: :id, in: :path, type: :string, required: trueparameter name: 'x-spree-order-token', in: :header, type: :string, required: false+ parameter name: 'Idempotency-Key', in: :header, type: :string, required: false,+ description: 'Unique key for request idempotency. Duplicate requests with the same key return the cached response.'response '200', 'order advanced' dolet(:advanceable_order) { create(:order_with_line_items, store: store, user: user) }@@ -277,6 +283,8 @@ RSpec.describe 'Orders API', type: :request, swagger_doc: 'api-reference/store.yparameter name: 'Authorization', in: :header, type: :string, required: falseparameter name: :id, in: :path, type: :string, required: trueparameter name: 'x-spree-order-token', in: :header, type: :string, required: false+ parameter name: 'Idempotency-Key', in: :header, type: :string, required: false,+ description: 'Unique key for request idempotency. Duplicate requests with the same key return the cached response.'response '200', 'order completed' dolet(:completable_order) dodiff --git a/spree/api/spec/integration/spree/api/v3/store/payment_sessions_spec.rb b/spree/api/spec/integration/spree/api/v3/store/payment_sessions_spec.rbindex 46e6f94d0f..5fa3750f09 100644--- a/spree/api/spec/integration/spree/api/v3/store/payment_sessions_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/store/payment_sessions_spec.rb@@ -39,6 +39,8 @@ RSpec.describe 'Payment Sessions API', type: :request, swagger_doc: 'api-referendescription: 'Order ID or number'parameter name: 'x-spree-order-token', in: :header, type: :string, required: false,description: 'Order token for guest access'+ parameter name: 'Idempotency-Key', in: :header, type: :string, required: false,+ description: 'Unique key for request idempotency. Duplicate requests with the same key return the cached response.'parameter name: :body, in: :body, schema: {type: :object,properties: {@@ -194,6 +196,8 @@ RSpec.describe 'Payment Sessions API', type: :request, swagger_doc: 'api-referenexternal_data: { type: :object, description: 'Provider-specific completion data' }}}+ parameter name: 'Idempotency-Key', in: :header, type: :string, required: false,+ description: 'Unique key for request idempotency. Duplicate requests with the same key return the cached response.'response '200', 'payment session completed' dolet(:'x-spree-api-key') { api_key.token }diff --git a/spree/api/spec/integration/spree/api/v3/store/store_credits_spec.rb b/spree/api/spec/integration/spree/api/v3/store/store_credits_spec.rbindex b1bd9c5a64..cef5c17153 100644--- a/spree/api/spec/integration/spree/api/v3/store/store_credits_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/store/store_credits_spec.rb@@ -26,6 +26,8 @@ RSpec.describe 'Store Credits API', type: :request, swagger_doc: 'api-reference/parameter name: 'Authorization', in: :header, type: :string, required: trueparameter name: :order_id, in: :path, type: :string, required: trueparameter name: 'x-spree-order-token', in: :header, type: :string, required: false+ parameter name: 'Idempotency-Key', in: :header, type: :string, required: false,+ description: 'Unique key for request idempotency. Duplicate requests with the same key return the cached response.'parameter name: :body, in: :body, schema: {type: :object,properties: {diff --git a/spree/core/config/locales/en.yml b/spree/core/config/locales/en.ymlindex 2df63c972d..2a1c51afed 100644--- a/spree/core/config/locales/en.yml+++ b/spree/core/config/locales/en.yml@@ -1231,6 +1231,7 @@ en:this_file_language: English (US)translations: Translationsicon: Icon+ idempotency_key_reused: This Idempotency-Key has already been used with different request parameters.image: Imageimage_alt_text: Add Alt text to your imageimages: Images