POST /v1/subscriptions/{subscriptionId}/billing-rail

Uwierzytelnianie

Wyślij klucz API jako token bearer. Klucz musi posiadać uprawnienie billing.payment.manage; klucz bez niego jest odrzucany z kodem 403, a nie 404.

Ten punkt końcowy nie wymaga identyfikatora organizacji. Twój klucz już identyfikuje organizację, do której należy, a odpowiedź jest do niej ograniczona.

Wypróbuj

Zastąp wszystko w nawiasach ostrych własnymi wartościami, a zastępczy znacznik klucza kluczem ze swojego pulpitu nawigacyjnego.

curl -X POST https://api.zinndigital.com/v1/subscriptions/{subscriptionId}/billing-rail \
  -H "Authorization: Bearer zdk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "rail": <string<engine, paypal>> }'

Zalogowany? Konsola API w Twoim panelu uzupełnia rzeczywiste identyfikator organizacji oraz Twój własny klucz i wykonuje żądanie względem aktywnego API, dzięki czemu możesz zobaczyć rzeczywistą odpowiedź. Otwórz ten punkt końcowy w konsoli API

Szczegóły

Move a subscription between the **engine** rail (we invoice and charge on the renewal date) and the **PayPal** rail (PayPal charges on its own schedule under an agreement the customer approved). ADR 0029 records the boundary: PayPal owns only *when* the money is taken — the engine still owns what is owed, tax, entitlements, dunning and suspension. ⛔⛔ **Switching to PayPal returns an `approval_url` and grants nothing.** Until the buyer approves in PayPal's own interface and PayPal sends us a **signed** `BILLING.SUBSCRIPTION.ACTIVATED` webhook, the agreement cannot charge and the subscription's clock has not started. `active` is `false` for exactly that reason. The browser's return from the approval URL is an attacker-supplied claim and is never treated as approval. Switching **away** cancels the agreement at PayPal first and unbinds second. The reverse order would hand the subscription back to the engine's renewal sweep while PayPal was still entitled to charge it — a double charge for the window between the two calls. Requires `billing.payment.manage`. `422` carries a `code`: `ALREADY_ON_RAIL`, `NO_CATALOGUE_PRICE`, `PRICE_WOULD_CHANGE` (the subscription is on a price that differs from the published one, so switching would change what the customer pays — refused rather than done quietly), `NOT_SWITCHABLE`, or `PAYPAL_REFUSED`.

Parametry

Treść żądania

Odpowiedź

Błędy, które ten punkt końcowy może zwrócić

401 · 403 · 404 · 422 · 429