Billing and bought Servers

Plans, checkout, add-ons, upgrades and invoices on the Hosted instance, and Servers bought from Cloudgate.

Applies to: Hosted only

Billing on the Hosted instance: the plan an Organization holds, checkout and the customer portal, Add-ons, trials and invoices. Bought Servers are Servers you buy from Cloudgate, billed monthly on the same invoice.

Every request goes to https://cloudgate.octabyte.app/backend on the Hosted instance, or to your console address followed by /backend when you self-host. Send a Personal key in x-api-key and the Organization in x-organization-id; Authentication shows how to make the key, and Errors explains every refusal. The examples setCLOUDGATE_KEY and CLOUDGATE_ORG_ID in the shell first. To do the same in the console, read Billing in the user guide.

Billing

Get standing

GET/billing/standing

Whether the Organization is frozen and why, and whether a payment has failed while Stripe retries: what the banner every member sees reads. Any member; empty on a Self-hosted instance.

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 You may not reach what it touches. The error body.

curl https://cloudgate.octabyte.app/backend/billing/standing \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Get subscription

GET/billing/subscription

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 You may not reach what it touches. The error body.

curl https://cloudgate.octabyte.app/backend/billing/subscription \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Get attached organizations

GET/billing/attached-organizations

The "Organizations on this plan" card: whether "Add an Organization to this plan" is offered and why not, how much of the pool is free, and each Organization this one pays for.

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 You may not reach what it touches. The error body.

curl https://cloudgate.octabyte.app/backend/billing/attached-organizations \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Get attached plan

GET/billing/attached-plan

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 You may not reach what it touches. The error body.

curl https://cloudgate.octabyte.app/backend/billing/attached-plan \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Stop paying

POST/billing/attached-organizations/{organizationId}/stop-paying

"Stop paying for it": detaches an Organization this one pays for, which lapses at once — see StopPaying. Owner or admin of the Paying Organization. Also the "Before <Paying> can move to Starter" checklist's Detach. Allowed while the Paying Organization is frozen (detach): it only takes an Organization off a plan nobody is paying.

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Parameters

Name	In	Type	Notes
`organizationId`required	path	string	The Organization's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 You may not reach what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/billing/attached-organizations/qFZkBHdCtz5umFauNio7A/stop-paying \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Get current plan

GET/billing/plan

The plan the organization holds now, and a waiting move's date; any member.

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 You may not reach what it touches. The error body.

curl https://cloudgate.octabyte.app/backend/billing/plan \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Get catalogue

GET/billing/products

Both plans and the Add-on, as Stripe prices them.

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 You may not reach what it touches. The error body.

curl https://cloudgate.octabyte.app/backend/billing/products \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Get invoices

GET/billing/invoices

The organization's Stripe invoices.

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 You may not reach what it touches. The error body.

curl https://cloudgate.octabyte.app/backend/billing/invoices \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Can create more servers

GET/billing/can-create-server

Whether one more Server fits the allowance, with the refusal's code and sentence when not; any member.

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 You may not reach what it touches. The error body.

curl https://cloudgate.octabyte.app/backend/billing/can-create-server \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Create checkout session

POST/billing/checkout

Starts a Stripe Checkout session for the chosen plan and its Add-ons.

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Request body

Field	Type	Notes
`addOns`required	integer	0 to 1000.
`plan`required	string	One of `starter`, `business`.
`returnTo`	string	Up to 2000 characters.

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 You may not reach what it touches. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/billing/checkout \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "addOns": 0,
    "plan": "starter"
  }'

Create customer portal session

POST/billing/portal

Opens a Stripe customer-portal session.

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 You may not reach what it touches. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/billing/portal \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Set add ons

POST/billing/add-ons

Sets the existing subscription's Add-on quantity.

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Request body

Field	Type	Notes
`addOns`required	integer	0 to 1000.

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 You may not reach what it touches. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/billing/add-ons \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "addOns": 0
  }'

Preview upgrade

GET/billing/upgrade-preview

What upgrading Starter to Business charges today and every month after, from Stripe's invoice preview.

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 You may not reach what it touches. The error body.

curl https://cloudgate.octabyte.app/backend/billing/upgrade-preview \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Upgrade

POST/billing/upgrade

Upgrades Starter to Business at once, charging the previewed amount. Not allowed while frozen: a Frozen Organization has no plan to upgrade.

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Request body

Field	Type	Notes
`prorationDate`required	integer	At least 0. More than true.

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 You may not reach what it touches. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/billing/upgrade \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "prorationDate": 0
  }'

Get downgrade impact

GET/billing/downgrade-impact

What moving to Starter stops, against what the Organization uses: its SSO providers and SSO-only people, SCIM connections, custom-role holders and protected apps.

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 You may not reach what it touches. The error body.

curl https://cloudgate.octabyte.app/backend/billing/downgrade-impact \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Downgrade

POST/billing/downgrade

Moves Business to Starter at the end of the paid month; nothing is charged. Not allowed while frozen, as the upgrade.

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 You may not reach what it touches. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/billing/downgrade \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Keep business

DELETE/billing/downgrade

"Keep Business": takes a waiting downgrade back, at no charge.

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 You may not reach what it touches. The error body.

curl -X DELETE https://cloudgate.octabyte.app/backend/billing/downgrade \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Cancel trial

POST/billing/cancel-trial

"Cancel trial": the plan ends with the free trial, and nothing is charged. Owner/admin, during a trial only.

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 You may not reach what it touches. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/billing/cancel-trial \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Keep trial

DELETE/billing/cancel-trial

