Get an invoice
One invoice with its lines, the customer and instance as they were when it was composed, its hold and its handoff. Addressed by id at organization level: an invoice outlives its instance and customer. Requires billing to be enabled for the organization.
Authorization
bearerAuth read:billingA JWT verified by the proxy in front of this API, or a Kaiten access token (ksh_...) — send either as Authorization: Bearer <token>. The scopes listed on each operation are checked server-side against current stored user assignments or stored service-token permissions, never JWT claims; write:<module> implies read:<module>, and read:* / write:* are wildcards over every module. x-kaiten-scopes lists every scope such a token can carry, including those enforced by a service in front of this API rather than by one of its operations.
In: header
Scope: read:billing
Path Parameters
Invoice identifier
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
curl -X GET "https://app.kaiten.sh/api/invoices/string"{
"billingEmail": "string",
"boundaryAt": "2019-08-24T14:15:22Z",
"collectionMethod": "SEND_INVOICE",
"createdAt": "2019-08-24T14:15:22Z",
"currency": "EUR",
"customerName": "string",
"customerSlug": "string",
"daysUntilDue": 0,
"discountTotal": 0,
"dueAt": "2019-08-24T14:15:22Z",
"handoff": {
"acknowledgedAt": "2019-08-24T14:15:22Z",
"claimCount": 0,
"externalReference": "string",
"leaseId": "string",
"leasedUntil": "2019-08-24T14:15:22Z",
"status": "NOT_REQUIRED"
},
"handoffStatus": "NOT_REQUIRED",
"hold": {
"heldAt": "2019-08-24T14:15:22Z",
"releaseReason": "string",
"releasedAt": "2019-08-24T14:15:22Z",
"releasedBy": "string"
},
"holdDetail": {
"itemLimit": {
"items": 0,
"limit": 0,
"providerKind": "STRIPE"
},
"pairs": [
{
"counterReportSeq": 0,
"detail": "string",
"entitlementId": "string",
"expected": "string",
"firstSeq": 0,
"found": "string",
"instanceId": "string",
"invariant": "string",
"lastSeq": 0,
"reportSeq": 0
}
]
},
"holdReason": "LEDGER_SEQUENCE_GAP",
"id": "string",
"instanceName": "string",
"instanceSlug": "string",
"issuedAt": "2019-08-24T14:15:22Z",
"kind": "ACTIVATION",
"licenseId": "string",
"licenseSlug": "string",
"lines": [
{
"addonId": "string",
"addonPriceId": "string",
"amount": 2440,
"billingModel": "FLAT_FEE",
"billingTiming": "ADVANCE",
"capped": true,
"description": "3.05 × 8.00 EUR (per 10k tokens); 130,500 used; 30,500 above the applied limit (100,000)",
"discount": {
"allocations": [
{
"amount": 0,
"targetSeq": 0
}
],
"application": 0,
"applicationsMax": 0,
"appliesTo": "LICENSE_BASE",
"base": "string",
"currency": "string",
"discountType": "PERCENTAGE",
"discountValue": "string",
"targetSeqs": [
0
]
},
"entitlementId": "string",
"entitlementSlug": "string",
"id": "string",
"instanceAddonId": "string",
"instanceVoucherId": "string",
"label": "Tokens — overage",
"licensePriceId": "string",
"metering": {
"ledger": {
"firstSeq": 0,
"instanceId": "string",
"lastSeq": 0,
"rows": 0,
"sumDelta": "string",
"sumOverage": "string"
},
"measuredQuantity": "30500",
"negativeSegmentsFloored": 0,
"saleUnitFactor": "10000",
"windows": 1
},
"overage": {
"limits": [
{
"limitValue": "100000",
"overagePercent": 50,
"rows": 0
}
],
"overageMeasured": "30500",
"usageMeasured": "130500"
},
"provider": {
"amount": 0,
"couponIds": [
"string"
],
"externalLineId": "string"
},
"quantity": "3.05",
"seq": 0,
"serviceFrom": "2019-08-24T14:15:22Z",
"serviceTo": "2019-08-24T14:15:22Z",
"trueUp": {
"billedQuantity": 0,
"maxQuantity": 0
},
"type": "BASE",
"unitAmountDecimal": "800",
"voucherId": "string"
}
],
"overdue": true,
"paidAt": "2019-08-24T14:15:22Z",
"provider": {
"externalCustomerId": "string",
"externalInvoiceId": "string",
"hostedInvoiceUrl": "string",
"invoiceNumber": "string",
"invoicePdfUrl": "string",
"lastPaymentError": "string",
"lastPushError": "string",
"nextPushAt": "2019-08-24T14:15:22Z",
"pushAttempts": 0,
"pushedAt": "2019-08-24T14:15:22Z",
"reconciledAt": "2019-08-24T14:15:22Z",
"reconciliationDetail": {
"discounts": [
{
"couponId": "string",
"kaitenAmount": 0,
"lineId": "string",
"providerAmount": 0,
"seq": 0,
"targetSeq": 0
}
],
"dueDate": {
"kaitenDueAt": "2019-08-24T14:15:22Z",
"providerDueAt": "2019-08-24T14:15:22Z"
},
"extraDiscounts": [
{
"amount": 0,
"discountId": "string",
"externalLineId": "string"
}
],
"extraInProvider": [
"string"
],
"inclusiveTax": true,
"lines": [
{
"externalLineId": "string",
"kaitenAmount": 0,
"lineId": "string",
"providerAmount": 0,
"seq": 0
}
],
"missingInProvider": [
"string"
],
"totals": {
"kaitenTotal": 0,
"providerSubtotal": 0,
"providerTotalDiscount": 0,
"providerTotalExcludingTax": 0
},
"warnings": [
"string"
]
},
"reconciliationStatus": "MATCHED",
"status": "draft",
"syncedAt": "2019-08-24T14:15:22Z",
"totalExcludingTax": 0
},
"providerKind": "NOOP",
"replacedByInvoiceId": "string",
"replacesInvoiceId": "string",
"serviceFrom": "2019-08-24T14:15:22Z",
"serviceTo": "2019-08-24T14:15:22Z",
"status": "DRAFT",
"subtotal": 0,
"total": 0,
"uncollectibleAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"voidReason": "string",
"voidedAt": "2019-08-24T14:15:22Z"
}{
"code": "License.NotFound",
"detail": "license not found",
"errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
"errors": [
{
"location": "string",
"message": "string",
"value": null
}
],
"instance": "/api/licenses/enterprise",
"status": 404,
"title": "Not Found",
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}{
"code": "License.NotFound",
"detail": "license not found",
"errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
"errors": [
{
"location": "string",
"message": "string",
"value": null
}
],
"instance": "/api/licenses/enterprise",
"status": 404,
"title": "Not Found",
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}{
"code": "License.NotFound",
"detail": "license not found",
"errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
"errors": [
{
"location": "string",
"message": "string",
"value": null
}
],
"instance": "/api/licenses/enterprise",
"status": 404,
"title": "Not Found",
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}{
"code": "License.NotFound",
"detail": "license not found",
"errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
"errors": [
{
"location": "string",
"message": "string",
"value": null
}
],
"instance": "/api/licenses/enterprise",
"status": 404,
"title": "Not Found",
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}{
"code": "License.NotFound",
"detail": "license not found",
"errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
"errors": [
{
"location": "string",
"message": "string",
"value": null
}
],
"instance": "/api/licenses/enterprise",
"status": 404,
"title": "Not Found",
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}{
"code": "License.NotFound",
"detail": "license not found",
"errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
"errors": [
{
"location": "string",
"message": "string",
"value": null
}
],
"instance": "/api/licenses/enterprise",
"status": 404,
"title": "Not Found",
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}Export invoices
Streams the invoices the filters of listInvoices select, as CSV or NDJSON. Amounts are integer minor units with the currency's exponent beside them, so a spreadsheet never sees a float. The export carries billing e-mails: it is an authenticated read for the organization's accounting. Requires billing to be enabled for the organization.
List the usage reports behind an invoice line
The usage reports a USAGE or OVERAGE line was measured from: its pair's reports dated in its service period, in reportSeq order. Summed by reset window and floored at 0, they give the line's measured quantity. Addressed by invoice, it answers after the instance was deleted. Requires billing to be enabled for the organization.