Friction Audit Report

What I found

POST /v1/charges accepts an Idempotency-Key header and handles it correctly. Send the same key twice and you get the same charge object back, with no second charge created. I confirmed this by hand across four repeat calls.

The header appears nowhere in the reference page for the endpoint. It is not in the parameters table, not in the request sample, and not in the errors section. Neither northwind-node nor northwind-python exposes it as an option, so an SDK user cannot send it without dropping to a raw HTTP call.

The behaviour therefore only protects integrators who guessed it was there. Most of them guessed because they have integrated Stripe before, which is a strange thing for your reliability to depend on.

The failure is worst under timeout, which is exactly when retries happen. Your gateway returns 504 on requests that exceed 30 seconds, and the charge frequently completes on your side after the 504 has already been sent. A caller that retries then charges the customer a second time.

Evidence

docs.northwindpay.com/api/charges/create

1 2

1. 1 Nine parameters documented. Idempotency-Key is not one of them.
2. 2 The request sample omits it too, so nobody copying this is protected.

Why it costs you

Your team put duplicate-charge tickets at 18% of support volume last quarter. Each one costs a support cycle, a refund, and a customer who now checks their statement.

The cost grows rather than holds steady. Retry-on-timeout is the default behaviour of every agent framework, and agents retry far more readily than humans do. As agent-written integrations increase, this defect scales with them.

This is also the cheapest finding in the report to fix. The capability already works. What is missing is a paragraph of documentation and an SDK parameter.

What I found

Your quickstart promises five minutes. I ran it cold on a fresh account and reached my first settled charge in 11 minutes 40 seconds. The gap is entirely step 3.

Step 3 asks for a publicly reachable HTTPS endpoint registered to receive charge.succeeded before any charge will resolve. On a laptop that means installing a tunneling tool, creating an account with that tool, starting a tunnel, copying the forwarding URL, and registering it in your dashboard. Five separate context switches, one of them to a third-party signup.

The note on that step says charges created before an endpoint is registered will remain pending and will not resolve. So a developer who skips ahead to step 5 gets a charge that silently never completes, and no error explains why.

This is the only step in the guide that requires leaving your product. It is also the step immediately before the two steps that produce the payoff.

Evidence

docs.northwindpay.com/guides/quickstart

1 2 3

1. 1 Promises five minutes. Measured at 11m40s.
2. 2 Skip this and your first charge silently stays pending forever.
3. 3 A third-party tunnel, installed and registered, before step 5 can succeed.

Why it costs you

Your signup-to-first-call conversion is 31%. A required third-party tool sitting between signup and first success is the single most common cause of a number in that range, and it is the step where evaluation traffic disappears without leaving a trace.

The developers you lose here are the ones evaluating you against an alternative in the same session. They do not file a ticket. They close the tab, and the only evidence is a signup that never made a second call.

The failure is silent rather than loud. A charge stuck in pending with no explanation reads as a broken product, not as a missing step.

What I found

A one-off payment can be recorded through POST /v1/charges, through POST /v1/payment_intents, or through POST /v1/invoices/:id/pay. A fourth path, POST /v1/customers/:id/charges, still exists from v1 and still appears in search results.

Searching your docs for "charge a customer" returns all four in the first five results. Each description is accurate in isolation. None of them says which one a new integration should reach for, and the descriptions overlap enough that relevance ranking cannot separate them.

Your MCP server exposes create_charge, create_payment_intent, and pay_invoice as three peer tools with one-line descriptions. An agent choosing between them has the tool name and roughly six words of guidance.

Given the plain task of charging a customer for overage, the agent selected pay_invoice in two of three runs. Both times it invented an invoice ID, failed, and retried against a second wrong tool before finding create_charge.

Human integrators hit a milder version of this. Two of the four engineers your team introduced me to had shipped code against payment_intents where charges was the simpler fit.

Evidence

docs.northwindpay.com/search?q=charge+a+customer

1 2 3

1. 1 The right answer for this task, ranked first but unmarked as canonical.
2. 2 Two near-identical descriptions. Nothing says when to use which.
3. 3 A deprecated v1 path, still surfacing in search.

