Remotehost Docs
API ReferenceAdd-ons

Change an add-on's quantity

PATCH
/orgs/{orgId}/addons/{listingId}/purchase

For an add-on sold per unit. An increase is charged now for the rest of the period and applies once paid (pendingQuantity meanwhile, with confirmationUrl when it needs confirming); a decrease credits the rest of the period and applies at once. Asking again for a change Stripe never received sends it again. Needs billing.manage. Audited.

Authorization

bearerAuth
AuthorizationBearer <token>

A RemoteHost API key (rh_sk_...) or a user session token.

In: header

Path Parameters

orgId*string
listingId*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/orgs/string/addons/string/purchase" \  -H "Content-Type: application/json" \  -d '{    "quantity": 0  }'
{  "purchase": {    "id": "string",    "listingId": "string",    "status": "pending",    "source": "billing",    "quantity": 0,    "pendingQuantity": 0,    "startedAt": "string",    "endsAt": "string",    "endedAt": "string"  },  "confirmationUrl": "string"}

Buy an add-on POST

Adds the add-on to the org's subscription, charged now for the rest of the period. The purchase is `pending` until Stripe has the payment; when the payment needs confirming, `confirmationUrl` is the invoice's page, and an unpaid purchase expires after 24 hours. Asking again for a pending purchase Stripe never received sends it again, with no second charge. Buying a cancelled add-on again before its `endsAt` keeps it with no second charge, at the quantity held, while the billing period is unchanged. Needs `billing.manage`, a live plan that is not trialing and has no scheduled change, and an org that is billed. Free and included add-ons are not sold. One add-on change per org at a time. Audited.

Cancel an add-on DELETE

Cancels at the end of the paid period: nothing is refunded or charged, the add-on stays until `endsAt`, and it does not renew. Allowed while the org's payment is failing too, so a recovery does not renew it. Buying it again before `endsAt` keeps it with no second charge. Needs `billing.manage`; allowed whatever the listing's state or the org's policy. Answers 200 only with the cancel in place. Audited.