---
title: "Your current plan, billing window and available changes (dashboard session required)"
method: GET
path: "/v1/subscription"
---

# Your current plan, billing window and available changes (dashboard session required)

`GET /v1/subscription`

## Request

- Base URL: `https://agentmandate-api.com`
- URL: `https://agentmandate-api.com/v1/subscription`
- Auth: API key in cookie `sp_session`

Reports the plan this account is on, the billing window it is in, any tier change already staged for the next invoice, and the full pricing ladder marked up so you can see which rungs are an upgrade and which a downgrade. `planChangesGoThrough` is the field to branch on: `self_serve` means POST /v1/subscription/plan can move you; `provider_managed` means Square’s own recurring subscription holds your price and neither this API nor a new checkout can move it — buying again would create a SECOND Square subscription and charge you twice; `checkout` appears only when you have no plan at all, where starting one is exactly right. All money is in integer minor units (cents). AUTHENTICATION IS YOUR DASHBOARD SESSION, NOT AN API KEY. Send the `@sp/core` session cookie this API sets when you sign in, from the same origin. An API key is refused here on purpose: it is a data-plane credential that lives in CI and in third-party integrations, and it must never be able to change what you are billed, cancel your account, or read your payment history. Errors: 401 `unauthenticated` when there is no valid session, 403 `forbidden` when the request is cross-origin or its `x-csrf-token` header is missing or wrong.

## Response `200`

Success

- object
  - `product` string
  - `subscribed` boolean: False when this account has never had a paid plan on this API.
  - `status` 'sandbox' | 'active' | 'past_due' | 'canceled': "sandbox" when there is no paid plan at all — the same vocabulary GET /v1/usage reports.
  - `plan` object, nullable: The tier in force right now.
  - `pendingPlan` object, nullable: A tier change already staged, applied when the current window is invoiced.
  - `planChangesGoThrough` 'self_serve' | 'provider_managed' | 'checkout': `self_serve` — POST /v1/subscription/plan moves you. `provider_managed` — Square holds your recurring price; the tier cannot be moved from here and starting a new checkout would duplicate the subscription. `checkout` — no plan yet, so POST /v1/checkout is where one starts.
  - `baseFeeOwner` 'internal' | 'provider': Who collects the flat monthly fee: us, or Square’s own recurring subscription.
  - `cancellation` object: What cancelling would do, stated before you do it.
  - `tiers` unknown[]: The published ladder, each rung marked current / upgrade / downgrade.
    - unknown
  - `requestId` string

## Other responses

- `400`: Deterministic error. Branch on `code`; quote `requestId` when reporting a problem.
- `401`: Deterministic error. Branch on `code`; quote `requestId` when reporting a problem.
- `403`: Deterministic error. Branch on `code`; quote `requestId` when reporting a problem.
- `409`: Deterministic error. Branch on `code`; quote `requestId` when reporting a problem.
- `500`: Deterministic error. Branch on `code`; quote `requestId` when reporting a problem.

---

[API](https://skmtc.dev/agentmandate-api/apis/agent-mandate.md) · [All operations](https://skmtc.dev/agentmandate-api/apis/agent-mandate/llms.txt) · [OpenAPI document](https://skmtc.dev/agentmandate-api/apis/agent-mandate/revisions/463fe122c4d8?raw)