Recoup

Get started with Recoup.

Try Our Platform

Use Recoup’s AI tools for your artists, releases, and catalog.

Build Your Platform

Our team builds custom AI software for your business.

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.

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

Kept in this browser tab only and cleared when it closes.

cURL for this request
curl --request GET \
  --url 'https://api.recoupable.dev/api/accounts/{id}/subscription'

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 only for effective Pro entitlement. A paid Starter account returns false. Use plan for paid-plan decisions.

statusstring · enumrequired

Current entitlement view. Resolving to Free returns none and null billing fields, including for an inactive subscription; this is not subscription lifecycle history.

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

Example: "active"

planstring | nullrequired

Plan identifier (e.g. pro). Null when no subscription currently confers a paid plan.

Values: "starter", "pro", null

Example: "pro"

sourcestring | nullrequired

Origin of the subscription. account for direct, organization when covered by an organization. Null when no subscription currently confers a paid plan.

Values: "account", "organization", null

Example: "account"

namestring | nullrequired

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

Example: "Pro"

amountCentsinteger | nullrequired

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

Example: 9900

currencystring | nullrequired

ISO 4217 currency code, lowercase.

Example: "usd"

intervalstring | nullrequired

Billing interval of the recurring price.

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

Example: "month"

collectionMethodstring | nullrequired

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", null

Example: "charge_automatically"

currentPeriodEndstring | nullrequired

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

Example: "2026-10-04T00:00:00Z"

format: date-time

No paid entitlement

free
{
  "isPro": false,
  "status": "none",
  "plan": null,
  "source": null,
  "name": null,
  "amountCents": null,
  "currency": null,
  "interval": null,
  "collectionMethod": null,
  "currentPeriodEnd": null
}

Paid Starter, not Pro

starter
{
  "isPro": false,
  "status": "active",
  "plan": "starter",
  "source": "account",
  "name": null,
  "amountCents": null,
  "currency": null,
  "interval": null,
  "collectionMethod": null,
  "currentPeriodEnd": null
}

Direct Pro

directPro
{
  "isPro": true,
  "status": "active",
  "plan": "pro",
  "source": "account",
  "name": null,
  "amountCents": null,
  "currency": null,
  "interval": null,
  "collectionMethod": null,
  "currentPeriodEnd": null
}

Organization Pro overrides account Starter

organizationPro
{
  "isPro": true,
  "status": "active",
  "plan": "pro",
  "source": "organization",
  "name": null,
  "amountCents": null,
  "currency": null,
  "interval": null,
  "collectionMethod": null,
  "currentPeriodEnd": null
}

Canceled subscription: current entitlement is none

inactive
{
  "isPro": false,
  "status": "none",
  "plan": null,
  "source": null,
  "name": null,
  "amountCents": null,
  "currency": null,
  "interval": null,
  "collectionMethod": null,
  "currentPeriodEnd": null
}

401Unauthorized - invalid or missing authentication

application/json

errorstringrequired

Human-readable error message.

Example: "Account not found"

401 example
{
  "error": "Unauthorized"
}

403Forbidden - account not accessible to the authenticated account

application/json

errorstringrequired

Human-readable error message.

Example: "Account not found"

404Account not found

application/json

errorstringrequired

Human-readable error message.

Example: "Account not found"

Full specification

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

Download accounts.json
View operation source
json
{
  "operationId": "getAccountsByIdSubscription",
  "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"
          },
          "examples": {
            "free": {
              "summary": "No paid entitlement",
              "value": {
                "isPro": false,
                "status": "none",
                "plan": null,
                "source": null,
                "name": null,
                "amountCents": null,
                "currency": null,
                "interval": null,
                "collectionMethod": null,
                "currentPeriodEnd": null
              }
            },
            "starter": {
              "summary": "Paid Starter, not Pro",
              "value": {
                "isPro": false,
                "status": "active",
                "plan": "starter",
                "source": "account",
                "name": null,
                "amountCents": null,
                "currency": null,
                "interval": null,
                "collectionMethod": null,
                "currentPeriodEnd": null
              }
            },
            "directPro": {
              "summary": "Direct Pro",
              "value": {
                "isPro": true,
                "status": "active",
                "plan": "pro",
                "source": "account",
                "name": null,
                "amountCents": null,
                "currency": null,
                "interval": null,
                "collectionMethod": null,
                "currentPeriodEnd": null
              }
            },
            "organizationPro": {
              "summary": "Organization Pro overrides account Starter",
              "value": {
                "isPro": true,
                "status": "active",
                "plan": "pro",
                "source": "organization",
                "name": null,
                "amountCents": null,
                "currency": null,
                "interval": null,
                "collectionMethod": null,
                "currentPeriodEnd": null
              }
            },
            "inactive": {
              "summary": "Canceled subscription: current entitlement is none",
              "value": {
                "isPro": false,
                "status": "none",
                "plan": null,
                "source": null,
                "name": null,
                "amountCents": null,
                "currency": null,
                "interval": null,
                "collectionMethod": null,
                "currentPeriodEnd": null
              }
            }
          }
        }
      }
    },
    "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"
          }
        }
      }
    }
  }
}