Skip to navigation
Get started

Quickstart

Send your first event and create an invoice in under 5 minutes
View as Markdown

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

Prerequisites

1. Create a customer

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": "[email protected]",
    "external_id": "cust_123"
  }'
Response
{
  "success": true,
  "customer": {
    "id": "cm5x9z8nv0000h85r7l9p2k1m",
    "name": "Acme Corp",
    "email": "[email protected]",
    "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

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
{
  "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

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
{
  "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.

curl -X POST https://api.trygrant.com/v1/invoices/cm5x9z8nv0001h85r7l9p2k2m/finalize \
  -H "Authorization: Bearer ak_live_YOUR_API_KEY"
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

Create, update, and manage customer records

Subscriptions API

Attach customers to plans with recurring billing

Invoices API

Build, finalize, and void invoices with line items

Events API

Ingest billable usage events at scale