Create order

import requests

url = "https://api.paywise.de/v2/orders/"

payload = { "debtor_id": "40000000-0000-4000-8000-000000000001" }
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "additional_debtors": [],
  "claims": [
    {
      "additional_charges": [],
      "additional_charges_amount": {
        "currency": "EUR",
        "value": "0.00"
      },
      "additional_debtor_ids": [],
      "created_at": "2026-07-18T10:00:00Z",
      "debtor_id": "40000000-0000-4000-8000-000000000001",
      "delay_date": "2026-07-09",
      "dispute_reason": null,
      "document_date": "2026-06-05",
      "document_reference": "2026-0042",
      "documents": [],
      "due_date": "2026-06-19",
      "events": [
        {
          "description": null,
          "location": null,
          "occurence": "2026-06-05T09:00:00Z",
          "title": "Invoice issued",
          "type": "claim",
          "your_reference": "2026-0042"
        }
      ],
      "id": "30000000-0000-4000-8000-000000000001",
      "is_disputed": false,
      "items": [],
      "legal_basis": {
        "claim_type_code": null,
        "contract_date": null,
        "description": null
      },
      "mandate_id": null,
      "metadata": [
        {
          "type": "comment",
          "value": "Consulting invoice from the customer portal"
        }
      ],
      "order_id": "20000000-0000-4000-8000-000000000001",
      "payments": [],
      "principal_amount": {
        "currency": "EUR",
        "value": "100.00"
      },
      "reminders": [],
      "status": "draft",
      "subject_matter": "Website accessibility consulting in June 2026",
      "total_amount": {
        "currency": "EUR",
        "value": "100.00"
      },
      "type": "receivable",
      "updated_at": "2026-07-18T10:00:00Z",
      "your_reference": "INV-2026-0042"
    }
  ],
  "confirmation_email": null,
  "created_at": "2026-07-18T10:00:00Z",
  "creditor_obligation_fulfilled": true,
  "debtor": {
    "acting_as": "consumer",
    "events": [
      {
        "description": null,
        "location": null,
        "occurence": "2026-05-01T09:00:00Z",
        "title": "Customer registered",
        "type": "registration",
        "your_reference": null
      }
    ],
    "id": "40000000-0000-4000-8000-000000000001",
    "legal_form": null,
    "metadata": [
      {
        "type": "user:reference",
        "value": "CUSTOMER-1001"
      }
    ],
    "organization": null,
    "person": {
      "birth_date": null,
      "first_name": "Alex",
      "last_name": "Example",
      "salutation": "mx"
    },
    "your_reference": "CUSTOMER-1001"
  },
  "expires_at": "2026-10-16T10:00:00Z",
  "id": "20000000-0000-4000-8000-000000000001",
  "mandate": null,
  "merged_into": null,
  "rejection": null,
  "starting_approach": "extrajudicial",
  "status": "draft",
  "totals": {
    "charges": {
      "currency": "EUR",
      "value": "0.00"
    },
    "main_claims": {
      "currency": "EUR",
      "value": "100.00"
    },
    "order_value": {
      "currency": "EUR",
      "value": "100.00"
    },
    "payments": {
      "currency": "EUR",
      "value": "0.00"
    }
  },
  "type": "invoice",
  "updated_at": "2026-07-18T10:00:00Z"
}

POST

orders

import requests

url = "https://api.paywise.de/v2/orders/"

