Skip to content
Full API Reference/
/
Receive purchase order pr...

ShipStation API v2 (2.0.0)

Download OpenAPI description
openapi.json
openapi.yaml
Overview
License
MIT
Languages
Servers
Mock server
https://docs.shipstation.com/_mock/openapi/
Production
https://api.shipstation.com/

Batches

Process labels in bulk and receive a large number of labels and customs forms in bulk responses. Batching is ideal for workflows that need to process hundreds or thousands of labels quickly.

Operations

Carriers

Retreive useful details about the carriers connected to your accounts, including carrier IDs, service IDs, advanced options, and available carrier package types.

Operations

Downloads

Download your label files in PDF, PNG, and ZPL.

Operations

Fulfillments

Manage fulfillments which represent completed shipments. Create fulfillments to mark orders as shipped with tracking information and notify customers and marketplaces.

Operations

Inventory

Manage inventory levels, warehouses, and locations.

Operations

Labels

Purchase and print shipping labels for any carrier active on your account. The labels endpoint also supports creating return labels, voiding labels, and getting label details like tracking.

Operations

Manifests

A manifest is a document that provides a list of the day's shipments. It typically contains a barcode that allows the pickup driver to scan a single document to register all shipments, rather than scanning each shipment individually.

Operations

Package Pickups

Scheduled pickups and manage pickup requests for supported carriers.

Operations

Package Types

Create custom package types to use for your shipments, rather than the carriers' default package types.

Operations

Products

Manage products in your ShipStation account. Products represent the items you sell and ship to customers.

Operations

Purchase Orders

Create and manage purchase orders from suppliers to replenish inventory. Track order status, receive products, and update inventory levels automatically.

Operations

List purchase orders

Request

Retrieve a paginated list of purchase orders with optional filtering by status, warehouse, dates, and other criteria.

Security
api_keys
Query
order_numberstring

Filter by order number

Example: order_number=02162026-02
statusstring

Filter by status

Enum"draft""open""receiving""received""cancelled""closed"
warehouse_idstring

Filter by warehouse ID

reference_numberstring

Filter by reference number

create_date_startstring(date-time)

Filter by creation date start (inclusive)

Example: create_date_start=2025-01-01T00:00:00Z
page_sizeinteger[ 1 .. 500 ]

Number of results per page

Default 50
curl -i -X GET \
  'https://docs.shipstation.com/_mock/openapi/v2/purchase_orders?order_number=02162026-02&status=draft&warehouse_id=string&reference_number=string&create_date_start=2025-01-01T00%3A00%3A00Z&page_size=50' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

The request was a success.

Bodyapplication/json
purchase_ordersArray of objects
totalinteger

Total number of purchase orders

Example: 150
pageinteger

Current page number

Example: 2
pagesinteger

Total number of pages

Example: 3
linksobject
Response
application/json
{
  "purchase_orders": [
    { … }
  ],
  "total": 150,
  "page": 2,
  "pages": 3,
  "links": {
    "first": { … },
    "next": { … }
  }
}

Create a new purchase order

Request

Create a new purchase order with products from a supplier.

Security
api_keys
Bodyapplication/jsonrequired
supplier_idstringrequired

Supplier identifier

Example: "se-567"
order_datestring(date-time)

Date when the order was placed

Example: "2025-01-15T00:00:00Z"
expected_delivery_datestring(date-time)

Expected delivery date

Example: "2025-02-01T00:00:00Z"
payment_termsstring

Payment terms for the order

Enum"none""cash_on_delivery""payment_on_receipt""payment_in_advance""net_7""net_15""net_30""net_45""net_60"
Example: "net_30"
payment_statusstring

Payment status for the order

Enum"none""unpaid""partially_paid""paid""refunded""credit_issued""other"
Example: "unpaid"
currency_codestring

ISO 4217 currency code

Default "USD"
Example: "USD"
shipping_carrierstring

Shipping carrier name

Example: "UPS"
tracking_numberstring

