Describe platformCardId as caller-suppliable with a system-generated fallback by ls-bolt[bot] · Pull Request #1022 · lightsparkdev/grid-api

ls-bolt · 2026-09-17T20:28:09Z

This PR has been claimed. The active PR is now #1023.

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.

The two cards guides that carried the same "ignored if supplied" framing are updated to match, and Card.platformCardId drops its "generated by the server" qualifier so the response description reads like every other platform-id field on a resource.

Note for reviewers

This describes the intended contract for the field. Card issuance today still assigns its own value and returns that on the created Card, so a caller who supplies platformCardId cannot yet retrieve or filter by the value they chose — support for honoring a caller-supplied id is a separate change. Merging this ahead of that work is a deliberate choice to match the documented contract customers have been given; reverting to the previous text is a one-line change if the preference is to wait.

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
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

Requested by @AaryamanBhute

…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>

mintlify · 2026-09-17T20:28:11Z

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

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

vercel · 2026-09-17T20:28:14Z

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:28pm UTC
grid-flow-builder	Ignored	Preview	Sep 17, 2026 8:28pm UTC
grid-wallet-demo	Ignored	Preview	Sep 17, 2026 8:28pm UTC

lightspark-bot · 2026-09-17T20:28:37Z

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

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

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

@greptile review

github-actions · 2026-09-17T20:29:05Z

✱ Stainless preview builds for grid

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

cli

docs(api): clarify platform-card-id parameter description in card issue method

go

feat(api): allow user-provided platformCardId in card creation

kotlin

feat(api): allow platform_card_id parameter in card creation

openapi

docs(api): update platformCardId field description in card schemas

php

docs(api): update platformCardID documentation in cards

python

docs(api): clarify platform_card_id can be user-provided in cards

ruby

docs(api): clarify platform_card_id generation behavior in cards

typescript

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

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@b7b214c61ed6c98738207ed1e282bf284ee30c55

✅ 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:33:03 UTC

greptile-apps · 2026-09-17T20:31:22Z

Confidence Score: 4/5

This PR should not merge until the documentation matches current card-issuance behavior or the runtime begins honoring caller-supplied identifiers.

Findings

Caller identifier is ignored ▶

Fix with agent prompt

### Issue 1
mintlify/snippets/cards/issuing-cards.mdx:24
When a caller supplies `platformCardId`, this text promises that it becomes their identifier for the card. Card issuance currently ignores that value and returns a generated one, while the card-list API supports filtering by `platformCardId`. A caller following this guide can therefore fail to find or correlate the created card using the identifier they supplied. This violates the repository directive to prioritize accurate, usable documentation; the docs need to describe the current behavior until the API honors caller-supplied values.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Updates the card issuance contract and guides to describe platformCardId as caller-suppliable, with a system-generated fallback when omitted.

Revises the card creation schema and issuance guides.
Simplifies the identifier description on the returned Card.
Regenerates both published OpenAPI bundles.
Currently documents behavior that card issuance does not yet implement.

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

greptile-apps · 2026-09-17T20:31:25Z

 |-------|----------|-------|
 | `customerId` | Yes | The `Customer` that owns the card. Must be `kycStatus: APPROVED`. |
-| `platformCardId` | No | Ignored if supplied. The value on the returned `Card` is generated by the server. |
+| `platformCardId` | No | Your own identifier for the card. Generated by the system if you omit it. |


Caller identifier is ignored

When a caller supplies platformCardId, this text promises that it becomes their identifier for the card. Card issuance currently ignores that value and returns a generated one, while the card-list API supports filtering by platformCardId. A caller following this guide can therefore fail to find or correlate the created card using the identifier they supplied. This violates the repository directive to prioritize accurate, usable documentation; the docs need to describe the current behavior until the API honors caller-supplied values.

Context Used: mintlify/AGENTS.md (source)

Knowledge Base Used: Cards API

Prompt To Fix With AI

This is a comment left during a code review. Path: mintlify/snippets/cards/issuing-cards.mdx Line: 24 Comment: **Caller identifier is ignored** When a caller supplies `platformCardId`, this text promises that it becomes their identifier for the card. Card issuance currently ignores that value and returns a generated one, while the card-list API supports filtering by `platformCardId`. A caller following this guide can therefore fail to find or correlate the created card using the identifier they supplied. This violates the repository directive to prioritize accurate, usable documentation; the docs need to describe the current behavior until the API honors caller-supplied values. **Context Used:** mintlify/AGENTS.md ([source](https://github.com/lightsparkdev/grid-api/blob/main/mintlify/AGENTS.md)) **Knowledge Base Used:** [Cards API](https://app.greptile.com/lightspark/-/custom-context/knowledge-base/lightsparkdev/grid-api/-/docs/cards-api.md) --- For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

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

greptile-apps Bot reviewed Sep 17, 2026

View reviewed changes

AaryamanBhute closed this Sep 17, 2026

AaryamanBhute mentioned this pull request Sep 17, 2026

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

Open

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

Navigation Menu

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

Describe platformCardId as caller-suppliable with a system-generated fallback#1022
ls-bolt[bot] wants to merge 1 commit into
mainfrom
09-17-platform-card-id-optional-description

ls-bolt Bot commented Sep 17, 2026 •

edited

Loading

Uh oh!

mintlify Bot commented Sep 17, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Sep 17, 2026 •

edited

Loading

Uh oh!

lightspark-bot commented Sep 17, 2026

Uh oh!

ls-bolt Bot commented Sep 17, 2026

Uh oh!

github-actions Bot commented Sep 17, 2026 •

edited

Loading

Uh oh!

greptile-apps Bot commented Sep 17, 2026 •

edited

Loading

Uh oh!

greptile-apps Bot Sep 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

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

Uh oh!

Summary

Note for reviewers

Changes: 6 files

Test plan

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!

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

Uh oh!

Uh oh!

lightspark-bot commented Sep 17, 2026

Uh oh!

ls-bolt Bot commented Sep 17, 2026

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!

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: 4/5

Findings

Summary

Uh oh!

greptile-apps Bot Sep 17, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ls-bolt Bot commented Sep 17, 2026 •

edited

Loading

mintlify Bot commented Sep 17, 2026 •

edited

Loading

vercel Bot commented Sep 17, 2026 •

edited

Loading

github-actions Bot commented Sep 17, 2026 •

edited

Loading

greptile-apps Bot commented Sep 17, 2026 •

edited

Loading