payload = { "debtor_id": "40000000-0000-4000-8000-000000000001" }
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "additional_debtors": [],
  "claims": [
    {
      "additional_charges": [],
      "additional_charges_amount": {
        "currency": "EUR",
        "value": "0.00"
      },
      "additional_debtor_ids": [],
      "created_at": "2026-07-18T10:00:00Z",
      "debtor_id": "40000000-0000-4000-8000-000000000001",
      "delay_date": "2026-07-09",
      "dispute_reason": null,
      "document_date": "2026-06-05",
      "document_reference": "2026-0042",
      "documents": [],
      "due_date": "2026-06-19",
      "events": [
        {
          "description": null,
          "location": null,
          "occurence": "2026-06-05T09:00:00Z",
          "title": "Invoice issued",
          "type": "claim",
          "your_reference": "2026-0042"
        }
      ],
      "id": "30000000-0000-4000-8000-000000000001",
      "is_disputed": false,
      "items": [],
      "legal_basis": {
        "claim_type_code": null,
        "contract_date": null,
        "description": null
      },
      "mandate_id": null,
      "metadata": [
        {
          "type": "comment",
          "value": "Consulting invoice from the customer portal"
        }
      ],
      "order_id": "20000000-0000-4000-8000-000000000001",
      "payments": [],
      "principal_amount": {
        "currency": "EUR",
        "value": "100.00"
      },
      "reminders": [],
      "status": "draft",
      "subject_matter": "Website accessibility consulting in June 2026",
      "total_amount": {
        "currency": "EUR",
        "value": "100.00"
      },
      "type": "receivable",
      "updated_at": "2026-07-18T10:00:00Z",
      "your_reference": "INV-2026-0042"
    }
  ],
  "confirmation_email": null,
  "created_at": "2026-07-18T10:00:00Z",
  "creditor_obligation_fulfilled": true,
  "debtor": {
    "acting_as": "consumer",
    "events": [
      {
        "description": null,
        "location": null,
        "occurence": "2026-05-01T09:00:00Z",
        "title": "Customer registered",
        "type": "registration",
        "your_reference": null
      }
    ],
    "id": "40000000-0000-4000-8000-000000000001",
    "legal_form": null,
    "metadata": [
      {
        "type": "user:reference",
        "value": "CUSTOMER-1001"
      }
    ],
    "organization": null,
    "person": {
      "birth_date": null,
      "first_name": "Alex",
      "last_name": "Example",
      "salutation": "mx"
    },
    "your_reference": "CUSTOMER-1001"
  },
  "expires_at": "2026-10-16T10:00:00Z",
  "id": "20000000-0000-4000-8000-000000000001",
  "mandate": null,
  "merged_into": null,
  "rejection": null,
  "starting_approach": "extrajudicial",
  "status": "draft",
  "totals": {
    "charges": {
      "currency": "EUR",
      "value": "0.00"
    },
    "main_claims": {
      "currency": "EUR",
      "value": "100.00"
    },
    "order_value": {
      "currency": "EUR",
      "value": "100.00"
    },
    "payments": {
      "currency": "EUR",
      "value": "0.00"
    }
  },
  "type": "invoice",
  "updated_at": "2026-07-18T10:00:00Z"
}

Authorizations

Authorization

string

header

required

Company-bound Case Management API key — the standard credential for this API.

Headers

X-On-Behalf-Of-Company

string<uuid>

Required when a Partner key calls the Case Management API; rejected for direct Case keys. Contains the entitled paywise company UUID.

Idempotency-Key

string

required

Required client-supplied command key scoped to the selected Case company or Partner owner, method, operation and path. An exact retry replays the original response while it is retained, including after credential rotation or replacement. Current permissions are required.

Maximum string length: 255

Body

application/json

Create an order with a referenced debtor and embedded claims in one API call. Returns the created order in its read representation.

debtor_id

string<uuid>

required

Existing primary debtor in the selected company.

additional_debtor_ids

string<uuid>[]

Other debtors, each supplied by an existing UUID from the active company. The primary debtor cannot also appear here, and each referenced additional debtor may appear only once. Maximum 10 entries.

Maximum array length: 10

claims

(Receivable claim · object | Titled claim · object)[]

Claims to create in this draft; each must specify type. Invoice and rental orders accept receivable claims. Titled orders accept titled claims and receivable enforcement costs (K014); at least one complete claim, including one titled claim for titled orders, is required before finalization. Maximum 50 entries. The 50-claim limit applies to the complete order, including claims added later through the claim endpoint; exceeding it returns 400 validation_error.

Maximum array length: 50

Create a receivable claim: the amount is stated on the claim itself.

Receivable claim
Titled claim

Show child attributes

confirmation_email

string<email> | null

Address that receives the order entry confirmation (Eingangsbestätigung) when the order is finalized. Omit or set null for no confirmation email.

