DDS OMS API Reference

Author: Andrew Gee ( andrew.gee@ddshq.com)

Last amended: 19-Jun-2019

The OMS ( Order Management System) processes orders and forwards them to the relevant commercial system.

This document describes the OMS external API, which allows the caller to get stock availability and place orders.

This version of the API has been designed to work with the PFAC.com website.

API Endpoint
https://oms.ddshq.com
Schemes: http
Version: v2

Authentication

apiKey

All calls must have the &key= query string parameter included for authorisation. Failure to do so will result in a 401 unauthorised exception.

type
apiKey
name
key
in
query

Stock

Stock

Get stock availability.

GET /Stock
request.sku: string[]
in query

Stock keeping unit. Example: DELLP565

Array values passed as multiple parameters: ?request.sku=aaa&request.sku=bbb
request.branchCode: string
in query

The branch where the stock is being queried from. For example '302' is the Northwich branch.

200 OK
StockResult

OK

400 Bad Request
ErrorResponse

If an error occurs with the input parameters. For example if you omit a required property.

401 Unauthorized
ErrorResponse

Invalid authentication credentials - if you pass the wrong API key.

500 Internal Server Error
ErrorResponse

If some other lower low problem occurrs.

Response Content-Types: application/json, text/json, application/xml, text/xml
Response Example (200 OK) 
{
  "stockItems": [
    {
      "sku": "string",
      "freeStock": "integer (int32)"
    }
  ]
}
Response Example (400 Bad Request) 
{
  "message": "string",
  "modelState": "object"
}
Response Example (401 Unauthorized) 
{
  "message": "string",
  "modelState": "object"
}
Response Example (500 Internal Server Error) 
{
  "message": "string",
  "modelState": "object"
}

Order

Order

Submit an order to the commercial system.

POST /Order
Order

The order object that the caller sends to the OMS.

Request Content-Types: application/json, text/json, application/xml, text/xml, application/x-www-form-urlencoded
Request Example
{
  "orderNumber": "string",
  "externalReference": "string",
  "email": "string",
  "billingAddress1": "string",
  "billingAddress2": "string",
  "billingCity": "string",
  "billingCounty": "string",
  "billingCountry": "string",
  "billingPostcode": "string",
  "shippingName": "string",
  "shippingAddress1": "string",
  "shippingAddress2": "string",
  "shippingCity": "string",
  "shippingCompany": "string",
  "shippingCounty": "string",
  "shippingCountry": "string",
  "shippingPostcode": "string",
  "transactionReference": "string",
  "courierNotes": "string",
  "collectBranchCode": "string",
  "paymentMethod": "string",
  "vatCharged": "boolean",
  "telephone": "string",
  "orderItems": [
    {
      "sku": "string",
      "quantity": "integer (int32)",
      "price": "number (double)",
      "priceWithDiscount": "number (double)",
      "discountCode": "string"
    }
  ]
}
200 OK
OrderResult

OK

400 Bad Request
ErrorResponse

If an error occurs with the input parameters. For example if you omit a required property.

401 Unauthorized
ErrorResponse

Invalid authentication credentials - if you pass the wrong API key.

500 Internal Server Error
ErrorResponse

If some other lower low problem occurrs.

Response Content-Types: application/json, text/json, application/xml, text/xml
Response Example (200 OK) 
{
  "id": "string"
}
Response Example (400 Bad Request) 
{
  "message": "string",
  "modelState": "object"
}
Response Example (401 Unauthorized) 
{
  "message": "string",
  "modelState": "object"
}
Response Example (500 Internal Server Error) 
{
  "message": "string",
  "modelState": "object"
}

Schema Definitions

StockRequest: object

The request object for getting stock availability.

sku: string[]

Stock keeping unit. Example: DELLP565

string
branchCode: string

The branch where the stock is being queried from. For example '302' is the Northwich branch.

Example
{
  "sku": [
    "string"
  ],
  "branchCode": "string"
}

StockResult: object

The result object for getting stock availability.

stockItems: StockItem

The stock items that were requested.

StockItem
Example
{
  "stockItems": [
    {
      "sku": "string",
      "freeStock": "integer (int32)"
    }
  ]
}

StockItem: object

Represents a stock item, with its SKU and FreeStock.

sku: string

Stock keeping unit. Example: DELLP565

freeStock: integer (int32)

A count of how many items are in stock.

Example
{
  "sku": "string",
  "freeStock": "integer (int32)"
}

ErrorResponse: object

An object to hold details about any errors that may occur.

message: string

Information about the error.

modelState: object

Information about problems with the input parameters.

Example
{
  "message": "string",
  "modelState": "object"
}

Order: object

The order object that the caller sends to the OMS.

orderNumber: string

The caller's own order number.

externalReference: string

Any other suitable reference that applies to the order.

email: string
billingAddress1: string
billingAddress2: string
billingCity: string
billingCounty: string
billingCountry: string
billingPostcode: string
shippingName: string
shippingAddress1: string
shippingAddress2: string
shippingCity: string
shippingCompany: string
shippingCounty: string
shippingCountry: string

A factor in determining the account number to use when placing an order on the commercial system.

shippingPostcode: string
transactionReference: string

Set to the same as the orderNumber by convention but not used currently.

courierNotes: string

This is any special instructions to pass on to the courier, but it is not used currently.

collectBranchCode: string

If the order is a 'Click and Collect' order, this must be populated with the branch code for where the customer has chosen to collect from. For example '302' is the Northwich branch.

paymentMethod: string None, PayPal, CreditDebitCard, ClickAndCollect

A factor in determining the account number to use when placing an order on the commercial system.

vatCharged: boolean

A factor in determining the account number to use when placing an order on the commercial system.

telephone: string
orderItems: OrderItem
OrderItem
Example
{
  "orderNumber": "string",
  "externalReference": "string",
  "email": "string",
  "billingAddress1": "string",
  "billingAddress2": "string",
  "billingCity": "string",
  "billingCounty": "string",
  "billingCountry": "string",
  "billingPostcode": "string",
  "shippingName": "string",
  "shippingAddress1": "string",
  "shippingAddress2": "string",
  "shippingCity": "string",
  "shippingCompany": "string",
  "shippingCounty": "string",
  "shippingCountry": "string",
  "shippingPostcode": "string",
  "transactionReference": "string",
  "courierNotes": "string",
  "collectBranchCode": "string",
  "paymentMethod": "string",
  "vatCharged": "boolean",
  "telephone": "string",
  "orderItems": [
    {
      "sku": "string",
      "quantity": "integer (int32)",
      "price": "number (double)",
      "priceWithDiscount": "number (double)",
      "discountCode": "string"
    }
  ]
}

OrderItem: object

An item to be included in the order.

sku: string

Stock keeping unit. Example: DELLP565

quantity: integer (int32)

The quantity of the item that has been requested by the customer.

price: number (double)

The base price of the item.

priceWithDiscount: number (double)

The discounted price of the item.

discountCode: string

Any discount code that the customer applied to the item during the order process.

Example
{
  "sku": "string",
  "quantity": "integer (int32)",
  "price": "number (double)",
  "priceWithDiscount": "number (double)",
  "discountCode": "string"
}

OrderResult: object

The result of calling the order endpoint.

id: string

An ID generated by the OMS to uniquely identify this order. Note that this is NOT generated by the commercial system. It is merely an identifier generated and used by the OMS itself.

Example
{
  "id": "string"
}