API Specification

https://api-dev.cdslogistics.net/OrderManagementApi/swagger/v1/swagger.json

Authentication

Order Management API uses an OAuth 2 Identity Provider and bearer tokens for authentication. In order to access API endpoints, an access token has to be requested from the identity provider. Once an access token is requested and received, send the access token in a request header to gain access to the API endpoints.

Access Token

Request Access Token

To request an access token, send a POST request to the identity provider token endpoint https://id-dev.cdslogistics.net/connect/token Include fields below in the body of the request.

Field	Value	Description
`grant_type`	client_credentials	Standard OAuth 2 flow for machine to machine authentication.
`scope`	order_management_api:orders	Scopes gives your access token access to specific areas of the API. Each scope should be separated using a space.
`client_id`	<client-id>	Your organization’s unique API key.
`client_secret`	<client-secret>	Your organization’s unique client secret. This should be treated as a password and stored securely.
`response_type`	token	There are different types of tokens available. Token requests an access token to be returned.

Request parameters for a token request

POST https://id-dev.cdslogistics.net/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=order_management_api:orders&client_id=<client-id>&client_secret=<client-secret>&response_type=token

After submitting the request, a JSON response containing the access token and token expiration will be returned.

Property	Description
`access_token`	The full access token that should be sent to the Order Management API as a bearer token.
`expires_in`	Token lifetime in seconds.
`token_type`	The type of token returned. Will always be bearer.
`scopes`	API scopes that the token has access to. Should match what was requested in the initial request.

Use Access Token to Access API Endpoints

To use access token to gain access to API endpoints, the access token must be included in the Authorization request header as a bearer token in every request that is sent to the Order Management API. The Authorization header value should be in the format of Bearer <access-token> If the access token is missing, invalid or has expired, an HTTP 401 response will be returned. A HTTP 401 will also be returned if the Bearer prefix is not included in the Authorization header.

POST https://api-dev.cdslogistics.net/OrderManagementApi/order/submit
Authorization: Bearer <access-token>

API Endpoints

Submit Order

POST request to https://api-dev.cdslogistics.net/OrderManagementApi/order/submit This API endpoint is used to create and update orders. If an open order exists with the provided orderReferenceNumber, the order will be updated; otherwise, the order will be created. Request

orderReferenceNumber
- Unique number used to identify the order
- Required
- Maximum length: 30 characters
poNumber
- The customer po number for the order
- Optional
- Maximum length: 30 characters
billToCode
- Order bill to
- Optional
manufacturerCode
- Order manufacturer code
- Optional
cdsFacilityCode
- The CDS facility code of the facility delivering the order
- Required if useConsigneeAddressToDetermineFaclityCode = false
- Maximum length: 6 characters
useConsigneeAddressToDetermineFaclityCode
- A boolean flag used to indicate whether the CDS facility will be supplied directly or should be determined by the consignee address
- Required
- Must be true or false
consignee
- The final delivery address and contact information
- Required
- consigneeName
  - Name of the person or company
  - Required
  - Maximum length: 100 characters
- streetAddress
  - Street address where the order is to be delivered
  - Required
  - Maximum length: 40 characters
- city
  - City where the order is to be delivered
  - Required
  - Maximum length: 18 characters
- state
  - State where the order is to be delivered
  - Required
  - Maximum length: 2 characters
- zip
  - Zip code where the order is to be delivered
  - Required
  - Maximum length: 10 characters
- phone1
  - Primary phone number for the order
  - Required
  - Maximum length: 20 characters
- phone2
  - Alternative phone number for the order
  - Optional
  - Maximum length: 20 characters
- email
  - Email for the order
  - Optional
  - Maximum length: 30 characters
deliveryType
- The type of delivery of the order
- Optional
- Must be HOME, STORE, BUILD if provided
shipDate
- The date that the order will be shipped to the CDS facility
- Optional
estimatedReceiveDate
- The date that the order is expected to be received by the CDS facility
- Optional
requestedDeliveryDate
- The requested delivery date for the order
- Optional
intermediateConsignee
- Company and/or store that sold the order
- Optional
- Maximum length: 30 characters
freightDetails
- List of commodities that are included on the order
- Required
- Each item in the list will contain the following fields
  - commodity
    - The commodity code for the item
      - Request CDS Logistics what commodity code to use
    - Required
  - count
    - The count of the commodity
    - Required
    - Must be greater than 0
  - volume
    - The total volume of the commodity in cubic feet
    - Required
  - weight
    - The total weight of the commodity in pounds
    - Optional
barcoding
- Barcode information if available for the items on the order
  - Optional
  - receivingLoadNumber
    - Unique identifier for the inbound truck or trailer that the order will be included with
    - Required if barcode details are provided
    - Maximum length: 50 characters
  - barcodeItemDetails
    - List of barcode details for the order
    - Each item in the list will contain the following fields
      - commodity
        
        The commodity code for the item
        
        Request CDS Logistics what commodity code to use
        
        Must match commodity code used in freight details
        
        Required
      - barcode
        
        The unique barcode for the item
        
        Required
        
        Maximum length: 50 characters
      - count
        
        The count included under the unique barcode
        
        Required
        
        Must be greater than 0
      - description
        
        Description of the item
        
        Optional
        
        Maximum length: 80 characters
      - groupBarcode
        
        A barcode used for a group of items
        
        Optional
        
        Maximum length: 50 characters
otherReferenceNumbers
- List of reference numbers for the order
- Each item in the list will contain the following fields
  - type
    - The reference type for the order
    - Required
  - value
    - The reference value for the order
    - Required
deliveryInstructions
- Delivery instructions for the order
  - Optional
  - Maximum length: 254 characters

Cancel Order

POST request to https://api-dev.cdslogistics.net/OrderManagementApi/order/cancel This API endpoint is used to cancel an existing order. If an open order exists with the provided orderReferenceNumber, the order will be cancelled. Request

orderReferenceNumber
- Unique number used to identify the order
- Required
- Maximum length: 30 characters

Order Status

By Order Reference Number

GET request to https://api-dev.cdslogistics.net/OrderManagementApi/order/status?orderReferenceNumber={customer_order_number}

By System Number

GET request to https://api-dev.cdslogistics.net/OrderManagementApi/order/status?systemNumber={cds_order_number} This API endpoint is used to get the first open order with a matching CRN (Customer Reference Number) or System Number (CDS Order Number). If there are no open orders for the customer billto, it returns the latest closed order for the customer billto. If there are no matching orders, it checks if there is a matching order in the order processing queue and returns that information. If no matching queue items, order is not found. Request

orderReferenceNumber
- Unique number used to identify the order
- Required
- Maximum length: 30 characters
systemNumber
- Unique number used to identify the order
- Required
- Data Type: Integer

Response Payload Status All available statuses are listed below.

In Import Queue
Pending Receipt
Received
Out for delivery
Complete
Cancelled

​API Specification

​Authentication

​Access Token

​Request Access Token

​Use Access Token to Access API Endpoints

​API Endpoints

​Submit Order

​Cancel Order

​Order Status

​By Order Reference Number

​By System Number