Skip to navigation
REST RPC APISubscriptions

Void subscription entitlements

View as Markdown

Voids the live entitlements granted by a cancelled or deactivated digital plan subscription, ending the customer’s access to the plan’s resources. The subscription itself is not changed.

The subscription must be inactive (live: false) and its product must be a digital plan; otherwise the request returns 400. Entitlements that another of the customer’s live subscriptions also grants are skipped unless void_shared_entitlements is true.

Voiding expires the whole entitlement, including any time granted by other purchases of the same plan.

If some voids fail, the request returns 200 with status: partial. Call the endpoint again to retry them.

This endpoint accepts the Application API Scope only. Storefront API Scope signatures are rejected. An API key needs write access.

Authentication

x-api-keystring

Application API Scope — server-to-server, sent in the x-api-key header. See Authentication.

Path parameters

subscription_idstringRequired
Unique Subscription ID

Request

This endpoint expects an object.
void_shared_entitlementsbooleanOptionalDefaults to false

Whether to also void entitlements that another of the customer’s live subscriptions grants to the same grantees. When false, those entitlements are skipped and listed in skipped_shared_entitlement_ids. Must be a JSON boolean; strings such as "true" are rejected with 400.

Response

Every matched entitlement was voided, some were voided and some failed, or there was nothing to void. Check status.

statusenum
Overall outcome of the request.
Allowed values:
voided_entitlement_idslist of strings
Public IDs of the entitlements that were voided.
failed_entitlement_idslist of strings
Public IDs of the entitlements that could not be voided. They are still live.
skipped_shared_entitlement_idslist of strings

Public IDs of the entitlements left live because another of the customer’s live subscriptions grants them. Always empty when void_shared_entitlements is true.

errorstring or null

Why entitlements failed to void, or why the entitlements could not be listed. null when nothing failed.

messagestring or null

Explains any skipped shared entitlements and how to void them. null when none were skipped.

Errors

400
Bad Request Error
403
Forbidden Error
404
Not Found Error
502
Bad Gateway Error