--- updatedAt: 2026-05-05T19:53:57.000Z agentTools: siteIndex: https://docs.recurly.com/llms.txt projectIndex: https://docs.recurly.com/recurly-subscriptions/v2021-02-25/llms.txt --- # List entitlements granted to an account # OpenAPI definition ````json { "openapi": "3.0.0", "info": { "title": "Recurly V3 API", "description": "# Getting Started\n\n## Versioning\nThe V3 API is versioned to allow stability for integrators and\nflexibility for Recurly to continue making improvements.\n\nThe versions follow a format that incorporates the approximate date the\nchanges were released in a YYYY-MM-DD format, e.g. `v2021-02-25`.\n\n> *WARNING*: Specifying a version is required to get a successful response.\n\nEach request should specify a version using the `Accept` header:\n* `Accept: application/vnd.recurly.v2021-02-25`\n* `Accept: application/vnd.recurly.v2021-02-25+json`\n\nAll responses will include a `Recurly-Version` header with the API version\nused to process the request:\n```\nRecurly-Version: recurly.v2021-02-25\n```\n\nRecurly's client libraries correspond with API versions as listed below.\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n
API VersionClient Library Version
v2021-02-254.x
v2019-10-103.x
\n\nClient library releases:\n\n* [Node.js](https://github.com/recurly/recurly-client-node/releases)\n* [Python](https://github.com/recurly/recurly-client-python/releases)\n* [.NET](https://github.com/recurly/recurly-client-dotnet/releases)\n* [Ruby](https://github.com/recurly/recurly-client-ruby/releases)\n* [Java](https://github.com/recurly/recurly-client-java/releases)\n* [PHP](https://github.com/recurly/recurly-client-php/releases)\n* [Go](https://github.com/recurly/recurly-client-go/releases)\n\nClient libraries follow semantic versioning. For example, [Ruby client library\nversion 3.18.1](https://github.com/recurly/recurly-client-ruby/releases/tag/3.18.1)\nrepresents major version `3`, minor version `18` with patch `1`.\n\nWe encourage you to update to the latest version of the API and corresponding client library,\nas most recent versions are more performant than their predecessors. See the\n[changelog](https://recurly.com/developers/api/changelog.html) for a comprehensive list of changes\nintroduced in the latest API version.\n\n### Default Versions\nSpecifying a version is required to get a successful response. If you wish to\nreceive the latest version and are willing to accept the risk of breaking changes,\nyou may specify a version of `latest`.\n\nThe following media types will default the newest version of\nthe API:\n\n* `application/vnd.recurly.latest`\n* `application/vnd.recurly.latest+json`\n\n### Deprecation\nResponses for a deprecated version request will return two headers:\n```\nRecurly-Deprecated: TRUE\nRecurly-Sunset-Date: 2017-06-01T00:00:00+00:00\n```\nThe sunset date is an ISO-8601 formatted date time after which the version\nwill no longer be accessible.\n\n### Unsupported Versions\nA request for an unsupported version will return a status code of 406 and\nthe body will include a list of supported versions:\n```\n{\n \"error\": {\n \"type\": \"invalid_api_version\",\n \"message\": \"That accept header isn't in the format we use to specify an API version. Try one of these instead:\",\n \"acceptable_accept_headers\": [\n \"application/vnd.recurly.v2016-03-01\",\n \"application/vnd.recurly.v2016-04-27\",\n \"application/vnd.recurly.v2016-07-27\",\n \"application/vnd.recurly.v2016-12-15\",\n \"application/vnd.recurly.v2017-01-12\",\n \"application/vnd.recurly.v2017-09-30\",\n \"application/vnd.recurly.v2018-01-24\",\n \"application/vnd.recurly.v2018-05-10\",\n \"application/vnd.recurly.v2018-06-06\",\n \"application/vnd.recurly.v2018-08-09\",\n \"application/vnd.recurly.v2019-10-10\",\n \"application/vnd.recurly.v2021-02-25\"\n ]\n }\n}\n```\n\n## Error Messages\nError messages sent via the Recurly API are generally directed at\ndevelopers and those who are familiar with API technology. When using the\nAPI and passing error messages to target systems, be mindful that\nthese messages may not make sense in the context of the target system.\nPlease consider changing these messages in the target system to be better\nsuited to the audience of the system.\n\nPlease see [transaction error codes](https://recurly.com/developers/pages/api-transaction-errors.html) for more details.\n\n## Pagination\n### Response Schema\nEvery GET listing endpoint returns a response with the same schema:\n\n```\n{\n \"object\": \"list\", // Always \"list\"\n \"has_more\": true, // false if this is the last page of data\n \"next\": \"https://...\", // A URL pointing to the next page of data\n \"data\": [] // The data for this page as an array\n}\n```\n\nTo page through every record, your code should continually call the URL\nat `next` until `has_more` is `false`.\n\n### Query Parameters\nMost GET listing endpoints take query parameters that allow filtering\nand sorting the results. Some endpoints have additional parameters, which are\ndocumented on the respective endpoints, but most support the\nfollowing parameters:\n\n* `ids`: A comma separated list of ids to match.\n* `limit`: The number of records to return per page.\n* `order`: The sort order of records.\n* `sort`: The date field to use in sorting.\n* `begin_time`: The start datetime to filter (ISO 8601).\n* `end_time`: The end datetime to filter (ISO 8601).\n\n### Counting with HEAD\nEvery GET listing endpoint also supports the HEAD HTTP method. Making a\nhead request to the endpoint results in an empty body and an additional\n`Recurly-Total-Records` header. This is a count of the total number of records\nthat the endpoint will return, taking into account the current filtering query\nparameters.\n\n## Limits\nIn order to provide a fast response time to all our customers, we may rate\nlimit excessive requests. By default, new Recurly sites have the following\nAPI rate limits:\n\n* Sandbox sites: 400 requests/min. All requests count towards the rate limit.\n* Production sites: 1,000 requests/min. Only GET requests count towards the rate limit.\n\nOnce your site moves into production mode, Recurly will only rate limit\nGET requests. New subscriptions, account modifications, and other requests\nusing POST, PUT, or DELETE methods will not count against your rate limit.\n\nThe rate limit is calculated over a sliding 5 minute window. This means a\nproduction site could make 4,000 requests within one minute and not hit\nthe rate limit so long as the site made less than 1,000 requests during\nthe prior 4 minutes.\n\nIf an API request exceeds the rate limit, the API will return a\n`429 Too Many Requests` HTTP status. If your business needs a higher\nlimit, please contact support.\n\nThe rate limit applied to your client can be determined with the\n`X-RateLimit-Limit` header, and the number of remaining requests is sent\nin the `X-RateLimit-Remaining` header. Finally, the `X-RateLimit-Reset`\nheader contains an integer value representing the time, measured in\nseconds since the UNIX Epoch, at which the request count will be reset.\n\n## Idempotent Requests\n\nRecurly supports idempotent requests via the `Idempotency-Key` header for\n`POST`, `PUT`, `PATCH`, and `DELETE` requests. This allows API clients to\nsafely retry these requests without risk of duplicate operations.\n\nWhen you send a request with an `Idempotency-Key` header, Recurly stores the\nresponse for **1 hour**. If you send an identical request (same key, method,\npath, and API key) within that window, Recurly replays the original response\nrather than processing a new one. The replay response includes an\n`Idempotency-Prior: true` header.\n\nIf a request with the same key is **already in flight** when a second arrives,\nthe server returns `409 Conflict` with `Recurly-Should-Retry: true` and a\n`Retry-After` header indicating how long to wait in seconds before retrying.\n\n> **Note:** `429 Too Many Requests` responses are intentionally **not** cached.\n> You may retry freely once your rate limit resets without risk of unintended\n> replay behavior.\n\nKeys must be **255 characters or fewer**. Keys exceeding this limit will\nreceive a `400 Bad Request` response. We recommend using a UUID v4 as your\nkey to guarantee uniqueness.\n\n> **SDK support:** Native `Idempotency-Key` management (automatic key\n> generation, retry handling, and replay detection) is currently supported only\n> in the **Ruby SDK**. When using other SDKs or raw HTTP clients, you must\n> supply and manage the `Idempotency-Key` header yourself.\n\n## Change Log\n\nA list of changes for this version can be found [in the changelog](https://recurly.com/developers/api/changelog.html#v2021-02-25---current-ga-version).\n", "version": "v2021-02-25" }, "security": [ { "api_key": [] } ], "x-tagGroups": [ { "name": "Customers", "tags": [ "Account", "Account Note", "Account Acquisition Info", "Billing Info", "Billing Infos", "Coupon Redemption", "Subscription", "Subscription Change", "Usage", "Shipping Address" ] }, { "name": "Invoices and Payments", "tags": [ "Purchase", "Invoice", "Line Item", "Credit Payment", "Transaction", "Revenue Recovery", "Gift Cards" ] }, { "name": "Products and Promotions", "tags": [ "Item", "Plan", "Add-on", "Measured Unit", "Coupon", "Unique Coupon Code", "Price Segment" ] }, { "name": "Configuration", "tags": [ "Site", "Custom Field Definition", "Shipping Method", "Dunning Campaigns", "Business Entities", "Automated Exports", "General Ledger Account", "Performance Obligations", "Invoice Templates" ] }, { "name": "App Management", "tags": [ "External Subscription", "External Invoice", "External Product", "External Account", "External Product Reference", "External Payment Phase" ] } ], "tags": [ { "name": "Account", "description": "Accounts are core to managing your customers inside of Recurly. The account object stores the entire Recurly history of your customer and acts as the entry point for working with a customer's billing information, subscription data, transactions, invoices and more." } ], "paths": { "/accounts/{account_id}/entitlements": { "parameters": [ { "$ref": "#/components/parameters/account_id" }, { "$ref": "#/components/parameters/filter_limited_subscription_state" } ], "get": { "tags": [ "Account" ], "operationId": "list_entitlements", "summary": "List entitlements granted to an account", "responses": { "200": { "description": "A list of the entitlements granted to an account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitlementList" } } } }, "404": { "description": "Incorrect site or account ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-code-samples": [] } } }, "servers": [ { "url": "https://v3.recurly.com" }, { "url": "https://v3.eu.recurly.com" } ], "components": { "parameters": { "account_id": { "name": "account_id", "in": "path", "description": "Account ID or code. For ID no prefix is used e.g. `e28zov4fw0v2`. For code use prefix `code-`, e.g. `code-bob`.", "required": true, "schema": { "type": "string" } }, "filter_limited_subscription_state": { "name": "state", "in": "query", "description": "Filter the entitlements based on the state of the applicable subscription.\n\n- When `state=active`, `state=canceled`, `state=expired`, or `state=future`, subscriptions with states that match the query and only those subscriptions will be returned.\n- When no state is provided, subscriptions with active or canceled states will be returned.\n", "schema": { "type": "string", "enum": [ "active", "canceled", "expired", "future" ] } } }, "securitySchemes": { "api_key": { "type": "http", "description": "Enter the API key as the username and set the password to an empty string. You can locate and manage your API keys from the [API Credentials](https://app.recurly.com/go/developer/api_keys) page.", "scheme": "basic" } }, "schemas": { "EntitlementList": { "type": "object", "description": "A list of privileges granted to a customer through the purchase of a plan or item.", "properties": { "object": { "type": "string", "title": "Object Type" }, "has_more": { "type": "boolean", "description": "Indicates there are more results on subsequent pages." }, "next": { "type": "string", "description": "Path to subsequent page of results." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Entitlement" } } } }, "Entitlement": { "type": "object", "properties": { "object": { "type": "string", "description": "Entitlement" }, "customer_permission": { "$ref": "#/components/schemas/CustomerPermission" }, "granted_by": { "type": "array", "description": "Subscription or item that granted the customer permission.", "items": { "$ref": "#/components/schemas/GrantedBy" } }, "created_at": { "type": "string", "format": "date-time", "description": "Time object was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Time the object was last updated" } } }, "CustomerPermission": { "type": "object", "properties": { "id": { "type": "string", "description": "Customer permission ID." }, "code": { "type": "string", "description": "Customer permission code." }, "name": { "type": "string", "description": "Customer permission name." }, "description": { "type": "string", "description": "Description of customer permission." }, "object": { "type": "string", "description": "It will always be \"customer_permission\"." } } }, "GrantedBy": { "type": "object", "description": "The subscription or external subscription that grants customer permissions.", "properties": { "object": { "type": "string", "title": "Object Type" }, "id": { "type": "string", "description": "The ID of the subscription or external subscription that grants the permission to the account." } } }, "Error": { "type": "object", "properties": { "type": { "title": "Type", "type": "string", "enum": [ "bad_request", "immutable_subscription", "internal_server_error", "invalid_api_key", "invalid_api_version", "invalid_content_type", "invalid_permissions", "invalid_token", "missing_feature", "not_found", "rate_limited", "service_not_available", "simultaneous_request", "tax_service_error", "transaction", "unauthorized", "unavailable_in_api_version", "unknown_api_version", "validation" ] }, "message": { "type": "string", "title": "Message" }, "params": { "type": "array", "title": "Parameter specific errors", "items": { "type": "object", "properties": { "param": { "type": "string" } } } } } } } } } ```` # Sibling pages * [List a site's accounts](https://docs.recurly.com/recurly-subscriptions/v2021-02-25/reference/list_accounts.md) * [Create an account](https://docs.recurly.com/recurly-subscriptions/v2021-02-25/reference/create_account.md) * [Fetch an account](https://docs.recurly.com/recurly-subscriptions/v2021-02-25/reference/get_account.md) * [Update an account](https://docs.recurly.com/recurly-subscriptions/v2021-02-25/reference/update_account.md) * [Deactivate an account](https://docs.recurly.com/recurly-subscriptions/v2021-02-25/reference/deactivate_account.md) * [Redact an account (GDPR Right to Erasure)](https://docs.recurly.com/recurly-subscriptions/v2021-02-25/reference/redact_account.md) * [Reactivate an inactive account](https://docs.recurly.com/recurly-subscriptions/v2021-02-25/reference/reactivate_account.md) * [Fetch an account's balance and past due status](https://docs.recurly.com/recurly-subscriptions/v2021-02-25/reference/get_account_balance.md) * [List the external invoices on an account](https://docs.recurly.com/recurly-subscriptions/v2021-02-25/reference/list_account_external_invoices.md) * [List an account's child accounts](https://docs.recurly.com/recurly-subscriptions/v2021-02-25/reference/list_child_accounts.md) * [List an invoice template's associated accounts](https://docs.recurly.com/recurly-subscriptions/v2021-02-25/reference/list_invoice_template_accounts.md) * [List an account's external subscriptions](https://docs.recurly.com/recurly-subscriptions/v2021-02-25/reference/list_account_external_subscriptions.md)