# REST API

**Base URL:** `https://{shop-domain}/api/ucp`

**Service root:** `GET /api/ucp` — returns protocol metadata and confirms reachability.

All mutating endpoints accept `Content-Type: application/json`. CORS is supported for browser-based integrations.

## Standard headers

| Header | Required | Purpose |
|--------|----------|---------|
| `Authorization` | Yes (except anonymous tier) | Bearer API key or signature headers |
| `UCP-Agent` | Recommended | Platform profile URL for capability negotiation |
| `Idempotency-Key` | Recommended on create/cancel | Prevents duplicate side effects |
| `Content-Type` | On POST/PUT | `application/json` |

See [Authentication](./authentication) for tier details.

## Catalog

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/catalog/search` | Search products (`query`, `filters`, `limit`, `cursor`, `context`) |
| `POST` | `/catalog/lookup` | Look up products by `ids` array |
| `POST` | `/catalog/product` | Get a single product by `id` |

**Context object** (optional on catalog calls): localize results with fields such as `language` (BCP 47), `currency` (ISO 4217), `address_country`, `address_region`, and `postal_code`.

Search responses include `products` and `pagination` (with a `cursor` for the next page). Lookup and product responses return full product objects including variants, pricing, and customization metadata.

## Carts

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/carts` | Create a cart from `line_items` |
| `GET` | `/carts/{id}` | Retrieve a cart |
| `PUT` | `/carts/{id}` | Replace all line items (full update) |
| `POST` | `/carts/{id}/cancel` | Cancel a cart (clear all items) |

**Line items** reference a variant by `item.id` and `quantity`. Products with customizations require a `customizations` array — use the customization metadata returned by catalog lookup/search to build valid entries.

Cart responses include:

- `id`, `currency`, `line_items`, `totals` (subtotal, tax, discounts, grand total in minor currency units)
- `continue_url` — a buyer-facing URL to continue to checkout in the storefront
- `discounts` — when the discount capability is negotiated
- `messages` — warnings or recoverable errors (for example rejected coupon codes)
- `ucp` — protocol metadata block

**Idempotency:** `POST /carts` and `POST /carts/{id}/cancel` honor the `Idempotency-Key` header. Replaying the same key returns the original response.

## Checkout and orders

Checkout session and order endpoints follow the UCP specification but are **not yet published** on Finqu. When they become available, they will appear under:

- `/checkout-sessions` (create, get, update, complete, cancel)
- `/orders/{id}`

## Money and localization

- All monetary amounts are **integers in minor currency units** (cents, öre, etc.)
- Currency codes are **ISO 4217** three-letter strings
- Country codes are **ISO 3166-1 alpha-2**
- Pass `context.currency` and `context.language` on catalog and cart calls to localize pricing and product content

## Product customizations

Many Finqu products support buyer customizations (text fields, option groups, required selections). The catalog returns customization definitions on variant metadata. When adding items to a cart:

1. Look up or search for the product first
2. Read `metadata.customizations` on the chosen variant
3. Include a `customizations` array on each line item with `{ "id": "…", "value": "…" }`
4. Required customization groups must have at least one selection

Missing or invalid customizations return validation errors with field-level messages.