Change Existing Order Items

HTTP Request

PUT /v1/orders/{orderId}/orderItems

Summary

Use this operation to change an order that has not yet been processed at the facility. You can change items and change quantities.

Request URLs

Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/fulfillment/v1/orders/{orderId}/orderItems
Production: https://shipping-api.pitneybowes.com/shippingservices/fulfillment/v1/orders/{orderId}/orderItems

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 (-), 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

The requested shipping-service details for 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

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

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, 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.

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.

updateDate

String

The date and time the order was updated in the client system, specified in the ISO 8601 format.

pbCreateDate

String

The date and time the order was created in the Pitney Bowes system, specified in the ISO 8601 format.

pbUpdateDate

String

The date and time the order was updated in the Pitney Bowes system, specified 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:

  • 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, 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

Notes associated with the order for internal reference, up to 255 characters.

dropShipInfo

Object

The billing address.

dropShipInfo.companyName

String

Name of the company.

dropShipInfo.address

String

Street address or P.O. Box.

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 PUT ".../v1/orders/{orderId}/orderItems" \
-H "Authorization: Bearer <oauth_token>" \
-H "X-PB-TransactionId: <unique_identifier>" \
-d '
{
    "clientId": "1234",
    "clientOrderId": "1643724181678",
    "orderLines": [ {
        "sku": "PRODUCT-SKU-001",
        "unitPrice": 10
        "quantity": 3
      },{
        "sku": "PRODUCT-SKU-985",
        "unitPrice": 8.0
        "quantity": 2
    } ]
}'

Sample Response

{
    "clientId": "1234",
    "clientOrderId": "1643724181678",
    "customerOrderId": "111-2212-1290877",
    "orderId": "ORDAA1267912211CO",
    "references": [ {
        "name": "REF1",
        "value": "jkjbmbbmbq1s"
    } ],
    "inputShippingDetails": {
        "carrier": "PITNEY BOWES",
        "serviceId": "NGSPS",
        "serviceName": "Newgistics Parcel Select",
        "trackingNumber": "95605332216"
    },
    "actualShippingDetails": {
        "carrier": "NGS",
        "serviceId": "NGSPS",
        "serviceName": "Newgistics Parcel Select"
    },
    "orderType": "eCom",
    "createDate": "<date>",
    "pbCreateDate": "<date>",
    "updateDate": "<date>",
    "pbUpdateDate": "<date>",
    "fromNode": "160",
    "shipOnDate": "<date>",
    "fulfillmentReleaseDate": "<date>",
    "promisedDeliveryDate": "<date>",
    "orderHandling": "X",
    "orderLines": [ {
        "lineId": 1,
        "sku": "PRODUCT-SKU-001",
        "unitPrice": 10.0,
        "orderedQuantity": 3.0,
        "lineTotal": 50
    },
    ...
    ],
    "orderCharges": {
        "orderCurrency": "USD",
        "shippingAmount": 16,
        "totalItemAmount": 74,
        "totalDutyAmount": 0,
        "totalTaxAmount": 9,
        "taxDetails": [ {
            "name": "SALES TAX",
            "fee": 9,
            "currency": "USD",
            "percentage": 0
        } ],
        "totalDiscountAmount": 5,
        "discountDetails": [ {
            "name": "COUPON",
            "fee": 5,
            "currency": "USD",
            "percentage": 0
        } ],
        "otherChargeDetails": [ {
            "name": "SUPPLIER_FEE",
            "fee": 0
        } ],
        "totalOrderAmount": 93
    },
    "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": true,
    "giftMessageText": "HAPPY THANKSGIVING",
    "customsInfo": {
        "customsDeclaredValue": 0,
        "importerCustomsReference": 0,
        "importerCustomsReferenceType": "TAXID"
    }
}

Error Codes

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