Tracking number for the shipment

Example: "1Z12345E1234567890"
reference_numberstring

Optional reference number

Example: "REF-12345"
warehouse_idstringrequired

Warehouse identifier

Example: "se-123456"
note_to_supplierstring

Note to include for the supplier

Example: "Please expedite delivery"
productsArray of objectsnon-emptyrequired

List of products in the purchase order

products[].​skustringrequired

SKU of the product

Example: "WIDGET-001"
products[].​supplier_skustring

Supplier's SKU for the product

Example: "SUPP-WIDGET-001"
products[].​quantityinteger>= 1required

Quantity to order

Example: 100
products[].​costnumber>= 0

Unit cost

Example: 9.99
curl -i -X POST \
  https://docs.shipstation.com/_mock/openapi/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
      }
    ]
  }'

Responses

Purchase order created successfully

Bodyapplication/json
purchase_order_idstring

Unique identifier for the created purchase order

Example: "se-234"
order_numberstring

Auto-generated order number

Example: "02162026-02"
supplier_idstring
Example: "se-567"
statusstring
Enum"draft""open""receiving""received""cancelled""closed"
Example: "draft"
order_datestring(date-time)
Example: "2025-01-15T00:00:00Z"
expected_delivery_datestring(date-time)
Example: "2025-02-01T00:00:00Z"
create_datestring(date-time)
Example: "2025-01-14T10:30:00Z"
modify_datestring(date-time)
Example: "2025-01-14T10:30:00Z"
payment_termsstring
Enum"none""cash_on_delivery""payment_on_receipt""payment_in_advance""net_7""net_15""net_30""net_45""net_60"
Example: "net_30"
payment_statusstring
Enum"none""unpaid""partially_paid""paid""refunded""credit_issued""other"
Example: "unpaid"
currency_codestring
Example: "USD"
shipping_carrierstring
Example: "UPS"
tracking_numberstring
Example: "1Z12345E1234567890"
reference_numberstring
Example: "REF-12345"
warehouse_idstring
Example: "se-123456"
note_to_supplierstring
Example: "Please expedite delivery"
productsArray of objects
Response
application/json
{
  "purchase_order_id": "se-234",
  "order_number": "02162026-02",
  "supplier_id": "se-567",
  "status": "draft",
  "order_date": "2025-01-15T00:00:00Z",
  "expected_delivery_date": "2025-02-01T00:00:00Z",
  "create_date": "2025-01-14T10:30:00Z",
  "modify_date": "2025-01-14T10:30: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": [
    { … }
  ]
}

Get purchase order details

Request

Retrieve detailed information about a specific purchase order including all products.

Security
api_keys
Path
purchase_order_idstringrequired

The purchase order identifier

Example: se-234
curl -i -X GET \
  https://docs.shipstation.com/_mock/openapi/v2/purchase_orders/se-234 \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

Purchase order details retrieved successfully

Bodyapplication/json
purchase_order_idstring
Example: "se-234"
order_numberstring
Example: "02162026-02"
supplier_idstring
Example: "se-567"
statusstring
Enum"draft""open""receiving""received""cancelled""closed"
Example: "open"
order_datestring(date-time)
Example: "2025-01-15T00:00:00Z"
expected_delivery_datestring(date-time)
Example: "2025-02-01T00:00:00Z"
create_datestring(date-time)
Example: "2025-01-14T10:30:00Z"
modify_datestring(date-time)
Example: "2025-01-14T10:30:00Z"
payment_termsstring
Enum"none""cash_on_delivery""payment_on_receipt""payment_in_advance""net_7""net_15""net_30""net_45""net_60"
Example: "net_30"
payment_statusstring
Enum"none""unpaid""partially_paid""paid""refunded""credit_issued""other"
Example: "unpaid"
currency_codestring
Example: "USD"
shipping_carrierstring
Example: "UPS"
tracking_numberstring
Example: "1Z12345E1234567890"
reference_numberstring
Example: "REF-12345"
warehouse_idstring
Example: "se-123456"
note_to_supplierstring
Example: "Please expedite delivery"
productsArray of objects
Response
application/json
{
  "purchase_order_id": "se-234",
  "order_number": "02162026-02",
  "supplier_id": "se-567",
  "status": "open",
  "order_date": "2025-01-15T00:00:00Z",
  "expected_delivery_date": "2025-02-01T00:00:00Z",
  "create_date": "2025-01-14T10:30:00Z",
  "modify_date": "2025-01-14T10:30: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": [
    { … }
  ]
}

