Appearance
Paying Customer
An order or subscription can be paid by a different customer than the one who receives it. The customer gets the features. The paying customer pays with their own mandate, receives the invoice and completes the checkout. A typical case: a company pays the subscription of one of its employees.
Both customers must belong to the same service. Only a Service or Admin account can set or change the paying customer; customers themselves cannot.
How it works
- Create the order with
paying_customer_id, or set it on a draft later. - Either customer may edit the draft. Only the paying customer can finalize it, confirming the gross amount they saw.
- The paying customer is charged. Tax, currency, invoice and credit balance are based on the paying customer.
- The features are granted to the customer. A subscription created from the order keeps the paying customer for its renewals.
- To hand the payments over to someone else, schedule a new paying customer with one of their mandates. The change takes effect with the next billing period.
Fields
On orders and subscriptions:
| Field | Type | Description |
|---|---|---|
customer_id | string | Customer who receives the features |
paying_customer | object | Customer who pays: id, is_company, first_name, last_name, company_name. Equal to the customer unless someone else pays. null when the paying customer was anonymized |
paying_customer_anonymized | boolean | true when the paying customer was anonymized. Then nobody can be charged, and the customer does not become the paying customer |
On a subscription's pending change:
| Field | Type | Description |
|---|---|---|
new_paying_customer_id | string | null | Customer who pays from the next renewal on, if a change is scheduled |
In webhooks for orders and subscriptions, paying_customer_id always holds the customer who pays. It equals customer_id when the customer pays for themselves, and is null with paying_customer_anonymized: true when the paying customer was anonymized.
Endpoints
Orders
| Endpoint | Description |
|---|---|
POST /orders/ | Accepts an optional paying_customer_id |
GET /orders/?customer_id=...&include_paid_for=true | Lists the customer's own orders plus the orders they pay for. Without include_paid_for, only the customer's own orders are listed |
PATCH /orders/{order_id}/paying-customer | Sets or clears the paying customer of a draft order. Body: {"paying_customer_id": "..."}. null or the order's own customer means the customer pays for themselves. Positions are repriced for the paying customer's country |
POST /orders/{order_id}/finalize | Must include expected_gross_amount when someone else pays. Returns 409 if it is missing or no longer matches the order total |
Subscriptions
| Endpoint | Description |
|---|---|
PATCH /subscriptions/{subscription_id}/paying-customer | Schedules a new paying customer. Body: {"paying_customer_id": "...", "mandate_id": "..."}. Returns the next renewal's gross amount (next_gross_amount) and when the change applies (effective_at) |
DELETE /subscriptions/{subscription_id}/paying-customer | Withdraws a scheduled change. A scheduled plan change stays |
Behavior notes
- Mandate: the mandate must belong to the new paying customer and be valid or pending. It is checked again when the change applies. If it can no longer be used, the change is dropped, the current paying customer keeps paying, and you get a
paying_customer_change_droppednotification. - Open payments stay: payments that are already open or failed are not moved to the new paying customer.
- Cancellation wins: cancelling the subscription drops a scheduled paying customer change, with the same notification.
- Switching back: pass the subscription's own customer as
paying_customer_idto let them pay for themselves again. - Switching the mandate (
PATCH /subscriptions/{id}/mandate) only accepts mandates of the paying customer. - Taxes may change with a new paying customer from another country or with a VAT exemption. Check
next_gross_amount. - Availability: the article and extensions must be available in the country of whoever pays at the next renewal. Scheduling a new paying customer checks the current plan and a scheduled plan change. Scheduling a downgrade while a new paying customer is scheduled checks the new paying customer's country. Both return
400otherwise. - Once-only rules (first-order coupons, articles that allow only one subscription) apply to the customer, not to the paying customer. One paying customer can pay the same article for several customers.
- Pay-as-you-go: a customer cannot pay for someone else when PAYG usage is involved, because usage is always billed to the customer who owns the balance. Setting a paying customer returns
400when an article or extension of the order or subscription is bound to a PAYG plan, or an article change will bind one. Binding a PAYG plan to an article returns409while someone pays for another customer's subscription or open order of it. Balance top-ups are not affected. - Price and article changes: the paying customer receives the consent requests for the subscriptions they pay for and answers them. The customer does not see these requests. Consent requests for PAYG price changes go to the customer who owns the balance. See Scheduled Price Changes and Scheduled Article Changes.
- Legal documents must be accepted by both customers before the order is finalized. If a document changes with mandatory re-acceptance, a subscription is cancelled at renewal unless both have accepted.
- Tax country: orders include
tax_country, the country the order is taxed in. That is the paying customer's country unless the order has a country override. - Availability: every article and extension of the order must be available in the tax country. If not, creating the order, adding a position or setting the paying customer returns
400naming the country, and the order stays unchanged. To keep the customer's country, set it as override withPATCH /orders/{id}/countrybefore setting the paying customer. - Emails: payment and invoice emails go to the paying customer. Emails about cancellation, pause, reactivation, plan changes and revocation go to both.
- Customer view: the customer sees the order and subscription, but not the paying customer's mandate. They cannot cancel, change, reactivate, finalize or withdraw. Subscription responses for customers include
viewer_role(customer,paying_customerorboth). - Right of withdrawal belongs to the paying customer. Their withdrawal does not waive or freeze the customer's own PAYG usage.
- Anonymization: a customer cannot be anonymized while they pay for an open order or a running subscription (including one with a pending withdrawal), or while they are scheduled to take over payments.
Relationships
- Orders - The paying customer is set on the order and confirmed at finalize.
- Subscriptions - Renewals charge the subscription's paying customer.
- Customers - Both sides are customers of the same service.
- Taxation - Tax is based on the paying customer.
- Right of Withdrawal - Only the paying customer can withdraw.