Create an Order

HTTP Request

POST /v1/orders

Summary

This operation creates a single order.

Request URLs

Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/fulfillment/v1/orders
Production: https://shipping-api.pitneybowes.com/shippingservices/fulfillment/v1/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 Elements

Required fields are marked Required. All other fields are optional.

Name	Data Type	Description
clientId	String	Required. The client ID assigned by Pitney Bowes.
clientOrderId	String	Required. The order ID assigned by the client. Maximum length: 50 characters
customerOrderId	String	The customer-specific order number. Typically this is the order number from the website or ERP system. Maximum length: 50 characters
brand	String	The manufacturer’s brand name for the item. Maximum length: 50 characters
references	Array[Object]	Additional reference information for the order. Each object in the array is a name-value pair that defines a reference field and value.
references.name	String	The name of the reference field, up to 50 characters.
references.values	String	The value, up to 255 characters
salesChannel	Object	Reserved for future use.
inputShippingDetails	Shipping Details Object	Required. The requested shipping-service details for the order.
orderType	String	The type of order. Possible values: eCom (default) Retail
createDate	String	Required. The date and time the order was created in the client system, specified in the ISO 8601 format: YYYY-MM-DDThh:mm:ssZ
updateDate	String	The date and time the order was updated in the client system, specified in the ISO 8601 format: YYYY-MM-DDThh:mm:ssZ
fromNode	String	The warehouse facility ID.
shipOnDate	String	The date and time by which the order is promised to be shipped, specified in the ISO 8601 format: YYYY-MM-DDThh:mm:ssZ
fulfillmentReleaseDate	String	The date and time the order is to be released for fulfillment, specified in the ISO 8601 format: YYYY-MM-DDThh:mm:ssZ
promisedDeliveryDate	String	The date and time the order is promised to be delivered, specified in the ISO 8601 format: YYYY-MM-DDThh:mm:ssZ
orderHandling	String	Possible value: X: Normal (default) R: Rush order (Reserved for future use) E: Emergency order (Reserved for future use)
orderLines	Array[Order Lines Object]	Required. The items included in the order.
orderCharges	Order Charges Object	Cost details.
toAddress	Address Object	Required. The order’s destination address.
billingAddress	Address Object	The order’s billing address.
isGift	Boolean	If true, the order is a gift.
giftMessageText	String	The gift message to be printed on the pack slip and included in the shipment. Maximum length: 1,024 characters
valueAddedServices	Array[Object]	Reserved for future use.
paymentDetails	Array[Object]	Reserved for future use.
customsInfo	Object	Customs information for an international order.
customsInfo.customsDeclaredValue	Number	The value that is declared in customs.
customsInfo.importerCustomsReference	String	A reference number used by the importer, such as a VAT number, PO number, or insured number. Maximum length: 100 characters
customsInfo.importerCustomsReferenceType	String	The type of reference number. Maximum length: 50 characters
internalNotes	String	Any notes associated with the order for internal reference. Maximum length: 255 characters
dropShipInfo	Object	The billing address.
dropShipInfo.companyName	String	Name of the company. Maximum length: 50 characters
dropShipInfo.address	String	Street address or P.O. Box. Include the apartment number if applicable. You can specify up to three address lines. Maximum length: 100 characters
dropShipInfo.city	String	The city or town. Maximum length: 50 characters
dropShipInfo.state	String	The state or province. Maximum length: 50 characters
dropShipInfo.postalCode	String	The postal code or ZIP code. Maximum length: 20 characters

Response Elements

