Skip to Content
LogoDevelopers
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 sessions

MethodPathDescription
POST/checkout-sessionsCreate a session. Pass cart_id to check out an existing cart
GET/checkout-sessions/{id}Retrieve a session
PUT/checkout-sessions/{id}Update buyer, fulfillment, and discounts (restate line_items)
POST/checkout-sessions/{id}/completeComplete the session. A remaining balance hands payment to com.finqu.hosted_checkout via continue_url
POST/checkout-sessions/{id}/cancelCancel the session and leave the cart in place

POST /checkout-sessions returns 201. POST /checkout-sessions, POST …/complete, and POST …/cancel honor Idempotency-Key.

Copy fulfillment method, group, and option ids from the session. Do not invent them. When identity linking is advertised and the request has no buyer token, the session includes an identity_optional message. Checkout still works as a guest.

See Getting Started — Checkout.

Orders

MethodPathDescription
GET/orders/{id}Read one order

Reading a buyer’s order requires the buyer token: Authorization: Bearer ucp_at_… with scope dev.ucp.shopping.order:read. Send that token on its own request, not together with fq_secret_…. A user token without the scope returns 403 and an insufficient_scope challenge. See Identity linking.

Locations

MethodPathDescription
POST/locations/searchSearch pickup locations (serves, context)
POST/locations/lookupLook up locations by ids

Embedded checkout, loyalty, and webhooks are listed on the capability reference. This page does not document those operations.

OAuth

MethodPathDescription
POST/oauth/tokenExchange an authorization code or refresh a token
POST/oauth/revokeRevoke an access or refresh token

Both endpoints take application/x-www-form-urlencoded and do not use the channel API key. See Identity linking.

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.