Skip to content
Guides
/
/
Create Purchase Orders
Last updated

Create Purchase Orders

Create new purchase orders to track inventory replenishment from your suppliers. Use the POST method with /v2/purchase_orders to create orders in draft status and include product details, delivery dates, and payment terms.

Create a Purchase Order

Request Body Properties

PropertyTypeRequiredDescription
supplier_idstringRequiredIdentifier for the supplier providing the products
warehouse_idstringRequiredIdentifier for the warehouse where products will be received
productsarrayRequiredArray of products to order (must contain at least one product)
order_datestring (date-time)OptionalDate when the order was placed with the supplier. Format: ISO 8601
expected_delivery_datestring (date-time)OptionalExpected delivery date for the shipment. Format: ISO 8601
payment_termsenumerated stringOptionalPayment terms: none, cash_on_delivery, payment_on_receipt, payment_in_advance, net_7, net_15, net_30, net_45, net_60
payment_statusenumerated stringOptionalPayment status: none, unpaid, partially_paid, paid, refunded, credit_issued, other
currency_codestringOptionalISO 4217 currency code (default: "USD")
shipping_carrierstringOptionalShipping carrier name for tracking the shipment
tracking_numberstringOptionalTracking number for the shipment from supplier
reference_numberstringOptionalYour custom reference number for internal tracking
note_to_supplierstringOptionalSpecial instructions or notes for the supplier

Product Properties

Each product in the products array must include:

PropertyTypeRequiredDescription
skustringRequiredStock Keeping Unit identifier
quantityintegerRequiredQuantity to order (minimum: 1)
supplier_skustringOptionalSupplier's SKU for this product
costnumberOptionalUnit cost of the product (minimum: 0)

Response Properties

On successful creation, the response includes:

  • The complete purchase order details (all properties from GET operation)
  • Auto-generated purchase_order_id
  • Auto-generated order_number
  • create_date and modify_date timestamps
  • Full product details for each product

Example Request & Response

POST /v2/purchase_orders

curl -i -X POST \
  https://api.shipstation.com/v2/purchase_orders \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "supplier_id": "se-567",
    "order_date": "2025-01-15T00:00:00Z",
    "expected_delivery_date": "2025-02-01T00:00:00Z",
    "payment_terms": "net_30",
    "payment_status": "unpaid",
    "currency_code": "USD",
    "shipping_carrier": "UPS",
    "tracking_number": "1Z12345E1234567890",
    "reference_number": "REF-12345",
    "warehouse_id": "se-123456",
    "note_to_supplier": "Please expedite delivery",
    "products": [
      {
        "sku": "WIDGET-001",
        "supplier_sku": "SUPP-WIDGET-001",
        "quantity": 100,
        "cost": 9.99
      }
    ]
  }'

Error Handling

Common errors when creating purchase orders:

  • 400 Bad Request: Missing required fields (supplier_id or products)

Validation rules:

  • products array must contain at least one product
  • quantity must be greater than 0
  • cost must be 0 or positive
  • Date formats must follow ISO 8601 standard
  • Supplier with the given ID was not found
Previous page
Next page