> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.tabs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.tabs.com/_mcp/server.

# Invoice a customer quickstart

Learn how to send an invoice to a customer using the Tabs API. In this guide you'll make a couple API calls and build a working example that you can adapt for your integration.

## Get your API key

You can create an API key from the [app](https://app.tabsplatform.com/merchant/developers). All requests require your key in the `Authorization` header.

## Step 1: Create the customer

A customer in Tabs represents the business you're billing. At minimum, provide a business name, but additional details are used in other workflows.

Create a customer using the `POST /v3/customers` endpoint, swapping in your API key:

```curl
curl -X POST https://integrators.prod.api.tabsplatform.com/v3/customers
  -H "Authorization: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
    "name": "Acme Corp",
    "primaryBillingContactEmail": "jordan.lee@acme.com",
    "billingAddress": {
      "line1": "123 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94105",
      "country": "US"
    }
  }'
```

Customer creation is processed asynchronously. Look up the customer with a filtered `GET /v3/customers` call to retrieve its `id`:

```curl
curl "https://integrators.prod.api.tabsplatform.com/v3/customers?filter=name:eq:Acme Corp&page=1&limit=50"
  -H "Authorization: YOUR_API_KEY"
```

```json
{
  "payload": {
    "data": [
      {
        "id": "cust_abc123",
        "name": "Acme Corp",
        "defaultCurrency": "USD",
        "primaryBillingContactEmail": "jordan.lee@acme.com",
        "billingAddress": {
          "line1": "123 Main Street",
          "city": "San Francisco",
          "state": "CA",
          "postalCode": "94105",
          "country": "US"
        },
        "lastUpdatedAt": "2025-01-15T12:00:00Z"
      }
    ],
    "limit": 50,
    "totalItems": 1,
    "currentPage": 1
  },
  "success": true,
  "message": "string",
  "error": null
}
```

Save the returned `id` — you'll use it in subsequent steps.

Tabs can automatically create customers by syncing with your CRM or ERP. If the customers exist already, try the GET /v3/customers endpoint to retrieve a customer id.

## Step 2: Create the contract

Every billing relationship in Tabs starts with a contract. A contract defines the billing arrangement with the customer. It also links the customer to a named agreement and serves as the container for any billing terms and schedules you attach later.

To create a contract (in Tabs) for a customer, call the POST /v3/contracts endpoint. Use your API key and the customer ID returned in Step 1.

```curl
curl -X POST https://integrators.prod.api.tabsplatform.com/v3/contracts
  -H "Authorization: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
    "name": "Acme Corp — Services Agreement 2025",
    "customerId": "cust_abc123"
  }'
```

Tabs returns a response like:

```json
{
  "id": "cont_xyz789",
  "name": "Acme Corp — Services Agreement 2025",
  "status": "ACTIVE",
  "customerId": "cust_abc123",
  "createdAt": "2025-01-15T12:05:00Z",
  "lastUpdatedAt": "2025-01-15T12:05:00Z"
}
```

Again, save the returned `id`, which represents the contract.  The contract starts in an unprocessed state—it won't generate invoices until you mark it as processed in Step 4.

## Step 3: Add a billing term

A billing term defines what you're charging, how much it costs, and how often. For a one-off invoice, create a billing term with isRecurring set to false. Tabs generates a single invoice for the full amount when you mark the contract as processed in Step 4.

Create the billing term on the contract by calling the POST /v3/contracts/\{contractId}/billing-terms endpoint:

```curl
curl -X POST https://integrators.prod.api.tabsplatform.com/v3/contracts/cont_xyz789/billing-terms
  -H "Authorization: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{
    "name": "Professional Services — February 2025",
    "description": "One-time engagement fee for February deliverables",
    "billingStartDate": "2025-02-01",
    "isRecurring": false,
    "interval": "NONE",
    "intervalFrequency": 1,
    "invoiceDateStrategy": "FIRST_OF_PERIOD",
    "netPaymentTerms": 30,
    "quantity": 1,
    "billingType": "FLAT",
    "pricingType": "SIMPLE",
    "pricing": [
      {
        "tier": 1,
        "amount": 5000.00,
        "amountType": "TOTAL_INVOICE",
        "tierMinimum": 0
      }
    ]
  }'
```

Tabs returns a response like:

```json
{
  "payload": {
    "id": "bt_def456",
    "contractId": "cont_xyz789",
    "billingTermGroupId": "btg_001",
    "name": "Professional Services — February 2025",
    "billingStartDate": "2025-02-01",
    "billingEndDate": "2025-02-01",
    "isRecurring": false,
    "billingType": "FLAT",
    "pricingType": "SIMPLE",
    "netPaymentTerms": 30,
    "createdAt": "2025-01-15T12:10:00Z"
  },
  "success": true,
  "message": "Billing term created successfully",
  "error": null
}
```

## Step 4: Mark the contract as processed

Creating a billing term defines what to bill, but Tabs doesn't generate the invoice until the contract is processed. Mark the contract as processed with the POST /v3/contracts/\{contractId}/actions endpoint:

```curl
curl -X POST https://integrators.prod.api.tabsplatform.com/v3/contracts/cont_xyz789/actions

  -H "Authorization: YOUR_API_KEY"

  -H "Content-Type: application/json"

  -d '{"action": "MARK_AS_PROCESSED"}'
```

Tabs sets the contract status to PROCESSED and generates a draft invoice for the billing term. The invoice has an issueDate of 2025-02-01 and a dueDate 30 days later (2025-03-03), based on the netPaymentTerms you specified.

You can change an invoice while it's in draft state.

## Step 5: Send the invoice

The final step is to send the invoice to the customer. First, fetch the invoice to review its details. Use the customer ID to scope the lookup with a filtered `GET /v3/invoices` call:

```curl
curl "https://integrators.prod.api.tabsplatform.com/v3/invoices?filter=customerId:eq:cust_abc123&page=1&limit=50"
  -H "Authorization: YOUR_API_KEY"
```

Tabs returns a response like:

```json
{
  "payload": {
    "data": [
      {
        "id": "inv_ghi012",
        "customerId": "cust_abc123",
        "status": "DRAFT",
        "issueDate": "2025-02-01",
        "dueDate": "2025-03-03",
        "total": 5000.00,
        "balanceRemaining": 5000.00,
        "lineItems": [
          {
            "id": "li_001",
            "name": "Professional Services — February 2025",
            "description": "One-time engagement fee for February deliverables",
            "quantity": 1,
            "unitPrice": 5000.00,
            "total": 5000.00
          }
        ]
      }
    ],
    "limit": 50,
    "totalItems": 1,
    "currentPage": 1
  },
  "success": true,
  "message": "string",
  "error": null
}
```

When you're ready to send the invoice, use the invoice actions endpoint to transition it from `DRAFT` to `SENT`. Sending is asynchronous, and at least one of `sendToErp` or `sendToCustomer` must be `true`:

```curl
curl -X POST "https://integrators.prod.api.tabsplatform.com/v3/customers/cust_abc123/invoices/inv_ghi012/actions"
  -H "Authorization: YOUR_API_KEY"
  -H "Content-Type: application/json"
  -d '{"action": "SEND", "sendToErp": true, "sendToCustomer": true}'
```

Tabs queues a background job and returns a job reference:

```json
{
  "message": "Invoice send job created, jobId: 9f8b7c6d-1234-4a56-b789-0a1b2c3d4e5f, please check the job status via /jobs/9f8b7c6d-1234-4a56-b789-0a1b2c3d4e5f"
}
```

Once the job completes, the invoice transitions from `DRAFT` to `SENT`. In a complete integration, you can set up payment options through Stripe and Plaid.

## Next steps

From here, you can:

* Review the [Tabs Data Model](/data-model)
* [Mark an Invoice as paid](/collect-payments/mark-invoices)