Custom channel API

A custom channel lets your own webshop, ERP or warehouse system send orders straight into Zippendo, when there is no ready-made connection for it. This page covers every control on the create window and the channel settings, and how a developer sends an order. The click-through journey is Connect order channels. The full payload reference is Custom channels. Click Order channels in the sidebar, then the Catalog tab. The Custom channel card reads Connect your own webshop or ERP system. Its button is Create channel.

Order channels catalog with the Custom channel card and the Create channel button — The Custom channel card in the catalog

Create the channel

Click Create channel. The Create custom channel window opens: An order channel for your own webshop or ERP system.

Create custom channel window with Channel name filled in as My webshop, Create channel and Cancel — Create custom channel: enter a Channel name

Field	Required	What to enter
Channel name	Yes	A name you recognize, for example “My webshop”. Create channel stays inactive until you enter one.
Brand	No	Only shown when your organization has brands. Orders from this channel belong to this brand.

Click Create channel (it shows Creating…). You see Order channel created, and Zippendo opens the new channel’s settings. If you see Couldn’t create the order channel, try again. Cancel closes the window.

Order ingestion

The settings page is headed by the channel name and Your own integration: send orders to the ingest URL, or use the API and SDKs. View documentation opens the Custom channels reference.

The Order ingestion card: Your system sends signed orders to the ingest URL below. Sign the raw body of every request with HMAC-SHA256, using the signing secret.

Control	What it does
Ingest URL	The address your system sends orders to, in the form `https://api.zippendo.com/webhooks/order-channels/<channel id>`. Copy it from your own channel. Copy shows Copied to clipboard., or Couldn’t copy to clipboard.
Generate secret	Creates the signing secret. Shows Generating…, then Signing secret generated. or Couldn’t generate the signing secret.
Replace secret	Replaces an existing secret. Zippendo asks you to confirm: your system is rejected until it signs with the new secret.
Revoke	Turns the secret off. Every order your system sends is rejected until you generate a new secret. Shows Signing secret revoked. or Couldn’t revoke the signing secret.
Active signing secret created	Followed by the date and time the current secret was created.

The channel only accepts orders once a signing secret exists. There is no separate switch to turn ingestion on. After Generate secret or Replace secret, the secret is shown once:

Order ingestion with the one-time signing secret, Copy, Revoke and Replace secret — Copy the signing secret now. It is only shown once

Copy the secret now. It is only shown once. If you replace it later, the current secret stops working at once. The secret starts with zwhs_. Store it in your system’s configuration.

Send an order

POST to the Ingest URL with two headers:

Header	Value
`X-Zippendo-Topic`	`order.created`, `order.updated`, `order.cancelled` or `ping`
`X-Zippendo-Signature`	HMAC-SHA256 of the raw request body, hex-encoded, keyed with the signing secret

order.created and order.updated both create or update the order by its externalId. The order.cancelled body is { "externalId": "…" }. ping returns 200 { "received": true } without changing anything.

import crypto from "node:crypto"

const body = JSON.stringify(order)
const signature = crypto.createHmac("sha256", process.env.ZIPPENDO_WEBHOOK_SECRET)
  .update(body)
  .digest("hex")

await fetch(webhookUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Zippendo-Topic": "order.created",
    "X-Zippendo-Signature": signature
  },
  body
})

Required payload fields: externalId, orderNumber and orderLines (at least one line with name and quantity). Optional: customerName, customerEmail, shippingAddress, subtotalAmount, totalAmount, currency, notes, shippingMethodTitle and serviceCode. Full field table: Custom channels.

Status	Meaning
`200`	Accepted and processed
`400`	Missing or unknown topic, a payload that failed validation, or Channel enabled is off
`401`	Signature check failed: wrong secret, missing header, or no secret generated yet
`404`	Unknown channel
`429`	Too many orders at once. Retry after the `Retry-After` delay
`5xx`	Processing failed. Retry: sending the same order again is safe

Prefer request and response? Create orders with POST /orgs/{orgId}/orders, passing orderChannelId, and an API token. A second order with the same externalId on the same channel returns 409 ORDER_EXISTS. To get tracking numbers and status changes back, subscribe to your organization’s webhooks (shipment.dispatched, tracking.updated). A custom channel has no tracking callback of its own, and no shipping method mapping screen. An order you send appears under Orders. Its status can be Error when Zippendo imported the order but could not create a shipment that is ready to send, for example because no shipping rule matched or the address is incomplete. The order still belongs to the channel.

Orders list with an order that arrived through a custom channel — An order sent by your system on the Orders page

Operations

Setting	Saved	What it does
Channel enabled	Straight away	Turns the channel on or off. When it is off, Zippendo rejects every order sent to this channel.
Send shipments automatically	With Save changes	Sends the shipment to the carrier automatically when an incoming order matches a shipping rule. Off by default.
Brand	Straight away	Orders from this channel belong to this brand. The list only appears when your organization has brands.
Default sender address	With Save changes	The sender for shipments when no shipping rule matches the order. With none saved yet, the list says No addresses yet.
Last order received	Read only	When the channel last received an order, or Never.

Save changes (Saving…) saves Send shipments automatically and Default sender address. You see Order channel updated, or Couldn’t update the order channel.

Turn a channel off

Turn Channel enabled off. On the Connected tab, the channel’s row in the Custom channel card then says Disabled. Custom channels always stay on the Connected tab, and never become leftover channels.

Order channels page with a custom channel marked Disabled — A custom channel that is turned off

Leftover Shopify or WooCommerce channels, marked No active connection and Disconnected, are something else. See Order channel settings.

Delete

Under Danger zone, find Delete channel: Delete this custom channel. Your integration can no longer send orders to it.

Click Delete and confirm: Delete this custom channel? Its ingest URL stops accepting orders immediately. You see Order channel deleted, or Couldn’t delete the order channel.

Connect order channels

Create the channel from the catalog, then open Orders.

Custom channels reference

Full payload, cancel, ping and REST examples.

Order channel settings

The Order channels page, brands and leftover channels.

Create an API token

A token for POST /orgs/{orgId}/orders instead of signed pushes.

Overview

Shipments

Orders & channels

Carriers

Connect a carrier

Connect an integration

Printing

Automation

Account

Search & dashboard

API & events

Custom channel API

Create the channel

Order ingestion

Send an order

Operations

Turn a channel off

Delete

Connect order channels

Custom channels reference

Order channel settings

Create an API token

​Create the channel

​Order ingestion

​Send an order

​Operations

​Turn a channel off

​Delete

​Related

Connect order channels

Custom channels reference

Order channel settings

Create an API token

Create the channel

Order ingestion

Send an order

Operations

Turn a channel off

Delete

Related