Store API: how should Add Line Item be retried safely after a lost response?

[SinnerAir]

Contract question / feature request

Does POST /store/carts/:id/line-items support an operation key that makes retrying
after a lost response safe? In the reproduction below, repeating the same request
with the same Idempotency-Key increases the quantity again.

If this header is not supported by this route, is there a recommended mechanism
for recovering an operation's outcome or retrying it without another increment?
If not, would you consider adding one and documenting the retry contract?

I am not claiming that this violates an existing documented guarantee. The
storefront guide
describes quantity as the quantity to add; I did not find a guarantee that this
route honors Idempotency-Key.

Environment

• @medusajs/medusa: 2.22.6.
• @medusajs/framework: 2.22.6.
• Node.js 24.22.2, Linux container; PostgreSQL 18.6, fresh disposable database.
• One backend, default in-memory locking and event bus; no Redis.
• Reproduced with the unmodified backend source from the official
  dtc-starter at 6440e853ee091b5ddc431aa2680dd358985aa707,
  including its config, seed, search, routes and workflows. All 24 files under
  src, plus the config/package files included in that count, matched the
  official source archive by SHA-256.
• Installed dependencies were reused from an existing Medusa 2.22.6 image; this
  was not an independent clean dependency installation.
• The disposable database URL included ?sslmode=disable because that isolated
  PostgreSQL instance does not support SSL. No pool settings or source files were
  changed. The successful run used no diagnostic preload.
• Sequential direct Store API requests using native fetch, without our
  application code or an SDK. No checkout or payment operation is involved.

Steps to reproduce

Use a disposable instance with a priced variant that has at least three available
units. Create a cart with one unit of that variant.

Send the following request, substituting the cart, variant and publishable key:

POST /store/carts/<cart-id>/line-items
x-publishable-api-key: <key>
Content-Type: application/json
Idempotency-Key: <the same UUID for both attempts>

{"variant_id":"<variant-id>","quantity":1}

1. Read the successful response but deliberately discard it before returning to
   the caller, and throw a simulated response-loss error instead.
2. Read the cart to establish that the first POST committed.
3. Send exactly the same POST again: same cart, JSON body and Idempotency-Key.
4. Read the cart again.

The standalone Node.js script below automates these steps and verifies each
observed quantity. It creates one cart and adds three units, so it should only
be run against a disposable database. Set MEDUSA_URL, MEDUSA_PUBLISHABLE_KEY,
MEDUSA_REGION_ID, and optionally MEDUSA_SALES_CHANNEL_ID.

Observed result

Initial quantity:                         1
After the POST with a discarded response:  2
After replaying it with the same key:      3

Both POST requests returned HTTP 200. Subsequent GET requests confirmed both
increments. The script returns diagnostic exit code 2 when replay increments
again, and 0 if the replay is deduplicated.

Desired contract

If an operation key is supported, replaying a completed operation should return
its outcome, or provide a way to query that outcome, without another mutation.
In this example, the quantity would remain 2.

It would help to clarify the key's scope and retention period, how a changed
request body is handled, and what happens with concurrent retries. These are
requested semantics, not assertions that the route currently promises them.

Disabling automatic retries avoids some duplicates but leaves the user with an
unknown outcome after response loss. Reading the cart does not always identify
which operation caused a quantity change when multiple tabs or concurrent actions
are involved.

Limits of this reproduction

Response loss is simulated deterministically after the first request has
completed successfully. This is not a real connection interruption or timeout
test, and it does not establish late server-side completion after cancellation.
It does not test price/stock races, cart-creation replay, checkout or payments.

Standalone reproduction script

import assert from 'node:assert/strict';
import { randomUUID } from 'node:crypto';

