Claim invoices from the handoff queue
Leases the oldest invoices waiting for the organization's accounting system, under one lease. Two consumers claiming at once get different invoices. An invoice not acknowledged before its lease expires is claimed again: the queue delivers at least once, so a consumer deduplicates on the invoice id. A claim is not idempotent: a lost response leaves its invoices leased until leasedUntil. Requires billing to be enabled for the organization.
Authorization
bearerAuth write: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: write:billing
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
curl -X POST "https://app.kaiten.sh/api/billing/handoff/claim" \ -H "Content-Type: application/json" \ -d '{}'{
"invoices": [
{
"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"
}
],
"leaseId": "string",
"leasedUntil": "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"
}List the handoff queue
The invoices waiting for the organization's accounting system (PENDING), or already acknowledged by it, oldest issue first. Reading never leases: claim to take invoices. Requires billing to be enabled for the organization.
Acknowledge a handed-off invoice
Records that the organization's accounting system booked an invoice from the handoff queue. Safe to repeat: the same acknowledgement again, or one that adds a reference the invoice did not have, answers 200. Another reference than the one it was acknowledged under is refused (AckHandoff.ReferenceMismatch), which a consumer can take as already handed off. Requires billing to be enabled for the organization.