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

# Quickstart

This guide walks you through the core Grant workflow: authenticating, creating a customer, sending a billable event, and generating an invoice.

## Prerequisites

* A Grant account with access to the [dashboard](https://www.trygrant.com/dashboard)
* An API key (see [Authentication](/api-reference/authentication))

## 1. Create a customer

```bash
curl -X POST https://api.trygrant.com/v1/customers \
  -H "Authorization: Bearer ak_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "email": "billing@acme.com",
    "external_id": "cust_123"
  }'
```

**`Response`**

```json title="Response"
{
  "success": true,
  "customer": {
    "id": "cm5x9z8nv0000h85r7l9p2k1m",
    "name": "Acme Corp",
    "email": "billing@acme.com",
    "external_id": "cust_123",
    ...
  },
  "request_id": "req_abc123"
}
```

Save the `customer.id` — you'll need it in the next steps.

## 2. Send a billable event

```bash
curl -X POST https://api.trygrant.com/v1/events/ingest \
  -H "Authorization: Bearer ak_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "event_name": "api.request",
        "idempotency_key": "evt_abc123xyz",
        "customer_id": "cm5x9z8nv0000h85r7l9p2k1m",
        "timestamp": "2024-01-15T10:30:00Z",
        "properties": {
          "tokens": 150,
          "model": "gpt-4"
        }
      }
    ]
  }'
```

**`Response`**

```json title="Response"
{
  "success": true,
  "accepted": 1,
  "request_id": "req_def456"
}
```

Events are queued for asynchronous processing. Use the `idempotency_key` to safely retry requests without creating duplicate events.

## 3. Create a draft invoice

```bash
curl -X POST https://api.trygrant.com/v1/invoices \
  -H "Authorization: Bearer ak_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cm5x9z8nv0000h85r7l9p2k1m",
    "collection_method": "send_invoice",
    "days_until_due": 30,
    "line_items": [
      {
        "description": "API calls — Jan 2024",
        "quantity": 1,
        "unit_amount_cents": 5000
      }
    ]
  }'
```

**`Response`**

```json title="Response"
{
  "success": true,
  "invoice": {
    "id": "cm5x9z8nv0001h85r7l9p2k2m",
    "status": "draft",
    "total_cents": 5000,
    "line_items": [...],
    ...
  },
  "request_id": "req_ghi789"
}
```

## 4. Finalize the invoice

Finalizing transitions the invoice from `draft` to `open`, assigns an invoice number, and generates a public payment URL.

```bash
curl -X POST https://api.trygrant.com/v1/invoices/cm5x9z8nv0001h85r7l9p2k2m/finalize \
  -H "Authorization: Bearer ak_live_YOUR_API_KEY"
```

**`Response`**

```json title="Response"
{
  "success": true,
  "invoice": {
    "id": "cm5x9z8nv0001h85r7l9p2k2m",
    "status": "open",
    "invoice_number": "INV-0001",
    "public_invoice_url": "https://www.trygrant.com/invoices/abc123",
    ...
  },
  "request_id": "req_jkl012"
}
```

## Next steps

#### [Customers API](/api-reference/customers)

Create, update, and manage customer records

#### [Subscriptions API](/api-reference/subscriptions)

Attach customers to plans with recurring billing

#### [Invoices API](/api-reference/invoices)

Build, finalize, and void invoices with line items

#### [Events API](/api-reference/events)

Ingest billable usage events at scale

> API documentation for Grant — billing infrastructure for usage-based pricing