Subscription

Get the authenticated user subscription

Return the authenticated user posterly subscription summary: status, tier, cancel-at-period-end, current period end, trial end, and pause state. Includes connected account usage and the account limit for the workspace the caller is acting in. Also returns what to do next for this user: upgrade_options (plans above theirs with prices, limits and credits), next_steps (respecting status; a plan upgrade is the upgrade_subscription step, and billing_url is the fallback when an upgrade cannot be made from here; the upgrade step id is upgrade_plan, formerly change_plan) and, for an Agency workspace owner, extra_accounts. Requires the billing:read scope. This endpoint bypasses the API add-on paywall so a user can always inspect and manage their own subscription. Returns 404 no_subscription when the user has no subscription.

get/api/v1/subscription

Request

  • Base URL: https://www.poster.ly
  • URL: https://www.poster.ly/api/v1/subscription
  • Auth: HTTP bearer

Response

Subscription summary fetched successfully.

Example response

{
  "subscription": {
    "id": "sub_row_123",
    "status": "active",
    "tier": "pro",
    "cancel_at_period_end": false,
    "current_period_end": "2026-08-01T00:00:00.000Z",
    "trial_ends_at": null,
    "paused_at": null,
    "pause_resumes_at": null,
    "stripe_subscription_id": "sub_1P0abcXYZ",
    "accounts": {
      "workspace_id": "ws_123",
      "used": 4,
      "limit": 12
    },
    "upgrade_options": [
      {
        "tier": "power_user",
        "name": "Power",
        "monthly_price": 25,
        "yearly_price": 240,
        "max_accounts": 30,
        "included_credits": 2000
      },
      {
        "tier": "agency",
        "name": "Agency",
        "monthly_price": 49,
        "yearly_price": 470,
        "max_accounts": 100,
        "included_credits": 4000
      }
    ],
    "next_steps": [
      {
        "id": "upgrade_plan",
        "text": "To move up, call upgrade_subscription with tier set to the plan you want (plan upgrades only). The first call only returns the exact quote and what is charged today. Confirm only after the user agrees.",
        "tool": "upgrade_subscription",
        "params": {
          "tier": "power_user"
        }
      }
    ],
    "billing_url": "https://www.poster.ly/dashboard/account/billing"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.