Tax

Tax is computed at invoice finalisation by an external tax engine — Paylera integrates with Stripe Tax, Avalara, and TaxJar. You configure which engine to use; Paylera handles the API calls, attaches the result to the invoice, and reissues if anything later requires recomputation.

What the tax engine receives

When an invoice is finalised, Paylera calls the engine with:

• Origin address — your tenant’s nexus address(es).
• Destination address — the customer’s billing address (or the shipping address, if set, for physical goods).
• Customer tax ID — VAT number, GST number, ABN, etc., when present.
• Line items — for each line, the amount, the product tax code, and quantity.
• Currency — taxes are computed in the invoice currency.
• Date of supply — the invoice’s issued_at timestamp.

The engine returns a per-line tax amount and a per-line jurisdiction breakdown. Paylera attaches this to the invoice as tax_breakdown.

Configuring tax

POST /v1/admin/tax/config
{
  "provider": "stripe_tax",
  "credentials": { "secret_key": "sk_live_…" },
  "default_origin": {
    "country": "US",
    "state": "CA",
    "postal_code": "94105"
  },
  "additional_nexuses": [
    { "country": "GB" },
    { "country": "DE" }
  ]
}

You can change the provider, but doing so does not retroactively recompute tax on existing invoices. Issued invoices keep the tax that was in effect at finalisation.

Product tax codes

Each product can declare a tax code (e.g., Stripe’s txcd_10000000 for SaaS, Avalara’s D9999999 for digital services). If absent, the default tax code on the tenant configuration applies.

PATCH /v1/products/{id}
{ "tax_code": "txcd_10000000" }

For mixed-tax-code plans, set the tax code per component:

{ "components": [
    { "code": "saas",   "tax_code": "txcd_10000000", "pricing": { … } },
    { "code": "advice", "tax_code": "txcd_20030000", "pricing": { … } }
] }

Customer tax ID

Capture the customer’s tax ID and Paylera passes it to the engine. The engine validates it (VIES for EU VAT, etc.) and may apply reverse-charge or zero-rating where appropriate.

POST /v1/customers/{id}/tax-ids
{ "type": "eu_vat", "value": "DE123456789" }

Type	Region
eu_vat	EU member states (validated via VIES)
gb_vat	United Kingdom
us_ein	United States
au_abn	Australia
ca_bn, ca_gst_hst, ca_pst_*	Canada
(extensible — see provider docs)	…

Reverse charge

For B2B EU sales with a valid tax ID in a different member state from your origin, the tax engine returns 0.00 and Paylera adds a tax_exempt: reverse_charge flag to the invoice. Your invoice PDF includes the legally-required wording.

Tax-inclusive vs tax-exclusive

By default, prices in Paylera are tax-exclusive — tax is added on top of the displayed price. To declare tax-inclusive pricing on a plan (common in jurisdictions with VAT), set:

{ "tax_behavior": "inclusive" }

For inclusive pricing, the engine derives the tax from the line amount; the line amount becomes subtotal_excluding_tax + tax.

Tax exemptions

Mark a customer as exempt:

PATCH /v1/customers/{id}
{ "tax_exempt": "exempt" }

Values: none (default), exempt, reverse_charge_eligible. The engine uses these as inputs; the actual tax computation is still the engine’s call.

Exemption certificates (US sales tax) can be uploaded via:

POST /v1/customers/{id}/tax-exemption-certificates

Recomputation

Tax can be recomputed before finalisation:

POST /v1/invoices/{id}/recompute-tax

After finalisation, tax is locked. To correct a finalised invoice’s tax, issue a credit note and a new invoice.

What you’re responsible for

• Filing returns. Paylera computes; you (or your tax engine) file.
• Choosing the right tax code per product.
• Keeping your origin / nexus list current as you cross thresholds.
• Capturing customer tax IDs for B2B sales.

What Paylera handles: calling the engine, persisting the breakdown, keeping the invoice immutable once issued, and flagging a recomputation when you change a plan’s tax code.