// Creates one cart and adds three units. Use a disposable Medusa database.
// No application code, SDK, database access or framework hooks are needed.
const base = process.env.MEDUSA_URL ?? 'http://127.0.0.1:9000';
const key = process.env.MEDUSA_PUBLISHABLE_KEY;
const region = process.env.MEDUSA_REGION_ID;
assert(key && region, 'Set MEDUSA_PUBLISHABLE_KEY and MEDUSA_REGION_ID');
const headers = { 'x-publishable-api-key': key, 'content-type': 'application/json' };
async function request(path, body, extra = {}) {
    const response = await fetch(`${base}${path}`, {
        method: body === undefined ? 'GET' : 'POST',
        headers: { ...headers, ...extra },
        body: body === undefined ? undefined : JSON.stringify(body),
        signal: AbortSignal.timeout(30_000),
    });
    const data = await response.json();
    assert.equal(response.status, 200, JSON.stringify({ path, status: response.status, data }));
    return data;
}
const query = new URLSearchParams({
    region_id: region,
    fields: '*variants.calculated_price,+variants.inventory_quantity,+variants.manage_inventory,+variants.allow_backorder',
    limit: '100',
});
const products = await request(`/store/products?${query}`);
const variant = products.products.flatMap(p => p.variants).find(v =>
    v.calculated_price?.calculated_amount != null &&
    (!v.manage_inventory || v.allow_backorder || v.inventory_quantity >= 3),
);
assert(variant, 'Seed a priced variant with at least three available units');
const { cart } = await request('/store/carts', {
    region_id: region,
    ...(process.env.MEDUSA_SALES_CHANNEL_ID ? { sales_channel_id: process.env.MEDUSA_SALES_CHANNEL_ID } : {}),
    items: [{ variant_id: variant.id, quantity: 1 }],
});
const quantity = async () => {
    const data = await request(`/store/carts/${cart.id}?fields=*items`);
    return data.cart.items.filter(i => i.variant_id === variant.id).reduce((sum, i) => sum + i.quantity, 0);
};
assert.equal(await quantity(), 1);
const operationKey = randomUUID();
const path = `/store/carts/${cart.id}/line-items`;
const payload = { variant_id: variant.id, quantity: 1 };
const operationHeaders = { 'Idempotency-Key': operationKey };

// Deterministic simulation of an unobservable successful response, NOT a
// server timeout test: the request finishes, but the caller never gets its result.
async function loseResponse() {
    await request(path, payload, operationHeaders);
    throw new Error('SIMULATED_RESPONSE_LOSS_AFTER_SUCCESS');
}
await assert.rejects(loseResponse, { message: 'SIMULATED_RESPONSE_LOSS_AFTER_SUCCESS' });
const afterLostResponse = await quantity();
assert.equal(afterLostResponse, 2);
await request(path, payload, operationHeaders); // exact same cart, payload and key
const afterReplay = await quantity();
console.log(JSON.stringify({
    cartId: cart.id, variantId: variant.id, operationKey,
    before: 1, afterLostResponse, afterReplay,
    deduplicated: afterReplay === afterLostResponse,
    simulation: 'discard completed response; no real network interruption or server timeout',
}, null, 2));
// Diagnostic exit status: 0 = idempotent, 2 = replay added again.
assert([2, 3].includes(afterReplay), 'Unexpected quantity; inspect cart');
if (afterReplay === 3) process.exitCode = 2;

[SinnerAir]

Additional evidence: I have now reproduced a mutation completing after a real client/transport timeout, rather than only discarding an already successful response.

Environment: Medusa/framework 2.22.6, Node.js 24.22.2, fresh PostgreSQL 18.6 database. The backend source/config/seed were unchanged from the official dtc-starter commit linked above. Dependencies were reused from an existing image, not independently reinstalled.

This test used isolated copies of our actual nginx configuration and built Node/Astro application. The application calls the Store API through its normal strict HTTP transport, with a 10-second timeout and no retries. No extra test proxy was inserted into that path. A successful control request first created a cart with quantity 1, using the actual application action and its signed proof/session cookies.

To make the ordering deterministic:

1. Prepare the next add operation normally.
2. In a separate database transaction, lock the existing cart_line_item row with SELECT ... FOR UPDATE.
3. Dispatch one add request. Verify via pg_blocking_pids that Medusa is waiting on that transaction (Lock / transactionid).
4. Keep the lock until the timeout is observed. Read the quantity before releasing the lock, then release it and observe the final quantity.

Results on two separate carts:

Scenario	At timeout	After releasing the database lock
HTTP client disconnects after 1.5 seconds	Actual TimeoutError after 1503 ms; nginx logs 499; quantity remains 1	Quantity becomes 2
HTTP client keeps waiting; the application's normal Store API transport reaches its 10-second deadline	Application action returns its explicit unknown result after 10085 ms; quantity remains 1	Quantity becomes 2

In both cases, the late quantity change was observed about 52 ms after releasing the lock. Medusa's HTTP logs show exactly one POST /store/carts/:id/line-items for each cart. No retry was sent.

unknown is our application's result, not a Medusa response or a claimed Medusa error code. These observations establish that a timeout/disconnect is not evidence that the mutation was rolled back or will not happen in this tested path. They do not establish that every proxy behaves the same way, or that a direct Store API disconnect always has this outcome.

Limits: this was an isolated HTTP integration test with a synthetic test publication/configuration and a fresh database, not a browser UI test or a purchase against an existing deployment. It did not test checkout, payments, price/stock races, or whether a retry would be deduplicated in this second experiment. The original replay experiment above covers that separately.

The contract question remains: is there a supported operation key or operation-status mechanism for safely resolving/retrying an Add Line Item request after this ambiguous outcome? I am still treating this as a contract/feature request, not as proof that the route violates a documented Idempotency-Key guarantee.