Skip to Content
ReferenceUcpREST API

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

HeaderRequiredPurpose
AuthorizationYes (except anonymous tier)Bearer API key or signature headers
UCP-AgentRecommendedPlatform profile URL for capability negotiation
Idempotency-KeyRecommended on create/cancelPrevents duplicate side effects
Content-TypeOn POST/PUTapplication/json

See Authentication for tier details.

Catalog

MethodPathDescription
POST/catalog/searchSearch products (query, filters, limit, cursor, context)
POST/catalog/lookupLook up products by ids array
POST/catalog/productGet 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

MethodPathDescription
POST/cartsCreate a cart from line_items
GET/carts/{id}Retrieve a cart
PUT/carts/{id}Replace all line items (full update)
POST/carts/{id}/cancelCancel 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.