Skip to main content

Purchase Orders API

🚀 Why Use the Purchase Orders API?​

Purchase orders are critical components of inventory management and logistics in DataDocks. They represent agreements for products to be delivered to your warehouses (inbound) or shipped from them (outbound). The Purchase Orders API enables you to programmatically create, track, and manage these essential documents, linking your supply chain systems directly to your warehouse operations.

Real Problems This API Solves​

  • Streamline Order Processing: Automatically create and update purchase orders from your ERP or order management system
  • Enhance Inventory Visibility: Track expected arrivals and departures with detailed product information
  • Simplify Carrier Management: Associate carriers with purchase orders to streamline logistics
  • Improve Planning: Set expected timelines to better manage warehouse resources
  • Enable Advanced Analytics: Access structured purchase order data for reporting and analysis

5-Minute Quickstart​

Ready to create your first purchase order via API? Follow these simple steps:

  1. Get your API token from support
  2. Identify your location subdomain (e.g., your-warehouse.datadocks.com)
  3. Create a basic purchase order with this command:
See cURL example
curl -X POST \
  https://your-warehouse.datadocks.com/api/v1/purchase_orders \
  -H 'Authorization: Token YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "purchase_order": {
      "po_number": "PO-2023-001",
      "carrier_name": "Express Logistics",
      "outbound": false,
      "expected_starts_at": "2023-06-01T08:00:00-04:00",
      "expected_ends_at": "2023-06-01T16:00:00-04:00",
      "purchase_order_items": [
        {
          "product_name": "Widgets",
          "unit_name": "Pallet",
          "quantity": 10,
          "weight": 500
        }
      ]
    }
  }'
  1. Done! Your purchase order is now in DataDocks. Check your dashboard to see it.

API Architecture Overview​

┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
│  Your System    │──────▶│  DataDocks API  │──────▶│  Warehouse Ops  │
│  (ERP/OMS/TMS)  │◀──────┤   (REST/JSON)   │◀──────┤  (POs/Items)    │
└─────────────────┘       └─────────────────┘       └─────────────────┘
                                  │  ▲
                                  │  │
                                  ▼  │
                           ┌─────────────────┐
                           │  Appointments   │
                           │  & Scheduling   │
                           │                 │
                           └─────────────────┘

Authentication​

All API requests must include your API token in the Authorization header:

Authorization: Token YOUR_API_TOKEN

Listing Purchase Orders​

Purpose​

Retrieve a paginated list of purchase orders with optional filtering by PO number. Use this endpoint to sync purchase orders with your systems, check status of expected deliveries, or prepare reports on warehouse activity.

Business Use Cases​

  • Sync purchase orders with your ERP or order management system
  • Generate reports on expected inventory movements
  • Monitor upcoming deliveries or shipments
  • Track carrier performance across purchase orders

HTTP Request​

GET https://[location_subdomain].datadocks.com/api/v1/purchase_orders

Query Parameters​

ParameterTypeRequiredDescriptionExample
pageIntegerNoPage number for pagination (defaults to 1)page=2
po_numberStringNoFilter by exact PO number (case-insensitive)po_number=A-1000

Response Format​

The response contains an array of purchase order objects, each with the following fields:

FieldTypeDescription
idIntegerUnique identifier for the purchase order
po_numberStringPurchase order number
nameStringAuto-generated name based on PO details
carrier_nameStringName of the carrier assigned to the purchase order
location_nameStringName of the warehouse location
outboundBooleanWhether this is an outbound (true) or inbound (false) order
expected_starts_atStringISO8601 timestamp when the PO is expected to start
expected_ends_atStringISO8601 timestamp when the PO is expected to end
custom_valuesObjectKey-value pairs of custom fields
purchase_order_itemsArrayList of items associated with this purchase order

Each item in purchase_order_items contains:

FieldTypeDescription
idIntegerUnique identifier for the item
customer_nameStringName of the customer associated with the item
product_nameStringName of the product
unit_nameStringUnit of measure (e.g., "Pallet", "Box")
quantityNumberQuantity of the product
weightNumberWeight of the item
custom_valuesObjectKey-value pairs of custom fields for this item

