Sync an invoice with its provider
Reads an invoice from its payment provider now and applies what the provider says: its finalization, payment, write-off or void. Refused for an invoice not in a provider (409 SyncInvoice.NotPushed). 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
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
application/problem+json
application/problem+json
curl -X POST "https://app.kaiten.sh/api/invoices/string/sync"{
"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"
}{
"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"
}Retry pushing an invoice to its provider
Puts a DRAFT or PUSH_FAILED invoice of a payment provider back in the push queue now, which resumes the push where its last attempt stopped. A draft waiting for finalization in its provider is finalized at once. Refused for a held invoice (409 RetryInvoicePush.Held) and for any other (409 RetryInvoicePush.InvalidStatus). Requires billing to be enabled for the organization.
Void an invoice
Voids an invoice not yet settled -- a DRAFT, held or not, a MANUAL one, or one a payment provider issued -- which frees its boundary for a recompose. A provider's invoice is voided there first, and here only once the provider confirms (503 VoidInvoice.ProviderUnavailable leaves it unchanged); one the provider reports paid is refused. A paid or written-off invoice cannot be voided. A handoff still pending stays so, and its consumer sees the VOID. Voiding a VOID invoice again answers it unchanged. Requires billing to be enabled for the organization.