Note

The Fulfillment APIs are coming soon.

Find Products

HTTP Request

POST /v1/products/search

Summary

This operation searches for products in the master catalog.

Request URLs

Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/fulfillment/v1/products/search
Production: https://shipping-api.pitneybowes.com/shippingservices/fulfillment/v1/products/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 to return 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 request 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 identifier 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

  • pbCreateDate

  • pbUpdateDate

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 is a name-value pair with the following two elements:

name: The field in the Products object upon which to search, entered as a String.

values: The values to search for, entered as an array. The array takes the data type of the field being searched.

You can search on the following Products-object fields. For possible values, see the field’s definition here:

  • active

  • createDate

  • fulfillmentRegion

  • pbCreateDate

  • pbUpdateDate

  • sku

  • updateDate

  • vendorDetails.name. To search this field, set “searchFields.name” to “vendorName”.

If no date filter is specified, the API returns products 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 products 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 products per page in the result set.

page

Number

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

sort

Array[String]

The sort order.

products

Array[Products Object]

The products. Each object in the array is a separate product.

Products Object

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

Name

Data Type

Description

clientId

String

Required. The client ID assigned by Pitney Bowes.

vendorDetails

Object

vendorDetails.name

String

Name of the vendor.

Maximum length: 50 characters

vendorDetails.number

String

The vendor identifier.

Maximum length: 30 characters

productType

String

Required. Identifies the product as one of the following:

  • ITEM

  • KIT

sku

String

Required. The SKU used to track the product in the warehouse.

Maximum length: 30 characters

createDate

String

The date the product was created in the client system, specified in the ISO 8601 format:

YYYY-MM-DDThh:mm:ss.sss±hhmm

updateDate

String

The date the product was modified in the client system, specified in the ISO 8601 format:

YYYY-MM-DDThh:mm:ss.sss±hhmm

pbCreateDate

String “readOnly”: true

RESPONSE ONLY. The date the product was created in the Pitney Bowes system, specified in the ISO 8601 format:

YYYY-MM-DDThh:mm:ss.sss±hhmm

pbUpdateDate

String

RESPONSE ONLY. The date the order was created in the Pitney Bowes system, specified in the ISO 8601 format:

YYYY-MM-DDThh:mm:ss.sss±hhmm

fulfillmentRegion

String

Where the product is sent for fulfillment. Possible values:

  • PB_ONLY (default)

  • THIRD_PARTY (Reserved for future use)

  • ALL (Reserved for future use)

details

Product Details Object

Required.

options

Array[Object]

Defines available options for the product.

options.name

String

A product option. Possible values:

  • COLOR

  • MODEL

  • SIZE

  • STYLE

options.code

String

A selectable code for the specified option, such as a style code or color code.

Maximum length: 8 characters

options.description

String

A description of the option.

Maximum length: 35 characters

active

Boolean

The status of the product. If true, the product is active. If false, the product is inactive.

status

String

Possible values:

  • PUBLISHED (default)

  • UNPUBLISHED

shippingAttributes

Object

shippingAttributes.shipsAlone

Boolean

The product is a ship alone.

Default value: false

shippingAttributes.dropShip

Boolean

The product is fulfilled by drop shipper.

Default value: false

shippingAttributes.safetyFactor

Number

Reserved for future use.

returnParameters

returnParameters.returnable

Boolean

Indicates whether the product can be returned.

Default value: true

returnParameters.returnWindow

Number, up to 1 decimal place

The number of days allowed for returns. To indicate no limit, enter 0.

prePackagedBoxQuantity

Number

The number of units in a prepackaged box.

physicalUnitDetails

Object

The product’s weight and dimensions.

physicalUnitDetails.weight

Number, up to 4 decimal places

Weight.

physicalUnitDetails.weightUOM

String

The unit of measurement for the product’s weight. Possible value:

  • LB: Pounds

physicalUnitDetails.dimensions

Dimensions Object

The product’s dimensions.

physicalCaseDetails

Object

physicalCaseDetails.caseWeight

Number, up to 4 decimal places

The weight of one item of this type of commodity.

physicalCaseDetails.unitOfMeasurement

String

The unit of measurement for the commodity’s weight. Possible value:

  • LB: Pounds

physicalCaseDetails.caseDimension

Dimensions Object

The case dimensions.

physicalCaseDetails.standardQuantity

Number, up to 1 decimal place

Standard case quantity for this SKU, must be greater than 0.

inventoryParameters

Inventory Parameters Object

additionalLanguageSupport

Array[Object]

additionalLanguageSupport.reference

String

The locale for additional language support on the packing slip. For example: FR_CA, ES_MX, DE_DE, etc.

Maximum length: 10 characters

additionalLanguageSupport.value

String

The description of the product for the specified locale.

Maximum length: 255 characters

Sample Request

curl -X POST ../v1/products/search?size=20&page=1
-H "Authorization: Bearer <oauth_token>" \
-H "X-PB-TransactionId: <unique_transaction_id>" \
-d '
{
    "clientId": "NGST",
    "sort": [
        "createDate-asc"
    ],
    "searchFields": [ {
        "name": "active",
        "values": [ "true" ]
    } ]
}'

Sample Response

{
    "totalPages": 4,
    "totalElements": 76,
    "first": true,
    "last": false,
    "size": 20,
    "page": 1,
    "sort": [
        "createDate-asc"
    ],
    "products": [ {
        "clientId": "NGST",
        "productType": "KIT",
        "sku": "1642787604",
        "pbCreateDate": "2022-01-21T11:19:59-07:00",
        "fulfillmentRegion": "PB_ONLY",
        "details": {
            "description": "vintage floral-print dress",
            "hsClassification": [ {
                "hsTariffCode": "640442",
                "countryCode": "IN"
        } ],
            "priceCurrency": "USD"
        },
        "active": true,
        "status": "PUBLISHED",
        "shippingAttributes": {
            "shipsAlone": false,
            "dropShip": false,
            "safetyFactor": 1
        },
        "returnParameters": {
            "returnable": true,
            "returnWindow": 0
        },
        "prePackagedBoxQuantity": 10,
        "inventoryParameters": {
            "lotTracked": false,
            "expiryDateTracked": false,
            "expiryWindow": 90,
            "serialTracked": false,
            "fragile": false,
            "temperatureControlled": false,
            "highValue": false,
            "requiresQuarantine": false
        }
    }, ... ],
}

Error Codes

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