Code Examples​

cURL​

See cURL example
# Basic listing
curl -H "Authorization: Token YOUR_API_TOKEN" \
     https://YOUR_LOCATION.datadocks.com/api/v1/purchase_orders

# Filtered by PO number
curl -H "Authorization: Token YOUR_API_TOKEN" \
     "https://YOUR_LOCATION.datadocks.com/api/v1/purchase_orders?po_number=A-1000"

JavaScript​

See JavaScript example
// Using fetch API with PO number filter
const getPurchaseOrders = async (poNumber) => {
  const params = new URLSearchParams();
  if (poNumber) params.append("po_number", poNumber);

  const response = await fetch(
    `https://YOUR_LOCATION.datadocks.com/api/v1/purchase_orders?${params.toString()}`,
    {
      method: "GET",
      headers: {
        Authorization: "Token YOUR_API_TOKEN",
        "Content-Type": "application/json",
      },
    }
  );

  if (!response.ok) {
    const errorData = await response.json();
    throw new Error(
      `Failed to fetch purchase orders: ${JSON.stringify(errorData)}`
    );
  }

  return response.json();
};

Sample Response​

See sample response
[
  {
    "id": 1,
    "po_number": "A-1000",
    "name": "A-1000-FastCo-Cereal",
    "carrier_name": "FastCo",
    "location_name": "Toronto",
    "outbound": false,
    "expected_starts_at": "2020-10-09T13:35:00-04:00",
    "expected_ends_at": "2020-10-15T13:35:00-04:00",
    "custom_values": {
      "expected_at": "2020-10-09",
      "travel_type": "Plane",
      "forklift_operator": "Joe"
    },
    "purchase_order_items": [
      {
        "id": 2,
        "customer_name": "FishCo",
        "product_name": "Trout",
        "unit_name": "Skid",
        "quantity": 16,
        "weight": 102,
        "custom_values": {}
      },
      {
        "id": 1,
        "customer_name": "FishCo",
        "product_name": "Cereal",
        "unit_name": "Skid",
        "quantity": 33,
        "weight": 581,
        "custom_values": {}
      }
    ]
  }
]

Retrieving a Single Purchase Order​

Purpose​

Get detailed information about a specific purchase order by ID. Use this endpoint when you need comprehensive data about a particular order, including all its line items and custom fields.

Business Use Cases​

  • Display detailed purchase order information in your application
  • Verify purchase order details before processing
  • Access the complete list of items in a specific order
  • Check custom field values for integration with other systems

HTTP Request​

GET https://[location_subdomain].datadocks.com/api/v1/purchase_orders/:id

Path Parameters​

ParameterTypeRequiredDescription
idIntegerYesUnique ID of the purchase order

Response​

A successful request returns a 200 OK response with the full purchase order object in the same format as the list response.

Code Examples​

cURL​

See cURL example
curl -H "Authorization: Token YOUR_API_TOKEN" \
     https://YOUR_LOCATION.datadocks.com/api/v1/purchase_orders/1

JavaScript​

See JavaScript example
const getPurchaseOrder = async (purchaseOrderId) => {
  try {
    const response = await fetch(
      `https://YOUR_LOCATION.datadocks.com/api/v1/purchase_orders/${purchaseOrderId}`,
      {
        method: "GET",
        headers: {
          Authorization: "Token YOUR_API_TOKEN",
          "Content-Type": "application/json",
        },
      }
    );

    if (!response.ok) {
      if (response.status === 404) {
        throw new Error(`Purchase order #${purchaseOrderId} not found`);
      }

      const errorData = await response.json();
      throw new Error(
        `Failed to retrieve purchase order: ${JSON.stringify(errorData)}`
      );
    }

    return await response.json();
  } catch (error) {
    console.error("Error fetching purchase order:", error);
    throw error;
  }
};

Creating a Purchase Order​

Purpose​

Create a new purchase order record in DataDocks. This endpoint allows you to add new purchase orders and their line items programmatically, integrating your order management system directly with your warehouse operations.

Decision Tree: When to Create a PO via API​

