Support tickets

Human support channel for HioBuy warehouse fulfillment integrations. Use when automation cannot resolve package, return, shipment, VAS, billing, or related API issues — attach a related_resource so ops can jump to the warehouse object.

Availability: Sandbox / Gateway MOCK is live. No Zendesk / email / agent console in this phase.
Path remains /v1/support/tickets (not under /v1/fulfillment/*), but the primary use case is fulfillment.

IDs: tkt_* · messages msg_*. Tickets are scoped to the current Application.

Create Support Ticket

Creates a support ticket for fulfillment issues (package, return, shipment, VAS, billing) and related API problems.

Prefer linking warehouse resources:

{
  "category": "PACKAGE",
  "subject": "Package received with missing items",
  "priority": "NORMAL",
  "related_resource": {
    "type": "PACKAGE",
    "id": "sb_pkg_received"
  },
  "message": "The package should contain 10 items, but only 8 items were received."
}

Default status: WAITING_FOR_HIOBUY. The first message is created automatically from message.

Category: API · FULFILLMENT · PACKAGE · RETURN · SHIPMENT · BILLING · ACCOUNT · OTHER
Priority: NORMAL · URGENT
related_resource.type (optional): INBOUND · PACKAGE · RETURN · SHIPMENT · SERVICE_REQUEST

List Support Tickets

Returns support tickets created by the current application.

Query: status, category, priority, related_resource_type, related_resource_id, created_from, created_to, page, page_size.

List items include last_message preview and message_count.

Get Support Ticket

Returns ticket details and conversation history.

Includes messages[] with sender_type (DEVELOPER · HIOBUY · SYSTEM). Attachments are reserved on messages only (IMAGE / VIDEO / DOCUMENT). Internal operator fields are never returned.

Add Ticket Message

Adds a new message to an existing support ticket.

{
  "message": "Here is the supplier order information. Please check again."
}

If status was WAITING_FOR_CUSTOMER, it becomes WAITING_FOR_HIOBUY.
If status is CLOSED → 409 TICKET_NOT_REPLYABLE.
Empty message → 422 MESSAGE_REQUIRED. Max length 10000.

Sandbox fixtures

Reserved webhooks (not delivered)

ticket.message.created · ticket.updated · ticket.resolved · ticket.closed

Example payload shape for ticket.message.created:

{
  "type": "ticket.message.created",
  "data": {
    "ticket_id": "tkt_xxx",
    "message_id": "msg_xxx",
    "sender_type": "HIOBUY",
    "status": "WAITING_FOR_CUSTOMER"
  }
}

Then call Get Support Ticket for the full conversation.

Related

• Packages
• Returns
• Fulfillment overview
• Errors