Recharge
Set up the Recharge source connector in Airbyte to sync data from the Recharge API.
Key Features:
- Sync Modes: Supports
Full RefreshandIncrementalsyncs for core streams. - API Version: Uses the
2021-11API version for most streams. TheOrdersstream uses the deprecated2021-01API when UseOrdersDeprecated API is on. This is the default in the setup form. When it’s off, the stream uses2021-11. TheShopstream always uses2021-01. - Lookback Window: Supports a configurable lookback window that re-fetches recent data for incremental streams. This setting doesn’t apply to the
ordersoreventsstreams. The Recharge API only returns events from the last 7 days. See Lookback Window.
Prerequisites
Before you set up the Recharge source, make sure you have the following:
- Recharge Account:
- Permission in your Recharge account to generate API tokens and access data for your chosen streams.
- Recharge API Access Token:
- An API Access Token with the appropriate permissions (scopes) for the streams you want to sync.
- Follow these instructions to generate a token: Recharge API Key Guide.
- Recharge Plan:
- Some streams are only available on specific Recharge plans, such as Pro or Custom. Make sure your plan supports the streams you need. See the Permissions & Plan Requirements section for details.
Setup guide
Step 1: Generate your Recharge API Access Token
- Follow the official Recharge documentation to generate an API Access Token.
- Grant the token the required read permissions (scopes) for every data stream you plan to sync with Airbyte. See the API Token Permissions (Scopes) & Plan Requirements section below for each stream’s required scopes.
Step 2: Set up the source connector in Airbyte
For Airbyte Cloud:
- Log into your Airbyte Cloud account.
- In the left navigation bar, click Sources. In the top-right corner, click + new source.
- On the source setup page, select Recharge from the Source type dropdown. Then enter a name for this connector.
- Enter the Start Date in the format
YYYY-MM-DDT00:00:00Z. Incremental streams don’t replicate records updated before this date. Full refresh streams return all available data. Theeventsstream ignores this value when it’s older than 7 days. See Events stream. - Enter your Access Token from Step 1.
- (Optional) Turn off Use
OrdersDeprecated API to sync theOrdersstream with the2021-11API instead of the deprecated2021-01API. - (Optional) Set a Lookback Window (in days) to re-fetch records updated before the saved sync position. The value sets the number of days re-fetched during each incremental sync. The default is
0. - Click Set up source.
For Airbyte Open Source:
- Go to your local Airbyte instance.
- In the left navigation bar, click Sources. In the top-right corner, click + new source.
- On the source setup page, select Recharge from the Source type dropdown. Then enter a name for this connector.
- Enter the Start Date in the format
YYYY-MM-DDT00:00:00Z. Incremental streams don’t replicate records updated before this date. Full refresh streams return all available data. Theeventsstream ignores this value when it’s older than 7 days. See Events stream. - Enter your Access Token from Step 1.
- (Optional) Turn off Use
OrdersDeprecated API to sync theOrdersstream with the2021-11API instead of the deprecated2021-01API. - (Optional) Set a Lookback Window (in days) to re-fetch records updated before the saved sync position. The value sets the number of days re-fetched during each incremental sync. The default is
0. - Click Set up source.
Supported sync modes
The Recharge source connector supports these sync modes:
| Feature | Supported? | Description |
|---|---|---|
| Full Refresh Sync | ✅ Yes | Replicates all available data from the source for selected streams. |
| Incremental Sync | ✅ Yes | Replicates new or modified data since the last sync, based on a cursor field (datetime). |
| SSL Connection | ✅ Yes | All requests to the Recharge API are made over HTTPS, ensuring data is encrypted in transit. |
Streams
| Stream Name | API Docs | Primary Key | Supports Full Refresh | Supports Incremental | Plan Requirement |
|---|---|---|---|---|---|
| Addresses | 2021-11 | id | ✅ | ✅ | ✅ Standard Plan |
| Bundle Selections | 2021-11 | id | ✅ | ✅ | 🎯 Pro and Custom plans only |
| Charges | 2021-11 | id | ✅ | ✅ | ✅ Standard Plan |
| Collections | 2021-11 | id | ✅ | ❌ | ✅ Standard Plan |
| Credit Adjustments | 2021-11 | id | ✅ | ✅ | 🎯 Pro and Custom plans only |
| Customers | 2021-11 | id | ✅ | ✅ | ✅ Standard Plan |
| Discounts | 2021-11 | id | ✅ | ✅ | ✅ Standard Plan |
| Events | 2021-11 | id | ✅ | ✅ | ✅ Standard Plan |
| Metafields | 2021-11 | id | ✅ | ❌ | ✅ Standard Plan |
| Onetimes | 2021-11 | id | ✅ | ✅ | ✅ Standard Plan |
| Orders | 2021-11 / 2021-01 (Deprecated) | id | ✅ | ✅ | ✅ Standard Plan |
| Payment Methods | 2021-11 | id | ✅ | ❌ | 🎯 Pro and Custom plans only |
| Plans | 2021-11 | id | ✅ | ❌ | ✅ Standard Plan |
| Shop | 2021-01 (Deprecated) | id | ✅ | ❌ | ✅ Standard Plan |
| Subscriptions | 2021-11 | id | ✅ | ✅ | ✅ Standard Plan |
Notes on Streams:
- Orders Stream: The Use
OrdersDeprecated API option is on by default in the setup form. The connector therefore uses the deprecated2021-01API for theOrdersstream. Turn this option off to use the2021-11API instead. If you create the source programmatically and omit this field, the connector uses2021-11. - Shop Stream: The
Shopstream uses the deprecated2021-01API version. This connector doesn’t yet include an updated stream (Store) that uses a newer API version.
If you’d like Airbyte to support more endpoints, create an issue.
Events stream
The Recharge events endpoint only returns events from the last 7 days. It rejects requests for older events. To prevent sync failures, the connector never requests events older than 7 days:
- If your Start Date is more than 7 days ago, the first
eventsstream sync starts from 7 days ago. You can’t backfill older events. - If a connection hasn’t synced for more than 7 days, the next incremental
eventsstream sync resumes from 7 days ago. Events already older than 7 days aren’t synced. The sync succeeds without warning you about the missing interval. - The Lookback Window (in days) setting doesn’t affect the
eventsstream.
Schedule syncs at least once every 7 days to prevent gaps in events data.
Lookback window
You can configure a Lookback Window (in days) (lookback_window_days). Each incremental sync re-fetches records updated within that many days before the saved sync position, plus one hour. The extra hour re-reads records changed while the previous sync was running. This can capture late-arriving or updated records. The setting doesn’t apply to orders or events.
API token permissions and plan requirements
Your Recharge API Access Token needs the corresponding read permissions (scopes) to sync data from specific streams. Some streams also require your Recharge account to use a specific plan.
Permission and plan errors
403 - The request was authenticated but not authorized for the requested resource (permission scope error)
Recharge can return this error for these reasons:
- Missing Scope: This is the main cause of a 403 error. The sync fails when your API token lacks a selected stream’s required scope.
- Missing Plan: The stream’s sync also fails when your Recharge account doesn’t have the required plan.
This table lists each stream’s required read scopes and plan requirements:
| Stream Name | Required Read Scope(s) | Plan Requirement |
|---|---|---|
| Addresses | read_customers | Standard Plan |
| Bundle Selections | read_subscriptions | Pro or Custom plans only |
| Charges | read_orders | Standard Plan |
| Collections | read_products | Standard Plan |
| Credit Adjustments | read_credit_adjustments | Pro or Custom plans only |
| Customers | read_customers | Standard Plan |
| Discounts | read_discounts | Standard Plan |
| Events | read_events | Standard Plan |
| Metafields | read_address, read_customer, read_subscription, read_order, read_charge (Enable scopes for the resources whose metafields you want to sync) | Standard Plan |
| Onetimes | read_subscriptions | Standard Plan |
| Orders | read_orders | Standard Plan |
| Payment Methods | read_payment_methods | Pro or Custom plans only |
| Plans | read_products | Standard Plan |
| Shop | read_shop | Standard Plan |
| Subscriptions | read_subscriptions | Standard Plan |
Performance considerations
The Recharge connector handles Recharge API limitations during normal use.
Rate limiting
Recharge applies rate limits to maintain API stability and fair usage. The API uses a “leaky bucket” algorithm. Each API token has a bucket of 40 requests that empties at 2 requests per second. This allows short bursts, but the sustained rate is 2 requests per second. Higher Recharge plans may have higher limits.
- If the request rate exceeds the limit, the API returns a
429 - The request has been rate limitederror. - The connector limits each sync to 2 requests per second, even when Recharge raises your token’s limit. Other syncs or apps using the same API token have separate pacing but share the token’s limit. Together, they can still receive
429errors. - When the connector receives a
429error, it retries with exponential backoff of 1, 2, 4 … seconds. It stops after 10 retries or about 10 minutes, whichever comes first.
See Recharge API Rate Limits for more details.
Error handling
- Transient HTTP Errors: Airbyte’s
DefaultErrorHandlerhandles common transient errors, such as500 - Internal server errorand503 - A 3rd party service on which the request depends has timed out. It retries requests with exponential backoff, up to 10 times. - Persistent Issues: If rate limits or other errors persist after automatic retries, create an issue on GitHub. Include the relevant logs and details.
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 |
|---|---|---|---|
| 3.1.0 | 2026-11-10 | 91334 | Migrated to manifest-only. Fixed orders skipping pages across date slices (2021-01 API) and skipping records at the saved cursor (both API versions); refresh orders to recover previously skipped orders. Added a one-hour lookback margin to other incremental streams except events. Requests are now paced at 2 per second on 2 threads, and records omit top-level fields whose value is null. |
| 3.0.12 | 2026-09-17 | 86358 | Fix events stream’s created_at_min not clamped to the API’s 7-day window, crashing the entire sync |
| 3.0.11 | 2025-10-21 | 68391 | Update dependencies |
| 3.0.10 | 2025-10-14 | 67927 | Update dependencies |
| 3.0.9 | 2025-10-08 | 67543 | Update dependencies |
| 3.0.8 | 2025-09-30 | 66444 | Update dependencies |
| 3.0.7 | 2025-09-09 | 65674 | Update dependencies |
| 3.0.6 | 2025-08-24 | 65465 | Update dependencies |
| 3.0.5 | 2025-08-16 | 65034 | Update dependencies |
| 3.0.4 | 2025-08-02 | 64452 | Update dependencies |
| 3.0.3 | 2025-07-20 | 63658 | Update dependencies |
| 3.0.2 | 2025-07-12 | 63057 | Update dependencies |
| 3.0.1 | 2025-07-05 | 62581 | Update dependencies |
| 3.0.0 | 2025-06-20 | 61727 | Removes deprecated products stream. Adds new plans stream. |
| 2.10.2 | 2025-06-28 | 62290 | Update dependencies |
| 2.10.1 | 2025-06-14 | 61073 | Update dependencies |
| 2.10.0 | 2025-05-29 | 60810 | Add new payment_methods stream |
| 2.9.1 | 2025-05-24 | 60151 | Update dependencies |
| 2.9.0 | 2025-05-16 | 60317 | Improve 429 error handler |
| 2.8.0 | 2025-05-14 | 60265 | Added credit_adjustments stream |
| 2.7.0 | 2025-05-08 | 59734 | Added lookback window to connector manifest configuration |
| 2.6.14 | 2025-05-04 | 59512 | Update dependencies |
| 2.6.13 | 2025-04-27 | 59114 | Update dependencies |
| 2.6.12 | 2025-04-19 | 58454 | Update dependencies |
| 2.6.11 | 2025-04-12 | 57867 | Update dependencies |
| 2.6.10 | 2025-04-05 | 57369 | Update dependencies |
| 2.6.9 | 2025-03-29 | 56739 | Update dependencies |
| 2.6.8 | 2025-03-22 | 56218 | Update dependencies |
| 2.6.7 | 2025-03-08 | 55068 | Update dependencies |
| 2.6.6 | 2025-02-22 | 54547 | Update dependencies |
| 2.6.5 | 2025-02-15 | 53943 | Update dependencies |
| 2.6.4 | 2025-02-01 | 53018 | Update dependencies |
| 2.6.3 | 2025-01-25 | 52468 | Update dependencies |
| 2.6.2 | 2025-01-18 | 51914 | Update dependencies |
| 2.6.1 | 2025-01-11 | 51333 | Update dependencies |
| 2.6.0 | 2025-01-02 | 49926 | Add new stream bundle_selections |
| 2.5.4 | 2025-01-04 | 50927 | Update dependencies |
| 2.5.3 | 2024-12-28 | 50724 | Update dependencies |
| 2.5.2 | 2024-12-21 | 50265 | Update dependencies |
| 2.5.1 | 2024-12-14 | 49081 | 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 |
| 2.5.0 | 2024-11-26 | 48382 | Add new stream events |
| 2.4.15 | 2024-11-04 | 48242 | Update dependencies |
| 2.4.14 | 2024-10-29 | 47890 | Update dependencies |
| 2.4.13 | 2024-10-28 | 47037 | Update dependencies |
| 2.4.12 | 2024-10-12 | 46797 | Update dependencies |
| 2.4.11 | 2024-10-05 | 46510 | Update dependencies |
| 2.4.10 | 2024-09-28 | 46110 | Update dependencies |
| 2.4.9 | 2024-09-21 | 45739 | Update dependencies |
| 2.4.8 | 2024-09-14 | 45520 | Update dependencies |
| 2.4.7 | 2024-09-07 | 45321 | Update dependencies |
| 2.4.6 | 2024-08-31 | 44995 | Update dependencies |
| 2.4.5 | 2024-08-24 | 44731 | Update dependencies |
| 2.4.4 | 2024-08-17 | 44205 | Update dependencies |
| 2.4.3 | 2024-08-12 | 43837 | Update dependencies |
| 2.4.2 | 2024-08-10 | 43703 | Update dependencies |
| 2.4.1 | 2024-08-03 | 43171 | Update dependencies |
| 2.4.0 | 2024-08-02 | 42975 | Migrate to CDK v4.3.0 |
| 2.3.2 | 2024-07-27 | 42723 | Update dependencies |
| 2.3.1 | 2024-07-20 | 42336 | Update dependencies |
| 2.3.0 | 2024-07-17 | 42076 | Migrate to CDK v3.7.0 |
| 2.2.0 | 2024-07-17 | 42075 | Migrate to CDK v2.4.0 |
| 2.1.0 | 2024-07-17 | 42069 | Migrate to CDK v1.8.0 |
| 2.0.6 | 2024-07-13 | 41748 | Update dependencies |
| 2.0.5 | 2024-07-10 | 41475 | Update dependencies |
| 2.0.4 | 2024-07-09 | 41167 | Update dependencies |
| 2.0.3 | 2024-07-06 | 40849 | Update dependencies |
| 2.0.2 | 2024-06-25 | 40387 | Update dependencies |
| 2.0.1 | 2024-06-22 | 40042 | Update dependencies |
| 2.0.0 | 2024-06-14 | 39491 | Update primary key for Shop stream from shop, store(object, object) to id(integer) |
| 1.2.0 | 2024-03-13 | 35450 | Migrated to low-code |
| 1.1.6 | 2024-03-12 | 35982 | Added additional query param to guarantee the records are in asc order |
| 1.1.5 | 2024-02-12 | 35182 | Manage dependencies with Poetry. |
| 1.1.4 | 2024-02-02 | 34772 | Fix airbyte-lib distribution |
| 1.1.3 | 2024-01-31 | 34707 | Added the UI toggle Use 'Orders' Deprecated API to switch between deprecated and modern api versions for Orders stream |
| 1.1.2 | 2023-11-03 | 32132 | Reduced period in days value for Subscriptions stream, to avoid 504 - Gateway TimeOut error |
| 1.1.1 | 2023-09-26 | 30782 | For the new style pagination, pass only limit along with cursor |
| 1.1.0 | 2023-09-26 | 30756 | Fix pagination and slicing |
| 1.0.1 | 2023-08-30 | 29992 | Revert for orders stream to use old API version 2021-01 |
| 1.0.0 | 2023-06-22 | 27612 | Change data type of the shopify_variant_id_not_found field of the Charges stream |
| 0.2.10 | 2023-06-20 | 27503 | Update API version to 2021-11 |
| 0.2.9 | 2023-04-10 | 25009 | Fix owner slicing for Metafields stream |
| 0.2.8 | 2023-04-07 | 24990 | Add slicing to connector |
| 0.2.7 | 2023-02-13 | 22901 | Specified date formatting in specification |
| 0.2.6 | 2023-02-21 | 22473 | Use default availability strategy |
| 0.2.5 | 2023-01-27 | 22021 | Set AvailabilityStrategy for streams explicitly to None |
| 0.2.4 | 2022-10-11 | 17822 | Do not parse JSON in should_retry |
| 0.2.3 | 2022-10-11 | 17822 | Do not parse JSON in should_retry |
| 0.2.2 | 2022-10-05 | 17608 | Skip stream if we receive 403 error |
| 0.2.2 | 2022-09-28 | 17304 | Migrate to per-stream state. |
| 0.2.1 | 2022-09-23 | 17080 | Fix total_weight value to be int instead of float |
| 0.2.0 | 2022-09-21 | 16959 | Use TypeTransformer to reliably convert to schema declared data types |
| 0.1.8 | 2022-08-27 | 16045 | Force total_weight to be an integer |
| 0.1.7 | 2022-07-24 | 14978 | Set additionalProperties to True, to guarantee backward cababilities |
| 0.1.6 | 2022-07-21 | 14902 | Increased test coverage, fixed broken charges, orders schemas, added state checkpoint |
| 0.1.5 | 2022-01-26 | 9808 | Update connector fields title/description |
| 0.1.4 | 2021-11-05 | 7626 | Improve ‘backoff’ for HTTP requests |
| 0.1.3 | 2021-09-17 | 6149 | Update discount and order schema |
| 0.1.2 | 2021-09-17 | 6149 | Change cursor_field for Incremental streams |