Another Rhythm application, or an integration you build, can check whether a contact or organization has enough of an entitlement your association sells. The application does not need to add up entitlement records on its own. This reference explains what the check counts, how to list an owner’s entitlements directly, how to change who owns an entitlement, and who can use these API operations. These actions do not have screens in the Console, so you can reach them only through the API. For what an entitlement is and how one is granted, see the entitlements concept article for Orders & Inventory.
Checking Whether an Owner Holds Enough of an Entitlement Type
The check needs the owner type, either contact or organization, the owner’s identifier, and the entitlement type’s identifier. You can also send a required quantity. Rhythm totals the owner’s entitlements for that type, then returns whether the total meets the required quantity, the total quantity, and how many entitlement records it counted.
| If you send | The check does this |
|---|---|
| A required quantity | Answers whether the owner’s total is at least that quantity |
| No required quantity | Uses 1 as the required quantity |
| An owner type other than contact or organization | Finds no matching owner and answers not entitled |
| A required quantity of zero or a negative number | Always answers entitled |
| A required quantity that is not a number | Always answers not entitled |
| An owner with no entitlements of that type | Answers not entitled with a total of zero, instead of returning an error |
| An owner type, owner identifier, or entitlement type identifier missing from the request | Refuses the request |
The check totals the quantities that were granted; it does not track how much of an entitlement has been used. If a customer bought five sittings of something and already used all five, the check still reports them as entitled to five unless the application that consumes the entitlement removes or reduces it. Entitlements for an inactive or deleted entitlement type still count.
Which Entitlements Count Toward the Check
Before Rhythm totals the quantities, it keeps or discards each matching entitlement by comparing its expiry date with the current date:
| Entitlement | Currently counts toward the check? |
|---|---|
| No expiry date | Yes, always |
| Expiry date on or before today | Yes |
| Expiry date after today | No |
Warning
An entitlement that has not yet expired is currently excluded from the check, while an entitlement whose expiry date has already passed is currently included. This expiry handling is why a customer with a recently purchased, unexpired entitlement could be told they are not entitled, or why a customer whose entitlement expired long ago could still be admitted. To confirm what a specific check counted, list the owner’s entitlements of that type and compare each expiry date with the table above.
Listing an Owner's Entitlements of One Type
You can list every entitlement record a contact or organization holds for one entitlement type, instead of relying only on the summarized check. The request needs the same owner type, owner identifier, and entitlement type identifier. The list does not filter by expiry date, so it returns expired, current, zero, and negative entitlements, oldest first and one page at a time. Use this when you need to show a customer the individual purchases behind their total, such as which order granted each right and when it expires.
If you need to find entitlements for someone who received an order through an Override Ship To Contact field, list entitlements with that contact as the owner instead of searching order line items for the recipient. Rhythm does not currently document a Commerce Orders endpoint for finding order lines by that field.
Changing an Entitlement's Owner or Order Link
You can change any field on an entitlement record through a direct update or patch call, except the entitlement’s own identifier. This includes fields that the Console’s entitlement editor does not offer:
| What you change | Effect |
|---|---|
| The owner (contact or organization) | The entitlement appears in the new owner’s checks and lists immediately |
| The entitlement type | The right counts toward the new type instead of the old one |
| The order or order line it came from | The entitlement appears on that order’s list, or on no order’s list if you clear the link |
Before Rhythm saves the change, the new owner, entitlement type, and order must all exist, and the record must still pass validation. Otherwise, the update is refused.
Warning
If you change an entitlement’s order or order line link, a later cancellation of the original order line will no longer find or reduce this entitlement. Cancellation processing only looks for entitlements linked to the line it is cancelling. Change this link only when you intend that outcome.
When you preserve access to previously purchased content, such as a webinar, confirm that the purchaser exists under the CRM or profile record you expect them to sign in with, then test access from that profile. Access depends on the entitlement’s owner record, so pointing the entitlement at the wrong contact or organization leaves the right person unable to reach it.
Account Access and Portal Restrictions
Every entitlement operation in this reference is limited to your own Rhythm account. A request that identifies with another account’s session is refused. Within your account, no more specific permission limits access further: any signed-in staff identity or service identity that can reach the API can check, list, or change any of your customers’ entitlements.
A Portal member is refused for every entitlement operation, including reading their own entitlements. There is no Portal page or route for entitlements, so members cannot see their own entitlements anywhere, and their requests are refused as unauthorized.