> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Aira as a data source

> Bring data from Aira (customers, invoices, contracts and usage resources) to your Lakehouse.

Aira is a Brazilian billing platform for usage-based and recurring pricing: it turns usage events into invoices, manages contracts and plans, and collects payments. The connector uses the Aira public API to extract your customers and their payment accounts and credit pools, your invoices with their line items, payments and discounts, your contracts with their plan instances and recurring discounts, and your metered resources. With it you can analyze revenue, billing and collection in your Lakehouse.

## Configuring Aira as a Source

In the [Sources](https://app.nekt.ai/sources) tab, click on the "Add source" button located on the top right of your screen. Then, select the Aira option from the list of connectors.

Click **Next** and you'll be prompted to add your access.

### 1. Add account access

Aira gives access to your data through an **API key**. Keys are provisioned by the Aira team: request one from Aira support at [contato@useaira.com](mailto:contato@useaira.com), asking for **read** access to the data you want to extract (for example, `invoices:read` and `contracts:read`). The key is delivered only once, so store it safely. The connector only reads data: it never writes to Aira.

<Note>
  If your Aira key is restricted to a list of allowed IP addresses, ask Aira support to allow Nekt's IP addresses for the key, or to remove the restriction.
</Note>

The following configurations are available:

* **API Key**: the Aira API key. Required.

* **Start Date** (advanced): only invoices whose invoice date is on or after this date are extracted. Leave it empty to extract every invoice. Customers, contracts and resources are always extracted in full.

* **Lookback Days** (advanced, default 7): on incremental syncs, invoices that are already paid or canceled are re-read only when their invoice date is at most this many days before the date of the previous sync. Invoices that are not paid or canceled yet are always re-read. See the Sync Type note below.

Once you're done, click **Next**.

### 2. Select streams

Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis. You can select entire groups of streams or pick specific ones.

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

<Note>
  Some streams make one request per record of another stream: payment accounts and credit pools per customer, invoice details and invoice discounts per refreshed invoice, contract details and recurring discounts per contract, and plan instances per plan instance. Invoice line items and invoice payments come from the invoice details response, with no extra request. Select only the streams you need.
</Note>

Before reading any data, each sync checks once that the API key can read every selected stream. If it can't, the sync stops right away and names the streams whose permission is missing, so you can ask Aira support for the permission or deselect them.

Select the streams and click **Next**.

### 3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.

* **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**: Aira does not expose when a record was last updated, so customers, invoices, contracts and resources are FULL\_TABLE: each sync replaces the table with what Aira currently holds. Invoice details, line items, payments and discounts are INCREMENTAL by invoice date. Each incremental sync re-reads:

  * every invoice that is not paid or canceled yet;
  * every invoice that was not paid or canceled on the previous sync, so the sync in which an invoice gets paid or canceled reads it one more time;
  * every invoice dated up to **Lookback Days** before the date of the previous sync, which covers invoices created and paid between two syncs. An invoice imported or created with a past date that is already paid or canceled when it first appears is only read by a full sync: run a full sync after an import.

  The first sync, a full sync, and the first sync after you select one of these four streams read every invoice. Read more about Sync Types [here](https://docs.nekt.com/get-started/core-concepts/types-of-sync).

<Tip>
  The `invoices` table always has the current status and total of every invoice. Join it with the detail tables by `invoice_id` when you need the latest status of an invoice.
</Tip>

<Note>
  An incremental table never deletes rows: a discount or line item removed from an invoice in Aira stays in its table. Every row of the invoice detail, line item, payment and discount tables has a `refreshed_at` column: the start of the sync that last read that invoice, the same value for the whole sync. A row is current when its `refreshed_at` matches the invoice's `refreshed_at` in `invoice_details`:

  ```sql theme={null}
  SELECT li.*
  FROM invoice_line_items li
  JOIN invoice_details d
    ON d.id = li.invoice_id
   AND d.refreshed_at = li.refreshed_at
  ```

  If you don't sync `invoice_details`, keep the rows whose `refreshed_at` is the most recent one for their `invoice_id` in the same table.
</Note>

Once you are done configuring, click **Next**.

### 4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters.

To define your [Trigger](https://docs.nekt.com/get-started/core-concepts/triggers), consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times).

Optionally, you can define some additional settings:

* 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](https://docs.nekt.com/get-started/core-concepts/resource-control).

Once you are ready, click **Next** to finalize the setup.

### 5. Check your new source

You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.

<Warning>For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run.</Warning>

## Troubleshooting

* **"Aira rejected the API key"**: the key does not exist, was deactivated or revoked, or has expired. Request a new key from Aira support and update it in the source configuration.
* **"The Aira API key is not allowed to read the data of the selected streams ..."**: the key does not have the read permission for that data. Ask Aira support to grant it, or deselect the streams listed in the message.
* **"Nekt's address is not on that list"**: the key is restricted to allowed IP addresses. Ask Aira support to allow Nekt's IP addresses.
* **"N of M records were not found in Aira while reading"**: those records were deleted in Aira during the sync and were skipped. If every record of a stream is not found (5 or more), the sync stops instead of loading an empty table. Contact Nekt support if it happens again.
* **Subsidiaries**: subsidiaries (filiais) are rows of the `customers` table with `type = 'subsidiary'` and their organization in `parent_customer_id`. To check that they all arrived, compare `SELECT count(*) FROM customers WHERE type = 'subsidiary'` with the subsidiaries shown in Aira.

# Streams and Fields

Below you'll find all available data streams from Aira and their corresponding fields. API reference: [Aira API](https://docs.useaira.com/api-reference/introduction).

<Note>
  Lists and nested objects are stored as JSON text. Every monetary amount is in **cents**, as Aira returns it (divide by 100 for reais). Discount `amount` values are cents when `method` is `fixed` and basis points (10000 = 100%) when `method` is `percentage`. Credit pool amounts are decimal text in the pool's credit unit.
</Note>

## Customers

<AccordionGroup>
  <Accordion title="Customers">
    Every customer registered in Aira, including subsidiaries and archived customers.

    Table: `customers` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Unique identifier (UUID) of the customer in Aira. |
    | `external_id` | String | Identifier of the customer in your own system, used across Aira to identify it. |
    | `name` | String | Name of the customer. |
    | `invoice_prefix` | String | Prefix of the customer's invoice numbers, generated by Aira. |
    | `type` | String | Customer type in the organization hierarchy: individual, organization or subsidiary. |
    | `parent_customer_id` | String | Parent customer (organization) id when the customer is a subsidiary. |
    | `archived_at` | Datetime | When the customer was archived; null for active customers. |
    | `custom_fields` | String (JSON) | Custom fields defined in Aira for the record (JSON object; each value is a string or a list of strings). |
  </Accordion>

  <Accordion title="Customer Payment Accounts">
    Payment accounts of each customer: the legal entity (CNPJ/CPF, address, billing e-mails) that receives the invoices. Archived accounts are included.

    Table: `customer_payment_accounts` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Unique identifier (UUID) of the payment account. |
    | `customer_id` | String | Customer that owns the payment account. |
    | `archived_at` | Datetime | When the payment account was archived; null for active accounts. |
    | `legal_entity_id` | String | Unique identifier of the legal entity behind the payment account. |
    | `legal_entity_trade_name` | String | Trade name (nome fantasia) of the legal entity. |
    | `legal_entity_business_name` | String | Registered business name (razão social) of the legal entity. |
    | `legal_entity_emails` | Array of strings | Billing e-mail addresses that receive the invoices. |
    | `legal_entity_tax_id` | String | Tax identification number of the legal entity, digits only. |
    | `legal_entity_tax_id_type` | String | Kind of tax identification number: cnpj or cpf. |
    | `legal_entity_zip_code` | String | Postal code (CEP) of the legal entity's address. |
    | `legal_entity_street` | String | Street of the legal entity's address. |
    | `legal_entity_number` | String | Street number of the legal entity's address. |
    | `legal_entity_neighborhood` | String | Neighborhood of the legal entity's address. |
    | `legal_entity_city` | String | City of the legal entity's address. |
    | `legal_entity_state` | String | State (UF) of the legal entity's address. |
    | `legal_entity_country` | String | Country of the legal entity's address. |
    | `legal_entity_complement` | String | Address complement of the legal entity. |
    | `legal_entity_custom_fields` | String (JSON) | Custom fields defined in Aira for the record (JSON object; each value is a string or a list of strings), set on the legal entity. |
  </Accordion>

  <Accordion title="Customer Credit Pools">
    Prepaid credit pools of each customer, with the available balance and the automatic top-up settings.

    Table: `customer_credit_pools` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Unique identifier (UUID) of the credit pool. |
    | `customer_id` | String | Customer that owns the credit pool. |
    | `currency_unit_id` | String | Credit currency unit the pool is denominated in. |
    | `currency_unit_name` | String | Name of the credit currency unit. |
    | `currency_unit_code` | String | Code of the credit currency unit. |
    | `start_date` | Date | Date the credit pool starts. |
    | `renewal_credit_amount` | String | Credits granted on each renewal, as a decimal string in the pool's currency unit (as returned by Aira). |
    | `available_amount` | String | Current credit balance, as a decimal string in the pool's currency unit (as returned by Aira). |
    | `schedule_renewal_date` | Date | Next scheduled renewal date of the pool. |
    | `top_up_created_by` | String | User who configured the automatic top-up. |
    | `top_up_credit_package_amount` | String | Credits granted per purchased top-up package, as a decimal string in the pool's currency unit. |
    | `top_up_price` | Number | Price billed per purchased top-up package, in cents. |
  </Accordion>
</AccordionGroup>

## Invoices

<AccordionGroup>
  <Accordion title="Invoices">
    Every invoice, canceled ones included, with its current status and total. This is the table to use for the current status of an invoice.

    Table: `invoices` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Unique identifier (UUID) of the invoice in Aira. |
    | `customer_id` | String | Customer the invoice bills. |
    | `customer_name` | String | Name of the customer the invoice bills. |
    | `customer_external_id` | String | Identifier of the billed customer in your own system. |
    | `billing_cycle_sequence` | Integer | Sequence of the invoice's billing cycle within its contract (1 for the first cycle, 2 for the second, ...). |
    | `billing_account_business_name` | String | Registered business name (razão social) of the billed legal entity. |
    | `billing_account_tax_id` | String | Tax identification number of the billed legal entity, digits only. |
    | `billing_account_tax_id_type` | String | Kind of tax identification number of the billed legal entity: cnpj or cpf. |
    | `invoice_number` | String | Human-readable invoice number (customer invoice prefix plus a sequential counter). |
    | `invoice_date` | Date | Closing date of the invoice (end of the billed period). |
    | `due_date` | Date | Payment due date; null before the invoice is issued. |
    | `total_amount` | Number | Final invoice amount, in cents. |
    | `status` | String | Current status: open, in\_review, issued, synced, pending, paid, overdue, canceled or failed. |
  </Accordion>

  <Accordion title="Invoice Details">
    The full invoice: amounts breakdown, billed and issuing legal entities, payments, status history and generated files.

    Table: `invoice_details` · Primary key: `id` · Sync: Incremental

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Unique identifier (UUID) of the invoice in Aira. |
    | `invoice_date` | Date | Closing date of the invoice (end of the billed period), used as the incremental replication key. |
    | `invoice_id` | String | Same as id; kept for joins with the other invoice streams. |
    | `refreshed_at` | Datetime | UTC start of the run that last read this invoice from Aira. |
    | `idempotency_key` | String | Key that identifies the invoice for idempotent creation. |
    | `customer_id` | String | Customer the invoice bills. |
    | `payment_account_id` | String | Customer payment account used as the billing account of the invoice. |
    | `contract_id` | String | Contract that generated the invoice; null for one-off and imported invoices. |
    | `billing_cycle_sequence` | Integer | Sequence of the invoice's billing cycle within its contract. |
    | `issuing_account` | String (JSON) | Snapshot of the legal entity issuing the invoice (the seller), captured at creation (JSON object). |
    | `billing_account` | String (JSON) | Snapshot of the billed legal entity, captured at creation (JSON object). |
    | `invoice_allocation_strategy` | String | How the contract distributes charges across payment accounts: single, percent\_split or subsidiary\_usage\_split. |
    | `last_calculated_at` | Datetime | When the billing engine last computed the invoice amounts. |
    | `invoice_number` | String | Human-readable invoice number. |
    | `memo` | String | Free-form memo attached to the invoice. |
    | `subtotal_amount` | Number | Sum of the line item subtotals before adjustments, in cents. |
    | `adjustment_amount` | Number | Net amount of all adjustments (discounts and allocation offsets), in cents; negative when they reduce the amount owed. |
    | `total_amount` | Number | Final invoice amount (subtotal + adjustments), in cents. |
    | `discount_amount` | Number | Discount portion of the adjustments, in cents; negative when discounts were applied. |
    | `status` | String | Invoice status when this row was last refreshed (the invoices stream always has the current status). |
    | `is_locked` | Boolean | Whether the invoice contents are locked against edits (derived from the status). |
    | `failure_reason` | String | Reason of the most recent failure on the invoice (e.g. ERP sync or payment issue). |
    | `source` | String | How the invoice originated: contract, one\_off or import. |
    | `auto_issue` | Boolean | Whether the invoice is issued automatically when its billing cycle closes. |
    | `amount_due` | Number | Outstanding amount due, in cents; null when not tracked. |
    | `due_date` | Date | Payment due date; null before the invoice is issued. |
    | `line_item_groups` | String (JSON) | Line item groups with their line items, one group per plan instance (JSON array). |
    | `standalone_line_items` | String (JSON) | Line items outside any group, e.g. minimum commitments and additional charges (JSON array). |
    | `payments` | String (JSON) | Payment charges registered for the invoice at the payment provider (JSON array). |
    | `status_history` | String (JSON) | Status transitions of the invoice, most recent first (JSON array). |
    | `artifacts` | String (JSON) | Files generated for the invoice, e.g. the invoice PDF (JSON array). |
  </Accordion>

  <Accordion title="Invoice Line Items">
    One row per invoice line item, grouped (one group per plan instance) or standalone. Read from the same response as Invoice Details, with no extra request.

    Table: `invoice_line_items` · Primary key: `id` · Sync: Incremental

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Unique identifier (UUID) of the line item. |
    | `invoice_id` | String | Invoice the line item belongs to. |
    | `invoice_date` | Date | Closing date of the invoice (end of the billed period), used as the incremental replication key. |
    | `refreshed_at` | Datetime | UTC start of the run that last read this invoice from Aira. Rows of an invoice whose refreshed\_at is older than the invoice's refreshed\_at in invoice\_details were no longer returned by Aira (e.g. deleted) and can be filtered out. |
    | `line_item_group_id` | String | Line item group containing the line item; null for standalone line items. |
    | `line_item_group_name` | String | Display name of the line item group, typically the plan or product name. |
    | `plan_id` | String | Plan whose instance generated the line item group; null outside plan groups. |
    | `plan_instance_id` | String | Plan instance that generated the line item group; null outside plan groups. |
    | `idempotency_key` | String | Key that identifies the line item within the invoice. |
    | `customer_id` | String | Customer whose consumption the line item bills (may be a subsidiary of the invoice's customer). |
    | `product_id` | String | Product the line item belongs to. |
    | `item_id` | String | Catalog item billed by the line; null when not backed by a catalog item. |
    | `resource_id` | String | Metered resource behind a usage\_based line item. |
    | `license_id` | String | License behind a license\_based line item. |
    | `name` | String | Display name of the line item on the invoice. |
    | `scope` | String | What the line item charges for: usage\_based, license\_based, fixed, minimum\_commitment, contract\_minimum\_commitment, credit\_purchase, additional\_charge, one\_off or tax\_gross\_up. |
    | `start_date` | Date | Start of the period covered by the line item. |
    | `end_date` | Date | End of the period covered by the line item. |
    | `total_usage` | Number | Total usage billed, in the unit given by usage\_format; null for charges without usage. |
    | `usage_format` | String | How to read total\_usage: unit (count of resource units) or currency (amount in cents). |
    | `subtotal_amount` | Number | Line item amount before adjustments, in cents. |
    | `adjustment_amount` | Number | Net amount of the adjustments on the line item, in cents. |
    | `total_amount` | Number | Final line item amount (subtotal + adjustments), in cents. |
    | `discount_amount` | Number | Discount portion of the adjustments, in cents. |
    | `metadata` | String (JSON) | Pricing metadata of the line item, shaped by its type (JSON object). |
    | `sub_line_items` | String (JSON) | Breakdown of the amount into priced rows: tiers, unit prices, prorations (JSON array). |
    | `adjustments` | String (JSON) | Adjustments applied on top of the subtotal, such as discounts and allocation offsets (JSON array). |
  </Accordion>

  <Accordion title="Invoice Payments">
    Payment charges registered for each invoice at the payment provider (boleto, Pix, credit card). Read from the same response as Invoice Details.

    Table: `invoice_payments` · Primary key: `id` · Sync: Incremental

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Unique identifier of the payment in Aira. |
    | `invoice_id` | String | Invoice the payment charges. |
    | `invoice_date` | Date | Closing date of the invoice (end of the billed period), used as the incremental replication key. |
    | `refreshed_at` | Datetime | UTC start of the run that last read this invoice from Aira. Rows of an invoice whose refreshed\_at is older than the invoice's refreshed\_at in invoice\_details were no longer returned by Aira (e.g. deleted) and can be filtered out. |
    | `amount` | Number | Amount charged by the payment, in cents. |
    | `due_date` | Date | Due date of the payment charge. |
    | `payment_method` | String | How the payment is collected: pix, bank\_slip (boleto), bolepix (boleto payable via Pix), credit\_card or bank\_transfer. |
    | `status` | String | Payment status when the invoice was last refreshed: created, pending, paid, failed, canceled or expired. |
  </Accordion>

  <Accordion title="Invoice Discounts">
    Discounts applied to each invoice, line item group or line item, inactive ones included. Refreshed for the same invoices as Invoice Details.

    Table: `invoice_discounts` · Primary key: `id` · Sync: Incremental

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Unique identifier (UUID) of the discount. |
    | `invoice_id` | String | Invoice the discount belongs to. |
    | `invoice_date` | Date | Closing date of the invoice (end of the billed period), used as the incremental replication key. |
    | `refreshed_at` | Datetime | UTC start of the run that last read this invoice from Aira. Rows of an invoice whose refreshed\_at is older than the invoice's refreshed\_at in invoice\_details were no longer returned by Aira (e.g. deleted) and can be filtered out. |
    | `target` | String | What the discount applies to: invoice, line\_item\_group or line\_item. |
    | `target_idempotency_key` | String | Idempotency key of the targeted invoice, line item group or line item. |
    | `method` | String | How amount is read: fixed (amount in cents) or percentage (amount in basis points). |
    | `reason` | String | Why the discount exists: manual\_discount, contract\_proration or contract\_recurring. |
    | `description` | String | Display text of the discount on the invoice. |
    | `amount` | Number | Discount value: whole cents when method is fixed; basis points when method is percentage (10000 = 100%). |
    | `is_active` | Boolean | Whether the discount currently affects the invoice totals. |
    | `custom_fields` | String (JSON) | Custom fields defined in Aira for the discount (JSON object). |
  </Accordion>
</AccordionGroup>

## Contracts

<AccordionGroup>
  <Accordion title="Contracts">
    Every contract, in all statuses, with the plan instances attached to it.

    Table: `contracts` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Unique identifier (UUID) of the contract in Aira. |
    | `start_date` | Date | Start date of the contract. |
    | `end_date` | Date | End date of the contract; null when it has no end date. |
    | `status` | String | Current status of the contract: active, canceled, completed or draft. |
    | `custom_fields` | String (JSON) | Custom fields defined in Aira for the record (JSON object; each value is a string or a list of strings). |
    | `plan_instances` | String (JSON) | Plan instances attached to the contract, with id, plan\_id, name and status (JSON array). While the contract is draft or active only its active plan instances are listed. |
  </Accordion>

  <Accordion title="Contract Details">
    The full contract: customer, contract number, issuing legal entity, billing schedule, payment settings, usage scope and allocations.

    Table: `contract_details` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Unique identifier (UUID) of the contract in Aira. |
    | `contract_number` | String | Human-readable contract number, sequential per customer (e.g. ACMEX-CTR-01). |
    | `customer_id` | String | Customer the contract belongs to. |
    | `legal_entity_id` | String | Legal entity (seller) issuing the contract's invoices. |
    | `legal_entity_business_name` | String | Registered business name (razão social) of the issuing legal entity. |
    | `legal_entity_trade_name` | String | Trade name (nome fantasia) of the issuing legal entity. |
    | `start_date` | Date | Date the contract becomes active. |
    | `end_date` | Date | Date the contract expires; null when it has no end date. |
    | `retroactive_date` | Date | Retroactive date from which contract changes apply. |
    | `status` | String | Current status of the contract: active, canceled, completed or draft. |
    | `rate_adjustment_index` | String | Reference index (e.g. IPCA) used for mass price adjustments. |
    | `custom_fields` | String (JSON) | Custom fields defined in Aira for the record (JSON object; each value is a string or a list of strings). |
    | `tax_regime_id` | String | Tax regime applied to invoices generated from the contract. |
    | `invoice_allocation_strategy` | String | How charges are distributed across payment accounts: single, percent\_split or subsidiary\_usage\_split. |
    | `include_new_subsidiaries_on_usage_scope` | Boolean | Whether future subsidiaries are automatically included in the usage scope. |
    | `auto_issue` | Boolean | Whether invoices are issued automatically when a billing cycle closes. |
    | `usage_scopes` | String (JSON) | Customers whose usage is billed by the contract (JSON array of {customerId}). |
    | `allocations` | String (JSON) | Payment accounts the invoices are allocated to, with their percentage (JSON array). |
    | `billing_settings_invoice_minimum_amount` | Number | Minimum invoice amount of the contract. |
    | `billing_settings_product_id` | String | Product used for the contract-level charges. |
    | `billing_schedule_period_unit` | String | Billing period unit: week, month, quarter or year. |
    | `billing_schedule_anchor_source` | String | How the billing cycle anchor is chosen (e.g. based\_on\_contract\_start\_date, first\_day\_of\_month, explicit). |
    | `billing_schedule_anchor_day` | Number | Day used as the billing cycle anchor. |
    | `billing_schedule_anchor_month` | Number | Month used as the billing cycle anchor. |
    | `payment_gateway_payment_method` | String | How invoices are collected: bolepix, bank\_slip, pix, credit\_card or bank\_transfer. |
    | `payment_gateway_due_date_mode` | String | How the due date is set: days\_after\_issue or fixed\_day. |
    | `payment_gateway_due_offset_days` | Number | Days after issue until the due date (days\_after\_issue mode). |
    | `payment_gateway_due_day` | Number | Day of the month of the due date (fixed\_day mode). |
    | `payment_gateway_due_month_offset` | Integer | 0 for a due date in the issue month, 1 for the next month. |
    | `payment_gateway_roll_due_date_to_business_day` | Boolean | Whether a due date on a non-business day moves to the next business day. |
    | `plan_instances` | String (JSON) | Plan instances attached to the contract (JSON array). |
  </Accordion>

  <Accordion title="Contract Recurring Discounts">
    Recurring discounts configured on each contract.

    Table: `contract_recurring_discounts` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Unique identifier (UUID) of the recurring discount. |
    | `contract_id` | String | Contract the discount is configured on. |
    | `plan_id` | String | Plan targeted by the discount (plan and metric scopes). |
    | `target_scope` | String | What the discount applies to on each invoice: invoice, plan, metric or contract\_minimum\_amount. |
    | `method` | String | How amount is read: fixed (amount in cents) or percentage (amount in basis points). |
    | `amount` | Number | Discount value: whole cents when method is fixed; basis points when method is percentage (10000 = 100%). |
    | `description` | String | Display text of the discount on invoices. |
    | `start_date` | Date | Billing cycle date the discount starts at. |
    | `invoice_count` | Number | How many invoices the discount applies to; null means until deactivated. |
    | `distribution_mode` | String | For fixed discounts on split invoices: full (whole amount on each invoice) or proportional. |
    | `is_active` | Boolean | Whether the discount is applied to new billing cycles. |
    | `custom_fields` | String (JSON) | Custom fields defined in Aira for the record (JSON object; each value is a string or a list of strings). |
  </Accordion>

  <Accordion title="Plan Instances">
    Plan instances listed on each contract, with the plan and the charges (pricing) of the version in force.

    Table: `plan_instances` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Unique identifier (UUID) of the plan instance. |
    | `contract_id` | String | Contract the plan instance is attached to. |
    | `plan_id` | String | Plan the instance was created from. |
    | `plan_name` | String | Name of the plan. |
    | `plan_description` | String | Description of the plan. |
    | `plan_product_id` | String | Product the plan belongs to. |
    | `status` | String | Current status of the plan instance: active, canceled or completed. |
    | `active_plan_instance_version_id` | String | Plan instance version currently in force. |
    | `active_plan_version_id` | String | Plan version the active instance version is based on. |
    | `active_plan_instance_version_reason` | String | Why the active version exists: created\_from\_plan\_version, duplicated\_from\_contract, manual\_override, readjustment or rollback. |
    | `active_plan_instance_version_number` | Number | Version number of the active plan instance version. |
    | `active_plan_instance_version_metadata` | String (JSON) | Context of the active version, shaped by its reason (e.g. readjustment percentage) (JSON object). |
    | `plan_charges` | String (JSON) | Charges of the active version with their pricing model, prices and billing frequency (JSON array). |
  </Accordion>
</AccordionGroup>

## Usage

<AccordionGroup>
  <Accordion title="Resources">
    Metered resources: the usage metrics that turn the events you send to Aira into billable quantities.

    Table: `resources` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Unique identifier (UUID) of the resource in Aira. |
    | `name` | String | Name of the resource. |
    | `type` | String | Type of the resource: unit or currency. |
    | `aggregation` | String | How events are aggregated in a period: sum, last\_during\_period or unique. |
    | `aggregate_by_field` | String | Event field aggregated to compute the usage. |
    | `billing_model` | String | Billing model of the resource: in\_full or proration. |
    | `item_id` | String | Catalog item related to the resource. |
    | `filters` | String (JSON) | Filters selecting the events the resource counts, as {property, value} conditions (JSON array). |
    | `archived_at` | Datetime | When the resource was archived; null when it is active. |
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.