Describe platformCardId as caller-suppliable with a system-generated fallback by AaryamanBhute · Pull Request #1023 · lightsparkdev/grid-api

AaryamanBhute · 2026-09-17T20:32:47Z

Summary

CardCreateRequest.platformCardId was described as "Always generated by the server; any value supplied in the request is ignored." This PR replaces that with the wording already used for the equivalent field on CustomerCreateRequest:

Platform-specific card identifier. If not provided, one will be generated by the system.

Card.platformCardId drops its "generated by the server" qualifier so the response description reads like every other platform-id field on a resource.

The schema states intent; the guides state today's behavior

Card issuance does not yet honor a caller-supplied platformCardId — it assigns its own value and returns that on the created Card. Honoring a supplied value is a separate change.

The schema description is deliberately forward-looking, matching the contract customers have been given. To keep that from misleading anyone in the meantime, the two cards guides say the current behavior outright rather than implying a supplied value sticks:

Issuing guide: "Grid does not yet honor a value you supply here — issuance always assigns its own. Read the identifier back from the returned Card and store that."
Quickstart: "Grid assigns platformCardId itself today, so read the identifier back from the returned Card rather than relying on a value you supplied."

That split is the point of the PR: publish the intended contract on the schema, without letting a caller store a value they cannot later filter or retrieve by. Reverting the schema line is a one-line change if the preference is to wait for the implementation.

Changes: 6 files

openapi/components/schemas/cards/CardCreateRequest.yaml — new platformCardId description
openapi/components/schemas/cards/Card.yaml — response description drops "generated by the server"
mintlify/snippets/cards/issuing-cards.mdx — request-field table row
mintlify/snippets/cards/quickstart.mdx — issuance walkthrough sentence
openapi.yaml, mintlify/openapi.yaml — regenerated bundles (make build)

Test plan

Docs-only repo, no application code.

make build — bundles regenerated; the bundle diff is exactly the two description lines
make lint — exit 0, 0 errors, warning/info counts unchanged from baseline
Detect breaking changes CI check passes
Grepped the repo for the old phrasings (any value supplied in the request is ignored, Ignored if supplied) — no remaining occurrences in specs, snippets, SDKs, or samples

lightspark-bot · 2026-09-17T20:33:08Z

Describe platformCardId as caller-suppliable with a system-generated fallback #1023 👈 (View in Graphite)
main

This stack of pull requests is managed by Graphite. Learn more about stacking.

vercel · 2026-09-17T20:33:15Z

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments

Project	Deployment	Actions	Updated
grid-cards-demo	Ignored	Preview	Sep 17, 2026 8:38pm UTC
grid-flow-builder	Ignored	Preview	Sep 17, 2026 8:38pm UTC
grid-wallet-demo	Ignored	Preview	Sep 17, 2026 8:38pm UTC

github-actions · 2026-09-17T20:33:28Z

✱ Stainless preview builds for grid

This PR will update the grid SDKs with the following commit messages.

cli

docs(api): clarify platform-card-id usage in cards issue method

go

feat(api): allow custom platformCardId in card creation

kotlin

docs(types): update platform_card_id description in cards models

openapi

docs(api): update platformCardId field documentation in Card schemas

php

docs(api): update platformCardID documentation in cards

python

feat(api): allow user-provided platform_card_id in cards issue method

ruby

docs(api): update platform_card_id documentation in card models and resource

typescript

docs(api): update platformCardId parameter description in cards issue method

Edit this comment to update them. They will appear in their respective SDK's changelogs.

✅ grid-typescript studio · code · diff

Your SDK build had at least one "error" diagnostic, but this did not represent a regression.
generate ❗ → build ⏭️ → lint ⏭️ → test ⏭️

✅ grid-openapi studio · code · diff

Your SDK build had at least one "error" diagnostic, but this did not represent a regression.
generate ❗

✅ grid-kotlin studio · code · diff

Your SDK build had at least one "error" diagnostic, but this did not represent a regression.
generate ❗ → build ⏭️ (prev: build ✅) → lint ⏭️ (prev: lint ✅) → test ⏭️ (prev: test ❗)

✅ grid-ruby studio · code · diff

Your SDK build had at least one "error" diagnostic, but this did not represent a regression.
generate ❗ → build ⏭️ → lint ⏭️ → test ⏭️

✅ grid-go studio · code · diff

