Subscription grants

A Subscription grant gives an Account access to a Plan without that Account buying it. Use it for partner entitlements or promotional access. A grant can expire, and it can be revoked.

A grant is not a Subscription. To buy a Plan, see Plans and purchases.

Prerequisites

• users.subscription:read to read grants and users.subscription:write to create, change or revoke them.
• The ID of the Plan. For the Plans an Account can see, List subscription plans returns id, name, description, price, currency, interval (Monthly or Annual) and features. Get a subscription plan returns one.

Endpoints

Create a grant

curl -X POST https://api.wingspan.app/v3/platform/subscription-grants \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "X-Wingspan-Account: Nw7kQ2pLx9RtVb3mHc5dZa" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "Gh8kLm3QtV6xZc2nWd5RbP",
    "planId": "Zc6vKm2PxQ8tNb4wRd7LhE",
    "reason": "Partner onboarding offer",
    "expiresAt": "2027-01-31T23:59:59Z"
  }'

The response is 201 with the grant: id, accountId, planId, reason, status (Active, Expired or Revoked), expiresAt, events (createdAt, updatedAt, revokedAt), actors (createdBy, revokedBy) and metadata. The IDs above are illustrative.

Change or revoke a grant

Update a grant uses JSON Merge Patch on reason, expiresAt and metadata. The plan and the Account cannot change. Revoke a grant ends access at once and returns 204.

Errors

Webhook events

SubscriptionGrant lifecycle events are published as webhooks. See Webhooks and events to subscribe.