Lithic docs
lithicapp.io

Abrechnung und Rechnungen

Abonnement und Rechnungsdaten des Workspace sowie die Rechnungen, die diese Instanz im eigenen Nummernkreis ausstellt — dazu der Rückruf des Zahlungsdienstleisters.

8 Operationen. Jeder Pfad ist relativ zum Ursprung der Instanz; jeder Antwortkörper ist JSON, sofern nicht anders vermerkt. Die Endpunktbeschreibungen unten stammen unverändert aus der Routentabelle des Servers und bleiben englisch. Authentifizierung, Fehler und seitenweise Abfrage stehen unter API.

POST /api/v1/billing/webhook

Payment-provider callback. Authenticated by signature over the raw body, not by a session, and idempotent by provider event id — the same event WILL arrive twice.

receiveBillingWebhook · token scope: session only

Response 200 — application/json

  • received · true — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required
    • reason · string — length 1–64

GET /api/v1/workspaces/{workspaceId}/billing/subscription

The workspace’s subscription as the payment provider last reported it. Never contains a card, a provider credential, or a provider object.

getBillingSubscription · token scope: session only

Path parameters

  • workspaceId · string (uuid) — required

Response 200 — application/json

  • workspaceId · string (uuid) — required
  • status · "none" | "incomplete" | "trialing" | "active" | "past_due" | "canceled" — required
  • planId · "free" | "pro" | "business" | "enterprise" | null — required
  • currentPeriodStart · string (date-time) | null — required
  • currentPeriodEnd · string (date-time) | null — required
  • cancelAtPeriodEnd · boolean — required
  • seats · integer | null — required The number of seats the payment provider is billing. NOT the workspace’s current member count: the quantity is fixed when the subscription is bought and nothing on this instance changes it, so the two diverge as soon as a member joins or leaves. Null when there is no subscription, and for one bought before this was recorded.
  • updatedAt · string (date-time) — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required
    • reason · string — length 1–64

GET /api/v1/workspaces/{workspaceId}/billing/customer

The billing details invoices are addressed to, plus the VAT treatment an invoice issued now would carry.

getBillingCustomer · token scope: session only

Path parameters

  • workspaceId · string (uuid) — required

Response 200 — application/json

  • workspaceId · string (uuid) — required
  • party · object — required
    • name · string — required, length 0–200
    • addressLines · string[] — required, 0–4 items
    • postalCode · string — required, length 0–20
    • city · string — required, length 0–120
    • countryCode · string | "" — required
    • vatId · string | null — required
    • email · string (email) | null — required
  • vatIdStatus · "absent" | "unchecked" | "valid" | "invalid" — required
  • vatIdCheckedAt · string (date-time) | null — required
  • taxTreatment · "domestic" | "eu_reverse_charge" | "eu_oss" | "non_eu" | "exempt" — required
  • updatedAt · string (date-time) — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required
    • reason · string — length 1–64

PUT /api/v1/workspaces/{workspaceId}/billing/customer

Replace the billing details. Changing the VAT ID marks it unchecked again — an unchecked number never buys reverse charge. Issued invoices keep the copy they were issued with.

updateBillingCustomer · token scope: session only

Path parameters

  • workspaceId · string (uuid) — required

Request body — application/json, required

  • name · string — required, length 1–200
  • addressLines · string[] — 0–4 items, default []
  • postalCode · string — length 0–20, default ""
  • city · string — length 0–120, default ""
  • countryCode · string — required
  • email · string (email) | null — default null
  • vatId · string | null — default null

Response 200 — application/json

  • workspaceId · string (uuid) — required
  • party · object — required
    • name · string — required, length 0–200
    • addressLines · string[] — required, 0–4 items
    • postalCode · string — required, length 0–20
    • city · string — required, length 0–120
    • countryCode · string | "" — required
    • vatId · string | null — required
    • email · string (email) | null — required
  • vatIdStatus · "absent" | "unchecked" | "valid" | "invalid" — required
  • vatIdCheckedAt · string (date-time) | null — required
  • taxTreatment · "domestic" | "eu_reverse_charge" | "eu_oss" | "non_eu" | "exempt" — required
  • updatedAt · string (date-time) — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required
    • reason · string — length 1–64

GET /api/v1/workspaces/{workspaceId}/billing/invoices

The workspace’s invoices and credit notes, newest first. Drafts are included and are the ones without a number.

listInvoices · token scope: session only

Path parameters

  • workspaceId · string (uuid) — required

Query parameters

  • cursor · string — length 1–∞
  • limit · integer — 1–100

Response 200 — application/json

  • items · object[] — required
    • id · string (uuid) — required
    • workspaceId · string (uuid) — required
    • type · "invoice" | "credit_note" — required
    • status · "draft" | "issued" | "void" — required
    • number · string | null — required
    • issuedAt · string (date-time) | null — required
    • currency · string — required
    • seller · object — required
      • name · string — required, length 1–200
      • addressLines · string[] — required, 0–4 items
      • postalCode · string — required, length 0–20
      • city · string — required, length 0–120
      • countryCode · string — required
      • vatId · string | null — required
      • email · string (email) | null — required
      • taxNumber · string | null — required, default null
    • buyer · object — required
      • name · string — required, length 1–200
      • addressLines · string[] — required, 0–4 items
      • postalCode · string — required, length 0–20
      • city · string — required, length 0–120
      • countryCode · string — required
      • vatId · string | null — required
      • email · string (email) | null — required
    • lines · object[] — required
      • description · string — required, length 1–500
      • quantity · integer — required, -9007199254740991–9007199254740991
      • unitNetMinor · integer — required, -9007199254740991–9007199254740991
      • netMinor · integer — required, -9007199254740991–9007199254740991
      • taxRateBp · integer — required, 0–10000
      • taxMinor · integer — required, -9007199254740991–9007199254740991
      • periodStart · string (date-time) | null — required
      • periodEnd · string (date-time) | null — required
    • netMinor · integer — required, -9007199254740991–9007199254740991
    • taxMinor · integer — required, -9007199254740991–9007199254740991
    • grossMinor · integer — required, -9007199254740991–9007199254740991
    • taxTreatment · "domestic" | "eu_reverse_charge" | "eu_oss" | "non_eu" | "exempt" — required
    • taxCountry · string — required
    • taxNote · string | null — required
    • periodStart · string (date-time) | null — required
    • periodEnd · string (date-time) | null — required
    • paidAt · string (date-time) | null — required
    • cancelsInvoiceId · string (uuid) | null — required
    • canceledByInvoiceId · string (uuid) | null — required
    • providerInvoiceId · string | null — required
    • createdAt · string (date-time) — required
  • nextCursor · string | null — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required
    • reason · string — length 1–64

