Hype Custom Integration Developer Guide

Companion reference: hype-custom-integration.mdPostman docs: https://documenter.getpostman.com/view/52109283/2sBXc8oNnL

1. Purpose

This guide explains how to build a production-ready integration against the Hype Custom adapter in Hype Exchange Service (HES).

Use this document for:

understanding the end-to-end sync model
implementing task polling and result reporting correctly
pushing order data into HES safely
handling the initial sync pipeline and dependency ordering
troubleshooting mapping and queue issues

Use the companion API reference for:

exact entity schemas
full example payloads
endpoint-by-endpoint request and response examples

2. Mental Model

HES is middleware between a Hype POS account and your platform account.

There are two integration directions:

Hype -> Your platform HES creates tasks. Your platform polls /tasks/hype-custom/{entity}, processes them, and reports the result with PUT.
Your platform -> Hype Your platform pushes data into HES through /webhook/hype-custom/{entity}. HES maps identifiers and delivers the work to the Hype side asynchronously.

Operationally, this means your integration must implement both:

a task consumer
a webhook producer

Delivery to Hype is asynchronous. A successful webhook response means HES accepted your request. Confirm that the order appears in Hype, and keep polling your orderRequests tasks for status changes.

3. Ownership And Data Flow

Treat the entities as follows:

Entity	Primary flow	Notes
Categories	Hype -> Your platform	Required before item sync can map `categoryId`
Saloons	Hype -> Your platform	Required before table sync
Tables	Hype -> Your platform	`saloonId` must already be mapped
Items	Hype -> Your platform	Required before supplements and order item references
Supplements	Hype -> Your platform	Menu-scoped and item-dependent
Order Requests	Bidirectional	You create/update via webhook, Hype sends status updates back via tasks
Order Delivery Channels	Initial sync	Used for ID mapping
Order Payment Types	Initial sync	Used for ID mapping
Order Request Status	Initial sync	Used for ID mapping

In day-to-day operation:

menu structure and venue layout are Hype-owned
order creation is external-platform-owned
order status changes eventually come back from Hype through orderRequests tasks

4. Base Contract

Authentication

All requests require:

http

Authorization: Bearer <your_api_token>
Content-Type: application/json
Accept: application/json

Environments

Environment	Base URL
Development	`https://es.dev.hype-software.com`
Production	`https://es.hype-software.com`

Rate Limits