Update a purchase order

Request

Update an existing purchase order.

Editing limitations:

  • In the draft status, all fields can be edited.
  • Once a purchase order moves to any other status (open, receiving, received, cancelled, or closed), updating via PUT is no longer allowed.
  • For purchase orders in open status, use the POST /v2/purchase_orders/{purchase_order_id}/shipping_details endpoint to update shipping-related details.
Security
api_keys
Path
purchase_order_idstringrequired

The purchase order identifier

Example: se-234
Bodyapplication/jsonrequired
supplier_idstringrequired
Example: "67890"
order_datestring(date-time)
Example: "2025-01-15T00:00:00Z"
expected_delivery_datestring(date-time)
Example: "2025-02-01T00:00:00Z"
payment_termsstring
Enum"none""cash_on_delivery""payment_on_receipt""payment_in_advance""net_7""net_15""net_30""net_45""net_60"
Example: "net_30"
payment_statusstring
Enum"none""unpaid""partially_paid""paid""refunded""credit_issued""other"
Example: "unpaid"
currency_codestring
Example: "USD"
shipping_carrierstring
Example: "UPS"
tracking_numberstring
Example: "1Z12345E1234567890"
reference_numberstring
Example: "REF-12345"
warehouse_idstringrequired
Example: "se-123456"
note_to_supplierstring
Example: "Please expedite delivery"
productsArray of objectsnon-emptyrequired
products[].​skustringrequired
Example: "WIDGET-001"
products[].​supplier_skustring
Example: "SUPP-WIDGET-001"
products[].​quantityinteger>= 1required
Example: 100
products[].​costnumber>= 0
Example: 9.99
curl -i -X PUT \
  https://docs.shipstation.com/_mock/openapi/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
      }
    ]
  }'

Responses

Purchase order updated successfully

Bodyapplication/json
purchase_order_idstring
Example: "se-234"
order_numberstring
Example: "02162026-02"
supplier_idstring
Example: "se-567"
statusstring
Enum"draft""open""receiving""received""cancelled""closed"
Example: "open"
order_datestring(date-time)
Example: "2025-01-15T00:00:00Z"
expected_delivery_datestring(date-time)
Example: "2025-02-01T00:00:00Z"
create_datestring(date-time)
Example: "2025-01-14T10:30:00Z"
modify_datestring(date-time)
Example: "2025-01-14T10:30:00Z"
payment_termsstring
Enum"none""cash_on_delivery""payment_on_receipt""payment_in_advance""net_7""net_15""net_30""net_45""net_60"
Example: "net_30"
payment_statusstring
Enum"none""unpaid""partially_paid""paid""refunded""credit_issued""other"
Example: "unpaid"
currency_codestring
Example: "USD"
shipping_carrierstring
Example: "UPS"
tracking_numberstring
Example: "1Z12345E1234567890"
reference_numberstring
Example: "REF-12345"
warehouse_idstring
Example: "se-123456"
note_to_supplierstring
Example: "Please expedite delivery"
productsArray of objects
Response
application/json
{
  "purchase_order_id": "se-234",
  "order_number": "02162026-02",
  "supplier_id": "se-567",
  "status": "open",
  "order_date": "2025-01-15T00:00:00Z",
  "expected_delivery_date": "2025-02-01T00:00:00Z",
  "create_date": "2025-01-14T10:30:00Z",
  "modify_date": "2025-01-14T10:30: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": [
    { … }
  ]
}