Your SDK build had at least one "error" diagnostic, but this did not represent a regression.
generate ❗ → build ⏭️ → lint ⏭️ → test ⏭️
go get github.com/stainless-sdks/grid-go@048ddc3fbd65b588d6c93ffeae56026f2bb38235

✅ grid-python studio · code · diff

Your SDK build had at least one "error" diagnostic, but this did not represent a regression.
generate ❗ → build ⏭️ → lint ⏭️ → test ⏭️

✅ grid-php studio · code · diff

Your SDK build had at least one "error" diagnostic, but this did not represent a regression.
generate ❗ → lint ⏭️ → test ⏭️

✅ grid-cli studio · code · diff

Your SDK build had at least one "error" diagnostic, but this did not represent a regression.
generate ❗ → build ⏭️ → lint ⏭️ → test ⏭️

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-09-17 20:42:38 UTC

ls-bolt · 2026-09-17T20:33:38Z

⚡ Review ledger

Round 1

Greptile P1 (issuing-cards.mdx:24) — "Caller identifier is ignored": the row promised a supplied platformCardId becomes the caller's identifier for the card → PARTIALLY FIXED. The over-promise was mine, beyond what was asked for, so the row now mirrors the schema line and adds the caveat: "Platform-specific card identifier. Generated by the system if you omit it. Always read the value back from the returned Card." The quickstart sentence got the same "read it back" caveat. The schema description itself stands as requested — it states the intended contract ahead of issuance honoring a caller-supplied value, which is called out in the PR description so the merge is a deliberate call.

Round 2

Greptile P1 (issuing-cards.mdx:24) — "Unsupported caller-supplied identifier": the guide presented a supplied platformCardId as usable, but issuance ignores it → FIXED. Both guides now state today's behavior outright instead of implying a supplied value sticks: issuing-cards.mdx:24 reads "Grid does not yet honor a value you supply here — issuance always assigns its own. Read the identifier back from the returned Card and store that," and quickstart.mdx:49 says "Grid assigns platformCardId itself today, so read the identifier back from the returned Card rather than relying on a value you supplied." The schema description stays forward-looking as requested; the PR description now spells out that split. (build + lint re-run clean, exit 0)

ls-bolt · 2026-09-17T20:33:45Z

⚡ Revision log — updated in place, latest first.

Revision 2

Both cards guides now say plainly that Grid does not yet honor a caller-supplied platformCardId and tell you to read the identifier back from the returned Card, per @greptile-apps's P1. The previous round's wording still implied a supplied value would stick.
PR description rewritten to explain the deliberate split: forward-looking schema description, current-behavior guides.
No bundle change (MDX only); make build and make lint re-run clean (exit 0, 0 errors). Detect breaking changes passing.

Earlier revisions (1)

Revision 1

Tightened the issuing-cards.mdx request-field row to mirror the schema description and tell callers to read platformCardId back from the returned Card, per @greptile-apps's P1. The earlier "your own identifier for the card" phrasing over-promised beyond the requested change.
Same "read it back" caveat added to the quickstart issuance walkthrough.
No bundle change (MDX only); make build and make lint re-run clean (exit 0, 0 errors).

ls-bolt · 2026-09-17T20:33:49Z

@greptile review

greptile-apps · 2026-09-17T20:34:19Z

The customer-facing guides still overstate the current behavior. mintlify/snippets/cards/issuing-cards.mdx:24 calls platformCardId “Your own identifier for the card,” and mintlify/snippets/cards/quickstart.mdx:50 says the system generates it only when omitted. Per the PR description, issuance currently ignores a caller-supplied value and returns a different system-generated value, so these statements are false until the separate implementation change lands. Either keep the guides aligned with today’s behavior, or explicitly say caller-supplied IDs are documented intent but not yet honored; changing only the OpenAPI contract is otherwise reasonable if that forward-looking behavior is intentional.

mintlify · 2026-09-17T20:35:20Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
Grid	🟢 Ready	View Preview	Sep 17, 2026, 8:40 PM

greptile-apps · 2026-09-17T20:36:44Z

Confidence Score: 5/5

The PR appears safe to merge because the guide changes resolve the previously reported caller-confusion risk and no new actionable failures remain.

Summary

This PR updates the public card schema to describe platformCardId as caller-suppliable with a generated fallback, while the cards guides explicitly document that current issuance still replaces supplied values.

Clarifies the CardCreateRequest.platformCardId and Card.platformCardId descriptions.
Warns callers to read and persist the identifier returned by card issuance.
Keeps both generated OpenAPI bundles synchronized with the modular schema source.

