Overview

Article-level entitlements are an extension of issue-based authentication that allow you to control access to individual pieces of content, rather than at the collection or timeline level.

When a user attempts to access a piece of content, the app checks their entitlements against those defined on the card. If a match is found, the user is granted access. If not, the paywall is shown.

This is useful for scenarios such as:

• Giving subscribers access to a specific edition's content without granting access to the whole app
• Restricting premium articles to users with a particular subscription tier
• Controlling access to imported or syndicated content on a per-item basis

How It Works

Article-level entitlements work by adding an entitlements array to each card in your content feed. The values in this array must correspond to the entitlements returned in your verify response.

Example JSON feed entry:

{
    "id": "page-6604",
    "type": "article",
    "title": "My Article",
    "entitlements": [
        "com.example.premium",
        "com.example.edition0003"
    ],
    "paywall_locked": true
}

Access rules:

Note: paywall_locked is still supported for backwards compatibility with older feeds and will continue to work if entitlements is not present.

Setting Up Card-level Entitlements

Step 1: Configure your content feed

Each card that should be access-controlled needs an entitlements array in its feed output, containing the relevant issue IDs that correspond to your verify response. This is typically handled by your CMS or content pipeline.

Step 2: Set entitlements in Express (Optional)

If you are manually using Pugpig Express as your CMS, add the following WordPress custom field to each post:

To apply multiple entitlements to a single piece of content, add multiple pugpig_article_entitlements custom field entries — one per entitlement value.

Step 3: Ensure your verify response includes the entitlements

Your authentication provider's verify response must return the relevant issue IDs in the <issues> block. For example:

<subscription state="active">
    <issues>
        <issue>com.example.premium</issue>
        <issue>com.example.edition0003</issue>
    </issues>
</subscription>

When a user logs in, the app will compare their issued entitlements against the entitlements array on each card to determine access.

Analytics

For analytics purposes, the presence of a non-empty entitlements array on a card (or the paywall_locked field, for backwards compatibility) means the card is treated as paid content.

Platform Support

Card-level entitlements are supported across all Pugpig Bolt platforms:

Known Limitations

• Timeline Layouts: Card-level entitlements cannot currently be applied via Timeline Layout position overrides. Entitlements are resolved early in the render pipeline, while layout overrides are applied later — these two processes do not merge.
• Marketing visibility + entitlements: It is not currently possible to combine marketing visibility with card-level entitlements (for example, showing a card only to signed-out users and a specific entitlement group simultaneously). Please speak to us if this is a requirement.

Related Articles

• Authentication in Pugpig Bolt
• In-app purchases and cross entitlement
• In-app subscription levels
• Bolt Metered Paywall

🔒 INTERNAL NOTES — Do not publish

The following information is for internal Pugpig team reference only and should not appear in the customer-facing version of this document.

Terminology: The feature was originally called "article-level entitlements" but was formally renamed to "card-level entitlements" (TU-2639) because it applies to all card types, not just articles. Both terms are still in active use internally and with customers.

Web support: Web support was not available until BOLT-11756 (Article-level entitlements — Web), which is currently Ready for Release as of Feb 2026. Ensure this has shipped before publishing web support in the doc.

Server spec: The authoritative server spec is BOLT-8286. This is the source of truth for the feed format and access logic.

Known client use cases: ACBJ (different access levels per article), Euromoney (China Report access), Argus, JFM (edition content entitlements via Aptoma/Kodus importers using format dk.{site}.eedition.{edition_id}), Burlington Media.

"Not entitlement" logic: There is currently no support for inverse entitlement logic (e.g. showing a card only to users who don't have a given entitlement). This has been discussed internally as a potential future feature (#product-development thread, March 2025).

Bolt version availability:

• iOS: Bolt 3.21+
• Android: Bolt 3.20.3+
• Web: Pending release of BOLT-11756