Order Request Fields - ShipRight

API  INTEGRATION

This is the list of all supported fields that our API accepts. You can see examples of the use of these fields in various scenarios here.

 

Field Part of Node Example Data Type Max Length Additional Notes
lineItems     Beginning of node.   Required
unitPrice lineItems 1.01 Decimal   Required, can be 0
itemCode lineItems COMP CHOCOLATES 1LB String 20 Required
quantity lineItems 1 Number   Required, must be > 0
                                                         
alternateOrderNumber   scenario_1 String 24 Optional, vendor specific
ownerCode   SR String 2 Required, valid value provided by SRS.
orderClass   DEFAULT String 18 Optional, defaults to ‘DEFAULT’
campaignCode   DEF String 10 Optional, defaults to ‘DEF’
discountApplied   0 Decimal   Required, dollar value, if a discount has been applied. Leave blank otherwise.
orderOrigination   phone String   Optional i
orderTotal   1.01 Decimal   Required ii
tax   0 Decimal   Optional
shippingAmount   0 Decimal   Required if the order total includes shipping. Leave blank otherwise.
shipVia   RG1 String 6 Required. Go here for common values. NOTE! If length is greater than 6 or the shipVia code is invalid, the API will set the code to a default of ‘RG1’.
orderDate   2014-03-12T16:00:00Z Date Time   Required, use W3C subset of ISO 8601 formats
PO     String 24 Optional
orderSourceId   5 String 1 Required, valid value provided by SRS.
userDefined1   Custom Data 1 String 30 Optional.  Contact ShipRight if you plan to use any User Defined fields.
userDefined2   Custom Data 2 String 30 Optional.  Contact ShipRight if you plan to use any User Defined fields.
userDefined3   Custom Data 3 String 30 Optional.  Contact ShipRight if you plan to use any User Defined fields.
shipToSameAsBillTo   true True/False   Required, true or false. Pass false if the orderedBy address is not the same as the shipTo address. If true, include a shiptTo node. It contains all the same fields in orderedBy.
orderedBy     Beginning of node.   Required
customerId orderedBy 9876543 Number   Optional iii
address orderedBy   Beginning of node.   Required
standardized orderedBy, address true True/False   Optional iv
email orderedBy, address bilbo@bagend.com String 100 Optional, but highly recommended. Note that a malformed email address results in a validation error.  If no email, leave blank.
attention orderedBy, address   String 35 Optional
address1 orderedBy, address LOBBY 2 String 35 Optional
address2 orderedBy, address 125 HIGH ST String 35 Required
city orderedBy, address BOSTON String 30 Required
region orderedBy, address MA String 35 Required
country orderedBy, address USA String 35 Required
postalCode orderedBy, address 02110-2770 String 10 Required
plus4 orderedBy, address   String 4 Optional.
                                                         
phones orderedBy   Beginning of node.   Optional
phoneType orderedBy, phones Mobile String   Optional, one of Daytime, Mobile, Work, Fax, Other
countryCode orderedBy, phones 123 String   Optional
areaCode orderedBy, phones   String   Optional
phoneNumber orderedBy, phones 1234567 String 15 Optional, use this if all you have is a single edit field for phone number.
                                                         
alternateCustomerNumber orderedBy bilbo_1 String   Optional
title         orderedBy Mr String 25 Optional
first orderedBy Bilbo String 25 Optional if fullName is not empty
middle orderedBy   String 25 Optional
last orderedBy Baggins String 25 optional if fullName is not empty
fullName orderedBy   String 35 Optional if first and last supplied
           
payment                                  Beginning of node.   Required v
paymentMethodCode payment I String 1 Required, valid codes provided by SRS. vi
prePaid payment true True/False   Required, true or false
paymentInstrumentType payment INVOICE String   Required, one of CREDITCARD, PAPERCHECK, ECHECK, INVOICE, PAYPAL, CASH

invoice/creditCard

 

 payment invoice”: { Beginning of node.   Required, payment method details, see Payment Objects

[i] orderOrigination is where the order originally came from, one of ‘none’, ‘phone’, ‘mail’, ‘web’, ‘other’. For example, if an order is placed over the phone and entered into a shopping cart, orderOrigination would be ‘phone’.

[ii] orderTotal must match the sum of all line item prices, tax and shippingAmount. If there was a discount applied, that needs to be accounted for as well in the orderTotal. If the orderTotal doesn’t match the sum, the order will be rejected for being out of balance.

[iii]If the order is placed by an existing customer and you have the customerId we assigned , you can include that to speed up processing. If the customer info is different than what we have in our database, it will be updated to match the new info you send us. Be aware that passing us an incorrect customerId could result in delaying the order or worse, updating the wrong customer. Be sure you are passing us the correct customerId, if you choose to use this feature.

[iv] The ShipRight Order API attempts to standardize incoming addresses. If successful, the standardized address is used for shipping and returned in the response. Included in the response is a field under address called standardized with a value of true if standardized and false otherwise. If possible, save the standardized address and set standardized to true in future requests, so the API will not attempt to standardize the address. This will speed up order processing.

[v] A payment node is required. The paymentMethodCode is specific to the kinds of payments a Merchant accepts and is issued by ShipRight. paymentInstrumentType is one of CREDITCARD, PAPERCHECK, ECHECK, INVOICE, PAYPAL, CASH. For each payment instrument type, a detail child node is required. See the Payment Objects page for more details and examples.

[vi] If a credit card is used for payment, paymentMethodCode indicates the card issuer, i.e. Visa, Amex, etc. Each issuer is assigned an issuer identification number (IIN) to uniquely identify it. The IIN consists of the first six digits of a card number. Therefore, the paymentMethodCode and the credit card number must agree. For example, if the paymentMethodCode indicates that the card was issued by Visa, then the first number of the card must be ‘4’. If the card number starts with any other number the API considers this a validation error (error message = ‘Invalid issuer identification number’).