# Coupling API

**Coupling** pairs a Zimarker code with your WMS ID, linking the Zimarker to a [pallet](/key-concepts#pallet). The Coupling API brings that operation to the integration API, so you can allocate Zimarkers and couple them programmatically, with no coupling station, pre-printed stock, or printer-mounted scanner required.

It uses the same `/integration/rest/api/v1/**` surface and the same [authentication](/rest-api/authentication) (`X-AUTH-KEY`) and organization scoping as the rest of the integration API, so there's no new auth to set up.

![Coupling API](/assets/coupling_api.d6294de49132863423544957a41d9e79b5c569a1e6df3c26b6012053cb1be836.9c1bb791.svg)

## Concepts

- **Code**: the unique identifier a Zimarker carries, drawn from the pool of codes Zimark has produced for your organization.
- **Allocation**: handing out the next unassigned code(s), each with a printable image. Allocation is atomic: a code is issued once and never reused.
- **Coupling**: pairing an allocated code with a WMS ID (and any custom fields), linking the Zimarker to the pallet.
- **Bank**: a batch of codes allocated ahead of time and drawn from locally, so printing keeps working offline or over an intermittent connection.


## Building blocks

Three operations plus one webhook, combined to fit your setup.

### Allocate code(s)

Hand out the next unassigned Zimarker code (or a batch), each with a printable image. Allocation is synchronous and low-latency, so it can sit inside a printing loop. Output starts as a PNG (CDN link or inline base64); ZPL is available on request, so printers can render the marker natively without rasterizing an image.

### Couple a code

Pair a code with a WMS ID and custom fields, linking the Zimarker to the pallet. Two modes:

- **Synchronous**: waits and returns the pallet. Use when your next step needs it.
- **Asynchronous**: returns an operation id immediately and completes coupling in the background. Use when you can't wait (a printer that just needs the sticker out).


### Get-and-couple

A convenience wrapper that allocates and couples in one call. The code and image always come back synchronously so you can print right away; the pallet returns now (sync) or via the webhook (async). This is the typical entry point.

### Coupling-events webhook

Subscribe once and receive the outcome of every coupling for your organization, whatever its origin (this API, a coupling station, the Back Office, or a scanner). Each event carries the status, the operation id, and the pallet on success. It's configured like any other trigger; see the [Webhook Reference](/webhooks/webhooks).

## Printing offline with a bank

If printing can't depend on a live call per label, pre-fetch a **bank** of codes with a batch allocation. Your software draws codes locally (issuing markers even while disconnected) and couples them asynchronously once the connection returns. Without a bank, a single dropped connection stalls the line; the bank turns that hard dependency into a soft one. Codes drawn into a bank are treated as consumed.

## Marker info on a pallet

The pallet returned by the integration API includes the marker(s) it carries, so a coupling result is self-describing, with no second call needed to learn which Zimarker a pallet holds.