Quickstart for US SaaS

The Recurso dashboard after first sign-in

This is the US-first path through Recurso: everything in USD, payments routed to Stripe, and jurisdiction-level sales tax applied automatically. If you’re billing Indian customers, start with the main Quickstart and India GST setup instead.

New to Recurso? Get a local instance running first — clone the repo and run make demo, or see the Quickstart installation options. Then come back here. Prefer not to self-host? Recurso Cloud is in early access.

What you’ll build

A working US subscription: a USD Pro plan, a customer in California, a Stripe-paid subscription, and an invoice that carries the correct combined state + local sales tax. Set $API_KEY to your key (the demo key is sk_test_12345) and, for a self-hosted instance, $BASE to http://localhost:8080.

Step 1: Point the seller jurisdiction at the US

Sales tax only engages when the seller is US-based. Set this in your environment before billing US customers (full detail in the US sales tax tutorial):

.env

COMPANY_COUNTRY=US
COMPANY_STATE=CA
TAXJAR_API_KEY=your_taxjar_api_token   # omit to invoice at an honest 0% while testing

Step 2: Create a USD plan

curl -X POST $BASE/v1/plans \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro Plan",
    "code": "pro-monthly-usd",
    "interval_unit": "month",
    "interval_count": 1,
    "amount": 4900,
    "currency": "USD"
  }'

Amounts are in the smallest currency unit — 4900 is $49.00. Because the price is in USD, Recurso routes payment to Stripe automatically.

Step 3: Add a US customer with a billing address

The billing state and zip are what drive the sales-tax lookup — always populate them for US buyers.

curl -X POST $BASE/v1/customers \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "email": "billing@acme.com",
    "billing_address": {
      "line1": "500 Market St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94105",
      "country": "US"
    }
  }'

Step 4: Start a subscription

curl -X POST $BASE/v1/subscriptions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_abc",
    "plan_id": "plan_pro"
  }'

USD invoices route to your Stripe connection automatically, and your customer pays through the hosted checkout page. In development with no gateway keys, the mock gateway simulates the charge — see Testing & Sandbox.

Step 5: Read the taxed invoice

Invoices generate automatically at each period end. With TaxJar configured and nexus declared in the buyer’s state, the invoice carries the live combined rate:

{
  "invoice_number": "REC/2026/0007",
  "currency": "USD",
  "lines": [
    { "description": "Pro Plan Subscription", "amount": 4900 }
  ],
  "subtotal": 4900,
  "tax_amount": 429,
  "tax_type": "sales_tax",
  "tax_note": "US sales tax via taxjar (CA)",
  "total": 5329
}

The tax_type field tells you exactly how tax was computed on every invoice:

`tax_type`	Meaning
`sales_tax`	Live TaxJar rate applied
`no_nexus`	Buyer is in a state you haven’t declared nexus in — 0%, correctly not collected
`sales_tax_error`	TaxJar lookup failed; invoiced at 0% and flagged for review (billing is never blocked)
`sales_tax_stub`	No TaxJar key — 0% placeholder, fine for dev

Getting tax right needs one more step: declaring the US states where you have nexus. Do that next — an invoice at sales_tax_stub or no_nexus is 0%, which is not what you want in production.

Next steps

US Sales Tax Setup

Declare nexus, connect TaxJar, and monitor economic-nexus thresholds

Testing & Sandbox

Simulate payments, failures, and dunning before going live

Revenue Recognition

ASC 606 deferred → recognized schedules

Going to Production

Switch to live Stripe keys deliberately

Get Started

Migrate to Recurso

Core Concepts

Usage & Monetization

Money & Books

Tax & Compliance

Recover & Retain

Customer Portal

Platform & Integrations

Deploy & Operate

Reference

What you’ll build

Step 1: Point the seller jurisdiction at the US

Step 2: Create a USD plan

Step 3: Add a US customer with a billing address

Step 4: Start a subscription

Step 5: Read the taxed invoice

Next steps

US Sales Tax Setup

Testing & Sandbox

Revenue Recognition

Going to Production

​What you’ll build

​Step 1: Point the seller jurisdiction at the US

​Step 2: Create a USD plan

​Step 3: Add a US customer with a billing address

​Step 4: Start a subscription

​Step 5: Read the taxed invoice

​Next steps

US Sales Tax Setup

Testing & Sandbox

Revenue Recognition

Going to Production

What you’ll build

Step 1: Point the seller jurisdiction at the US

Step 2: Create a USD plan

Step 3: Add a US customer with a billing address

Step 4: Start a subscription

Step 5: Read the taxed invoice

Next steps