docs: document receipt delivery confirmation endpoint#542
Conversation
Add a new section to the transaction lifecycle guide explaining the
receipt delivery confirmation endpoint (POST /transactions/{transactionId}/confirm).
This endpoint was added in commit 1de75a3 and allows platforms to record
when they delivered a receipt to their customer, which may be required
for compliance purposes.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
Greptile SummaryAdds a "Receipt Delivery Confirmation" section to the Transaction Lifecycle guide documenting the
Confidence Score: 4/5Documentation-only change; safe to merge, though the code example and missing response/error details could leave developers without enough to self-serve. The change is purely additive documentation with no logic or schema impact. The code block is not a runnable command, the response is described only in prose, and there is no error-handling guidance — gaps that contradict the team's own style guide but don't block correctness. mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx — the new section's code example and response documentation.
|
| Filename | Overview |
|---|---|
| mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx | Adds 'Receipt Delivery Confirmation' section; code block mixes HTTP notation with JSON body in a single bash block (not a runnable command), and the response description is prose-only with no concrete JSON example or error-handling guidance. |
Sequence Diagram
sequenceDiagram
participant Platform
participant GridAPI as Grid API
Platform->>GridAPI: "POST /transactions/{transactionId}/confirm"
Note right of GridAPI: body: {receiptDeliveryConfirmedAt}
GridAPI-->>Platform: 200 OK – updated transaction
Note right of GridAPI: receiptDeliveryConfirmedAt populated
Note over Platform,GridAPI: If receiptDeliveryConfirmedAt is omitted,
Note over Platform,GridAPI: Grid records the current server time
Platform->>GridAPI: "POST /transactions/{transactionId}/confirm (no body field)"
GridAPI-->>Platform: "200 OK – receiptDeliveryConfirmedAt = server time"
Prompt To Fix All With AI
Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.
---
### Issue 1 of 2
mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx:364-372
The code block embeds the JSON request body inside a `bash` block with a bare HTTP method line, which is not a runnable command. The Mintlify style guide (`CLAUDE.md`) requires complete, runnable examples that users can copy and execute. Splitting the request and response into proper blocks — or using a `curl` form — keeps this consistent with the guide's standard and makes it clear to the reader that the JSON is a request body, not bash syntax.
```suggestion
```bash
curl -X POST "https://api.example.com/transactions/{transactionId}/confirm" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{"receiptDeliveryConfirmedAt": "2025-08-15T14:31:00Z"}'
```
**Response:** Returns the updated transaction with `receiptDeliveryConfirmedAt` populated:
```json
{
"id": "Transaction:abc123",
"status": "COMPLETED",
"receiptDeliveryConfirmedAt": "2025-08-15T14:31:00Z"
}
```
```
### Issue 2 of 2
mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx:372-374
**Missing idempotency / error behavior documentation**
The section documents the happy path and the "omit the field" shortcut, but skips documenting what happens when the call is made for a transaction that doesn't exist, is not yet `COMPLETED`, or belongs to a different customer. The `AGENTS.md` style guide calls for "troubleshooting for likely failure points" and documenting error HTTP status codes. A developer who receives a 404 or 422 on this endpoint will have nowhere to look in the guide.
Reviews (1): Last reviewed commit: "docs: document receipt delivery confirma..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| ```bash | ||
| POST /transactions/{transactionId}/confirm | ||
|
|
||
| { | ||
| "receiptDeliveryConfirmedAt": "2025-08-15T14:31:00Z" | ||
| } | ||
| ``` | ||
|
|
||
| **Response:** Returns the updated transaction with `receiptDeliveryConfirmedAt` populated. |
There was a problem hiding this comment.
bash block with a bare HTTP method line, which is not a runnable command. The Mintlify style guide (CLAUDE.md) requires complete, runnable examples that users can copy and execute. Splitting the request and response into proper blocks — or using a curl form — keeps this consistent with the guide's standard and makes it clear to the reader that the JSON is a request body, not bash syntax.
| ```bash | |
| POST /transactions/{transactionId}/confirm | |
| { | |
| "receiptDeliveryConfirmedAt": "2025-08-15T14:31:00Z" | |
| } | |
| ``` | |
| **Response:** Returns the updated transaction with `receiptDeliveryConfirmedAt` populated. | |
| ```bash | |
| curl -X POST "https://api.example.com/transactions/{transactionId}/confirm" \ | |
| -H "Content-Type: application/json" \ | |
| -H "Authorization: Bearer YOUR_API_KEY" \ | |
| -d '{"receiptDeliveryConfirmedAt": "2025-08-15T14:31:00Z"}' |
Response: Returns the updated transaction with receiptDeliveryConfirmedAt populated:
{
"id": "Transaction:abc123",
"status": "COMPLETED",
"receiptDeliveryConfirmedAt": "2025-08-15T14:31:00Z"
}
**Context Used:** mintlify/CLAUDE.md ([source](https://app.greptile.com/lightspark/github/lightsparkdev/grid-api/-/custom-context?memory=8705e0ee-b98a-4325-9b4d-e1f5638b408a))
<details><summary>Prompt To Fix With AI</summary>
`````markdown
This is a comment left during a code review.
Path: mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx
Line: 364-372
Comment:
The code block embeds the JSON request body inside a `bash` block with a bare HTTP method line, which is not a runnable command. The Mintlify style guide (`CLAUDE.md`) requires complete, runnable examples that users can copy and execute. Splitting the request and response into proper blocks — or using a `curl` form — keeps this consistent with the guide's standard and makes it clear to the reader that the JSON is a request body, not bash syntax.
```suggestion
```bash
curl -X POST "https://api.example.com/transactions/{transactionId}/confirm" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{"receiptDeliveryConfirmedAt": "2025-08-15T14:31:00Z"}'
Response: Returns the updated transaction with receiptDeliveryConfirmedAt populated:
{
"id": "Transaction:abc123",
"status": "COMPLETED",
"receiptDeliveryConfirmedAt": "2025-08-15T14:31:00Z"
}
**Context Used:** mintlify/CLAUDE.md ([source](https://app.greptile.com/lightspark/github/lightsparkdev/grid-api/-/custom-context?memory=8705e0ee-b98a-4325-9b4d-e1f5638b408a))
How can I resolve this? If you propose a fix, please make it concise.
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!
| **Response:** Returns the updated transaction with `receiptDeliveryConfirmedAt` populated. | ||
|
|
||
| If you omit `receiptDeliveryConfirmedAt` from the request body, Grid uses the current server time. Calling this endpoint again updates the stored confirmation time. |
There was a problem hiding this comment.
The section documents the happy path and the "omit the field" shortcut, but skips documenting what happens when the call is made for a transaction that doesn't exist, is not yet COMPLETED, or belongs to a different customer. The AGENTS.md style guide calls for "troubleshooting for likely failure points" and documenting error HTTP status codes. A developer who receives a 404 or 422 on this endpoint will have nowhere to look in the guide.
Context Used: mintlify/AGENTS.md (source)
Prompt To Fix With AI
This is a comment left during a code review.
Path: mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx
Line: 372-374
Comment:
**Missing idempotency / error behavior documentation**
The section documents the happy path and the "omit the field" shortcut, but skips documenting what happens when the call is made for a transaction that doesn't exist, is not yet `COMPLETED`, or belongs to a different customer. The `AGENTS.md` style guide calls for "troubleshooting for likely failure points" and documenting error HTTP status codes. A developer who receives a 404 or 422 on this endpoint will have nowhere to look in the guide.
**Context Used:** mintlify/AGENTS.md ([source](https://app.greptile.com/lightspark/github/lightsparkdev/grid-api/-/custom-context?memory=51934046-75fb-42d3-9870-f42d61cb60e3))
How can I resolve this? If you propose a fix, please make it concise.
Summary
POST /transactions/{transactionId}/confirmendpoint to the Transaction Lifecycle guideChanges
Documentation (Mintlify)
platform-overview/core-concepts/transaction-lifecycle.mdxReview Checklist
Reviewed the following areas for sync with commit 1de75a3:
🤖 Generated with Claude Code