Skip to main content
Purchase Order Creation API
curl --request POST \
  --url https://api.pazy.io/v1.0/procurement/purchase-order

​
Authentication

All requests require an API key in the request headers. Headers: 
Authorization: Api-Key YOUR_API_KEY
Content-Type: application/json

​
Request

Content-Type: application/json

​
Body Parameters

ParameterTypeRequiredDescription
poNumberstringYesPurchase order number to assign to the document (minimum 1 character)
lineItemsarrayYesList of line items that make up the purchase order (minimum 1 item required)
poTypestringYesIndicates whether the purchase order is for goods or services. Valid values: GOODS, SERVICES
matchingTypestringYesSpecifies whether the purchase order follows a two-way or three-way match process. Valid values: TWO_WAY, THREE_WAY
poDatestringYesPurchase order date in ISO-8601 format (YYYY-MM-DD)
vendorIdstringNoIdentifier of the vendor that should be linked to the purchase order (minimum 1 character)
gstinstringNoGSTIN of the organization (minimum 1 character)
descriptionstringNoShort description for the purchase order (1-255 characters)
currencystringNoISO 4217 currency code that will be used for the purchase order amounts (3 characters, e.g., INR, USD)
paymentTermsstringNoFree form outline of the agreed payment terms (minimum 1 character)
deliveryDatestringNoRequested delivery date for the purchase order in ISO-8601 format (YYYY-MM-DD)
termsAndConditionsstringNoTerms and conditions that must be displayed on the purchase order (minimum 1 character)
additionalNotesstringNoAdditional notes to append to the purchase order document (minimum 1 character)

​
Line Items Object

Each item in the lineItems array must contain the following fields:
ParameterTypeRequiredDescription
quantitynumberYesQuantity requested for the line item
ratenumberYesUnit rate to be applied to the line item
identifierstringYesIdentifier or SKU that uniquely represents the line item (minimum 1 character)

​
PO Type Values

The poType field accepts the following values:
  • GOODS: Purchase order for physical goods or products
  • SERVICES: Purchase order for services

​
Matching Type Values

The matchingType field accepts the following values:
  • TWO_WAY: Purchase order matching based on purchase order and invoice (2-way match)
  • THREE_WAY: Purchase order matching based on purchase order, invoice, and goods receipt note (3-way match)

​
Code Examples

curl -X POST https://api.pazy.io/v1.0/procurement/purchase-order \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "poNumber": "PO-2024-001",
    "poDate": "2024-01-15",
    "poType": "GOODS",
    "matchingType": "THREE_WAY",
    "vendorId": "vaz0eCPVFvCU2X1gW2Z",
    "gstin": "29ABCDE1234F1Z5",
    "description": "Office supplies purchase order",
    "currency": "INR",
    "paymentTerms": "Net 30 days",
    "deliveryDate": "2024-02-15",
    "termsAndConditions": "All goods must be delivered in original packaging",
    "additionalNotes": "Please deliver during business hours",
    "lineItems": [
      {
        "identifier": "SKU-001",
        "quantity": 100,
        "rate": 50.00
      },
      {
        "identifier": "SKU-002",
        "quantity": 50,
        "rate": 75.50
      }
    ]
  }'

​
Success Response

HTTP Status: 200 OK Response Fields:
FieldTypeDescription
okbooleanIndicates whether the request was successful
dataobjectContains the purchase order creation response data
data.idstringUnique identifier for the purchase order
data.poNumberstringPurchase order number assigned to the document
data.statusstringCurrent status of the purchase order

​
Response Example

{
  "ok": true,
  "data": {
    "id": "po_identifier",
    "poNumber": "PO-2024-001",
    "status": "DRAFT"
  }
}

​
Error Responses

​
Missing Required Fields

HTTP Status: 400 Bad Request 
{
  "ok": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELD",
    "message": "poNumber is required"
  }
}

​
Invalid Procurement Type

