# Billing & Usage

Subscription management, usage monitoring, and cost tracking.

## Plans & Pricing

### Plan Limits

| Limit                       | Free               | Pro                  | Enterprise                             |
| --------------------------- | ------------------ | -------------------- | -------------------------------------- |
| Queries/month               | 1,000              | 10,000               | Negotiable                             |
| Tokens/month (input+output) | 100,000            | 1,000,000            | Unlimited                              |
| Agents                      | 1                  | 10                   | Unlimited                              |
| Data sources                | 3                  | 25                   | Unlimited                              |
| Users                       | 3                  | 25                   | Unlimited                              |
| Data retention              | 30 days            | 90 days              | Custom                                 |
| RAG strategies              | All                | All                  | All                                    |
| Browser extension           | ✅                  | ✅                    | ✅                                      |
| API access                  | ✅                  | ✅                    | ✅                                      |
| Analytics                   | Last 7 days        | Last 90 days         | Custom                                 |
| SSO (SAML/OAuth)            | ❌                  | ❌                    | ✅                                      |
| Support                     | Community (GitHub) | Email (24h response) | Priority (4h response) + Slack channel |
| SLA                         | None               | 99% uptime           | 99.9% uptime                           |
| **Price**                   | $0                 | $99/month            | Contact sales                          |

**Overage charges** (Pro plan):

* Queries: $0.01 per query over limit
* Tokens: $0.001 per 1K tokens over limit

**Billing cycle**: Monthly (1st of month) or annual (prepaid discount available)

### Add-Ons (Pro/Enterprise)

| Add-On                   | Price              | Notes             |
| ------------------------ | ------------------ | ----------------- |
| Additional user          | $10/user/month     | Min 5 users       |
| Additional data source   | $25/source/month   | Beyond plan limit |
| Query volume increase    | $50 per 5K queries | Prepaid blocks    |
| Dedicated infrastructure | Contact sales      | Enterprise only   |

## Manage Subscription

### View Current Plan

**Location**: Settings → Billing

**Displayed info**:

* Plan name (Free/Pro/Enterprise)
* Monthly cost (e.g., "$99/month")
* Usage (e.g., "8,245 / 10,000 queries")
* Next billing date (e.g., "Feb 1, 2024")
* Payment method (e.g., "Visa \*\*\*\*1234")

**Expected view**: Card showing current plan details, usage bars with percentages

### Upgrade Plan

**Location**: Settings → Billing → Upgrade Plan button

1. Click **Upgrade Plan**
2. Select new plan (Pro or Enterprise contact sales)
3. Review changes modal:
   * New monthly cost
   * Prorated charge today
   * New limits
4. Click **Confirm Upgrade**
5. Enter payment info (if not on file)
6. Confirm

**Expected result**:

* Upgrade takes effect immediately
* Prorated charge billed to payment method
* Usage limits update (visible in 5-10 minutes)
* Confirmation email sent

**Prorating example**:

* Upgrade on Jan 15 (mid-cycle)
* 15 days remaining in month
* Pro plan: $99/month = $3.30/day
* Prorated charge: $3.30 × 15 = $49.50

### Downgrade Plan

**Location**: Settings → Billing → Change Plan

1. Click **Change Plan**
2. Select lower tier (Free if currently Pro)
3. Review limitations warning:
   * Reduced query limit
   * Features removed (e.g., SSO)
   * Data retention reduced
4. Confirm downgrade

**Expected result**:

* Scheduled for end of current billing period
* Current plan continues until then
* No refund for unused days
* Warning shown: "Effective Feb 1, 2024"

**Resource cleanup** (when downgrade activates):

* Agents beyond limit disabled (status: "Inactive - Plan Limit")
* Data sources beyond limit disabled
* Users beyond limit set to readonly

### Cancel Subscription

**Location**: Settings → Billing → Cancel Subscription

1. Click **Cancel Subscription**
2. Select reason (dropdown: Cost, Not using, Missing features, Other)
3. Optional feedback (text area)
4. Click **Confirm Cancellation**
5. Receive cancellation email

**Expected result**:

* Access continues until end of billing period
* No further charges
* Data retained for 30 days after end date
* Can reactivate before data deletion

**Data retention after cancellation**:

* Days 1-30: Full access to export data (readonly)
* Day 31: Data deleted permanently (agents, interactions, analytics)
* Data sources: Not deleted (original sources untouched)

## Usage Monitoring

### Usage Dashboard

**Location**: Settings → Billing → Usage tab

**Metrics displayed** (current billing period):

* Queries used / limit (e.g., "8,245 / 10,000")
* Tokens used / limit (e.g., "750K / 1M")
* Data sources active / limit (e.g., "18 / 25")
* Users active / limit (e.g., "22 / 25")

**Bars color-coded**:

* Green: 0-79% used
* Yellow: 80-99% used
* Red: 100%+ used (overage)

**When over limit** (Pro plan):

* Overage charges apply
* Banner shows estimated overage cost
* Option to upgrade to higher tier

