API REFERENCE

Get Account Subscription

On this page

GET/api/accounts/{id}/subscription

Retrieve the subscription that confers an account's plan, directly or via an organization: isPro, status, plan, source, plus the billing fields name, amountCents, currency, interval, collectionMethod and currentPeriodEnd. Everything but isPro and status is null when status is none. id may be the authenticated account or an organization the caller belongs to.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL

curl --request GET \
  --url 'https://api.recoupable.dev/api/accounts/YOUR_ID/subscription' \
  --header 'x-api-key: YOUR_API_KEY'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Parameters

Path parameters

idstringrequired

The unique identifier (UUID) of the account. Must be the authenticated account or another accessible via organization membership.

Responses

200Subscription retrieved successfully

application/json

isProbooleanrequired

True when the account has an active paid subscription, directly or via an organization.

statusstring · enumrequired

Lifecycle state of the subscription. none when no subscription exists.

Values: "active", "trialing", "canceled", "past_due", "none"

planstringrequirednullable

Plan identifier (e.g. pro). Null when no subscription exists.

sourcestring · enumrequirednullable

Origin of the subscription. account for direct, organization when covered by an organization. Null when no subscription exists.

Values: "account", "organization"

namestringrequirednullable

Display name of the plan's Stripe price (nickname) or product. Null when no subscription exists.

amountCentsintegerrequirednullable

Recurring amount in the smallest currency unit (cents for USD). Null when no subscription exists.

currencystringrequirednullable

ISO 4217 currency code, lowercase.

intervalstring · enumrequirednullable

Billing interval of the recurring price.

Values: "day", "week", "month", "year"

collectionMethodstring · enumrequirednullable

charge_automatically bills the card on file at renewal; send_invoice emails an invoice that is paid manually (enterprise plans). A saved card is never charged for a send_invoice plan.

Values: "charge_automatically", "send_invoice"

currentPeriodEndstringrequirednullable

End of the current billing period: the renewal date, or the next invoice date for invoiced plans.

format: date-time

401Unauthorized - invalid or missing authentication

application/json

errorstringrequired

Human-readable error message.

401 example

{
  "error": "Unauthorized"
}

403Forbidden - account not accessible to the authenticated account

application/json

errorstringrequired

Human-readable error message.

404Account not found

application/json

errorstringrequired

Human-readable error message.

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download accounts.json

View operation source

json

{
  "description": "Retrieve the subscription that confers an account's plan, directly or via an organization: `isPro`, `status`, `plan`, `source`, plus the billing fields `name`, `amountCents`, `currency`, `interval`, `collectionMethod` and `currentPeriodEnd`. Everything but `isPro` and `status` is null when `status` is `none`. `id` may be the authenticated account or an organization the caller belongs to.",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "description": "The unique identifier (UUID) of the account. Must be the authenticated account or another accessible via organization membership.",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "responses": {
    "200": {
      "description": "Subscription retrieved successfully",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SubscriptionResponse"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized - invalid or missing authentication",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SubscriptionErrorResponse"
          },
          "example": {
            "error": "Unauthorized"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden - account not accessible to the authenticated account",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SubscriptionErrorResponse"
          }
        }
      }
    },
    "404": {
      "description": "Account not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SubscriptionErrorResponse"
          }
        }
      }
    }
  }
}