Offer codes, free trials and entitlements

Three related but separate things live under AnythinkPay's /me/* surface: offers (referral codes and promotions), the app engagement trial (free access before any subscription), and entitlements (the one check your app makes to gate a feature). This page covers all three, plus user balances if your project uses account credit.

Offers and offer codes

An offer is a referral or promotional programme: a set of codes, an eligibility rule, and a reward. AnythinkPay lazily creates a default referral offer for a project the first time someone asks for their personal code, so a project with no offers configured still works.

In the Anythink dashboard

AnythinkPay › Offers (reached from the AnythinkPay hub) lists offers, each code's owner and redemption count, and every redemption with its redeemer and referrer.

With the CLI

anythink fetch /integrations/anythinkpay/offers
anythink fetch /integrations/anythinkpay/offers --method POST --body \
  '{"kind":"referral","name":"Referral programme","is_active":true}'
anythink fetch /integrations/anythinkpay/offers/{id}/codes
anythink fetch /integrations/anythinkpay/offers/redemptions

With an AI assistant (MCP)

List redemptions for the referral offer on this project.

A subscriber's own codes and referrals

Your app calls these as the logged-in user — they're gated on the subscriber-level permission anythink_subscription_plans:read, not the admin anythink_offers:read, specifically so a mobile app's own JWT can call them without administrator rights:

GET  /org/{orgId}/integrations/anythinkpay/offers/me/code       # this user's code for the default referral offer
GET  /org/{orgId}/integrations/anythinkpay/offers/me/codes      # this user's code for every active referral offer
POST /org/{orgId}/integrations/anythinkpay/offers/me/redeem/{slug}
GET  /org/{orgId}/integrations/anythinkpay/offers/me/referrals  # this user's referral stats + personal code slug

me/redeem/{slug} optionally takes ?subscription_id= when the redemption should apply against a specific subscription (for example a plan-gated code). Eligibility is evaluated against the redeeming user's currently active subscriptions — which plans, and the highest plan tier — resolved server-side, not something your app has to compute.

Limit: On a user's first launch, call /me/code before /me/referrals rather than firing them in parallel. The first call creates the user's personal codes; waiting for it avoids a race when both requests try to create them at once.

Free trials

There are two distinct "trial" concepts — don't conflate them:

• A plan's own trial (trial_period_days on a SubscriptionPlan) delays the first charge after a subscriber checks out — covered in Create plans and manage subscriptions.
• The app engagement trial is Anythink-owned, plan-independent free access for a user who has never subscribed to anything. It's gated on a project setting (AppEngagementTrialEnabled) and a length in days (AppEngagementTrialDays), both currently set through project settings rather than a dedicated dashboard page. It starts the first time a never-subscribed user calls /me/entitlement (a deliberate side effect — that's "first app use"), and never restarts once started. Offer redemptions can add bonus days to it via trial_bonus_days on the offer's reward configuration.

A local check against a fresh project with the app engagement trial not enabled: GET /subscriptions/me/entitlement for a never-subscribed user returned has_access: false, is_trial: false, trial_length_days: 7 (the configured length, unused because the trial toggle is off) — confirming the toggle, not just the day count, gates whether the trial actually starts.

Entitlements

One endpoint answers "can this user access the paid feature right now", across Stripe, Apple, and the app engagement trial:

GET /org/{orgId}/integrations/anythinkpay/subscriptions/me/entitlement

{
  "has_access": true,
  "subscription_id": "b6b8...",
  "provider": "stripe",
  "product_id": "Pro monthly",
  "status": "trialing",
  "expires_at": "2026-10-06T17:49:06Z",
  "trial_length_days": 0,
  "pending_product_id": null
}

• If the user has never subscribed, this resolves the app engagement trial instead (see above) and the subscription-specific fields are null.
• If the user has multiple subscriptions (for example, an old Apple subscription and a new Stripe one), it returns the strongest current entitlement — preferring one that currently grants access, then the one that runs longest.
• pending_product_id / pending_at surface an Apple downgrade that's scheduled but hasn't taken effect yet (DID_CHANGE_RENEWAL_PREF / DOWNGRADE) — useful for showing "switching to X on your next renewal" in your app.

This is gated on anythink_subscription_plans:read, so a subscriber's own JWT can call it directly — you don't need an admin API key in your mobile or web client.

User balances

If your project uses account credit (store credit, referral rewards paid as balance rather than trial days), a subscriber reads their own balance the same way — subscriber-level permission, not admin:

GET /org/{orgId}/integrations/anythinkpay/balances/me

Administrators additionally have GET .../balances/users/{userId}, .../balances/users/{userId}/history, .../balances/tenant/holders, .../balances/tenant/activity, and POST .../balances/users/{userId}/adjust to manually credit or debit a user's balance — gated on anythink_balances:read / :update.

Note: Whether user balances are customer-facing depends on your app — AnythinkPay stores and lets you adjust them, but doesn't itself spend a balance against a charge. If your product model needs "pay with balance first, then card", that logic lives in your own workflow or backend, using the balance read/adjust endpoints above.

Permissions

Next steps