GET /api/v1/workspaces/{workspaceId}/billing/invoices/{invoiceId}

One invoice, complete: parties, lines, net/VAT/gross, period and VAT treatment. Enough to render the document without asking the payment provider anything.

getInvoice · token scope: session only

Path parameters

  • workspaceId · string (uuid) — required
  • invoiceId · string (uuid) — required

Response 200 — application/json

  • id · string (uuid) — required
  • workspaceId · string (uuid) — required
  • type · "invoice" | "credit_note" — required
  • status · "draft" | "issued" | "void" — required
  • number · string | null — required
  • issuedAt · string (date-time) | null — required
  • currency · string — required
  • seller · object — required
    • name · string — required, length 1–200
    • addressLines · string[] — required, 0–4 items
    • postalCode · string — required, length 0–20
    • city · string — required, length 0–120
    • countryCode · string — required
    • vatId · string | null — required
    • email · string (email) | null — required
    • taxNumber · string | null — required, default null
  • buyer · object — required
    • name · string — required, length 1–200
    • addressLines · string[] — required, 0–4 items
    • postalCode · string — required, length 0–20
    • city · string — required, length 0–120
    • countryCode · string — required
    • vatId · string | null — required
    • email · string (email) | null — required
  • lines · object[] — required
    • description · string — required, length 1–500
    • quantity · integer — required, -9007199254740991–9007199254740991
    • unitNetMinor · integer — required, -9007199254740991–9007199254740991
    • netMinor · integer — required, -9007199254740991–9007199254740991
    • taxRateBp · integer — required, 0–10000
    • taxMinor · integer — required, -9007199254740991–9007199254740991
    • periodStart · string (date-time) | null — required
    • periodEnd · string (date-time) | null — required
  • netMinor · integer — required, -9007199254740991–9007199254740991
  • taxMinor · integer — required, -9007199254740991–9007199254740991
  • grossMinor · integer — required, -9007199254740991–9007199254740991
  • taxTreatment · "domestic" | "eu_reverse_charge" | "eu_oss" | "non_eu" | "exempt" — required
  • taxCountry · string — required
  • taxNote · string | null — required
  • periodStart · string (date-time) | null — required
  • periodEnd · string (date-time) | null — required
  • paidAt · string (date-time) | null — required
  • cancelsInvoiceId · string (uuid) | null — required
  • canceledByInvoiceId · string (uuid) | null — required
  • providerInvoiceId · string | null — required
  • createdAt · string (date-time) — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required
    • reason · string — length 1–64

GET /api/v1/workspaces/{workspaceId}/billing/invoices/{invoiceId}/document

The issued invoice rendered as a self-contained HTML document (print to PDF). Drafts have no document — an unnumbered invoice must not be printable.

getInvoiceDocument · token scope: session only

Path parameters

  • workspaceId · string (uuid) — required
  • invoiceId · string (uuid) — required

Response 200 — application/json

  • invoiceId · string (uuid) — required
  • number · string — required
  • format · "html" — required
  • html · string — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required
    • reason · string — length 1–64

POST /api/v1/workspaces/{workspaceId}/billing/checkout

Begin a subscription on the payment provider’s hosted page. Answers a short-lived provider URL; card details are only ever entered there, never here. Refused (409) while the workspace already has a subscription the provider is still holding — including one whose first payment has been started and not completed — and while its billing details are incomplete: a name, a country and an email address, because a plan change is not a second subscription and a payment whose invoice can never be issued or delivered is worse than no payment.

startBillingCheckout · token scope: session only

Path parameters

  • workspaceId · string (uuid) — required

Request body — application/json, required

  • planId · "pro" | "business" | "free" | "team" — required The plan to buy. team is the deprecated spelling of pro and is resolved to it. free is accepted only so a client written against the older published enum gets an explanation instead of a crash: the route always refuses it with 400, because moving to free is a cancellation and this instance has no self-service route for one. enterprise and self_hosted are not accepted at all — an operator assigns that plan.
  • returnPath · string — length 0–512, default "/" Where the payment provider sends the browser back to, as a path on this instance — the host is chosen by the server from the operator’s allowlist and cannot be set here. It must be a path the app serving that origin actually renders, and only one of this instance’s products has a billing screen today (/settings/billing): a checkout started from another product’s origin comes back to a route that app does not serve yet. The payment, the entitlement and the invoice are unaffected — only the last page is.

Response 200 — application/json

  • url · string (uri) — required
  • expiresAt · string (date-time) — required

Response default — application/json

  • error · object — required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
    • message · string — required
    • reason · string — length 1–64