Get started

Quickstart

Create a workspace, get a test key and send your first invoice in about ten minutes.

You need a Forma account and Node 20 or later for the CLI. The API itself works from any language; the examples show curl, Node and Python.

Install the CLI

The CLI signs you in, creates workspaces and keys, and forwards webhook events to your machine while you build.

npm install -g @forma/cli

Send your first invoice

1. Sign in

   Run forma login. A browser window opens; approve the request and return to the terminal. The token is stored in your system keychain.

   bash

   forma login

2. Create a workspace

   A workspace holds your customers, invoices and team. Most companies need one. The currency is the default for new invoices; you can bill in others.

   bash

   forma workspace create "Forma Studio" --currency EUR

3. Create a test key

   Keys belong to a workspace, not a person. A test key starts with fk_test_ and only sees test data.

   bash

   forma keys create --name "Local development" --mode test

4. Create a customer

   Every invoice belongs to a customer. The customer's payment terms set the due date.

   bash

   forma customers create \  --name "Palisade Hotels Group" \  --email accounts@palisade.example \  --terms net30

Create the invoice

With a customer and a key you can call the API. Replace cus_8Kq2mZ with the id the previous step printed.

curl https://api.forma.example/v2/invoices \  -H "Authorization: Bearer $FORMA_KEY" \  -H "Idempotency-Key: first-invoice-001" \  -d customer=cus_8Kq2mZ \  -d "lines[0][description]=Brand identity workshop" \  -d "lines[0][unit_amount]=480000" \  -d send=true

Listen for events

When the customer pays, Forma sends an invoice.paid event. During development the CLI forwards events from Forma to a port on your machine.

forma listen --forward-to localhost:4242/forma/hooks

Trigger a test payment from the dashboard or with forma trigger invoice.paid and watch the event arrive. Webhooks explains the payload and how to verify that an event really came from Forma.

Go live

1. Create a live key with forma keys create --mode live and store it in your secrets manager, not in your repository.
2. Add a live webhook endpoint with its own signing secret.
3. Check Errors and rate limits so your code retries the right failures.
4. Switch your client from the test key to the live key. Nothing else changes.