Orders

API change history

Provides 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)
    string
    Media type of the body sent to the API.
  • string
    Subscription key which provides access to this API. Found in your Profile.

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