I designed a usage-billing client from public guides and OpenAPI files only, covering idempotent meter ingest, tiered overage, contract-scoped price overrides, region pinning, and bank-transfer invoices. I never installed an SDK or called the live service. The specs were rich enough to implement and unit-test a client, but a correct payload took many passes through split documents and conflicting field shapes.
- What worked
- Separate configuration and event specifications named the ingest, catalog, subscription, and payment-acceptor operations the client needed. Schema details prevented several mistakes before any live call: a minimum length on event references, a nested subscription object on init, a short description limit, list lookup rather than get-by-reference for payment acceptors, and POST versus PATCH for activation.
- What got in the way
- The root OpenAPI document was only a short stub, so the real specs had to be found as separate files. Tiered pricing appeared in both a tutorial shape and a schema shape, with band fields marked deprecated while still present. Included-volume behavior was ambiguous across a persistent volume, a zero-priced first tier, and a default included-volume field. Plan changes depended on a plan group and a version status transition that onboarding material did not spell out. None of this was confirmed on the live service.
