Developers

Search

Search guides and the API reference

Get started

Quickstart

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

For AI agents: this page is available as Markdown, and every guide plus the API reference is in llms-full.txt.

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.

  1. Get your API key

    If you don't have a key yet, an org admin can create one under Account → Developers (see Get an API key). Then export it in your terminal so the examples below can use it:

    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 in the business portal.

  3. Pick a category

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

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

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

    200OK
    {
  "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 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" }
      }
    ]
  }'

    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:

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

    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.

  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 https://api.onme.com/v1/orders/o-jfAQKlOHalPHMJkwMYZffJF_6j2OMWSu9svqSIvkLSw \
  -H "Authorization: Bearer $ONME_API_KEY"

    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 shows the whole journey.

Next steps