API reference

Every endpoint, request and response schema, and error code in the On Me API, with code samples for each request.

Base URL: https://api.onme.com

OpenAPI 3.1 spec: openapi.json

Introduction

Buy and send On Me gifts programmatically. New here? Start with the quickstart.

Authenticate with a secret key as a bearer token: Authorization: Bearer omk-.... See Authentication.

There is one base URL for both environments, and your key decides which one answers: omk- reaches live, omk-sandbox- reaches the sandbox. Everything below works the same in each, so moving an integration to production is a key swap and nothing else.

The sandbox additionally answers the Sandbox endpoints below, and lets you choose what becomes of a gift by the recipient address you send to — delivered, bounced, opened, claimed, spent, or a failed order. Operations badged Mockable are the ones that address steers. See Testing in the sandbox.

Successful responses return the resource itself, or { "object": "list", "data": [...], "has_more": false } for lists. Errors return a single error object; see Errors.

POST /v1/orders requires an Idempotency-Key header. Retry a timed-out request with the same key and you get the original order, never a second charge. See Idempotency and retries.

Errors

Handling errors

Every error response has the same shape:

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "Invalid email address",
    "param": "gifts[0].delivery.email",
    "doc_url": "https://business.onme.com/docs/reference#errors/parameter_invalid",
    "request_id": "req-3kTq9x..."
  }
}

• Branch on type and code. Never parse message; it is for humans and may change.
• param names the offending field when there is one, as a path such as gifts[0].amount.
• Log request_id (also sent as the Request-Id header on every response) and quote it when contacting support.

An error in this shape means nothing happened: no order, no charge, no gifts. A timeout, a dropped connection or a gateway error without an error object means the outcome is unknown: retry with the same Idempotency-Key.

Retrying

Every code below says whether to retry it:

Back off exponentially with jitter (for example 0.5s, 1s, 2s, capped at 10s) and honour Retry-After when present.

Error codes

api_key_missing

401 · authentication_error · Retry: after fix

No API key was provided. Send it as a bearer token in the Authorization header.

Send Authorization: Bearer omk-... on every request.

api_key_invalid

401 · authentication_error · Retry: after fix

The API key is not recognised.

Check for a truncated or mistyped key. An org admin can create a new one under Account → Developers in the business portal.

api_key_revoked

401 · authentication_error · Retry: after fix

The API key was valid but has since been revoked.

Switch to a current key. An org admin can create one under Account → Developers in the business portal.

api_key_environment_mismatch

401 · authentication_error · Retry: after fix

The request reached the wrong environment for its key. You should not see this: there is one base URL, and your key decides which deployment serves the request. It means the request bypassed that routing, or reached a deployment host directly.

Call the documented base URL rather than a deployment host directly. If you already are, this is a fault on our side — quote the request_id.

organization_suspended

403 · authentication_error · Retry: no

The organization owning this API key is suspended. Contact support.

resource_missing

404 · invalid_request_error · Retry: no

No such resource. Also returned for a resource owned by another organization, so that IDs are not enumerable.

parameter_invalid

422 · invalid_request_error · Retry: after fix

A parameter failed validation, or a required one such as the Idempotency-Key header is missing. param identifies it.

Fix the parameter named in param (for example gifts[0].delivery.phone) and send the request again. For POST /v1/orders, keep the same Idempotency-Key.

cursor_invalid

422 · invalid_request_error · Retry: after fix

The cursor in starting_after or ending_before does not refer to a resource you can access.

request_body_invalid

400 · invalid_request_error · Retry: after fix

The request body could not be parsed as JSON.

request_body_too_large

413 · invalid_request_error · Retry: after fix

The request body exceeds the 1MB limit.

gift_already_redeemed

422 · invalid_request_error · Retry: no

The gift has already been redeemed by its recipient.

gift_already_delivered

422 · invalid_request_error · Retry: no

The gift has already been delivered.

gift_resend_limit_reached

422 · invalid_request_error · Retry: no

The gift has reached its delivery-retry limit.

gift_delivery_not_updatable

422 · invalid_request_error · Retry: no

Delivery can only be redirected for a gift whose delivery has failed and that is not yet redeemed.

idempotency_key_reused

409 · invalid_request_error · Retry: no

This Idempotency-Key was already used for a request with a different body. Use a new key for a new order.

Generate a new Idempotency-Key for a new order. Reuse a key only to retry the exact same request.

organization_not_configured

422 · invalid_request_error · Retry: after fix

The organization has no active member for orders to be attributed to. Add an active admin, or set a billing contact who is one, in the On Me business portal.

In the business portal, make sure your organization has an active admin, or set a billing contact who is one.

insufficient_balance

402 · insufficient_balance_error · Retry: after fix

