Merchant API for headless backends

Use pk_live_ keys with write scopes from your server only. All requests go to your Merly gateway at /api/v1/merchant.

Swagger UI →Full Merchant API reference →← Headless hub

Write scopes (headless)

Scope	Label	Use
`write:webhooks`	Test webhooks	Send signed test lifecycle events to your configured outbound webhook URL
`write:catalog`	Publish catalog	Publish store policy and product directory (headless merchants)
`write:customers`	Link customers	Link external customer IDs to Merly wallets (headless merchants)
`write:orders`	Ingest orders	Report paid orders for purchase earn (headless merchants)

All mutating routes require an x-idempotency-key header. Generate a unique value per logical operation so safe retries do not double-apply changes.

Write endpoints

POSTTest outbound webhook

/api/v1/merchant/webhooks/test

Scope: write:webhooks

Sends a signed test lifecycle event to the outbound webhook URL configured in Integrations.

Request body

{
  "event_type": "merly.points.earned"
}

Example response

{
  "ok": true,
  "event_type": "merly.points.earned",
  "correlation_id": "…"
}

POSTPublish catalog policy and products

/api/v1/merchant/catalog/publish

Scope: write:catalog

Headless merchants only. Requires x-idempotency-key.

Request body

{
  "policy_store_only": true,
  "cap": {
    "max_coupon_value_usd": 50
  }
}

Example response

{
  "ok": true,
  "product_count": 0,
  "catalog_store_id": "hl_boutique-example-com",
  "correlation_id": "…"
}

POSTLink external customer to Merly wallet

/api/v1/merchant/customers/link

Scope: write:customers

Request body

{
  "external_customer_id": "cust_1",
  "email": "buyer@example.com"
}

Example response

{
  "customer_user_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "created": true,
  "linked": true,
  "correlation_id": "…"
}

POSTIngest paid order

/api/v1/merchant/orders

Scope: write:orders

Request body

{
  "order_id": "ord_1",
  "external_customer_id": "cust_1",
  "customer_email": "buyer@example.com",
  "currency": "USD",
  "total": "120.00",
  "subtotal": "110.00"
}

Example response

{
  "order_id": "ord_1",
  "earn_granted": 110,
  "correlation_id": "…"
}

Read endpoints (shopper wallet data)

Use from your backend when enriching CRM or support tools — not in the browser SDK.

GETCustomer wallet balance

/api/v1/merchant/customers/{customer_id}/balance — read:balance

GETSubscription tier

/api/v1/merchant/customers/{customer_id}/tier — read:tier

GETWallet activity

/api/v1/merchant/customers/{customer_id}/activity — read:activity

POSTValidate Merly credit coupon at merchant checkout

/api/v1/merchant/coupons/validate — read:coupons