Pazy Documentation

Purchase Order Creation API

curl --request POST \
  --url https://api.pazy.io/v1.0/procurement/purchase-order

const options = {method: 'POST'};

fetch('https://api.pazy.io/v1.0/procurement/purchase-order', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pazy.io/v1.0/procurement/purchase-order",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pazy.io/v1.0/procurement/purchase-order"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.pazy.io/v1.0/procurement/purchase-order")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

Purchase Order Creation API

curl --request POST \
  --url https://api.pazy.io/v1.0/procurement/purchase-order

const options = {method: 'POST'};

fetch('https://api.pazy.io/v1.0/procurement/purchase-order', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pazy.io/v1.0/procurement/purchase-order",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pazy.io/v1.0/procurement/purchase-order"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.pazy.io/v1.0/procurement/purchase-order")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

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

Parameter	Type	Required	Description
`poNumber`	string	Yes	Purchase order number to assign to the document (minimum 1 character)
`lineItems`	array	Yes	List of line items that make up the purchase order (minimum 1 item required)
`poType`	string	Yes	Indicates whether the purchase order is for goods or services. Valid values: `GOODS`, `SERVICES`
`matchingType`	string	Yes	Specifies whether the purchase order follows a two-way or three-way match process. Valid values: `TWO_WAY`, `THREE_WAY`
`poDate`	string	Yes	Purchase order date in ISO-8601 format (YYYY-MM-DD)
`vendorId`	string	No	Identifier of the vendor that should be linked to the purchase order (minimum 1 character)
`gstin`	string	Yes	Entity GSTIN of the organization 15 character length (`{State Code}{PAN}{Entity Number}{Z}{Checksum}`)
`description`	string	No	Short description for the purchase order (1-255 characters)
`currency`	string	No	ISO 4217 currency code that will be used for the purchase order amounts (3 characters, e.g., INR, USD)
`paymentTerms`	string	No	Free form outline of the agreed payment terms (minimum 1 character)
`deliveryDate`	string	No	Requested delivery date for the purchase order in ISO-8601 format (YYYY-MM-DD)
`termsAndConditions`	string	No	Terms and conditions that must be displayed on the purchase order (minimum 1 character)
`additionalNotes`	string	No	Additional notes to append to the purchase order document (minimum 1 character)
`state`	string	No	Target state for the PO: `DRAFTED` or `ACTIVE`. When `ACTIVE` is requested the API validates all required fields. If they are all present the PO is created in active state; if anything is missing it falls back to `DRAFTED` and the response includes `submitWarnings`. Omitting this field defaults to `DRAFTED`.
`tags`	object	No	PO-level tags (flex fields). Map of tag slug to a `{ value }` object. See Tags below.

Fields Required for Active State (when `state: "ACTIVE"`)

When state: "ACTIVE" is passed, the following fields must be present in addition to the schema-required fields for the PO to be activated:

Field	Level	Requirement
`vendorId`	PO	Vendor must be linked
`description`	PO	Description must be non-empty
`paymentTerms`	PO	Payment terms must be non-empty
`quantity`	Each line item	Must be greater than 0
`rate`	Each line item	Must be greater than 0

If any of the above are missing, the PO is still created in draft state and submitWarnings in the response identifies exactly which fields were absent.

Line Items Object

Each item in the lineItems array must contain the following fields:

Parameter	Type	Required	Description
`quantity`	number	Yes	Quantity requested for the line item
`rate`	number	Yes	Unit rate to be applied to the line item
`identifier`	string	Yes	Free-text label for the line item (minimum 1 character)
`skuCode`	string	Required for `THREE_WAY`	Item code of an existing SKU in your inventory. Used to link this line item to a SKU. Takes priority over `skuName` when both are provided
`skuName`	string	Required for `THREE_WAY`	Name of an existing SKU in your inventory. Used to link this line item to a SKU when `skuCode` is not provided
`tags`	object	No	Line-item-level tags. Map of tag slug to a `{ value }` object. See Tags below.

SKU matching (THREE_WAY): When matchingType is THREE_WAY, every line item must include either skuCode or skuName, and it must resolve to an existing SKU in your inventory. If any line item is missing both fields, or if the provided code/name cannot be matched, the request is rejected with a 400 error and the purchase order is not created. See Bulk SKU Creation to pre-populate your inventory.

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)

Tag type	What to send as `value`
`DROPDOWN`	The tag value id (number) of an existing option
`VARCHAR`	Free text (string)
`DATETIME`	A date string in `YYYY-MM-DD` format

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": "<vendorId>",
    "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",
    "state": "ACTIVE",
    "tags": {
      "cost-center": { "value": 42 },
      "project-code": { "value": "PRJ-2024" }
    },
    "lineItems": [
      {
        "identifier": "SKU-001",
        "quantity": 100,
        "rate": 50.00,
        "tags": {
          "budget-line": { "value": "Stationery" }
        }
      },
      {
        "identifier": "SKU-002",
        "quantity": 50,
        "rate": 75.50
      }
    ]
  }'

