Skip to main content

​
Official TypeScript and Python SDKs

paywise now publishes official SDKs for the Case Management API and the Partner API: @paywise/sdk for TypeScript/JavaScript and paywise for Python. One client covers both APIs, with typed requests and responses, automatic pagination, retries that reuse the Idempotency-Key, and the X-On-Behalf-Of-Company header for Partner keys. The SDKs are in beta (0.x). See SDKs. No API change; existing integrations are not affected.

​
claim_type_code removed from mandate history

History entries returned by GET /v2/mandates/{id}/history/ no longer contain claim_type_code. The field carried an internal processing code of the status update, not a stable public value. Read the entry’s title and description for what happened, and the mandate’s current state for decisions. Action required if your integration reads claim_type_code from history entries: remove that access. legal_basis.claim_type_code on claims is not affected.

​
Mahnservice: invoice.reopened webhook event

A new Mahnservice webhook event, invoice.reopened, reports an invoice from a connected bookkeeping system that is open again after it was paid, cancelled, or written off, because the bookkeeping reversed the clearing (for example a returned direct debit). The invoice is open or overdue again with its current balance, and its dunning is paused with the new pause_reason value reopened until the client resumes it. The event uses the same data as the other invoice events: company_id, invoice_id, and invoice_url. Subscribe through POST /v2/webhooks/ or a Partner-owned subscription; see Invoice lifecycle. This is an additive change under the versioning policy: a subscription with "*" receives the event automatically, one with an explicit event list does not. Invoices submitted through the Mahnservice API are never reopened.

​
Claim lookup by reference

GET /v2/claims/ accepts two new filters, your_reference and document_reference. Both match the whole value exactly, ignoring case and surrounding whitespace, so document_reference=RE-1 does not return RE-10. Use them to resolve an invoice number from your accounting system to its claim, and from there to its order or mandate, in one call. An empty value is ignored like an absent filter. This is an additive change under the versioning policy: existing requests are unaffected.

​
Incremental sync pages by cursor

Every Case Management and Partner list that accepts updated_since now pages by an opaque cursor while that filter is set, instead of by offset. Results stay ordered by updated_at, then id; next carries the cursor, previous is null, and count covers the whole window. Rows changed less than 60 seconds ago are held back until they are settled. Offset paging over a changing order could skip a row: when a row you had already read changed before the next page, the row at the page boundary was never returned. With the cursor, one complete run sees every change since updated_since, so the overlap window the earlier guidance recommended is no longer needed. Action required if you build page URLs yourself: offset together with updated_since is now 400 validation_error with invalid_parameter on offset, and cursor without updated_since is rejected the same way. An altered cursor is 400 invalid_cursor. Integrations that follow the returned next URL, as documented, need no change. Lists without updated_since keep limit/offset pagination. See Pagination and synchronization for the checkpoint procedure.

​
Optional salutation for every person

person.salutation is optional for every natural person: consumer debtors, business debtors with a person identity, and legal representatives. Omit it, or send null or "" when it is unknown; mr, ms, and mx remain the supported values. Previously only consumer debtors could omit it. Order readiness no longer reports a missing salutation. This relaxes a validation rule, so existing requests are unaffected.

​
SDK-friendlier request and event schemas

Several OpenAPI components changed shape so that generated clients (TypeScript, Java, C#, Python) keep every field. The JSON on the wire is unchanged:
  • DebtorWriteRequest is a oneOf discriminated by acting_as, with the complete variants ConsumerDebtorWriteRequest and BusinessDebtorWriteRequest.
  • Document uploads publish one flat request model per operation that types both base64 and file, shared by the JSON and multipart bodies. Exactly one source is still required at runtime.
  • Legal representatives, message PATCH, and answers to requests to client publish one object whose “exactly one of” or “at least one of” rule is stated in the descriptions and enforced at runtime.
  • Each webhook event type has its own <Event>WebhookEvent component, and RequestToClientWebhookEventData is a single object with optional mandate_id, request_to_client_url, and order_id.
Regenerate your client to pick up the new model names. The legal-form catalog grows by 20 permanent codes. Both catalogs — GET /v2/legal-forms/ and GET /partner/v2/legal-forms/ — list them, and debtor and company legal_form fields accept them: Existing codes are unchanged. This is an additive change under the versioning policy: no action is required if your integration refreshes the catalog as recommended. Debtors and companies whose legal form previously had no code now return its code instead of null.

​
Initial release

This initial release establishes the current public contracts for all three paywise APIs. The published OpenAPI references, guides, and examples describe the initial release baseline.
  • Case Management API (/v2/): submit invoice, rental, and titled orders and manage collection cases, documents, payments, statements, and webhooks.
  • Partner API (/partner/v2/): onboard and manage client companies and users, then act for those companies through the Case Management API.
  • Mahnservice API (/mahnservice/v1/): submit invoices for reminders, manage documents, report payments, and follow the reminder lifecycle through collection handover.
All three APIs provide separate production and sandbox environments and share HTTP conventions, error and retry guidance, and webhook delivery conventions. Future contract changes follow the versioning policy. Claims and debtors are stable top-level resources. Orders reference debtor UUIDs and group claims, while order responses embed debtor summaries and claim projections needed to follow a submission. Claims remain addressable by the same UUID when paywise review moves them to another order or accepts them into a mandate. Mandate activity is available through one history collection with typed related resources and attachment downloads. Debtor correspondence of a case is readable as its own collection: text, a PDF rendering and the attachments of each email, with the history linking to it and a mandate.correspondence.published event. Existing v1 debtors, claims, mandates, payments, and Partner companies remain the same business records and retain their UUIDs. Existing cases continue from their current lifecycle state. The current APIs also preserve v1 metadata on debtors, claims, additional charges, and payments, plus events on debtors, claims, and additional charges, so historical integration context is readable without reimporting it. Partner integrations can connect existing companies, onboard new companies, manage memberships, and submit cases on behalf of connected clients. A disconnect revokes the Partner’s access without replacing the company’s underlying business records. The legacy Case Management and Partner v1 APIs are deprecated. No shutdown date has been announced, and their frozen documentation remains available in the legacy API snapshot. Existing integrations can move incrementally with the Case migration guide and Partner migration guide. Mahnservice starts with its own /mahnservice/v1/ contract and has no frozen predecessor. It is not part of the legacy Case Management and Partner v1 deprecation.