┌─────────────────┐
│ Need to add a   │
│ purchase order? │
└────────┬────────┘
         │
         ▼
┌─────────────────┐     Yes     ┌─────────────────┐
│  Integration    │────────────▶│   Perfect for   │
│  with your ERP/ │             │   the API!      │
│  Order system?  │             │                 │
└────────┬────────┘             └─────────────────┘
         │ No
         ▼
┌─────────────────┐     Yes     ┌─────────────────┐
│ Creating many   │────────────▶│   Use bulk      │
│ orders at once? │             │   import        │
└────────┬────────┘             └─────────────────┘
         │ No
         ▼
┌─────────────────┐
│   Use the web   │
│   interface     │
└─────────────────┘

Business Use Cases​

  • System Integration: Create purchase orders directly from your ERP or order management system
  • Automated Order Processing: Programmatically convert sales orders to purchase orders
  • EDI Integration: Transform EDI 850 Purchase Order documents into DataDocks POs
  • Vendor Integration: Allow vendors to submit purchase orders through your systems

HTTP Request​

POST https://[location_subdomain].datadocks.com/api/v1/purchase_orders

Request Body​

ParameterTypeRequiredDescriptionConstraintsDefaultExample
po_numberStringYesPurchase order numberMust be uniqueNone"PO-2023-001"
carrier_nameStringNo *Name of the carrierNoneNone"Express Logistics"
carrier_numberStringNoCarrier's company numberMust match existing carrierNone"EXP-001"
location_nameStringNoName of the locationMust match existing locationCurrent location"Toronto Warehouse"
outboundBooleanNoWhether this is an outbound orderNonefalsetrue
expected_starts_atStringNoISO8601 timestamp for expected startValid ISO8601 formatNone"2023-06-01T08:00:00-04:00"
expected_ends_atStringNoISO8601 timestamp for expected endValid ISO8601 formatNone"2023-06-01T16:00:00-04:00"
alternate_reference_numberStringNoAlternative reference numberNoneNone"REF-123"
closedBooleanNoWhether the PO is closedNonefalsetrue
custom_valuesObjectNo *Custom field valuesBased on location settings{}{"department": "Produce"}
purchase_order_itemsArrayNoLine items for the POAt least one item recommended[]See below

Each item in purchase_order_items can include:

ParameterTypeRequiredDescriptionConstraintsExample
customer_nameStringNo *Name of the customerNone"Acme Corp"
customer_numberStringNo *Customer's company numberMust match existing customer"ACME-001"
product_nameStringNo *Name of the productNone"Widgets"
unit_nameStringNo *Unit of measureNone"Pallet"
quantityNumberNo *Quantity of the productMust be positive10
weightNumberNo *Weight of the itemMust be positive500
custom_valuesObjectNo *Custom field values for this itemBased on location settings{"color": "Blue"}

* Fields might be required depending on location preferences

Response​

A successful request returns a 200 OK response with the full purchase order object, including the generated id and other system-assigned values.

Code Examples​

cURL​

See cURL example
curl -H "Authorization: Token YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{
       "purchase_order": {
         "po_number": "PO-2023-001",
         "carrier_name": "Express Logistics",
         "outbound": false,
         "expected_starts_at": "2023-06-01T08:00:00-04:00",
         "expected_ends_at": "2023-06-01T16:00:00-04:00",
         "custom_values": {
           "department": "Electronics",
           "priority": "High"
         },
         "purchase_order_items": [
           {
             "product_name": "Laptops",
             "unit_name": "Box",
             "quantity": 50,
             "weight": 250,
             "custom_values": {
               "model": "XPS 13"
             }
           },
           {
             "product_name": "Monitors",
             "unit_name": "Pallet",
             "quantity": 10,
             "weight": 500,
             "custom_values": {
               "size": "27-inch"
             }
           }
         ]
       }
     }' \
     https://YOUR_LOCATION.datadocks.com/api/v1/purchase_orders

JavaScript​

