Submit Orders V2
Uri: https://test-api.finerworks.com/v3/submit_orders_v2
Method: POST
Submits a list of new orders (up to 50 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. |
| payment_token |
Supply a payment_method token provided by the payment processor. Use "invoice" if payment is to be made later. Note account must qualify for an invoicing option for this to be accepted otherwise the orders will not be received. You can also use "xxxx" which will override each order's test_mode settings and set them to TRUE. |
text |
Required |
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,
"payment_token": "xxxx"
}
Sample Code Library
curl --location --request sample_method 'https://test-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,
"payment_token": "xxxx"
}'
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://test-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,
'payment_token': 'xxxx'
}');
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://test-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,
'payment_token': 'xxxx'
}, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var settings = {
"url": "https://test-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,
'payment_token': 'xxxx'
}),
};
$.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,
"payment_token": "xxxx"
});
req.write(postData);
req.end();
require "uri"
require "net/http"
url = URI("https://test-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,
'payment_token': 'xxxx'
}"
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,
"reference_id": "7fbfe3386d11470cbff30154d1e85ee6"
},
"orders": [
{
"order_po": "PO_0001",
"order_id": 123456,
"order_confirmation_id": 411111111,
"order_confirmation_datetime": "2025-01-17T13:41:00.4351317-06:00"
},
{
"order_po": "PO_0002",
"order_id": 123457,
"order_confirmation_id": 411111112,
"order_confirmation_datetime": "2025-01-17T13:41:00.4351317-06:00"
}
],
"debug": null,
"misc": null
}