# /entitlements/activate - Shop-facing activation/renewal of an add-on

**POST /entitlements/activate**

Activate or renew an add-on after a shop purchase or subscription
renewal (called by the NethShop webhook). The system is addressed by
its key; the entitlement accepts the canonical catalog id or the
legacy alias.

Idempotent upsert: an existing (system, entitlement, scope) grant is
renewed in place (new expiry, revocation cleared), so webhook retries
are safe. The grant is recorded with `source: shop`.

Requires the `manage:entitlements` permission — held by the
Backoffice, Admin and Super Admin user roles, or an owner API key.



## Servers
- Backend API server (port 8080): https://api.your-domain.com/api (Backend API server (port 8080))
- Collect API server (port 8081): https://collect.your-domain.com/api (Collect API server (port 8081))


## Authentication methods
- Bearer auth


## Parameters



### Body: application/json (object)

- **system_key** (string)
  Key of the system to activate the add-on on

- **entitlement** (string)
  Canonical catalog id or legacy alias of the add-on

- **scope** (string)
  Application instance to narrow the grant to (only for scoped catalog items)

- **valid_until** (string(date-time) | null)
  Expiry of the grant. Null/omitted = perpetual.

- **source_ref** (string)
  Free-form reference to the originating record (e.g. shop subscription id)

- **buyer_email** (string)
  Email of the WordPress customer that owns the order
  (server-to-server, trusted). Resolved to a my user to store the
  `purchased_by` audit snapshot; an address matching no my user is
  kept raw.

- **variant** (object)
  Shop variation (tier) of the purchased product line. Display metadata
  only: the add-on↔product mapping stays on the parent product and
  /auth enforcement ignores it. Refreshed by activate, so tier
  upgrades/downgrades follow the renewals. Omitted for manual grants
  and simple (non-variable) products.



## Responses
### 200
Entitlement activated successfully

#### Body: application/json (object)
- **code** (integer)

- **message** (string)

- **data** (object)
  One add-on grant for one system, optionally narrowed to a single
  application instance via `scope` (omitted = whole system). `active` is
  derived: not revoked and not expired (`valid_until` null = perpetual).
  Revocation is soft (sets `revoked_at`, the row is kept for audit).


### 400
Unknown entitlement, scope not supported by the catalog item, or system-type mismatch ("this entitlement applies to nsec systems only")

#### Body: application/json (object)
- **code** (integer)
  HTTP error code

- **message** (string)
  Error message

- **data** (object)


### 401
Unauthorized - invalid or missing token

#### Body: application/json (object)
- **code** (integer)

- **message** (string)

- **data** (object | null)


### 403
Forbidden - insufficient permissions

#### Body: application/json (object)
- **code** (integer)

- **message** (string)

- **data** (object | null)


### 404
System not found for this key

#### Body: application/json (object)
- **code** (integer)
  HTTP error code

- **message** (string)
  Error message

- **data** (object)


### 500
Internal server error

#### Body: application/json (object)
- **code** (integer)

- **message** (string)

- **data** (object | null)



[Powered by Bump.sh](https://bump.sh)