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

# Invoicing proration

# Invoicing, Taxation & Proration

Fype features an automated invoicing engine that calculates compliance taxation and handles complex mid-cycle subscription changes (upgrades and downgrades) with proration credits.

***

## GST Compliance & Tax Splitting

Fype calculates and applies Indian Goods and Services Tax (GST) automatically.

* **Standard Tax Rate**: **18%** is applied to taxable products (`SAC Code: 997331`).
* **Precision Calculation**: Calculations are completed in **Paise** (subunits) to avoid floating-point rounding errors:
  $\text{Taxable Value} = \lfloor \frac{\text{Base Amount}}{1.18} \rfloor$
  $\text{Total Tax Amount} = \text{Base Amount} - \text{Taxable Value}$

### State-Boundary Tax Routing

Fype determines how to split GST based on the merchant's corporate location versus the customer's state boundary:

* **Intra-state (Merchant State == Customer State)**: Splits the total tax equally between **CGST** (Central GST - 9%) and **SGST** (State GST - 9%).
* **Inter-state (Merchant State != Customer State)**: Allocates the entire 18% tax amount to **IGST** (Integrated GST).

All generated invoices automatically populate these splits in their `tax_details` metadata payload.

***

## Mid-Cycle Plan Changes (Proration)

When a customer upgrades or downgrades their subscription mid-cycle, Fype calculates the unused credit on the existing plan, calculates the cost of the new plan for the remaining time in the billing period, and generates a net balance adjustment.

```mermaid theme={null}
gantt
    title Mid-Cycle Plan Upgrade Timeline
    dateFormat  D
    axisFormat %d
    
    section Old Plan (₹1,000)
    Unused Time (15 days credit = ₹500) :active, day1, 15d
    section New Plan (₹2,000)
    Prorated Cost (15 days cost = ₹1,000) :done, day15, 30d
    
    section Invoicing
    Adjustment Invoice Issued (Charge: ₹500) :crit, day15, 1d
```

### Proration Mathematics

1. **Unused Credit (Old Plan)**:
   $\text{Credit} = \text{Old Plan Price} \times \frac{\text{Remaining Time in Current Billing Period}}{\text{Total Time in Current Billing Period}}$
2. **Prorated Cost (New Plan)**:
   $\text{Cost} = \text{New Plan Price} \times \frac{\text{Remaining Time in Current Billing Period}}{\text{Total Time in Current Billing Period}}$
3. **Net Adjustment**:
   $\text{Adjustment} = \text{New Plan Cost} - \text{Old Plan Credit}$

* **Upgrade (Net positive adjustment)**: Fype creates an invoice representing the difference. If a card or mandate is linked, Fype attempts to collect the balance immediately.
* **Downgrade (Net negative adjustment)**: Fype creates a negative invoice (Credit Note) and applies the surplus balance to the customer's credit balance (which is automatically deducted from future invoice cycles).

Fype also synchronizes the updated plan with the underlying gateway (e.g. Razorpay subscription modification APIs) to ensure future automated billing periods charge the correct rate.

***

## API Examples

### Change a Subscription's Plan

Upgrade or downgrade a customer's subscription. Fype will calculate proration and return the updated subscription and the generated adjustment invoice.

```bash theme={null}
curl -X POST https://api.fype.dev/v1/subscriptions/{subscription_uuid}/change-plan \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "new_plan_uuid",
    "price_id": "new_price_uuid"
  }'
```

### Response Payload Snippet

```json theme={null}
{
  "subscription": {
    "id": "sub_uuid",
    "status": "active",
    "plan_id": "new_plan_uuid",
    "price_id": "new_price_uuid"
  },
  "proration_invoice": {
    "id": "inv_uuid",
    "invoice_number": "INV-2026-0083",
    "subtotal": 42372,
    "tax_amount": 7628,
    "total": 50000,
    "amount_due": 50000,
    "tax_details": {
      "tax_rate": 18.0,
      "cgst": 3814,
      "sgst": 3814,
      "igst": 0
    }
  }
}
```