Tax Configuration

Proper tax configuration is essential for accurate invoicing, compliance, and financial reporting. OptiFlow supports multiple tax types, rates, and complex tax scenarios.

Overview

Tax features in OptiFlow:

Multiple tax types (VAT, sales tax, withholding, etc.)
Multiple tax rates per transaction
Exclusive and inclusive tax calculations
Default taxes for products
Tax reporting and compliance
Multi-tax line items

Tax Types

OptiFlow supports different tax classifications:

Type	Description	Calculation	Use Case
ITBIS	Value Added Tax	Exclusive	Dominican Republic VAT (18%)
ISC	Selective Consumption Tax	Exclusive	Luxury goods, alcohol, tobacco
Withholding	Income Tax Withholding	Exclusive	Professional services withholding
Sales Tax	General Sales Tax	Exclusive/Inclusive	State/local sales taxes

Reference: TaxType enum in app/Enums/TaxType.php

Exclusive vs. Inclusive Taxes

Exclusive Taxes (most common):

Tax is added to the subtotal
Calculation: Subtotal + (Subtotal × Tax Rate) = Total
Example: $100 + ($ 100 × 18%) = $118

Inclusive Taxes:

Tax is already included in the price
Calculation: Total ÷ (1 + Tax Rate) = Subtotal
Example: $118 ÷ 1.18 =$ 100 subtotal, $18 tax

// From TaxType enum
public function isExclusive(): bool
{
    return match($this) {
        self::ITBIS, self::ISC, self::WITHHOLDING => true,
        self::INCLUSIVE_VAT => false,
    };
}

Creating Tax Rates

Navigate to Tax Configuration

Go to Settings → Taxes → Create TaxReference: TaxController::create() in app/Http/Controllers/TaxController.php:66

Enter Tax Details

Required Fields:Name: Descriptive name for the tax

Examples: “ITBIS 18%”, “ISC Alcoholes 10%”, “Retención 10%”
Should clearly indicate the purpose and rate

Type: Select tax classification

ITBIS (VAT)
ISC (Selective Consumption)
Withholding
Sales Tax
Other

Rate: Tax percentage

Enter as a number (e.g., 18 for 18%)
Supports up to 2 decimal places (e.g., 7.5 for 7.5%)
Can be 0 for exempt/zero-rated items

Default: Mark as default (checkbox)

Default taxes are pre-selected when creating invoices
Useful for commonly applied taxes like standard VAT

// Tax model fillable fields
protected $fillable = [
    'name',
    'type',
    'rate',
    'is_default',
];

Save Tax

Click Create TaxThe tax is now available for:

Invoice line items
Quotation line items
Product default tax configuration
Tax reports

Reference: CreateTaxAction::handle() in app/Actions/CreateTaxAction.php

Tax Configuration Examples

Dominican Republic Standard Setup

Create ITBIS 18%

Name: “ITBIS 18%”
Type: ITBIS
Rate: 18
Default: ✓ Yes

Create ITBIS Reduced Rate

Name: “ITBIS 16% (Reducido)”
Type: ITBIS
Rate: 16
Default: ✗ No

Create ISC for Alcohol

Name: “ISC Alcoholes 10%”
Type: ISC
Rate: 10
Default: ✗ No

Create Withholding

Name: “Retención 10%”
Type: Withholding
Rate: 10
Default: ✗ No

Create Exempt

Name: “Exento”
Type: ITBIS
Rate: 0
Default: ✗ No

Setting Default Product Taxes

Assign default taxes to products for faster invoice creation:

Edit Product

Navigate to Products → Select product → Edit

Select Default Tax

Choose the tax that typically applies to this product:

Standard products: ITBIS 18%
Alcohol/tobacco: ISC + ITBIS
Exempt items: Exento (0%)
Services: Withholding tax

Save Product

When this product is added to an invoice, the default tax is automatically selected

Default taxes are suggestions only. Users can still modify or add taxes when creating invoices.

Applying Taxes to Invoices

Single Tax per Line Item

Most common scenario:

Create invoice
Add product line item
Tax auto-populates from product default
Or manually select tax from dropdown
Tax amount calculated: Quantity × Unit Price × Tax Rate

Multiple Taxes per Line Item

For complex scenarios (e.g., ISC + ITBIS on alcohol):

Add Product to Invoice

Add the product line item

Select Multiple Taxes

In the tax field:

Click to open multi-select
Select first tax (e.g., “ISC Alcoholes 10%”)
Select second tax (e.g., “ITBIS 18%”)
Both taxes apply

Tax Calculation

Taxes are calculated based on type:Exclusive taxes (most common):

Both calculated on subtotal
Example: $100 product
- ISC 10%: $10
- ITBIS 18%: $18
- Total: $100 +$ 10 + $18 =$ 128

Cascading taxes (if configured):

Second tax on subtotal + first tax
Example: $100 product
- ISC 10%: $10 (on$ 100)
- ITBIS 18%: $19.80 (on$ 110)
- Total: $100 +$ 10 + $19.80 =$ 129.80

Reference: Tax grouping in InvoiceController::create()

// Taxes grouped by type for UI organization
$taxesGroupedByType = Tax::query()
    ->orderBy('is_default', 'desc')
    ->orderBy('name')
    ->get()
    ->groupBy('type')
    ->mapWithKeys(fn ($taxes, $type) => [
        $type => [
            'label' => TaxType::tryFrom($type)?->label() ?? $type,
            'isExclusive' => TaxType::tryFrom($type)?->isExclusive() ?? false,
            'taxes' => $taxes->toArray(),
        ],
    ]);

Tax Calculation Details

Line Item Tax Calculation

// Simplified calculation logic
$lineSubtotal = $quantity * $unitPrice;
$lineDiscount = /* discount calculation */;
$taxableAmount = $lineSubtotal - $lineDiscount;

foreach ($selectedTaxes as $tax) {
    $taxAmount = $taxableAmount * ($tax->rate / 100);
    $totalTaxAmount += $taxAmount;
}

$lineTotal = $taxableAmount + $totalTaxAmount;

Invoice Total Calculation

// Invoice totals (from CreateInvoiceAction)
'total_amount' => $data['total'],
'subtotal_amount' => $data['subtotal'],      // Sum of line subtotals
'discount_amount' => $data['discount_total'], // Sum of discounts
'tax_amount' => $data['tax_amount'],          // Sum of all tax amounts

Calculation order:

Calculate line subtotal (quantity × price)
Apply line discount
Calculate taxes on (subtotal - discount)
Sum all lines for invoice totals

Viewing Tax Usage

Navigate to Tax Detail

Go to Settings → Taxes → Select a taxReference: TaxController::show() in app/Http/Controllers/TaxController.php:88

View Usage Statistics

Tax detail page shows:

Number of products using this as default tax
Number of invoice line items with this tax
Number of quotation line items with this tax
Total tax amount collected (if available)

// From Tax model
public function isInUse(): bool
{
    return $this->invoiceItems()->exists()
        || $this->quotationItems()->exists()
        || $this->products()->exists();
}

View Related Records

Links to:

Products using this tax
Recent invoices with this tax
Quotations with this tax

Editing Tax Rates

Navigate to Tax

Go to Settings → Taxes → Select tax → EditReference: TaxController::edit() in app/Http/Controllers/TaxController.php:101

Check If In Use

System displays warning if tax is currently in use:

Changing tax rates affects future invoices but NOT past invoices. Past invoices retain the tax rate that was applied when they were created.

If tax is in use:

Safe to change: Name, default status
Use caution: Rate (creates inconsistency in reporting)
Not recommended: Type (may cause calculation issues)

Make Changes

Update fields as needed:

Name: Safe to update
Rate: Update if tax rate changed by government
Default: Safe to toggle
Type: Avoid changing if in use

Save Changes

Click Update TaxImpact:

New invoices use new rate
Existing invoices unchanged (tax rate saved per line item)
Product defaults updated

Reference: UpdateTaxAction::handle()

Best Practice: Rate Changes

When tax rates change (e.g., government changes VAT from 18% to 20%):

