Guides

Tax Collection — Enabling Stripe Tax

Copy page

Zuplo supports automatic tax collection through Stripe Tax. When enabled, taxes (such as VAT, sales tax, or GST) are automatically calculated and added to your customers' invoices.

Prerequisites

• Monetization configured with Stripe connected (see Quickstart)
• A billing profile (created automatically during initial setup)
• Tax registrations added in Stripe for countries where you collect tax

Add tax registrations in Stripe

You must add tax registrations in Stripe for every country where you are required to collect tax. Without a registration, Stripe Tax cannot calculate taxes for customers in that country.

1. Go to your Stripe Tax registrations page.
2. Click + Add registration and add each country where you have a tax obligation.

Find your billing profile

Retrieve your billing profiles to get the billing profile ID:

Code
curl -X GET "https://dev.zuplo.com/v3/metering/${ZUPLO_BUCKET_ID}/billing/profiles" \
  -H "Authorization: Bearer ${ZUPLO_API_KEY}" \
  -H "Content-Type: application/json"

The response contains an items array. Save the id from your billing profile as BILLING_PROFILE_ID.

Enable tax collection

Use the PUT endpoint to update the billing profile. You need to change two things:

1. Set the correct supplier country in supplier.addresses[0].country. Tax calculation depends on your supplier country — it defines what taxes your company is required to collect. Use the ISO 3166-1 alpha-2 country code (e.g., US, GB, DE).

2. Enable tax collection by setting workflow.tax.enabled to true.

First, get the current billing profile to use as a base for the update:

Code
curl -X GET "https://dev.zuplo.com/v3/metering/${ZUPLO_BUCKET_ID}/billing/profiles/${BILLING_PROFILE_ID}" \
  -H "Authorization: Bearer ${ZUPLO_API_KEY}" \
  -H "Content-Type: application/json"

Then update the profile with tax enabled. The key fields to change in the response body are:

Code
{
  "supplier": {
    "addresses": [
      {
        "country": "GB"
      }
    ],
    "name": "Stripe Account"
  },
  "workflow": {
    "tax": {
      "enabled": true,
      "enforced": false
    }
  }
}

Send the full profile body back via PUT:

Code
curl -X PUT "https://dev.zuplo.com/v3/metering/${ZUPLO_BUCKET_ID}/billing/profiles/${BILLING_PROFILE_ID}" \
  -H "Authorization: Bearer ${ZUPLO_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{ ... full billing profile body with tax enabled ... }'

Tax enforcement modes

The workflow.tax object controls how tax collection behaves:

enabled	enforced	Behavior
false	false	No tax calculation. Stripe Tax is not used. Invoices are created without tax lines.
true	false	Best-effort tax calculation. Tax is calculated when possible. If it fails (e.g., no valid customer tax location or no tax registration for their country), the invoice is finalized without tax.
true	true	Strict tax enforcement. Tax calculation is required. If Stripe Tax returns an error, the invoice fails and the customer cannot complete the purchase.

Tax behavior configuration

You can configure whether tax is included in the price or added on top of it by adding a defaultTaxConfig to the invoicing section of your billing profile:

Code
{
  "invoicing": {
    "autoAdvance": true,
    "draftPeriod": "P0D",
    "dueAfter": "P0D",
    "progressiveBilling": true,
    "defaultTaxConfig": {
      "behavior": "exclusive",
      "stripe": {
        "code": "txcd_10000000"
      }
    }
  }
}

Setting	Description
behavior: "exclusive"	Tax is added on top of the listed price. A $9.99 plan with 20% VAT charges $11.99.
behavior: "inclusive"	Tax is included in the listed price. A $9.99 plan total stays $9.99, with tax extracted from that amount.
stripe.code	The Stripe Tax code for your product category. txcd_10000000 is the general "Software as a Service (SaaS)" category.

Troubleshooting

Customers blocked from subscribing

When enforced is true and a customer tries to subscribe from a country where you have not added a Stripe tax registration, they see an error and cannot create or upgrade subscriptions.

Fix: Add a tax registration for the missing country in Stripe, or set enforced to false to use best-effort mode.

Invoices missing tax lines

If tax collection is enabled but invoices don't show tax:

• Verify you have a tax registration for the customer's country.
• Check that the customer's address includes a valid country.
• Confirm workflow.tax.enabled is true on the billing profile.