Create a Work Order

HTTP Request

POST /v1/work-orders

Summary

This operation creates a work order.

Request URLs

Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/fulfillment/v1/work-orders
Production: https://shipping-api.pitneybowes.com/shippingservices/fulfillment/v1/work-orders

Request Headers

Name

Description

Authorization

Required. OAuth token generated using the Generate an OAuth Token API.

X-PB-TransactionId

Required. A unique identifier for the request, up to 25 characters. The following characters are allowed: letters, numbers, hyphens (-), and underscores (_).

Important: Ensure this is a unique ID.

Request / Response Elements

This POST operation sends and receives the Work Orders object, described in the table below. The table describes the Work Orders object for all operations that use it. If a field is not used in this POST operation, it is marked as such.

Fields required in the request are marked Required. All other fields are optional, except fields marked RESPONSE ONLY, which appear only in the response.

Name

Data Type

Description

clientId

String

Required. The client ID assigned by Pitney Bowes.

clientWorkOrderId

String

Required. The work order ID assigned in the client system.

Maximum length: 35 characters

workOrderId

String

The work order ID assigned by Pitney Bowes.

workOrderName

String

Required. The name of the work order in the client system.

Maximum length: 30 characters

description

String

The work order description

Maximum length: 250 characters

type

String

Required. The type of work order. Possible value:

  • KIT

  • REFURBISHED (Reserved for future use.)

  • OTHER (Reserved for future use.)

status

String

RESPONSE ONLY. The order status. Possible values:

  • CREATED

  • INPROGRESS

  • CANCELED

  • CLOSED

  • COMPLETE

node

String

Required. The ID for the Pitney Bowes Fulfillment Center where work order is to be produced.

createDate

String

The date and time the work order was created in the client system, specified in the ISO 8601 format: YYYY-MM-DDThh:mm:ssZ

This field is not returned for Status Search.

updateDate

String

The date and time the work order was updated in the client system, specified in the ISO 8601 format: YYYY-MM-DDThh:mm:ssZ

This field is not returned for Status Search.

pbCreateDate

String

RESPONSE ONLY. The date and time the work order was created in the Pitney Bowes system, returned in the ISO 8601 format: YYYY-MM-DDThh:mm:ssZ

This field is not returned for Status Search.

pbCreateDate

String

RESPONSE ONLY. The date and time the work order was updated in the Pitney Bowes system, returned in the ISO 8601 format: YYYY-MM-DDThh:mm:ssZ

This field is not returned for Status Search.

sku

String

Required. The SKU for the produced kit. The kit must be part of the master catalog.

Maximum length: 30 characters

brand

String

The seller’s brand name for the item.

Maximum length: 50 characters

workOrderQuantity

Number

Required. The number of kits ordered.

priority

String

The priority of the work order. Possible values:

  • PRIORITY

  • STANDARD

This field is not returned for Status Search.

requestedStartDate

String

The date and time by which the work order should be started. Specify this in the ISO 8601 format: YYYY-MM-DDThh:mm:ssZ

This field is not returned for Status Search.

requestedCompletionDate

String

The date and time by which the work order should be completed. Specify this in the ISO 8601 format: YYYY-MM-DDThh:mm:ssZ

This field is not returned for Status Search.

The fields below do not apply to the Create or Update operations.

startDate

String

RESPONSE ONLY. Date the work order was started.

completionDate

String

RESPONSE ONLY. Date the work order was completed.

startQuantity

Number

RESPONSE ONLY. Start quantity of the work order.

completedQuantity

Number

RESPONSE ONLY. Quantity produced for the work order.

lotNumbers

Array[String]

RESPONSE ONLY. Completed Lot numbers for the produced product.

This field is not returned for Status Search.

serialNumbers

Array[String]

RESPONSE ONLY. Reserved for future use.

rejectedQuantity

Number

RESPONSE ONLY. Rejected quantity for the product.

This field is not returned for Status Search.

scrappedQuantity

Number

RESPONSE ONLY. Scrapped quantity for the product.

This field is not returned for Status Search.

workOrderLines

Array[Object]

RESPONSE ONLY. The child items.

This field is not returned for Status Search.

workOrderLines.childSKU

String

RESPONSE ONLY. The SKU of the child item. The item must be part of the master catalog.

workOrderLines.lotNumbers

Array[String]

RESPONSE ONLY. The completed lot numbers for the produced product.

workOrderLines.serialNumbers

Array[String]

RESPONSE ONLY. Reserved for future use.

workOrderLines.issuedQuantity

Number

RESPONSE ONLY. The issued quantity of the child product.

cancelDate

String

RESPONSE ONLY. If the work order was cancelled, the date the client cancelled the work order.

pbCancelDate

string

RESPONSE ONLY. The date the work order is cancelled in the Pitney Bowes system.

This field is not returned for Status Search.

cancelReason

string

RESPONSE ONLY. If the work order was cancelled, this gives the reason for cancellation.

This field is not returned for Status Search.

references

Array[Object]

RESPONSE ONLY. Reserved for future use.

references.name

String

RESPONSE ONLY. Reserved for future use.

references.value

String

RESPONSE ONLY. Reserved for future use.

Sample Request

curl -X POST ".../v1/work-orders" \
-H "Authorization: Bearer <oauth_token>" \
-H "X-PB-TransactionId: <unique_identifier>" \
-d '
{
    "clientId": "1234",
    "clientWorkOrderId": "W-284238",
    "workOrderName": "September Welcome Kit",
    "description": "September Welcome Kit",
    "type": "KIT",
    "node": "160",
    "createDate": "2021-08-30T16:07:49Z",
    "sku": "Product-210411",
    "workOrderQuantity": 2000,
    "priority": "PRIORITY",
    "requestedStartDate": "2021-08-30T16:07:49Z",
    "requestedCompletionDate": "2021-08-30T16:07:49Z"
}'

Sample Response

{
    "clientId": "1234",
    "clientWorkOrderId": "W-284238",
    "workOrderId": "WO1234A789117803242",
    "workOrderName": "September Welcome Kit",
    "description": "September Welcome Kit",
    "type": "KIT",
    "status": "CREATED",
    "node": "160",
    "createDate": "2021-08-30T09:07:49Z",
    "pbCreateDate": "2021-08-30T09:07:49Z",
    "sku": "Product-210411",
    "workOrderQuantity": 2000,
    "priority": "PRIORITY",
    "requestedStartDate": "2021-08-30T09:07:49Z",
    "requestedCompletionDate": "2021-08-30T09:07:49Z"
}

Error Codes

For lists of error codes returned by the Fulfillment APIs, please see 80-Prefix Error Codes (Fulfillment APIs).