Commits an order of stamps for ONE state. This RESERVES the total face value from your stamp-duty wallet — and, when your workspace is prepaid on fees, the gross service fee from your service-fee wallet — failing with 402 (see details.wallet) if either available is short. All stamps in the order must be for the same state — mixed-state payloads are rejected with per-row error code MIXED_STATE (the create fails fast on that check alone; run /validate to see the full per-row picture in one call). Split multi-state work into one order per state, each with its own Idempotency-Key. Call /validate first to catch row errors and see the quote without spending. Rows in states whose live availability switch is off (see GET /states/availability) are rejected with per-row error code STATE_INACTIVE. The Idempotency-Key is mandatory: a retry with the same key returns the original order instead of creating a duplicate. Returns immediately — fulfilment is async (poll the order or subscribe to webhooks).

Webhook payload examples

Every webhook delivery is a signed POST with this outer shape:

{
  "type": "stamp.processing_started",
  "timestamp": "2026-06-16T05:10:01.000Z",
  "data": {}
}

stamp.processing_started data:

{
  "stampId": "019ecebf-36ef-70b3-bb1e-cb4bf6caf566",
  "bulkOrderId": "019ecebf-36ac-7d02-a18e-367ad311e704",
  "clientReference": "po-7-1",
  "partnerBatchId": "019ecebf-4865-79cb-bd12-d3a22a1356bd",
  "acceptedAt": "2026-06-16T05:10:00.000Z"
}

order.processing_started data:

{
  "bulkOrderId": "019ecebf-36ac-7d02-a18e-367ad311e704",
  "partnerBatchId": "019ecebf-4865-79cb-bd12-d3a22a1356bd",
  "acceptedAt": "2026-06-16T05:10:00.000Z",
  "stamps": [
    {
      "stampId": "019ecebf-36ef-70b3-bb1e-cb4bf6caf566",
      "clientReference": "po-7-1"
    }
  ],
  "clientReferences": ["po-7-1"]
}

stamp.verified data:

{
  "stampId": "019ecebf-36ef-70b3-bb1e-cb4bf6caf566",
  "bulkOrderId": "019ecebf-36ac-7d02-a18e-367ad311e704",
  "clientReference": "po-7-1",
  "certificateNumber": "IN-MH12345678901234X",
  "documentUrl": "https://storage.example.com/signed/stamp-paper.png",
  "documentUrlExpiresInSeconds": 900,
  "certificateUrl": "https://esahayak.io/api/v1/stamps/019ecebf-36ef-70b3-bb1e-cb4bf6caf566/certificate"
}

order.fulfilled data:

{
  "bulkOrderId": "019ecebf-36ac-7d02-a18e-367ad311e704",
  "stamps": [
    {
      "stampId": "019ecebf-36ef-70b3-bb1e-cb4bf6caf566",
      "clientReference": "po-7-1"
    }
  ],
  "clientReferences": ["po-7-1"]
}

stamp.cancelled data:

{
  "stampId": "019ecebf-36ef-70b3-bb1e-cb4bf6caf566",
  "bulkOrderId": "019ecebf-36ac-7d02-a18e-367ad311e704",
  "clientReference": "po-7-1"
}

order.cancelled data:

{
  "bulkOrderId": "019ecebf-36ac-7d02-a18e-367ad311e704",
  "cancelledStamps": 1
}

wallet.low_balance data:

{
  "walletId": "019ecebf-72e1-7fac-92be-17d5e02ff5d8",
  "available": 750,
  "threshold": 1000
}

{
  "stamps": [
    {
      "state": "Maharashtra",
      "articleCode": "5",
      "denomination": 500,
      "stampDutyPayer": "Acme Pvt Ltd",
      "firstParty": {
        "name": "Acme Pvt Ltd"
      },
      "secondParty": {
        "name": "Acme Pvt Ltd"
      },
      "purpose": "Leave & licence",
      "district": "HR-GRG",
      "sro": "HR-GRG-SOHNA",
      "costCentre": "CC-MUMBAI",
      "businessUnit": "Legal"
    }
  ]
}

{
  "id": "019ecebf-36ac-7d02-a18e-367ad311e704",
  "reference": "PO-7",
  "state": "Haryana",
  "status": "PLACED",
  "isTest": true,
  "counts": {
    "requested": 1,
    "allocated": 0,
    "generated": 0,
    "verified": 0,
    "delivered": 0,
    "cancelled": 0
  },
  "createdAt": "2026-06-16T04:44:58.311Z",
  "stampCount": 1,
  "stamps": [
    {
      "id": "019ecebf-36ef-70b3-bb1e-cb4bf6caf566",
      "clientReference": "po-7-1"
    }
  ]
}