Axuz Developers

POST /v1/teams/{teamId}/billing/subscriptions

Checkout Fase 91 (attach+create numa call)

  • 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`.

Is the Fase 91 "checkout" endpoint. Two flows collapse into this handler:

1. Team has no active subscription AND no payment method — the UI first opens the AddPaymentMethodModal, attaches via the Stripe endpoints above, then POSTs here with the fresh pm_id. We persist it as a payment_methods row (mirroring teamAttachStripePaymentMethod) and create the subscription. 2. Team already has a payment method — UI just POSTs {plan_id, billing_cycle[, payment_method_id]}. We skip the card dance and go straight to subscription creation.

Payload: {plan_id, billing_cycle, payment_method_id?}. The handler reuses teamUpgradeSubscription's logic for the create step so both endpoints stay behaviourally identical at the "add subscription" seam.

Parameters

NameInTypeRequiredDescription
teamIdpathstringyes

Request body

application/json · Required

NameTypeRequiredDescription
plan_idstring<uuid>yes
billing_cyclestringno

enum: "monthly", "yearly"

payment_method_idstring<uuid>no

UUID de payment_methods (não Stripe pm_*)

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

Responses

200

upgrade em vez de create

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

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/v1/teams/TEAM_ID/billing/subscriptions' \
  -H "Authorization: Bearer $AXUZ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"plan_id":"00000000-0000-0000-0000-000000000000","billing_cycle":"monthly","payment_method_id":"00000000-0000-0000-0000-000000000000"}'

Node.js

const res = await fetch("https://api-billing.axuz.net/v1/teams/TEAM_ID/billing/subscriptions", {
  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",
    "payment_method_id": "00000000-0000-0000-0000-000000000000"
  }),
});
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/v1/teams/TEAM_ID/billing/subscriptions",
    headers={
        "Authorization": f"Bearer {os.environ['AXUZ_TOKEN']}",
    },
    json={
        "plan_id": "00000000-0000-0000-0000-000000000000",
        "billing_cycle": "monthly",
        "payment_method_id": "00000000-0000-0000-0000-000000000000",
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())