Get subscription status

GET

/v1/accounts/{accountId}/subscriptions

const url = 'https://api-v1.tailwind.ai/v1/accounts/example/subscriptions';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://api-v1.tailwind.ai/v1/accounts/example/subscriptions \
  --header 'Authorization: Bearer <token>'

Whether a Pinterest account currently has active, paying access, and what is backing it — normalized across Tailwind’s legacy and modular billing systems so callers never need to know which one the org is on.

entitled is the answer to “can this account use paid features right now”. Legacy orgs are billed org-wide and always report a single entry describing the org’s plan; modular orgs report one entry per entitlement the account currently holds, which may be several (e.g. Publishing and SEO), or none. A modular entitlement can come from a subscription or from a Tailwind-issued grant — source says which.

Only current entitlements are reported: ended subscriptions and expired grants are omitted rather than returned with entitled: false.

Authorizations

bearerAuth

Parameters

Path Parameters

accountId

required

string

Numeric Tailwind account ID returned by GET /v1/accounts

Responses

200

Subscription status

application/json

object

data

A Pinterest account’s current paying access, normalized across billing systems.

object

entitled

required

Whether the account currently has active, paying access. This is the field to check before relying on a paid capability.

boolean

billingSystem

required

Which billing system the owning organization is on. An org is on exactly one.

string

Allowed values: legacy modular shopify

subscriptions

required

The entitlements backing entitled. A legacy org always reports exactly one entry describing its org-wide plan. A modular org reports one entry per current entitlement — possibly several, possibly none.

Array<object>

One entitlement backing an account’s access.

object

source

required

What backs this entitlement: the org’s plan (legacy), a Maxio subscription, or a Tailwind-issued grant.

string

Allowed values: plan subscription grant

state

required

Billing-system state. Legacy reports the org’s Chargify subscription state (e.g. “active”, “past_due”); modular subscriptions report the Maxio state; grants report “granted”.

string

pendingCancellation

required

Whether a cancellation is scheduled but access continues through the paid period

boolean

currentPeriodEndsAt

required

Unix timestamp the current paid period ends, when known. Null for ordinary legacy plans, whose renewal date is not stored locally.

integer

nullable

productType

required

Modular only: the product domain this entitlement covers. Null on the legacy rail, which is not domain-scoped.

string

nullable

Allowed values: bundle seo engagement publishing

billingCycle

required

Modular subscriptions only. Null for legacy plans and for grants.

string

nullable

Allowed values: monthly annual

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "data": {
    "billingSystem": "legacy",
    "subscriptions": [
      {
        "source": "plan",
        "productType": "bundle",
        "billingCycle": "monthly"
      }
    ]
  }
}

400

Invalid request

application/json

object

error

object

code

Error code

string

message

Error message

string

reason

Machine-readable denial reason. Present on PAYMENT_REQUIRED errors: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded.

string

resolve_url

Present on PAYMENT_REQUIRED errors: where the denial can be resolved. Reason-specific, because buying credits does not clear a trial, access or connection denial. Requests sent with X-Request-Source: mcp receive an informational plans page instead, so agent surfaces never present a purchase link.

string

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request body"
  },
  "meta": {
    "requestId": "abc123"
  }
}

401

Authentication required or invalid bearer credentials

application/json

object

error

object

code

Error code

string

message

Error message

string

reason

Machine-readable denial reason. Present on PAYMENT_REQUIRED errors: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded.

string

resolve_url

string

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  },
  "meta": {
    "requestId": "abc123"
  }
}

404

Resource not found

application/json

object

error

object

code

Error code

string

message

Error message

string

reason

Machine-readable denial reason. Present on PAYMENT_REQUIRED errors: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded.

string

resolve_url

string

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Account not found"
  },
  "meta": {
    "requestId": "abc123"
  }
}

429

Rate limit exceeded

application/json

object

error

object

code

Error code

string

message

Error message

string

reason

Machine-readable denial reason. Present on PAYMENT_REQUIRED errors: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded.

string

resolve_url

string

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Daily rate limit of 5000 requests exceeded. Resets at midnight UTC."
  },
  "meta": {
    "requestId": "abc123"
  }
}