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’).