See JavaScript example
const createPurchaseOrder = async (purchaseOrderData) => {
  try {
    const response = await fetch(
      `https://YOUR_LOCATION.datadocks.com/api/v1/purchase_orders`,
      {
        method: "POST",
        headers: {
          Authorization: "Token YOUR_API_TOKEN",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ purchase_order: purchaseOrderData }),
      }
    );

    if (!response.ok) {
      const errorData = await response.json();
      const errorMessages = Object.entries(errorData.errors || {})
        .map(([field, messages]) => `${field}: ${messages.join(", ")}`)
        .join("\n");

      throw new Error(`Failed to create purchase order:\n${errorMessages}`);
    }

    return await response.json();
  } catch (error) {
    console.error("API Error:", error);
    throw error;
  }
};

Updating a Purchase Order​

Purpose​

Update an existing purchase order's details. This endpoint allows you to modify any aspect of a purchase order, including its line items, dates, carrier information, and custom fields.

Business Use Cases​

  • Keep Data Current: Update delivery dates or carrier information as they change
  • Modify Order Contents: Add, remove, or change line items as needed
  • Change Order Status: Mark purchase orders as closed when fulfilled
  • Add Reference Information: Update custom fields with tracking or delivery data

HTTP Request​

PUT https://[location_subdomain].datadocks.com/api/v1/purchase_orders/:id

Path Parameters​

ParameterTypeRequiredDescription
idIntegerYesUnique ID of the purchase order

Request Body​

The request body accepts the same parameters as the create endpoint. Only the fields you want to change need to be included.

Common Update Scenarios​

Updating Dates​

{
  "purchase_order": {
    "expected_starts_at": "2023-06-05T08:00:00-04:00",
    "expected_ends_at": "2023-06-05T16:00:00-04:00"
  }
}

Changing Carrier​

{
  "purchase_order": {
    "carrier_name": "Fast Transit Inc",
    "carrier_number": "FTI-001"
  }
}

Closing a Purchase Order​

{
  "purchase_order": {
    "closed": true
  }
}

Updating Line Items​

{
  "purchase_order": {
    "purchase_order_items": [
      {
        "id": 123,
        "quantity": 15
      },
      {
        "product_name": "New Product",
        "unit_name": "Box",
        "quantity": 5,
        "weight": 25
      }
    ]
  }
}

Code Examples​

cURL​

See cURL example
curl -H "Authorization: Token YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -X PUT \
     -d '{
       "purchase_order": {
         "carrier_name": "Updated Logistics Co",
         "expected_starts_at": "2023-06-02T08:00:00-04:00",
         "custom_values": {
           "tracking_number": "TRK12345"
         }
       }
     }' \
     https://YOUR_LOCATION.datadocks.com/api/v1/purchase_orders/1

JavaScript​

See JavaScript example
const updatePurchaseOrder = async (purchaseOrderId, updateData) => {
  try {
    const response = await fetch(
      `https://YOUR_LOCATION.datadocks.com/api/v1/purchase_orders/${purchaseOrderId}`,
      {
        method: "PUT",
        headers: {
          Authorization: "Token YOUR_API_TOKEN",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ purchase_order: updateData }),
      }
    );

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(
        `Failed to update purchase order: ${JSON.stringify(errorData)}`
      );
    }

    return await response.json();
  } catch (error) {
    console.error("Error updating purchase order:", error);
    throw error;
  }
};

Removing All Purchase Order Items​

If you need to clear all line items from a purchase order, include the clear_po_items parameter with a value of true:

{
  "purchase_order": {
    "clear_po_items": "true",
    "purchase_order_items": [
      {
        "product_name": "New Product",
        "unit_name": "Box",
        "quantity": 10
      }
    ]
  }
}

This will remove all existing items and replace them with the new items provided (if any).

Deleting a Purchase Order​

Purpose​

Remove a purchase order from the system. This endpoint allows you to delete purchase orders that are no longer needed.

Important Considerations​

Before deleting a purchase order, consider the following:

  • The purchase order must not be associated with any active appointments
  • Deletion is permanent and cannot be undone
  • In many cases, it's better to mark a purchase order as closed rather than delete it

Business Use Cases​

  • Clean Up Test Data: Remove test or dummy purchase orders
  • Remove Duplicate Records: Clean up after data de-duplication
  • System Maintenance: Remove old, unused purchase order records

