Partner API

Create deliveries from your own system

Four endpoints: quote a fee, create a delivery, read one back, and poll for changes. Everything is scoped to the store the key belongs to, and every response carries a request_id worth quoting if you need to ask us what happened.

Getting a key

Store portal → API. A key is shown once, at creation. Send it asX-Postman-Api-Key, or as a bearer token if that suits your HTTP client better. Revoking is immediate.

Parcel labels

Postman parcels carry a printed QR label, and the label code is the order number. When you create a delivery through the API we allocate the next unused label from your batch and return it as order_number - print or write that on the parcel. If your batch is exhausted the API answers 409 no_labels_available rather than creating an order nobody can carry.

Creating a delivery

curl -X POST https://postmandelivery.ge/api/v1/orders \
  -H "X-Postman-Api-Key: pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_reference": "SHOP-1042",
    "receiver": {
      "first_name": "Nino",
      "last_name": "Beridze",
      "phone": "555123456"
    },
    "delivery_address": "Vake, Chavchavadze 12, entrance 2",
    "preferred_delivery_date": "2026-08-25",
    "weight_kg": 2,
    "product_price_paid": true,
    "delivery_fee_payer": "store"
  }'

external_reference is your own order id, and it is the idempotency key: repeating a create with the same reference returns the original order with 200 instead of creating a second parcel. That is what makes a retry after a timeout safe.

Quoting a fee

curl -X POST https://postmandelivery.ge/api/v1/rates/quote \
  -H "X-Postman-Api-Key: pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"weight_kg": 3.4}'

Answers from your own agreement, not the public price list. A store with no configured rates gets an error rather than a guess.

Polling for changes

curl "https://postmandelivery.ge/api/v1/orders?updated_after=2026-08-20T09:00:00Z" \
  -H "X-Postman-Api-Key: pk_live_..."
curl "https://postmandelivery.ge/api/v1/orders?cursor=<next_cursor>" \
  -H "X-Postman-Api-Key: pk_live_..."

Orders come back oldest-change-first with a next_cursor. Use updated_after only to choose the initial timestamp. Store the opaque next_cursor and pass it as cursor on every following page. It includes an order-id tie-breaker, so simultaneous updates cannot disappear between pages. A status this deployment does not recognise is reported as unknown rather than omitted, so a new lifecycle state never makes an order silently stop moving in your system.

Limits and errors

120 requests per minute per key. Over that, 429 with a Retry-After header. Errors are { "error": { "code", "message", "fields" }, "request_id" }, where fields names what was wrong with the request.

No developer?

The Zapier integration covers the same ground without code: it can create a delivery when an order arrives in your shop, and tell you or your customer when a parcel moves. Ask us for an invite - it is built on these same endpoints.

Testing

There is no separate sandbox host yet. Test against a real store with a key you revoke afterwards; orders you create can be cancelled from the portal while they are still new.

Partner API - create deliveries from your own system | Postman Delivery