Connect your business to HiCCUP.

Merchants supply the products. Marketplaces sell them. Warehouses hold and ship them. Each role has its own API, its own credentials and its own reference. Pick yours below.

You supply products to HiCCUP

Merchant API

Push your catalog, stock and prices. Pack the packages we route to you. Track your supplier invoices.

POST/merchant/products/upsert
PUT/merchant/products/stock
PUT/merchant/products/price
PUT/merchant/package/markPackagesPacked

9 endpoints, 15 requests a minuteOpen the Merchant guide You sell the HiCCUP catalog on your channel

Marketplace API

Pull the published catalog, prices and stock. Push orders and returns. Follow every package and shipment to the customer.

GET/marketplace/catalog
POST/marketplace/orders
GET/marketplace/shipments/{shipmentUid}
POST/marketplace/returns

13 endpoints, 15 to 30 requests a minuteOpen the Marketplace guide You hold HiCCUP stock in your warehouse

Warehouse API

Report on-hand quantities by barcode or sku. HiCCUP redistributes the new levels to every sales channel immediately.

PUT/warehouse/stock

1 endpoint, 30 requests a minuteOpen the Warehouse guide

One key. One token. Every API.

Exchange the API key we issued you for a short-lived token, then send that token on every call. The token carries your scope and your tenant: you never send a merchant, channel or warehouse id yourself, and it cannot be widened from the client.

Tokens expire. When a call returns 401, request a new token and retry.

# 1. exchange your key for a token
curl -X POST https://api.hiccup.dev/auth/token \
  -H "X-API-KEY: $HICCUP_API_KEY"

# response: { "token": "eyJhbGciOi…", "tokenType": "Bearer", "expiresIn": 1752500000 }

# 2. call your API with it
curl https://api.hiccup.dev/marketplace/catalog?page=1&size=50 \
  -H "Authorization: Bearer $TOKEN"

The same rules everywhere.

The three APIs are built by one team on one platform. What you learn integrating one carries over to the next.

Pagination

Merchant and Marketplace

Lists take page (from 1) and size, and answer with data plus meta.page, meta.size, meta.totalPages and meta.totalCount.

Incremental sync

Marketplace

Every feed accepts updatedSince (ISO-8601) and is ordered by updatedOn. Poll with the newest updatedOn you stored and you never re-read the whole table.

Tenant scoping

All APIs

The token scopes every request to you. You never send your own merchant, channel or warehouse id, and nothing outside your scope can be read or changed.

Rate limits

All APIs

Limits are per token per minute and printed on every endpoint. A 429 means back off and retry after the minute rolls over.

Errors

All APIs

Errors are JSON with a message and a code. Batch endpoints validate every item before changing anything. The exact shape differs per API, so read the reference you integrate.

Barcodes and skus

All APIs

Merchant and Warehouse calls take the barcode printed on the goods and resolve it to the sku. Marketplace rows carry familySku (product), skuPrefix (colourway) and sku (size).