Application API

For partner applications: browse merchants and products, hand customers a checkout link, and follow the orders it creates.

Resources

Order webhooks

If your application has a webhook_url configured, Gini POSTs to it when an order created through your application changes.

Events

Event	Fired when
order.created	An order tagged with your application is created.
order.status_updated	Its `status` changes — any transition.

Payload

order.status_updated

{
    "event": "order.status_updated",
    "previous_status": "accepted",
    "external_id": "ORD-9001",
    "cart_id": null,
    "order": {
        "id": 265552,
        "status": "on_the_way"
    },
    "sent_at": "1785500000"
}

order has the same shape as GET /orders/{id} — shortened above.

Field	On	Notes
previous_status	`order.status_updated`	The status before this transition.
external_id	every event	Your reference, as sent on the token. `null` when the token carried none, or the order did not come from a token.
cart_id	`order.created` only	The id returned with the token. `null` on `order.status_updated`.
sent_at	every event	Unix seconds, as a string. The same value as `X-TIMESTAMP`.

Notes

Record external_id → order.id when order.created arrives, then match later events on order.id.

Verifying

Headers: X-TIMESTAMP (Unix seconds) and

Signature

X-SIGNATURE = hex( HMAC_SHA256(app_secret, raw_body + timestamp) )

Verify with a constant-time comparison against the raw body, and reject stale timestamps — the same way we verify your requests.

Delivery

Notes

Immediate first attempt. We try to deliver in the same request that changed the order, waiting up to 3 seconds. Respond fast — acknowledge, then process asynchronously.
Then queued retries. If that attempt fails or times out, delivery moves to a queue with a 15-second timeout per attempt, up to 5 attempts, backing off 1 min, 5 min, 15 min, 30 min, 1 h.
Any 2xx marks it delivered.
Deliveries can arrive out of order under retry — use previous_status and sent_at to detect a stale event. Your endpoint must be idempotent: a retry after a slow 2xx can deliver the same event twice.

Previous States and districts Next MCP server