Organization API Purchase Orders

Why Use the Purchase Orders API?

Create and manage purchase orders across your warehouses from one integration. You can assign an order to a warehouse when you create it, or leave it unassigned until you know where it will be handled.

• Sync orders from your ERP — Create purchase orders and line items directly from your order system.
• Assign warehouses later — Import orders before choosing a receiving or shipping location.
• Track scheduled orders — Retrieve purchase orders that have booked appointments.

Use your organization subdomain in each request, such as acme.datadocks.com. Your API user needs access to the locations you want to work with. See Authentication and Access for setup details.

5-Minute Quickstart

Create a purchase order for your Toronto warehouse:

1. Get your API token and organization subdomain from DataDocks support.
2. Confirm the warehouse name using Listing Locations.
3. Send the following request, replacing the sample values with your order details.

See cURL example

curl -H "Authorization: Token YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{
       "purchase_order": {
         "po_number": "PO-2026-001",
         "location_name": "Toronto",
         "expected_starts_at": "2026-10-01T09:00:00-04:00",
         "purchase_order_items": [
           {
             "product_name": "Widgets",
             "quantity": 10
           }
         ]
       }
     }' \
     https://acme.datadocks.com/api/v1/purchase_orders

A successful request returns 200 OK with the purchase order details. Save its id to retrieve or update the order later. Your warehouse settings may require additional fields.

Listing Purchase Orders

Purpose

Retrieve orders across the locations your API user can access, or filter the list to one warehouse. Unassigned orders are included in both cases.

HTTP Request

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

Query Parameters

Parameter	Type	Required	Description	Example
location_name	String	No	Include this location's orders and unassigned orders	Toronto
po_number	String	No	Filter by purchase order number	PO-2026-001
page	Integer	No	Page number	2

Without location_name, the list includes orders at all locations your API user can access, plus unassigned orders in your organization.

Code Examples

See cURL examples

# List orders across your accessible locations
curl -H "Authorization: Token YOUR_API_TOKEN" \
     https://acme.datadocks.com/api/v1/purchase_orders

# List Toronto orders and unassigned orders
curl -H "Authorization: Token YOUR_API_TOKEN" \
     "https://acme.datadocks.com/api/v1/purchase_orders?location_name=Toronto"

Response Format

A successful request returns 200 OK with an array of purchase orders. See the Purchase Orders API for the complete response fields. Follow the response's Link header to retrieve additional pages.

Viewing a Single Order

Add the order ID to the URL:

curl -H "Authorization: Token YOUR_API_TOKEN" \
     https://acme.datadocks.com/api/v1/purchase_orders/123

You can include ?location_name=Toronto to look for the order at that location or among unassigned orders. An order outside the locations you can access returns 404 Not Found.

Creating a Purchase Order

HTTP Request

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

Request Body

Send the order fields inside a purchase_order object.

Parameter	Type	Required	Description	Example
po_number	String	Yes	Purchase order number	PO-2026-001
location_name	String	No	Warehouse to assign; omit to create an unassigned order	Toronto
expected_starts_at	String	No	Expected start time; include a UTC offset when possible	2026-10-01T09:00:00-04:00
expected_ends_at	String	No	Expected end time	2026-10-01T17:00:00-04:00
purchase_order_items	Array	No	Order line items	See the example below
custom_values	Object	No	Values for your configured custom fields	{"department":"Produce"}

Other fields, including carrier details, reference numbers, and line-item attributes, are described in the Purchase Orders API. Required fields can depend on your warehouse settings.

Code Example: Create an Unassigned Order

Leave out location_name when the warehouse is not yet known:

See cURL example

curl -H "Authorization: Token YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{
       "purchase_order": {
         "po_number": "PO-2026-002",
         "expected_starts_at": "2026-10-01T13:00:00Z",
         "purchase_order_items": [
           {
             "customer_name": "Acme Retail",
             "product_name": "Widgets",
             "quantity": 10
           }
         ]
       }
     }' \
     https://acme.datadocks.com/api/v1/purchase_orders

Response

A successful request returns 200 OK with the new order, including its id. The order remains unassigned until you provide a location in an update.

Updating a Purchase Order

HTTP Request

PATCH https://[organization_subdomain].datadocks.com/api/v1/purchase_orders/[id]

PUT is also supported. Include the fields you want to update inside purchase_order. For the full list of editable fields, see the Purchase Orders API.

Changing a Purchase Order's Location

Include location_name in the request body to assign, move, or unassign an order:

location_name in the Body	Result
Omitted	Keep the current location
A known location name	Assign or move the order to that location
null, an empty string, or only spaces	Remove the location assignment
An unknown name	Return 404; keep the current location

Your API user needs write permission at both the order's current location and the destination. Unassigned orders only require access to the destination. Selecting a destination without access returns 403 Forbidden.

