A valid request URL is required to generate request examples{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "incomplete",
"current_period_start": "2023-11-07T05:31:56Z",
"current_period_end": "2023-11-07T05:31:56Z",
"cancel_at_period_end": true,
"canceled_at": "2023-11-07T05:31:56Z",
"trial_ends_at": "2023-11-07T05:31:56Z",
"provider": "stripe",
"provider_account_id": "<string>",
"provider_subscription_id": "<string>",
"provider_synced_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"items": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"quantity": 123,
"price": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"kind": "recurring",
"currency": "<string>",
"amount_minor": 123,
"tax_behavior": "inclusive",
"archived": true
}
}
],
"capabilities": {
"scheduled_plan_change": true,
"proration": true,
"cancel_at_period_end": true,
"hosted_portal": true,
"tax_calculation": true,
"resume_subscription": true,
"list_invoices": true,
"list_catalogue": true,
"publish_catalogue": true,
"manage_coupons": true,
"pause_subscription": true,
"discount_subscription": true,
"refund_payment": true
},
"mirror_refreshed": true,
"mirror_stale_reason": "provider_reread_failed",
"unmapped_provider_price_id": "<string>"
}{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "incomplete",
"current_period_start": "2023-11-07T05:31:56Z",
"current_period_end": "2023-11-07T05:31:56Z",
"cancel_at_period_end": true,
"canceled_at": "2023-11-07T05:31:56Z",
"trial_ends_at": "2023-11-07T05:31:56Z",
"provider": "stripe",
"provider_account_id": "<string>",
"provider_subscription_id": "<string>",
"provider_synced_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"items": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"quantity": 123,
"price": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"kind": "recurring",
"currency": "<string>",
"amount_minor": 123,
"tax_behavior": "inclusive",
"archived": true
}
}
],
"capabilities": {
"scheduled_plan_change": true,
"proration": true,
"cancel_at_period_end": true,
"hosted_portal": true,
"tax_calculation": true,
"resume_subscription": true,
"list_invoices": true,
"list_catalogue": true,
"publish_catalogue": true,
"manage_coupons": true,
"pause_subscription": true,
"discount_subscription": true,
"refund_payment": true
},
"mirror_refreshed": true,
"mirror_stale_reason": "provider_reread_failed",
"unmapped_provider_price_id": "<string>"
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Adopt an existing subscription
Requires billing:write. Records a subscription that already exists at your gateway and has never existed here — the migration path for arriving with customers who are already paying.
Why it is needed
Every other subscription in this mirror was born from a checkout started here: the row exists first, its id travels to the gateway as the checkout’s client reference, and the completed checkout is what links the two. A subscription created before you connected — or created in the gateway’s own dashboard — has no such row, so its webhooks arrive, are stored, and settle with a note saying nothing here is linked to it. The money is real and every entitlement read says the customer is on nothing.
What is missing is not information about the subscription. It is which of your teams it belongs to: a gateway’s answer names a payer the gateway invented, and only you know which customer that is. This endpoint is where you say so.
What it does
Reads the subscription from the gateway and writes it down against the customer you name — status, period, trial, scheduled cancellation and line, through exactly the same apply the webhooks use. Nothing is charged, nothing is created at the gateway, and nothing about the subscription changes: what changes is that this system now holds it.
Once adopted, the row behaves like any other. Webhooks find it, the nightly reconciliation re-reads it, entitlements resolve through its plan, and it can be changed or cancelled from here.
Naming the customer
By customer_id, or by customer_external_id — your own id for the team, which is what makes a migration scriptable without keeping a map of our uuids. Send exactly one: a request carrying both holds two beliefs about who is paying. The customer has to exist; this does not create one.
Running it again is safe
A backfill is a script that a network failure makes somebody run twice. Adopting the same subscription for the same customer again answers 200 with the row rather than an error, so a rerun converges; adopting it for a different customer is refused, because that is the one repeat that means somebody made a mistake. A first adoption answers 201.
What it refuses, and why it refuses rather than guesses
There is no way to un-adopt: a subscription is never deleted here, and its gateway reference is only ever written into an empty column. A wrong link is permanent, so anything that would have to be guessed is refused instead.
- The price has to be mapped into this environment’s catalogue. The plan is not stored on the gateway’s object; it is resolved from the price. Import your catalogue (or publish your prices onto the gateway) first — the refusal names the gateway price it could not place.
- One priced line only. Where the gateway holds several, which line names the plan is a question no provider answers, and there is no previous plan here to fall back on.
- The payer has to agree, where it can be checked. If this customer has paid through this gateway before, their payer reference is known and a subscription belonging to a different payer is refused. If they never have — the ordinary case when migrating — there is nothing to check against and your word is what stands.
- The subscription must not already be mirrored under another customer.
A valid request URL is required to generate request examples{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "incomplete",
"current_period_start": "2023-11-07T05:31:56Z",
"current_period_end": "2023-11-07T05:31:56Z",
"cancel_at_period_end": true,
"canceled_at": "2023-11-07T05:31:56Z",
"trial_ends_at": "2023-11-07T05:31:56Z",
"provider": "stripe",
"provider_account_id": "<string>",
"provider_subscription_id": "<string>",
"provider_synced_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"items": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"quantity": 123,
"price": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"kind": "recurring",
"currency": "<string>",
"amount_minor": 123,
"tax_behavior": "inclusive",
"archived": true
}
}
],
"capabilities": {
"scheduled_plan_change": true,
"proration": true,
"cancel_at_period_end": true,
"hosted_portal": true,
"tax_calculation": true,
"resume_subscription": true,
"list_invoices": true,
"list_catalogue": true,
"publish_catalogue": true,
"manage_coupons": true,
"pause_subscription": true,
"discount_subscription": true,
"refund_payment": true
},
"mirror_refreshed": true,
"mirror_stale_reason": "provider_reread_failed",
"unmapped_provider_price_id": "<string>"
}{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "incomplete",
"current_period_start": "2023-11-07T05:31:56Z",
"current_period_end": "2023-11-07T05:31:56Z",
"cancel_at_period_end": true,
"canceled_at": "2023-11-07T05:31:56Z",
"trial_ends_at": "2023-11-07T05:31:56Z",
"provider": "stripe",
"provider_account_id": "<string>",
"provider_subscription_id": "<string>",
"provider_synced_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"items": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"quantity": 123,
"price": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"kind": "recurring",
"currency": "<string>",
"amount_minor": 123,
"tax_behavior": "inclusive",
"archived": true
}
}
],
"capabilities": {
"scheduled_plan_change": true,
"proration": true,
"cancel_at_period_end": true,
"hosted_portal": true,
"tax_calculation": true,
"resume_subscription": true,
"list_invoices": true,
"list_catalogue": true,
"publish_catalogue": true,
"manage_coupons": true,
"pause_subscription": true,
"discount_subscription": true,
"refund_payment": true
},
"mirror_refreshed": true,
"mirror_stale_reason": "provider_reread_failed",
"unmapped_provider_price_id": "<string>"
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Autorizações
A staff session token, uk_st_…. Minted by sign-up, sign-in or the two-factor exchange. Only a 401 means it is spent; not_a_member (403) is about the organization named in X-Organization-Id and leaves the token good for the others.
Cabeçalhos
The organization the caller is acting on — the org_… code that appears in the panel URL. It identifies; the membership JOIN is what authorizes, so a forged code reads nothing: the answer is not_a_member (403), which does not mean the session is over. Absent, the session's default organization answers, or — if that membership was revoked while the session was open — any other one the caller still holds.
Parâmetros de consulta
Which environment to act in. A view parameter, valid only on the staff surface — a machine credential never chooses its environment, it is resolved from the key.
live, test Corpo
The gateway's own id for the subscription to adopt, such as a Stripe sub_…. The one thing here that cannot be derived.
Which of your teams is paying. Must be a customer of this environment. Mutually exclusive with customer_external_id.
The same, addressed by your own id for the team. Mutually exclusive with customer_id. The customer must already exist — this does not create one.
Which gateway holds it. Only needed when the environment has more than one connected.
stripe Resposta
It was already adopted for this customer, and the row is returned unchanged. Nothing was written and no fact was published.
What one of your customers is paying, mirrored from the gateway.
That word decides how to read every field below. The gateway is the source of truth about money; this is a local copy kept so an entitlement can be answered without a network call, joined to the rest of your data, and read while the gateway is unreachable. provider_synced_at is when the copy was last confirmed — null means never, which is what a checkout that was started and not completed looks like.
Who is billed. A subscription always hangs off a customer, including when that customer is a team of one.
What they are subscribed to, as opposed to how it is billed — which is items. Entitlements are computed from the plan's features, so this always has exactly one answer.
In our vocabulary, never a gateway's spelling, so this does not change when you change gateway.
incomplete is created and not yet paid — no access. past_due is paid before and a payment has failed; whether that keeps access is a grace-period decision and not this field's. unknown means the adapter did not recognise what the gateway said: it is a reason to look, never a reason to charge anybody or to cut them off, and it deliberately does not read as active or as canceled.
incomplete, trialing, active, past_due, paused, canceled, unknown The period paid for. Null together with the end, never one alone: an incomplete subscription has no period, and a made-up one is a date an entitlement expires on that nothing happens at.
A cancellation that has been scheduled and has not happened. The subscription is still active until current_period_end, which is why this is its own field rather than a status.
When it actually stopped. Null while it has not.
Null when there is no trial — which is a different fact from a trial that ended, and only one of them should make a screen say a trial expired.
Which gateway holds this subscription. Exactly one: that is who is charging the card.
stripe The merchant account, as the gateway names it. Empty until a health check has asked who the keys belong to.
The gateway's own id. Empty for a checkout that was started and never completed — a row that exists here and nowhere else, and the one state in which no act on this subscription is possible.
When this copy was last re-read from the gateway, as opposed to when the row was last written. Null means never confirmed. A mirror that cannot say how stale it is would be claiming to be the source.
The lines. Present on a single subscription, absent from the list.
Show child attributes
Show child attributes
What a gateway can do beyond the minimum every gateway can do. Every flag defaults to false, so a provider that declares nothing is treated as the weakest one — silence is never a claim. Read it to stop offering an act that would be refused.
Every flag below is always present. The object is emitted whole or not at all: absent means this server has no adapter loaded for the gateway, and it never means "some flags were left out". A reader must therefore distinguish false from missing rather than testing for falsiness — a key that is not here is not a gateway that cannot do something, it is a question nobody asked.
Show child attributes
Show child attributes
Present only on the answer to an act. true means the gateway was re-read afterwards and everything above is what it said. false means the act happened and the copy above is not (or not entirely) the gateway's answer — either the re-read did not get through, or it did and part of it could not be written down. mirror_stale_reason says which. Treat it as a reason to read again, never as a sign the act failed.
Present whenever mirror_refreshed is, and null when it is true — an absent field would leave you inferring that nothing is wrong.
provider_reread_failed — the gateway was not reachable after it accepted the act. Nothing above was updated; read again.
price_not_mapped_to_provider — the gateway named a price that is not mapped onto any price in this catalogue for this environment, so plan_id was left as it was while everything else was applied. This one matters: entitlements are computed from the plan, so until you map the price (see unmapped_provider_price_id) the customer keeps the plan they were on. Prices created in the gateway's own dashboard are the usual cause.
subscription_has_extra_lines — the gateway holds more priced lines than one, so which of them names the plan is not decidable and both plan_id and items were left as they were.
provider_reread_failed, price_not_mapped_to_provider, subscription_has_extra_lines, null The gateway's own price id to map, when mirror_stale_reason is price_not_mapped_to_provider. Null otherwise.