Update Invoice

PUT/rest/invoices/:invoice_number

Production URL

https://api.betterpayment.de/rest/invoices/:invoice_number

Test URL

https://testapi.betterpayment.de/rest/invoices/:invoice_number

Updates an existing invoice. Both PUT and PATCH are supported. Only the fields you send are changed; anything you omit is left as it is. status is not accepted here — use Change Invoice Status instead.

Request

invoice_numberStringrequired

Append invoice number to /rest/invoices/#invoice_number

invoiceObjectrequired

Hash containing the invoice fields to update.

Example Request

PATCH /rest/invoices/INV-2024-001
Authorization: Basic <base64(api_key:api_password)>
Content-Type: application/json
{
"invoice": {
  "amount": "10.55",
  "email": "dev@betterpayment.de"
}
}

Deactivate an invoice

Example Request (deactivate)

PATCH /rest/invoices/INV-2024-001
Authorization: Basic <base64(api_key:api_password)>
Content-Type: application/json
{
"invoice": {
  "active": false
}
}

Updatable fields

All fields go inside the invoice hash. Each is optional.

Parameter	Comments
active	true / false — activates or deactivates the invoice. Deactivating stops the payment link from working and blocks further e-mails for it. Only changeable while the invoice is pending and has no payment plan (see below). Accepts JSON booleans as well as "1"/"0" and "true"/"false".
amount	Invoice amount as a decimal. Accepts 10.55, "10.55" and German-style "10,55". Stored unsigned, so -10.55 is saved as 10.55. Only changeable while the invoice is pending and has no payment plan (see below). Sending "" is rejected with 422; sending null is treated as "not supplied" and leaves the amount unchanged.
debt_claim_number	New invoice number. If another active invoice in the same channel already uses it, that invoice is deactivated automatically so this one can take the number over.
first_name, last_name, company, email, phone, tax_id, customer_id	Customer details
address, address2, postal_code, city, state, country	Billing address
description	Description of the invoice/service
currency	3-letter currency code (ISO 4217). Rejected with 422 if it isn't exactly 3 characters.
print_date	Invoice date (YYYY-MM-DD format)
redirect_after_payments	Whether to redirect after payment (boolean)
success_url, error_url	Redirect URLs used after a successful / failed payment
expires_in	Number of units after which the payment link expires (requires expires_in_unit)
expires_in_unit	"minutes", "hours", or "days" (requires expires_in). Rejected with 422 if outside the whitelist.
locale	Per-invoice language for customer e-mails. One of en, de, pt. Rejected with 422 if outside the whitelist.
initial_email_type	"initial" or "reminder". Rejected with 422 if outside the whitelist.
send_initial_email	Stored opt-in flag (boolean). Only affects the e-mail sent at creation time, so changing it later has no effect on delivery.

When amount and active can be changed

info

amount and active can only be changed while the invoice's status is pending and no payment plan has ever been attached to it — including a payment plan that has since been cancelled or has failed. Once either condition is broken, money has been committed against those values: a payment plan's instalments are derived from the amount, and deactivating the invoice would break the payment link the plan collects against. Any attempt to change them is rejected with 422 and the rest of the update is not applied. Sending the values the invoice already has is always accepted, so a payload that echoes them back does not fail.

warning

A channel can hold at most one active invoice per invoice number. Activating an invoice while another active invoice in the same channel holds the same number is rejected with 422 — deactivate that one first. Note that because number-addressed endpoints always resolve to the active invoice (see How an invoice number is resolved), reactivating a deactivated invoice through this endpoint is only possible while no active invoice holds its number.

Response

The invoice hash is identical in shape to the Get Invoice response — see that section for the full field list, including active and id.

invoiceObject

Hash containing complete invoice information. See Get Invoice for the full field list, including active and id.

messageString

Success or error message from the API

errorString

Error details (null on success)

paylinkString

Direct payment link for the customer

qrcodeString

Base64-encoded QR code image for the payment. Suggested size 250PX with PNG format.

Example Response

{
"invoice": {
  "id": 789,
  "status": "pending",
  "active": true,
  "created_at": "2024-08-14T07:50:20.123Z",
  "updated_at": "2024-08-14T07:50:20.123Z",
  "debt_claim_number": "INV-2024-001",
  "print_date": "2024-08-14",
  "first_name": "Peter",
  "last_name": "Struwwel",
  "address": "Teststr 5",
  "address2": "12B",
  "postal_code": "10178",
  "city": "Berlin",
  "country": "Germany",
  "email": "dev@betterpayment.de",
  "amount": 10.55,
  "amount_cents": 1055,
  "currency": "EUR",
  "description": "Payment for drinks",
  "customer_id": "123456",
  "state": "BE",
  "phone": "+4917143214321",
  "redirect_after_payments": false,
  "success_url": "https://example.com/success",
  "error_url": "https://example.com/error",
  "tax_id": "123456789",
  "company": "Example GmbH",
  "expires_in": 24,
  "expires_in_unit": "hours",
  "expired": false,
  "uuid": "f34b3b2f-2680-4d62-a0c9-ce2e50ddbb8a",
  "channel_id": 123,
  "import_id": 456,
  "locale": "de",
  "effective_locale": "de",
  "send_initial_email": true,
  "initial_email_type": "initial",
  "effective_initial_email_type": "initial",
  "last_email": {
    "email_type": "reminder",
    "status": "sent",
    "sent_at": "2026-05-20T14:30:00Z",
    "recipient_email": "dev@betterpayment.de",
    "locale": "de"
  }
},
"message": "Invoice has been successfully created.",
"error": null,
"paylink": "http://yourchannel.jetztzahlen.de/pay/f34b3b2f-2680-4d62-a0c9-ce2e50ddbb8a",
"qrcode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}

Error responses

On failure the response carries no invoice, and both message and error are the same plain string describing the problem.

Status	When	Body
404	No invoice with this number for the authenticated merchant	{ "message": "Invoice not found.", "error": "Invoice not found." }
422	amount or active change attempted on an invoice that is no longer pending, or that has a payment plan	{ "message": "The amount and the active flag can only be changed while…", "error": "…" }
422	Activation attempted while another active invoice in the channel holds the same number	{ "message": "Another active invoice with this invoice number already exists in this channel. Deactivate it before activating this one.", "error": "…" }
422	A field failed validation	{ "message": "Currency is too long", "error": "Currency is too long" } — other examples: "Amount can't be blank" (amount sent as ""), "Locale isn't an option", "Expires In Unit isn't an option"

Example — amount or active change no longer allowed

{
  "message": "The amount and the active flag can only be changed while the invoice is still pending and has no payment plan attached.",
  "error": "The amount and the active flag can only be changed while the invoice is still pending and has no payment plan attached."
}

Example — another active invoice already holds this number

{
  "message": "Another active invoice with this invoice number already exists in this channel. Deactivate it before activating this one.",
  "error": "Another active invoice with this invoice number already exists in this channel. Deactivate it before activating this one."
}