​

Configuring IUGU as a Source

​

1. Add account access

• API token: The token to authenticate against the Iugu API service. This field is required and stored securely.
  The financial_statement stream requires a live API token; test tokens will return no balance movement.
• Initial sync date: Starting point for data extraction. Only records created or updated after this date will be synced. This field is required.

​

2. Select streams

Tip: The stream can be found more easily by typing its name.

​

3. Configure data streams

• Layer: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
• Folder: a folder can be created inside the selected layer to group all tables being created from this new data source.
• Table name: we suggest a name, but feel free to customize it. You have the option to add a prefix to all tables at once and make this process faster!
• Sync Type: you can choose between INCREMENTAL and FULL_TABLE.
  • Incremental: every time the extraction happens, we’ll get only the new data, which is good if, for example, you want to keep every record ever fetched.
  • Full table: every time the extraction happens, we’ll get the current state of the data, which is good if, for example, you don’t want to have deleted data in your catalog.

​

4. Configure data source

• Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource here.
• Determine when to execute an Additional Full Sync. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while.

​

5. Check your new source

​

Streams and Fields

​

Available streams

​

Fields by stream

​

Data Model

​

Use Cases for Data Analysis

​

1. Invoice volume and totals by status

• Monitor cash position and outstanding receivables
• Compare paid vs. open or canceled invoices over a period

SELECT
   i.status,
   COUNT(*) AS invoice_count,
   SUM(i.total_cents) / 100.0 AS total_billed,
   SUM(i.total_paid_cents) / 100.0 AS total_paid
FROM
   nekt_raw.iugu_invoices i
WHERE
   CAST(i.updated_at AS TIMESTAMP) >= CURRENT_TIMESTAMP - INTERVAL '90' DAY
GROUP BY
   i.status
ORDER BY
   total_billed DESC

SELECT
   i.status,
   COUNT(*) AS invoice_count,
   SUM(i.total_cents) / 100.0 AS total_billed,
   SUM(i.total_paid_cents) / 100.0 AS total_paid
FROM
   `nekt_raw.iugu_invoices` i
WHERE
   TIMESTAMP(i.updated_at) >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 90 DAY)
GROUP BY
   i.status
ORDER BY
   total_billed DESC

​

2. Active subscriptions with customer email

• Segment subscribers by plan or contact
• Join subscription flags to customer master data

SELECT
   s.id AS subscription_id,
   s.plan_name,
   s.customer_email,
   c.name AS customer_name,
   s.price_cents / 100.0 AS price,
   s.currency,
   s.cycles_count,
   s.updated_at
FROM
   nekt_raw.iugu_subscriptions s
   LEFT JOIN nekt_raw.iugu_customers c ON s.customer_id = c.id
WHERE
   s.active = true
ORDER BY
   s.updated_at DESC

SELECT
   s.id AS subscription_id,
   s.plan_name,
   s.customer_email,
   c.name AS customer_name,
   s.price_cents / 100.0 AS price,
   s.currency,
   s.cycles_count,
   s.updated_at
FROM
   `nekt_raw.iugu_subscriptions` s
   LEFT JOIN `nekt_raw.iugu_customers` c ON s.customer_id = c.id
WHERE
   s.active = TRUE
ORDER BY
   s.updated_at DESC

​

Implementation Notes

​

Amounts and types

• Monetary amounts are often exposed both as integer cents fields and as formatted strings from the API; prefer _cents columns for aggregations when available.
• Some invoice timestamp fields exist as plain strings alongside *_iso datetime fields; use the ISO fields when you need reliable temporal filtering.

​

Incremental sync

• Streams use updated_at (or entry_date) as the replication key; set Start Date to bound the initial backfill.
• To prevent hitting the API’s 10,000 records listing limit on high-volume updates, incremental syncs also slide created_at windows automatically.
• Use Additional Full Sync if you need periodic reconciliation with IUGU’s current state.

​

Pagination and timeouts

• Bounded windows: To prevent the IUGU API from timing out (Cloudflare 504/524) when searching through sparse historical data, the connector walks backwards from today to the Start Date using bounded time windows. The window size dynamically adjusts (between 1 and 128 days) based on data density.
• Automatic throttling: If IUGU responds too slowly, the connector automatically shrinks the page size (from 100 down to 1 record) and halves the time window to bypass the timeout, then scales back up after a few successful clean pages. You may see warnings in your run logs when this happens, and the run may take longer.
• Timezones: Date filters and bounds in IUGU are day-granular and evaluate in Brasília time (America/Sao_Paulo).

​

Financial Statement (Extrato Financeiro)

• Live token required: The financial_statement stream requires a live API token. Test tokens will not return any balance movement.
• Synthetic IDs: The statement entries do not have a native ID returned by the API. The connector generates a synthetic SHA-256 ID based on the entry’s identifying fields and its position among identical entries on the same day.
• Timezones and daily syncs: The stream filters only by date, walking one day at a time using the America/Sao_Paulo timezone. Since entries do not have a time of day, hourly runs will re-read the current day and merge entries by their synthetic ID securely.
• Cent conversions: amount_cents and balance_cents arrive from the API as strings ("100.0") and are automatically cast to integers by the connector.

​

API and performance

• Selecting only the streams you need reduces extraction time and API load.
• Large nested arrays (for example split_rules, items, payment_methods) can make rows wide; consider flattening in a downstream Query or Notebook if you model them as separate tables.
• Listing limit: The IUGU API caps all list responses at 10,000 records, returning an error for deeper offsets. The connector safely bypasses this across all streams by automatically paginating through short date windows rather than relying on standard offset pagination.

​

Skills for agents