• It takes the location filters of GET /v1/providers (country, postalCode, city, street, lat/lng, radiusKm) and serviceMethod, and answers { "categories": ["backwaren", "essen-trinken", …] }: every category with at least one orderable offer there, and the group each sits in.
• It matches exactly as GET /v1/providers?category= does, so a home screen can leave out a group card that would open on an empty list. Works with a publishable key.

• language is a two-letter ISO 639-1 code (en, de, …). Place names come back in that language where the geocoder has one, falling back to English. Left off, names come back as before (German first, then English).
• near is an ISO alpha-2 country. Results in that country come first; the others stay in the list. A bare postcode like 24105 exists in several countries, and near puts the one the customer most likely means at the top. Unlike country, it rules nothing out.

• Only COMPLETED, CANCELLED, REFUNDED or FAILED orders; an open one answers 409 order_status_conflict. It answers 204, and repeating it is harmless.
• Nothing is deleted. The order is still readable by id, its invoice stays valid, and the provider and you still see it.

• Before, category was matched against the categories a business stated in its settings, so a bakery that also sells coffee was found under bakery only. Now it is found under both.
• Under a category filter, listingCount and priceFromCents count only the offers in that category, the same way they already did for serviceMethod and location.

• ?serviceMethod=DELIVERY,AT_CUSTOMER (or the parameter repeated) matches a listing that offers any of them — everything that comes to the customer, goods and services alike. PICKUP,AT_PROVIDER is everything the customer goes to. One value works as before.
• An unknown value is still a 400.

• instantAllowed on every listing. true only on a SCHEDULED listing, and it means the customer chooses: leave scheduledFor out of POST /v1/orders (or POST /v1/customers/me/orders) and the order is INSTANT, with no appointment booked; send it and the order is SCHEDULED as before. A basket needs a time as soon as one scheduled line doesn't allow this. See Place an order.
• GET /v1/listings?fulfillment=INSTANT includes these listings.
• A quote offer on such a listing may leave out scheduledFor and durationMinutes.
• Moving an INSTANT order with scheduledFor is refused: scheduledFor is only valid on an order booked for a time.

API operations​

• GET /health answers 200 {"status":"ok"} when the API and its database are up and 503 otherwise. No /v1, no key, and it never counts against a rate limit or shows in your usage.
• Rate limits are counted once across all servers. The limits, the X-RateLimit-* headers and the 429 body are unchanged — a budget simply no longer resets or multiplies depending on which server answers. See Rate limits.
• Webhook deliveries are sent once. A retry is claimed before it is sent, so a delivery never goes out twice when the API runs on several servers.
• Request logs and webhook delivery history are kept for 400 days, longer than the usage charts' longest range (a year), and deleted after that.

API changes​

• Customers can delete their own account — DELETE /v1/customers/me erases the profile, addresses, quote requests and push tokens and signs out every device. While an order is still open it answers 409 customer_has_open_orders with the orders in details.openOrders. See Deleting the account.
• Push notifications to the customer's phone. Register an Expo push token with PUT /v1/customers/me/push-token and Handl pushes when the provider accepts, declines, cancels, changes or completes the order, or sends a quote — in German or English by the customer's locale. Prefer to push from your own server? Skip the token and use the order.* webhooks. See Push notifications.
• startWithinWithdrawalPeriod on POST /v1/orders, POST /v1/customers/me/orders and quote accept records that the customer asked for a service to start inside the withdrawal period; the order answers it as withdrawalWaiverAt. Services only — on goods it is a 400. See Starting a service inside the withdrawal period.
• VARIABLE pricing is refused on listing create and update (400); use FIXED, or QUOTE to price per request.
• An order belonging to another provider is a 404, like any other order you can't see. The order_not_yours code is gone.
• Applications need privacyAccepted: true — POST /v1/partner-applications and POST /v1/provider-applications answer 400 without it. Rejected applications are deleted six months after the decision.
• Opening hours don't gate orders. An INSTANT order is taken at any hour; show provider.openingHours if it matters to your customer.
• Repeating diary exceptions. A dated availability window may carry an rrule (FREQ=WEEKLY;BYDAY=…, FREQ=MONTHLY, FREQ=YEARLY, with UNTIL or COUNT) and then applies on every occurrence — in the portal and on PUT /v1/sandbox/providers/:id/listings/:listingId/availability. See Sandbox.
• Providers can connect an external calendar by its iCal address; its events are synced every 15 minutes and those hours stop being offered in availability. Nothing changes in the API you call.
• Webhook URLs must be public https — in the sandbox too, since one URL serves both environments. POST /v1/partners/me/webhook answers 400 for http://, a port other than 443, credentials in the URL, localhost or a private address. Deliveries check the resolved address on every attempt and no longer follow redirects. For local testing, use an https tunnel. See What the URL must be.
• Ready for pickup. A PICKUP order the provider has accepted can be marked ready to collect: the order gains readyAt, the new webhook order.ready_for_pickup is sent once, and a customer with a registered push token is told. The status stays IN_PROGRESS. GET /v1/customers/me/orders carries readyAt and paidAt too.
• paidAt on every order: when the payment succeeded and the order became CONFIRMED.

