--- 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 the external subscriptions on a site See the [Pagination Guide](/developers/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. # 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": "External Subscription", "description": "A subscription from an external resource that is not managed by the Recurly platform and instead is managed by third-party platforms like Apple App Store and Google Play Store." } ], "paths": { "/external_subscriptions": { "get": { "tags": [ "External Subscription" ], "operationId": "list_external_subscriptions", "summary": "List the external subscriptions on a site", "description": "See the [Pagination Guide](/developers/guides/pagination.html) to learn how to use pagination in the API and Client Libraries.", "parameters": [ { "$ref": "#/components/parameters/sort_dates" } ], "responses": { "200": { "description": "A list of the the external_subscriptions on a site.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalSubscriptionList" } } } }, "404": { "description": "Incorrect site.", "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": { "sort_dates": { "name": "sort", "in": "query", "description": "Sort field. You *really* only want to sort by `updated_at` in ascending\norder. In descending order updated records will move behind the cursor and could\nprevent some records from being returned.\n", "schema": { "default": "created_at", "type": "string", "enum": [ "created_at", "updated_at" ] } } }, "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": { "AccountMini": { "type": "object", "title": "Account mini details", "properties": { "id": { "type": "string", "maxLength": 13, "readOnly": true }, "object": { "type": "string", "title": "Object type", "readOnly": true }, "code": { "type": "string", "description": "The unique identifier of the account.", "maxLength": 50 }, "email": { "type": "string", "format": "email", "description": "The email address used for communicating with this customer.", "maxLength": 255 }, "first_name": { "type": "string", "maxLength": 255 }, "last_name": { "type": "string", "maxLength": 255 }, "company": { "type": "string", "maxLength": 255 }, "parent_account_id": { "type": "string", "maxLength": 13 }, "bill_to": { "type": "string", "maxLength": 6 }, "dunning_campaign_id": { "type": "string", "title": "Dunning Campaign ID", "description": "Unique ID to identify a dunning campaign. Used to specify if a non-default dunning campaign should be assigned to this account. For sites without multiple dunning campaigns enabled, the default dunning campaign will always be used." } } }, "PlanCode": { "type": "string", "title": "Plan code", "description": "Unique code to identify the plan. This is used in Hosted Payment Page URLs and in the invoice exports.", "pattern": "/^[a-z0-9_+-]+$/", "maxLength": 50 }, "PlanName": { "type": "string", "title": "Name", "description": "This name describes your plan and will appear on the Hosted Payment Page and the subscriber's invoice.", "maxLength": 255 }, "PlanMini": { "type": "object", "title": "Plan mini details", "description": "Just the important parts.", "properties": { "id": { "type": "string", "title": "Plan ID", "maxLength": 13, "readOnly": true }, "object": { "type": "string", "title": "Object type", "readOnly": true }, "code": { "$ref": "#/components/schemas/PlanCode" }, "name": { "$ref": "#/components/schemas/PlanName" } } }, "ExternalPaymentPhase": { "type": "object", "description": "Details of payments in the lifecycle of a subscription from an external resource that is not managed by the Recurly platform, e.g. App Store or Google Play Store.", "properties": { "id": { "type": "string", "title": "External payment phase ID", "description": "System-generated unique identifier for an external payment phase ID, e.g. `e28zov4fw0v2`." }, "object": { "type": "string", "title": "Object type" }, "started_at": { "type": "string", "format": "date-time", "title": "Started At" }, "ends_at": { "type": "string", "format": "date-time", "title": "Ends At" }, "starting_billing_period_index": { "type": "integer", "title": "Starting Billing Period Index" }, "ending_billing_period_index": { "type": "integer", "title": "Ending Billing Period Index" }, "offer_type": { "type": "string", "title": "Offer Type", "description": "Type of discount offer given, e.g. \"FREE_TRIAL\"" }, "offer_name": { "type": "string", "title": "Offer Name", "description": "Name of the discount offer given, e.g. \"introductory\"" }, "period_count": { "type": "integer", "title": "Period Count", "description": "Number of billing periods" }, "period_length": { "type": "string", "title": "Period Length", "description": "Billing cycle length" }, "amount": { "type": "string", "format": "decimal", "title": "Amount", "minimum": 0, "description": "Allows up to 9 decimal places" }, "currency": { "type": "string", "title": "Currency", "description": "3-letter ISO 4217 currency code.", "maxLength": 3 }, "created_at": { "type": "string", "format": "date-time", "title": "Created at", "description": "When the external subscription was created in Recurly." }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated at", "description": "When the external subscription was updated in Recurly." } } }, "ExternalProductMini": { "type": "object", "title": "External product mini details", "description": "Just the important parts.", "properties": { "id": { "type": "string", "title": "External product ID", "readOnly": true }, "object": { "type": "string", "title": "Object type", "readOnly": true }, "name": { "type": "string", "title": "Name", "description": "The merchant-facing name of the external product." } } }, "ExternalProductReferenceMini": { "type": "object", "title": "External Product Reference details", "description": "External Product Reference details", "properties": { "id": { "type": "string", "title": "External Product ID", "description": "System-generated unique identifier for an external product ID, e.g. `e28zov4fw0v2`." }, "object": { "type": "string", "title": "object" }, "reference_code": { "type": "string", "title": "reference_code", "description": "A code which associates the external product to a corresponding object or resource in an external platform like the Apple App Store or Google Play Store." }, "external_connection_type": { "type": "string", "title": "external_connection_type", "description": "Source connection platform." }, "created_at": { "type": "string", "format": "date-time", "description": "When the external product was created in Recurly." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the external product was updated in Recurly." } } }, "ExternalSubscription": { "type": "object", "description": "Subscription from an external resource such as Apple App Store or Google Play Store.", "properties": { "id": { "type": "string", "title": "External subscription ID", "description": "System-generated unique identifier for an external subscription ID, e.g. `e28zov4fw0v2`." }, "object": { "type": "string", "title": "Object type" }, "account": { "$ref": "#/components/schemas/AccountMini" }, "external_product_reference": { "$ref": "#/components/schemas/ExternalProductReferenceMini" }, "external_product": { "$ref": "#/components/schemas/ExternalProductMini" }, "plan": { "$ref": "#/components/schemas/PlanMini" }, "external_payment_phases": { "type": "array", "title": "External payment phases", "description": "The phases of the external subscription payment lifecycle.", "items": { "$ref": "#/components/schemas/ExternalPaymentPhase" } }, "external_id": { "type": "string", "title": "External Id", "description": "The id of the subscription in the external systems., I.e. Apple App Store or Google Play Store." }, "uuid": { "type": "string", "title": "Uuid", "description": "Universally Unique Identifier created automatically." }, "last_purchased": { "type": "string", "format": "date-time", "title": "Last purchased", "description": "When a new billing event occurred on the external subscription in conjunction with a recent billing period, reactivation or upgrade/downgrade." }, "auto_renew": { "type": "boolean", "title": "Auto-renew", "description": "An indication of whether or not the external subscription will auto-renew at the expiration date.", "default": false }, "in_grace_period": { "type": "boolean", "title": "In grace period", "description": "An indication of whether or not the external subscription is in a grace period.", "default": false }, "app_identifier": { "type": "string", "title": "App identifier", "description": "Identifier of the app that generated the external subscription." }, "quantity": { "type": "integer", "title": "Quantity", "description": "An indication of the quantity of a subscribed item's quantity.", "default": 1, "minimum": 0 }, "state": { "type": "string", "description": "External subscriptions can be active, canceled, expired, past_due, voided, revoked, or paused.", "default": "active" }, "activated_at": { "type": "string", "format": "date-time", "title": "Activated at", "description": "When the external subscription was activated in the external platform." }, "canceled_at": { "type": "string", "format": "date-time", "title": "Canceled at", "description": "When the external subscription was canceled in the external platform." }, "expires_at": { "type": "string", "format": "date-time", "title": "Expires at", "description": "When the external subscription expires in the external platform." }, "trial_started_at": { "type": "string", "format": "date-time", "title": "Trial started at", "description": "When the external subscription trial period started in the external platform." }, "trial_ends_at": { "type": "string", "format": "date-time", "title": "Trial ends at", "description": "When the external subscription trial period ends in the external platform." }, "test": { "type": "boolean", "title": "Test", "description": "An indication of whether or not the external subscription was purchased in a sandbox environment.", "default": false }, "imported": { "type": "boolean", "title": "Imported", "description": "An indication of whether or not the external subscription was created by a historical data import.", "default": false }, "created_at": { "type": "string", "format": "date-time", "title": "Created at", "description": "When the external subscription was created in Recurly." }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated at", "description": "When the external subscription was updated in Recurly." } } }, "ExternalSubscriptionList": { "type": "object", "properties": { "object": { "type": "string", "title": "Object type", "description": "Will always be List." }, "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/ExternalSubscription" } } } }, "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 * [Create an external subscription](https://docs.recurly.com/recurly-subscriptions/v2021-02-25/reference/create_external_subscription.md) * [Fetch an external subscription](https://docs.recurly.com/recurly-subscriptions/v2021-02-25/reference/get_external_subscription.md) * [Update an external subscription](https://docs.recurly.com/recurly-subscriptions/v2021-02-25/reference/put_external_subscription.md) * [List the external invoices on an external subscription](https://docs.recurly.com/recurly-subscriptions/v2021-02-25/reference/list_external_subscription_external_invoices.md) * [List the external payment phases on an external subscription](https://docs.recurly.com/recurly-subscriptions/v2021-02-25/reference/list_external_subscription_external_payment_phases.md)