Recurly Python Client

4.70.0 · active · verified Thu Apr 16

The `recurly` library is the official Python client for Recurly's V3 API, enabling developers to integrate subscription billing and management into their applications. It provides functionalities for managing accounts, subscriptions, invoices, and transactions. The library is actively maintained with frequent minor version releases, often driven by updates to the underlying Recurly API schema, and the current stable version is 4.70.0.

Common errors

```
recurly.NotFoundError: Not Found
```
cause 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).

fix Ensure 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.
```
cause The private API key used to initialize the `recurly.Client` is incorrect, expired, or not provided.

fix Verify 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.
```
cause 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.

fix Inspect 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.
```
cause An address field containing a country code does not use a valid 2-letter ISO 3166-1 alpha-2 country code.

fix Ensure 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
```
cause 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).

fix Check 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.

Warnings

breaking Upgrading 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.
Fix: Refer 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.
gotcha Recurly 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.
Fix: For webhooks, use a dedicated XML-to-dict parser like `xmltodict` for processing incoming webhook data. Be mindful of security implications when parsing untrusted XML.
gotcha Recurly'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.
Fix: Store your `RECURLY_API_KEY` in environment variables or a secure vault. Access it in server-side code using `os.environ.get('RECURLY_API_KEY')`.
gotcha Many 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.
Fix: Consult 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`.

Install

pip install recurly Install latest version

Imports

Client
wrong:
```
from recurly import Client
```
correct:
```
import recurly
client = recurly.Client(api_key='YOUR_API_KEY')
```
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.

Quickstart

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}")

view raw JSON →