"Keep <plan>": takes a cancelled trial's cancel back.

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 You may not reach what it touches. The error body.

curl -X DELETE https://cloudgate.octabyte.app/backend/billing/cancel-trial \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Update invoice notifications

PATCH/billing/invoice-notifications

Turns invoice mail on or off.

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Request body

Field	Type	Notes
`enabled`required	boolean

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 You may not reach what it touches. The error body.

curl -X PATCH https://cloudgate.octabyte.app/backend/billing/invoice-notifications \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "enabled": true
  }'

Bought Servers

Check whether buying a Server is offered

GET/bought-servers/offer

Whether Buy a Server is offered here.

Who can call it: Owner or Admin. Needs server: read, which a custom role can also grant.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl https://cloudgate.octabyte.app/backend/bought-servers/offer \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

List locations, sizes and prices

GET/bought-servers/catalogue

Every Location and every size with its tidy monthly price and availability.

Who can call it: Owner or Admin. Needs server: create, which a custom role can also grant.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl https://cloudgate.octabyte.app/backend/bought-servers/catalogue \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Price a purchase today

GET/bought-servers/today

The Today box: what Buy would charge now for this size there, and the dates it covers.

Who can call it: Owner or Admin. Needs server: create, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`serverType`required	query	string	Not empty.
`location`required	query	string	Not empty.
`backups`	query	string	One of `true`, `false`.
`storageGb`	query	number

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl "https://cloudgate.octabyte.app/backend/bought-servers/today?serverType=example&location=example" \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

List Bought Servers

GET/bought-servers/purchases

The Organization's Bought Servers not yet made: waiting for payment, or being created.

Who can call it: Owner or Admin. Needs server: read, which a custom role can also grant.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl https://cloudgate.octabyte.app/backend/bought-servers/purchases \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Buy a Server

POST/bought-servers

Buy: charged at once; the machine is asked for only once the payment succeeds.

Who can call it: Owner or Admin. Needs server: create, which a custom role can also grant.

Request body

Field	Type	Notes
`serverType`required	string	Not empty.
`location`required	string	Not empty.
`name`	string	Up to 100 characters.
`backups`	boolean
`storageGb`	integer	10 to 10240.
`termsAccepted`required	boolean	One of `true`.
`prorationDate`required	integer	At least 0. More than true.
`returnTo`	string	Up to 2000 characters.

Responses

201 Created: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/bought-servers \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "serverType": "example",
    "location": "example",
    "termsAccepted": true,
    "prorationDate": 0
  }'

Finish paying for a purchase

POST/bought-servers/{id}/finish-paying

Finish paying*: where the payment stands, and where to finish it (3D Secure).

Who can call it: Owner or Admin. Needs server: create, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Bought Server's id.

Request body

Field	Type	Notes
`returnTo`	string	Up to 2000 characters.

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/bought-servers/RAU6yAYUXFRdXdPLyLoPC/finish-paying \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "returnTo": "example"
  }'

Cancel an unpaid purchase

POST/bought-servers/{id}/cancel

Cancel a purchase still waiting for payment: nothing is charged. A removal, so a frozen Organization may still do it.

Who can call it: Owner or Admin. Needs server: create, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Bought Server's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/bought-servers/RAU6yAYUXFRdXdPLyLoPC/cancel \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Get a Bought Server

GET/bought-servers/{id}

The Bought Server behind a Server: its stage, what it holds and its prices.

Who can call it: Owner or Admin. Needs server: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Bought Server's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl https://cloudgate.octabyte.app/backend/bought-servers/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Set backups

PUT/bought-servers/{id}/backups

Backups on (charged at once, for the rest of the plan's month) or off (every backup deleted at once, credited on the next invoice). Off only lowers what is owed, so a frozen Organization may still do it; on is refused while frozen, by the service.

Who can call it: Owner or Admin. Needs server: create, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Bought Server's id.

Request body

Field	Type	Notes
`enabled`required	boolean

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X PUT https://cloudgate.octabyte.app/backend/bought-servers/RAU6yAYUXFRdXdPLyLoPC/backups \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "enabled": true
  }'

Grow storage

PUT/bought-servers/{id}/storage

Extra storage grown: charged at once for the rest of the plan's month, then the Volume and the filesystem are grown. It never shrinks.

Who can call it: Owner or Admin. Needs server: create, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Bought Server's id.

Request body

Field	Type	Notes
`sizeGb`required	integer	10 to 10240.

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X PUT https://cloudgate.octabyte.app/backend/bought-servers/RAU6yAYUXFRdXdPLyLoPC/storage \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "sizeGb": 10
  }'

List sizes a Server can move to

GET/bought-servers/{id}/sizes

The sizes the Server can move to in its Location, with their prices.

Who can call it: Owner or Admin. Needs server: read, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Bought Server's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl https://cloudgate.octabyte.app/backend/bought-servers/RAU6yAYUXFRdXdPLyLoPC/sizes \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Set size

PUT/bought-servers/{id}/size

A new size, up (charged at once, for the rest of the plan's month) or down (credited on the next invoice); the machine is powered off while it changes. Down only lowers what is owed, so a frozen Organization may still do it; up is refused while frozen, by the service.

Who can call it: Owner or Admin. Needs server: create, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Bought Server's id.

Request body

Field	Type	Notes
`serverType`required	string	Not empty.

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X PUT https://cloudgate.octabyte.app/backend/bought-servers/RAU6yAYUXFRdXdPLyLoPC/size \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "serverType": "example"
  }'

Something missing or wrong on this page? Email support@octabyte.io, or start a free trial and try it in the console.