1000 requests per minute per token for /tasks/hype-custom/* and /webhook/hype-custom/*
60 requests per minute per token for /api/hype-custom/* (integrations and queue jobs)
429 means you must back off and retry later; the response has no Retry-After header, so use your own backoff

5. What Your Platform Must Implement

At minimum, a reliable integration needs these pieces:

A polling worker for /tasks/hype-custom/*
Entity-specific handlers for POST, PUT, and GET task types
A reporter that batches task results back to PUT /tasks/hype-custom/{entity}
A webhook client for POST and PUT /webhook/hype-custom/orderRequests
Storage for your own entity IDs and enough state to handle retries idempotently
Monitoring around integration status and queued failures

Recommended behavior:

make all handlers idempotent
log every HES task ID and your resulting platform ID
treat the HES task id as a unit-of-work identifier, not as your entity ID
do not acknowledge success before your own write is committed

6. Endpoint Map

Task Endpoints

Use these to receive work from HES:

text

GET /tasks/hype-custom/{entity}
PUT /tasks/hype-custom/{entity}

Supported task entities:

categories
saloons
tables
items
supplements
orderRequests
orderDeliveryChannels
orderPaymentTypes
orderRequestStatus

Webhook Endpoints

Use these to push work into HES:

text

POST /webhook/hype-custom/{entity}
PUT  /webhook/hype-custom/{entity}

Supported public webhook entities:

orderRequests
orderDeliveryChannels
orderPaymentTypes
orderRequestStatus

Operational Endpoints

Use these for visibility and support tooling:

text

GET    /api/hype-custom/integrations
GET    /api/hype-custom/integrations/{integrationId}
GET    /api/hype-custom/integrations/{integrationId}/queue-jobs
DELETE /api/hype-custom/integrations/{integrationId}/queue-jobs/{jobId?}

7. Implementing The Task Consumer

Task Polling Rules

For each entity endpoint, GET /tasks/hype-custom/{entity} returns an array of pending tasks:

json

[
  {
    "id": "9a101f76-f1c8-47c2-a19f-259150bb62e0",
    "request": {
      "name": "Пици",
      "order": 2
    },
    "status": 0,
    "meta": {
      "source_account": {
        "id": "a0fa1fe5-feda-4753-9f23-691343e3828c",
        "name": "Local",
        "platform_id": "4d410b0e-ee37-497e-8362-478a383d68ee",
        "platform_name": "Hype Server",
        "platform_key": "hype-server"
      }
    },
    "type": "POST"
  }
]

Important rules:

id is the HES task identifier you must report back as entity_task_id
type tells you what operation to execute in your system
status is always 0 when the task is fetched
an empty array means "no work", not an error

Task Type Semantics

Type	Meaning	Your responsibility
`POST`	Create entity in your system	Create it and return your new platform ID
`PUT`	Update existing entity in your system	Update it and return the current platform representation
`GET`	Return all entities of that type from your system	Return the full collection in `response`

HES does not currently send DELETE tasks. A record deleted in Hype arrives as a PUT task with its fields reset to empty or zero values (for example "name": ""); check for this case before applying a PUT.

Reporting Results

Send task results back with:

text

PUT /tasks/hype-custom/{entity}

Request body:

json

[
  {
    "entity_task_id": "9a101f76-f1c8-47c2-a19f-259150bb62e0",
    "status": 201,
    "response": {
      "id": "your-platform-id"
    }
  }
]

Critical behavior:

always send the inner status field
if you omit status, HES currently treats it as 500
for successful non-GET tasks, return a non-null response with your entity id whenever your platform created or matched a real entity
for successful GET tasks, return response as an array of your platform records for that entity type; each record should include its stable id
a 2xx status without a usable response can leave HES without the IDs needed for automatic linking or the values needed for manual bootstrap mapping
exception: saloon/table tasks may be acknowledged with response: {} when your platform does not model venue floor plans; this advances sync without creating saloon/table mappings
you can batch multiple task results in one request
the HTTP response from HES is 204 No Content; your actual processing outcome is carried in each item's status

Recommended Worker Shape

async function syncEntity(entity: string) {
  const tasks = await hes.get(`/tasks/hype-custom/${entity}`)
  if (tasks.length === 0) return

  const results = []

  for (const task of tasks) {
    try {
      const response = await processTask(task)

      results.push({
        entity_task_id: task.id,
        status: response.created ? 201 : 200,
        response: response.payload,
      })
    } catch (error) {
      results.push({
        entity_task_id: task.id,
        status: 422,
        response: { message: String(error) },
      })
    }
  }

  await hes.put(`/tasks/hype-custom/${entity}`, results)
}

Polling Strategy

During initial sync, poll all task endpoints continuously. The pipeline is sequential, so only one entity type is usually active at a time, but polling them all avoids waiting for a manual switch.

After the integration becomes active, continue polling at least:

categories
saloons
tables
items
supplements
orderRequests

Tasks for the bootstrap endpoints appear only during initial sync, because Hype doesn't send changes to delivery channels, payment types, or order statuses:

orderDeliveryChannels
orderPaymentTypes
orderRequestStatus

8. Implementing The Webhook Producer

Main Day-To-Day Webhook

The primary webhook you will use in steady state is:

text

POST /webhook/hype-custom/orderRequests
PUT  /webhook/hype-custom/orderRequests

Use it when:

a customer places a new order on your platform
an order must be updated while still editable in Hype's order-request flow
you need to push a later order status update

Operational note:

a successful webhook call returns 204 No Content when HES accepts the payload, not when the Hype POS has already applied it
if you need downstream confirmation, monitor the integration state, queue jobs, or the later orderRequests tasks coming back from Hype

Important Order Request Rules

do not send an order until the integration is fully synced and required mappings exist
tableId is optional, but if present it must already be mapped through the standalone tables sync
order item id values must reference previously synced item mappings
order item supplement id values must reference previously synced supplement mappings
tip is optional, gross, amount-only, defaults to 0, and should be included in total and paid paymentTypes[].amount
paymentTypes[].status should be completed or pending; other values are treated as unpaid by Hype Server
payment statuses are applied when Hype attaches (accepts) the order; until then, an update webhook replaces paymentTypes, and payment-status changes sent after acceptance are ignored
once the order is accepted/attached in Hype, updates become effectively status-driven; do not rely on late full-snapshot mutation

Bootstrap Webhooks

These endpoints exist mainly for initial setup:

POST / PUT /webhook/hype-custom/orderDeliveryChannels
POST / PUT /webhook/hype-custom/orderPaymentTypes
POST / PUT /webhook/hype-custom/orderRequestStatus

Use them to establish mapping context, not as the main operational workflow.

9. Initial Sync Pipeline

The initial sync is a strict sequence. HES advances only after the current step's source response has been processed and every task produced by that step has been reported successfully.

Pipeline Order

Step	Entity	Purpose
1	Categories	Hype -> You
2	Saloons	Hype -> You
3	Tables	Hype -> You
4	Items	Hype -> You
5	Supplements	Hype -> You
6	Order Request Statuses	Collect Hype values for manual mapping
7	Order Delivery Channels	Collect Hype values for manual mapping
8	Order Payment Types	Collect Hype values for manual mapping
9	Order Request Statuses	Collect your values through a `GET` task for manual mapping
10	Order Delivery Channels	Collect your values through a `GET` task for manual mapping
11	Order Payment Types	Collect your values through a `GET` task for manual mapping

The table describes the standard 11-step configuration. The integration template can narrow the enabled entities and change the total. Steps 6-11 collect both sides' values; they do not automatically pair them.

Why The Order Matters

items depend on categories
tables depend on saloons
supplements depend on items
orders depend on item, supplement, status, payment, delivery-channel, and optionally table mappings

Pipeline Behavior You Must Expect

the pipeline is single-threaded and blocking
a single step can produce multiple sync tasks; all of them must finish before the next step starts
there is no per-step timeout; it will wait indefinitely for your polling/reporting
if you stop polling, the integration stays in syncing
if a step fails, previous successful mappings remain; there is no rollback

Go-Live Rule

Treat the integration as ready for order traffic only when:

GET /api/hype-custom/integrations/{id}?include=pipeline shows the integration as active
the pipeline status is synced or no active pipeline remains
your side has finished the bootstrap GET tasks for statuses, channels, and payment types
after activation, someone has opened the integration in the Hype Server back-office UI, paired the corresponding order statuses, delivery channels, and payment types, and saved those manual mappings
a test order reaches Hype and its status update returns to your platform

active confirms pipeline completion. It does not confirm that the manual mappings have been saved. Cover every status, channel, and payment type that will be used, and review the mappings when new values are introduced.

10. Mapping And Dependency Notes

ID Mapping Is The Core Contract

HES must be able to translate IDs between Hype and your platform. For automatically synchronized entities, task results establish that translation. For order statuses, delivery channels, and payment types, bootstrap responses supply the available values; a person pairs those values in the Hype Server back-office UI after activation.

Because of that:

always return your platform id on successful non-GET task results
keep your IDs stable
do not change entity IDs after initial sync
do not send orders that reference entities that were never mapped

Non-Obvious Dependency Rules

tableId on an order is optional, but if sent it must already exist in the table mapping
if your platform does not use saloons/tables, acknowledge those tasks with response: {} and omit tableId from all order webhooks
supplement mappings come only from the standalone supplements sync; item tasks carry no supplement data
Hype refreshes the mapped status in orderRequests tasks. Other returned fields can be retained from earlier stored order data; process these tasks as status notifications.

11. Failure Handling And Troubleshooting

Common HTTP Errors

Status	Meaning
`401`	Missing or invalid bearer token
`404`	Wrong endpoint, unknown task entity, or unknown `entity_task_id`
`429`	Rate limit exceeded
`500`	Internal HES error; also a queue-jobs request for an integration outside your account, or a webhook `POST` for an unsupported entity

HES never returns 422 for tasks or webhooks. Webhooks accept any JSON body with 204 and fail later during asynchronous processing; check queue jobs for the error. A webhook PUT for an unsupported entity returns 200 with {"error": "Resource can't be found"}, so treat any webhook response other than 204 as a failure.

Common Integration Failures

Symptom	Likely cause	What to check
Order webhook accepted but order does not appear in Hype yet	Delivery is still pending or has failed	Inspect integration status and queue errors; contact Hype support if delivery remains stalled
Queue shows missing linked entity errors	Referenced entity was not mapped yet	Check items, tables, supplements, statuses, payment types, or delivery channels
Tables fail to sync	Saloon mapping missing	Verify saloons finished first
Supplements fail to sync	Item mapping missing	Verify items finished first
Task reported as success but later mapping is missing	You returned no `response.id` or omitted `status`	Ensure `2xx` + populated response body, except intentional saloon/table no-op ACKs

Queue Behavior To Expect

When HES hits a missing dependency during ongoing sync, it can pause the integration queue and retry later. In practice this is often a short pause-and-retry loop of about 60 seconds. That is usually a mapping problem, not a transport problem.

Operational Checks

Use these endpoints when diagnosing issues:

GET /api/hype-custom/integrations
GET /api/hype-custom/integrations/{integrationId}
GET /api/hype-custom/integrations/{integrationId}/queue-jobs

Look for:

integration status: inactive, syncing, active, aborted, error
pipeline status: pending, processing, synced, failed, stopped
queue jobs stuck on a referenced entity that was never mapped

12. Implementation Checklist

store one HES bearer token per integration/account
implement polling workers for all documented task entities
make task handlers idempotent
always report task results with entity_task_id, status, and response
include your platform id in successful non-GET task responses whenever your platform created or matched a real entity
implement bootstrap GET task handling for statuses, delivery channels, and payment types, returning arrays with stable IDs
after the integration becomes active, complete and save manual status, delivery-channel, and payment-type mappings in the Hype Server back-office UI before sending orders
ensure every order references already-mapped items, supplements, and statuses
log HES task IDs and your resulting entity IDs for auditability
monitor integration and queue-job endpoints during onboarding

API reference: hype-custom-integration.md
Postman collection: https://documenter.getpostman.com/view/52109283/2sBXc8oNnL

Hype Custom Integration Developer Guide ​

1. Purpose ​

2. Mental Model ​

3. Ownership And Data Flow ​

4. Base Contract ​

Authentication ​

Environments ​

Rate Limits ​

5. What Your Platform Must Implement ​

6. Endpoint Map ​

Task Endpoints ​

Webhook Endpoints ​

Operational Endpoints ​

7. Implementing The Task Consumer ​

Task Polling Rules ​

Task Type Semantics ​

Reporting Results ​

Recommended Worker Shape ​

Polling Strategy ​

8. Implementing The Webhook Producer ​

Main Day-To-Day Webhook ​

Important Order Request Rules ​

Bootstrap Webhooks ​

9. Initial Sync Pipeline ​

Pipeline Order ​

Why The Order Matters ​

Pipeline Behavior You Must Expect ​

Go-Live Rule ​

10. Mapping And Dependency Notes ​

ID Mapping Is The Core Contract ​

Non-Obvious Dependency Rules ​

11. Failure Handling And Troubleshooting ​

Common HTTP Errors ​

Common Integration Failures ​

Queue Behavior To Expect ​

Operational Checks ​

12. Implementation Checklist ​

13. Related Documents ​

Hype Custom Integration Developer Guide

1. Purpose

2. Mental Model

3. Ownership And Data Flow

4. Base Contract

Authentication

Environments

Rate Limits

5. What Your Platform Must Implement

6. Endpoint Map

Task Endpoints

Webhook Endpoints

Operational Endpoints

7. Implementing The Task Consumer

Task Polling Rules

Task Type Semantics

Reporting Results

Recommended Worker Shape

Polling Strategy

8. Implementing The Webhook Producer

Main Day-To-Day Webhook

Important Order Request Rules

Bootstrap Webhooks

9. Initial Sync Pipeline

Pipeline Order

Why The Order Matters

Pipeline Behavior You Must Expect

Go-Live Rule

10. Mapping And Dependency Notes

ID Mapping Is The Core Contract

Non-Obvious Dependency Rules

11. Failure Handling And Troubleshooting

Common HTTP Errors

Common Integration Failures

Queue Behavior To Expect

Operational Checks

12. Implementation Checklist

13. Related Documents