REST API Specification

Open API Specification

Get started with our interactive OpenAPI documentation! You can retrieve JSON object definitions and experiment with API methods and payloads.

What is OpenAPI?

DISCLAIMER: Our OpenAPI spec is in progress. You may observe frequent/significant changes as we convert this documentation to that spec. The OpenAPI spec is not fully functional yet. All methods require X-Ctl-ClientId and X-Ctl-UserId headers, so please reach out to your CTL representative if you have not been provided with those values.

Usage guidelines

This API was designed to be robust and performs as much validation up front as possible. If a validation error is detected, a 400 Bad Request response will be sent back with specifics shown in the body. This allows a high degree of confidence that an order, if accepted by the API, will be able to ship.

Character encoding of a request will be respected, and assumed to be UTF-8 if not specified. Unless otherwise specified this API will accept any printable Unicode text when it comes to string values. Control characters other than whitespace will generally cause a validation error.

Using a client with full HTTP pipelining support is encouraged to ensure optimal throughput.

Bulk retrieval

This API is capable for retrieving bulk data. To prevent bloating responses and memory usage, results are limited in size and may necessitate multiple operations.

There are two models for bulk retrieval: streaming, and paged.

Streaming results

Streaming is intended for data that will not change over time: the API allows you to peek into any point in the stream, and is designed with the assumption that you will keep track of your position over time and use it to sync data from CTL into your systems.

APIs supporting streaming will have a fromUpdateId parameter, and each result returned will have an UpdateIndex value. After retrieving the first page of data, you can pass in the next UpdateIndex value to retrieve from.

For an example of how to work with streaming results, see the Querying new shipments sample.

Paged results

Paging is used for data that will potentially change over time. A good example of this might be search results. When first queried, a snapshot of the results are cached and paged, and you have a limited time to retrieve the pages before the query expires.

Paged results return a CollectionKey which you can use to construct a pageKey parameter pased into subsequent calls.

For an example of how to work with paged results, see the Querying for a large amount of orders sample.

Authorization

In this API, data is associated with a Client ID. To access the client's data, one or more users are assigned a User ID. Authorization is done by including both of these keys as request headers. These keys will be provided by CTL and must be present for every request unless otherwise noted.

PUT /v1/Orders/1234 HTTP/1.1
Content-Type: application/json; charset=utf-8
X-Ctl-ClientId: xxxx
X-Ctl-UserId: xxxx

Validation and error handling

Errors are communicated via HTTP response codes. Every operation in this document defines possible response codes. When a 400 Bad Request is received, this means input validation has failed. The body of the response will consist of a simple object telling you why:

{
   "Message": "A validation error occurred.",
   "ModelState": {
      "ShipTo.Addr1": "The Addr1 field is required",
      "JobNumber": "The field JobNumber must be a string with a maximum length of 25."
   }
}

Operations

Retrieving available clients

A user may have access to multiple clients. This API lists all the clients available to a user.

For this API, only the X-Ctl-UserId header is required.

Sample request

PUT /v1/Clients HTTP/1.1                
X-Ctl-UserId: xxxx

Sample response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "Id": "f2c19252-855d-434d-bbbf-b7b600ac36a3",
    "Name": "sample string 2"
  },
  {
    "Id": "f2c19252-855d-434d-bbbf-b7b600ac36a3",
    "Name": "sample string 2"
  }
]

Request

GET /v1/Clients

Response content

A list of Client objects.

Response codes

Code	Meaning
200 OK	A list of clients has been returned.
404 Not Found	The given user was not found or has no available clients.
503 Service Unavailable	There is a temporary error preventing the request from completing. The client should retry the request at a later time.

Client object

{
  "Id": "f2c19252-855d-434d-bbbf-b7b600ac36a3",
  "Name": "sample string 2"
}

Key	Type	Required	Description
Id	string	yes	The client ID used for API access.
Name	string	yes	The client's name.

Retrieving available carriers

This endpoint retrieves carriers and shipping services available for orders.

In the OMS, carriers and service levels are identified under one collection. Rather than "UPS" and "Ground", for instance, there is a single carrier of "UPS Ground".

Sample request

GET /v1/Carriers HTTP/1.1                
X-Ctl-UserId: xxxx
X-Ctl-ClientId: xxxx

Sample response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[
  {
    "Id": "f2c19252-855d-434d-bbbf-b7b600ac36a3",
    "Name": "sample string 2"
  },
  {
    "Id": "f2c19252-855d-434d-bbbf-b7b600ac36a3",
    "Name": "sample string 2",
    "StandardAlphaCode": "UPSC",
    "AddressFieldSizes": {
      "Attention": 35,
      "Name": 35,
      "Address1": 35,
      "Address2": 35,
      "Address3": 35,
      "City": 30,
      "StateOrProvince": 30,
      "PostalCode": 20,
      "CountryCode": 2,
      "PhoneNumber": 30,
      "Ref1": 30,
      "Ref2": 30,
      "Ref3": 30,
      "Ref4": 30,
      "Ref5": 30
    }
  }
]

Request

GET /v1/Carriers

Response content

A list of Carrier objects.

Response codes

Code	Meaning
200 OK	A list of carriers has been returned.
401 Unauthorized	The given client/user ID is not present in the OMS.
404 Not Found	No carriers are available for this client.
503 Service Unavailable	There is a temporary error preventing the request from completing. The client should retry the request at a later time.

Carrier object

{
  "Id": "f2c19252-855d-434d-bbbf-b7b600ac36a3",
  "Name": "sample string 2",
  "StandardAlphaCode": "USPC"
  "AddressFieldSizes": {}
}

Key	Type	Required	Description
Id	string	yes	The carrier ID.
Name	string	yes	The carrier / service level.
StandardAlphaCode	string		The freight carrier's SCAC, if applicable.
Address Field Sizes	Address Field Sizes object		The Address field maximum lengths for this carrier

Address Field Sizes object

{
      "Attention": 35,
      "Name": 35,
      "Address1": 35,
      "Address2": 35,
      "Address3": 35,
      "City": 30,
      "StateOrProvince": 30,
      "PostalCode": 20,
      "CountryCode": 2,
      "PhoneNumber": 30,
      "Ref1": 30,
      "Ref2": 30,
      "Ref3": 30,
      "Ref4": 30,
      "Ref5": 30
    }

Key	Type	Description
*	int	All fields describe the maximum length of the respective field in the Address object

Adding sales orders

This API provides a robust method to add orders.

In the event of a timeout, it is impossible to know the status of an order. Recognizing that the internet can occasionally be an unreliable environment, sync automation should build in retry logic: if the previous request succeeded, the API will return a 409 Conflict error. Otherwise it will return 201 Created as normal.

In fact, the API is built so that it is always safe to re-submit an order even if the request didn't fail.

Sample request

PUT /v1/Orders/{id} HTTP/1.1                
Content-Type: application/json; charset=utf-8
X-Ctl-ClientId: xxxx
X-Ctl-UserId: xxxx

{
  "CarrierId": "2436EBED-1304-4B7A-A587-40F7A4AAD49B",
  "DateOrdered": "2014-09-03T15:23:34+05:00",
  "ShipTo": {
    "Attention": "sample string 1",
    "Name": "sample string 2",
    "Address1": "sample string 3",
    "Address2": "sample string 4",
    "City": "sample string 5",
    "StateOrProvince": "sample string 6",
    "PostalCode": "sample string 7",
    "CountryCode": "sample string 8",
    "Email": "sample string 9",
    "PhoneNumber": "sample string 10"
  },  
  "Items": [
    {
      "Sku": "sample string 1",
      "Quantity": 2,
      "DeclaredValuePerEach": 49.99,
      "Variables": [
        {
          "Key": "sample string 1",
          "Value": "sample string 2"
        },
        {
          "Key": "sample string 1",
          "Value": "sample string 2"
        }
      ]
    },                
    {
      "Sku": "sample string 1",
      "Quantity": 2,
      "DeclaredValuePerEach": null,
      "Variables": [
        {
          "Key": "sample string 1",
          "Value": "sample string 2"
        },
        {
          "Key": "sample string 1",
          "Value": "sample string 2"
        }
      ]
    },
  ],
  "Variables": [
    {
      "Key": "sample string 1",
      "Value": "sample string 2"
    },
    {
      "Key": "sample string 1",
      "Value": "sample string 2"
    }
  ]
}

Sample response

HTTP/1.1 201 Created

Request

PUT v1/Orders/{id}

Request parameters

Name	Description
{id}	The order's ID.

Body parameters

An Order object.

Response codes

Code	Meaning
201 Created	The order has been created.
400 Bad Request	The order data has failed validation and must be corrected. See Validation and error handling for more information.
401 Unauthorized	The given client/user ID is not present in the OMS.
409 Conflict	An order with that ID already exists and may not be updated.
503 Service Unavailable	There is a temporary error preventing the request from completing. The client should retry the request at a later time.

Order object

{
  "CarrierId": "2436EBED-1304-4B7A-A587-40F7A4AAD49B",
  "StreamId": "a90ae5ad-5043-415c-824f-ccec81a7cfde",
  "ThirdPartyShipAccount" : "sample string 1",
  "ThirdPartyShipBillTo": Address object,
  "JobNumber": "sample string 2",
  "PurchaseNumber": "sample string 3",
  "DateOrdered": "2014-09-03T15:23:34+05:00",
  "Comments": "sample string 4",
  "BillTo": Address object,
  "ShipToAddressId": "sample string 5",
  "ShipTo": Address object,
  "ShippingPaymentType": "Prepaid",
  "Items": [
                        OrderItem object,
                        OrderItem object
  ],
  "Variables": [
                        OrderVariable object,
                        OrderVariable object
  ]
}

Key	Type	Maximum length	Required	Description
CarrierId	string			A carrier ID. If not specified, a default carrier will be chosen by the OMS.
StreamId	string			A stream ID. If not specified, a default stream will be chosen by the OMS. Used to indicate different account types, corresponds to a ZZ- customer.
DateOrdered	string			The date the customer placed the order. Must be a valid ISO 8601 date and may include an offset. Typically printed on packing slips.
Comments	string			A string of comments. Typically printed on packing slips.
ShipFromDate	string			Must be a valid ISO 8601 date. Any time portion of the date will be ignored. If part of our business rules agreement, CTL will ensure your package ships on or after this date.
ShipByDate	string			Must be a valid ISO 8601 date. Any time portion of the date will be ignored. If part of our business rules agreement, CTL will ensure your package ships before or on this date.
DeliverFromDate	string			Must be a valid ISO 8601 date. Any time portion of the date will be ignored. If part of our business rules agreement, CTL will ensure your package delivers on or after this date.
DeliverByDate	string			Must be a valid ISO 8601 date. Any time portion of the date will be ignored. If part of our business rules agreement, CTL will ensure your package delivers before or on this date.
BillTo	An Address object			The customer's billing address. Typically shown on a packing slip. If not specified, the ship-to address will be used.
ShipToAddressId	string			A preconfigured address to use as the shipping address. If specified, ShipTo must be left null or unspecified.
ShipTo	An Address object			The order's ship to address may be left off initially, but must be present before an order can process and ship.
ShippingPaymentType	string			PENDING. Leave null.
ThirdPartyShipAccount	string	20		If third-party shipping is being used, the account number.
ThirdPartyShipBillTo	An Address object			If third-party shipping is being used, the billing address to use.
JobNumber	string	25		A job number this order is associated with. Not used for anything other than creating reports.
PurchaseNumber	string	25		A purchase order this order is associated with. Not used for anything other than creating reports.
Items	A list of OrderItem objects		yes	The order's items.
Variables	A list of OrderVariable objects			Any misc information associated with the order. Commonly used to store IDs required for ship-confirm to an eCom site.
GiftMessage	string	80		A gift message to print on the order's packing slip. Additional configuration is needed before using this field; please contact your account manager if needed.

