Subscription Owner Control

Subscription Owner Control

Purpose: allow account owners to inspect plans and execute subscription lifecycle actions.

UI Flow

1. User opens billing page for token-selected account.
2. UI loads GET /api/subscriptions.
3. UI loads GET /api/subscriptions/features.
4. UI loads GET /api/subscriptions/identity.
5. UI loads GET /api/subscriptions/merchants.
6. UI creates checkout or portal sessions when owner starts billing actions.
7. UI runs sync/change/cancel actions from explicit owner actions.

Client Library Flow

const subs = await api.subscriptions.list();
const features = await api.subscriptions.features();
const merchants = await api.subscriptions.merchants();

const checkout = await api.subscriptions.createCheckoutSession({
  price_id,
  success_url,
  cancel_url,
});

await api.subscriptions.change(subscriptionId, {
  interval: "year",
});

HTTP/curl Flow

API_BASE_URL="https://api.inbox-manager.com"

curl -sS "${API_BASE_URL}/api/subscriptions" \
  -H "authorization: Bearer ${BEARER_TOKEN}"

curl -sS "${API_BASE_URL}/api/subscriptions/features" \
  -H "authorization: Bearer ${BEARER_TOKEN}"

curl -sS "${API_BASE_URL}/api/subscriptions/identity" \
  -H "authorization: Bearer ${BEARER_TOKEN}"

curl -sS "${API_BASE_URL}/api/subscriptions/merchants" \
  -H "authorization: Bearer ${BEARER_TOKEN}"

curl -sS -X POST "${API_BASE_URL}/api/subscriptions/stripe/checkout-session" \
  -H "authorization: Bearer ${BEARER_TOKEN}" \
  -H "content-type: application/json" \
  --data "{\"price_id\":\"${PRICE_ID}\",\"success_url\":\"${SUCCESS_URL}\",\"cancel_url\":\"${CANCEL_URL}\"}"

curl -sS -X POST "${API_BASE_URL}/api/subscriptions/stripe/portal-session" \
  -H "authorization: Bearer ${BEARER_TOKEN}" \
  -H "content-type: application/json" \
  --data "{\"return_url\":\"${RETURN_URL}\"}"

curl -sS -X POST "${API_BASE_URL}/api/subscriptions/sync?allow_deletes=false" \
  -H "authorization: Bearer ${BEARER_TOKEN}" \
  -H "content-type: application/json" \
  --data '{}'

curl -sS -X POST "${API_BASE_URL}/api/subscriptions/${SUBSCRIPTION_ID}/change" \
  -H "authorization: Bearer ${BEARER_TOKEN}" \
  -H "content-type: application/json" \
  --data '{"interval":"month"}'

curl -sS -X POST "${API_BASE_URL}/api/subscriptions/${SUBSCRIPTION_ID}/cancel" \
  -H "authorization: Bearer ${BEARER_TOKEN}" \
  -H "content-type: application/json" \
  --data '{"timing":"period_end"}'

curl -sS -X POST "${API_BASE_URL}/api/subscriptions/stripe/checkout-session-sync" \
  -H "authorization: Bearer ${BEARER_TOKEN}" \
  -H "content-type: application/json" \
  --data "{\"session_id\":\"${SESSION_ID}\"}"

Notes

• Subscription routes are accountless; account context comes from JWT acc.
• Owner authorization is enforced by upstream auth subscription endpoints.
• inbox-manager forwards the user bearer token directly.
• Stripe webhook callbacks are not proxied through inbox-manager.