Note
The Fulfillment APIs are coming soon.
Update an Order¶
HTTP Request¶
PUT /v1/orders/{orderId}
Summary¶
This operation updates an order. You must pass the whole order object again to make the update. You cannot pass a partial object.
Request URLs¶
Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/fulfillment/v1/orders/{orderId}
Production: https://shipping-api.pitneybowes.com/shippingservices/fulfillment/v1/orders/{orderId}
Path Parameter¶
Name |
Description |
---|---|
orderId |
Required. The order ID assigned by Pitney Bowes. |
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 ( Important: Ensure this is a unique ID. |
Request / Response Elements¶
This PUT operation sends and receives the Orders object, described in the table below. 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. |
orderId |
String |
RESPONSE ONLY. The order 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[References Object] |
Additional reference information for the order. Each object in the array is a name-value pair that defines a reference field and value. |
salesChannel |
Object |
Reserved for future use. |
shippingDetails |
Required. The carrier details for the order. |
|
orderType |
String |
The type of order. Possible values:
|
createDate |
String |
Required. The date and time the order was created in the client system, specified in the ISO 8601 format: |
updateDate |
String |
The date and time the order was updated in the client system, specified in the ISO 8601 format: |
pbCreateDate |
String |
RESPONSE ONLY. The date and time the order was created in the Pitney Bowes system, returned in the ISO 8601 format: |
pbUpdateDate |
String |
RESPONSE ONLY. The date and time the order was updated in the Pitney Bowes system, returned in the ISO 8601 format: |
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: |
fulfillmentReleaseDate |
String |
The date and time the order is to be released for fulfillment, specified in the ISO 8601 format: |
promisedDeliveryDate |
String |
The date and time the order is promised to be delivered, specified in the ISO 8601 format: |
orderHandling |
String |
Possible value:
|
orderLines |
Array[Order Lines Object] |
Required. The items included in the order. |
orderCharges |
Cost details. |
|
toAddress |
Required. The order’s destination address. |
|
billingAddress |
The order’s billing address. |
|
isGift |
Boolean |
If |
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 |
status |
String |
RESPONSE ONLY. Status of the order. Possible values are:
|
isOnHold |
Boolean |
RESPONSE ONLY. If |
holdReason |
Array[String] |
RESPONSE ONLY. Reason codes for the hold. |
internalNotes |
String |
Any notes associated with the order for internal reference. Maximum length: 255 characters |
Sample Request¶
The following request changes the billingAddress
for an existing order.
curl -X POST .../v1/orders/ORA0007091203967291392US \
-H "Authorization: Bearer <oauth_token>" \
-H "X-PB-TransactionId: <unique_identifier>" \
-d '
{
"clientId": "NGST",
"clientOrderId": "1643749029194",
"customerOrderId": "111-212-1687792",
"references": [],
"shippingDetails": {
"carrier": "PITNEY BOWES",
"serviceId": "PARCEL",
"serviceName": "PARCEL SELECT",
"trackingNumber": "9560533222"
},
"orderType": "eCom",
"createDate": "2022-01-26T01:20:00Z",
"fromNode": "160",
"shipOnDate": "2022-01-27T01:20:00Z",
"fulfillmentReleaseDate": "2022-01-28T01:20:00Z",
"promisedDeliveryDate": "2022-01-30T01:20:00Z",
"orderHandling": "E",
"orderLines": [ {
"lineId": 1,
"sku": "1642787722",
"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": [
"643 Greenway Rd"
],
"cityTown": "Boone",
"stateProvince": "NC",
"postalCode": "28607",
"countryCode": "US"
},
"isGift": false
}'
Sample Response¶
{
"clientId": "NGST",
"orderId": "ORA0007091203967291392US",
"clientOrderId": "1643750157499",
"customerOrderId": "111-212-1687792",
"references": [],
"shippingDetails": {
"carrier": "PITNEY BOWES",
"serviceId": "PARCEL",
"serviceName": "PARCEL SELECT",
"trackingNumber": "9560533222"
},
"orderType": "eCom",
"createDate": "2022-01-26T01:20:00Z",
"pbCreateDate": "2022-01-26T22:31:00Z",
"pbUpdateDate": "2022-01-26T23:08:00Z",
"fromNode": "160",
"shipOnDate": "2022-01-27T01:20:00Z",
"fulfillmentReleaseDate": "2022-01-28T01:20:00Z",
"promisedDeliveryDate": "2022-01-30T01:20:00Z",
"orderHandling": "E",
"orderLines": [ {
"lineId": 1,
"sku": "1642787722",
"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": [
"643 Greenway Rd"
],
"cityTown": "Boone",
"stateProvince": "NC",
"postalCode": "28607",
"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).