### Usage Alerts

**Configure**: Settings → Billing → Alerts

**Alert types**:

1. **Approaching limit**: 80% of quota
2. **Near limit**: 90% of quota
3. **Exceeded**: 100% of quota

**Actions**:

* Email to billing admin
* Optional webhook POST to your endpoint

**Alert payload**:

```json
{
  "alert_type": "approaching_limit",
  "metric": "queries",
  "current": 8000,
  "limit": 10,000,
  "percent": 80,
  "estimated_overage_cost": 0
}
```

### Usage Breakdown

**By agent** (Dashboard → Analytics → Usage):

* Agent name
* Query count
* Percentage of total
* Avg latency
* Cost

**By user** (Admin → Users → Usage tab):

* User email
* Query count (30 days)
* Last active timestamp
* Cost attribution

**By channel** (Analytics → Channels):

* API: Direct API calls
* Browser Extension: Chrome extension queries
* Widget: Embedded widget queries
* Slack: Slack app queries

## Payment Management

### Payment Methods

**Location**: Settings → Billing → Payment Method

**Supported**:

* Credit card: Visa, Mastercard, Amex, Discover
* ACH/wire transfer: Enterprise only, min $1000/month
* Purchase orders: Enterprise only, net-30 terms

**Add/update card**:

1. Click **Update Payment Method**
2. Enter card details (Stripe secure form)
3. Click **Save**
4. Verification charge: $1 (refunded immediately)

**Expected result**: New card becomes primary, old card remains as backup for 30 days

### Invoices

**Location**: Settings → Billing → Invoices tab

**Invoice list shows**:

* Invoice number (e.g., "INV-2024-001234")
* Date (e.g., "Jan 1, 2024")
* Amount (e.g., "$99.00")
* Status (Paid, Failed, Pending)
* PDF download icon

**Invoice contains**:

* Billing period (e.g., "Jan 1 - Jan 31, 2024")
* Line items:
  * Pro Plan: $99.00
  * Overage (250 queries × $0.01): $2.50
  * Add-on users (2 × $10): $20.00
* Subtotal: $121.50
* Tax (if applicable): $9.72
* Total: $131.22
* Payment method: Visa \*\*\*\*1234

**Download**: Click PDF icon → opens in browser or downloads

**Email**: Click envelope icon → send to email address (e.g., <accounts@company.com>)

### Credits & Refunds

**Service credits**:

* Issued for: Outages >1 hour, data loss incidents
* Amount: Pro-rated based on downtime
* Applied: Next invoice (automatic)
* Expiry: 12 months from issue date
* Balance visible: Settings → Billing → Credits

**Refunds** (cancellation):

* Pro plan: Pro-rated refund for unused days
* Annual prepay: Pro-rated refund minus 10% admin fee
* Processing time: 5-10 business days
* Method: Original payment method or check

**Example**: Cancel on Jan 15 with annual prepay ($990 paid)

* Days used: 15 days = $40.50
* Admin fee: $99.00
* Refund: $990 - $40.50 - $99.00 = $850.50

## Troubleshooting

### Payment Failed

**Symptom**: Email "Payment failed for invoice INV-XXXX"

**Diagnostic steps**:

1. Settings → Billing → Payment Method → check expiration date
2. Check card has sufficient funds
3. Verify billing address matches card
4. Check with bank for fraud hold

**Fix**: Update payment method immediately, click **Retry Payment** button in billing section

**Service impact**: Pro plan downgrades to Free after 7 days of failed payment

***

### Unexpected Charges

**Symptom**: Invoice higher than expected

**Diagnostic steps**:

1. Settings → Billing → Usage → check metrics for spike
2. Analytics → By Agent → identify high-usage agent
3. Analytics → By User → identify users with unusual activity
4. Check data source sync logs for re-processing

**Fix**: If spike legitimate, accept charge. If suspicious, contact <billing@twig.so> with invoice number and suspected issue.

***

### Upgrade Not Reflected

**Symptom**: Upgraded to Pro but still shows Free limits

**Diagnostic steps**:

1. Check email for upgrade confirmation
2. Settings → Billing → verify payment processed
3. Refresh page (Cmd+R / Ctrl+R)
4. Log out and log back in
5. Check after 10 minutes (cache propagation)

**Fix**: If not resolved after 10 minutes, contact <support@twig.so> with upgrade timestamp and invoice number

## When This Doesn't Apply

**Enterprise customers**: Billing managed via custom contracts, not self-service portal. Contact account manager for changes.

**Reseller customers**: Billing through reseller, not direct Twig. Contact reseller for subscription changes.

## Next Steps

[Cost Optimization](/product/monitoring/cost-optimization.md) - Reduce query costs

[User Management](/product/administration/user-management.md) - Add/remove users

[Analytics](https://github.com/thrivapp/twig-help-docs/blob/staging/monitoring/analytics.md) - Track usage patterns


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.twig.so/product/administration/billing-usage.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.