SKUU Connect: product and inventory integration

A simple customer guide for integrating a custom commerce platform with
SKUU Connect API v1.

This page covers the Phase-1 product and inventory integration. For exact field
rules, schemas and response examples, use the API Reference in this portal.

Overview

SKUU connects a customer's catalogue and physical stock to the SKUU retail
network.

The integration has three API connections:

The customer remains the source of truth for physical stock. SKUU is the only
system allowed to write quantities at the virtual SKUU_Network location.

What to implement

1. Product catalogue

Expose a cursor-paginated endpoint:

GET https://api.customer.example/skuu/v1/products?limit=100
Authorization: Bearer <token>
Accept: application/json

Example response:

{
  "products": [
    {
      "product_id": "P-123",
      "title": "Wool Coat",
      "brand": "Example Brand",
      "variants": [
        {
          "variant_id": "V-123-38",
          "barcode": "8712345678901",
          "sku": "WC-38",
          "size": "38",
          "colour": "black",
          "price": 249.95,
          "currency": "EUR",
          "inventory": [
            {
              "location_id": "1",
              "available_quantity": 3
            },
            {
              "location_id": "900",
              "available_quantity": 0
            }
          ]
        }
      ]
    }
  ],
  "next_cursor": null
}

Important rules:

• Product and variant IDs must be stable and unique.
• Every variant needs a barcode, SKU, or title/size/colour matching route.
• inventory must include every agreed physical location and the
  SKUU_Network location.
• Include explicit zero quantities; do not omit an out-of-stock location.
• Quantities are absolute non-negative integers, never deltas.
• Return next_cursor when another page exists. SKUU sends that value back as
  the next cursor query parameter.
• A successfully completed catalogue is authoritative. Never return a partial
  catalogue as the final page.

2. Real-time inventory updates

Send one webhook for each changed (variant_id, location_id) pair:

POST {skuu_webhook_url}
Content-Type: application/json
X-SKUU-Signature: sha256=<hmac>

{
  "spec_version": "1",
  "event": "inventory.updated",
  "event_id": "evt_01JABC123",
  "occurred_at": "2026-07-24T10:00:00Z",
  "data": {
    "variant_id": "V-123-38",
    "location_id": "1",
    "available_quantity": 2,
    "changed_at": "2026-07-24T09:59:58Z"
  }
}

Important rules:

• available_quantity is the new absolute quantity.
• Send one event per variant and location; data is one object, not an array.
• Give every logical event a globally unique string event_id.
• A retry must reuse the same event ID, body and source timestamps.
• Sign the exact raw JSON bytes sent over the wire.
• Stop after HTTP 200.
• Retry network failures and 5xx responses with exponential backoff.
• Treat 401 as a configuration or signature problem; do not retry blindly.
• Treat 413 as permanent and fix the payload before sending a new event.

HTTP 200 acknowledges delivery; it does not by itself prove that the stock
change was applied. SKUU confirms durable acceptance during testing.

SKUU provides a complete webhook URL for each environment before testing.
Do not derive, reuse or hardcode a URL from another environment.

3. SKUU network inventory writes

Expose an endpoint where SKUU can update one variant at the virtual
SKUU_Network location:

PUT https://api.customer.example/skuu/v1/inventory
Authorization: Bearer <token>
Content-Type: application/json
X-SKUU-Signature: sha256=<hmac>

{
  "variant_id": "V-123-38",
  "location_id": "900",
  "available_quantity": 4
}

A successful response echoes the accepted values:

{
  "variant_id": "V-123-38",
  "location_id": "900",
  "available_quantity": 4,
  "success": true
}

The endpoint must:

• accept only the agreed SKUU_Network location;
• replace its current quantity with the supplied absolute value;
• return success when the same value is sent again;
• create no extra side effect for an identical repeated write; and
• show the updated network quantity in the next GET /products response.

Virtual SKUU_Network location

Create one virtual inventory location per environment.

• SKUU and the customer agree its numeric location_id.
• Every catalogue variant includes this location.
• Its initial quantity is 0.
• SKUU exclusively owns quantity writes to it.
• Customer physical stock always has priority.
• Network availability is used only when the customer's own sellable stock is
  zero according to the agreed physical-location topology.

Authentication

Body-bearing requests use:

X-SKUU-Signature: sha256=<lowercase hex HMAC-SHA256>

Calculate the digest over the exact raw UTF-8 request body:

HMAC-SHA256(shared_secret, exact_raw_request_body_bytes)

Use a constant-time comparison when verifying signatures. Bearer tokens and
HMAC secrets are different for testing and production and are exchanged only
through an approved secret channel.

Technical requirements

• HTTPS with TLS 1.2 or newer
• UTF-8 JSON request and response bodies
• Content-Type: application/json
• RFC 3339 timestamps with an explicit timezone
• Stable opaque product, variant and event IDs
• Canonical numeric location IDs transmitted as strings
• Absolute non-negative integer stock quantities
• Separate testing and production URLs and credentials
• A stable catalogue snapshot during one pagination traversal

SKUU normally performs a full catalogue reconciliation every 12 hours; the
final cadence is agreed per customer.

Rate limits and retries

Tell SKUU about request limits, maintenance windows or IP allow-list
requirements before testing.

• For SKUU → customer catalogue and inventory requests, SKUU retries network
  failures, 429 and 5xx responses and honours a numeric Retry-After
  header. Other 4xx responses are permanent.
• For customer → SKUU webhooks, retry network failures and 5xx responses
  using the same event. Stop on 200, 401 and 413.

Security best practices

• Give SKUU a token scoped only to the required catalogue and network-inventory
  operations.
• Store tokens and HMAC secrets in a secret manager or protected environment
  configuration.
• Never put credentials in source control, ordinary chat or documentation.
• Verify HMAC before parsing JSON or performing a side effect.
• Keep testing and production credentials fully separate.
• Rotate credentials through a coordinated cutover with both teams.

What SKUU needs from you

• Testing API root and bearer token
• One shared HMAC secret per environment, generated and exchanged through the
  agreed secure channel
• Production API root and credentials later, before production activation
• The complete physical-location ID list
• The assigned SKUU_Network location ID
• Currency and catalogue pagination limits
• IP allow-list or rate-limit requirements
• A technical contact for testing and incident coordination

Environments, testing and activation

Phase 1 is activated in controlled steps:

1. Confirm URLs, locations and credentials for testing.
2. Fetch and validate every catalogue page in read-only mode.
3. Import the accepted catalogue into SKUU's testing environment.
4. Send one signed inventory.updated event and one identical replay.
5. Verify that the first event is accepted and the replay is deduplicated.
6. Test a reversible SKUU_Network write: 0 → 1 → identical 1 → 0.
7. Read the catalogue after every write and confirm physical stock is unchanged.
8. Exchange bilateral Phase-1 sign-off.

Production remains disabled until testing has passed and both teams explicitly
approve the production activation window.

Full reference

Use the API Reference in this portal for the machine-readable contract,
endpoint schemas and response examples.

Questions or platform-specific constraints can be discussed with your SKUU
integration contact before implementation.

Next: orders and fulfilment

After Phase 1 is signed off, continue with the
Phase 2 orders and fulfilment guide. The
customer may implement the contract immediately; traffic remains
activation-gated until bilateral testing is complete.

Next: returns

After completing the Phase 2 implementation, continue with the
Phase 3 returns guide. It is an
implementation-ready preview; return traffic remains disabled until both
teams pass a coordinated TESTING conformance window.