docs.northwindpay.com/api/platform/mcp

1 2

1. 1 "Creates a charge." Three words, and the tool name already said all three.
2. 2 Nothing here tells a model when to prefer this over create_charge.

Why it costs you

Wrong-endpoint integrations are expensive later rather than now. They ship, they work, and then they need migrating when the semantics diverge. That is support cost and engineering cost you carry on someone else behalf.

For agents, the cost is immediate. Each wrong call is a failed request, a retry, and in the pay_invoice case a hallucinated identifier. Reliability against your surface drops for reasons that have nothing to do with the model.

This is the finding with the longest tail. Naming and information architecture are the hardest things to change once integrations depend on them, so the cost of deferring it compounds in a way the other findings do not.

What I found

Every validation failure across the v3 surface returns HTTP 400 with the body { "error": "Invalid request" }. There is no error code, no field pointer, and no indication of what would make the request valid.

On POST /v1/charges that string is the entire diagnostic for nine possible parameters. I triggered it by omitting currency, by sending amount as a string, and by passing a customer ID from test mode against a live key. All three produced identical responses.

The dashboard request log does show the parsed request body, so a human can eventually work it out by comparing what they sent against the reference. That takes a context switch and a few minutes per occurrence.

An agent has no dashboard. It reads "Invalid request", cannot infer which of nine parameters to change, and in the runs I recorded it either repeated the identical call or began altering parameters one at a time.

Evidence

Why it costs you

This is a tax on every integration you have, paid in minutes rather than in outages. It is small per occurrence and large in aggregate, and it lands hardest on new integrators who have the least context for guessing.

It is the most common shape of avoidable support ticket. A developer who cannot tell why a request was rejected asks you.

For agents it converts a recoverable failure into an unrecoverable one. An error that names the field is a second chance. An error that does not is a dead end.

What I found

A customer in the billing subsystem is a payer: an entity with payment sources, charges, and invoices, keyed cus_.

A customer in the CRM sync is an account: an organisation with seats, a plan, and contacts, keyed acct_. The sync endpoints call it customer in every field name and every payload.

The two are one-to-many in practice. One account can carry several payers, which is normal for enterprise billing. Nothing in the documentation states the relationship, and no page mentions that the word changes meaning depending on which endpoints you are calling.

I lost about forty minutes to this while building the reconciliation script, and I was looking for exactly this class of problem. Two of your own engineers described the same confusion when I asked about it, which suggests it is costing you internally as well.

The agent runs conflated the two consistently. Given an account ID where a payer ID was needed, it passed it through unchanged and got a 404 with no explanation, because the error does not say that the ID belongs to a different object type.

Evidence

Why it costs you

Conceptual mismatches are the most expensive kind of API friction because they do not present as errors. They present as code that works in testing and produces wrong numbers in production.

Robillard found that conceptual and structural problems, not syntax or tooling, dominate what makes an API hard to learn. [2] This is that category, and it is the one that documentation edits alone cannot fully fix.

The reconciliation use case is the one where this hurts most, and it is also the use case your enterprise customers care about.

What I found

GET /v1/customers/:id returns 41 fields with subscriptions, payment sources, and metadata expanded by default. There is no fields parameter and no way to request a smaller object.

A typical customer response measured 2,180 tokens. Of that, an agent answering "what plan is this customer on" needs two fields, roughly 30 tokens. The other 98% is carried and paid for.

List endpoints compound it. GET /v1/customers defaults to 100 per page with the same expansion, which is around 218,000 tokens for a single page. That exceeds the usable context of most models in one call.

Your dashboard needed the expanded shape in 2021 and the default has not been revisited since. Your own engineers confirmed no external caller depends on the expansion being unconditional.

Evidence

Why it costs you

This is the mildest finding here, and I have rated it P3 for that reason. It costs agent callers money and context rather than causing failures.

The practical effect is that an agent doing multi-step work against your API runs out of room sooner than it should. A twenty-call workflow spends roughly 43,600 tokens on customer reads where about 600 would do.

It also affects your own dashboard latency, since the same expansion is what makes the customer list slow to load.