Create New Tax

Name: “ITBIS 20% (from [date])”
Type: ITBIS
Rate: 20
Default: ✓ Yes

Update Old Tax

Name: “ITBIS 18% (until [date])”
Default: ✗ No

Update Products

Update product default taxes to use new rate

This approach maintains clear audit trail and reporting.

Deleting Taxes

Navigate to Tax

Go to Settings → Taxes → Select tax → DeleteReference: TaxController::destroy() in app/Http/Controllers/TaxController.php:125

Validation Check

System checks if tax can be deleted:Cannot delete if:

Tax is used on any invoice line items
Tax is used on any quotation line items
Tax is set as default on any products

// From DeleteTaxAction
if ($tax->isInUse()) {
    throw new InvalidArgumentException(
        'No se puede eliminar el impuesto porque está siendo utilizado.'
    );
}

Solution:

Remove tax from all products first
Tax remains on historical invoices (preserved for records)
Mark as inactive instead of deleting

Confirm Deletion

If tax is not in use, confirm deletion.Tax is permanently removed from the system.

Tax Reporting

Available Tax Reports

Tax Collection Report
- Navigate to Reports → Tax Reports → Tax Collection
- View tax collected by:
  - Tax type
  - Date range
  - Customer
  - Product category
Tax Liability Report
- Taxes owed to tax authorities
- Breakdown by tax type
- Filing period summary
Withholding Tax Report
- Withholding taxes collected
- By vendor/customer
- Compliance reporting format
Exempt Sales Report
- Zero-rated and exempt sales
- Justification tracking

Exporting Tax Data

Navigate to Tax Report

Go to desired tax report

Select Date Range

Choose reporting period (monthly, quarterly, annual)

Apply Filters

Filter by:

Tax type
Workspace
Customer type

Export

Click Export → Select format:

Excel (.xlsx)
CSV
PDF

Common Tax Scenarios

Scenario 1: Standard Product Sale (Dominican Republic)

Product: Electronics Tax: ITBIS 18% Calculation:

Subtotal: $1,000
ITBIS 18%: $180
Total: $1,180

Scenario 2: Alcohol Sale (Multiple Taxes)

Product: Wine Taxes: ISC 10% + ITBIS 18% Calculation:

Subtotal: $100
ISC 10%: $10
ITBIS 18%: $18
Total: $128

Scenario 3: Professional Services (Withholding)

Service: Consulting Taxes: Service Fee + Withholding 10% Calculation:

Service Fee: $1,000
Withholding 10%: $100 (retained by payer)
Payment to Provider: $900
Amount Due to Tax Authority: $100

Scenario 4: Exempt Sale

Product: Basic food items (exempt) Tax: Exento (0%) Calculation:

Subtotal: $50
Tax: $0
Total: $50

Compliance and Best Practices

Regular Updates: Keep tax rates current with government regulations. Subscribe to tax authority updates.

Clear Naming: Use descriptive tax names including rate and effective date for clarity.

Document Changes: When tax rates change, document the change in system notes and notify users.

Audit Trail: OptiFlow preserves tax rates on historical invoices. Never manually edit old tax amounts.

Monthly Reconciliation: Reconcile tax collected in OptiFlow with tax reports submitted to authorities monthly.

Backup Before Changes: Before changing tax configuration, export current tax reports for records.

Troubleshooting

Wrong Tax Amount on Invoice

Problem: Tax calculation appears incorrect Investigation:

Check if discount was applied (tax is on discounted amount)
Verify correct tax rate was selected
Check if multiple taxes are applied
Review if tax is inclusive vs. exclusive

Cannot Delete Tax

Problem: “No se puede eliminar el impuesto porque está siendo utilizado” Solution:

Check products using this tax → update their default tax
Tax remains on historical invoices (this is correct behavior)
Consider making inactive instead of deleting

Problem: Created tax doesn’t show when creating invoice Cause: May be filtered by type or marked inactive Solution:

Verify tax is active
Check if tax type is appropriate for the document
Refresh the page

Incorrect Tax Report Totals

