# Quickstart

> Send your first On Me gift through the API in about five minutes, open it as your recipient would, then look it up.


In this guide you send a $10 gift to yourself as a link, open it the way a recipient would, and then look it up through the API. You need a terminal, and optionally Node 18+ or Python 3 with `requests`. The Node samples use top-level `await`, so run them as ES modules, for example by saving them as `.mjs` files.

> **Warning: This sends a real gift** Following this guide with a live key spends $10 of your organization's real balance on a real gift. The gift is yours to keep: claim it and spend it. To rehearse it instead, use a sandbox key — see [Testing in the sandbox](https://business.onme.com/docs/sandbox).

1. **Get your API key**

If you don't have a key yet, an org admin can create one under [Account → Developers](https://business.onme.com/account/developers) (see [Get an API key](https://business.onme.com/docs/authentication#get-an-api-key)). Then export it in your terminal so the examples below can use it:

```bash
export ONME_API_KEY=omk-...
```

2. **Check your balance**: Your order is paid for from your organization's balance, so make sure it has at least $10. You can see it, and add funds, under [Billing](https://business.onme.com/billing) in the business portal.
3. **Pick a category**

A category decides where the gift can be spent. List them all:

**cURL**

```bash
curl https://api.onme.com/v1/categories \
  -H "Authorization: Bearer $ONME_API_KEY"
```
**Node**

```js
const response = await fetch('https://api.onme.com/v1/categories', {
  headers: { Authorization: `Bearer ${process.env.ONME_API_KEY}` },
})
const categories = await response.json()
console.log(categories.data.map((category) => `${category.id}: ${category.name}`))
```
**Python**

```python
import os
import requests

response = requests.get(
    "https://api.onme.com/v1/categories",
    headers={"Authorization": f"Bearer {os.environ['ONME_API_KEY']}"},
)
categories = response.json()
print([f"{category['id']}: {category['name']}" for category in categories["data"]])
```

You get back a list. We've trimmed each category to the fields you need here:

**200 OK**
```json
{
  "object": "list",
  "data": [
    { "id": "coffee", "name": "Coffee", "description": "For caffeine-addicts" },
    { "id": "choice", "name": "Choice", "description": "For those who want to choose" }
  ],
  "has_more": false
}
```

Copy the `id` of the one you like. The examples below use `coffee`.

4. **Send the gift**

Create an order with one $10 gift. `amount` is in cents, so $10 is `1000`, the smallest gift you can send. The `link` delivery method means we don't email or text anyone; we give you a link instead.

Every `POST /v1/orders` needs an `Idempotency-Key` header with a value that's unique to this order. If a request times out, retrying with the same key returns the original order instead of charging you twice.

**cURL**

```bash
curl https://api.onme.com/v1/orders \
  -H "Authorization: Bearer $ONME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "gifts": [
      {
        "amount": 1000,
        "category": "coffee",
        "delivery": { "method": "link" },
        "personalization": { "recipient_name": "You" }
      }
    ]
  }'
```
**Node**

```js
import { randomUUID } from 'node:crypto'

const response = await fetch('https://api.onme.com/v1/orders', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ONME_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': randomUUID(),
  },
  body: JSON.stringify({
    gifts: [
      {
        amount: 1000,
        category: 'coffee',
        delivery: { method: 'link' },
        personalization: { recipient_name: 'You' },
      },
    ],
  }),
})
const order = await response.json()
console.log(order.order_id, order.gifts[0].delivery.link)
```
**Python**

```python
import os
import uuid
import requests

response = requests.post(
    "https://api.onme.com/v1/orders",
    headers={
        "Authorization": f"Bearer {os.environ['ONME_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "gifts": [
            {
                "amount": 1000,
                "category": "coffee",
                "delivery": {"method": "link"},
                "personalization": {"recipient_name": "You"},
            }
        ]
    },
)
order = response.json()
print(order["order_id"], order["gifts"][0]["delivery"]["link"])
```

A `201` means the order exists and your balance has been debited. With `status: "processed"`, as here, the gift exists too. `sender_name` shows your organization's name because you didn't set one:

**201 Created**
```json
{
  "order_id": "o-jfAQKlOHalPHMJkwMYZffJF_6j2OMWSu9svqSIvkLSw",
  "status": "processed",
  "gifts": [
    {
      "gift_id": "g-gpsh60pP2JhgzroxWk4AyXfL237_DiKIJQK8ilq2u5g",
      "amount": 1000,
      "category": "coffee",
      "delivery": {
        "method": "link",
        "status": "sent",
        "link": "https://gift.onme.com/b6YSLdAA98fcSxpU"
      },
      "personalization": {
        "recipient_name": "You",
        "sender_name": "Acme"
      }
    }
  ]
}
```

In the rare case that `status` is `processing`, `gifts` can be empty; the gift is finished shortly after, and the lookup in the last step returns it. See [when the status is processing](https://business.onme.com/docs/creating-orders#when-the-status-is-processing).

Hang on to the `order_id`; you need it in the last step. If you got an error instead, its `code` says what to fix, and nothing was charged. Look it up in the [error reference](https://business.onme.com/docs/reference#errors).

5. **Open your gift**: Copy `gifts[0].delivery.link` from the response and open it in your browser. You land on the gift's claim page, the same one a recipient sees when you share a link with them. Claim it if you like: it's a real gift.
6. **Look it up**

Fetch the order by its ID, replacing the example ID with your own:

**cURL**

```bash
curl https://api.onme.com/v1/orders/o-jfAQKlOHalPHMJkwMYZffJF_6j2OMWSu9svqSIvkLSw \
  -H "Authorization: Bearer $ONME_API_KEY"
```
**Node**

```js
const orderID = 'o-jfAQKlOHalPHMJkwMYZffJF_6j2OMWSu9svqSIvkLSw'
const response = await fetch(`https://api.onme.com/v1/orders/${orderID}`, {
  headers: { Authorization: `Bearer ${process.env.ONME_API_KEY}` },
})
const order = await response.json()
console.log(order.gifts[0].delivery.status)
```
**Python**

```python
import os
import requests

order_id = "o-jfAQKlOHalPHMJkwMYZffJF_6j2OMWSu9svqSIvkLSw"
response = requests.get(
    f"https://api.onme.com/v1/orders/{order_id}",
    headers={"Authorization": f"Bearer {os.environ['ONME_API_KEY']}"},
)
order = response.json()
print(order["gifts"][0]["delivery"]["status"])
```

Because you opened the link, the gift's `delivery.status` has moved from `sent` to `opened`. If you claimed it, it reads `claimed`.


## What just happened

- **Your balance paid for the order.** `POST /v1/orders` debited $10 from your organization's balance and, almost always, created the gift in the same request. There was no checkout and no card to charge.
- **You delivered the gift yourself.** With the `link` method, we created the gift and handed you its claim link, and you chose where it went. The `email` and `phone` methods have us send it for you.
- **The gift moved through its lifecycle.** It started as `sent`, became `opened` when you visited the link, and becomes `claimed` once someone claims it and gets a card for its category. [How a gift moves](https://business.onme.com/docs/overview#how-a-gift-moves) shows the whole journey.

## Next steps

- [Creating orders](https://business.onme.com/docs/creating-orders): send several gifts at once, set the names recipients see, and handle every response.
- [Idempotency and retries](https://business.onme.com/docs/idempotency): build a retry loop that can never charge you twice.
- [Delivery methods](https://business.onme.com/docs/delivery-methods): send gifts by email or SMS, and fix a delivery that failed.