HTTP Status: 400 Bad Request 
{
  "ok": false,
  "error": {
    "code": "INVALID_PROCUREMENT_TYPE",
    "message": "Invalid procurement type"
  }
}

​
Invalid Matching Type

HTTP Status: 400 Bad Request 
{
  "ok": false,
  "error": {
    "code": "INVALID_MATCHING_TYPE",
    "message": "Invalid matching type"
  }
}

​
Invalid Date

HTTP Status: 400 Bad Request 
{
  "ok": false,
  "error": {
    "code": "INVALID_DATE",
    "message": "Invalid date"
  }
}

​
Invalid Expected Delivery Date

HTTP Status: 400 Bad Request 
{
  "ok": false,
  "error": {
    "code": "INVALID_EXPECTED_DELIVERY_DATE",
    "message": "Invalid expected delivery date"
  }
}

​
Invalid Line Items

HTTP Status: 400 Bad Request 
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed: /body/lineItems: must NOT have fewer than 1 items"
  }
}
HTTP Status: 400 Bad Request 
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed: /body/lineItems/0/quantity: must be number"
  }
}
HTTP Status: 400 Bad Request 
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed: /body/lineItems/0/identifier: must NOT have fewer than 1 characters"
  }
}

​
Invalid Currency

HTTP Status: 400 Bad Request 
{
  "ok": false,
  "error": {
    "code": "INVALID_CURRENCY",
    "message": "Invalid currency Only INR is supported at the moment"
  }
}

​
Invalid Description Length

HTTP Status: 400 Bad Request 
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed: /body/description: must NOT have more than 255 characters"
  }
}

​
Vendor Not Found

HTTP Status: 404 Not Found 
{
  "ok": false,
  "error": {
    "code": "VENDOR_NOT_FOUND",
    "message": "Vendor not found"
  }
}

​
Invalid GSTIN

HTTP Status: 400 Bad Request 
{
  "ok": false,
  "error": {
    "code": "INVALID_GSTIN",
    "message": "Invalid GSTIN"
  }
}

​
Invalid State

HTTP Status: 400 Bad Request 
{
  "ok": false,
  "error": {
    "code": "INVALID_STATE",
    "message": "Invalid state"
  }
}

​
Authentication Errors

HTTP Status: 401 Unauthorized 
{
  "ok": false,
  "error": {
    "code": "MISSING_CREDENTIALS",
    "message": "Missing Credentials"
  }
}

{
  "ok": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API Key"
  }
}

​
Permission Errors

HTTP Status: 403 Forbidden 
{
  "ok": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Permission check failed - PERMISSION_CHECK_FAILED"
  }
}

​
Purchase Order Creation Errors

HTTP Status: 500 Internal Server Error 
{
  "ok": false,
  "error": {
    "code": "PROCUREMENT_CREATION_FAILED",
    "message": "Error creating procurement"
  }
}

​
Internal Error

HTTP Status: 500 Internal Server Error 
{
  "ok": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal error"
  }
}

​
Best Practices

​
Purchase Order Creation

  • Ensure all required fields (poNumber, lineItems, poType, matchingType, poDate) are provided
  • Use ISO 8601 date format (YYYY-MM-DD) for all date fields
  • Provide at least one line item with valid quantity, rate, and identifier values
  • Use INR for the currency field (only INR is currently supported)
  • Choose the appropriate matchingType based on your procurement process:
    • Use TWO_WAY for simpler matching between PO and invoice
    • Use THREE_WAY when goods receipt verification is required
  • Link the purchase order to a vendor using vendorId if available
  • Include gstin for tax compliance in Indian markets
  • Keep description concise (max 255 characters) for better readability
  • Use termsAndConditions to specify important contractual terms
  • Add additionalNotes for delivery instructions or special requirements

​
Line Items

  • Ensure each line item has a unique identifier
  • Use positive numbers for quantity and rate