Install & Compatibility
Where this runs
tested against v4.72.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.209s · 18.7MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.189s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ import recurly
client = recurly.Client(api_key='YOUR_API_KEY')
✗ from recurly import Client
The recommended approach is to import the top-level 'recurly' module and access 'Client' via 'recurly.Client' to preserve namespace integrity.
ApiError
✓ from recurly import ApiError
Commonly imported for error handling.
NetworkError
✓ from recurly import NetworkError
Commonly imported for error handling related to network issues.
This quickstart demonstrates how to initialize the Recurly client using an API key and perform a basic API call to retrieve an account and list its invoices. Ensure `RECURLY_API_KEY` is set as an environment variable or replaced with your actual private API key. Remember to handle `recurly.ApiError` for API-specific responses and `recurly.NetworkError` for connectivity issues.
import os
import recurly
# It's highly recommended to store your API key as an environment variable.
RECURLY_API_KEY = os.environ.get('RECURLY_API_KEY', 'YOUR_PRIVATE_API_KEY')
# Initialize the Recurly client
# For EU region, use: client = recurly.Client(RECURLY_API_KEY, region='eu')
client = recurly.Client(RECURLY_API_KEY)
# Example: Fetch an account by its code
try:
# Note: Use 'code-' prefix for account codes, if applicable, based on your Recurly setup.
account_code = 'code-example-account-123'
account = client.get_account(account_code=account_code)
print(f"Successfully retrieved account: {account.id} (Code: {account.code}, Email: {account.email})")
# Example: List recent invoices for the account
print(f"\nRecent invoices for account {account.code}:")
for invoice in client.list_account_invoices(account_id=account.id).items():
print(f" Invoice {invoice.id}: State={invoice.state}, Total={invoice.total}")
except recurly.ApiError as e:
print(f"Recurly API Error: {e.message}")
if e.error_code:
print(f" Error Code: {e.error_code}, Details: {e.details}")
except recurly.NetworkError as e:
print(f"Recurly Network Error: {e.message}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingUpgrading from Recurly Python client v2.x.x (for Recurly API v2) to v4.x.x (for Recurly API v3) requires a complete rewrite of your integration code. There is no backward compatibility or drop-in shim. Recurly API v2 versions are officially deprecated and have reached end-of-life.fixRefer to the Recurly Developer Hub for the 'API v2 Python Client Upgrade Guide' and re-implement your integration using the new API v3 paradigms and the v4.x.x Python client.
affects: All versions prior to 4.0.0 (API v2 client) when migrating to 4.0.0+ (API v3 client)
gotchaRecurly API (used by this client library) is JSON-based, but webhook payloads are still XML. This library does not handle webhook parsing directly. Developers must implement their own XML parsing (e.g., using `xmltodict`) and validate webhook signatures.fixFor webhooks, use a dedicated XML-to-dict parser like `xmltodict` for processing incoming webhook data. Be mindful of security implications when parsing untrusted XML.
affects: All 4.x.x versions
gotchaRecurly's private API keys should be treated like passwords and never exposed in client-side code (e.g., JavaScript). They grant full access to your Recurly account's API. Always store them securely, preferably in environment variables or a secret management system.fixStore your `RECURLY_API_KEY` in environment variables or a secure vault. Access it in server-side code using `os.environ.get('RECURLY_API_KEY')`. affects: All versions
gotchaMany client methods accept IDs or codes (e.g., for accounts, plans). When using a 'code' (a user-defined identifier), it often requires a `code-` prefix (e.g., `client.get_account(account_code='code-my-account')`) while internal Recurly IDs do not use prefixes.fixConsult the specific method's documentation in the `recurly.client` module for parameter expectations. Always use the specified prefixes when interacting with object 'codes' to avoid `NotFoundError` or `InvalidParameterError`.
affects: All 4.x.x versions
Errors
Common errors & fixes
recurly.NotFoundError: Not Found
Attempting to retrieve an object (e.g., an account) by directly instantiating its class or using an incorrect identifier (ID vs. code, or missing 'code-' prefix).
fixEnsure you are using the correct client method (e.g., `client.get_account(...)` not `recurly.Account(...)`) and providing the correct identifier type and format (e.g., `account_code='code-your-account'` for a code, or the raw Recurly ID).
recurly.ApiError: 401 Unauthorized - Your API key is missing or invalid.
The private API key used to initialize the `recurly.Client` is incorrect, expired, or not provided.
fixVerify your `RECURLY_API_KEY` environment variable or the string passed to `recurly.Client()`. Ensure it's a valid private API key from your Recurly Admin Dashboard under Integrations > API Credentials.
recurly.ApiError: 400 Bad Request - The request was invalid or could not be understood by the server.
Often caused by malformed request bodies (e.g., incorrect JSON structure, missing required fields, invalid data types) or, historically with v2 API, invalid XML in requests.
fixInspect the `e.details` and `e.message` from the `ApiError` for specific validation feedback. Review your request body against the Recurly API documentation for the endpoint you are calling to ensure correct schema and data.
recurly.ApiError: 400 Bad Request - Invalid country code.
An address field containing a country code does not use a valid 2-letter ISO 3166-1 alpha-2 country code.
fixEnsure all country fields in your API requests (e.g., when creating or updating an account's billing information or shipping addresses) use the correct 2-letter ISO 3166-1 alpha-2 format (e.g., 'US', 'GB', 'DE').
recurly.NetworkError: Connection refused / Max retries exceeded / SSLError
Indicates a problem establishing or maintaining an HTTP connection to the Recurly API servers. This can be due to transient network issues, proxy misconfigurations, firewall restrictions, or issues with the underlying HTTP client in specific deployment environments (e.g., Flask + Gunicorn).
fixCheck network connectivity, proxy settings, and firewall rules. For intermittent issues, particularly in complex deployments, consider implementing retry logic or investigating specific HTTP client library behavior if possible.
Upgrade
Version history
4.72.0latest on PyPI · released Jun 10, 2026
Audit
Dependencies
No dependency data recorded yet.