Get started

# Quickstart

Four calls: prove the key works, resolve a customer, find something to sell, then write an order. Everything below runs against your live company, so start on an account you do not mind adding a draft order to.

1

## Create a key in the Factory app

Open Settings, then API keys, and create one. It is shown once. A key is scoped to the company that made it and carries that company's permissions, so treat it like a password: server side only, never in a browser or a mobile app.

> Store it as `FACTORY_API_KEY` in your environment. Every sample on this site reads it from there.

2

## Confirm the key and read your settings

A singleton read keyed by the token. It is the cheapest way to prove authentication works, and it tells you the currency, tax rate and measurement system every later response is expressed in.

```bash
curl https://api.factory.app/v1/company \
  -H "Authorization: Bearer $FACTORY_API_KEY"
```

```json
{
  "company": {
    "companyId": "company_01k2m4p6r8t0v2x4z6a8c0e2g4",
    "name": "Coastal Canopies",
    "currency": "AUD",
    "taxRate": "0.10",
    "measurementSystem": "MEASUREMENT_SYSTEM_METRIC"
  }
}
```

3

## Resolve a customer and a product

An order line references ids, not names. Resolve both before you write. Catalogue search takes one text query and returns ranked hits across products, kits and flashings. Search is in preview, so it is not yet covered by the compatibility guarantees.

```bash
curl "https://api.factory.app/v1/customers?companyName=Coastal%20Canopies" \
  -H "Authorization: Bearer $FACTORY_API_KEY"

curl "https://api.factory.app/v1/catalogue:search?query=colorbond%200.42" \
  -H "Authorization: Bearer $FACTORY_API_KEY"
```

4

## Write a draft order

Send the whole order in one call. Leave `isSubmitted` off while you are testing and it lands as a draft. Always send a `requestId` (a UUID you generate) — a repeat with the same key can never create a second order: it is rejected with a 409 that carries the original order’s id.

```bash
curl -X POST https://api.factory.app/v1/orders \
  -H "Authorization: Bearer $FACTORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "d5f7a8c2-3e1b-4d9f-a6c0-8b2e4f1d7a3c",
    "customerId": "cust_01k2m4p6r8t0v2x4z6a8c0e2g4",
    "reference": "PO-88431",
    "lines": [
      {
        "catalogue": {
          "productId": "prod_01k2m4p6r8t0v2x4z6a8c0e2g4",
          "rowPriceId": "rowprice_01k2m4p6r8t0v2x4z6a8c0e2g4",
          "pricing": { "quantity": "12" }
        }
      }
    ]
  }'
```

> **Next.** Read core concepts before you write anything real — money arrives as micros and every 64-bit number is a string. Then push an order in covers the full path including validation failures.

---

Source: https://developer.factory.app/quickstart · Factory Sales API v1