Breaking​

• ListingDto.durationMinutes is removed.
• ListingPriceDto gains minutesPerUnit (1–2400: the time for one unit — up to a 40-hour week — or the whole job when the price has no unit) and setupMinutes (counted once per appointment). Every price of a fixed-price service listing needs minutesPerUnit; goods carry neither.
• AvailabilitySlotDto gains segments, and its endsAt is now when the job finishes, not the end of a grid cell. A window's slotDurationMinutes is only the grid starts sit on.
• Order DTOs gain appointmentSegments: { startsAt, endsAt }[], empty when there is no appointment.
• A quote offer on a SCHEDULED listing needs durationMinutes (5–1440) beside scheduledFor.

New​

• POST /v1/availability (publishable key allowed): the basket's items, as POST /v1/orders takes them, plus optional from/to/serviceMethod; answers the starts where the whole basket fits on every scheduled listing in it. Use it instead of intersecting diaries in your app.
• ?items=<listingPriceId>:<quantity>,… and ?serviceMethod= on GET /v1/listings/:id/availability.
• durationMinutes on quote offers, and the order that accepting one creates runs that long.
• GET /v1/sandbox/quote-requests/:id/availability?durationMinutes= (sandbox key): the free starts for an offer of that length, so you can answer a scheduled request as its provider.
• Travel time: a provider who comes to the customer can keep a fixed time free before each appointment. It is never part of the price or of segments, but it can make a start unavailable.
• Moving an order keeps its length and replaces its appointmentSegments.

• New: POST/GET /v1/customers/me/quote-requests[/:id], …/:id/accept ({ offerId }, returns the order and its clientSecret) and …/:id/decline.
• New: GET /v1/quote-requests[/:id] with your secret key (orders:read).
• New webhooks: quote.offered, quote.withdrawn, quote.rejected, quote.expired.
• New sandbox routes: POST /v1/sandbox/quote-requests/:id/offer and …/reject.
• Ordering a QUOTE listing directly is now 409 listing_requires_quote; a request or offer that moved on is 409 quote_status_conflict.

• POST /v1/customers/me/orders/:id/cancel now also takes a CONFIRMED order. The customer gets back everything not already refunded, and the order ends at REFUNDED. From IN_PROGRESS on it is still a 409.
• A paid order cancelled this way fires order.cancelled, with amountCents and refundedAmountCents like order.refunded. No separate order.refunded follows.
• A refund made by hand in the payment dashboard is now recorded on the order and fires order.refunded like any other refund, with its share of VAT, commission and your partner share accounted for.

• An invitation mails the person a link to set a password. Everyone on the team keeps the same rights; only the owner invites, removes and hands ownership on.
• POST /v1/partners/me/users { email } and DELETE /v1/partners/me/users/:uid are console-session only: an API key gets 403 partner_session_required.
• New error: 409 cannot_remove_self — the owner can't remove themselves; hand ownership on first.

• A closed account answers every request with 403 account_closed, carrying closedAt and purgeAfter.
• The REVOKED partner status is gone; api_key_suspended now means SUSPENDED only.
• New error codes: account_closed, account_has_open_business, not_account_owner, confirmation_mismatch, recent_sign_in_required, account_not_closed, account_purged, owner_replacement_required, owner_is_only_user.

• categories on a provider is never empty.
• provider_setup_incomplete now also covers a provider with no category.
• A sandbox provider's categories are the ones its listings are filed under. Created with no listings, it answers 404 until you add its first offer. See Your own test businesses.

• New webhook event type webhook.test.
• GET /v1/partners/me/usage behaves as before with a key; requests made by the console are not counted.
• GET /v1/orders accepts sort=desc (default stays asc).
• New error codes: partner_session_required, live_key_not_active, no_previous_key, webhook_not_configured.

What changed for you

• Your app's revenue share (revenueShareBps on GET /v1/partners/me, 20% by default) is now paid out automatically from every live order, as a Stripe transfer out of the same charge the customer was billed on.
• Three new endpoints set it up: POST /v1/partners/me/payouts/onboarding, GET /v1/partners/me/payouts, GET /v1/partners/me/payouts/dashboard-link. See Getting paid.
• A live order is refused with 409 partner_payouts_not_set_up until you finish onboarding, unless your share is 0%. Sandbox never checks this.
• A new webhook, partner_share.transferred, fires when your share lands — simulated in sandbox, a real transfer in live.
• Refunds and disputes reduce your share proportionally, the same way they already reduce the provider's.
• None of this is visible to the customer who paid — partnerShareBps, partnerShareCents and partnerTransferStatus are partner- and provider-facing only.

See adr/0020-three-way-revenue-split.md for the full design.

• POST …/orders/:id/cancel works on an order paid through an invoice. It used to try to cancel the invoice's PaymentIntent, which Stripe refuses; it now voids the invoice, which cancels the PaymentIntent with it. An invoice that is already void is accepted as is, and one Stripe reports paid answers 409 order_status_conflict — refund it instead.
• scheduledFor in the past is a 400, when an order is placed and when it is changed, even if that hour was free. The availability routes never offered one.

