What this credential may call

What this credential is allowed to do with this newsletter, and what it would be told if it tried something it is not. Needs settings: read.

Two things in this API can be put behind a plan, and both answer 402 when they are: writing, every operation that changes something, and insights, the engagement and metrics operations, whose numbers are computed rather than looked up. Every other read is free on every plan.

Read this at the start of a run rather than discovering a 402 in the middle of one. Each entry in api_access carries the plan list the refusal would put in allowed_values and the sentence it would put in message.

granted is the field to branch on: true when the call would be allowed at this moment. included is the longer view, whether the newsletter's plan carries the feature at all, and the two differ only while Commune is not charging for it. Read included to warn a creator before a bill starts; read granted to decide whether to make the next call.

Never itself refused for payment, so it declares no 402.

get/newsletters/{newsletter}/entitlements

Request

Base URL: https://api.usecommune.com
URL: https://api.usecommune.com/newsletters/{newsletter}/entitlements
Auth: one of:
- HTTP bearer
- OAuth 2 (authorization code, authorization URL https://usecommune.com/api/oauth/authorize, token URL https://usecommune.com/api/oauth/token, scopes: settings:read)

Query parameters

expandstring

Comma-separated list of relationship paths to inline in the response. Unexpanded relationships are returned as a reference object carrying only id and object. Each operation documents the paths it accepts, and an unknown path answers 400. Nested paths use a dot, for example article.newsletter.

fieldsstring

Comma-separated allow-list of top level properties to return on each object, so a client can trim a response it does not need in full. id and object are always returned. An unknown property name answers 400. Properties omitted by an operation, such as content on any article list, cannot be brought back with fields.

Response

What this newsletter's plan includes, and what a credential on it may call.

object'entitlements' required

Always entitlements.

planstring nullable required

The Commune plan this newsletter is on, or null when it has none on record. Most newsletters connected to an outside provider have none, which is not an error and is why this is nullable rather than absent.

Not an enum. Plan names are a commercial decision that moves faster than a contract version, and a client that switched on this value would break on the next one Commune offers. What to branch on is api_access, which answers the question a plan name is a proxy for.

statusstring nullable required

The state of the newsletter's subscription, or null alongside a null plan. Also not an enum, for the same reason. A subscription whose payment is merely late still carries every capability its plan does, so do not infer a refusal from this field: read granted.

Example response

{
  "newsletter": {
    "object": "newsletter",
    "id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
  }
}

Changes

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