Website API

Public Website API for /api/website/listings, /api/website/stock-updates, order/contact webhooks, and reply relay delivery.

Last updated:

These endpoints are intentionally public integration contracts for connected Website channels. They do not use browser session authentication.

Public Website endpoints covered here include /api/website/listings, /api/website/stock-updates, /webhooks/website/orders/created, /webhooks/website/orders/cancelled, and /webhooks/website/messages/contact.

Use the Website API key as a bearer token:

Authorization: Bearer <website_api_key>

Order and contact ingestion routes also require signed request integrity headers. Catalogue and stock read routes use the bearer token only.

Catalogue listing feed

GET /api/website/listings

Returns published Website listings for the authenticated Website connection.

Query parameters:

  • page (default 1)
  • page_size (default 50, max 200)
  • q (optional title, SKU, or listing-id search)
  • sort:
    • title
    • sku
    • Omitted/default: latest published or updated first

Response fields:

{
  "ok": true,
  "page": 1,
  "page_size": 50,
  "total": 1,
  "items": [
    {
      "id": "WL-000003",
      "sku": "ABC-001",
      "title": "Example listing",
      "description": "Listing or stock-backed description",
      "listing_type": "fixed_price",
      "currency": "GBP",
      "price": 19.99,
      "quantity": 4,
      "view_url": "https://example.com/products/abc-001",
      "image_url": "https://cdn.example.com/products/abc-001.jpg",
      "item_specifics": [
        {
          "name": "Artist",
          "value": "Example Artist"
        }
      ],
      "updated_at": "2026-06-20 12:00:00+00",
      "published_at": "2026-06-20 11:30:00+00"
    }
  ]
}

Notes:

  • id is the Website listing ID when present; otherwise it falls back to the internal listing UUID.
  • description uses the listing description first, then falls back to the linked stock product description.
  • image_url is the primary linked stock product image when available.
  • item_specifics contains the Website draft item specifics captured at publish time. These complement stock item Reference facts and are returned as ordered name/value pairs.

Stock update feed

GET /api/website/stock-updates

Returns active stock rows for the authenticated Website connection. Use this when the customer website needs stock availability or stock-text refreshes without reading signed-in ChannelWeave UI APIs.

Query parameters:

  • page (default 1)
  • page_size (default 50, max 200)
  • q (optional SKU, stock-name, or stock-description search)
  • sort:
    • sku
    • sku_desc
    • available_asc
    • available_desc
    • updated_asc
    • updated_desc
    • Omitted/default: stock name ascending

Response fields:

{
  "ok": true,
  "page": 1,
  "page_size": 50,
  "total": 1,
  "items": [
    {
      "id": "2f1a4c2e-2d8c-4d4c-a9b7-0e3a6f0f1c2d",
      "sku": "ABC-001",
      "stock_name": "Example stock item",
      "stock_description": "Default listing description",
      "quantity_available": "4.0000",
      "updated_at": "2026-06-20 12:00:00+00"
    }
  ]
}

Order webhook routes

  • POST /webhooks/website/orders/created
  • POST /webhooks/website/orders/cancelled

Auth and integrity headers

  • Authorization: Bearer <website_api_key>
  • X-CW-Timestamp
  • X-CW-Signature (v1=<hmac_sha256_hex>)

Required request body fields

{
  "external_order_ref": "WEB-10001234",
  "line_items": [
    {
      "sku": "ABC-001",
      "quantity": 2
    }
  ]
}

For orders/cancelled, only external_order_ref is required.

When POST /webhooks/website/orders/created is called:

  • ChannelWeave creates/updates the website order record immediately.
  • line_items are created/updated by line number.
  • All line sku values must exist in ChannelWeave stock for the connected account.
  • Order totals are recalculated from order lines plus shipping_*/discount_amount.

When POST /webhooks/website/orders/cancelled is called:

  • Order status and fulfilment status are set to cancelled.
  • Existing order lines are marked cancelled.

Optional order/buyer/address fields

Optional fields are upserted when provided:

  • external_order_number
  • currency_code (defaults to GBP)
  • order_date, external_created_at, external_updated_at
  • payment_status (defaults to awaiting_payment; shown in the app UI as Awaiting payment)
  • shipping_net_amount, shipping_tax_amount, discount_amount
  • buyer_name, buyer_email, buyer_phone
  • shipping_address
  • billing_address

shipping_address and billing_address accept either direct address objects or nested shipping.address and billing.address objects.

Address data is normalised into:

  • The order shipping address field
  • The order billing address field

line_items contract

Each line_items[] entry accepts:

  • sku (required)
  • quantity (required, positive number)
  • unit_price or price (optional, non-negative)
  • discount_amount, tax_rate, tax_amount, net_amount, gross_amount (optional)
  • external_line_ref, line_ref, id (optional idempotency reference)
  • external_item_ref, item_ref, listing_id (optional)
  • description/title/name (optional description text)

Contact-message webhook route

  • POST /webhooks/website/messages/contact

Purpose

Accepts website contact-form submissions and creates/updates an Inbox → Messages conversation with:

  • channel_code = 'website'
  • message_type_code = 'buyer_question'
  • direction = 'inbound'

Request contract

Content type: JSON object (application/json).

Required auth and integrity headers:

  • Authorization: Bearer <website_api_key>
  • X-CW-Timestamp
  • X-CW-Signature (v1=<hmac_sha256_hex>)

Required fields:

  • name
  • email
  • message
  • submission_id (or X-CW-Idempotency-Key header)

Optional fields:

  • company
  • target_date (YYYY-MM-DD)
  • website_host
  • website_domain
  • source_url
  • page_url
  • website_url

For static websites, the browser should post to your own relay endpoint first; the relay signs and forwards JSON to this ChannelWeave route.

Response codes

  • 200 { "ok": true } on ingest
  • 401 missing/invalid API key
  • 400 bad signature/timestamp or invalid payload
  • 500 server error

Outbound Website reply dispatch (customer relay)

When a team member replies to an eligible Website conversation in Inbox → Messages, ChannelWeave sends a signed server-to-server POST to the customer website relay:

  • POST https://<customer-website>/api/website/replies/send

Required integrity headers:

  • X-CW-Timestamp
  • X-CW-Signature (v1=<hmac_sha256_hex>)
  • X-CW-Idempotency-Key

Required JSON fields:

  • reply_id
  • thread_id
  • buyer_email
  • subject
  • reply_body

Recommended optional JSON fields:

  • buyer_name
  • external_thread_id
  • sent_at

Relay expectations:

  • Verify timestamp window + signature using Website signing secret
  • Enforce idempotency by reply_id / idempotency header
  • Deliver the email via the customer’s configured provider
  • Return 200 { "ok": true } when delivery succeeds