Submit Orders
Uri: https://api.finerworks.com/v3/submit_orders
Method: POST
Submits a list of new orders (up to 5 at a time) which includes customer details (sender and recipient) as well as line item details and optional display fields for the packing slip. Once an order is successfully submitted it will return a confirmation (order reference id) and place the order into an accepted status and ultimately in our production que.
Body
| Name | Description | Type | Additional information |
|---|---|---|---|
| orders |
A list of orders which contain specifics of the order being submitted |
array (order_details) |
Required |
| validate_only |
Default is always false. Set to "true" only if you want to pre-check your orders first and do not want the orders to be actually submitted. The response will simply provide a success status or notify you what is incomplete. |
boolean |
None. |
Example JSON Body
application/json, text/json
{
"orders": [
{
"order_po": "PO_0001",
"order_key": null,
"recipient": {
"first_name": "Bob",
"last_name": "Ross",
"company_name": "Happy Little Trees, Inc",
"address_1": "742 Evergreen Terrace",
"address_2": null,
"address_3": null,
"city": "Mountain Scene",
"state_code": "AK",
"province": null,
"zip_postal_code": "88888",
"country_code": "us",
"phone": "555-555-5555",
"email": null,
"address_order_po": "PO_0001"
},
"order_items": [
{
"product_order_po": "PO_0001",
"product_qty": 1,
"product_sku": "AP1234P1234",
"product_image": null,
"product_title": "The Big Blue Mountain",
"template": null,
"product_guid": "00000000-0000-0000-0000-000000000000",
"custom_data_1": null,
"custom_data_2": null,
"custom_data_3": null
}
],
"shipping_code": "SD",
"ship_by_date": null,
"customs_tax_info": null,
"gift_message": null,
"test_mode": false,
"webhook_order_status_url": null,
"document_url": null,
"acct_number_ups": null,
"acct_number_fedex": null,
"custom_data_1": null,
"custom_data_2": null,
"custom_data_3": null
},
{
"order_po": "PO_0002",
"order_key": null,
"recipient": {
"first_name": "Bob",
"last_name": "Ross",
"company_name": "Happy Little Trees, Inc",
"address_1": "742 Evergreen Terrace",
"address_2": null,
"address_3": null,
"city": "Mountain Scene",
"state_code": "AK",
"province": null,
"zip_postal_code": "88888",
"country_code": "us",
"phone": "555-555-5555",
"email": null,
"address_order_po": "PO_0002"
},
"order_items": [
{
"product_order_po": "PO_0002",
"product_qty": 1,
"product_sku": "AP1234P1234",
"product_image": null,
"product_title": "The Big Blue Mountain",
"template": null,
"product_guid": "00000000-0000-0000-0000-000000000000",
"custom_data_1": null,
"custom_data_2": null,
"custom_data_3": null
}
],
"shipping_code": "SD",
"ship_by_date": null,
"customs_tax_info": null,
"gift_message": null,
"test_mode": false,
"webhook_order_status_url": null,
"document_url": null,
"acct_number_ups": null,
"acct_number_fedex": null,
"custom_data_1": null,
"custom_data_2": null,
"custom_data_3": null
}
],
"validate_only": false
}
Sample Code Library
curl --location --request sample_method 'https://api.finerworks.comsample_endpoint' \
--header 'Content-Type: application/json' \
--header 'web_api_key: my-web-api-key-goes-here' \
--header 'app_key: my-app-key-goes-here' \
--data-raw '{
"orders": [
{
"order_po": "PO_0001",
"order_key": null,
"recipient": {
"first_name": "Bob",
"last_name": "Ross",
"company_name": "Happy Little Trees, Inc",
"address_1": "742 Evergreen Terrace",
"address_2": null,
"address_3": null,
"city": "Mountain Scene",
"state_code": "AK",
"province": null,
"zip_postal_code": "88888",
"country_code": "us",
"phone": "555-555-5555",
"email": null,
"address_order_po": "PO_0001"
},
"order_items": [
{
"product_order_po": "PO_0001",
"product_qty": 1,
"product_sku": "AP1234P1234",
"product_image": null,
"product_title": "The Big Blue Mountain",
"template": null,
"product_guid": "00000000-0000-0000-0000-000000000000",
"custom_data_1": null,
"custom_data_2": null,
"custom_data_3": null
}
],
"shipping_code": "SD",
"ship_by_date": null,
"customs_tax_info": null,
"gift_message": null,
"test_mode": false,
"webhook_order_status_url": null,
"document_url": null,
"acct_number_ups": null,
"acct_number_fedex": null,
"custom_data_1": null,
"custom_data_2": null,
"custom_data_3": null
},
{
"order_po": "PO_0002",
"order_key": null,
"recipient": {
"first_name": "Bob",
"last_name": "Ross",
"company_name": "Happy Little Trees, Inc",
"address_1": "742 Evergreen Terrace",
"address_2": null,
"address_3": null,
"city": "Mountain Scene",
"state_code": "AK",
"province": null,
"zip_postal_code": "88888",
"country_code": "us",
"phone": "555-555-5555",
"email": null,
"address_order_po": "PO_0002"
},
"order_items": [
{
"product_order_po": "PO_0002",
"product_qty": 1,
"product_sku": "AP1234P1234",
"product_image": null,
"product_title": "The Big Blue Mountain",
"template": null,
"product_guid": "00000000-0000-0000-0000-000000000000",
"custom_data_1": null,
"custom_data_2": null,
"custom_data_3": null
}
],
"shipping_code": "SD",
"ship_by_date": null,
"customs_tax_info": null,
"gift_message": null,
"test_mode": false,
"webhook_order_status_url": null,
"document_url": null,
"acct_number_ups": null,
"acct_number_fedex": null,
"custom_data_1": null,
"custom_data_2": null,
"custom_data_3": null
}
],
"validate_only": false
}'
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.finerworks.comsample_endpoint');
$request->setMethod(HTTP_Request2::METHOD_sample_method);
$request->setConfig(array(
'follow_redirects' => TRUE
));
$request->setHeader(array(
'Content-Type' => 'application/json',
'web_api_key' => 'my-web-api-key-goes-here',
'app_key' => 'my-app-key-goes-here'
));
$request->setBody('{
'orders': [
{
'order_po': 'PO_0001',
'order_key': null,
'recipient': {
'first_name': 'Bob',
'last_name': 'Ross',
'company_name': 'Happy Little Trees, Inc',
'address_1': '742 Evergreen Terrace',
'address_2': null,
'address_3': null,
'city': 'Mountain Scene',
'state_code': 'AK',
'province': null,
'zip_postal_code': '88888',
'country_code': 'us',
'phone': '555-555-5555',
'email': null,
'address_order_po': 'PO_0001'
},
'order_items': [
{
'product_order_po': 'PO_0001',
'product_qty': 1,
'product_sku': 'AP1234P1234',
'product_image': null,
'product_title': 'The Big Blue Mountain',
'template': null,
'product_guid': '00000000-0000-0000-0000-000000000000',
'custom_data_1': null,
'custom_data_2': null,
'custom_data_3': null
}
],
'shipping_code': 'SD',
'ship_by_date': null,
'customs_tax_info': null,
'gift_message': null,
'test_mode': false,
'webhook_order_status_url': null,
'document_url': null,
'acct_number_ups': null,
'acct_number_fedex': null,
'custom_data_1': null,
'custom_data_2': null,
'custom_data_3': null
},
{
'order_po': 'PO_0002',
'order_key': null,
'recipient': {
'first_name': 'Bob',
'last_name': 'Ross',
'company_name': 'Happy Little Trees, Inc',
'address_1': '742 Evergreen Terrace',
'address_2': null,
'address_3': null,
'city': 'Mountain Scene',
'state_code': 'AK',
'province': null,
'zip_postal_code': '88888',
'country_code': 'us',
'phone': '555-555-5555',
'email': null,
'address_order_po': 'PO_0002'
},
'order_items': [
{
'product_order_po': 'PO_0002',
'product_qty': 1,
'product_sku': 'AP1234P1234',
'product_image': null,
'product_title': 'The Big Blue Mountain',
'template': null,
'product_guid': '00000000-0000-0000-0000-000000000000',
'custom_data_1': null,
'custom_data_2': null,
'custom_data_3': null
}
],
'shipping_code': 'SD',
'ship_by_date': null,
'customs_tax_info': null,
'gift_message': null,
'test_mode': false,
'webhook_order_status_url': null,
'document_url': null,
'acct_number_ups': null,
'acct_number_fedex': null,
'custom_data_1': null,
'custom_data_2': null,
'custom_data_3': null
}
],
'validate_only': false
}');
try {
$response = $request->send();
if ($response->getStatus() == 200) {
echo $response->getBody();
}
else {
echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
$response->getReasonPhrase();
}
}
catch(HTTP_Request2_Exception $e) {
echo 'Error: ' . $e->getMessage();
}
var client = new RestClient("https://api.finerworks.comsample_endpoint");
client.Timeout = -1;
var request = new RestRequest(Method.sample_method);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("web_api_key", "my-web-api-key-goes-here");
request.AddHeader("app_key", "my-app-key-goes-here");
request.AddParameter("application/json", "{
'orders': [
{
'order_po': 'PO_0001',
'order_key': null,
'recipient': {
'first_name': 'Bob',
'last_name': 'Ross',
'company_name': 'Happy Little Trees, Inc',
'address_1': '742 Evergreen Terrace',
'address_2': null,
'address_3': null,
'city': 'Mountain Scene',
'state_code': 'AK',
'province': null,
'zip_postal_code': '88888',
'country_code': 'us',
'phone': '555-555-5555',
'email': null,
'address_order_po': 'PO_0001'
},
'order_items': [
{
'product_order_po': 'PO_0001',
'product_qty': 1,
'product_sku': 'AP1234P1234',
'product_image': null,
'product_title': 'The Big Blue Mountain',
'template': null,
'product_guid': '00000000-0000-0000-0000-000000000000',
'custom_data_1': null,
'custom_data_2': null,
'custom_data_3': null
}
],
'shipping_code': 'SD',
'ship_by_date': null,
'customs_tax_info': null,
'gift_message': null,
'test_mode': false,
'webhook_order_status_url': null,
'document_url': null,
'acct_number_ups': null,
'acct_number_fedex': null,
'custom_data_1': null,
'custom_data_2': null,
'custom_data_3': null
},
{
'order_po': 'PO_0002',
'order_key': null,
'recipient': {
'first_name': 'Bob',
'last_name': 'Ross',
'company_name': 'Happy Little Trees, Inc',
'address_1': '742 Evergreen Terrace',
'address_2': null,
'address_3': null,
'city': 'Mountain Scene',
'state_code': 'AK',
'province': null,
'zip_postal_code': '88888',
'country_code': 'us',
'phone': '555-555-5555',
'email': null,
'address_order_po': 'PO_0002'
},
'order_items': [
{
'product_order_po': 'PO_0002',
'product_qty': 1,
'product_sku': 'AP1234P1234',
'product_image': null,
'product_title': 'The Big Blue Mountain',
'template': null,
'product_guid': '00000000-0000-0000-0000-000000000000',
'custom_data_1': null,
'custom_data_2': null,
'custom_data_3': null
}
],
'shipping_code': 'SD',
'ship_by_date': null,
'customs_tax_info': null,
'gift_message': null,
'test_mode': false,
'webhook_order_status_url': null,
'document_url': null,
'acct_number_ups': null,
'acct_number_fedex': null,
'custom_data_1': null,
'custom_data_2': null,
'custom_data_3': null
}
],
'validate_only': false
}, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var settings = {
"url": "https://api.finerworks.comsample_endpoint",
"method": "sample_method",
"timeout": 0,
"headers": {
"Content-Type": "application/json",
"web_api_key": "my-web-api-key-goes-here",
"app_key": "my-app-key-goes-here"
},
"data": JSON.stringify({
'orders': [
{
'order_po': 'PO_0001',
'order_key': null,
'recipient': {
'first_name': 'Bob',
'last_name': 'Ross',
'company_name': 'Happy Little Trees, Inc',
'address_1': '742 Evergreen Terrace',
'address_2': null,
'address_3': null,
'city': 'Mountain Scene',
'state_code': 'AK',
'province': null,
'zip_postal_code': '88888',
'country_code': 'us',
'phone': '555-555-5555',
'email': null,
'address_order_po': 'PO_0001'
},
'order_items': [
{
'product_order_po': 'PO_0001',
'product_qty': 1,
'product_sku': 'AP1234P1234',
'product_image': null,
'product_title': 'The Big Blue Mountain',
'template': null,
'product_guid': '00000000-0000-0000-0000-000000000000',
'custom_data_1': null,
'custom_data_2': null,
'custom_data_3': null
}
],
'shipping_code': 'SD',
'ship_by_date': null,
'customs_tax_info': null,
'gift_message': null,
'test_mode': false,
'webhook_order_status_url': null,
'document_url': null,
'acct_number_ups': null,
'acct_number_fedex': null,
'custom_data_1': null,
'custom_data_2': null,
'custom_data_3': null
},
{
'order_po': 'PO_0002',
'order_key': null,
'recipient': {
'first_name': 'Bob',
'last_name': 'Ross',
'company_name': 'Happy Little Trees, Inc',
'address_1': '742 Evergreen Terrace',
'address_2': null,
'address_3': null,
'city': 'Mountain Scene',
'state_code': 'AK',
'province': null,
'zip_postal_code': '88888',
'country_code': 'us',
'phone': '555-555-5555',
'email': null,
'address_order_po': 'PO_0002'
},
'order_items': [
{
'product_order_po': 'PO_0002',
'product_qty': 1,
'product_sku': 'AP1234P1234',
'product_image': null,
'product_title': 'The Big Blue Mountain',
'template': null,
'product_guid': '00000000-0000-0000-0000-000000000000',
'custom_data_1': null,
'custom_data_2': null,
'custom_data_3': null
}
],
'shipping_code': 'SD',
'ship_by_date': null,
'customs_tax_info': null,
'gift_message': null,
'test_mode': false,
'webhook_order_status_url': null,
'document_url': null,
'acct_number_ups': null,
'acct_number_fedex': null,
'custom_data_1': null,
'custom_data_2': null,
'custom_data_3': null
}
],
'validate_only': false
}),
};
$.ajax(settings).done(function (response) {
console.log(response);
});
var https = require('follow-redirects').https;
var fs = require('fs');
var options = {
'method': 'sample_method',
'hostname': 'api.finerworks.com',
'path': 'sample_endpoint',
'headers': {
'Content-Type': 'application/json',
'web_api_key': 'my-web-api-key-goes-here',
'app_key': 'my-app-key-goes-here'
},
'maxRedirects': 20
};
var req = https.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function (chunk) {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
res.on("error", function (error) {
console.error(error);
});
});
var postData = JSON.stringify({
"orders": [
{
"order_po": "PO_0001",
"order_key": null,
"recipient": {
"first_name": "Bob",
"last_name": "Ross",
"company_name": "Happy Little Trees, Inc",
"address_1": "742 Evergreen Terrace",
"address_2": null,
"address_3": null,
"city": "Mountain Scene",
"state_code": "AK",
"province": null,
"zip_postal_code": "88888",
"country_code": "us",
"phone": "555-555-5555",
"email": null,
"address_order_po": "PO_0001"
},
"order_items": [
{
"product_order_po": "PO_0001",
"product_qty": 1,
"product_sku": "AP1234P1234",
"product_image": null,
"product_title": "The Big Blue Mountain",
"template": null,
"product_guid": "00000000-0000-0000-0000-000000000000",
"custom_data_1": null,
"custom_data_2": null,
"custom_data_3": null
}
],
"shipping_code": "SD",
"ship_by_date": null,
"customs_tax_info": null,
"gift_message": null,
"test_mode": false,
"webhook_order_status_url": null,
"document_url": null,
"acct_number_ups": null,
"acct_number_fedex": null,
"custom_data_1": null,
"custom_data_2": null,
"custom_data_3": null
},
{
"order_po": "PO_0002",
"order_key": null,
"recipient": {
"first_name": "Bob",
"last_name": "Ross",
"company_name": "Happy Little Trees, Inc",
"address_1": "742 Evergreen Terrace",
"address_2": null,
"address_3": null,
"city": "Mountain Scene",
"state_code": "AK",
"province": null,
"zip_postal_code": "88888",
"country_code": "us",
"phone": "555-555-5555",
"email": null,
"address_order_po": "PO_0002"
},
"order_items": [
{
"product_order_po": "PO_0002",
"product_qty": 1,
"product_sku": "AP1234P1234",
"product_image": null,
"product_title": "The Big Blue Mountain",
"template": null,
"product_guid": "00000000-0000-0000-0000-000000000000",
"custom_data_1": null,
"custom_data_2": null,
"custom_data_3": null
}
],
"shipping_code": "SD",
"ship_by_date": null,
"customs_tax_info": null,
"gift_message": null,
"test_mode": false,
"webhook_order_status_url": null,
"document_url": null,
"acct_number_ups": null,
"acct_number_fedex": null,
"custom_data_1": null,
"custom_data_2": null,
"custom_data_3": null
}
],
"validate_only": false
});
req.write(postData);
req.end();
require "uri"
require "net/http"
url = URI("https://api.finerworks.comsample_endpoint")
https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true
request = Net::HTTP::sample_method.new(url)
request["Content-Type"] = "application/json"
request["web_api_key"] = "my-web-api-key-goes-here"
request["app_key"] = "my-app-key-goes-here"
request.body = "{
'orders': [
{
'order_po': 'PO_0001',
'order_key': null,
'recipient': {
'first_name': 'Bob',
'last_name': 'Ross',
'company_name': 'Happy Little Trees, Inc',
'address_1': '742 Evergreen Terrace',
'address_2': null,
'address_3': null,
'city': 'Mountain Scene',
'state_code': 'AK',
'province': null,
'zip_postal_code': '88888',
'country_code': 'us',
'phone': '555-555-5555',
'email': null,
'address_order_po': 'PO_0001'
},
'order_items': [
{
'product_order_po': 'PO_0001',
'product_qty': 1,
'product_sku': 'AP1234P1234',
'product_image': null,
'product_title': 'The Big Blue Mountain',
'template': null,
'product_guid': '00000000-0000-0000-0000-000000000000',
'custom_data_1': null,
'custom_data_2': null,
'custom_data_3': null
}
],
'shipping_code': 'SD',
'ship_by_date': null,
'customs_tax_info': null,
'gift_message': null,
'test_mode': false,
'webhook_order_status_url': null,
'document_url': null,
'acct_number_ups': null,
'acct_number_fedex': null,
'custom_data_1': null,
'custom_data_2': null,
'custom_data_3': null
},
{
'order_po': 'PO_0002',
'order_key': null,
'recipient': {
'first_name': 'Bob',
'last_name': 'Ross',
'company_name': 'Happy Little Trees, Inc',
'address_1': '742 Evergreen Terrace',
'address_2': null,
'address_3': null,
'city': 'Mountain Scene',
'state_code': 'AK',
'province': null,
'zip_postal_code': '88888',
'country_code': 'us',
'phone': '555-555-5555',
'email': null,
'address_order_po': 'PO_0002'
},
'order_items': [
{
'product_order_po': 'PO_0002',
'product_qty': 1,
'product_sku': 'AP1234P1234',
'product_image': null,
'product_title': 'The Big Blue Mountain',
'template': null,
'product_guid': '00000000-0000-0000-0000-000000000000',
'custom_data_1': null,
'custom_data_2': null,
'custom_data_3': null
}
],
'shipping_code': 'SD',
'ship_by_date': null,
'customs_tax_info': null,
'gift_message': null,
'test_mode': false,
'webhook_order_status_url': null,
'document_url': null,
'acct_number_ups': null,
'acct_number_fedex': null,
'custom_data_1': null,
'custom_data_2': null,
'custom_data_3': null
}
],
'validate_only': false
}"
response = https.request(request)
puts response.read_body
| Name | Description | Type | Additional information |
|---|---|---|---|
| status |
Status of response |
response_status |
None. |
| orders |
List of orders that have been successfully submitted. |
array (received_order) |
None. |
| debug |
Used to assist debugging any errors |
Object |
None. |
| misc |
Miscellaneous data |
Object |
None. |
Example JSON Response
application/json, text/json
{
"status": {
"success": true,
"status_code": 200,
"message": "",
"debug": null
},
"orders": [
{
"order_po": "PO_0001",
"order_id": 123456,
"order_confirmation_id": 411111111,
"order_confirmation_datetime": "2024-04-18T03:21:10.9546002-05:00"
},
{
"order_po": "PO_0002",
"order_id": 123457,
"order_confirmation_id": 411111112,
"order_confirmation_datetime": "2024-04-18T03:21:10.9546002-05:00"
}
],
"debug": null,
"misc": null
}