Recurly
Use this guide to set up the Recurly source connector and find reference information. The connector reads data from the Recurly v3 API (version v2021-02-25).
Prerequisites
- A Recurly site
- A Recurly user whose role includes the Integration permission, allowing you to view API credentials
- A private API key for the site you want to sync
Set up the connector
1. Get a Recurly API key
- Sign in to Recurly as a user with the Integration permission.
- Go to Integrations > API Credentials.
- Copy an existing private API key, or add a new private key for Airbyte.
A dedicated Airbyte key lets you revoke access without affecting other integrations. Recurly private API keys grant full access to your site’s data. Recurly doesn’t offer read-only keys. For more information, see Recurly API keys.
2. Set up Recurly in Airbyte
- In Airbyte, go to Sources and add a new source. Select Recurly.
- For API Key, paste the private API key from Step 1.
- (Optional) For Start Date, enter the replication start date and time in UTC, using
YYYY-MM-DDTHH:mm:ssZ. If you leave it empty, the connector replicates the last five years of data. - (Optional) For End Date, enter the replication end date and time in UTC, using
YYYY-MM-DDTHH:mm:ssZ. The connector won’t replicate records updated after this time. If you leave it empty, the connector replicates data up to the sync time. - (Optional) For Number of concurrent threads, enter how many requests the connector sends to Recurly in parallel, from 1 to 20. The default is 10.
- (Optional) For Days in length for each API call to get data, enter how many days the connector requests from the accounts stream at once, from 1 to 365. The default is 30. Smaller values make more API calls but improve concurrency.
- (Optional) Turn on Use Sandbox Environment if the API key belongs to a Recurly sandbox site. Sandbox sites have a lower rate limit than production sites.
- Click Set up source.
Supported sync modes
The Recurly source connector supports these sync modes:
- Full Refresh
- Incremental
All streams except Export Dates support incremental syncs. Most streams use updated_at as the cursor. The Account Notes stream uses created_at.
Supported streams
- Accounts
- Account Coupon Redemptions
- Account Notes
- Add Ons
- Billing Infos
- Coupons
- Credit Payments
- Export Dates (Full Refresh only)
- Invoices
- Line Items
- Measured Units
- Plans
- Shipping Addresses
- Shipping Methods
- Subscriptions
- Transactions
- Unique Coupons
- Unique Coupons Parent
Some streams can take longer to sync on sites with many accounts because they make one request per account. These streams are Account Coupon Redemptions, Account Notes, Billing Infos and Shipping Addresses.
Limits and troubleshooting
Rate limits
Recurly limits API requests over a sliding five-minute window. Production sites allow 5,000 GET requests by default, while sandbox sites allow 2,000 requests. The connector paces requests within the limit for the site type you select with Use Sandbox Environment. See Recurly API limits.
Recurly applies the limit across the whole site, while the connector tracks only its own requests. The connector can still receive HTTP 429 responses if other connections or integrations use the same Recurly site. It retries rate-limited responses and server errors up to five times, using exponential backoff.
Authentication errors
The sync fails with a configuration error if Recurly returns HTTP 401 or 403. Check that the API key is an active private key for the site you want to sync. Then update the API Key field.
IP allow list
If you use Airbyte Cloud and restrict access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.
Changelog
Expand to review
| Version | Date | Pull Request | Subject |
|---|---|---|---|
| 1.3.71 | 2026-11-10 | 91303 | Pace requests to Recurly’s published rate limits, retry rate-limited and server error responses with exponential backoff, show actionable API key errors, and accept start and end dates saved without the trailing Z |
| 1.3.70 | 2026-11-10 | 91708 | Update dependencies |
| 1.3.69 | 2026-11-03 | 90721 | Update dependencies |
| 1.3.68 | 2026-10-20 | 89408 | Update dependencies |
| 1.3.67 | 2026-10-13 | 88767 | Update dependencies |
| 1.3.66 | 2026-10-06 | 88013 | Update dependencies |
| 1.3.65 | 2026-09-29 | 87315 | Update dependencies |
| 1.3.64 | 2026-09-22 | 86794 | Update dependencies |
| 1.3.63 | 2026-09-15 | 86212 | Update dependencies |
| 1.3.62 | 2026-09-08 | 85632 | Update dependencies |
| 1.3.61 | 2026-08-18 | 84729 | Update dependencies |
| 1.3.60 | 2026-08-11 | 84098 | Update dependencies |
| 1.3.59 | 2026-07-28 | 83194 | Update to CDK 7.23.8 (fixes AirbyteCustomCodeNotPermittedError for bundled custom components) and remove the temporary Cloud version override |
| 1.3.58 | 2026-07-28 | 1082 | Roll Cloud back to 1.3.56 — 1.3.57 is built on SDM 7.23.7, which breaks bundled custom components |
| 1.3.57 | 2026-07-28 | 83069 | Update dependencies |
| 1.3.56 | 2026-07-21 | 82560 | Update dependencies |
| 1.3.55 | 2026-07-14 | 81973 | Update dependencies |
| 1.3.54 | 2026-06-30 | 81209 | Update dependencies |
| 1.3.53 | 2026-06-23 | 80563 | Update dependencies |
| 1.3.52 | 2026-06-16 | 80005 | Update dependencies |
| 1.3.51 | 2026-06-09 | 79468 | Update dependencies |
| 1.3.50 | 2026-06-02 | 78924 | Update dependencies |
| 1.3.49 | 2026-04-28 | 77376 | Update dependencies |
| 1.3.48 | 2026-04-21 | 76720 | Update dependencies |
| 1.3.47 | 2026-04-13 | 76276 | Rename “concurrent workers” to “concurrent threads” in connector spec |
| 1.3.46 | 2026-03-24 | 75379 | Update dependencies |
| 1.3.45 | 2026-03-10 | 74639 | Update dependencies |
| 1.3.44 | 2026-03-03 | 73886 | Update dependencies |
| 1.3.43 | 2026-02-17 | 73522 | Update dependencies |
| 1.3.42 | 2026-02-03 | 72656 | Update dependencies |
| 1.3.41 | 2026-01-20 | 72016 | Update dependencies |
| 1.3.40 | 2026-01-14 | 71471 | Update dependencies |
| 1.3.39 | 2025-12-18 | 70642 | Update dependencies |
| 1.3.38 | 2025-11-25 | 70003 | Update dependencies |
| 1.3.37 | 2025-11-18 | 69622 | Update dependencies |
| 1.3.36 | 2025-10-29 | 68903 | Update dependencies |
| 1.3.35 | 2025-10-21 | 68341 | Update dependencies |
| 1.3.34 | 2025-10-14 | 67882 | Update dependencies |
| 1.3.33 | 2025-10-08 | 67545 | Update dependencies |
| 1.3.32 | 2025-09-30 | 66434 | Update dependencies |
| 1.3.31 | 2025-09-09 | 65702 | Update dependencies |
| 1.3.30 | 2025-08-24 | 65439 | Update dependencies |
| 1.3.29 | 2025-08-16 | 64996 | Update dependencies |
| 1.3.28 | 2025-08-03 | 64476 | Update dependencies |
| 1.3.27 | 2025-07-20 | 63657 | Update dependencies |
| 1.3.26 | 2025-07-07 | 63356 | Update Schema and add configurable concurrency |
| 1.3.25 | 2025-07-05 | 62679 | Update dependencies |
| 1.3.24 | 2025-06-28 | 61292 | Update dependencies |
| 1.3.23 | 2025-06-23 | 46722 | Fixes timestamp pattern for UI to match what connector expects |
| 1.3.22 | 2025-05-24 | 60470 | Update dependencies |
| 1.3.21 | 2025-05-10 | 60117 | Update dependencies |
| 1.3.20 | 2025-05-03 | 59488 | Update dependencies |
| 1.3.19 | 2025-04-27 | 59059 | Update dependencies |
| 1.3.18 | 2025-04-19 | 58512 | Update dependencies |
| 1.3.17 | 2025-04-12 | 57862 | Update dependencies |
| 1.3.16 | 2025-04-05 | 57342 | Update dependencies |
| 1.3.15 | 2025-03-29 | 56797 | Update dependencies |
| 1.3.14 | 2025-03-22 | 56238 | Update dependencies |
| 1.3.13 | 2025-03-08 | 55054 | Update dependencies |
| 1.3.12 | 2025-02-23 | 54550 | Update dependencies |
| 1.3.11 | 2025-02-15 | 54010 | Update dependencies |
| 1.3.10 | 2025-02-08 | 53507 | Update dependencies |
| 1.3.9 | 2025-02-01 | 52982 | Update dependencies |
| 1.3.8 | 2025-01-25 | 52493 | Update dependencies |
| 1.3.7 | 2025-01-18 | 51864 | Update dependencies |
| 1.3.6 | 2025-01-11 | 51351 | Update dependencies |
| 1.3.5 | 2024-12-28 | 50684 | Update dependencies |
| 1.3.4 | 2024-12-21 | 50289 | Update dependencies |
| 1.3.3 | 2024-12-14 | 49718 | Update dependencies |
| 1.3.2 | 2024-12-12 | 49333 | Update dependencies |
| 1.3.1 | 2024-12-11 | 49091 | Starting with this version, the Docker image is now rootless. Please note that this and future versions will not be compatible with Airbyte versions earlier than 0.64 |
| 1.3.0 | 2024-11-13 | 48474 | Remove definition and schema redundancy, update to latest CDK and make compatibility with builder |
| 1.2.0 | 2024-11-04 | 47290 | Migrate to manifest only format |
| 1.1.13 | 2024-11-04 | 48248 | Update dependencies |
| 1.1.12 | 2024-10-28 | 47067 | Update dependencies |
| 1.1.11 | 2024-10-12 | 46829 | Update dependencies |
| 1.1.10 | 2024-10-05 | 46456 | Update dependencies |
| 1.1.9 | 2024-09-28 | 46140 | Update dependencies |
| 1.1.8 | 2024-09-21 | 45764 | Update dependencies |
| 1.1.7 | 2024-09-14 | 45471 | Update dependencies |
| 1.1.6 | 2024-09-07 | 45274 | Update dependencies |
| 1.1.5 | 2024-08-31 | 45050 | Update dependencies |
| 1.1.4 | 2024-08-24 | 44742 | Update dependencies |
| 1.1.3 | 2024-08-17 | 44210 | Update dependencies |
| 1.1.2 | 2024-08-10 | 43472 | Update dependencies |
| 1.1.1 | 2024-08-03 | 43144 | Update dependencies |
| 1.1.0 | 2024-07-24 | 40729 | Migrate connector to low code |
| 1.0.12 | 2024-07-20 | 42206 | Update dependencies |
| 1.0.11 | 2024-07-13 | 41836 | Update dependencies |
| 1.0.10 | 2024-07-10 | 41500 | Update dependencies |
| 1.0.9 | 2024-07-09 | 41174 | Update dependencies |
| 1.0.8 | 2024-07-06 | 40820 | Update dependencies |
| 1.0.7 | 2024-06-27 | 40215 | Replaced deprecated AirbyteLogger with logging.Logger |
| 1.0.6 | 2024-06-25 | 40474 | Update dependencies |
| 1.0.5 | 2024-06-22 | 40012 | Update dependencies |
| 1.0.4 | 2024-06-06 | 39178 | [autopull] Upgrade base image to v1.2.2 |
| 1.0.3 | 2024-04-19 | 37246 | Updating to 0.80.0 CDK |
| 1.0.2 | 2024-04-12 | 37246 | schema descriptions |
| 1.0.1 | 2024-03-05 | 35828 | Bump version to unarchive supportLevel in Cloud productionDB |
| 1.0.0 | 2024-03-01 | 35763 | Re-introduce updated connector to catalog from archival repo |
| 0.5.0 | 2024-02-22 | 34622 | Republish connector using base image/Poetry, update schemas |
| 0.4.1 | 2022-06-10 | 13685 | Add state_checkpoint_interval to Recurly stream |
| 0.4.0 | 2022-01-28 | 9866 | Revamp Recurly Schema and add more resources |
| 0.3.2 | 2022-01-20 | 8617 | Update connector fields title/description |
| 0.3.1 | 2022-01-10 | 9382 | Source Recurly: avoid loading all accounts when importing account coupon redemptions |
| 0.3.0 | 2021-12-08 | 8468 | Support Incremental Sync Mode |