ContextQMD
Back to Airbyte

Recharge

docs/integrations/sources/recharge.md

2.0.026.0 KB
Original Source

Recharge

This document guides you through setting up the Recharge source connector in Airbyte, allowing you to sync data from the Recharge API.

Key Features:

  • Sync Modes: Supports Full Refresh and Incremental syncs for core streams.
  • API Version: Primarily uses the 2021-11 API version. Includes an option to use the deprecated 2021-01 API for the Orders stream.
  • Lookback Window: Supports a configurable lookback window for most streams to re-fetch recent data.

Prerequisites

Before setting up the Recharge source, ensure you have the following:

  1. Recharge Account:
    • Permissions within your Recharge account to generate API tokens and access the data for the streams you intend to sync.
  2. Recharge API Access Token:
    • You'll need an API Access Token with the appropriate permissions (scopes) for the data streams you wish to sync.
    • Instructions for generating a token can be found here: Recharge API Key Guide.
  3. Recharge Plan:
    • Some streams are only available on specific Recharge plans (e.g., Pro, Custom). Ensure 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. When configuring the token, ensure you grant it the necessary read permissions (scopes) for all the data streams you plan to sync with Airbyte. Refer to the API Token Permissions (Scopes) & Plan Requirements section below for a detailed list of required scopes per stream.

Step 2: Set up the source connector in Airbyte

<!-- env:cloud -->

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 and enter a name for this connector.
  4. Choose required Start date
  5. Enter your Access Token.
  6. click Set up source.
<!-- /env:cloud --> <!-- env:oss -->

For Airbyte Open Source:

  1. Go to local Airbyte page.
  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 and enter a name for this connector.
  4. Choose required Start date
  5. Enter your Access Token generated from Step 1.
  6. click Set up source.
<!-- /env:oss -->

Supported sync modes

The Recharge source connector supports the following 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 connector uses the 2021-11 API for the Orders stream. If you need to use the deprecated 2021-01 API for orders, enable the Use Orders Deprecated API toggle in the connector configuration.
  • Shop Stream: The Shop stream currently utilizes the deprecated 2021-01 API version. An updated stream (Store) using a newer API version has not yet been implemented in this connector.

If there are more endpoints you'd like Airbyte to support, please create an issue.

Lookback Window

The connector supports a configurable Lookback Window (days). This feature allows the connector to re-fetch data from the specified number of days in the past during each incremental sync. This can be useful for capturing late-arriving or updated records.

Lookback Window for events Stream:

  • The events stream API has a limitation where it does not support querying data older than 7 days. At present, the lookback window setting does not affect the events stream.

API Token Permissions (Scopes) & Plan Requirements

To successfully sync data from specific streams, your Recharge API Access Token must have the corresponding read permissions (scopes). Additionally, some streams are only available if your Recharge account is on a specific plan.

Error Handling for Permissions & Plans:

403 - The request was authenticated but not authorized for the requested resource (permission scope error)

This error from Recharge can occur due to:

  • Missing Scope: This is the primary cause for the 403 error. If your API token lacks the necessary scope for a selected stream, the sync will fail.
  • Missing Plan: If your Recharge account is not on the required plan for a selected stream, the sync for that stream will also fail.

The following table lists the required read scopes and plan requirements for each stream:

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 and Custom 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 is designed to handle Recharge API limitations under normal usage.

Rate Limiting

Recharge implements rate limits to ensure API stability and fair usage. The API uses a "leaky bucket" algorithm, which allows for infrequent bursts of calls but maintains a sustainable request rate over time.

  • If the request rate exceeds the limit, the API will return a 429 - The request has been rate limited error.
  • When a 429 error is received, this Airbyte connector will automatically:
    • Pause for 2 seconds.
    • Retry the request.
    • This retry process can happen up to 10 times.

For more details, see Recharge API Rate Limits.

Error Handling

  • Transient HTTP Errors: Common transient errors (e.g., 500 - Internal server error, 503 - A 3rd party service on which the request depends has timed out) are handled by Airbyte's DefaultErrorHandler. This mechanism retries requests with an exponential backoff strategy, up to a maximum of 10 retries.
  • Persistent Issues: If you consistently encounter rate limit issues or other errors that are not automatically resolved by the connector's retry mechanisms, please create an issue on GitHub with relevant logs and details.

Changelog

<details> <summary>Expand to review</summary>
VersionDatePull RequestSubject
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.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-02PR_NUMBER_PLACEHOLDERMigrate 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
</details>