Recharge

Knowi connects directly to Recharge via the 2021-11 REST API, enabling MRR, churn, LTV, and cohort analytics on your subscription data. Join Recharge with Shopify, Stripe, Klaviyo, your data warehouse, and 30+ other sources - no ETL required.

Overview

1. Connect to Recharge using an API access token from your Recharge admin.
2. Pull from pre-built collections (Subscriptions, Customers, Orders, Charges, Products, Discounts, Addresses, One-Time Products, Store Info) or use the Custom Query collection for any Recharge endpoint.
3. Join Recharge data with Shopify, Stripe, MongoDB, PostgreSQL, REST APIs, and 30+ other sources without a warehouse.
4. Build MRR dashboards, run cohort retention analysis, and ask questions in natural language.

Connecting

Step 1: Generate a Recharge API Token

1. Log in to your Recharge admin.
2. Navigate to Tools & apps > API tokens in the left sidebar. (Only store owners can access API tokens by default.)
3. Click Create an API Token.
4. Enter a token name (e.g., "Knowi Analytics").

5. Configure the API scopes. For analytics, grant Read access to:

   • read_subscriptions — Required for the Subscriptions and One-Time Products collections
   • read_customers — Required for the Customers and Addresses collections
   • read_orders — Required for the Orders and Charges collections
   • read_products — Required for the Products collection
   • read_discounts — Required for the Discounts collection
   • read_store — Required for the Store Info collection

   Tip: Grant only the scopes you need. Custom Query resources may require additional read scopes, such as read_payment_methods for payment methods or read_plans for plans. You can revisit the token later and add more scopes as you expand your analytics.

6. Click Save and copy the generated token.

Step 2: Connect in Knowi

1. Log in to Knowi and navigate to Queries from the left sidebar.
2. Click New Datasource (the + icon), then search for Recharge in the datasource selector.
3. Fill in the form:
   • Datasource Name: A label for this connection (e.g., "Recharge Production")
   • Access Token: Paste the token you copied in Step 1
4. Click Save to store the datasource.

Step 3: Create a Query

1. Click Start Querying (or create a new query and select your Recharge datasource).
2. Select a Collection from the "Recharge Options" dropdown:
   • Subscriptions — Pull all subscriptions with status, billing frequency, and customer associations
   • Customers — Customer records with subscription counts and totals
   • Orders — All orders (recurring and one-time)
   • Charges — Individual charge records (success, error, queued, refunded)
   • Products — Products configured for subscription
   • Discounts — Active and historical discount codes
   • Addresses — Customer shipping addresses with linked subscriptions
   • One-Time Products — Add-ons attached to recurring orders
   • Store Info — Store-level configuration and metadata
   • Custom Query — Hit any Recharge API endpoint
3. Fill in the optional filter parameters (status, date ranges, customer ID).
4. Click Preview to see results.
5. Name your dataset and click Create & Run to save and schedule.

Available Collections

Subscriptions

Returns all subscriptions with billing frequency, pricing, status, and customer associations. Core data for MRR and churn dashboards.

Parameters:

Default Cloud9QL:

select subscriptions;
select expand(subscriptions);
select id, customer_id, product_title, sku, price, currency, quantity,
       status, order_interval_frequency, order_interval_unit,
       next_charge_scheduled_at, created_at, cancelled_at
order by created_at desc;

Customers

Returns all customers with subscription counts and lifetime totals.

Parameters:

Orders

Recurring and one-time orders generated by subscriptions.

Parameters: Status (success, error, queued, skipped), Customer ID, Created date range, Scheduled date range.

Charges

Individual charge attempts. Most useful for failed-payment dunning analysis and gross-vs-net revenue reconciliation.

Parameters: Status (success, error, queued, skipped, refunded, partially_refunded), Customer ID, Created and Scheduled date ranges.

Products

Products configured for subscription with billing frequency and discount settings.

Discounts

Discount codes with usage counts and status (enabled, disabled, fully_disabled).

Addresses

Customer shipping addresses linked to subscriptions and discount codes.

One-Time Products (Onetimes)

One-time add-ons that ride along with recurring orders.

Store Info

Store-level metadata returned as a single record. Useful as a constant join key when working across multiple Recharge stores.