HTTP Request​

DELETE https://[location_subdomain].datadocks.com/api/v1/purchase_orders/:id

Path Parameters​

ParameterTypeRequiredDescription
idIntegerYesUnique ID of the purchase order

Response​

A successful request returns a 204 No Content response, indicating that the purchase order was deleted successfully.

Code Examples​

cURL​

See cURL example
curl -H "Authorization: Token YOUR_API_TOKEN" \
     -X DELETE \
     https://YOUR_LOCATION.datadocks.com/api/v1/purchase_orders/1

JavaScript​

See JavaScript example
const deletePurchaseOrder = async (purchaseOrderId) => {
  try {
    const response = await fetch(
      `https://YOUR_LOCATION.datadocks.com/api/v1/purchase_orders/${purchaseOrderId}`,
      {
        method: "DELETE",
        headers: {
          Authorization: "Token YOUR_API_TOKEN",
        },
      }
    );

    if (!response.ok) {
      if (response.status === 404) {
        throw new Error(`Purchase order #${purchaseOrderId} not found`);
      }

      const errorData = await response.json();
      throw new Error(
        `Failed to delete purchase order: ${JSON.stringify(errorData)}`
      );
    }

    return true; // Successfully deleted
  } catch (error) {
    console.error("Error deleting purchase order:", error);
    throw error;
  }
};

Automatic Entity Resolution​

Carrier Resolution​

When creating or updating a purchase order, you can provide either carrier_name or carrier_number (or both):

  • If you provide carrier_number, the system will attempt to find a matching carrier by company number
  • If a match is found, the carrier's name and ID will be automatically associated with the purchase order
  • If no match is found, the system will use the provided carrier_number as the carrier_name

Product Resolution​

When creating or updating purchase order items:

  • If the product name matches an existing product (case-insensitive), that product will be used
  • If the product didn't match any existing product, the item will be created but may not be linked to a proper product record
  • contact support if you need to create a product if it doesn't exist yet

Unit Resolution​

Similar to products:

  • If the unit name matches an existing unit (case-insensitive), that unit will be used
  • If the unit didn't match any existing unit, the item will not have a proper unit association
  • contact support if you need to create a unit if it doesn't exist yet

Best Practices​

Data Management​

  • Use Unique PO Numbers: Ensure each purchase order has a unique identifier
  • Provide Carrier Numbers: When possible, use carrier company numbers for reliable carrier association
  • Validate Data Client-Side: Ensure data meets basic validation before sending
  • Consider Using Closed Flag: Rather than deleting purchase orders, mark them as closed
  • Manage Custom Fields Properly: Only use custom fields that are configured for your location

Performance Optimization​

  • Include Complete Data Sets: When possible, include all relevant data in a single API call
  • Use Batch Operations: Group related purchase order updates together
  • Be Specific with Queries: Use available filters to minimize data transfer

Common Gotchas and Troubleshooting​

  • PO Number Uniqueness: Purchase order numbers should be unique within a location
  • Date Formatting: Dates must be in valid ISO8601 format (e.g., "2023-06-01T08:00:00-04:00")
  • Carrier Association: If carriers aren't being properly associated, ensure you're using the correct company number
  • Custom Field Types: JSON fields in custom values will be preserved as JSON; other fields will be converted to strings
  • Clearing Line Items: Remember to use the clear_po_items parameter if you want to completely replace all line items

Error Handling​

Error CodeDescriptionPossible Cause
400Bad RequestInvalid values or format
404Not FoundPurchase order ID doesn't exist
422Unprocessable EntityValidation failed (e.g., missing required field)
401UnauthorizedInvalid or missing API token
403ForbiddenInsufficient permissions

Sample Error Response​

{
  "errors": {
    "po_number": ["can't be blank"],
    "purchase_order_items": ["must have at least one item"]
  }
}

Help and Support​

If you're experiencing issues not covered in this documentation:

  1. Check the error response: Most API errors include specific information about what went wrong
  2. Verify permissions: Ensure your API token has sufficient permissions
  3. Test in smaller steps: Break down complex operations to identify the specific issue