Problem: Tax report totals don’t match expectations Investigation:

Verify date range is correct
Check workspace filter (multi-workspace environments)
Ensure invoice statuses are included (paid vs. pending)
Review if cancelled invoices are excluded

Advanced Configuration

Tax Exemptions

For customers exempt from certain taxes:

Create “Exempt” tax rate (0%)
When creating invoice for exempt customer, select “Exempt” tax
Document exemption reason in invoice notes
Maintain exemption certificates on file

Reverse Charge

For B2B transactions where buyer collects tax:

Create “Reverse Charge” tax type (0%)
Apply to invoice
Note in invoice: “Reverse charge applies”
Buyer remits tax to authority

Get Started

Core Features

Guides

Workflows & Automation

Tax Configuration

Overview

Tax Types

Exclusive vs. Inclusive Taxes

Creating Tax Rates

Tax Configuration Examples

Dominican Republic Standard Setup

Setting Default Product Taxes

Applying Taxes to Invoices

Single Tax per Line Item

Multiple Taxes per Line Item

Tax Calculation Details

Line Item Tax Calculation

Invoice Total Calculation

Viewing Tax Usage

Editing Tax Rates

Best Practice: Rate Changes

Deleting Taxes

Tax Reporting

Available Tax Reports

Exporting Tax Data

Common Tax Scenarios

Scenario 1: Standard Product Sale (Dominican Republic)

Scenario 2: Alcohol Sale (Multiple Taxes)

Scenario 3: Professional Services (Withholding)

Scenario 4: Exempt Sale

Compliance and Best Practices

Troubleshooting

Wrong Tax Amount on Invoice

Cannot Delete Tax

Incorrect Tax Report Totals

Advanced Configuration

Tax Exemptions

Reverse Charge

Build docs developers (and LLMs) love

Get Started

Core Features

Guides

Workflows & Automation

​Overview

​Tax Types

​Exclusive vs. Inclusive Taxes

​Creating Tax Rates

​Tax Configuration Examples

​Dominican Republic Standard Setup

​Setting Default Product Taxes

​Applying Taxes to Invoices

​Single Tax per Line Item

​Multiple Taxes per Line Item

​Tax Calculation Details

​Line Item Tax Calculation

​Invoice Total Calculation

​Viewing Tax Usage

​Editing Tax Rates

​Best Practice: Rate Changes

​Deleting Taxes

​Tax Reporting

​Available Tax Reports

​Exporting Tax Data

​Common Tax Scenarios

​Scenario 1: Standard Product Sale (Dominican Republic)

​Scenario 2: Alcohol Sale (Multiple Taxes)

​Scenario 3: Professional Services (Withholding)

​Scenario 4: Exempt Sale

​Compliance and Best Practices

​Troubleshooting

​Wrong Tax Amount on Invoice

​Cannot Delete Tax

​Tax Not Appearing in Dropdown

​Incorrect Tax Report Totals

​Advanced Configuration

​Tax Exemptions

​Reverse Charge

​Related Features

Build docs developers (and LLMs) love

Overview

Tax Types

Exclusive vs. Inclusive Taxes

Creating Tax Rates

Tax Configuration Examples

Dominican Republic Standard Setup

Setting Default Product Taxes

Applying Taxes to Invoices

Single Tax per Line Item

Multiple Taxes per Line Item

Tax Calculation Details

Line Item Tax Calculation

Invoice Total Calculation

Viewing Tax Usage

Editing Tax Rates

Best Practice: Rate Changes

Deleting Taxes

Tax Reporting

Available Tax Reports

Exporting Tax Data

Common Tax Scenarios

Scenario 1: Standard Product Sale (Dominican Republic)

Scenario 2: Alcohol Sale (Multiple Taxes)

Scenario 3: Professional Services (Withholding)

Scenario 4: Exempt Sale

Compliance and Best Practices

Troubleshooting

Wrong Tax Amount on Invoice

Cannot Delete Tax

Tax Not Appearing in Dropdown

Incorrect Tax Report Totals

Advanced Configuration

Tax Exemptions

Reverse Charge

Related Features