Skip to content
Guides
/
/
Update Purchase Orders
Last updated

Update Purchase Orders

Update existing purchase orders to modify product quantities, change delivery dates, or add tracking information. ShipStation provides three endpoints for updates:

  • PUT /v2/purchase_orders/{purchase_order_id} - Update all order details (only available in draft status)
  • POST /v2/purchase_orders/{purchase_order_id}/shipping_details - Update shipping-related details (only available in open status)
  • POST /v2/purchase_orders/{purchase_order_id}/status - Update only the status

Update Purchase Order Details (Draft Status Only)

Use the PUT method to update all details of a purchase order that is in draft status. This includes modifying products, dates, tracking, and all other information. Once a purchase order moves to open status or beyond, you cannot use this endpoint. For purchase orders in open status, use the POST endpoint described below to update shipping-related details only.

Path Parameters

ParameterTypeDescription
purchase_order_idstringThe unique identifier of the purchase order to update

Request Body Properties

All fields can be updated when the purchase order is in draft status.

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
expected_delivery_datestring (date-time)OptionalExpected delivery date
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
shipping_carrierstringOptionalShipping carrier name
tracking_numberstringOptionalTracking number from supplier
reference_numberstringOptionalYour custom reference number
note_to_supplierstringOptionalNotes or special instructions

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)

Example Request & Response

PUT /v2/purchase_orders/{purchase_order_id}

curl -i -X PUT \
  https://api.shipstation.com/v2/purchase_orders/se-234 \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "supplier_id": "67890",
    "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
      }
    ]
  }'

Update Shipping Details (Open Status Only)

Use the POST /v2/purchase_orders/{purchase_order_id}/shipping_details method to update shipping-related details for a purchase order in open status. This allows you to modify delivery dates, tracking information, and other shipping details after the order has been sent to the supplier. Once a purchase order moves to receiving, received, cancelled, or closed status, updating is no longer allowed.

Path Parameters

ParameterTypeDescription
purchase_order_idstringThe unique identifier of the purchase order to update

Request Body Properties

Only the following shipping-related fields can be updated when the purchase order is in open status:

PropertyTypeRequiredDescription
expected_delivery_datestring (date-time)OptionalExpected delivery date
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
shipping_carrierstringOptionalShipping carrier name
tracking_numberstringOptionalTracking number from supplier
reference_numberstringOptionalYour custom reference number
order_datestring (date-time)OptionalThe date the order was placed
note_to_supplierstringOptionalA note or message to the supplier

Example Request & Response

POST /v2/purchase_orders/{purchase_order_id}/shipping_details

curl -i -X POST \
  'https://api.shipstation.com/v2/purchase_orders/{purchase_order_id}/shipping_details' \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "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",
    "note_to_supplier": "Please expedite delivery"
  }'

Update Purchase Order Status

Use the POST method to update only the status of a purchase order. This is useful for workflow management without modifying other details.

Path Parameters

ParameterTypeDescription
purchase_order_idstringThe unique identifier of the purchase order

Request Body

PropertyTypeDescription
statusenumerated stringNew status: open, receiving, received, cancelled, closed

Valid Status Transitions

Purchase orders follow specific status transition rules:

From StatusCan Transition ToUse Case
draftopen, cancelledSend order to supplier or cancel before ordering
openreceiving, cancelledBegin receiving products or cancel the order
receivingreceived, cancelledComplete receiving or cancel partial shipment
receivedclosedTerminal state - all products received
closed(none)Terminal state - order completed
cancelled(none)Terminal state - order cancelled

Example Request & Response

POST /v2/purchase_orders/{purchase_order_id}/status

curl -i -X POST \
  https://api.shipstation.com/v2/purchase_orders/se-234/status \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "status": "open"
  }'

Error Handling

Common errors when updating purchase orders:

  • 400 Bad Request: Missing required fields or invalid data format
    • Invalid status transition (e.g., trying to go from received to open)
    • Invalid enum values
  • 404 Not Found: Purchase order ID doesn't exist

Invalid Status Transitions

If you attempt an invalid status transition, you'll receive a 422 error. For example:

{
  "request_id": "aa3d8e8e-462b-4476-9618-72db7f7b7009",
  "errors": [
    {
      "error_source": "Shipengine",
      "error_type": "validation",
      "error_code": "invalid_status",
      "message": "Cannot transition from 'received' to 'open'"
    }
  ]
}

Always check the current status before attempting to update it, and follow the valid transition rules listed above.

Previous page
Next page