Skip to main content
This guide walks through the most common integration: take a vendor from creation to a paid invoice. Each step links to the endpoint page with the full parameter list.
All examples use YOUR_API_KEY as a placeholder. See the overview for how to create a key. Your key needs permission for each resource you call, for example Payment with Create for marking invoices as paid.

​
The flow

1

Create the vendor

Create a vendor. Only name is required, but add gstNumber, panNumber and address if you have them.
Save data.vendorId from the response. Check data.vendorState too: ACTIVE means the vendor is ready, and APPROVAL_PENDING means your vendor admins still need to approve it.
If the vendor may already exist, use Vendor Search or Vendor List first. Creation can fail with DUPLICATE_VENDOR_NAME or DUPLICATE_GSTIN.
2

Create the purchase order

Create a purchase order linked to the vendor.
Save data.poId. Three things to know:
  • gstin is your own entity’s GSTIN. Company Entities lists the ones available to you.
  • With state: "ACTIVE", the PO needs a vendor, description, payment terms, and a quantity and rate greater than 0 on every line. If anything is missing, the PO is created as a draft and the response lists what was missing in submitWarnings.
  • THREE_WAY matching needs every line item to match an existing SKU. See Bulk SKU Creation.
3

Upload the invoice

Create an invoice by uploading the file (PDF, JPEG, JPG or PNG, up to 50 MB). This request is multipart/form-data, not JSON.
Save data.id. This is the invoice identifier used everywhere else, including as slug when marking it paid.
4

Wait for processing to finish

The invoice is processed asynchronously, so the upload response returns isReady: false. Poll Invoice Details until data.processingStatus.isReady is true.
Poll every few seconds, not continuously. Stop and investigate if processingStatus.status becomes FAILED, USER_CANCELLED or DISCARDED.
5

Approve the invoice

Only invoices in the APPROVED state can be marked as paid. Approval happens through your approval workflow in the Pazy app. Check the invoice’s state with Invoice Details before the next step.
6

Record the payment

Mark the invoice as paid. The x-idempotency-key header is required on this endpoint.
See Recording payments for partial payments, batches, and how to read per-invoice results.

Recording payments

Partial payments, batches over 100 invoices, and result statuses.

Errors and retries

What each error means and which ones are safe to retry.