Order API
Order materials and track orders and deliveries within your system. Retrieve order details and the status of upcoming deliveries to keep your team on track and your customers informed in real time.
The Place Order endpoint submits orders to a given ABC Supply branch. You can specify account numbers, dates, delivery appointments, pricing, product line items and comments and will return the confirmation number.
order API
Place Orders
POST /orders
Place orders to ABC Supply Branches
Sandbox
Production
Authorization
For Individuals and Businesses, use OAuth 2.0 server or user token with the order.write scope.
For Third-Party Aggregators, use OAuth 2.0 user token with the order.write scope.
Request
Name
Type
Description
requestId
string
A unique identifier provided by the client to track orders within the ABC Supply order processing system.
purchaseOrder
string
The purchase order related to the sales order.
branchNumber
string
The branch number.
deliveryService
enum
The type of delivery service for the order (e.g., “COM”: Common Carrier, “CPU”: Customer Pickup, “EXP”: Express Pickup, “OTR”: Our Truck Roof, “OTG”: Our Truck Ground, “OTW”: Our Truck Window, “TPC”: Third-Party Carrier).
typeCode
enum
The type code for the order. (e.g., “DR”: Direct Ship, “M”: Item Returns, “Report”: Measurement Reports, “SA”: Customer Pickup, “SO”: Sales Order).
dates
object
The object that describes delivery dates.
dates.deliveryRequestedFor
string
The date for which the delivery is requested.
deliveryAppointment
object
The object that describes the delivery appointment.
deliveryAppointment.instructionsTypeCode
string
The delivery appointment type. “AT”: Anytime Delivery, “AM”: Morning Delivery, “PM”: Afternoon Delivery, “FS”: First Stop Delivery, “ST”: Specific Time, “TR”: Time Range.
deliveryAppointment.instructions
string
The delivery instructions.
deliveryAppointment.fromTime
string
The earliest point of scheduled delivery in local military time (e.g., “13:00”). Required, but value only applies to Specific Time and Time Range.
deliveryAppointment.toTime
string
The latest point of scheduled delivery in local military time (e.g., “13:00”). Required, but value only applies to Time Range.
deliveryAppointment.timeZoneCode
string
The two-letter time zone code. “ET”: Eastern Time, “CT”: Central Time, “MT”: Mountain Time, “PT”: Pacific Time, “AT”: Alaska Time, “HT”: Hawaii-Aleutian Time.
referenceNumber
string
Sales order reference number. Required for product returns.
shipmentSequenceNumber
integer
The original shipment number for a returned item. Required for product returns.
shipTo
object
The object describing the ship-to information.
shipTo.name
string
A user-specified job name for reference.
shipTo.number
string
The unique ABC ship-to account number identifying the ship-to location receiving the item.
shipTo.address
object
The object describing the delivery address. If not supplied, the ship-to address on file is used.
shipTo.address.line1
string
This is the first line of the ship-to account’s address, usually including the street number and name.
shipTo.address.line2
string
This is the second line of the ship-to account’s address, which may include additional information like building numbers.
shipTo.address.line3
string
This is the third line of the ship-to account’s address, often used for more specific location information or additional directions.
shipTo.address.city
string
The ship-to city.
shipTo.address.state
string
The ship-to state.
shipTo.address.postal
string
The ship-to zip code.
shipTo.address.country
object
The ship-to country (e.g., “USA”).
shipTo.contacts
array
The list of contacts related to a ship-to.
shipTo.contacts[].name
string
The contact name.
shipTo.contacts[].functionCode
enum
The contact’s function code. “SO”: service order writer, “SM”: submitting contact, “DC”: delivery contact, “DI”: delivery/acknowledgement instructions, “CB” changed by.
“SM” is used by ABC Supply as the primary contact for order processing.
shipTo.contacts[].email
string
The contact email address.
shipTo.contacts[].phones
array
The list of phone numbers related to a contact.
shipTo.contacts[].phones[].number
string
The phone number.
shipTo.contacts[].phones[].type
string
The type of the phone (e.g., “MOBILE”).
shipTo.contacts[].phones[].ext
string
The phone extension if present.
orderComments
array
A list of comments that relate to the order.
orderComments[].description
string
The order comment text to display.
orderComments[].code
string
The code for the order comment (e.g., “H”: Header, “F”: Footer, “D”: Detailed).
lines
array
A list of lines that relate to an order’s items.
lines[].id
integer
A unique item identifier.
lines[].itemNumber
string
The item number.
lines[].itemDescription
string
The description of the item.
lines[].dimensions
object
The object describing the item’s dimensions. Required for items with length variations available.
lines[].dimensions.length
object
The object that describes the length of the item.
lines[].dimensions.length.uom
string
The unit of measurement of the item’s length.
lines[].dimensions.length.value
float
The value of the length dimension.
lines[].orderedQty
object
The object that describes the quantity of the item.
lines[].orderedQty.value
integer
The number of items ordered.
lines[].orderedQty.uom
string
The ordered quantity’s unit of measure.
lines[].unitPrice
object
The object that describes the item’s unit price.
lines[].unitPrice.value
float
The value of the item unit price.
lines[].unitPrice.uom
string
The unit of measure for the item unit price.
lines[].unitPrice.instructions
string
The instructions that relate to an item’s unit price.
lines[]. creditMemoOriginalSequenceId
integer
The line item number from the original order for a product return. Required for product returns.
lines[].comments
object
The object describing comments relating to a line item.
lines[].comments.code
enum
The code for the line comment (e.g., “H”: Header, “F”: Footer, “D”: Detailed, “notes”: General Notes ).
lines[].comments.description
string
The line comment text to display.
Example Request
Simple request for placing one order with one item number for an account at a given location.
[
{
"requestId": "12345",
"purchaseOrder": "999999-9",
"branchNumber": "595",
"deliveryService": "OTG",
"typeCode": "SO",
"dates": {
"deliveryRequestedFor": "2024-03-05"
},
"deliveryAppointment": {
"instructionsTypeCode": "AT",
"instructions": "Please leave in driveway",
"fromTime": "10:00",
"toTime": "11:00",
"timeZoneCode": "CT"
},
"currency": "USD",
"shipTo": {
"name": "Test Account",
"number": "123123",
"address": {
"line1": "123 Main St",
"line2": "Dock 123",
"line3": "Bldg. 1 Section 2",
"city": "Chicago",
"state": "IL",
"postal": "60661",
"country": "USA"
},
"contacts": [
{
"name": "John Doe",
"functionCode": "SM",
"email": "[email protected]",
"phones": [
{
"number": "8882221111",
"type": "MOBILE",
"ext": ""
}
]
},
{
"name": "Jane Doe",
"functionCode": "DC",
"email": "[email protected]",
"phones": [
{
"number": "8882221112",
"type": "MOBILE",
"ext": ""
},
{
"number": "8882221113",
"type": "WORK",
"ext": "1234"
},
{
"number": "8882221114",
"type": "FAX",
"ext": ""
}
]
},
{
"name": "Joe Doe",
"functionCode": "CB",
"email": "[email protected]",
"phones": [
]
}
]
},
"orderComments": [
{
"code": "H",
"description": "Order header comment here"
},
{
"code": "F",
"description": "Order footer comment here"
},
{
"code": "D",
"description": "Order detail comment here"
}
],
"lines": [
{
"id": "1",
"itemNumber": "0170030024",
"itemDescription": "Paint ABC Touch-UP Spray Black 12 OZ",
"orderedQty": {
"value": 3,
"uom": "CN"
},
"unitPrice": {
"value": 6.59,
"uom": "CN",
"instructions" : "Quote #123456"
},
"comments":
{
"code": "D",
"description": "Line comment text here"
}
},
{
"id": "2",
"itemNumber": "0170030023",
"itemDescription": "Paint ABC Touch-UP Spray White 12 OZ",
"orderedQty": {
"value": 10,
"uom": "CN"
},
"unitPrice": {
"value": 7.6,
"uom": "CN",
"instructions" : "Quote #123458"
},
"comments":
{
"code": "D",
"description": "Line comment text here"
}
}
]
}
]Response
Example Response
Response for a successfully submitted order.
{
"request": {
"batchId": "B11048723",
"recievedTime": "2024-12-06T15:40:51",
"ordersReceived": 1,
"ordersFailed": 0,
"ordersSucceded": 1
},
"orders": [
{
"requestId": "1733521251547",
"confirmationNumber": "C10-11917146",
"message": "Ordered successfully"
}
]
}Name
Type
Description
request
object
The object that describes the request.
request.batchId
string
ID for the order batch.
request.receivedTime
string
The date when order was received.
request.ordersReceived
integer
The number of orders received.
request.ordersFailed
integer
The number of orders that failed to process.
request.ordersSucceded
integer
The number of orders that were processed successfully.
orders
array
The list of orders.
orders[].requestId
string
The unique request tracking ID for the order.
orders[].confirmationNumber
string
The confirmation number for the order.
orders[].message
string
A message regarding the success or failure of order placement.
HTTP Status Codes
Code
Status
Description
202
Accepted
The request was successfully processed.
401
Unauthorized
Ship-To number or branch number are invalid for the user.
403
Forbidden
The required order.read scope is not present for the user.
400
Bad Request
Required fields are missing or improperly formatted. See the error message for details.
500
Internal Server Error
The server was unable to process the request.
Additional Examples
Example Request
Request for a Credit Memo (returned item):
[
{
"requestId": "1234567",
"purchaseOrder": "999999-9",
"branchNumber": "556",
"deliveryService": "OTG",
"typeCode": "M",
"referenceNumber": "1001028157",
"shipmentSequenceNumber": 1,
"dates": {
"deliveryRequestedFor": "2024-03-05"
},
"deliveryAppointment": {
"instructionsTypeCode": "AT",
"instructions": "Returning item - no delivery",
"fromTime": "12:00",
"toTime": "12:00",
"timeZoneCode": "CT"
},
"currency": "USD",
"shipTo": {
"name": "Test Account",
"number": "123123",
"address": {
"line1": "123 Main St",
"line2": "Dock 123",
"line3": "Bldg. 1 Section 2",
"city": "Chicago",
"state": "IL",
"postal": "60661",
"country": "USA"
},
"contacts": [
{
"name": "John Doe",
"functionCode": "SM",
"email": "[email protected]",
"phones": [
{
"number": "8882221111",
"type": "MOBILE",
"ext": ""
}
]
}
]
},
"orderComments": [
{
"code": "H",
"description": "Returning the following items"
}
],
"lines": [
{
"id": "1",
"itemNumber": "0170030024",
"itemDescription": "Paint ABC Touch-UP Spray Black 12 OZ",
"orderedQty": {
"value": 3,
"uom": "CN"
},
"unitPrice": {
"value": 6.59,
"uom": "CN",
"instructions" : "Quote #123456"
},
"creditMemoOriginalSequenceId": 2,
"comments":
{
"code": "D",
"description": "Item wrong color"
}
}
]
}
]