Custom Query

Hit any endpoint not covered by the pre-built collections. Examples: checkouts, payment_methods, credits, metafields, webhooks, async_batches, collections.

Date Tokens

Recharge accepts ISO 8601 timestamps. Knowi date tokens automatically format for you:

{$c9_today:yyyy-MM-dd}T00:00:00Z       - today, midnight UTC
{$c9_today-30d:yyyy-MM-dd}T00:00:00Z   - 30 days ago, midnight UTC
{$c9_thismonth:yyyy-MM-dd}T00:00:00Z   - first day of this month, midnight UTC
{$c9_today-1d:yyyy-MM-dd}T00:00:00Z    - yesterday, midnight UTC (for daily incremental syncs)

Cloud9QL Examples

MRR by Product

select subscriptions;
select expand(subscriptions);
select status, product_title, price, order_interval_frequency, order_interval_unit;

# Normalize to monthly revenue
select product_title,
       (case order_interval_unit
         when 'day'   then price * (30.0 / order_interval_frequency)
         when 'week'  then price * (4.345 / order_interval_frequency)
         when 'month' then price / order_interval_frequency
         else price end) as mrr_contribution
where status = 'active';

select product_title, sum(mrr_contribution) as mrr
group by product_title
order by mrr desc;

Daily Cancellation Count (Active Churn)

select subscriptions;
select expand(subscriptions);
select date_format(cancelled_at, 'yyyy-MM-dd') as cancel_date
where cancelled_at is not null
  and cancelled_at >= '{$c9_today-30d:yyyy-MM-dd}T00:00:00Z';

select cancel_date, count(*) as cancellations
group by cancel_date
order by cancel_date desc;

Failed Charge Rate (Passive Churn Signal)

select charges;
select expand(charges);
select status, date_format(processed_at, 'yyyy-MM-dd') as charge_date
where processed_at >= '{$c9_today-7d:yyyy-MM-dd}T00:00:00Z';

select charge_date,
       sum(case when status = 'error' then 1 else 0 end) as failed,
       count(*) as total
group by charge_date
order by charge_date desc;

Scheduling Queries

Recharge data changes constantly. Schedule queries to refresh on a cadence that matches your reporting needs:

1. Open the query, click the schedule icon.
2. Set a frequency (every hour, every 6 hours, daily, weekly).
3. Use the Updated After parameter with {$c9_lastrun:yyyy-MM-dd'T'HH:mm:ss'Z'} to fetch only changes since the last run.

Cross-Source Joins

Recharge becomes much more powerful when joined with other sources. Some common patterns:

Recharge + Shopify: Reconcile Subscription vs Storefront Revenue

select r.product_title,
       r.mrr as recharge_mrr,
       s.total_revenue as shopify_revenue
from recharge_mrr_by_product as r
left join shopify_revenue_by_product as s
  on r.product_title = s.product_title
order by recharge_mrr desc;

Recharge + Stripe: Subscription LTV minus Processing Fees

select c.customer_id,
       sum(c.total_price) as gross_ltv,
       sum(s.fee) as stripe_fees,
       sum(c.total_price) - sum(s.fee) as net_ltv
from recharge_charges as c
left join stripe_balance_transactions as s
  on c.transaction_id = s.source
where c.status = 'success'
group by c.customer_id;

Recharge + Klaviyo: Did Win-Back Emails Reduce Cancellations?

Compare cohorts that received Klaviyo win-back campaigns vs cohorts that did not, tracking retention rates 30/60/90 days post-cancellation.

See Cross-source joins documentation for details.

Rate Limits and Pagination

• Rate limit: 40 burst calls, 2 calls per second sustained, per store. Knowi automatically respects this with backoff on 429 responses.
• Pagination: Cursor-based with up to 250 records per page. Knowi pulls all pages automatically using the next_cursor field.
• Backfills: Large backfills (100K+ subscriptions) complete in a few hours due to the rate limit. Run during off-hours and rely on incremental syncs after that.

Troubleshooting

Resources

• Recharge Developer Docs (2021-11)
• Recharge API Token guide
• Cursor pagination reference
• Recharge Tech Partner Program
• Cloud9QL reference
• Cross-source joins
• Embedded analytics with SSO