API reference

Every endpoint and object. JSON in, JSON out, amounts in minor units (cents).

Basics

Base URL: https://www.useharbor.io/v1
Authentication: Authorization: Bearer hk_test_… or hk_live_… on every request. The key's prefix picks the environment.
User-scoped requests (checkouts, orders, connections, most sandbox controls) also send Harbor-User-Token: user-….
Bodies are JSON with content-type: application/json. Unknown fields are rejected.
Money is { "amount": 2659, "currency": "USD" }, with amount in minor units.
Ids have a type prefix: usr_, ofr_, chk_, ord_, evt_, whk_, con_.
Errors are described in Errors. Every response has a Harbor-Request-Id header.
Idempotency: send Idempotency-Key: <any unique string> on a POST to make it safe to retry. Harbor runs it once and returns the stored response (with Idempotent-Replayed: true) for repeats within 24 hours. Reusing a key for a different request returns INVALID_REQUEST; a repeat that arrives while the first is still running returns IDEMPOTENCY_KEY_IN_USE (409). Use one for every confirm.

Lists the stores Harbor can buy from: the registry (major retailers and named stores; sandbox keys also see sandbox stores) on the first page, then the catalog of every UCP store Harbor has discovered.

Parameter	Type	Description
`q`	string	Search store names, domains and categories, like `coffee`.
`limit`	integer	Catalog stores per page, 1–200. Default 100.
`after`	string	Continue from `next_after` on the previous page.

Returns { "merchants": [Merchant], "has_more", "next_after" }. Any store with a UCP checkout works from its product link even before it's listed; it joins the catalog on first use.

GET/v1/merchants/{id}key

One merchant.

The Merchant object

Field	Type	Description
`id`	string	Stable id, like `target` or `ucp_shop_example_com`.
`name`	string	Display name.
`domain`	string	The store's domain.
`tier`	string	`major`, `protocol` or `long_tail`.
`route`	string	`device_session`, `ucp` or `browser`. See Stores and routes.
`category`	string	Catalog stores, where known: what the store mainly sells, like `apparel` or `home`.
`requires_connection`	boolean	Whether the user must connect the store in Approve first.
`capabilities`	object	`offers`, `checkout`, `orders`: what Harbor supports there.
`status`	string	`healthy`, `degraded` or `down`.
`sandbox`	boolean	Present and `true` for sandbox stores.

Approval

POST/v1/approval_tokenskey

Starts Harbor Approve for a user. See Approve users.

Parameter	Type	Description
`client_user_id`	string, required	Your id for the user, up to 200 characters.
`rules`	object	`max_per_order`, `max_per_day`, `confirm_above` (integers, minor units), `currency`, `allowed_merchants` (merchant ids).
`merchant_ids`	string[]	Stores to offer for connecting, up to 50.
`redirect_uri`	string	Where to send the user after approving, with `public_token` added.

Returns { "approval_token", "expiration", "hosted_url" }. The token lasts 30 minutes.

POST/v1/approval_tokens/exchangekey

Parameter	Type	Description
`public_token`	string, required	From Approve. Works once.

Returns { "user_token", "user_id" }.

Offers

POST/v1/offerskey

Looks up a live price and availability for a product link.

Parameter	Type	Description
`url`	string, required	A product page URL.

Returns an Offer. Major retailers' prices are read in the user's browser, so create their checkouts with product_url instead; offers there return MERCHANT_NOT_SUPPORTED.

GET/v1/offers/{id}key

An offer you looked up.

The Offer object

Field	Type	Description
`id`	string	`ofr_…`
`merchant_id`	string	The store.
`url`	string	The product page.
`title`	string	Product name.
`price`	Money	Price of the selected variant.
`availability`	string	`in_stock`, `out_of_stock`, `preorder` or `unknown`.
`item_ref`	string	The store's id for the selected variant.
`image_url`	string	The store's product photo, served from the store's own CDN, when it publishes one.
`variants`	array	Other variants: `item_ref`, `title`, `price`, `availability`.
`fetched_at`	string	When Harbor asked the store.
`expires_at`	string	15 minutes later. Checkouts need an unexpired offer.

Checkouts

All checkout endpoints need Harbor-User-Token. See Checkouts for the lifecycle.

POST/v1/checkoutskey + user

Parameter	Type	Description
`offer_id`	string	An unexpired offer. Provide this or `product_url`.
`product_url`	string	A product link. Required for major retailers.
`item_ref`	string	A variant from the offer. Defaults to the offer's.
`quantity`	integer	1 to 20. Default 1.
`buyer`	object	`email`, `phone`.
`shipping_address`	object	`name`, `line1`, `line2`, `city`, `region`, `postal_code`, `country` (2 letters).

Returns the Checkout.

GET/v1/checkouts/{id}key + user

The current state of a checkout.

POST/v1/checkouts/{id}/updatekey + user

Adds or replaces buyer and shipping_address, and re-prices with the store. Not available for major retailers.

POST/v1/checkouts/{id}/confirmkey + user

Places the order. Only in ready_to_confirm. No body.

POST/v1/checkouts/{id}/user_inputkey + user

Parameter	Type	Description
`fields`	object	The values `next_action.fields` asked for, like `{ "verification_code": "123456" }`.

POST/v1/checkouts/{id}/cancelkey + user

Cancels an open checkout. No body.

The Checkout object

Field	Type	Description
`id`	string	`chk_…`
`user_id`	string	The Harbor user.
`merchant_id`	string	The store.
`offer_id`	string	The offer it came from, if any.
`product_url`	string	The product link.
`route`	string	How it's placed: `device_session`, `ucp` or `browser`.
`status`	string	`building`, `requires_user_action`, `ready_to_confirm`, `confirming`, `completed`, `failed` or `canceled`.
`line_items`	array	`item_ref`, `title`, `quantity`, `unit_price`.
`totals`	object	`subtotal`, `shipping`, `tax`, `total`, each Money, from the store.
`shipping_address`	object	As sent.
`next_action`	object	When `requires_user_action`: `type`, `description`, and `url`, `fields`, `task_id` or `connection_id` depending on the type.
`requires_user_confirmation`	boolean	The user must confirm this total themselves.
`user_confirmed_at`	string	When they did.
`order_id`	string	Set when `completed`.
`error`	object	Set when `failed`. Same shape as API errors.
`merchant_messages`	array	The store's own messages, for debugging.
`created_at`, `updated_at`	string	ISO timestamps.

Orders

GET/v1/orderskey + user

The user's orders, newest first, up to 100: { "orders": [Order] }.

GET/v1/orders/{id}key + user

One order. See Orders for the object and statuses.

Connections

GET/v1/connectionskey + user

The stores the user has connected: { "connections": [Connection] }, each with id, user_id, merchant_id, status (active, needs_user or revoked) and created_at.

Webhook endpoints

POST/v1/webhook_endpointskey

Parameter	Type	Description
`url`	string, required	Where to post events.

Returns { "id", "url", "secret" }. See Webhooks for events and signatures. List and remove endpoints in the dashboard.

Sandbox

Sandbox keys only. See Sandbox.

POST/v1/sandbox/public_tokenkey

POST/v1/sandbox/connectionskey + user

POST/v1/sandbox/checkouts/{id}/user_confirmkey + user

POST/v1/sandbox/checkouts/{id}/merchant_completekey + user

POST/v1/sandbox/orders/{id}/advancekey + user

Health

GET/v1/healthnone

Returns { "ok": true }.