IQmetrix API Guide for Purchase Order (PO) Creation: Process, Payload Structure, and Troubleshooting

1. Overview

The IQmetrix Vendor Inventory API supports the creation of Purchase Orders (POs) through a structured JSON payload. This guide outlines the key requirements, step-by-step process, and common issues encountered during PO creation using the IQmetrix API.

2. Requirements for Purchase Order Creation

To create a Purchase Order, the following prerequisites and fields are essential:

• API Authorization: A valid access token obtained via OAuth 2.0.
• Endpoint: https://apirc.iqmetrix.net/vendorinventory/v1/vendors/{vendorID}/companies/{companyID}/locations/{locationID}/purchaseOrders.
• Headers:
• Authorization: Bearer [access_token]
• Content-Type: application/json

Core Payload Fields:

• vendorID (Integer): The vendor’s unique identifier.
• billToStoreId (Integer): ID of the billing location.
• shipToStoreId (Integer): ID of the destination location for items.
• vendorInvoiceNumber (String): Unique invoice identifier for the vendor.
• items (Array): List of items, each containing:
• sku (String): Item’s SKU code.
• quantity (Integer): Number of units ordered.
• cost (Float): Cost per unit.

3. Step-by-Step Process for PO Creation

Step 1: Authenticate and Obtain Access Token

Before calling the PO creation endpoint, obtain an access token using the OAuth 2.0 password grant type.

Step 2: Build the JSON Payload

Construct the payload according to the required structure:

{

  “vendorID”: 308022,

  “billToStoreId”: 256439,

  “shipToStoreId”: 256628,

  “vendorInvoiceNumber”: “INV-12345”,

  “items”: [

    {

      “sku”: “SKU1234”,

      “quantity”: 10,

      “cost”: 15.99

    }

  ]

}

Step 3: Send the PO Creation Request

• Method: POST
• URL: Update with specific vendor, company, and location IDs.
• Headers: Include the Authorization and Content-Type headers.

Step 4: Review the Response

• Successful Response: If successful, the API returns a 201 Created status, along with the purchaseOrderId and externalPurchaseOrderNumber.
• Common Errors: If the PO status indicates failure, check the response body for error details.

4. Common Issues and Troubleshooting

Issue 1: Receiving 200 OK Instead of 201 Created

• A 200 OK response indicates that the request reached the server but didn’t create the PO successfully. Ensure that:
• All required fields in the payload are correctly populated.
• The Authorization token is valid and includes Bearer before the token.
• The Content-Type header is application/json.

Issue 2: API Error Code 400 or 401 (Unauthorized)

• Cause: Incorrect or expired access token.
• Solution: Re-authenticate to obtain a fresh access token and retry the request.

Issue 3: Invalid vendorInvoiceNumber or Duplicate Errors

• Cause: Duplicate or incorrect vendorInvoiceNumber.
• Solution: Ensure that each PO has a unique vendorInvoiceNumber to avoid conflicts.

Issue 4: Payload Validation Errors

• Cause: Incorrect data type or missing fields.
• Solution: Verify that vendorID, billToStoreId, shipToStoreId, and items are present and formatted as specified. Specifically, ensure all items have valid SKUs, quantities, and costs.

5. Best Practices for Reliable PO Creation

1. Consistent Error Logging: Implement logging to capture request and response details, especially for authorization errors or unexpected status codes.
2. Token Expiry Handling: Refresh the access token if an authorization error (401) is encountered.
3. Unique vendorInvoiceNumber: Use unique identifiers for vendorInvoiceNumber to prevent duplication errors.
4. API Status Monitoring: Regularly check the IQmetrix status page or API changelog to stay informed of any updates that could impact request behavior.

6. Example Code Snippet for Purchase Order Creation

function CreatePurchaseOrder(accessToken, vendorID, StoreID, BillToStoreID, ShipToStoreID, InvoiceNumber, itemsObj) {

  const payload = {

    vendorID: vendorID,

    billToStoreId: BillToStoreID,

    shipToStoreId: ShipToStoreID,

    vendorInvoiceNumber: InvoiceNumber,

    items: itemsObj.map(item => ({

      sku: item.SKU,

      quantity: item.QTY,

      cost: item.RATE_ITEM

    }))

  };

  const response = https.post({

    url: `https://apirc.iqmetrix.net/vendorinventory/v1/vendors/${vendorID}/companies/${StoreID}/locations/${ShipToStoreID}/purchaseOrders`,

    headers: {

      ‘Authorization’: `Bearer ${accessToken}`,

      ‘Content-Type’: ‘application/json’

    },

    body: JSON.stringify(payload)

  });

  if (response.code === 201) {

    return JSON.parse(response.body);

  } else {

    throw new Error(`Create PO Failed: ${response.body}`);

  }

}

Conclusion

By following this guide, you can reliably create Purchase Orders in IQmetrix and troubleshoot common errors effectively. Ensure that the payload structure, headers, and unique identifiers are aligned with IQmetrix API standards to prevent issues with PO creation. For recurring issues, consult IQmetrix support or refer to the API documentation for updates on endpoint requirements.