Name	Data Type	Description
clientId	String	The client ID assigned by Pitney Bowes.
clientOrderId	String	The order ID assigned by the client, up to 50 characters.
orderId	String	The order ID assigned by Pitney Bowes.
customerOrderId	String	The customer-specific order number. Typically this is the order number from the website or ERP system, up to 50 characters.
brand	String	The manufacturer’s brand name for the item, up to 50 characters.
references	Array[Object]	Additional reference information for the order. Each object in the array is a name-value pair that defines a reference field and value.
references.name	String	The name of the reference field, up to 50 characters.
references.values	String	The value, up to 255 characters
salesChannel	Object	Reserved for future use.
inputShippingDetails	Shipping Details Object	The requested shipping-service details for the order.
actualShippingDetails	Shipping Details Object	The actual shipping-service details set during processing of the order.
orderType	String	The type of order. Possible values: eCom (default) Retail
createDate	String	The date and time the order was created in the client system, specified in the ISO 8601 format: YYYY-MM-DDThh:mm:ssZ
updateDate	String	The date and time the order was updated in the client system, specified in the ISO 8601 format: YYYY-MM-DDThh:mm:ssZ
pbCreateDate	String	The date and time the order was created in the Pitney Bowes system, returned in the ISO 8601 format: YYYY-MM-DDThh:mm:ssZ
pbUpdateDate	String	The date and time the order was updated in the Pitney Bowes system, returned in the ISO 8601 format: YYYY-MM-DDThh:mm:ssZ
fromNode	String	The warehouse facility ID.
shipOnDate	String	The date and time by which the order is promised to be shipped, specified in the ISO 8601 format: YYYY-MM-DDThh:mm:ssZ
fulfillmentReleaseDate	String	The date and time the order is to be released for fulfillment, specified in the ISO 8601 format: YYYY-MM-DDThh:mm:ssZ
promisedDeliveryDate	String	The date and time the order is promised to be delivered, specified in the ISO 8601 format: YYYY-MM-DDThh:mm:ssZ
orderHandling	String	Possible value: X: Normal (default) R: Rush order (Reserved for future use) E: Emergency order (Reserved for future use)
orderLines	Array[Order Lines Object]	The items included in the order.
orderCharges	Order Charges Object	Cost details.
toAddress	Address Object	The order’s destination address.
billingAddress	Address Object	The order’s billing address.
isGift	Boolean	If true, the order is a gift.
giftMessageText	String	The gift message to be printed on the pack slip and included in the shipment, up to 1,024 characters.
valueAddedServices	Array[Object]	Reserved for future use.
paymentDetails	Array[Object]	Reserved for future use.
customsInfo	Object	Customs information for an international order.
customsInfo.customsDeclaredValue	Number	The value that is declared in customs.
customsInfo.importerCustomsReference	String	A reference number used by the importer, such as a VAT number, PO number, or insured number, up to 100 characters.
customsInfo.importerCustomsReferenceType	String	The type of reference number, up to 50 characters.
status	String	Status of the order. Possible values are: BACKORDER CANCELED HOLD INPROGRESS ONHOLD RECEIVED RETURNED SHIPPED
isOnHold	Boolean	If true, the order is on hold.
holdReason	Array[String]	Reason codes for the hold.
internalNotes	String	Any notes associated with the order for internal reference, up to 255 characters.
dropShipInfo	Object	The billing address.
dropShipInfo.companyName	String	Name of the company, up to 50 characters.
dropShipInfo.address	String	Street address or P.O. Box, up to 100 characters.
dropShipInfo.city	String	The city or town.
dropShipInfo.state	String	The state or province.
dropShipInfo.postalCode	String	The postal code or ZIP code.

Sample Request

curl -X POST ".../v1/orders" \
-H "Authorization: Bearer <oauth_token>" \
-H "X-PB-TransactionId: <unique_identifier>" \
-d '
{
    "clientId": "1234",
    "clientOrderId": "OR12345645678",
    "customerOrderId": "000-111-222-4444",
    "inputShippingDetails": {
        "carrier": "PITNEY BOWES",
        "serviceId": "PARCEL",
        "serviceName": "PARCEL SELECT",
        "trackingNumber": "9561234567"
    },
    "orderType": "eCom",
    "createDate": "2022-02-07T01:20:00Z",
    "fromNode": "160",
    "shipOnDate": "2022-02-08T01:20:00Z",
    "fulfillmentReleaseDate": "2022-02-09T01:20:00Z",
    "promisedDeliveryDate": "2022-02-10T01:20:00Z",
    "orderHandling": "E",
    "orderLines": [ {
        "lineId": 1,
        "sku": "0001-0001",
        "originCountryCode": "US",
        "originStateProvince": "CT",
        "unitPrice": 10,
        "orderedQuantity": 5,
        "lineTotal": 50,
        "inventoryType": "NEW"
    },
    ...
    ],
    "orderCharges": {
        "orderCurrency": "USD",
        "shippingAmount": 10,
        "totalItemAmount": 150,
        "dutyDetails": [ {
            "name": "COUPON",
            "fee": 5,
            "currency": "USD",
            "percentage": 1
        } ],
        "totalTaxAmount": 5,
        "taxDetails": [ {
            "name": "SALES TAX",
            "fee": 5,
            "currency": "USD",
            "percentage": 1
        } ],
        "totalDiscountAmount": 5,
        "discountDetails": [ {
            "name": "COUPON",
            "fee": 5,
            "currency": "USD"
        } ],
        "otherChargeDetails": [ {
            "name": "SUPPLIER_FEE",
            "fee": 0
        } ],
        "totalOrderAmount": 160
    },
    "toAddress": {
        "name": "John Smith",
        "company": "ABC",
        "phone": "111-111-1111",
        "email": "john@example.com",
        "addressLines": [
            "2352 Bent Creek Rd"
        ],
        "cityTown": "Auburn",
        "stateProvince": "AL",
        "postalCode": 36830,
        "countryCode": "US"
    },
    "billingAddress": {
        "name": "John Smith",
        "company": "ABC",
        "phone": "111-111-1111",
        "email": "john@example.com",
        "addressLines": [
            "2352 Bent Creek Rd"
        ],
        "cityTown": "Auburn",
        "stateProvince": "AL",
        "postalCode": 36830,
        "countryCode": "US"
    }
}'

