Advanced Analytica Advanced Analytica: IBOM
← All connectors
Recharge logo

Source connector

Recharge

Set up Recharge as a source and move its data into your chosen destination.

Version 3.1.0 community generally available

Recharge

Set up the Recharge source connector in Airbyte to sync data from the Recharge API.

Key Features:

  • Sync Modes: Supports Full Refresh and Incremental syncs for core streams.
  • API Version: Uses the 2021-11 API version for most streams. The Orders stream uses the deprecated 2021-01 API when Use Orders Deprecated API is on. This is the default in the setup form. When it’s off, the stream uses 2021-11. The Shop stream always uses 2021-01.
  • Lookback Window: Supports a configurable lookback window that re-fetches recent data for incremental streams. This setting doesn’t apply to the orders or events streams. 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:

  1. Recharge Account:
    • Permission in your Recharge account to generate API tokens and access data for your chosen streams.
  2. 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.
  3. 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

  1. Follow the official Recharge documentation to generate an API Access Token.
  2. 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:

  1. Log into your Airbyte Cloud account.
  2. In the left navigation bar, click Sources. In the top-right corner, click + new source.
  3. On the source setup page, select Recharge from the Source type dropdown. Then enter a name for this connector.
  4. 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. The events stream ignores this value when it’s older than 7 days. See Events stream.
  5. Enter your Access Token from Step 1.
  6. (Optional) Turn off Use Orders Deprecated API to sync the Orders stream with the 2021-11 API instead of the deprecated 2021-01 API.
  7. (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.
  8. Click Set up source.

For Airbyte Open Source:

  1. Go to your local Airbyte instance.
  2. In the left navigation bar, click Sources. In the top-right corner, click + new source.
  3. On the source setup page, select Recharge from the Source type dropdown. Then enter a name for this connector.
  4. 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. The events stream ignores this value when it’s older than 7 days. See Events stream.
  5. Enter your Access Token from Step 1.
  6. (Optional) Turn off Use Orders Deprecated API to sync the Orders stream with the 2021-11 API instead of the deprecated 2021-01 API.
  7. (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.
  8. Click Set up source.

Supported sync modes

The Recharge source connector supports these sync modes:

FeatureSupported?Description
Full Refresh Sync✅ YesReplicates all available data from the source for selected streams.
Incremental Sync✅ YesReplicates new or modified data since the last sync, based on a cursor field (datetime).
SSL Connection✅ YesAll requests to the Recharge API are made over HTTPS, ensuring data is encrypted in transit.

Streams

Stream NameAPI DocsPrimary KeySupports Full RefreshSupports IncrementalPlan Requirement
Addresses2021-11id✅✅✅ Standard Plan
Bundle Selections2021-11id✅✅🎯 Pro and Custom plans only
Charges2021-11id✅✅✅ Standard Plan
Collections2021-11id✅❌✅ Standard Plan
Credit Adjustments2021-11id✅✅🎯 Pro and Custom plans only
Customers2021-11id✅✅✅ Standard Plan
Discounts2021-11id✅✅✅ Standard Plan
Events2021-11id✅✅✅ Standard Plan
Metafields2021-11id✅❌✅ Standard Plan
Onetimes2021-11id✅✅✅ Standard Plan
Orders2021-11 / 2021-01 (Deprecated)id✅✅✅ Standard Plan
Payment Methods2021-11id✅❌🎯 Pro and Custom plans only
Plans2021-11id✅❌✅ Standard Plan
Shop2021-01 (Deprecated)id✅❌✅ Standard Plan
Subscriptions2021-11id✅✅✅ Standard Plan

Notes on Streams:

  • Orders Stream: The Use Orders Deprecated API option is on by default in the setup form. The connector therefore uses the deprecated 2021-01 API for the Orders stream. Turn this option off to use the 2021-11 API instead. If you create the source programmatically and omit this field, the connector uses 2021-11.
  • Shop Stream: The Shop stream uses the deprecated 2021-01 API 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 events stream 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 events stream 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 events stream.

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 NameRequired Read Scope(s)Plan Requirement
Addressesread_customersStandard Plan
Bundle Selectionsread_subscriptionsPro or Custom plans only
Chargesread_ordersStandard Plan
Collectionsread_productsStandard Plan
Credit Adjustmentsread_credit_adjustmentsPro or Custom plans only
Customersread_customersStandard Plan
Discountsread_discountsStandard Plan
Eventsread_eventsStandard Plan
Metafieldsread_address, read_customer, read_subscription, read_order, read_charge (Enable scopes for the resources whose metafields you want to sync)Standard Plan
Onetimesread_subscriptionsStandard Plan
Ordersread_ordersStandard Plan
Payment Methodsread_payment_methodsPro or Custom plans only
Plansread_productsStandard Plan
Shopread_shopStandard Plan
Subscriptionsread_subscriptionsStandard 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 limited error.
  • 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 429 errors.
  • When the connector receives a 429 error, 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 DefaultErrorHandler handles common transient errors, such as 500 - Internal server error and 503 - 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
VersionDatePull RequestSubject
3.1.02026-11-1091334Migrated 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.122026-09-1786358Fix events stream’s created_at_min not clamped to the API’s 7-day window, crashing the entire sync
3.0.112025-10-2168391Update dependencies
3.0.102025-10-1467927Update dependencies
3.0.92025-10-0867543Update dependencies
3.0.82025-09-3066444Update dependencies
3.0.72025-09-0965674Update dependencies
3.0.62025-08-2465465Update dependencies
3.0.52025-08-1665034Update dependencies
3.0.42025-08-0264452Update dependencies
3.0.32025-07-2063658Update dependencies
3.0.22025-07-1263057Update dependencies
3.0.12025-07-0562581Update dependencies
3.0.02025-06-2061727Removes deprecated products stream. Adds new plans stream.
2.10.22025-06-2862290Update dependencies
2.10.12025-06-1461073Update dependencies
2.10.02025-05-2960810Add new payment_methods stream
2.9.12025-05-2460151Update dependencies
2.9.02025-05-1660317Improve 429 error handler
2.8.02025-05-1460265Added credit_adjustments stream
2.7.02025-05-0859734Added lookback window to connector manifest configuration
2.6.142025-05-0459512Update dependencies
2.6.132025-04-2759114Update dependencies
2.6.122025-04-1958454Update dependencies
2.6.112025-04-1257867Update dependencies
2.6.102025-04-0557369Update dependencies
2.6.92025-03-2956739Update dependencies
2.6.82025-03-2256218Update dependencies
2.6.72025-03-0855068Update dependencies
2.6.62025-02-2254547Update dependencies
2.6.52025-02-1553943Update dependencies
2.6.42025-02-0153018Update dependencies
2.6.32025-01-2552468Update dependencies
2.6.22025-01-1851914Update dependencies
2.6.12025-01-1151333Update dependencies
2.6.02025-01-0249926Add new stream bundle_selections
2.5.42025-01-0450927Update dependencies
2.5.32024-12-2850724Update dependencies
2.5.22024-12-2150265Update dependencies
2.5.12024-12-1449081Starting 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.02024-11-2648382Add new stream events
2.4.152024-11-0448242Update dependencies
2.4.142024-10-2947890Update dependencies
2.4.132024-10-2847037Update dependencies
2.4.122024-10-1246797Update dependencies
2.4.112024-10-0546510Update dependencies
2.4.102024-09-2846110Update dependencies
2.4.92024-09-2145739Update dependencies
2.4.82024-09-1445520Update dependencies
2.4.72024-09-0745321Update dependencies
2.4.62024-08-3144995Update dependencies
2.4.52024-08-2444731Update dependencies
2.4.42024-08-1744205Update dependencies
2.4.32024-08-1243837Update dependencies
2.4.22024-08-1043703Update dependencies
2.4.12024-08-0343171Update dependencies
2.4.02024-08-0242975Migrate to CDK v4.3.0
2.3.22024-07-2742723Update dependencies
2.3.12024-07-2042336Update dependencies
2.3.02024-07-1742076Migrate to CDK v3.7.0
2.2.02024-07-1742075Migrate to CDK v2.4.0
2.1.02024-07-1742069Migrate to CDK v1.8.0
2.0.62024-07-1341748Update dependencies
2.0.52024-07-1041475Update dependencies
2.0.42024-07-0941167Update dependencies
2.0.32024-07-0640849Update dependencies
2.0.22024-06-2540387Update dependencies
2.0.12024-06-2240042Update dependencies
2.0.02024-06-1439491Update primary key for Shop stream from shop, store(object, object) to id(integer)
1.2.02024-03-1335450Migrated to low-code
1.1.62024-03-1235982Added additional query param to guarantee the records are in asc order
1.1.52024-02-1235182Manage dependencies with Poetry.
1.1.42024-02-0234772Fix airbyte-lib distribution
1.1.32024-01-3134707Added the UI toggle Use 'Orders' Deprecated API to switch between deprecated and modern api versions for Orders stream
1.1.22023-11-0332132Reduced period in days value for Subscriptions stream, to avoid 504 - Gateway TimeOut error
1.1.12023-09-2630782For the new style pagination, pass only limit along with cursor
1.1.02023-09-2630756Fix pagination and slicing
1.0.12023-08-3029992Revert for orders stream to use old API version 2021-01
1.0.02023-06-2227612Change data type of the shopify_variant_id_not_found field of the Charges stream
0.2.102023-06-2027503Update API version to 2021-11
0.2.92023-04-1025009Fix owner slicing for Metafields stream
0.2.82023-04-0724990Add slicing to connector
0.2.72023-02-1322901Specified date formatting in specification
0.2.62023-02-2122473Use default availability strategy
0.2.52023-01-2722021Set AvailabilityStrategy for streams explicitly to None
0.2.42022-10-1117822Do not parse JSON in should_retry
0.2.32022-10-1117822Do not parse JSON in should_retry
0.2.22022-10-0517608Skip stream if we receive 403 error
0.2.22022-09-2817304Migrate to per-stream state.
0.2.12022-09-2317080Fix total_weight value to be int instead of float
0.2.02022-09-2116959Use TypeTransformer to reliably convert to schema declared data types
0.1.82022-08-2716045Force total_weight to be an integer
0.1.72022-07-2414978Set additionalProperties to True, to guarantee backward cababilities
0.1.62022-07-2114902Increased test coverage, fixed broken charges, orders schemas, added state checkpoint
0.1.52022-01-269808Update connector fields title/description
0.1.42021-11-057626Improve ‘backoff’ for HTTP requests
0.1.32021-09-176149Update discount and order schema
0.1.22021-09-176149Change cursor_field for Incremental streams
Advanced Analytica

Most businesses are sitting on information they can’t use at speed. The people who hold it are busy, and when they leave, the knowledge goes with them. The documents are static, and the processes around them weren’t designed for AI.

Advanced Analytica works with these businesses to turn that information into structured data assets. Once they're integrated, AI systems can govern it, and the business can use it. We bring in the strategy, the specification and the AI skills to rework how the business operates.

MOVE FAST. STAY SAFE.