Required string length: 1 - 255

creditor_obligation_fulfilled

boolean | null

Whether you have fully performed your obligation to the debtor. For invoice and rental orders, supply true or false before finalization; null leaves the decision unset. Omit for titled orders.

rental_agreement

object

Rental-agreement singleton supplied only for a rental order.

Show child attributes

starting_approach

enum<string> | null

Initial route for invoice and rental orders: extrajudicial starts with out-of-court collection; judicial starts by applying for a payment order (Mahnbescheid). Required before finalization; omit for titled orders, where enforcement is implicit.

Available options:

extrajudicial,

judicial

success_fee_confirmed

boolean

Only valid for titled orders. Confirmation of the titled-order success-fee arrangement; it must be true before finalization. See the paywise General Terms and Conditions (AGB) for the exact conditions for titled orders.

type

enum<string>

default:invoice

Order type discriminator: invoice, rental, or titled. Defaults to invoice when omitted.

Available options:

invoice,

rental,

titled

Response

Invoice order
Rental order
Titled order

An invoice order contains receivable claims and exposes starting_approach and creditor_obligation_fulfilled.

Read representation of an order.

status is derived from the order's submission and review progress; mandate names the created mandate once the order is accepted; merged_into names the surviving order when this order was merged away during review.

additional_debtors

object[]

required

read-only

Inline summaries of the additional debtors. Retrieve each debtor's full details with GET /v2/debtors/{id}/ using its id. Replace membership through PATCH /v2/orders/{id}/ while the order is a draft. API submissions are limited to 10 additional debtors.

Show child attributes

claims

(Receivable claim · object | Titled claim · object)[]

required

read-only

Receivable claims belonging to this order, including their itemized charges and documents. Titled claims are accepted only in titled orders. API submissions are limited to 50 claims per order.

A receivable claim based on an invoice, rent, or another obligation. Its principal amount, dates, charges, and documents belong to the claim.

Receivable claim
Titled claim

Show child attributes

confirmation_email

string<email> | null

required

read-only

Address receiving the order-entry confirmation, when requested.

created_at

string<date-time>

required

read-only

Time at which the order was created.

creditor_obligation_fulfilled

boolean | null

required

read-only

Whether you fully performed your obligation to the debtor.

debtor

object

required

Inline summary of the primary debtor. Retrieve full details with GET /v2/debtors/{id}/ using its id.

Show child attributes

expires_at

string<date-time> | null

required

read-only

Time at which this API-created draft expires: updated_at plus 90 days, refreshed by every successful draft change. Once it has passed, the order reads expired and every change answers 409 order_expired until the daily cleanup deletes it. Null once the order is finalized and for orders created in the portal.

string<uuid>

required

read-only

Stable identifier of this order.

mandate

string<uuid> | null

required

read-only

Accepted case created from this order, when available.

merged_into

string<uuid> | null

required

read-only

Surviving order when this order was merged during review.

rejection

object | null

required

Why paywise declined the order: reason, time, notified recipients, and the standard reason's key. Null unless status is rejected.

Show child attributes

starting_approach

enum<string> | null

required

Initial collection route: extrajudicial starts out of court; judicial starts by applying for a payment order (Mahnbescheid). Null while this decision is unset.

Available options:

extrajudicial,

judicial

status

enum<string>

required

Order lifecycle state: draft is editable; submitted awaits processing; awaiting_client_response requires client input; accepted has entered case processing; rejected was declined; withdrawn was cancelled by the client; expired passed its draft deadline and accepts no further changes (409 order_expired) until the daily cleanup deletes it; merged points to the surviving order in merged_into.

Available options:

draft,

submitted,

awaiting_client_response,

accepted,

rejected,

withdrawn,

expired,

merged

totals

object

required

Financial totals calculated across the order's claims.

Show child attributes

type

enum<string>

required

Literal invoice order discriminator.

Available options:

invoice

updated_at

string<date-time>

required

read-only

Time at which the order was last updated.

Start here

API essentials

Case Management API

Partner API

Mahnservice API

Integrations

Legacy APIs (v1)

Authorizations

Headers

Body

Response