Copy page

Products

Product Entitlements

Product entitlements are stable access-right identifiers attached to products. An active customer subscription grants the union of entitlements on the products in its open timeline segment.

Use the public API at https://api.ledgerbee.com/api/v1 with an x-api-key header. Reading requires products-read. Creating, updating, deleting, and changing product bindings require products-write. The generated API Reference defines each request and response schema.

Define an entitlement

POST https://api.ledgerbee.com/api/v1/entitlements creates an externally managed entitlement. The optional key is a case-insensitive, tenant-unique integration identifier. Reuse the same key in retries and reconciliation jobs.

Code
{
  "name": "Advanced reports",
  "key": "advanced-reports"
}

The full CRUD surface (list, read, update, delete) is documented in the API Reference. Deleting requires the entitlement to be unbound from every product first.

Reads return every entitlement in the tenant so product bindings and webhook entitlementIds always resolve. Each response carries managedExternally and externalSource. Only rows with externalSource "api" can be updated or deleted through the public API; other rows are managed inside LedgerBee and are read-only here.

Attach entitlements to products

Pass entitlementIds when creating or updating a product. The array replaces the public API-owned subset of that product's bindings. Bindings managed inside LedgerBee are preserved.

Code
{
  "name": "Pro plan",
  "productNumber": "PRO",
  "productGroupId": "16fbe7dd-bc92-4ef7-953f-0f4d520e7189",
  "entitlementIds": ["69777e2d-9c96-4fc6-9848-d5fe7d8da437"]
}

Product detail responses include entitlement references. Product list items do not include them. Fetch product detail when the binding set is needed.

Read grants and synchronize access

GET https://api.ledgerbee.com/api/v1/subscriptions/{id} includes the current entitlements union. There is no public subscription-preview endpoint.

Use the access-boundary topics in the subscription webhook topic table. Grant or replace access when a subscription starts, transitions, resumes, or ends its trial. Treat assignment as advance notice because a future-dated assignment is not active yet. Revoke access on an effective pause or finalized cancellation; both payloads carry an empty entitlementIds array.

See Subscription webhooks for delivery, ordering, signature verification, and retry guidance.

Identifier and lifecycle contract

No bearer token or redeemable entitlement token is minted. LedgerBee delivers entitlement UUIDs in API responses and webhooks. Store the UUID as the durable identity. Use key for idempotent catalogue reconciliation and name only for display.

Changing a product binding changes the union returned by the next subscription read and the next access-boundary event. Access begins only when a granting-status segment is open. Pausing or final churn revokes the set in its access-boundary webhook. If webhook delivery is delayed, process retries idempotently by event id and reconcile against the subscription detail endpoint.

Support matrix

Operation	Public API-owned entitlement	LedgerBee-managed entitlement
Read entitlement	Yes	Yes
Update or delete entitlement	Yes	No
Replace product bindings through public API	Replaced	Preserved
Replace product bindings in the LedgerBee app	Preserved	Replaced
Delete a bound entitlement	No	No

Deleting a product removes all of that product's entitlement bindings. It does not delete shared entitlement records.

Errors and failure states

Condition	What you observe	Action
Entitlement id is absent from the tenant	ENTITLEMENT_NOT_FOUND	Refresh the entitlement list and verify the id.
Name is already used	ENTITLEMENT_NAME_EXISTS	Choose another name or use the existing entitlement.
Case-insensitive key is already used	ENTITLEMENT_KEY_EXISTS	Re-read by key and continue with the existing entitlement.
Products still reference the entitlement	ENTITLEMENT_IN_USE	Remove the product bindings before deletion.
Public write targets a LedgerBee-managed row	ENTITLEMENT_MANAGED_INTERNALLY	Leave the row unchanged or ask an operator to change it.
Write targets a row owned by another system	ENTITLEMENT_MANAGED_EXTERNALLY	Change it through the owning integration.

All errors use the standard public error envelope. Safe network retries should use an idempotency key.