The organization balance cannot cover this order. Top up and retry; no order was created and nothing was charged.

Add funds in the On Me business portal under Billing, then retry with the same Idempotency-Key.

rate_limit_exceeded

429 · rate_limit_error · Retry: yes

Too many requests. Retry after the interval given in the Retry-After header.

Back off for the number of seconds in Retry-After, then retry.

sandbox_missing

404 · invalid_request_error · Retry: after fix

No sandbox environment exists for this organization, or the requested sandbox belongs to another organization.

gift_not_claimed

422 · invalid_request_error · Retry: after fix

The gift has not been claimed yet, and the requested operation requires a claimed gift.

sandbox_endpoint_only

403 · invalid_request_error · Retry: no

A /v1/sandbox endpoint was called with a live key. These endpoints fabricate delivery and redemption state, so they answer only in the sandbox. They are documented here because they share a base URL with everything else, not because they exist in production.

Send the request with a sandbox key (omk-sandbox-). There is no live equivalent — in production these transitions are caused by the recipient.

gift_delivery_not_simulatable

422 · invalid_request_error · Retry: after fix

Sandbox only. Delivery can only be simulated for a gift On Me sends itself (email or phone); a link gift is delivered by you.

resource_locked

409 · api_error · Retry: yes

Another operation holds this resource. Nothing happened; retry after a short wait.

idempotency_in_progress

409 · api_error · Retry: yes

A request with this Idempotency-Key is still in progress. Retry after a short wait to get its result.

Wait a second and retry with the same key; you will get the original result.

internal_error

500 · api_error · Retry: yes

An unexpected error occurred on our side. It is safe to retry after a short wait; quote the request_id if it persists.

Retry after a short wait, with the same Idempotency-Key for POST /v1/orders. If it keeps happening, contact support with the request_id.

Categories

The gift catalog.

GET /v1/categories: List categories

Returns the full catalog in one response. Uses the same list envelope as the other collections, but is not paginated — the catalog is small and bounded, so has_more is always false.

Responses

• 200: The full category catalog. Returns CategoryList (see Objects).
• 401: The API key is missing, invalid, or revoked. Returns Error (see Objects).
• 403: The organization is suspended. Returns Error (see Objects).
• 429: Rate limit exceeded. Retry after the interval in Retry-After. Returns Error (see Objects).
• default: An unexpected error. Returns Error (see Objects).

Orders

Purchases of one or more gifts.

GET /v1/orders: List orders

Orders belonging to the calling organization, most recent first. Includes orders still processing as well as processed ones; orders that were never paid for are not returned.

Query parameters

Responses

• 200: A page of orders. Returns OrderList (see Objects).
• 401: The API key is missing, invalid, or revoked. Returns Error (see Objects).
• 403: The organization is suspended. Returns Error (see Objects).
• 422: A query parameter or cursor is invalid. Returns Error (see Objects).
• 429: Rate limit exceeded. Retry after the interval in Retry-After. Returns Error (see Objects).
• default: An unexpected error. Returns Error (see Objects).

POST /v1/orders: Create an order

Mockable

Creates and funds an order of 1–10 gifts, charged to your organization balance in a single debit.

Responds once every gift exists: 201 for a new order, and 200 when an Idempotency-Key replay returns the order that key already created. If we hit a problem after charging you, the order comes back processing instead; it is paid for and we will finish it.

Every request must carry an Idempotency-Key header. See Idempotency and retries and Errors.

Mockable in the sandbox. The recipient address you send to decides what happens: a gift that is delivered, bounces, is opened, claimed or spent, an order that stays processing for twenty seconds, or a whole-order 402 or 500. See Testing in the sandbox.

Headers

Request body (JSON)

Responses

• 200: An Idempotency-Key replay: the order this key already created. Returns Order (see Objects).
  • Header Idempotent-Replayed: Present on a replay.
• 201: The new order: processed, with its gifts, or processing if we hit a problem after charging you. Returns Order (see Objects).
• 400: The request body could not be parsed. Returns Error (see Objects).
• 401: The API key is missing, invalid, or revoked. Returns Error (see Objects).
• 402: The organization balance cannot cover this order. Nothing was created or charged. Returns Error (see Objects).
• 403: The organization is suspended. Returns Error (see Objects).
• 409: A request with this key is still in progress (idempotency_in_progress), this key was used with a different body (idempotency_key_reused), or another order for your organization was being charged at the same moment (resource_locked). Nothing was created or charged. Returns Error (see Objects).
• 413: The request body exceeds the 1MB limit. Returns Error (see Objects).
• 422: The Idempotency-Key header is missing or invalid, the request body failed validation, or the organization has no active member for orders to be attributed to. Returns Error (see Objects).
• 429: Rate limit exceeded. Retry after the interval in Retry-After. Returns Error (see Objects).
• 500: An unexpected error. Nothing was created or charged, so it is safe to retry. Returns Error (see Objects).
• default: An unexpected error. Returns Error (see Objects).

