Skip to content

by Startups.Studio

Finance Subscription

Subscription.switch

POST /{namespace}/subscriptions/{subscription}/switch

Switch moves a Subscription to another Offer and prorates the current period.

Noun: Subscription
Mode: do
Event: Subscription.switched

You, to your agent

Switch the latest subscription with an offer.

curl -X POST https://api.sb/shiftnote.app/subscriptions/subscription_1/switch \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"offer":"offer_1"}'

import { $ } from 'startup-builder'

const subscription = await $.Subscription.switch({ subscription: 'subscription_1', offer: 'offer_1' })

npx startup-builder do Subscription.switch --json '{"subscription":"subscription_1","offer":"offer_1"}'

{
  "name": "do",
  "arguments": {
    "code": "return await $.Subscription.switch({ subscription: 'subscription_1', offer: 'offer_1' })"
  }
}

Inputs

Input	Type	Required	Description
`subscription`	Subscription	required	The Subscription to move.
`offer`	Offer	required	The Offer to move to.
`effectiveAt`	`datetime`		When the move takes effect; moving existing Customers to a higher Price waits at least the notice period.

Outputs

Output	Type	Required	Description
`subscription`	Subscription	required	The Subscription on its new Offer.

Effects

Emits Subscription.switched.
Performed by the Billing Specialist.
Two-way: it runs at once, in the try, send and do modes.
Bills or credits the prorated difference at once.
Moving existing Customers to a higher Price sends notice and switches each at its first renewal after the notice period.
A move to a cheaper Offer runs at once, with no Limit, Approval or delay window.

Refuses when

Check	Error	Fix	Then call
The input does not match the schema of the operation.	`invalid-input`	Read the schema of the operation, then send every required field with the right type.	Subscription.switch
The operation is part of an Offer the caller has not accepted or paid for.	`payment-required`	Accept the Offer named in the response, then retry the call.	Offer.accept
The key is valid, but its scopes do not allow this operation.	`forbidden`	Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them.	Subscription.switch
The record is not in a state that allows this Verb, so the call is refused.	`refused`	Read the record, run the Verb that moves it to an allowed state, then retry.	Subscription.switch

When it waits

Gate	Default
Decision class	Low: two-way, nothing at stake
Delay window	None: it runs once review passes.
Limit	The call Limit of the Permission it runs under.
Over the Limit	It waits `pending` for an Approval from the Founder. Approved, it runs; refused, it ends `refused` with `limit-exceeded`; unanswered by its deadline, it ends `canceled`.

Subscription.resume

Previous Page

Subscription.unsubscribe

Next Page