const response = await fetch('https://api.pazy.io/v1.0/procurement/purchase-order', {
  method: 'POST',
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    poNumber: 'PO-2024-001',
    poDate: '2024-01-15',
    poType: 'GOODS',
    matchingType: 'THREE_WAY',
    vendorId: '<vendorId>',
    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',
    state: 'ACTIVE',
    tags: {
      'cost-center': { value: 42 },
      'project-code': { value: 'PRJ-2024' }
    },
    lineItems: [
      {
        identifier: 'SKU-001',
        quantity: 100,
        rate: 50.00,
        tags: {
          'budget-line': { value: 'Stationery' }
        }
      },
      {
        identifier: 'SKU-002',
        quantity: 50,
        rate: 75.50
      }
    ]
  })
});

const result = await response.json();

import requests

url = "https://api.pazy.io/v1.0/procurement/purchase-order"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

payload = {
    "poNumber": "PO-2024-001",
    "poDate": "2024-01-15",
    "poType": "GOODS",
    "matchingType": "THREE_WAY",
    "vendorId": "<vendorId>",
    "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",
    "state": "ACTIVE",
    "tags": {
        "cost-center": {"value": 42},
        "project-code": {"value": "PRJ-2024"}
    },
    "lineItems": [
        {
            "identifier": "SKU-001",
            "quantity": 100,
            "rate": 50.00,
            "tags": {
                "budget-line": {"value": "Stationery"}
            }
        },
        {
            "identifier": "SKU-002",
            "quantity": 50,
            "rate": 75.50
        }
    ]
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()

Success Response

HTTP Status: 200 OK Response Fields:

Field	Type	Description
`ok`	boolean	Indicates whether the request was successful
`data`	object	Contains the purchase order creation response data
`data.poId`	string	Unique slug identifier for the purchase order (use this to retrieve or update the PO)
`data.state`	string	State the PO was created in — `DRAFTED` or `APPROVED` (active)
`data.skuMatchWarnings`	array	Not applicable for `THREE_WAY` POs (unmatched SKUs are rejected). Reserved for future use
`data.submitWarnings`	object	Present only when `submit: true` was passed but required fields were missing. The PO is still created in draft state

`skuMatchWarnings` Object

Field	Type	Description
`lineItemIdentifier`	string	The `identifier` value of the unmatched line item
`skuCode`	string	The `skuCode` that was provided (if applicable)
`skuName`	string	The `skuName` that was provided (if applicable)
`message`	string	Human-readable description of why the SKU could not be matched

`submitWarnings` Object

Field	Type	Description
`po`	array of strings	PO-level fields that were missing (e.g. `"vendorId"`, `"description"`, `"paymentTerms"`)
`lineItems`	object	Map of line item identifier to an array of missing fields (e.g. `"quantity"`, `"rate"`)

Response Example — draft (no `state` field or `state: "DRAFTED"`)

{
  "ok": true,
  "data": {
    "poId": "po_slug_identifier",
    "state": "DRAFTED"
  }
}

Response Example — active (`state: "ACTIVE"`, all fields present)

{
  "ok": true,
  "data": {
    "poId": "po_slug_identifier",
    "state": "ACTIVE"
  }
}

Response Example — draft despite `state: "ACTIVE"` (fields missing)

{
  "ok": true,
  "data": {
    "poId": "po_slug_identifier",
    "state": "DRAFTED",
    "submitWarnings": {
      "po": ["vendorId", "paymentTerms"],
      "lineItems": {
        "SKU-001": ["rate"]
      }
    }
  }
}