docs(openapi): region and currencies resolve independently on customer create - #789
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
|
The latest updates on your projects. Learn more about Vercel for GitHub. 2 Skipped Deployments
|
✱ Stainless preview builds for gridThis PR will update the cli go kotlin openapi php python ruby typescript ✅ grid-ruby studio · code
|
3c78787 to
3b37ac8
Compare
…r create Create-customer required `region` and `currencies` to be sent together or not at all. lightsparkdev/webdev#31313 drops that rule: currencies pin the payment configuration on their own, and region is only a tiebreaker. - `region`: drop the both-or-neither requirement, the regulatory-jurisdiction claim, and "immutable after creation" — nothing persists the field. Described as what it is for: disambiguating a currency offered in more than one region. - `currencies`: drop "inferred from the customer's region" as the only fallback. - Add a create example with currencies and no region. The existing `individualCustomerInferred` example (region, no currencies) was rejected by the old rule, which is part of why the rule was wrong. Description- and example-only, so there is nothing for oasdiff to flag. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
3b37ac8 to
c64d14f
Compare
Greptile SummaryThis PR updates the customer-create contract so
Confidence Score: 4/5The PR appears safe to merge with the coordinated backend rollout, though the customer CLI help should be aligned with the new The source schema, example, and generated bundles are internally consistent; the remaining issue is non-blocking contradictory documentation in the CLI. Files Needing Attention: openapi/components/schemas/customers/CustomerCreateRequest.yaml and cli/src/commands/customers.ts
|
| Filename | Overview |
|---|---|
| openapi/components/schemas/customers/CustomerCreateRequest.yaml | Updates the two field descriptions correctly for the intended backend behavior, but exposes contradictory region semantics in the CLI help. |
| openapi/paths/customers/customers.yaml | Adds a well-formed currencies-without-region example demonstrating the newly supported request shape. |
| openapi.yaml | Root generated bundle consistently reflects the modular schema and example changes. |
| mintlify/openapi.yaml | Mintlify’s generated bundle consistently reflects the source OpenAPI changes. |
Prompt To Fix All With AI
### Issue 1
openapi/components/schemas/customers/CustomerCreateRequest.yaml:13-16
**Region semantics conflict with CLI**
The updated schema describes `region` solely as an optional configuration-selection tiebreaker, while the customer CLI still calls it immutable after creation. This gives users conflicting guidance about whether the value becomes durable customer state.
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.Reviews (1): Last reviewed commit: "docs(openapi): region and currencies res..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| description: >- | ||
| Country code (ISO 3166-1 alpha-2) representing the customer's regional identity. | ||
| This determines the regulatory jurisdiction and KYC requirements for the customer. | ||
| Required if the customer will use currencies with different KYC requirements across | ||
| regions. A customer with accounts in multiple regions should be registered as separate | ||
| customers. This field is immutable after creation. | ||
| Country code (ISO 3166-1 alpha-2) for the customer's region. Optional — send | ||
| it only when the same currency is offered in more than one of your regions, | ||
| to pick the one that applies to this customer. |
There was a problem hiding this comment.
The updated schema describes region solely as an optional configuration-selection tiebreaker, while the customer CLI still calls it immutable after creation. This gives users conflicting guidance about whether the value becomes durable customer state.
Knowledge Base Used:
Prompt To Fix With AI
This is a comment left during a code review.
Path: openapi/components/schemas/customers/CustomerCreateRequest.yaml
Line: 13-16
Comment:
**Region semantics conflict with CLI**
The updated schema describes `region` solely as an optional configuration-selection tiebreaker, while the customer CLI still calls it immutable after creation. This gives users conflicting guidance about whether the value becomes durable customer state.
**Knowledge Base Used:**
- [Customers and KYC](https://app.greptile.com/lightspark/-/custom-context/knowledge-base/lightsparkdev/grid-api/-/docs/customers-and-kyc.md)
- [OpenAPI Spec Core: Structure, Build, and Shared Schemas](https://app.greptile.com/lightspark/-/custom-context/knowledge-base/lightsparkdev/grid-api/-/docs/openapi-spec-core.md)
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
2 participants
Reason
Create-customer required
regionandcurrenciesto be sent together or not at all, but the spec never said so — it documented the two as independently conditional and promised currencies could be inferred from region. lightsparkdev/webdev#31313 removes the both-or-neither rule from the handler: currencies pin the payment configuration on their own, and region is only a tiebreaker. This brings the API surface in line.Overview
CustomerCreateRequest.yaml:region— drops the both-or-neither requirement, the "determines the regulatory jurisdiction and KYC requirements" claim, and "immutable after creation". Nothing persists the field. Now described by what it is actually for: optional, and only needed to say which region applies when the same currency is offered in more than one of yours.currencies— drops "currencies will be inferred from the customer's region" as the only fallback. Now: optional, send them if your platform supports more than one currency; some combinations require separate customers.Both are two plain sentences aimed at an integrator, rather than describing the resolution mechanism.
paths/customers/customers.yamlgains a create example with currencies and no region. Worth noting the existingindividualCustomerInferredexample (region, no currencies) was rejected by the old rule — the examples already assumed the behavior #31313 implements.Two related things deliberately not here:
regiontext describes the intended end state. Todayunique(platform_id, currency_code)means one currency cannot be served by two switches on a platform, so region currently narrows across different currencies' jurisdictions instead. #31313's docstring TODO is the re-key to(platform, currency, jurisdiction)that makes the described behavior literal.Customer.yamldocumentsregionandcurrencieson the customer response, but neither is ever populated. Removing them is an oasdiffresponse-property-removedERR, so it wants its own change.Test Plan
npm run lint:openapi— redocly lint clean, spectral clean at--fail-severity=error, bundles regenerated intoopenapi.yamlandmintlify/openapi.yaml.🤖 Generated with Claude Code