Update purchase order shipping details

Request

Update shipping-related details for a purchase order in open status.

Editing limitations:

  • Once a purchase order moves to any higher status (receiving, received, cancelled, or closed), updating shipping details is no longer allowed.
  • Only the following fields can be modified: shipping_carrier, payment_terms, payment_status, order_date, expected_delivery_date, note_to_supplier, tracking_number, currency_code, and reference_number.
Security
api_keys
Path
purchase_order_idstringrequired

The purchase order identifier

Bodyapplication/jsonrequired
order_datestring(date-time)
Example: "2025-01-15T00:00:00Z"
expected_delivery_datestring(date-time)
Example: "2025-02-01T00:00:00Z"
payment_termsstring
Enum"none""cash_on_delivery""payment_on_receipt""payment_in_advance""net_7""net_15""net_30""net_45""net_60"
Example: "net_30"
payment_statusstring
Enum"none""unpaid""partially_paid""paid""refunded""credit_issued""other"
Example: "unpaid"
currency_codestring
Example: "USD"
shipping_carrierstring
Example: "UPS"
tracking_numberstring
Example: "1Z12345E1234567890"
reference_numberstring
Example: "REF-12345"
note_to_supplierstring
Example: "Please expedite delivery"
curl -i -X POST \
  'https://docs.shipstation.com/_mock/openapi/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"
  }'

Responses

Purchase order shipping details updated successfully

Bodyapplication/json
purchase_order_idstring
Example: "se-234"
order_numberstring
Example: "02162026-02"
supplier_idstring
Example: "se-567"
statusstring
Enum"draft""open""receiving""received""cancelled""closed"
Example: "open"
order_datestring(date-time)
Example: "2025-01-15T00:00:00Z"
expected_delivery_datestring(date-time)
Example: "2025-02-01T00:00:00Z"
create_datestring(date-time)
Example: "2025-01-14T10:30:00Z"
modify_datestring(date-time)
Example: "2025-01-14T10:30:00Z"
payment_termsstring
Enum"none""cash_on_delivery""payment_on_receipt""payment_in_advance""net_7""net_15""net_30""net_45""net_60"
Example: "net_30"
payment_statusstring
Enum"none""unpaid""partially_paid""paid""refunded""credit_issued""other"
Example: "unpaid"
currency_codestring
Example: "USD"
shipping_carrierstring
Example: "UPS"
tracking_numberstring
Example: "1Z12345E1234567890"
reference_numberstring
Example: "REF-12345"
warehouse_idstring
Example: "se-123456"
note_to_supplierstring
Example: "Please expedite delivery"
productsArray of objects
Response
application/json
{
  "purchase_order_id": "se-234",
  "order_number": "02162026-02",
  "supplier_id": "se-567",
  "status": "open",
  "order_date": "2025-01-15T00:00:00Z",
  "expected_delivery_date": "2025-02-01T00:00:00Z",
  "create_date": "2025-01-14T10:30:00Z",
  "modify_date": "2025-01-14T10:30: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": [
    { … }
  ]
}

Update purchase order status

Request

Update the status of a purchase order. Valid status transitions must be followed.

Security
api_keys
Path
purchase_order_idstringrequired

The purchase order identifier

Example: se-234
Bodyapplication/jsonrequired
statusstringrequired

New status for the purchase order

Enum"open""receiving""received""cancelled""closed"
Example: "open"
curl -i -X POST \
  https://docs.shipstation.com/_mock/openapi/v2/purchase_orders/se-234/status \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "status": "open"
  }'

Responses

Status updated successfully

Bodyapplication/json
purchase_order_idstring
Example: "se-234"
statusstring
Enum"open""receiving""received""cancelled""closed"
Example: "open"
Response
application/json
{
  "purchase_order_id": "se-234",
  "status": "open"
}

Receive purchase order products

Request

Record receipt of products from a purchase order. This updates inventory levels and may automatically change purchase order status.

