Skip to content

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 ​

  1. Create the order with paying_customer_id, or set it on a draft later.
  2. Either customer may edit the draft. Only the paying customer can finalize it, confirming the gross amount they saw.
  3. The paying customer is charged. Tax, currency, invoice and credit balance are based on the paying customer.
  4. The features are granted to the customer. A subscription created from the order keeps the paying customer for its renewals.
  5. 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:

FieldTypeDescription
customer_idstringCustomer who receives the features
paying_customerobjectCustomer 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_anonymizedbooleantrue 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:

FieldTypeDescription
new_paying_customer_idstring | nullCustomer 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 ​

EndpointDescription
POST /orders/Accepts an optional paying_customer_id
GET /orders/?customer_id=...&include_paid_for=trueLists 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-customerSets 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}/finalizeMust include expected_gross_amount when someone else pays. Returns 409 if it is missing or no longer matches the order total

Subscriptions ​

EndpointDescription
PATCH /subscriptions/{subscription_id}/paying-customerSchedules 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-customerWithdraws 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_dropped notification.
  • 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_id to 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 400 otherwise.
  • 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 400 when 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 returns 409 while 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 400 naming the country, and the order stays unchanged. To keep the customer's country, set it as override with PATCH /orders/{id}/country before 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_customer or both).
  • 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.