Address object

{
  "Attention": "sample string 1",
  "Name": "sample string 2",
  "Address1": "sample string 3",
  "Address2": "sample string 4",
  "City": "sample string 5",
  "StateOrProvince": "sample string 6",
  "PostalCode": "sample string 7",
  "CountryCode": "sample string 8",
  "Email": "sample string 9",
  "PhoneNumber": "sample string 10",
  "IsResidential": true
}

Key	Type	Maximum length *	Required	Description
Attention	string	35		Typically a person within a business.
Name	string	35	yes	If a business address, the name of the business. If a residential address, the person's name.
Address1	string	35	yes	The first address line.
Address2	string	35		An optional second address line.
City	string	30	yes
StateOrProvince	string	30	yes	If a US address, state will be validated as a 2-letter state code as defined by USPS 28 Appendix B.
PostalCode	string	20	yes	If a US address, postal code will be validated as either a 5-digit zip code, or a full zip+4.
CountryCode	string	2		If specified, must be a two-letter country code as defined by ISO 3166-1 alpha-2. if not specified, is assumed to be "US" .
Email	string	64		If specified, must be a valid email address as defined by RFC 5322/5321/3696.
PhoneNumber	string	30		Must consist only of code points defined in the Windows-1252 character encoding.
IsResidential	bool			Only used for ship-to addresses. If specified, indicates if the address is residential or not.
*	These are the default maximum lengths, but may vary by Carrier. See Carriers for more information on the Address Field Sizes object

OrderItem object

{
  "Sku": "sample string 1",
  "Quantity": 2,
  "Description": "sample string 2",
  "UnitOfMeasure": "EACH",
  "DeclaredValuePerUOM": 78.23,
  "Variables": [
                        OrderVariable object,
                        OrderVariable object
  ]
}

Key	Type	Maximum length	Required	Description
Sku	string	32	yes	This must be either a product's primary ID or a product's alias. Must consist only of printable code points defined in the Windows-1252 character encoding.
Quantity	decimal		yes	The number of items to include in the order. Must be at least 1.
Description	string	100		An optional description to include on packing slips. If not specified, the default description in the ERP will be used.
UnitOfMeasure	string	10		The unit of measure, e.g. "EACH" or "CASE". The correct values here depend on configuration within CTL's ERP and are per-item. They will be established upon item setup. If not specified, the items' default sales unit of measure will be used.
DeclaredValuePerUOM	decimal		for international shipments	The total value of a single instance of the order item (disregarding quantity). This value is declared to customs and is required for international shipments.
Variables	A list of OrderVariable objects			Any misc information associated with the item. Commonly used to store IDs required for ship-confirm to an eCom site.

OrderVariable object

{
  "Key": "sample string 1",
  "Value": "sample string 2"
}

Key	Type	Maximum length	Required	Description
Key	string	32	yes	The variable's key.
Value	string	512	yes	The variable's value.

Updating order ship address

This API will update an order's ship to address.

Sample request

PUT /v1/Orders/{id}/ShipTo HTTP/1.1
Content-Type: application/json; charset=utf-8
X-Ctl-ClientId: xxxx
X-Ctl-UserId: xxxx

{
  "Attention": "sample string 1",
  "Name": "sample string 2",
  "Address1": "sample string 3",
  "Address2": "sample string 4",
  "City": "sample string 5",
  "StateOrProvince": "sample string 6",
  "PostalCode": "sample string 7",
  "CountryCode": "sample string 8",
  "Email": "sample string 9",
  "PhoneNumber": "sample string 10"
}

Request

PUT /v1/Orders/{id}/ShipTo

Request parameters

Name	Description
{id}	The order's ID.

Body parameters

An Address object.

Response codes

Code	Meaning
200 OK	The order's address has been updated.
400 Bad Request	The address data has failed validation and must be corrected. See Validation and error handling for more information.
401 Unauthorized	The given client/user ID is not present in the OMS.
404 Not Found	An order with that ID was not found in the OMS.
409 Conflict	The given order has already been processed and may no longer be updated.
503 Service Unavailable	There is a temporary error preventing the request from completing. The client should retry the request at a later time.

Cancelling an order

Orders may be cancelled through the API if caught before processing. Otherwise, orders will need to be intercepted manually by a CSR.

Sample request

PUT /v1/Orders/{id}/IsCancelled HTTP/1.1
Content-Type: application/json; charset=utf-8
X-Ctl-ClientId: xxxx
X-Ctl-UserId: xxxx
{
  "Cancel": true
}

Request

PUT /v1/Orders/{id}/IsCancelled

Request parameters

Name	Description
{id}	The order's ID.

Body parameters

An OrderCancellation object.

Response codes

Code	Meaning
200 OK	The order has been cancelled.
400 Bad Request	The data has failed validation and must be corrected. See Validation and error handling for more information.
401 Unauthorized	The given client/user ID is not present in the OMS.
404 Not Found	An order with that ID was not found in the OMS.
409 Conflict	The given order has already been processed and may no longer be cancelled.
503 Service Unavailable	There is a temporary error preventing the request from completing. The client should retry the request at a later time.

OrderCancellation object

{
  "Cancel": true
}

Key	Type	Required	Description
Cancel	bool	yes	If true, the cancel the order. Currently, false is not supported.

Retrieving order status

This endpoint will retrieve a single order's status and is useful for real-time updates. For syncing multiple shipments, the bulk API should be used instead.

Sample request

GET /v1/Orders/{id} HTTP/1.1
Content-Type: application/json; charset=utf-8
X-Ctl-ClientId: xxxx
X-Ctl-UserId: xxxx

