Orders
API change historyProvides methods for working with order processing and settings.
Import External Order
This API allows clients to import an order that has been processed by a system external to DirectScale. This API imports order data for commission calculations only. It is therefore assumed that all processing, billing, shipping of goods, etc. for the order was done by the external system.
Order Types
OrderType
is optional, and will be set to "Standard" by default if not passed in as part of the request. If OrderType
is passed in as part of the request object, please ensure one of the following integers are used:
- Standard -
null
, 0, or 1 - AutoShip - 2
- Enrollment - 3
Duplicate Item/Sku Combinations
If the request contains multiple line items with the same ItemId
and SKU
, these line items will be combined and the quantity will be updated to be the sum of all line item quantities in question.
Mapping External Items to the DirectScale System
A valid order line item must be tied to an external order in order for it to show up in the DirectScale system. For this purpose the request makes both SKU
and ItemId
available for mapping. Both, one, or the other may be used to map the given item to an inventory item in the DirectScale inventory system. The logic in the API will attempt to find a match, first using the ItemId
and then using the SKU
.
However, sometimes there is no direct mapping. In these situations, a single order line item will be created and applied to the order with the Import Order Default
Item ID as the ItemId
. For Example, consider the sample line item request below. Both the ItemId
and the SKU
are blank. In this situation, the Import Order Default
Item ID will be assigned as the the order line item's Item ID.
{
"ItemId": 0,
"Sku": "",
"ProductName": "Sample Product Name",
"Quantity": 1,
"Price": 123.45
}
Try it
Request
Request URL
Request headers
-
(optional)stringMedia type of the body sent to the API.
Request body
Required Fields:
- CustomerId
- Get Customers
- Get Customer by Filter
- ExternalOrderId
- Get Customer
- Get Customer by Parameter
- CommissionDate
- Not sourced by DirectScale
Uniqueness Required:
- ExternalOrderId
{
"CustomerId": 2,
"OrderType": 1,
"ExternalOrderId": "321123",
"OrderDate": "2020-03-30T00:00:00Z",
"CommissionDate": "2020-03-30T00:00:00Z",
"EmailAddress": "testcust@asdfmail.com",
"InvoiceDate": "2020-03-30T00:00:00Z",
"PartyId": 0,
"PriceGroupId": 1,
"ShippingAddress": {
"Street1": "123 Test Way",
"Street2": "",
"City": "Placerville",
"PostalCode": "95667",
"Region": "CA",
"CountryCode": "US"
},
"Phone": "123-456-7890",
"SpecialInstructions": "Special Instructions Text",
"CurrencyCode": "usd",
"LineItems": [
{
"ItemId": 11,
"Sku": "",
"ProductName": "Widget",
"Quantity": 2,
"Price": 123.45
},
{
"ItemId": 0,
"Sku": "DEF-456",
"ProductName": "Gadget",
"Quantity": 1,
"Price": 176.55
}
],
"SubTotal": 300,
"ShippingTotal": 5.5,
"TaxTotal": 6.5,
"Total": 311,
"TotalCv": 50,
"TotalQv": 50,
"TotalBonus": 100,
"CustomFields": {
"Field1": "12345",
"Field2": "Some text here",
"Field3": "1|55|33",
"Field4": "Another value",
"Field5": "-22.35"
}
}
{
"required": [
"CustomerId",
"CommissionDate",
"ExternalOrderId"
],
"type": "object",
"properties": {
"CustomerId": {
"type": "integer"
},
"OrderType": {
"type": "integer"
},
"ExternalOrderId": {
"type": "string"
},
"OrderDate": {
"type": "string"
},
"CommissionDate": {
"type": "string"
},
"EmailAddress": {
"type": "string"
},
"InvoiceDate": {
"type": "string"
},
"PartyId": {
"type": "integer"
},
"PriceGroupId": {
"type": "integer"
},
"ShippingAddress": {
"type": "object",
"properties": {
"Street1": {
"type": "string"
},
"Street2": {
"type": "string"
},
"City": {
"type": "string"
},
"PostalCode": {
"type": "string"
},
"Region": {
"type": "string"
},
"CountryCode": {
"type": "string"
}
}
},
"Phone": {
"type": "string"
},
"SpecialInstructions": {
"type": "string"
},
"CurrencyCode": {
"type": "string"
},
"LineItems": {
"type": "array",
"items": {
"required": [
"ItemId",
"Sku",
"ProductName",
"Quantity",
"Price"
],
"type": "object",
"properties": {
"ItemId": {
"type": "integer"
},
"Sku": {
"type": "string"
},
"ProductName": {
"type": "string"
},
"Quantity": {
"type": "integer"
},
"Price": {
"type": "number"
}
}
}
},
"SubTotal": {
"type": "integer"
},
"ShippingTotal": {
"type": "number"
},
"TaxTotal": {
"type": "number"
},
"Total": {
"type": "integer"
},
"TotalCv": {
"type": "integer"
},
"TotalQv": {
"type": "integer"
},
"TotalBonus": {
"type": "integer"
},
"CustomFields": {
"type": "object",
"properties": {
"Field1": {
"type": "string"
},
"Field2": {
"type": "string"
},
"Field3": {
"type": "string"
},
"Field4": {
"type": "string"
},
"Field5": {
"type": "string"
}
}
}
},
"example": {
"CustomerId": 2,
"OrderType": 1,
"ExternalOrderId": "321123",
"OrderDate": "2020-03-30",
"CommissionDate": "2020-03-30",
"EmailAddress": "testcust@asdfmail.com",
"InvoiceDate": "2020-03-30",
"PartyId": 0,
"PriceGroupId": 1,
"ShippingAddress": {
"Street1": "123 Test Way",
"Street2": "",
"City": "Placerville",
"PostalCode": "95667",
"Region": "CA",
"CountryCode": "US"
},
"Phone": "123-456-7890",
"SpecialInstructions": "Special Instructions Text",
"CurrencyCode": "usd",
"LineItems": [
{
"ItemId": 11,
"Sku": "",
"ProductName": "Widget",
"Quantity": 2,
"Price": 123.45
},
{
"ItemId": 0,
"Sku": "DEF-456",
"ProductName": "Gadget",
"Quantity": 1,
"Price": 176.55
}
],
"SubTotal": 300,
"ShippingTotal": 5.5,
"TaxTotal": 6.5,
"Total": 311,
"TotalCv": 50,
"TotalQv": 50,
"TotalBonus": 100,
"CustomFields": {
"Field1": "12345",
"Field2": "Some text here",
"Field3": "1|55|33",
"Field4": "Another value",
"Field5": "-22.35"
}
}
}
{
"CustomerId": 2,
"ExternalOrderId": "Jango Fett",
"CommissionDate": "2020-12-25T00:00:00Z",
"SubTotal": 100,
"ShippingTotal": 5,
"TaxTotal": 6,
"Total": 111,
"TotalCv": 5,
"TotalQv": 5,
"TotalBonus": 1000
}
Responses
201 Created
Order successfully imported.
400 Bad Request
Returns one of an array of different error possibilities. Please refer to the error description for greater detail.
Code samples
@ECHO OFF
curl -v -X POST "https://dsapi.directscale.com/v1/orders/external-orders"
-H "Content-Type: application/json (full)"
-H "Ocp-Apim-Subscription-Key: {subscription key}"
--data-ascii "{body}"
using System;
using System.Net.Http.Headers;
using System.Text;
using System.Net.Http;
using System.Web;
namespace CSHttpClientSample
{
static class Program
{
static void Main()
{
MakeRequest();
Console.WriteLine("Hit ENTER to exit...");
Console.ReadLine();
}
static async void MakeRequest()
{
var client = new HttpClient();
var queryString = HttpUtility.ParseQueryString(string.Empty);
// Request headers
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");
var uri = "https://dsapi.directscale.com/v1/orders/external-orders?" + queryString;
HttpResponseMessage response;
// Request body
byte[] byteData = Encoding.UTF8.GetBytes("{body}");
using (var content = new ByteArrayContent(byteData))
{
content.Headers.ContentType = new MediaTypeHeaderValue("< your content type, i.e. application/json >");
response = await client.PostAsync(uri, content);
}
}
}
}
// // This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
import java.net.URI;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
public class JavaSample
{
public static void main(String[] args)
{
HttpClient httpclient = HttpClients.createDefault();
try
{
URIBuilder builder = new URIBuilder("https://dsapi.directscale.com/v1/orders/external-orders");
URI uri = builder.build();
HttpPost request = new HttpPost(uri);
request.setHeader("Content-Type", "application/json (full)");
request.setHeader("Ocp-Apim-Subscription-Key", "{subscription key}");
// Request body
StringEntity reqEntity = new StringEntity("{body}");
request.setEntity(reqEntity);
HttpResponse response = httpclient.execute(request);
HttpEntity entity = response.getEntity();
if (entity != null)
{
System.out.println(EntityUtils.toString(entity));
}
}
catch (Exception e)
{
System.out.println(e.getMessage());
}
}
}
<!DOCTYPE html>
<html>
<head>
<title>JSSample</title>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
</head>
<body>
<script type="text/javascript">
$(function() {
var params = {
// Request parameters
};
$.ajax({
url: "https://dsapi.directscale.com/v1/orders/external-orders?" + $.param(params),
beforeSend: function(xhrObj){
// Request headers
xhrObj.setRequestHeader("Content-Type","application/json (full)");
xhrObj.setRequestHeader("Ocp-Apim-Subscription-Key","{subscription key}");
},
type: "POST",
// Request body
data: "{body}",
})
.done(function(data) {
alert("success");
})
.fail(function() {
alert("error");
});
});
</script>
</body>
</html>
#import <Foundation/Foundation.h>
int main(int argc, const char * argv[])
{
NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
NSString* path = @"https://dsapi.directscale.com/v1/orders/external-orders";
NSArray* array = @[
// Request parameters
@"entities=true",
];
NSString* string = [array componentsJoinedByString:@"&"];
path = [path stringByAppendingFormat:@"?%@", string];
NSLog(@"%@", path);
NSMutableURLRequest* _request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:path]];
[_request setHTTPMethod:@"POST"];
// Request headers
[_request setValue:@"application/json (full)" forHTTPHeaderField:@"Content-Type"];
[_request setValue:@"{subscription key}" forHTTPHeaderField:@"Ocp-Apim-Subscription-Key"];
// Request body
[_request setHTTPBody:[@"{body}" dataUsingEncoding:NSUTF8StringEncoding]];
NSURLResponse *response = nil;
NSError *error = nil;
NSData* _connectionData = [NSURLConnection sendSynchronousRequest:_request returningResponse:&response error:&error];
if (nil != error)
{
NSLog(@"Error: %@", error);
}
else
{
NSError* error = nil;
NSMutableDictionary* json = nil;
NSString* dataString = [[NSString alloc] initWithData:_connectionData encoding:NSUTF8StringEncoding];
NSLog(@"%@", dataString);
if (nil != _connectionData)
{
json = [NSJSONSerialization JSONObjectWithData:_connectionData options:NSJSONReadingMutableContainers error:&error];
}
if (error || !json)
{
NSLog(@"Could not parse loaded json with error:%@", error);
}
NSLog(@"%@", json);
_connectionData = nil;
}
[pool drain];
return 0;
}
<?php
// This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
require_once 'HTTP/Request2.php';
$request = new Http_Request2('https://dsapi.directscale.com/v1/orders/external-orders');
$url = $request->getUrl();
$headers = array(
// Request headers
'Content-Type' => 'application/json (full)',
'Ocp-Apim-Subscription-Key' => '{subscription key}',
);
$request->setHeader($headers);
$parameters = array(
// Request parameters
);
$url->setQueryVariables($parameters);
$request->setMethod(HTTP_Request2::METHOD_POST);
// Request body
$request->setBody("{body}");
try
{
$response = $request->send();
echo $response->getBody();
}
catch (HttpException $ex)
{
echo $ex;
}
?>
########### Python 2.7 #############
import httplib, urllib, base64
headers = {
# Request headers
'Content-Type': 'application/json (full)',
'Ocp-Apim-Subscription-Key': '{subscription key}',
}
params = urllib.urlencode({
})
try:
conn = httplib.HTTPSConnection('dsapi.directscale.com')
conn.request("POST", "/v1/orders/external-orders?%s" % params, "{body}", headers)
response = conn.getresponse()
data = response.read()
print(data)
conn.close()
except Exception as e:
print("[Errno {0}] {1}".format(e.errno, e.strerror))
####################################
########### Python 3.2 #############
import http.client, urllib.request, urllib.parse, urllib.error, base64
headers = {
# Request headers
'Content-Type': 'application/json (full)',
'Ocp-Apim-Subscription-Key': '{subscription key}',
}
params = urllib.parse.urlencode({
})
try:
conn = http.client.HTTPSConnection('dsapi.directscale.com')
conn.request("POST", "/v1/orders/external-orders?%s" % params, "{body}", headers)
response = conn.getresponse()
data = response.read()
print(data)
conn.close()
except Exception as e:
print("[Errno {0}] {1}".format(e.errno, e.strerror))
####################################
require 'net/http'
uri = URI('https://dsapi.directscale.com/v1/orders/external-orders')
request = Net::HTTP::Post.new(uri.request_uri)
# Request headers
request['Content-Type'] = 'application/json (full)'
# Request headers
request['Ocp-Apim-Subscription-Key'] = '{subscription key}'
# Request body
request.body = "{body}"
response = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
http.request(request)
end
puts response.body