Billing
Read one invoice or receipt
One document with its lines, totals, who it is billed to, the issuer, and the card as a brand and last four digits.
GET
/user/billing/documents/{id}TL;DR
| Question | Answer |
|---|---|
| What does it do? | Read one invoice or receipt. |
| What does it take? | id in the path. |
| What does it return? | Status 200 with a body of type BillingDocumentDetail. |
| What can go wrong? | 400 the id is not shaped like an invoice id; 401 not signed in; 404 no such document for this account; 429 too many requests; 502 stripe could not complete the request; 503 billing is not set up on this server. Every failure uses the one error envelope. |
What it does
One document with its lines, totals, who it is billed to, the issuer, and the card as a brand and last four digits. A document that does not exist, is another account's, or is not Plotwork's is the same 404.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The document id, as the list gave it. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The document. | BillingDocumentDetail |
| 400 | The id is not shaped like an invoice id. | ErrorResponse |
| 401 | Not signed in. | ErrorResponse |
| 404 | No such document for this account. | ErrorResponse |
| 429 | Too many requests. | ErrorResponse |
| 502 | Stripe could not complete the request. | ErrorResponse |
| 503 | Billing is not set up on this server. | ErrorResponse |
Response body
A 200 answer has the type BillingDocumentDetail.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The id to ask for the document and its PDF with. |
kind | "invoice" | "receipt" | yes | A receipt is an invoice that has been paid; anything else is an invoice. |
number | string | yes | The number printed on the document, which an accounts department quotes back. |
description | string | yes | What it was for, such as the plan. Empty when Stripe names nothing. |
currency | string | yes | The three-letter currency, in capitals. at least 3 characters; at most 3 characters. |
totalCents | integer | yes | The total in whole cents (the currency's minor unit). |
status | string | yes | The invoice's own word: paid, open, void, or uncollectible. A draft is never listed. |
issuedAt | integer | yes | When it was issued, in milliseconds since the epoch. |
paidAt | integer | null | yes | When it was paid, in milliseconds since the epoch, or null while it is not. |
downloadable | boolean | yes | False when there is no PDF to fetch, so the PDF route would answer 404. |
lines | DocumentLine[] | yes | |
lines[].description | string | yes | |
lines[].quantity | integer | yes | minimum 1. |
lines[].amountCents | integer | yes | |
lines[].periodStart | integer | null | yes | The start of the service period, in milliseconds since the epoch, or null. |
lines[].periodEnd | integer | null | yes | The end of the service period, in milliseconds since the epoch, or null. |
subtotalCents | integer | null | yes | |
taxCents | integer | null | yes | The tax, or null when Stripe names none. |
amountPaidCents | integer | null | yes | |
billedTo | object | yes | |
billedTo.name | string | null | yes | |
billedTo.email | string | null | yes | |
issuer | object | null | yes | The Stripe account's business name and its tax numbers, from the invoice. There is no address: Stripe does not put one on an invoice. |
issuer.name | string | yes | |
issuer.lines | string[] | yes | |
paidWith | object | null | yes | The card the payment was taken from: its brand and last four digits, and nothing more of it. Null when it was not paid by card. |
paidWith.brand | string | yes | |
paidWith.last4 | string | yes | pattern ^\d{4}$. |
See also
| Doc | Why |
|---|---|
| API reference | Every endpoint, and the error envelope |
| Schemas | Every request and response type |
| Tool reference | The operations as callable tools |