Sample response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "UpdateIndex": 1,
  "CarrierId": "2436EBED-1304-4B7A-A587-40F7A4AAD49B",
  "DateOrdered": "2014-09-03T15:23:34+08:00",
  "DateReceived": "2014-09-04T00:00:11+05:00",
  "ShipTo": {
    "Attention": "sample string 1",
    "Name": "sample string 2",
    "Address1": "sample string 3",
    "Address2": "sample string 4",
    "City": "sample string 5",
    "StateOrProvince": "sample string 6",
    "PostalCode": "sample string 7",
    "CountryCode": "sample string 8",
    "Email": "sample string 9",
    "PhoneNumber": "sample string 10"
  },
  "Items": [
    {
      "Sku": "sample string 1",
      "Quantity": 2,
      "Variables": [
        {
          "Key": "sample string 1",
          "Value": "sample string 2"
        },
        {
          "Key": "sample string 1",
          "Value": "sample string 2"
        }
      ]
    },                
    {
      "Sku": "sample string 1",
      "Quantity": 2,
      "Variables": [
        {
          "Key": "sample string 1",
          "Value": "sample string 2"
        },
        {
          "Key": "sample string 1",
          "Value": "sample string 2"
        }
      ]
    },
  ],
  "Variables": [
    {
      "Key": "sample string 1",
      "Value": "sample string 2"
    },
    {
      "Key": "sample string 1",
      "Value": "sample string 2"
    }
  ],
  "Shipments": [
    {
      "CarrierId": "2436EBED-1304-4B7A-A587-40F7A4AAD49B",
      "MasterTrackingNumber": "sample string 1",
      "ShipTo": {
        "Attention": "sample string 1",
        "Name": "sample string 2",
        "Address1": "sample string 3",
        "Address2": "sample string 4",
        "City": "sample string 5",
        "StateOrProvince": "sample string 6",
        "PostalCode": "sample string 7",
        "CountryCode": "sample string 8",
        "Email": "sample string 9",
        "PhoneNumber": "sample string 10"
      },
      "Packages": [
        {
          "TrackingNumber": "sample string 1",                
          "WeightInPounds": 1.0,                                
          "HeightInInches": 1.0,                                
          "WidthInInches": 1.0,                                
          "ThicknessInInches": 1.0,
          "Items": [
            {
              "Sku": "sample string 1",
              "Quantity": 2,
              "Variables": [
                {
                  "Key": "sample string 1",
                  "Value": "sample string 2"
                },
                {
                  "Key": "sample string 1",
                  "Value": "sample string 2"
                }
              ]
            },                
            {
              "Sku": "sample string 1",
              "Quantity": 2,
              "Variables": [
                {
                  "Key": "sample string 1",
                  "Value": "sample string 2"
                },
                {
                  "Key": "sample string 1",
                  "Value": "sample string 2"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Request

GET v1/Orders/{id}

Request parameters

Name	Description
{id}	The order's ID.

Response content

An OrderInfo object.

Response codes

Code	Meaning
200 OK	The order has been retrieved.
400 Bad Request	The order data has failed validation and must be corrected. See Validation and error handling for more information.
401 Unauthorized	The given client/user ID is not present in the OMS.
503 Service Unavailable	There is a temporary error preventing the request from completing. The client should retry the request at a later time.

OrderInfo object

{
  "UpdateIndex": 1,
  "IsClosed": true,
  "CarrierId": "2436EBED-1304-4B7A-A587-40F7A4AAD49B",
  "DateOrdered": "2014-09-03T15:23:34+08:00",
  "DateReceived": "2014-09-04T00:00:11+05:00",
  "ShipTo": Address object,
  "Items": [
                        OrderItem object,
                        OrderItem object
  ],
  "Variables": [
                        OrderVariable object,
                        OrderVariable object
  ],
  "Shipments": [
                        Shipment object,
                        Shipment object
  ]
}

Key	Type	Required	Description
UpdateIndex	int	yes	An index used for syncing.
IsClosed	bool	yes	If true, the order has been closed out by CTL. Under some rare circumstances, additional shipments may be added after closing an order. However, it generally means an order has finished shipping, or in the case of no shipments, was manually cancelled.
CarrierId	string		A carrier ID. If not specified, a default carrier will be chosen by the OMS.
DateOrdered	string		The date the client placed the order. Must be a valid ISO 8601 date, and may include an offset. Typically printed on packing slips.
DateReceived	string	yes	The date CTL received the order. Must be a valid ISO 8601 date, and may include an offset.
ShipTo	An Address object	yes	The order's ship to address.
Items	A list of OrderItem objects	yes	The order's items.
Variables	A list of OrderVariable objects		Any misc information associated with the order. Commonly used to store IDs required for ship-confirm to an eCom site.
Shipments	A list of Shipment objects		The order's shipments, if any.
ShipByDate	Date		The latest date that CTL intends to ship this order. May be blank if business rules do not dictate calculating a specific ship date.

Shipment object

{
  "Id": "5AF4C10E-E00A-4163-BB40-E3ED43C4424A",
  "CarrierId": "2436EBED-1304-4B7A-A587-40F7A4AAD49B",
  "ShipTo": Address object,
  "MasterTrackingNumber": "sample string 1",
  "Packages": [
                        Package object,
                        Package object
  ]
}

Key	Type	Required	Description
Id	string		The ID for the shipment.
CarrierId	string		The carrier used for the shipment.
ShipTo	An Address object	yes	The address this shipment was sent to. May be different from the order address if it was run through address correction.
MasterTrackingNumber	string		A master tracking number, if applicable. For freight shipments, this will be a PRO number.
BillOfLadingNumber	string		For freight shipments, the BOL number.
Packages	A list of Package objects	yes	Individual packages in this shipment.
ShipDate	Date	yes	The date this shipment was posted.
ScheduledDeliveryDate	Date		The shipment's scheduled delivery date, if applicable.

Package object

{
  "Id": "F3541AD9-C32F-4ECD-9C0B-E6E88A596017",
  "TrackingNumber": "sample string 1",
  "UniformCommercialCode": "sample string 2",
  "CartonSku": "sample string 3",
  "WeightInPounds": 1.0,
  "HeightInInches": 1.0,
  "WidthInInches": 1.0,
  "ThicknessInInches": 1.0,
  "Items": [
                        Package Item object,
                        Package Item object
  ]
}

Key	Type	Required	Description
Id	string		The ID for the package.
TrackingNumber	string		The package's tracking number, if applicable.
UniformCommericalCode	string		The package's UCC number, if applicable.
CartonSku	string		The carton the package's items were was shipped in, if applicable.
WeightInPounds	decimal		The weight of the package, if applicable.
HeightInInches	decimal		The height of the package, if applicable.
WidthInInches	decimal		The width of the package, if applicable.
ThicknessInInches	decimal		The thickness of the package, if applicable.
Items	A list of OrderItems	yes	Items included in this package.

Package Item Object

{
  "UnitsShipped": 1.00000000000000000000,
  "Metadata": [
                        OrderVariable object
  ],
  "Sku": "Item Sku",
  "Quantity": 1.00000000000000000000,
  "Description": null,
  "UnitOfMeasure": "EACH",
  "DeclaredValuePerUOM": null,
  "Variables": [
                        OrderVariable object

  ]
}

Key	Type	Maximum length	Required	Description
UnitsShipped	decimal			The number of units shipped in the package
Metadata	A list of OrderVariable objects			Any misc information associate with the package item. For example, the serial or lot code of the packaged Sku.
Sku	string	32	yes	This must be either a product's primary ID or a product's alias. Must consist only of printable code points defined in the Windows-1252 character encoding.
Quantity	decimal		yes	The number of items to include in the order. Must be at least 1.
Description	string	100		An optional description to include on packing slips. If not specified, the default description in the ERP will be used.
UnitOfMeasure	string	10		The unit of measure, e.g. "EACH" or "CASE". The correct values here depend on configuration within CTL's ERP and are per-item. They will be established upon item setup. If not specified, the items' default sales unit of measure will be used.
DeclaredValuePerUOM	decimal		for international shipments	The total value of a single instance of the order item (disregarding quantity). This value is declared to customs and is required for international shipments.
Variables	A list of OrderVariable objects			Any misc information associated with the item. Commonly used to store IDs required for ship-confirm to an eCom site.

Retrieving bulk order status

This endpoint is used to sync shipments.

To do so, one should keep track of the last "UpdateIndex" received from this service. You can then call this again with the "fromUpdateId" parameter to get any orders which have been updated since your last try. See the Querying new shipments sample to better understand usage.

Because this can return a large amount of data, results are paged. The API should be called with the last received index until nothing more is returned.

Sample request

GET /v1/Orders/?fromUpdateId=1 HTTP/1.1
X-Ctl-ClientId: xxxx
X-Ctl-UserId: xxxx

Sample response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[                
    {
      "UpdateIndex": 1,
      "CarrierId": "2436EBED-1304-4B7A-A587-40F7A4AAD49B",
      "DateOrdered": "2014-09-03T15:23:34+08:00",
      "DateReceived": "2014-09-04T00:00:11+05:00",
      "ShipTo": {
        "Attention": "sample string 1",
        "Name": "sample string 2",
        "Address1": "sample string 3",
        "Address2": "sample string 4",
        "City": "sample string 5",
        "StateOrProvince": "sample string 6",
        "PostalCode": "sample string 7",
        "CountryCode": "sample string 8",
        "Email": "sample string 9",
        "PhoneNumber": "sample string 10"
      },
      "Items": [
        {
          "Sku": "sample string 1",
          "Quantity": 2,
          "Variables": [
        {
          "Key": "sample string 1",
          "Value": "sample string 2"
        },
        {
          "Key": "sample string 1",
          "Value": "sample string 2"
        }
          ]
        },                
        {
          "Sku": "sample string 1",
          "Quantity": 2,
          "Variables": [
        {
          "Key": "sample string 1",
          "Value": "sample string 2"
        },
        {
          "Key": "sample string 1",
          "Value": "sample string 2"
        }
          ]
        },
      ],
      "Variables": [
        {
          "Key": "sample string 1",
          "Value": "sample string 2"
        },
        {
          "Key": "sample string 1",
          "Value": "sample string 2"
        }
      ],
      "Shipments": [
        {
          "Id": "4E35F5AF-49CC-42A4-8C9E-7881F7074F00",
          "CarrierId": "2436EBED-1304-4B7A-A587-40F7A4AAD49B",
          "MasterTrackingNumber": "sample string 1",
          "ShipTo": {
            "Attention": "sample string 1",
            "Name": "sample string 2",
            "Address1": "sample string 3",
            "Address2": "sample string 4",
            "City": "sample string 5",
            "StateOrProvince": "sample string 6",
            "PostalCode": "sample string 7",
            "CountryCode": "sample string 8",
            "Email": "sample string 9",
            "PhoneNumber": "sample string 10"
          },
          "Packages": [
            {
              "Id": "AE70CB0E-397B-41A1-ADC6-60CBD5A77D62",
              "TrackingNumber": "sample string 1",                
              "WeightInPounds": 1.0,                                
              "HeightInInches": 1.0,                                
              "WidthInInches": 1.0,                                
              "ThicknessInInches": 1.0,
              "Items": [
                {
                  "Sku": "sample string 1",
                  "Quantity": 2,
                  "Variables": [
                    {
                      "Key": "sample string 1",
                      "Value": "sample string 2"
                    },
                    {
                      "Key": "sample string 1",
                      "Value": "sample string 2"
                    }
                  ]
                },                
                {
                  "Sku": "sample string 1",
                  "Quantity": 2,
                  "Variables": [
                    {
                      "Key": "sample string 1",
                      "Value": "sample string 2"
                    },
                    {
                      "Key": "sample string 1",
                      "Value": "sample string 2"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ],
      "ThirdPartyAccountShipNumber": "sample string 2"
    },
    {
      "UpdateIndex": 1,
      "CarrierId": "2436EBED-1304-4B7A-A587-40F7A4AAD49B",
      "DateOrdered": "2014-09-03T15:23:34+08:00",
      "DateReceived": "2014-09-04T00:00:11+05:00",
      "ShipTo": {
        "Attention": "sample string 1",
        "Name": "sample string 2",
        "Address1": "sample string 3",
        "Address2": "sample string 4",
        "City": "sample string 5",
        "StateOrProvince": "sample string 6",
        "PostalCode": "sample string 7",
        "CountryCode": "sample string 8",
        "Email": "sample string 9",
        "PhoneNumber": "sample string 10"
      },
      "Items": [
        {
          "Sku": "sample string 1",
          "Quantity": 2,
          "Variables": [
        {
          "Key": "sample string 1",
          "Value": "sample string 2"
        },
        {
          "Key": "sample string 1",
          "Value": "sample string 2"
        }
          ]
        },                
        {
          "Sku": "sample string 1",
          "Quantity": 2,
          "Variables": [
        {
          "Key": "sample string 1",
          "Value": "sample string 2"
        },
        {
          "Key": "sample string 1",
          "Value": "sample string 2"
        }
          ]
        },
      ],
      "Variables": [
        {
          "Key": "sample string 1",
          "Value": "sample string 2"
        },
        {
          "Key": "sample string 1",
          "Value": "sample string 2"
        }
      ],
      "Shipments": [
        {
          "Id": "F1350C4C-3293-441D-A963-20A9EE8D0535",
          "CarrierId": "2436EBED-1304-4B7A-A587-40F7A4AAD49B",
          "MasterTrackingNumber": "sample string 1",
          "ShipTo": {
            "Attention": "sample string 1",
            "Name": "sample string 2",
            "Address1": "sample string 3",
            "Address2": "sample string 4",
            "City": "sample string 5",
            "StateOrProvince": "sample string 6",
            "PostalCode": "sample string 7",
            "CountryCode": "sample string 8",
            "Email": "sample string 9",
            "PhoneNumber": "sample string 10"
          },
          "Packages": [
            {
              "Id": "835BEF0A-3BDA-41CD-AD25-4165111D33F3",
              "TrackingNumber": "sample string 1",                
              "WeightInPounds": 1.0,                                
              "HeightInInches": 1.0,                                
              "WidthInInches": 1.0,                                
              "ThicknessInInches": 1.0,
              "Items": [
                {
                  "Sku": "sample string 1",
                  "Quantity": 2,
                  "Variables": [
                    {
                      "Key": "sample string 1",
                      "Value": "sample string 2"
                    },
                    {
                      "Key": "sample string 1",
                      "Value": "sample string 2"
                    }
                  ]
                },                
                {
                  "Sku": "sample string 1",
                  "Quantity": 2,
                  "Variables": [
                    {
                      "Key": "sample string 1",
                      "Value": "sample string 2"
                    },
                    {
                      "Key": "sample string 1",
                      "Value": "sample string 2"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ],
      "ThirdPartyAccountShipNumber": null
    }
]

Response content

A PagedCollection object containing OrderInfo objects.

Response codes

Code	Meaning
200 OK	Orders have been retrieved.
401 Unauthorized	The given client/user ID is not present in the OMS.
404 Not Found	No orders have been found matching these parameters.
503 Service Unavailable	There is a temporary error preventing the request from completing. The client should retry the request at a later time.

Searching orders

This endpoint is used to search orders.

Because this can return a large amount of data, results are paged and continuation tokens are provided to continue reading results.

Sample request

GET /v1/Orders/?query=foo+bar HTTP/1.1
X-Ctl-ClientId: xxxx
X-Ctl-UserId: xxxx

Sample response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "IsTruncated": false,
  "TotalItems": 2,
  "TotalPages": 1,
  "CollectionKey": "sample string 1",
  "Items": [                
    {
      "UpdateIndex": 1,
      "CarrierId": "2436EBED-1304-4B7A-A587-40F7A4AAD49B",
      "DateOrdered": "2014-09-03T15:23:34+08:00",
      "DateReceived": "2014-09-04T00:00:11+05:00",
      "ShipTo": {
        "Attention": "sample string 1",
        "Name": "sample string 2",
        "Address1": "sample string 3",
        "Address2": "sample string 4",
        "City": "sample string 5",
        "StateOrProvince": "sample string 6",
        "PostalCode": "sample string 7",
        "CountryCode": "sample string 8",
        "Email": "sample string 9",
        "PhoneNumber": "sample string 10"
      },
      "Items": [
        {
          "Sku": "sample string 1",
          "Quantity": 2,
          "Variables": [
        {
          "Key": "sample string 1",
          "Value": "sample string 2"
        },
        {
          "Key": "sample string 1",
          "Value": "sample string 2"
        }
          ]
        },                
        {
          "Sku": "sample string 1",
          "Quantity": 2,
          "Variables": [
        {
          "Key": "sample string 1",
          "Value": "sample string 2"
        },
        {
          "Key": "sample string 1",
          "Value": "sample string 2"
        }
          ]
        },
      ],
      "Variables": [
        {
          "Key": "sample string 1",
          "Value": "sample string 2"
        },
        {
          "Key": "sample string 1",
          "Value": "sample string 2"
        }
      ],
      "Shipments": [
        {
          "Id": "4E35F5AF-49CC-42A4-8C9E-7881F7074F00",
          "CarrierId": "2436EBED-1304-4B7A-A587-40F7A4AAD49B",
          "MasterTrackingNumber": "sample string 1",
          "ShipTo": {
            "Attention": "sample string 1",
            "Name": "sample string 2",
            "Address1": "sample string 3",
            "Address2": "sample string 4",
            "City": "sample string 5",
            "StateOrProvince": "sample string 6",
            "PostalCode": "sample string 7",
            "CountryCode": "sample string 8",
            "Email": "sample string 9",
            "PhoneNumber": "sample string 10"
          },
          "Packages": [
            {
              "Id": "AE70CB0E-397B-41A1-ADC6-60CBD5A77D62",
              "TrackingNumber": "sample string 1",                
              "WeightInPounds": 1.0,                                
              "HeightInInches": 1.0,                                
              "WidthInInches": 1.0,                                
              "ThicknessInInches": 1.0,
              "Items": [
                {
                  "Sku": "sample string 1",
                  "Quantity": 2,
                  "Variables": [
                    {
                      "Key": "sample string 1",
                      "Value": "sample string 2"
                    },
                    {
                      "Key": "sample string 1",
                      "Value": "sample string 2"
                    }
                  ]
                },                
                {
                  "Sku": "sample string 1",
                  "Quantity": 2,
                  "Variables": [
                    {
                      "Key": "sample string 1",
                      "Value": "sample string 2"
                    },
                    {
                      "Key": "sample string 1",
                      "Value": "sample string 2"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ],
      "ThirdPartyAccountShipNumber": "sample string 2"
    },
    {
      "UpdateIndex": 1,
      "CarrierId": "2436EBED-1304-4B7A-A587-40F7A4AAD49B",
      "DateOrdered": "2014-09-03T15:23:34+08:00",
      "DateReceived": "2014-09-04T00:00:11+05:00",
      "ShipTo": {
        "Attention": "sample string 1",
        "Name": "sample string 2",
        "Address1": "sample string 3",
        "Address2": "sample string 4",
        "City": "sample string 5",
        "StateOrProvince": "sample string 6",
        "PostalCode": "sample string 7",
        "CountryCode": "sample string 8",
        "Email": "sample string 9",
        "PhoneNumber": "sample string 10"
      },
      "Items": [
        {
          "Sku": "sample string 1",
          "Quantity": 2,
          "Variables": [
        {
          "Key": "sample string 1",
          "Value": "sample string 2"
        },
        {
          "Key": "sample string 1",
          "Value": "sample string 2"
        }
          ]
        },                
        {
          "Sku": "sample string 1",
          "Quantity": 2,
          "Variables": [
        {
          "Key": "sample string 1",
          "Value": "sample string 2"
        },
        {
          "Key": "sample string 1",
          "Value": "sample string 2"
        }
          ]
        },
      ],
      "Variables": [
        {
          "Key": "sample string 1",
          "Value": "sample string 2"
        },
        {
          "Key": "sample string 1",
          "Value": "sample string 2"
        }
      ],
      "Shipments": [
        {
          "Id": "F1350C4C-3293-441D-A963-20A9EE8D0535",
          "CarrierId": "2436EBED-1304-4B7A-A587-40F7A4AAD49B",
          "MasterTrackingNumber": "sample string 1",
          "ShipTo": {
            "Attention": "sample string 1",
            "Name": "sample string 2",
            "Address1": "sample string 3",
            "Address2": "sample string 4",
            "City": "sample string 5",
            "StateOrProvince": "sample string 6",
            "PostalCode": "sample string 7",
            "CountryCode": "sample string 8",
            "Email": "sample string 9",
            "PhoneNumber": "sample string 10"
          },
          "Packages": [
            {
              "Id": "835BEF0A-3BDA-41CD-AD25-4165111D33F3",
              "TrackingNumber": "sample string 1",                
              "WeightInPounds": 1.0,                                
              "HeightInInches": 1.0,                                
              "WidthInInches": 1.0,                                
              "ThicknessInInches": 1.0,
              "Items": [
                {
                  "Sku": "sample string 1",
                  "Quantity": 2,
                  "Variables": [
                    {
                      "Key": "sample string 1",
                      "Value": "sample string 2"
                    },
                    {
                      "Key": "sample string 1",
                      "Value": "sample string 2"
                    }
                  ]
                },                
                {
                  "Sku": "sample string 1",
                  "Quantity": 2,
                  "Variables": [
                    {
                      "Key": "sample string 1",
                      "Value": "sample string 2"
                    },
                    {
                      "Key": "sample string 1",
                      "Value": "sample string 2"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ],
      "ThirdPartyAccountShipNumber": null
    }
  ]
}

Request

GET /v1/Orders?fromDate={fromDate}&toDate={toDate}&query={query}&maxResults={maxResults}&pageKey={pageKey}&pageIndex={pageIndex}

Request parameters

All parameters are optional, but results may be truncated if too many would be returned.

Name	Description
{fromDate}	The date, inclusive, to search from.
{toDate}	The date, exclusive, to search to.
{query}	Free-form text to search for. Looks in address data, order IDs, tracking numbers, etc.
{maxResults}	The maximum number of results to return. This is primarily designed to speed up possibly broad queries where you only need a limited amount of results. It is treated merely as a hint and results may still be truncated if the number requested is too high.
{pageKey}	A page key used to resume a previously paged query.
{pageIndex}	A page index used to resume a previously paged query.

Response content

A PagedCollection object containing OrderInfo objects.

Response codes

Code	Meaning
200 OK	Orders have been retrieved.
400 Bad Request	The order data has failed validation and must be corrected. See Validation and error handling for more information.
401 Unauthorized	The given client/user ID is not present in the OMS.
404 Not Found	No orders have been found matching these parameters.
503 Service Unavailable	There is a temporary error preventing the request from completing. The client should retry the request at a later time.

PagedCollection object

A PagedCollection object represents a single page in a larger collection.

Recognizing that a majority of web frameworks work poorly with and/or restrict the size of JSON objects and responses, the API will split up large collections of objects into one or more of these pages that can be retrieved individually.

For an example of how to use these objects, see the Querying for a large amount of orders sample.

{
  "IsTruncated": false,
  "TotalItems": 2,
  "TotalPages": 1,
  "CollectionKey": "sample string 1",
  "Items": [                
    object,
    object
  ]
}

Key	Type	Required	Description
IsTruncated	bool	yes	If true, the request would return too many objects. The results have been arbitrarily truncated.
TotalItems	int	yes	The total number of items in the collection.
TotalPages	int	yes	The total number of pages in the collection.
CollectionKey	string	yes	A key used to retrieve other pages in the collection.
Items	A list of objects	yes	Items in this page of the collection. The type of object will depend on the API being exposed.

Retrieving inventory counts

Retrieves a snapshot of inventory information. Though this does give accurate inventory counts, it's not intended for syncing inventory counts between CTL and external systems. For that, the Transaction History endpoint provides a differential stream of inventory updates that will typically be more robust in use and result in fewer ops.

Because this endpoint can potentially return a large amount of data, results follow the paged bulk data model.

Sample request

GET /v1/Products/ HTTP/1.1
X-Ctl-ClientId: xxxx
X-Ctl-UserId: xxxx

Sample response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "IsTruncated": false,
    "TotalItems": 4,
    "TotalPages": 2,
    "CollectionKey": "sample string 1",
    "Items": [
        {
            "Id": "Foo",
            "Description": "Your Product",
            "QuantityAvailable": 10.0000000000,
            "QuantityOnHand": 11.0000000000,
            "Aliases": ["Foo1", "Foo2"]
        }, {
            "Id": "Bar",
            "Description": "Your Other Product",
            "QuantityAvailable": 5.0000000000,
            "QuantityOnHand": 50.0000000000,
            "Aliases": []
        }
    ]
}

Response content

A paged collection of Product objects.

Response codes

Code	Meaning
200 OK	Products have been retrieved.
401 Unauthorized	The given client/user ID is not present in the OMS.
404 Not Found	No products have been found matching these parameters.
503 Service Unavailable	There is a temporary error preventing the request from completing. The client should retry the request at a later time.

Product object

{
    "Id": "Foo",
    "Description": "Your Product",
    "QuantityAvailable": 10.0000000000,
    "QuantityOnHand": 11.0000000000,
    "Aliases": ["Foo1", "Foo2"]
}

Key	Type	Required	Description
Id	string	yes	The unique ID of the product.
Description	string		A description of the product.
QuantityAvailable	decimal	yes	The amount of unallocated product available for orders. This is equivalent to the amount on hand, minus items on outstanding sales orders and minus quarantined items.
QuantityOnHand	decimal	yes	The amount of this product in building. This includes items that have already been assigned to orders, or which have been quarantined.
Aliases	An array of strings		Aliases that can be used to refer to this product on orders in place of its primary ID.

Requesting product additions/updates

Modifying product definitions is a three-step process. First, a product change request is PUT into the CTL API. This request is not immediately processed. Next, an account manager at CTL will validate the change request. CTL may either accept or reject the request. Following that, you can query this API with an UpdateIndex to retrieve that result as well as a rejection reason if applicable.

Sample request

PUT /v1/ProductChanges/{id} HTTP/1.1
X-Ctl-ClientId: xxxx
X-Ctl-UserId: xxxx
X-Ctl-CancelDisabledItems: true

{
    "ProductId": "PROD1",
    "Description": "Your Product",
    "SecondaryDescription": "Your Product B",
    "ExtendedDescription": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. In ullamcorper, purus eget iaculis aliquam, eros nisi maximus lorem, id porta odio nunc sit amet ipsum. Integer pharetra tincidunt turpis, lacinia luctus purus. Mauris sit amet cursus mauris, sit amet mollis nunc. Nam nec eleifend est, eget aliquam nisl.",
    "Aliases": ["Foo1", "Foo2"],
    "UnitsOfMeasure": {
        "EACH": {
            "BaseQuantity": 1,
            "LengthInInches": 2,
            "WidthInInches": 3,
            "HeightInInches": 4,
            "WeightInPounds": 5,
        },
        "PACK": {
            "BaseQuantity": 8,
            "LengthInInches": 4,
            "WidthInInches": 6,
            "HeightInInches": 8,
            "WeightInPounds": 40,
        }
    },
    "SalesUnitOfMeasure": "EACH",
    "PurchaseUnitOfMeasure": "EACH",
    "PutAwayUnitOfMeasure": "EACH",
    "ProductGroupCode": "Your Group Code",
    "Category1": "foo",
    "Category2": "bar",
    "Category3": "baz",
    "Category4": "qux",
    "SpecialEquipmentCode": "H",
    "CycleCountCode": ""
}

Sample response

HTTP/1.1 201 Created

Request

PUT /v1/ProductChanges/{changeId}
X-Ctl-CancelDisabledItems: {cancelItems}

Request parameters

Name	Description
{changeId}	The change's ID.
{cancelItems}	If specified and the item is being disabled, indicates if unprocessed orders should have this item automatically cancelled from them or not. If "true", the item will be automatically cancelled. If an order has no remaining items, the order itself will be cancelled. If "false", and there are unprocessed orders, the request will immediately fail with a validation message.

Name

Description

{changeId}

The change's ID.

{cancelItems}

If specified and the item is being disabled, indicates if unprocessed orders should have this item automatically cancelled from them or not.

If "true", the item will be automatically cancelled. If an order has no remaining items, the order itself will be cancelled. If "false", and there are unprocessed orders, the request will immediately fail with a validation message.

Body parameters

A Product Master object.

Response codes

Code	Meaning
201 Created	The change request has been received.
400 Bad Request	The change request data has failed validation and must be corrected. See Validation and error handling for more information.
401 Unauthorized	The given client/user ID is not present in the OMS.
409 Conflict	A change request with that ID already exists and may not be updated.
503 Service Unavailable	There is a temporary error preventing the request from completing. The client should retry the request at a later time.

Product Master object

{
    "ProductId": "PROD1",
    "Description": "Your Product",
    "SecondaryDescription": "Your Product B",
    "ExtendedDescription": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. In ullamcorper, purus eget iaculis aliquam, eros nisi maximus lorem, id porta odio nunc sit amet ipsum. Integer pharetra tincidunt turpis, lacinia luctus purus. Mauris sit amet cursus mauris, sit amet mollis nunc. Nam nec eleifend est, eget aliquam nisl.",
    "Aliases": ["Foo1", "Foo2"],
    "UnitsOfMeasure": {
        "EACH": {
            "BaseQuantity": 1,
            "LengthInInches": 2,
            "WidthInInches": 3,
            "HeightInInches": 4,
            "WeightInPounds": 5,
        },
        "PACK": {
            "BaseQuantity": 8,
            "LengthInInches": 4,
            "WidthInInches": 6,
            "HeightInInches": 8,
            "WeightInPounds": 40,
        }
    },
    "SalesUnitOfMeasure": "EACH",
    "PurchaseUnitOfMeasure": "EACH",
    "PutAwayUnitOfMeasure": "EACH",
    "ProductGroupCode": "Your Group Code",
    "Category1": "foo",
    "Category2": "bar",
    "Category3": "baz",
    "Category4": "qux",
    "SpecialEquipmentCode": "H",
    "CycleCountCode": "A"
}

Key	Type	Maximum length	Required	Description
ProductId	string	20	yes	The product's unique identifier within CTL's ERP. Typically a SKU number.
Description	string	50	yes	The primary description of the product.
SecondaryDescription	string	50		A secondary description for the product.
ExtendedDescription	string	400		An extended description for the product.
Aliases	List of strings	30 per string		Alternate names the product can go by. If specified, aliases can be used in place of the primary product ID when placing orders.
UnitsOfMeasure	Object with the UOM codes as keys.			Units of measure for this product. If not specified and creating a new product, "EACH" will be implicitly created.
UnitsOfMeasure keys	string	10	The name of this unit of measure. "EACH", "PACK", etc.
UnitsOfMeasure[].BaseQuantity	integer		yes	The number of EACHes that make up this UOM. If the UOM is "EACH", must be equal to 1.
UnitsOfMeasure[].LengthInInches	decimal			The length dimension of this UOM.
UnitsOfMeasure[].WidthInInches	decimal			The width dimension of this UOM.
UnitsOfMeasure[].HeightInInches	decimal			The width dimension of this UOM.
UnitsOfMeasure[].WeightInPounds	decimal			The weight dimension of this UOM.
BillOfMaterialEntries	Object with BOM entries for Assembled Items			Bill of Material Entries for this product, used as the recipe requirements for assembled items.
BillOfMaterialEntries[].ProductId	string	20	yes	The Product Id of the required product. Must be present in our system.
BillOfMaterialEntries[].UnitOfMeasure	string	10	yes	The Unit of Measure of the required product. Must be present in our system.
BillOfMaterialEntries[].Quantity	int		yes	The Quantity of this product needed. Must be positive.
SalesUnitOfMeasure	string	10		The default sales unit of measure. If a product is ordered without a UOM, this will be used by default.
PurchaseUnitOfMeasure	string	10		The default purchase unit of measure. If a product is placed on purchase order, this will be used by default.
PutAwayUnitOfMeasure	string	10		The default putaway unit of measure. After receiving the product, it will be broken down into this UOM before being put away.
Product Group Code	string	10		Commonly used to indicate a busines division that owns the product, typically used for invoicing or reporting purposes; coordinate with your account manager for usage.
Category1	string	30		Freeform text that can be used to categorize products in CTL's ERP. Commonly used for reporting purposes; coordinate with your account manager for usage.
Category2	string	30		Freeform text that can be used to categorize products in CTL's ERP. Commonly used for reporting purposes; coordinate with your account manager for usage.
Category3	string	30		Freeform text that can be used to categorize products in CTL's ERP. Commonly used for reporting purposes; coordinate with your account manager for usage.
Category4	string	30		Freeform text that can be used to categorize products in CTL's ERP. Commonly used for reporting purposes; coordinate with your account manager for usage.
SpecialEquipmentCode	string	4		A equipment code indicating special handling is needed for this product. If specified, must be one of: C: Cooler with ice G: Glass / breakable H: Hazmat HA: Hazmat (Aerosol) HG: Hazmat (Glass / breakable) HL: Hazmat (Liquid) HLG: Hazmat (Liquid, glass / breakable) L: Liquid LG: Liquid, glass / breakable
CycleCountCode	string	10		A Cycle Count Code. If Present must match allowed Cycle Count Codes specific to your account.
StartingUseDate	string			If specified, indicates the first date this item is expected to be used. Must be a valid ISO 8601 date and may include an offset. Depending on business rules this may be used to optimize storage and production.
FinalUseDate	string			If specified, indicates the last date this item is expected to be used. Must be a valid ISO 8601 date and may include an offset. Depending on business rules this may be used to optimize storage and production, or to automatically retire an item.
Enabled	bool			If false, indicates the item should be disabled. If an item has unshipped sales orders or unreceived purchase orders against it, the request to disable will immediately fail. The X-Ctl-CancelDisabledItems header can be set to "true" to automatically remove the item from any unprocessed sales orders, cancelling the order outright if there are no remaining items on it.

Retrieving product change request updates

This API satisfies the third step in the product change request workflow: it allows retrieval of the result of a change request, which can either succeed or fail. If a request fails, a message will acompany it describing why -- you are at that point able to correct the issue and re-submit under a new ID if needed.

To use this API, one should keep track of the last "UpdateIndex" received from this service. You can then call this again with the "fromUpdateId" parameter to get any orders which have been updated since your last try. See the Querying new shipments sample to better understand usage.

Because this can return a large amount of data, results are paged. The API should be called with the last received index until nothing more is returned.

Sample request

GET /v1/ProductChanges/?fromUpdateId=1 HTTP/1.1
X-Ctl-ClientId: xxxx
X-Ctl-UserId: xxxx

Sample response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[
    {
        "UpdateIndex": 1,
        "Status": "Denied",
        "ResultMessage": "Requested a PACK of 1, did you mean 8?",
        "DateCreated": "2017-12-12T11:05:01-05:00",
        "DateProcessed": "2017-12-13T15:57:32-05:00",
        "Id": "Foo",
        "ProductId": "PROD1",
        "Description": "Your Product",
        "SecondaryDescription": "Your Product B",
        "ExtendedDescription": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. In ullamcorper, purus eget iaculis aliquam, eros nisi maximus lorem, id porta odio nunc sit amet ipsum. Integer pharetra tincidunt turpis, lacinia luctus purus. Mauris sit amet cursus mauris, sit amet mollis nunc. Nam nec eleifend est, eget aliquam nisl.",
        "Aliases": ["Foo1", "Foo2"],
        "UnitsOfMeasure": {
            "EACH": {
                "BaseQuantity": 1,
                "LengthInInches": 2,
                "WidthInInches": 3,
                "HeightInInches": 4,
                "WeightInPounds": 5,
            },
            "PACK": {
                "BaseQuantity": 1,
                "LengthInInches": 4,
                "WidthInInches": 6,
                "HeightInInches": 8,
                "WeightInPounds": 40,
            }
        },
        "SalesUnitOfMeasure": "EACH",
        "PurchaseUnitOfMeasure": "EACH",
        "PutAwayUnitOfMeasure": "EACH",
        "ProductGroupCode": "Your Group Code",
        "Category1": "foo",
        "Category2": "bar",
        "Category3": "baz",
        "Category4": "qux",
        "SpecialHandlingCode": "H"
    },
    {
        "UpdateIndex": 2,
        "Status": "Accepted",
        "DateCreated": "2017-12-13T17:01:02-05:00",
        "DateProcessed": "2017-12-13T18:46:49-05:00",
        "Id": "Foo2",
        "ProductId": "PROD1",
        "Description": "Your Product",
        "SecondaryDescription": "Your Product B",
        "ExtendedDescription": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. In ullamcorper, purus eget iaculis aliquam, eros nisi maximus lorem, id porta odio nunc sit amet ipsum. Integer pharetra tincidunt turpis, lacinia luctus purus. Mauris sit amet cursus mauris, sit amet mollis nunc. Nam nec eleifend est, eget aliquam nisl.",
        "Aliases": ["Foo1", "Foo2"],
        "UnitsOfMeasure": {
            "EACH": {
                "BaseQuantity": 1,
                "LengthInInches": 2,
                "WidthInInches": 3,
                "HeightInInches": 4,
                "WeightInPounds": 5,
            },
            "PACK": {
                "BaseQuantity": 8,
                "LengthInInches": 4,
                "WidthInInches": 6,
                "HeightInInches": 8,
                "WeightInPounds": 40,
            }
        },
        "SalesUnitOfMeasure": "EACH",
        "PurchaseUnitOfMeasure": "EACH",
        "PutAwayUnitOfMeasure": "EACH",
        "ProductGroupCode": "Your Group Code",
        "Category1": "foo",
        "Category2": "bar",
        "Category3": "baz",
        "Category4": "qux",
        "SpecialHandlingCode": "H"
    }
]

Request

GET /v1/ProductChanges/?fromUpdateId={updateId}

Request parameters

Name	Description
{updateId}	The ID to begin retrieving updates from. Starts at 0.

Response codes

Code	Meaning
200 OK	Change requests have been retrieved.
401 Unauthorized	The given client/user ID is not present in the OMS.
404 Not Found	No change requests have been found matching these parameters.
503 Service Unavailable	There is a temporary error preventing the request from completing. The client should retry the request at a later time.

Product Master Status object

{
    "UpdateIndex": 2,
    "Status": "Accepted",
    "DateCreated": "2017-12-13T17:01:02-05:00",
    "DateProcessed": "2017-12-13T18:46:49-05:00",
    "Id": "Foo2",
    "Description": "Your Product",
    "SecondaryDescription": "Your Product B",
    "ExtendedDescription": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. In ullamcorper, purus eget iaculis aliquam, eros nisi maximus lorem, id porta odio nunc sit amet ipsum. Integer pharetra tincidunt turpis, lacinia luctus purus. Mauris sit amet cursus mauris, sit amet mollis nunc. Nam nec eleifend est, eget aliquam nisl.",
    "Aliases": ["Foo1", "Foo2"],
    "UnitsOfMeasure": {
        "EACH": {
            "BaseQuantity": 1,
            "LengthInInches": 2,
            "WidthInInches": 3,
            "HeightInInches": 4,
            "WeightInPounds": 5,
        },
        "PACK": {
            "BaseQuantity": 8,
            "LengthInInches": 4,
            "WidthInInches": 6,
            "HeightInInches": 8,
            "WeightInPounds": 40,
        }
    },
    "SalesUnitOfMeasure": "EACH",
    "PurchaseUnitOfMeasure": "EACH",
    "PutAwayUnitOfMeasure": "EACH",
    "ProductGroupCode": "Your Group Code",
    "Category1": "foo",
    "Category2": "bar",
    "Category3": "baz",
    "Category4": "qux",
    "SpecialHandlingCode": "H"
}

Key	Type	Description
UpdateIndex	integer	An incrementing update index used for streaming updates to the change requests.
Status	string	The current status of the request. Can be one of: Pending: the change request has not yet been reviewed. Accepted: the change has been applied. Denied: the change has been denied. See ResultMessage for details why.
ResultMessage	string	A free-form message describing why a change was denied.
DateCreated	Date	The date this request was created.
DateProcessed	Date	The date this request was approved or denied.
The object also contains the original data received on the request, see the ProductMaster object for a description of this data.

Retrieving transaction history

The transaction history log is a stream of inventory changes. Purchase receipts, sales shipments, manual adjustments, kit creation, and more will all result in a log entry. This endpoint is appropriate for syncing CTL's inventory counts with an external system.

Because this endpoint can potentially return a large amount of data, results follow the streaming bulk data model.

Sample request

GET /v1/ProductTransactions/?fromUpdateId=200 HTTP/1.1
X-Ctl-ClientId: xxxx
X-Ctl-UserId: xxxx

Sample response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[{
    "Date": "2015-06-29T00:00:00-05:00",
    "TransactionType": "Adjustment",
    "TransactionSourceId": "T000052",
    "ProductId": "PROD01",
    "Quantity": 2.0000000000,
    "UnitOfMeasure": "EACH",
    "UpdateIndex": 299
}, {
    "Date": "2015-06-29T00:00:00-05:00",
    "TransactionType": "Adjustment",
    "TransactionSourceId": "T000052",
    "ProductId": "PROD02",
    "Quantity": 1.0000000000,
    "UnitOfMeasure": "EACH",
    "UpdateIndex": 300
}, {
    "Date": "2015-06-29T00:00:00-05:00",
    "TransactionType": "Adjustment",
    "TransactionSourceId": "T000052",
    "ProductId": "PROD03",
    "Quantity": 1.0000000000,
    "UnitOfMeasure": "EACH",
    "UpdateIndex": 301
}]

Request

GET /v1/ProductTransactions/?fromUpdateId={fromUpdateId}

Request parameters

Name	Description
{fromUpdateId}	An update index, inclusive, to lookup transaction history updates from. See the Querying new shipments sample to better understand usage.

Response content

A collection of ProductTransaction objects.

Response codes

Code	Meaning
200 OK	Transactions have been retrieved.
401 Unauthorized	The given client/user ID is not present in the OMS.
404 Not Found	No transactions have been found matching these parameters.
503 Service Unavailable	There is a temporary error preventing the request from completing. The client should retry the request at a later time.

ProductTransaction object

{
    "Date": "2015-06-29T00:00:00-05:00",
    "TransactionType": "Adjustment",
    "TransactionSourceId": "T000052",
    "ProductId": "PROD01",
    "Quantity": 2.0000000000,
    "UnitOfMeasure": "EACH",
    "UpdateIndex": 299
}

Key	Type	Required	Description
Date	Date	yes	The date of this transaction. Note, in some cases transactions may not be in date order.
TransactionType	string	The type of transaction. Possible values include "Purchase Receipt", "Sales Shipment", "Adjustment", "Consumption", "Output", and "Quarantine".
TransactionSourceId	string		The source of the transaction: a purchase receipt number, sales order number, etc.
ProductId	string	yes	The unique ID of the affected product.
Quantity	decimal	yes	The number of units affected by the transaction. A receipt will be positive, a something will be negative.
UnitOfMeasure	string	yes	The unit type affected. "EACH" is used for individual products, while other units of measure may be "CASE" etc. and depend on the product's configuration.
UpdateIndex	long	yes	The update index of this transaction.

Adding purchase orders

Sample request

PUT /v1/PurchaseOrders/{id} HTTP/1.1                
Content-Type: application/json; charset=utf-8
X-Ctl-ClientId: xxxx
X-Ctl-UserId: xxxx
X-Ctl-Overwrite: false
{
  "ExpectedReceiptDate": "2014-09-03T15:23:34+05:00",
  "Items": [
    {
      "Sku": "sample string 1",
      "Quantity": 2,
      "UnitOfMeasure": "EACH"
    },                
    {
      "Sku": "sample string 2",
      "Quantity": 3,
      "UnitOfMeasure": "CASE"
    },                
    {
      "Sku": "sample string 3",
      "Quantity": 4,
      "UnitOfMeasure": "ROLL"
    }
  ]
}

Sample response

HTTP/1.1 201 Created

Request

PUT v1/PurchaseOrders/{id}

Request parameters

Name	Description
{id}	The order's ID.
X-Ctl-Overwrite header	If true, overwrite an existing PO in the system. Only unprocessed POs can be overwritten. If the PO has already been processed, a 409 Conflict will be returned.

Body parameters

An Order object.

Response codes

Code	Meaning
201 Created	The order has been created.
400 Bad Request	The order data has failed validation and must be corrected. See Validation and error handling for more information.
401 Unauthorized	The given client/user ID is not present in the OMS.
409 Conflict	An order with that ID already exists and may not be updated.
503 Service Unavailable	There is a temporary error preventing the request from completing. The client should retry the request at a later time.

Order object

{
  "ExpectedReceiptDate": "2014-09-03T15:23:34+05:00",
  "Items": [
                        PurchaseOrderItem object,
                        PurchaseOrderItem object
  ],
  "VendorName": "Acme Manufacturing Co.",
  "InvoiceNumber": "12345"
}

Key	Type	Maximum length	Required	Description
ExpectedReceiptDate	string			The date the order is to be received. If specified, must be a valid ISO 8601 date and may include an offset.
Items	A list of PurchaseOrderItem objects		yes	The order's items.
VendorName	string	50		The name of the vendor supplying the goods.
InvoiceNumber	string	35		The invoice number associated by the vendor with this PO.
ReadyForProcessing	bool			If false, the PO is considered a draft and will not be processed. Typically used to notify CTL when a PO will be incoming but not all items have been finalized. The PO can be overwritten once finalized to indicate CTL should process it. Or, if a PO is no longer being sent, deleted.

PurchaseOrderItem object

{
  "Sku": "sample string 1",
  "Quantity": 4.6,
  "UnitOfMeasure": "ROLL"
}

Key	Type	Maximum length	Required	Description
Sku	string	40	yes	The product's unique ID, or a previously agreed upon alias. Must consist only of printable code points defined in the Windows-1252 character encoding.
Quantity	decimal		yes	The number of items to include in the order. Must be greater than zero.
UnitOfMeasure	string	10		The unit of measure, e.g. "EACH" or "CASE". The correct values here depend on configuration within CTL's ERP and are per-item. They will be established upon item setup. If not specified, the item's default receiving unit of measure will be used.

Closing purchase orders

This request closes a purchase order. It indicates to CTL that all expected receipts against this order have been made, and no further trucks will arrive.

Sample request

PUT /v1/PurchaseOrders/{id}/close HTTP/1.1
X-Ctl-ClientId: xxxx
X-Ctl-UserId: xxxx

Sample response

HTTP/1.1 204 No Content

Request

PUT /v1/PurchaseOrders/{id}/close

Request parameters

Name	Description
{id}	The order's ID.

Body parameters

None. This request has no content.

Response codes

Code	Meaning
204 No Content	The order has been closed.
401 Unauthorized	The given client/user ID is not present in the OMS.
404 Not Found	No order with that ID exists.
503 Service Unavailable	There is a temporary error preventing the request from completing. The client should retry the request at a later time.

Retrieving purchase receipts

Retrieves receipts against purchase orders. Note that received items may potentially be damaged and quarantined, and thus might not be part of available inventory. This endpoint should not be used to calculate overall inventory counts. For that, the Transaction History endpoint is more appropriate.

Because this endpoint can potentially return a large amount of data, results follow the streaming bulk data model.

Sample request

GET /v1/PurchaseReceipts/?fromUpdateId=422 HTTP/1.1
X-Ctl-ClientId: xxxx
X-Ctl-UserId: xxxx

Sample response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[  
    {  
        "Id":"PR00001",
        "PurchaseOrderId":"P00001",
        "ReceiptDate":"2015-07-02T00:00:00-05:00",
        "Items":[  
            {  
                "ProductId":"asdf",
                "Quantity":1.0000000000,
                "UnitOfMeasure":"EACH"
            }
        ],
        "UpdateIndex":425
    },
    {  
        "Id":"PR00002",
        "PurchaseOrderId":"P00001",
        "ReceiptDate":"2015-07-09T00:00:00-05:00",
        "Items":[  
            {  
                "ProductId":"asdf",
                "Quantity":1.0000000000,
                "UnitOfMeasure":"EACH"
            }
        ],
        "UpdateIndex":464
    },
    {  
        "Id":"PR0003",
        "PurchaseOrderId":"P00002",
        "ReceiptDate":"2015-07-13T00:00:00-05:00",
        "Items":[  
            {  
                "ProductId":"foo",
                "Quantity":2.0000000000,
                "UnitOfMeasure":"EACH"
            },
            {  
                "ProductId":"bar",
                "Quantity":3.0000000000,
                "UnitOfMeasure":"EACH"
            },
            {  
                "ProductId":"baz",
                "Quantity":5.0000000000,
                "UnitOfMeasure":"EACH"
            }
        ],
        "UpdateIndex":485
    }
]

Request

GET /v1/PurchaseReceipts/?fromUpdateId={fromUpdateId}

Request parameters

Name	Description
{fromUpdateId}	An update index, inclusive, to lookup order updates from. See the Querying new shipments sample to better understand usage.

Response content

A collection of PurchaseReceipt objects.

Response codes

Code	Meaning
200 OK	Purchase receipts have been retrieved.
401 Unauthorized	The given client/user ID is not present in the OMS.
404 Not Found	No purchase receipts have been found matching these parameters.
503 Service Unavailable	There is a temporary error preventing the request from completing. The client should retry the request at a later time.

PurchaseReceipt object

{
    "UpdateIndex":425,
    "Id":"PR00001",
    "PurchaseOrderId":"P00001",
    "ReceiptDate":"2015-07-02T00:00:00-05:00",
    "Items":[
                        PurchaseReceiptItem object,
                        PurchaseReceiptItem object
    ],
    "VendorScorecard":{
        "BoxLabeledWithQuantity": true,
        "BoxLabeledWithItemNumber": true,
        "BoxDamaged": false,
        "ProductLabeledWithItemNumber": true
    }
}

Key	Type	Description
Id	string	A unique ID assigned to the receipt by CTL.
PurchaseOrderId	string	The unique ID of the purchase order being received against.
ReceiptDate	Date	The date received.
Items	A list of PurchaseReceiptItem objects	The purchase receipt's items.
VendorScorecard.BoxLabeledWithQuantity	bool	If true, the box was labeled with contained quantities.
VendorScorecard.BoxLabeledWithItemNumber	bool	If true, the box was labeled with contained items.
VendorScorecard.BoxDamaged	bool	If true, the box was damaged.
VendorScorecard.ProductLabeledWithItemNumber	bool	If true, the products contained in the receipt were labeled with their item number.

PurchaseReceiptItem object

{  
    "ProductId":"foo",
    "Quantity":2.0000000000,
    "UnitOfMeasure":"EACH"
}

Key	Type	Required	Description
ProductId	string	yes	The unique ID of the product received.
Quantity	decimal	yes	The amount of units of product received.
UnitOfMeasure	string	yes	The type of unit received. "EACH" refers to individual products, while others might refer to containers of product. To confirm which units of measure are possible, please contact your account manager.

Adding Advanced Shipment Notices (ASNs)

Sample Request

PUT /v1/ASNs/{id} HTTP/1.1                
Content-Type: application/json; charset=utf-8
X-Ctl-ClientId: xxxx
X-Ctl-UserId: xxxx
X-Ctl-Overwrite: false
{
  "PurchaseDate": "2014-09-03T15:23:34+05:00",
  "ExpectedReceiptDate": "2014-09-03T15:23:34+05:00",
  "VendorName": "Acme Manufacturing Co.",
  "VendorInvoiceNumber": "12345",
  "JobNumber": "J339",
  "Items": [
    {
      "Sku": "AA009",
      "Quantity": 2,
      "UnitOfMeasure": "EACH",
      "VendorPartNumber": "ACMEANVIL009",
      "Description": "Acme Anvil's for all your metal forming and roadrunner hunting needs.",
      "CartonNumber": "BOX00221A"
    },                
    {
      "Sku": "sample string 2",
      "Quantity": 3,
      "UnitOfMeasure": "CASE"
    },                
    {
      "Sku": "sample string 3",
      "Quantity": 4,
      "UnitOfMeasure": "ROLL"
    }
  ]
}

Sample response

HTTP/1.1 201 Created

Request

PUT v1/ASNs/{id}

Request parameters

Name	Description
{id}	The ASN's ID.
X-Ctl-Overwrite header	If true, overwrite an existing ASN in the system. Only unprocessed ASNs can be overwritten. If the ASN has already been processed, a 409 Conflict will be returned.

Body parameters

An ASN object.

Response codes

Code	Meaning
201 Created	The ASN has been created.
400 Bad Request	The ASN data has failed validation and must be corrected. See Validation and error handling for more information.
401 Unauthorized	The given client/user ID is not present in the OMS.
409 Conflict	An ASN with that ID already exists and may not be updated.
503 Service Unavailable	There is a temporary error preventing the request from completing. The client should retry the request at a later time.

ASN Object

{
  "PurchaseDate": "2014-09-03T15:23:34+05:00",
  "InvoiceNumber": "12345"
  "ExpectedReceiptDate": "2014-09-03T15:23:34+05:00",
  "VendorName": "Acme Manufacturing Co.",
  "JobNumber": "J339",
  "Items": [
                        ASN Item object,
                        ASN Item object
  ],


}

Key	Type	Maximum length	Required	Description
PurchaseDate	string			A PurchaseDate to record for the ASN. If specified, must be a valid ISO 8601 date and may include an offset.
ExpectedReceiptDate	string			The date the order is to be received. If specified, must be a valid ISO 8601 date and may include an offset.
VendorName	string	50		The name of the vendor supplying the goods.
VendorInvoiceNumber	string	35		The invoice number associated by the vendor with this ASN.
JobNumber	string			The JobNumber associated with this ASN.
Items	A list of ASN Item objects		yes	The ASN's items.

ASN Item object

{
  "Sku": "sample string 1",
  "Quantity": 4,
  "UnitOfMeasure": "ROLL",
  "VendorPartNumber": "23335",
  "GroupCode": "c5a1861f-05e4-4804-b809-c26aa6164221",
}

Key	Type	Maximum length	Required	Description
Sku	string	40	yes	The product's unique ID, or a previously agreed upon alias. Must consist only of printable code points defined in the Windows-1252 character encoding.
Quantity	decimal		yes	The number of items to include in the order. Must be greater than zero.
UnitOfMeasure	string	10		The unit of measure, e.g. "EACH" or "CASE". The correct values here depend on configuration within CTL's ERP and are per-item. They will be established upon item setup. If not specified, the item's default receiving unit of measure will be used.
VendorPartNumber	string	50		The Vendor Part Number associated with this ASN Item.
Description	string	50		A Short Description of the Item that this record represents.
CartonNumber	string	20		An Identifier for the Carton (or pallet, shipping container, etc.) this item will arrive in. Unique to the ASN.
GroupCode	string	50		A Group Code to associate this item detail with a group. This might be unique to a group used for scanning during receiving.

Retrieving ASN Receipt status

This endpoint will retrieve a single ASN's status and is useful for real-time updates. For syncing multiple ASN Receipts, the bulk ASN Receipts API should be used instead.

Sample request

GET /v1/ASNs/{id} HTTP/1.1
Content-Type: application/json; charset=utf-8
X-Ctl-ClientId: xxxx
X-Ctl-UserId: xxxx

Sample response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
        "Id": "ACME6128",
        "PurchaseDate": "2021-09-21T00:00:00",
        "ExpectedReceiptDate": "2021-09-27T00:00:00",
        "VendorName": "ACME Tools",
        "VendorInvoiceNumber": null,
        "JobNumber": null,
        "Items": [
            {
                "Sku": "ACME0500009",
                "Quantity": 1.00000000000000000000,
                "UnitOfMeasure": "EACH",
                "VendorPartNumber": null,
                "Description": null,
                "CartonNumber": "ACME05000098",
                "SerialLotRange": "ACME0379-ACME7910",
                "SerialLotLow": "ACME7910",
                "SerialLotHigh": "ACME7910",
                "PostedReceiptDate": "2021-09-21T00:00:00"
            },
            {
                "Sku": "ACME0500009",
                "Quantity": 1.00000000000000000000,
                "UnitOfMeasure": "EACH",
                "VendorPartNumber": null,
                "Description": null,
                "CartonNumber": "2220005000098",
                "SerialLotRange": "ACME8515-ACME1580",
                "SerialLotLow": "ACME1580",
                "SerialLotHigh": "ACME1580",
                "PostedReceiptDate": "2021-09-21T00:00:00"
            },
            {
                "Sku": "ACME0500009",
                "Quantity": 1.00000000000000000000,
                "UnitOfMeasure": "EACH",
                "VendorPartNumber": null,
                "Description": null,
                "CartonNumber": "ACME05000098",
                "SerialLotRange": null,
                "SerialLotLow": null,
                "SerialLotHigh": null,
                "PostedReceiptDate": null
            },
            {
                "Sku": "222000500009",
                "Quantity": 1.00000000000000000000,
                "UnitOfMeasure": "EACH",
                "VendorPartNumber": null,
                "Description": null,
                "CartonNumber": "ACME05000098",
                "SerialLotRange": null,
                "SerialLotLow": null,
                "SerialLotHigh": null,
                "PostedReceiptDate": null
            }
        ],
        "UpdateIndex": 8558
    }

Response content

An ASN Receipt object.

ASN Receipt Object

{
  "PurchaseDate": "2014-09-03T15:23:34+05:00",
  "InvoiceNumber": "12345"
  "ExpectedReceiptDate": "2014-09-03T15:23:34+05:00",
  "VendorName": "Acme Manufacturing Co.",
  "JobNumber": "J339",
  "Items": [
                        ASN Receipt Item object,
                        ASN Receipt Item object
  ],


}

Key	Type	Maximum length	Required	Description
PurchaseDate	string			A PurchaseDate to record for the ASN. If specified, must be a valid ISO 8601 date and may include an offset.
ExpectedReceiptDate	string			The date the order is to be received. If specified, must be a valid ISO 8601 date and may include an offset.
VendorName	string	50		The name of the vendor supplying the goods.
VendorInvoiceNumber	string	35		The invoice number associated by the vendor with this ASN.
JobNumber	string			The JobNumber associated with this ASN.
Items	A list of ASN Item objects		yes	The ASN's items.

ASN Receipt Item object

{
  "Sku": "sample string 1",
  "Quantity": 4,
  "UnitOfMeasure": "ROLL",
  "VendorPartNumber": "23335"
}

Key	Type	Maximum length	Required	Description
Sku	string	40	yes	The product's unique ID, or a previously agreed upon alias. Must consist only of printable code points defined in the Windows-1252 character encoding.
Quantity	decimal		yes	The number of items to include in the order. Must be greater than zero.
UnitOfMeasure	string	10		The unit of measure, e.g. "EACH" or "CASE". The correct values here depend on configuration within CTL's ERP and are per-item. They will be established upon item setup. If not specified, the item's default receiving unit of measure will be used.
VendorPartNumber	string	50		The Vendor Part Number associated with this ASN Item.
Description	string	50		A Short Description of the Item that this record represents.
CartonNumber	string	20		An Identifier for the Carton (or pallet, shipping container, etc.) this item will arrive in. Unique to the ASN.
SerialLotRange	string	50		The Scanned Serial Lot Range for this Received Item.
SerialLotLow	string	25		The lower of the two alpha-numeric serial numbers that create a range.
SerialLotHigh	string	25		The higher of the two alpha-numeric serial numbers that create a range.
PurchaseDate	string			The Date that we've recorded the package as received in the warehouse. If null or empty, we have not received it.

Retrieving bulk ASN Receipt status

This endpoint is used to sync ASN Receipts.

Because this can return a large amount of data, results are paged. To retreive the next list of updates, one should keep track of the last "UpdateIndex" received from this service. You can then call this again with the "fromUpdateId" parameter to get any ASN Receipts which have been updated since your last try.

Sample request

GET /v1/ASNs/?fromUpdateId=1 HTTP/1.1
X-Ctl-ClientId: xxxx
X-Ctl-UserId: xxxx

Sample response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[                
  {
        "Id": "ACME6128",
        "PurchaseDate": "2021-09-21T00:00:00",
        "ExpectedReceiptDate": "2021-09-27T00:00:00",
        "VendorName": "ACME Tools",
        "VendorInvoiceNumber": null,
        "JobNumber": null,
        "Items": [
            {
                "Sku": "ACME0500009",
                "Quantity": 1.00000000000000000000,
                "UnitOfMeasure": "EACH",
                "VendorPartNumber": null,
                "Description": null,
                "CartonNumber": "ACME05000098",
                "SerialLotRange": "ACME0379-ACME7910",
                "SerialLotLow": "ACME7910",
                "SerialLotHigh": "ACME7910",
                "PostedReceiptDate": "2021-09-21T00:00:00"
            },
            {
                "Sku": "ACME0500009",
                "Quantity": 1.00000000000000000000,
                "UnitOfMeasure": "EACH",
                "VendorPartNumber": null,
                "Description": null,
                "CartonNumber": "2220005000098",
                "SerialLotRange": "ACME8515-ACME1580",
                "SerialLotLow": "ACME1580",
                "SerialLotHigh": "ACME1580",
                "PostedReceiptDate": "2021-09-21T00:00:00"
            },
            {
                "Sku": "ACME0500009",
                "Quantity": 1.00000000000000000000,
                "UnitOfMeasure": "EACH",
                "VendorPartNumber": null,
                "Description": null,
                "CartonNumber": "ACME05000098",
                "SerialLotRange": null,
                "SerialLotLow": null,
                "SerialLotHigh": null,
                "PostedReceiptDate": null
            },
            {
                "Sku": "222000500009",
                "Quantity": 1.00000000000000000000,
                "UnitOfMeasure": "EACH",
                "VendorPartNumber": null,
                "Description": null,
                "CartonNumber": "ACME05000098",
                "SerialLotRange": null,
                "SerialLotLow": null,
                "SerialLotHigh": null,
                "PostedReceiptDate": null
            }
        ],
        "UpdateIndex": 8558
    },
    {
        "Id": "ACME6129",
        "PurchaseDate": "2021-09-21T00:00:00",
        "ExpectedReceiptDate": "2021-09-27T00:00:00",
        "VendorName": "ACME Tools",
        "VendorInvoiceNumber": null,
        "JobNumber": null,
        "Items": [
            {
                "Sku": "ACME0500010",
                "Quantity": 1.00000000000000000000,
                "UnitOfMeasure": "EACH",
                "VendorPartNumber": null,
                "Description": null,
                "CartonNumber": "ACME05000104",
                "SerialLotRange": "ACME9199-ACME9932",
                "SerialLotLow": "ACME9199",
                "SerialLotHigh": "ACME9932",
                "PostedReceiptDate": "2021-09-21T00:00:00"
            },
            {
                "Sku": "ACME0500011",
                "Quantity": 1.00000000000000000000,
                "UnitOfMeasure": "EACH",
                "VendorPartNumber": null,
                "Description": null,
                "CartonNumber": "ACME05000111",
                "SerialLotRange": "ACME1062-ACME6261",
                "SerialLotLow": "ACME1062",
                "SerialLotHigh": "ACME6261",
                "PostedReceiptDate": "2021-09-21T00:00:00"
            }
        ],
        "UpdateIndex": 8559
    }
]

Response content

An array containing ASN Receipt objects.

Response codes

Code	Meaning
200 OK	ASN Receipts have been retrieved.
401 Unauthorized	The given client/user ID is not present in the OMS.
404 Not Found	No orders have been found matching these parameters.
503 Service Unavailable	There is a temporary error preventing the request from completing. The client should retry the request at a later time.

Retrieving sales returns

The sales returns log is a stream of returned shipments. Each log entry represents a posted sales return receipt. This endpoint is appropriate for syncing CTL's return counts with an external system.

Because this endpoint can potentially return a large amount of data, results follow the streaming bulk data model.

Sample request

GET /v1/Returns/?fromUpdateId=154 HTTP/1.1
X-Ctl-ClientId: xxxx
X-Ctl-UserId: xxxx

Sample response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[{
    "Id": "SR00154",
    "DateCreated": "2015-06-29T15:57:32-05:00",
    "OrderId": "SO01592",
    "ReasonCode": "001",
    "Notes": "",
    "Stream": "ZZ-CO",
    "Items": [
                        ReturnItem object,
                        ReturnItem object
    ],
    "UpdateIndex": 154
}, {
    "Id": "SR00155",
    "DateCreated": "2015-06-30T14:31:42-05:00",
    "OrderId": "SO01652",
    "ReasonCode": "005",
    "Notes": "",
    "Stream": "ZZ-CO",
    "Items": [
                        ReturnItem object,
                        ReturnItem object,
                        ReturnItem object,
                        ReturnItem object
    ],
    "UpdateIndex": 155
}, {
    "Id": "SR00156",
    "DateCreated": "2015-06-30T15:30:21-05:00",
    "OrderId": "SO01921",
    "ReasonCode": "003",
    "Notes": "",
    "Stream": "ZZ-CO",
    "Items": [
                        ReturnItem object,
                        ReturnItem object,
                        ReturnItem object
    ],
    "UpdateIndex": 156
}, {
    "Id": "SR00157",
    "DateCreated": "2015-06-30T20:12:56-05:00",
    "OrderId": "SO01438",
    "ReasonCode": "001",
    "Notes": "",
    "Stream": "ZZ-CO",
    "Items": [
                        ReturnItem object
    ],
    "UpdateIndex": 157
}]

Request

GET /v1/Returns/?fromUpdateId={fromUpdateId}

Request parameters

Name	Description
{fromUpdateId}	An update index, inclusive, to lookup posted shipping returns from (update index represents the Id of a specific Return). See the Querying new shipments sample to better understand usage.

Response content

A collection of Return objects.

Response codes

Code	Meaning
200 OK	A list of returns has been retrieved.
401 Unauthorized	The given client/user ID is not present in the OMS.
404 Not Found	No returns have been found matching these parameters.
503 Service Unavailable	There is a temporary error preventing the request from completing. The client should retry the request at a later time.

Return object

{
    "Id": "SR00157",
    "DateCreated": "2015-06-30T20:12:56-05:00",
    "OrderId": "SO01592",
    "Notes": "Items delivered were not as described.\nRecipient needed same items but three sizes larger.",
    "Stream": "ZZ-CO",
    "Items": [
                        ReturnItem object,
                        ReturnItem object
    ],
    "UpdateIndex": 157
}

Key	Type	Required	Description
Id	string	yes	The unique Id of the return.
DateCreated	date	yes	The date the return was posted.
OrderId	string	yes	The sales order that the return originated from. If there is no sales order, this will be set to the same value as the Return's Id.
Stream	string	yes	The name of the stream that this return originated from.
Notes	string	no	Any notes related to the return. Notes are optional, and if there are multiple notes, they will be separated by the \n (newline) character.
Items	A list of ReturnItem objects	yes	The item/s included in the return shipment.
UpdateIndex	long	yes	The update index of this return.

ReturnItem object

{
    "ProductId": "SR00157",
    "Quantity": 2,
    "ReasonCode": "001",
    "Notes": "Two red widgets\nTwo of five were damaged during shipment."    
}

Key	Type	Required	Description
ProductId	string	yes	The product ID of the item returned.
Quantity	decimal	yes	The quantity of items being returned. This may differ from the quantity of items originally shipped.
ReasonCode	string	yes	Represents the reason the items were returns. Reason codes are client-specific.
Notes	string	no	Any notes related to the item. Notes are optional, and if there are multiple notes, they will be separated by the \n (newline) character.

Samples

Querying for a large amount of orders

This pseudocode shows how to process paged orders when a query produces too many results for one response.

page0 = GET '/v1/Orders?query=foo'

if(page0.IsTruncated)
{
    // truncated results, query too broad.
}

// do something with page0.items...

for(i = 1; i < page0.TotalPages; ++i)
{
    nextPage = GET '/v1/Orders?pageKey=' + page0.PageKey + '-' + i;
    // do something with nextPage.items...
}

Querying new shipments

This pseudocode shows the typical process that would be used to regularly retrieve ship-confirmation and tracking numbers for orders.

updateIndex = 0

while(true)
{
    while(true)
    {
        page = GET '/v1/Orders?fromUpdateId=' + updateIndex;
        
        if(page.Length == 0)
        {
            break;
        }
        
        // do something with page, then...
        
        // set updateIndex to a new starting point.
        updateIndex = page.Last.UpdateIndex + 1;
    }
    
    // now wait until the next scheduled sync time.
    Sleep(1d);
}