GET /v1/orders/{order_id}: Retrieve an order

Path parameters

Responses

• 200: The order. Returns Order (see Objects).
• 401: The API key is missing, invalid, or revoked. Returns Error (see Objects).
• 403: The organization is suspended. Returns Error (see Objects).
• 404: No such resource, or it belongs to another organization. Returns Error (see Objects).
• 429: Rate limit exceeded. Retry after the interval in Retry-After. Returns Error (see Objects).
• default: An unexpected error. Returns Error (see Objects).

Gifts

Individual gifts and their delivery.

GET /v1/gifts: List gifts

Gifts belonging to the calling organization, most recent purchase first. Redemption links in a list response are not refreshed — retrieve a gift individually to be sure of a working link.

Query parameters

Responses

• 200: A page of gifts. Returns GiftList (see Objects).
• 401: The API key is missing, invalid, or revoked. Returns Error (see Objects).
• 403: The organization is suspended. Returns Error (see Objects).
• 422: A query parameter or cursor is invalid. Returns Error (see Objects).
• 429: Rate limit exceeded. Retry after the interval in Retry-After. Returns Error (see Objects).
• default: An unexpected error. Returns Error (see Objects).

GET /v1/gifts/{gift_id}: Retrieve a gift

Retrieving a link-delivered gift whose redemption token has expired mints a fresh one, so the returned link always works.

Path parameters

Responses

• 200: The gift. Returns Gift (see Objects).
• 401: The API key is missing, invalid, or revoked. Returns Error (see Objects).
• 403: The organization is suspended. Returns Error (see Objects).
• 404: No such resource, or it belongs to another organization. Returns Error (see Objects).
• 429: Rate limit exceeded. Retry after the interval in Retry-After. Returns Error (see Objects).
• default: An unexpected error. Returns Error (see Objects).

PUT /v1/gifts/{gift_id}/delivery: Redirect a failed delivery

Mockable

Re-sends a gift to a different address. Restricted to gifts whose delivery has FAILED and that are not yet redeemed; any other state returns 422. Redirecting a successfully delivered gift would let a caller reroute it, so this is a security constraint rather than a convenience.

Mockable in the sandbox. The failed delivery this needs is otherwise unreachable on demand — order to delivery-failed@sandbox.onme.com, or call POST /v1/sandbox/gifts/{gift_id}/deliver with {"outcome":"failed"}, to get a gift in the one state it accepts. See Testing in the sandbox.

Path parameters

Request body (JSON)

Responses

• 200: The updated gift. Returns Gift (see Objects).
• 400: The request body could not be parsed. Returns Error (see Objects).
• 401: The API key is missing, invalid, or revoked. Returns Error (see Objects).
• 403: The organization is suspended. Returns Error (see Objects).
• 404: No such resource, or it belongs to another organization. Returns Error (see Objects).
• 413: The request body exceeds the 1MB limit. Returns Error (see Objects).
• 422: The gift is not in a state whose delivery can be redirected, or the body failed validation. Returns Error (see Objects).
• 429: Rate limit exceeded. Retry after the interval in Retry-After. Returns Error (see Objects).
• default: An unexpected error. Returns Error (see Objects).

Sandbox

Simulation endpoints, answered only for a sandbox key. They drive state that in production only a recipient can cause — delivery settling, opening, claiming, spending — plus a reset. See Testing in the sandbox.

POST /v1/sandbox/gifts/{gift_id}/deliver: Simulate delivery

Sandbox only

Settles a pending email or phone delivery as delivered or failed. Use this on a gift that already exists. A link-delivered gift has no delivery for On Me to settle and returns 422 gift_delivery_not_simulatable. A failed outcome is what unlocks PUT /v1/gifts/{gift_id}/delivery.

Sandbox only: a live key gets 403 sandbox_endpoint_only. In production this transition is caused by the recipient, and there is no way to ask for it.

Path parameters

Request body (JSON)

Responses

• 200: The gift, after the transition. Returns Gift (see Objects).
• 400: The request body could not be parsed. Returns Error (see Objects).
• 401: The API key is missing, invalid, or revoked. Returns Error (see Objects).
• 403: Called with a live key (sandbox_endpoint_only) — these endpoints exist only in the sandbox — or the organization is suspended. Returns Error (see Objects).
• 404: No such resource, or it belongs to another organization. Returns Error (see Objects).
• 422: Delivery cannot be simulated for this gift (gift_delivery_not_simulatable — the gift is delivered by link, so there is nothing for us to send), or the body failed validation. Returns Error (see Objects).
• 429: Rate limit exceeded. Retry after the interval in Retry-After. Returns Error (see Objects).
• default: An unexpected error. Returns Error (see Objects).

