Note

The Fulfillment APIs are coming soon.

Find Work Orders

HTTP Requests

This operation provides two requests.

Return all Work Order Data

POST /v1/work-orders/search

Summary

Use this operation to find work orders based on your search criteria. The operation provides two HTTP requests. The Return all Work Order Data request returns all fields in the Work Orders object for each result. The request to Return a Subset of Work Order Data (Status Search) returns a smaller payload focused on current status. See the Work Orders Object table for which fields are returned in the Status Search.

Request URLs

Return all Work Order Data

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

Return a Subset of Work Order Data (Status Search)

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

Query Parameters

Query parameters are optional.

Name

Description

page

The page number to return in the result set. Page numbering starts at 1.

Default value: 1

size

The number of results per page.

Default value: 20

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 Elements

The POST operation sends an object with the fields described here. Required fields are marked Required. All other fields are optional.

Name

Data Type

Description

clientId

String

Required. The client ID assigned by Pitney Bowes.

sort

Array[String]

The property upon which to sort and the sort order. Use the following syntax:

<property>-<sort_direction>

Where <property> is one of the following:

  • createDate

  • updateDate

And <sort_direction> is either of the following:

  • asc: ascending

  • desc: descending

For example: "createDate-asc"

searchFields

Array[Object]

The search criteria. Each object in the array defines a search field and search values. The object takes the following elements:

  • name: Required. The name of the search field, entered as a String. Possible values:

    • status

    • workOrderIds

    • createDate

    • updateDate

    • cancelDate

    • completionDate

    • pbCreateDate

    • pbUpdateDate

    • pbCancelDate

  • values. Required when “searchFields.name” is set to “status” or “workOrderIds”. This field takes a String array. Enter the values to search for as separate Strings in the array.

  • from. Applies when “searchFields.name” is set to one of the above date fields. Enter the start of the date range, as a String.

  • to. Applies when “searchFields.name” is set to one of the above date fields. Enter the end of the date range, as a String.

If no date filter is specified, the API returns orders created in the last six months.

Response Elements

The response returns an object with the fields described here.

Name

Data Type

Description

totalPages

Number

The number of pages in the result set.

totalElements

Number

The number of work orders in the result set.

first

Boolean

If true, this is the first page of the result set.

last

Boolean

If true, this is the last page of the result set.

size

Number

The number of work orders per page.

page

Number

The page number to return. Page numbering starts at 1.

sort

Array[String]

The sort order.

workOrders

Array[Work Orders Object]

The work orders. Each object in the array is a separate work order.

Work Orders Object

The workOrders array in the response contains the Work Orders object, described in the table below. (The table describes the Work Orders object for all operations that use it. Some fields in the table are labeled Required, meaning they are required in operations that send a payload.)

Depending on which HTTP request you use, this operation returns all Work Orders data or a subset of the data, as shown in the Sample Request to Return a Subset of Work Order Data.

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 Requests

See the following examples:

Sample Request to Return all Work Order Data

This request returns the full Work Orders object.

Example Request
curl -X POST ../v1/work-orders/search \
-H "Authorization: Bearer <oauth_token>" \
-H "X-PB-TransactionId: <unique_identifier>" \
-d '
{
    "clientId": "NGST",
    "sort": [
        "createDate-desc"
    ],
    "searchFields": [ {
        "name": "status",
        "values": [
            "CREATED",
            "INPROGRESS"
        ]
    },{
        "name": "Brands",
        "values": [
            "Acme"
        ]
    } ]
}'
Example Response
{
    "totalPages": 4,
    "totalElements": 78,
    "first": true,
    "last": false,
    "size": 20,
    "page": 1,
    "sort": [
        "createDate-desc"
    ],
    "workOrders": [ {
        "clientId": "NGST",
        "clientWorkOrderId": "W-284238",
        "workOrderId": "WO1234A789117803242",
        "workOrderName": "Welcome Kit",
        "description": "Welcome Kit",
        "type": "KIT",
        "status": "CREATED",
        "node": "160",
        "createDate": "2022-04-07T016:00:00-07:00",
        "pbCreateDate": "2022-04-07T18:58:19-07:00",
        "sku": "Product-210411",
        "workOrderQuantity": 2000,
        "priority": "PRIORITY",
        "requestedStartDate": "2022-04-08T09:00:00-07:00",
        "requestedCompletionDate": "2022-04-08T016:00:00-07:00",
        "lotNumbers": [
            "LOT#11-2321-1134553",
            "LOT#11-2321-1134556"
        ],
        "workOrderLines": [ {
                "childSKU": "Product-120445",
                "lotNumbers": [
                    "LOT#18-2321-245612",
                    "LOT#18-2321-245618"
                ],
                "issuedQuantity": 10000
            }, ... ]
    }, ... ]
}

Sample Request to Return a Subset of Work Order Data

This request, called a Status Search, returns a subset of the fields in the Work Orders object.

Example Request
curl -X POST ../v1/work-orders/status/search \
-H "Authorization: Bearer <oauth_token>" \
-H "X-PB-TransactionId: <unique_identifier>" \
-d '
{
    "clientId": "NGST",
    "sort": [
        "createDate-desc"
    ],
    "searchFields": [ {
        "name": "status",
        "values": [
            "CREATED",
            "INPROGRESS"
        ]
    },{
        "name": "Brands",
        "values": [
            "Acme"
        ]
    } ]
}'
Example Response
{
    "totalPages": 4,
    "totalElements": 78,
    "first": true,
    "last": false,
    "size": 20,
    "page": 1,
    "sort": [
        "createDate-desc"
    ],
    "workOrderStatusList": [ {
        "clientId": "NGST",
        "clientWorkOrderId": "W-284238",
        "workOrderId": "WO156A0029204893659052712",
        "workOrderName": "Welcome Kit",
        "description": "Welcome Kit",
        "type": "KIT",
        "status": "COMPLETE",
        "node": "160",
        "workOrderQuantity": 5000,
        "startDate": "2022-02-01T09:01:32Z”,
        "completionDate": "2022-02-01T09:07:54Z”,
        "startQuantity": 100,
        "completedQuantity": 100,
        "sku": "Product-210411"
    }, ... ]
}

Error Codes

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