Invoices

{
  "id": "inv_xxxxxxxxxxxxxxxx",
  "object": "invoice",
  "organization_id": "org_xxxxxxxxxxxxxxxx",
  "invoice_number": "INV-2024-001",
  "order_number": "ORD-12345",
  "status": "draft",
  "contact_id": "con_xxxxxxxxxxxxxxxx",
  "contact_name": "Acme Corporation",
  "contact_email": "billing@acme.com",
  "contact_tax_number": "US123456789",
  "currency_id": "CUR_USD",
  "currency_rate": "1.0000",
  "issued_at": "2024-01-15",
  "due_at": "2024-02-14",
  "amount": "1250.00",
  "category_id": "cat_xxxxxxxxxxxxxxxx",
  "notes": "Payment due within 30 days",
  "footer": "Thank you for your business",
  "parent_id": null,
  "created_by": "usr_xxxxxxxxxxxxxxxx",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "metadata": {
    "payment_terms": "net_30",
    "po_number": "PO-12345"
  }
}

{
  "request_id": "req_xxxxxxxxxxxxxxxx",
  "success": true,
  "data": {
    "status": "queued",
    "estimated_completion": "2024-01-15T10:30:10Z",
    "invoice_preview": {
      "number": "INV-2024-001",
      "total_amount": "1500.00",
      "total_tax": "300.00",
      "grand_total": "1800.00"
    }
  },
  "error": null,
  "duration_ms": 0,
  "credit_cost": 5
}

{
  "object": "list",
  "data": [
    {
      "id": "inv_xxxxxxxxxxxxxxxx",
      "invoice_number": "INV-2024-001",
      "status": "paid",
      "contact_name": "Acme Corporation",
      "amount": "1250.00",
      "issued_at": "2024-01-15",
      "due_at": "2024-02-14",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "has_more": false,
  "total_count": 1
}

[
  {
    "status": "draft",
    "changed_at": "2024-01-15T10:30:00Z",
    "changed_by": "user_xxx"
  },
  {
    "status": "sent",
    "changed_at": "2024-01-15T14:20:00Z",
    "changed_by": "user_xxx"
  },
  {
    "status": "paid",
    "changed_at": "2024-01-20T09:15:00Z",
    "changed_by": "user_xxx"
  }
]

draft → sent → viewed → partial → paid
   ↓      ↓       ↓        ↓       ↓
cancelled  overdue

function calculateInvoiceTotal(items, taxRates) {
  let subtotal = 0;
  let totalTax = 0;

  items.forEach(item => {
    const lineTotal = item.quantity * item.price;
    subtotal += lineTotal;

    if (item.tax_id) {
      const taxRate = taxRates[item.tax_id];
      const taxAmount = lineTotal * (taxRate / 100);
      totalTax += taxAmount;
    }
  });

  const grandTotal = subtotal + totalTax;

  return {
    subtotal: subtotal.toFixed(2),
    tax: totalTax.toFixed(2),
    total: grandTotal.toFixed(2)
  };
}

// Example usage
const items = [
  { name: "Service A", quantity: 10, price: 50.00, tax_id: "vat_20" },
  { name: "Service B", quantity: 5, price: 100.00, tax_id: "vat_20" }
];

const taxRates = { "vat_20": 20.00 };

const totals = calculateInvoiceTotal(items, taxRates);
console.log(totals); // { subtotal: "1000.00", tax: "200.00", total: "1200.00" }

function calculateMultiTaxInvoice(items, taxDefinitions) {
  let subtotal = 0;
  const taxBreakdown = {};

  items.forEach(item => {
    const lineTotal = item.quantity * item.price;
    subtotal += lineTotal;

    // Apply multiple taxes per item
    item.taxes.forEach(taxRef => {
      const tax = taxDefinitions[taxRef.tax_id];
      let taxAmount = 0;

      switch (tax.type) {
        case 'normal':
          taxAmount = lineTotal * (tax.rate / 100);
          break;
        case 'compound':
          // Tax on (subtotal + previous taxes)
          const taxableAmount = lineTotal + (taxBreakdown[taxRef.tax_id] || 0);
          taxAmount = taxableAmount * (tax.rate / 100);
          break;
        case 'fixed':
          taxAmount = tax.rate;
          break;
      }

      taxBreakdown[taxRef.tax_id] = (taxBreakdown[taxRef.tax_id] || 0) + taxAmount;
    });
  });

  const totalTax = Object.values(taxBreakdown).reduce((sum, amount) => sum + amount, 0);
  const grandTotal = subtotal + totalTax;

  return {
    subtotal: subtotal.toFixed(2),
    taxBreakdown,
    totalTax: totalTax.toFixed(2),
    grandTotal: grandTotal.toFixed(2)
  };
}

{
  "template": "service_invoice",
  "defaults": {
    "category_id": "cat_services",
    "payment_terms": "net_30",
    "footer": "Thank you for your business. Payment terms: Net 30 days.",
    "item_defaults": {
      "tax_id": "tax_vat_20"
    }
  },
  "sections": [
    {
      "name": "services",
      "label": "Services Provided",
      "item_category": "service"
    },
    {
      "name": "expenses",
      "label": "Reimbursable Expenses",
      "item_category": "expense"
    }
  ]
}

{
  "template": "product_invoice",
  "defaults": {
    "category_id": "cat_sales",
    "payment_terms": "net_15",
    "footer": "Prices subject to change. Shipping costs not included.",
    "item_defaults": {
      "tax_id": "tax_sales_tax"
    }
  },
  "sections": [
    {
      "name": "products",
      "label": "Products Ordered",
      "show_quantity": true,
      "show_sku": true
    },
    {
      "name": "discounts",
      "label": "Discounts Applied",
      "negative_amounts": true
    }
  ]
}

# Create a monthly recurring invoice template
recurring_invoice = {
    "template_invoice": {
        "contact_id": "con_subscription_customer",
        "category_id": "cat_subscriptions",
        "items": [
            {
                "name": "Monthly Software License",
                "quantity": 1,
                "price": 99.00,
                "tax_id": "tax_vat_20"
            }
        ],
        "notes": "Monthly recurring charge"
    },
    "recurring_schedule": {
        "frequency": "monthly",
        "start_date": "2024-02-01",
        "end_date": "2024-12-31",
        "auto_send": True
    }
}

# This would be implemented in future API versions
# The recurring system would automatically generate invoices

// Pause recurring invoice
async function pauseRecurring(invoiceId) {
  // Future API endpoint
  const response = await fetch(`/organizations/${orgId}/invoices/${invoiceId}/recurring/pause`, {
    method: 'POST',
    headers: authHeaders
  });
  return response.json();
}

// Resume recurring invoice
async function resumeRecurring(invoiceId) {
  // Future API endpoint
  const response = await fetch(`/organizations/${orgId}/invoices/${invoiceId}/recurring/resume`, {
    method: 'POST',
    headers: authHeaders
  });
  return response.json();
}

// Update recurring amount
async function updateRecurringAmount(invoiceId, newAmount) {
  // Future API endpoint
  const response = await fetch(`/organizations/${orgId}/invoices/${invoiceId}/recurring`, {
    method: 'PATCH',
    headers: { ...authHeaders, 'Content-Type': 'application/json' },
    body: JSON.stringify({ amount: newAmount })
  });
  return response.json();
}