Code Examples

See cURL examples: assign or unassign an order

# Assign an order to Vancouver
curl -H "Authorization: Token YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -X PATCH \
     -d '{
       "purchase_order": {
         "location_name": "Vancouver"
       }
     }' \
     https://acme.datadocks.com/api/v1/purchase_orders/123

# Remove the location assignment
curl -H "Authorization: Token YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -X PATCH \
     -d '{
       "purchase_order": {
         "location_name": null
       }
     }' \
     https://acme.datadocks.com/api/v1/purchase_orders/123

A successful update returns 200 OK with the updated order.

Use the request body to change the location. A location in the URL limits which orders can be found, but does not reassign them. When moving an order, put the destination in the body and leave location_name out of the URL. Sending different names in the URL and body returns 400 Bad Request.

When updating line items, use IDs from the order you are changing. Line items do not accept their own location_name.

Dates and Time Zones

Include a UTC offset, such as -04:00, or use Z for UTC when sending timestamps.

Request	How Times Without an Offset Are Read
Create/update an assigned order	Use the effective assigned location's time zone
Create an unassigned order or clear assignment	Use UTC
Collection time filters	Use the optional query location's zone, otherwise UTC

Updating an assigned order without location_name preserves its warehouse and uses that warehouse's time zone. Moving an order uses the destination zone; clearing assignment uses UTC. Explicit timestamp offsets always take precedence.

Returned timestamps, including order/item creation and update times, use the order's assigned zone or UTC when unassigned. Booked appointments use their own zones. A query location never changes an unassigned order's UTC output. earliest_assignment_date is also a date-time and follows the same rule.

Products and Customers

Products

Product names are stored as text without creating or assigning product entities. Assigned orders still apply their warehouse's product-name validation and settings, including updates without a location selector.

Customers

Customer names are matched against existing companies in your organization. If no company matches, a new customer can be created when your API user has permission.

For unassigned orders, new customer names are allowed and the new company has these defaults:

Setting	Default
Automatically approve appointments (auto_approve_appointments)	false
Allow the customer to create carriers (can_create_carriers)	false

Assigned orders use their effective warehouse settings for customer creation, including updates without a selector. Relocation uses the destination settings; clearing assignment uses the unassigned defaults.

Custom Fields

Send custom field values in custom_values on the purchase order or its line items.

• Assigned orders: Use fields enabled at the order's warehouse, including updates without location_name.
• Unassigned orders: Use the organization's custom-field definitions, including definitions not enabled at any warehouse. A query location filter does not narrow these definitions.

Moving an order uses the destination warehouse's fields. Clearing its assignment uses organization-wide definitions for the same request.

JSON fields accept objects and arrays. Other field values are stored as text and must meet their configured validation rules.

An unknown field name returns 422 Unprocessable Entity. If the same key has conflicting types across applicable definitions, assign the order to a warehouse with an unambiguous definition or make the field types consistent before submitting it.

Finding Orders with Booked Appointments

Purpose

Check which purchase orders have been scheduled. Use this endpoint to update shipment status in your ERP or TMS.

HTTP Request

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

Query Parameters

Parameter	Type	Required	Description
location_name	String	No	Limit orders to a location you can access, plus unassigned orders
start_time	String	No	Include orders with an accessible appointment scheduled to start at or after this time
end_time	String	No	Include orders with an accessible appointment scheduled to start at or before this time; this does not filter appointment finish times
updated_since	String	No	Include orders created or updated since this time
limit	Integer	No	Results per request; default 100, maximum 250
offset	Integer	No	Number of results to skip; default 0

Code Example

See cURL example

curl -H "Authorization: Token YOUR_API_TOKEN" \
     "https://acme.datadocks.com/api/v1/purchase_orders/with_booked_appointments?location_name=Toronto&limit=100&offset=0"

The response includes purchase orders and only appointments at locations your API user can access. Inaccessible appointments do not affect time filtering or cause an order to appear. See the Purchase Orders API for the full response format.

Additional Operations

Operation	Method	Path
Delete an order	DELETE	/api/v1/purchase_orders/123

This route accepts an optional location_name in the URL and use the same access rules as other purchase-order requests. A successful delete returns 204 No Content.

Error Handling

Error Code	Possible Cause	What to Check
400	Different location names in the URL and body	Put the destination in the body when moving an order.
403	No access to the selected warehouse	Confirm your API user's location access with support.
404	Unknown location, missing order, or order outside your accessible locations	Check the location name and purchase order ID.
422	Invalid order, line item, or custom field	Check the response's errors and correct the listed fields.

See the Organization API guide for authentication, payment, and rate-limit errors.

Help and Support

If you need help with your integration, contact support@datadocks.com with the request URL, purchase order ID, and error response. Leave your API token out of the message.