Security
api_keys
Path
purchase_order_idstringrequired

The purchase order identifier

Example: se-234
Bodyapplication/jsonrequired
product_receivesArray of objectsnon-emptyrequired

List of products being received

product_receives[].​skustringrequired

SKU of the product

Example: "WIDGET-001"
product_receives[].​inventory_location_idstringrequired

Location where inventory is received

Example: "se-12345"
product_receives[].​received_quantityinteger>= 1

Quantity received and accepted. At least one of received_quantity or rejected_quantity must be provided and greater than 0.

Example: 95
product_receives[].​rejected_quantityinteger>= 1

Quantity rejected (damaged, missing, etc.). At least one of received_quantity or rejected_quantity must be provided and greater than 0.

Example: 5
product_receives[].​lotstring

Lot number. Note - Availability depends on your ShipStation account plan.

Example: "LOT-2025-001"
product_receives[].​expiration_datestring(date-time)

Expiration date for the lot. Note - Availability depends on your ShipStation account plan.

Example: "2026-01-01T00:00:00Z"
curl -i -X POST \
  https://docs.shipstation.com/_mock/openapi/v2/purchase_orders/se-234/receives \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "product_receives": [
      {
        "sku": "WIDGET-001",
        "inventory_location_id": "se-12345",
        "received_quantity": 95,
        "rejected_quantity": 5,
        "lot": "LOT-2025-001",
        "expiration_date": "2026-01-01T00:00:00Z"
      }
    ]
  }'

Responses

Products received successfully

Bodyapplication/json
purchase_order_idstring
Example: "se-234"
statusstring
Enum"receiving""received"
Example: "receiving"
Response
application/json
{
  "purchase_order_id": "se-234",
  "status": "receiving"
}

Get purchase order summary PDF

Request

Download a PDF document containing the purchase order summary. Available for purchase orders with status: open, receiving, received, or closed.

Security
api_keys
Path
purchase_order_idstringrequired

The purchase order identifier

Example: se-234
curl -i -X GET \
  https://docs.shipstation.com/_mock/openapi/v2/purchase_orders/se-234/documents/order_summary \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

PDF document generated successfully

Bodyapplication/pdf
string(binary)
Response
No content

Get purchase order received summary PDF

Request

Download a PDF document containing the received products summary. Available for purchase orders with status: receiving, received, or closed.

Security
api_keys
Path
purchase_order_idstringrequired

The purchase order identifier

Example: se-234
curl -i -X GET \
  https://docs.shipstation.com/_mock/openapi/v2/purchase_orders/se-234/documents/received_summary \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

PDF document generated successfully

Bodyapplication/pdf
string(binary)
Response
No content

Rates

Quickly compare rates using the Rates endpoint. You can see and compare rates for the carriers connected to your account (as long as they support sending rates).

Operations

Shipments

Shipments are at the core of most ShipStation capabilities. Shipment objects are required for cretaing labels and manifests, as well as getting rates.

Operations

Suppliers

Manage supplier information including contact details, email addresses, and physical addresses. Suppliers are used when creating purchase orders.

Operations

Tags

Tags are text-based identifiers you can add to shipments to help in your shipment management workflows.

Operations

Totes

Manage totes (bins or containers) used in warehouse picking and packing operations. Create, update, delete totes and track tote quantities by warehouse.

Operations

Tracking

Use the tracking endpoint to stop receiving tracking updates (more dedicated tracking endpoint methods coming soon).

Operations

Warehouses

Get warehouse details like warehouse ID and related addresses using the warehouses endpoint.

Operations

Users

Manage and retrieve user information for the ShipStation account. This endpoint allows you to list users with various filtering options.

Operations

Webhooks

Webhooks are a powerful feature that can save you from sending repeated polling requests to check on the state of something. With webhooks, ShipStation will automatically contact your servers when the stage changes. This can include parcel tracking events, notification when a batch operation completes, and more.

Operations