> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ugift.me/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Overview of the UGiftMe REST API for B2B integrations.

# UGiftMe REST API

Server-side integration over **`/api/v1/business`**: catalog, orders, wallet, and outbound webhooks using **`X-API-Key`**.

## Base URLs

| Environment | Base URL                     |
| ----------- | ---------------------------- |
| Sandbox     | `https://api-stage.ugift.me` |
| Production  | `https://api.ugift.me`       |

All paths in this documentation are prefixed with **`/api/v1/business`** (for example **`GET /api/v1/business/auth`**).

## Authentication

Every documented request requires:

`X-API-Key: <your-api-key>`

Keys are UUIDs issued from the **dashboard**. If your key has an **IP allow list**, requests must come from an allowed address.

Use **`GET /api/v1/business/auth`** to validate a key and retrieve minimal integration metadata (health checks and connection tests).

## What you can call

| Area         | Role                                                                                                                                                 |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Products** | List, filter, and search the catalog available to your key.                                                                                          |
| **Orders**   | Create single or bulk orders; list, search, and fetch by id; poll async **order requests**.                                                          |
| **Wallet**   | Wallets, balances, and transaction history.                                                                                                          |
| **Webhooks** | Register and manage HTTPS endpoints for **outbound** events (UGiftMe POSTs to your URL). **POST**, **GET**, **PATCH**, **DELETE** under `/webhooks`. |

## Orders (async)

When async processing is enabled, **`POST /api/v1/business/orders`** may return **`202`** with `orderRequestId` and `status: queued`. Poll **`GET /api/v1/business/orders/order-requests/{id}`**. Optional **`Idempotency-Key`** is supported on create and bulk create.

## Webhooks

UGiftMe sends events to URLs you register; your integration **receives** POST requests only. Manage subscriptions with **`POST`** (create), **`GET`** (list), **`PATCH /{id}`** (update URL, events, description, or pause via `isActive` without rotating the secret), and **`DELETE /{id}`** (remove).

Allowed `events`: `order.queued`, `order.processing`, `order.succeeded`, `order.failed`, `product.updated`, `wallet.updated`.

See **[Webhook deliveries](/docs/webhook-deliveries)** for POST headers, HMAC signature verification, payload shapes, retries, and test endpoints.

## Error responses

Failures return JSON with at least an **`error`** string (no global `success` / `action` / `code` envelope). See the **API Guide** and **UGiftMe API Reference** tabs for status-specific examples including **`403 Forbidden`** (IP allow list, business profile checks) and **`404 Not Found`** (missing wallet, order, or webhook).

## Interactive reference

Open the **UGiftMe API Reference** tab for the full OpenAPI-driven pages and playground. Narrative detail lives under **UGiftMe API**.