A refused scheduledFor now names the picker to read: the listing's GET /v1/listings/:id/availability when an order is placed, the order's own …/orders/:id/availability when one is moved.

• UpsertServiceAreaDto.placeId — new. We fill in city and region from the place. Cannot be combined with postalCodePrefixes or a radius (400). If the place can't be looked up right now the save is refused with 503 — try again.
• ServiceAreaDto gains placeId and hasOutline. The polygon itself is at GET /v1/places/:id/boundary.
• GET /v1/listings, GET /v1/providers and GET /v1/listings/:id/service-area-check take an optional street, so the check asks exactly the question an order will.
• Orders place a delivery address by its street (deliveryAddress.line1), falling back to the postcode. If the address can't be placed at all, an outlined area falls back to its city, or to its whole country.

What changed for you

• Groups: Essen, Reinigung, Reparatur & Montage (Handwerk and Haushalt merged), Umzug & Entsorgung (formerly Transport), Technik im Haus. The groups bau, garden, energy and household no longer exist.
• Renamed slugs: cleaning-construction → cleaning-moveout (Umzugs- & Endreinigung), household-handyman → handwerk-handyman, household-furniture → handwerk-furniture, household-pest → handwerk-pest, household-clearance → transport-clearance. Category ids did not change.
• Deleted categories: everything under the four removed groups, plus cleaning-office, handwerk-heating, -carpentry, -flooring, -roofing, -metal, -glazing, household-other, tech-smarthome and tech-security. A ?category= filter on one of them now simply matches nothing, and filing a listing under one of their ids is refused.
• Existing rows were re-filed, not lost. A listing, order or provider tag on a deleted category now names the nearest kept one: handwerk-heating → handwerk-plumbing, tech-smarthome → tech-tv, tech-security → tech-other, cleaning-office → cleaning-other, everything else → handwerk-other.

If you cached category ids or slugs, refresh them from GET /v1/categories.

• PATCH /v1/customers/me/orders/:id and PATCH /v1/orders/:id while the order is PENDING_PAYMENT or CONFIRMED; the provider, from the portal and Handl Orders, while it is CONFIRMED or IN_PROGRESS.
• The checks of placing an order apply again, and the tax country may not move.
• An unpaid order whose invoice address changed gets a new invoice: paymentSecretChanged: true means fetch the payment secret again.
• New webhook order.updated; every order read carries changes, newest first.
• GET /v1/customers/me/orders/:id/availability and GET /v1/orders/:id/availability list the times an appointment can move to, counting the order's own booking as free.

See Customer ordering for the rules and the errors.

What changed​

ServiceMethod gains two values, AT_CUSTOMER and AT_PROVIDER. Goods keep PICKUP and DELIVERY; a service names one or both of AT_CUSTOMER/AT_PROVIDER. A listing's serviceMethods can never be empty and can never mix a goods method with a service method — every listing that used to answer [] became ["AT_CUSTOMER"], since every surface that showed that listing as "on site" meant the customer's own place.

Order.serviceMethod is likewise never null. A past order with no method recorded also became AT_CUSTOMER; it carries no deliveryAddress, only the billing address taken at checkout, so the provider portal's route endpoint falls back to that billing address for an AT_CUSTOMER order with nothing else to route to.

AT_CUSTOMER works exactly like DELIVERY did: it requires deliveryAddress and is checked against the provider's service area at order time, the same 400 either one gets outside it. AT_PROVIDER works like PICKUP — no address, refused if one is sent.

A service listing (AT_CUSTOMER/AT_PROVIDER) now requires durationMinutes; a goods listing (PICKUP/DELIVERY) must not carry one. This is checked on every save, not only on publish — a migrated listing that predates the rule and has no duration is exempt from just that part, so it can still be taken offline or published from the listings table. Only a PATCH whose body is exactly { "isActive": ... } gets that exemption; any content edit on such a listing is refused until it gets a duration. See the new error codes for the four listing-shape messages and the order-time ones.

The provider portal's edit page is no longer a separate one-page editor — it's the same step wizard /provider/listings/new uses, reachable at every step, saving from every step, with a red marker on any step still carrying an unmet rule. Opening it shows a loading skeleton while the listing loads and a not-found page for an id that isn't the provider's own. The offer-type step (Ware/Dienstleistung) resets the category only when the provider actively switches type — never on load, so a loaded listing's category is never silently defaulted — and the handover step is two cards for goods (Abholung/Lieferung) and two for a service (beim Kunden/im Geschäft), replacing the old multi-select where picking none of them meant on-site work.

Fixed: POST /v1/customers/me/orders with addressId and no serviceMethod on a listing that only offers DELIVERY used to send the saved address through as the billing address and 400 for a missing deliveryAddress. It now resolves the order's method before deciding where the address goes, so it arrives as deliveryAddress as it should.

See How customer and provider meet for the four methods and adr/0017 in the repo for why two methods rather than a single serviceLocation field.