POST /v1/sandbox/gifts/{gift_id}/open: Simulate the recipient opening a gift

Sandbox only

Stamps the gift opened, as a recipient following their link would.

Sandbox only: a live key gets 403 sandbox_endpoint_only. In production this transition is caused by the recipient, and there is no way to ask for it.

Path parameters

Responses

• 200: The gift, after the transition. Returns Gift (see Objects).
• 401: The API key is missing, invalid, or revoked. Returns Error (see Objects).
• 403: Called with a live key (sandbox_endpoint_only) — these endpoints exist only in the sandbox — or the organization is suspended. Returns Error (see Objects).
• 404: No such resource, or it belongs to another organization. Returns Error (see Objects).
• 429: Rate limit exceeded. Retry after the interval in Retry-After. Returns Error (see Objects).
• default: An unexpected error. Returns Error (see Objects).

POST /v1/sandbox/gifts/{gift_id}/claim: Simulate the recipient claiming a gift

Sandbox only

Redeems the gift onto a card. Back-fills the opened timestamp if the gift was never opened, because a claimed-but-never-opened gift is a state production cannot produce and your integration should not have to handle.

Sandbox only: a live key gets 403 sandbox_endpoint_only. In production this transition is caused by the recipient, and there is no way to ask for it.

Path parameters

Responses

• 200: The gift, after the transition. Returns Gift (see Objects).
• 401: The API key is missing, invalid, or revoked. Returns Error (see Objects).
• 403: Called with a live key (sandbox_endpoint_only) — these endpoints exist only in the sandbox — or the organization is suspended. Returns Error (see Objects).
• 404: No such resource, or it belongs to another organization. Returns Error (see Objects).
• 422: The gift is already redeemed (gift_already_redeemed). Returns Error (see Objects).
• 429: Rate limit exceeded. Retry after the interval in Retry-After. Returns Error (see Objects).
• default: An unexpected error. Returns Error (see Objects).

POST /v1/sandbox/gifts/{gift_id}/spend: Simulate a first spend

Sandbox only

Records spend against the claimed gift’s card. Ordering is enforced as it is in production: spending before claiming returns 422 gift_not_claimed.

Sandbox only: a live key gets 403 sandbox_endpoint_only. In production this transition is caused by the recipient, and there is no way to ask for it.

Path parameters

Responses

• 200: The gift, after the transition. Returns Gift (see Objects).
• 401: The API key is missing, invalid, or revoked. Returns Error (see Objects).
• 403: Called with a live key (sandbox_endpoint_only) — these endpoints exist only in the sandbox — or the organization is suspended. Returns Error (see Objects).
• 404: No such resource, or it belongs to another organization. Returns Error (see Objects).
• 422: The gift has not been claimed yet (gift_not_claimed). Returns Error (see Objects).
• 429: Rate limit exceeded. Retry after the interval in Retry-After. Returns Error (see Objects).
• default: An unexpected error. Returns Error (see Objects).

POST /v1/sandbox/reset: Delete all sandbox data

Sandbox only

Deletes every order, gift, balance and balance ledger entry belonging to your organization in the sandbox. Your API keys survive; you will need to add funds again before you can order.

Not reversible and not idempotency-protected. It is scoped to your own sandbox data, which is the only safety property it needs. The counts come back separately rather than summed so an automated setup step can assert on what actually went.

Sandbox only: a live key gets 403 sandbox_endpoint_only.

Responses

• 200: What was deleted. Returns SandboxResetResult (see Objects).
• 401: The API key is missing, invalid, or revoked. Returns Error (see Objects).
• 403: Called with a live key (sandbox_endpoint_only) — this endpoint exists only in the sandbox — or the organization is suspended. Returns Error (see Objects).
• 429: Rate limit exceeded. Retry after the interval in Retry-After. Returns Error (see Objects).
• default: An unexpected error. Returns Error (see Objects).

Meta

Unauthenticated service endpoints.

GET /v1/health: Health check

Liveness probe. Requires no authentication.

Responses

• 200: The API is reachable.
• 429: Rate limit exceeded. Retry after the interval in Retry-After. Returns Error (see Objects).
• default: An unexpected error. Returns Error (see Objects).

GET /v1/openapi.json: Retrieve this specification

Returns this document. Requires no authentication, so a client can read the contract before it holds a key.

Responses

• 200: The OpenAPI document.
• 429: Rate limit exceeded. Retry after the interval in Retry-After. Returns Error (see Objects).
• default: An unexpected error. Returns Error (see Objects).

Objects

GiftDelivery

GiftPersonalization

Gift

GiftList

Order

OrderList

Category

CategoryList

SandboxResetResult

Error