_{Reviews (2) · Last reviewed commit: "Describe platformCardId as caller-suppli..."}

…fallback The create-card description said the value was always server-generated and any supplied value ignored. Match the platformCustomerId wording on CustomerCreateRequest instead: optional, system-generated when omitted. Co-Authored-By: aaryamanbhute <aaryamanbhute@users.noreply.github.com>

ls-bolt · 2026-09-17T20:39:15Z

@greptile review

greptile-apps · 2026-09-17T20:39:44Z

The current behavior is now stated clearly in both guides (mintlify/snippets/cards/issuing-cards.mdx:24 and mintlify/snippets/cards/quickstart.mdx:49): supplied values are not honored today, and callers must read the returned identifier. The forward-looking OpenAPI wording is explicitly intentional and documented in the PR description. I don’t see any remaining actionable issues.

ls-bolt Bot added the bolt label Sep 17, 2026

ls-bolt Bot mentioned this pull request Sep 17, 2026

Describe platformCardId as caller-suppliable with a system-generated fallback #1022

Closed

ls-bolt Bot force-pushed the 09-17-platform-card-id-optional-description branch from 50f3314 to 6731122 Compare September 17, 2026 20:33

AaryamanBhute marked this pull request as ready for review September 17, 2026 20:33

mintlify Bot deployed to staging - mintlify September 17, 2026 20:35 View deployment

greptile-apps Bot reviewed Sep 17, 2026

View reviewed changes

Comment thread mintlify/snippets/cards/issuing-cards.mdx Outdated

ls-bolt Bot force-pushed the 09-17-platform-card-id-optional-description branch from 6731122 to 0012344 Compare September 17, 2026 20:38

mintlify Bot deployed to staging - mintlify September 17, 2026 20:40 View deployment

Navigation Menu

Describe platformCardId as caller-suppliable with a system-generated fallback - #1023

Describe platformCardId as caller-suppliable with a system-generated fallback#1023
AaryamanBhute wants to merge 1 commit into
mainfrom
09-17-platform-card-id-optional-description

AaryamanBhute commented Sep 17, 2026 •

edited by ls-bolt Bot

Loading

Uh oh!

lightspark-bot commented Sep 17, 2026

Uh oh!

vercel Bot commented Sep 17, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Sep 17, 2026 •

edited

Loading

Uh oh!

ls-bolt Bot commented Sep 17, 2026 •

edited

Loading

Uh oh!

ls-bolt Bot commented Sep 17, 2026 •

edited

Loading

Revision 1

Uh oh!

ls-bolt Bot commented Sep 17, 2026

Uh oh!

greptile-apps Bot commented Sep 17, 2026

Uh oh!

mintlify Bot commented Sep 17, 2026 •

edited

Loading

Uh oh!

greptile-apps Bot commented Sep 17, 2026 •

edited

Loading

Uh oh!

Uh oh!

ls-bolt Bot commented Sep 17, 2026

Uh oh!

greptile-apps Bot commented Sep 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

AaryamanBhute commented Sep 17, 2026 • edited by ls-bolt Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

The schema states intent; the guides state today's behavior

Changes: 6 files

Test plan

Uh oh!

lightspark-bot commented Sep 17, 2026

Uh oh!

vercel Bot commented Sep 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Sep 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✱ Stainless preview builds for grid

Uh oh!

ls-bolt Bot commented Sep 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Round 1

Round 2

Uh oh!

ls-bolt Bot commented Sep 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Revision 2

Revision 1

Uh oh!

ls-bolt Bot commented Sep 17, 2026

Uh oh!

greptile-apps Bot commented Sep 17, 2026

Uh oh!

mintlify Bot commented Sep 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

greptile-apps Bot commented Sep 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Confidence Score: 5/5

Summary

Uh oh!

Uh oh!

ls-bolt Bot commented Sep 17, 2026

Uh oh!

greptile-apps Bot commented Sep 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

AaryamanBhute commented Sep 17, 2026 •

edited by ls-bolt Bot

Loading

vercel Bot commented Sep 17, 2026 •

edited

Loading

github-actions Bot commented Sep 17, 2026 •

edited

Loading

ls-bolt Bot commented Sep 17, 2026 •

edited

Loading

ls-bolt Bot commented Sep 17, 2026 •

edited

Loading

mintlify Bot commented Sep 17, 2026 •

edited

Loading

greptile-apps Bot commented Sep 17, 2026 •

edited

Loading