Place Orders

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

POST /orders

Place orders to ABC Supply Branches

Sandbox

Resource:

POST

https://partners-sb.abcsupply.com/api/order/v2/orders

Production

Resource:

POST

https://partners.abcsupply.com/api/order/v2/orders

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 generated by the partner (client) to track orders within the system. This identifier can be in the form of a GUID (Globally Unique Identifier) or any other format chosen by the partner, and it is sent to us to facilitate order tracking.

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.

currency

string

The ISO 4217 currency code of the price amount.

referenceNumber

string

Sales order reference number. Required for product returns.

shipmentSequenceNumber

enum

Sales order shipment sequence number.

shipTo

object

The object describing the ship-to information.

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 ship to 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.

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 comment text.

orderComments[].code

string

The code for the order comment (e.g., “H”: Header, “F”: Footer, “D”: Detailed, “0”: Default). Defaults to “0” if no value provided.

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

enum

N/A

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 description of the comment.

Example Request

Simple request for placing one order with one item number for an account at a given location.

POST /api/order/v2/orders HTTP/1.1
Host: partners.abcsupply.com
Authorization: Bearer <TOKEN>
[
  {
    "trackingId": "9393939fn383n3393",
    "purchaseOrder": "PO-123456890",
    "branchNumber": "409",
    "deliveryService": "COM",
    "typeCode": "DR",
    "dates": {
      "deliveryRequestedFor": "2019-12-20"
    },
    "deliveryAppointment": {
      "instructionsTypeCode": "AT",
      "instructions": "Please leave in driveway",
      "fromTime": "10:00",
      "toTime": "11:00",
      "timeCode": "CT"
    },
    "currency": "USD",
    "shipTo": {
      "number": "12345678-100",
      "address": {
        "line1": "123 ABC Dr.",
        "line2": "",
        "line3": "Bldg. 1",
        "city": "Greenwood",
        "state": "IN",
        "postal": "46143",
        "country": "USA"
      },
      "contacts": [
        {
          "name": "John Doe",
          "functionCode": "SM",
          "email": "[email protected]",
          "phones": [
            {
              "number": "+13043651700",
              "type": "MOBILE",
              "ext": ""
            }
          ]
        },
        {
          "name": "Jane Doe",
          "functionCode": "DC",
          "phones": [
            {
              "number": "+13043651700",
              "type": "MOBILE",
              "ext": ""
            },
            {
              "number": "+13043651710",
              "type": "WORK",
              "ext": "1234"
            },
            {
              "number": "+13043651700",
              "type": "FAX",
              "ext": ""
            }
          ]
        }
      ]
    },
    "orderComments": [
      {
        "code": "O",
        "description": "Not to exceed 300lbs"
      },
      {
        "code": "O",
        "description": "Wood color"
      }
    ],
    "lines": [
      {
        "id": "1",
        "itemNumber": "N58XMR",
        "itemDescription": "GAF ENG ROY SOV CHARCOAL 3/S",
        "dimensions": {
          "length": {
            "uom": "ft",
            "value": 4.5
          }
        },
        "orderedQty": {
          "value": 1300,
          "uom": "PC"
        },
        "unitPrice": {
          "value": 365.01,
          "uom": "PC",
          "instructions": "Quote #123456"
        },
        "comments": {
          "code": "H",
          "description": "Not to exceed 300lbs"
        }
      }
    ]
  }
]

Expand

Response

Example Response

Response for a successfully submitted order.

{
    "request": {
        "batchId": "B9991487",
        "receivedTime": "2023-02-20T13:59:58.0330000Z",
        "ordersReceived": 1,
        "ordersFailed": 0,
        "ordersSucceded": 1
    },
    "orders": [
        {
            "requestId": "2020730-739d",
            "confirmationNumber": "C6-2720432",
            "message": "Ordered successfully"
        }
    ]
}

Expand

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

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

Name

Type

Description

503

string

Place orders service is not available.

500

string

Server error.

Additional Examples

Example Response

Response for an order failed to submit due to invalid JSON

{
    "message": "Bad Request - Invalid JSON"
}

Expand