Sample Response

{
    "clientId": "1234",
    "clientOrderId": "OR12345645678",
    "orderId": "ORA0008185936177270784US",
    "customerOrderId": "000-111-222-4444",
    "references": [],
    "inputShippingDetails": {
        "carrier": "PITNEY BOWES",
        "serviceId": "PARCEL",
        "serviceName": "PARCEL SELECT",
        "trackingNumber": "9561234567"
    },
    "orderType": "eCom",
    "createDate": "2022-02-07T01:20:00Z",
    "pbCreateDate": "2022-02-07T14:33:27-07:00Z",
    "fromNode": "160",
    "shipOnDate": "2022-02-08T01:20:00Z",
    "fulfillmentReleaseDate": "2022-02-09T01:20:00Z",
    "promisedDeliveryDate": "2022-02-10T01:20:00Z",
    "orderHandling": "E",
    "orderLines": [ {
        "lineId": 1,
        "sku": "0001-0001",
        "originCountryCode": "US",
        "originStateProvince": "CT",
        "unitPrice": 10.0,
        "orderedQuantity": 5,
        "lineTotal": 50.0,
        "inventoryType": "NEW"
    },
    ...
    ],
    "orderCharges": {
        "orderCurrency": "USD",
        "shippingAmount": 10.0,
        "totalItemAmount": 150.0,
        "dutyDetails": [ {
            "name": "COUPON",
            "fee": 5.0,
            "currency": "USD",
            "percentage": 1.0
        } ],
        "totalTaxAmount": 5.0,
        "taxDetails": [ {
            "name": "SALES TAX",
            "fee": 5.0,
            "currency": "USD",
            "percentage": 1.0
        } ],
        "totalDiscountAmount": 5.0,
        "discountDetails": [ {
            "name": "COUPON",
            "fee": 5.0,
            "currency": "USD"
        } ],
        "otherChargeDetails": [ {
            "name": "SUPPLIER_FEE",
            "fee": 0.0,
            "currency": "USD"
        } ],
        "totalOrderAmount": 160.0
    },
    "toAddress": {
        "name": "John Smith",
        "company": "ABC",
        "phone": "111-111-1111",
        "email": "john@example.com",
        "addressLines": [
            "2352 Bent Creek Rd"
        ],
        "cityTown": "Auburn",
        "stateProvince": "AL",
        "postalCode": "36830",
        "countryCode": "US"
    },
    "billingAddress": {
        "name": "John Smith",
        "company": "ABC",
        "phone": "111-111-1111",
        "email": "john@example.com",
        "addressLines": [
            "2352 Bent Creek Rd"
        ],
        "cityTown": "Auburn",
        "stateProvince": "AL",
        "postalCode": "36830",
        "countryCode": "US"
    },
    "isGift": false,
    "status": "RECEIVED",
    "isOnHold": false
}

Error Codes

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

 
 
 
 

• next
• previous |

© Copyright 2023 Pitney Bowes Inc. All rights reserved.