Axuz Developers

POST /teams/{teamId}/billing/subscription/upgrade

Upgrade/downgrade OU criação com trial anti-farming

  • Access: Team admin
  • Service: https://api-billing.axuz.net

Accepted authentication

  • sessionCookie — Sessão plena Axuz (cookie de sessão da casa). Sessão restrita é 403 enrollment_required.
  • bearerSession — JWT de acesso da sessão em `Authorization: Bearer`.

Responde POST /teams/{teamId}/billing/ subscription/upgrade.

AUTORIZAÇÃO (G-030): owner/admin do time. Apesar do nome, a rota é a troca de plano do lado do cliente nos DOIS sentidos — passa qualquer plano para ApplyProration, inclusive um mais barato —, então é ela que atende "upgrade/downgrade dentro do app sem sair pro gateway". Membro comum recebe 403.

Dois modos: (1) já existe subscription → change-plan com proração (ApplyProration); (2) primeira vez → INSERT nova subscription (trial se aplicável e nunca teve; senão active). Trial anti-farming: só concede se a equipe nunca teve subscription (EXISTS). Efeitos: leituras + UPDATE ou INSERT em subscriptions.

Parameters

NameInTypeRequiredDescription
teamIdpathstringyes

Request body

application/json · Required

NameTypeRequiredDescription
plan_idstring<uuid>yes
billing_cyclestringno

enum: "monthly", "yearly"

{
  "plan_id": "00000000-0000-0000-0000-000000000000",
  "billing_cycle": "monthly"
}

Responses

200

upgrade aplicado

NameTypeRequiredDescription
okbooleanno
idstring<uuid>no
modestringno

enum: "upgrade"

prorationBillingProrationResultno
proration.change_kindstringno

enum: "upgrade", "downgrade", "cancel"

proration.credit_centsintegerno
proration.charge_centsintegerno
proration.net_centsintegerno
proration.invoice_idstring<uuid> | nullno
proration.proration_item_idstring<uuid>no

201

nova subscription criada

NameTypeRequiredDescription
okbooleanno
idstring<uuid>no
modestringno

enum: "create"

400

input inválido

NameTypeRequiredDescription
errorstringyes

401

Sem credencial valida

NameTypeRequiredDescription
errorstringyes

403

Sem permissao (nao e owner/admin; token sem escopo; token de integracao em rota nao permitida)

NameTypeRequiredDescription
errorstringyes

429

Limite de requisições excedido.

NameTypeRequiredDescription
errorstringyes

500

erro interno

NameTypeRequiredDescription
errorstringyes

Examples

"Try it" is turned off in this reference. Use the examples with your test credential.

curl

curl -sS -X POST 'https://api-billing.axuz.net/teams/TEAM_ID/billing/subscription/upgrade' \
  -H "Authorization: Bearer $AXUZ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"plan_id":"00000000-0000-0000-0000-000000000000","billing_cycle":"monthly"}'

Node.js

const res = await fetch("https://api-billing.axuz.net/teams/TEAM_ID/billing/subscription/upgrade", {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.AXUZ_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "plan_id": "00000000-0000-0000-0000-000000000000",
    "billing_cycle": "monthly"
  }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
console.log(await res.json());

Python

import os
import requests

res = requests.request(
    "POST",
    "https://api-billing.axuz.net/teams/TEAM_ID/billing/subscription/upgrade",
    headers={
        "Authorization": f"Bearer {os.environ['AXUZ_TOKEN']}",
    },
    json={
        "plan_id": "00000000-0000-0000-0000-000000000000",
        "billing_cycle": "monthly",
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())