POST
https://test-api.finerworks.com/v3/submit_orders_v2
Submit Orders V2
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 queue.
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. IMPORTANT: To use the INVOICE option, an account must be setup for this to be accepted otherwise the orders will not be received. FOR TESTING: You can use "xxxx" which will override each order's test_mode settings and set them to TRUE. | text | None. |
| account_key | Optional - This will only be accepted for accounts with permission to utilize this parameter, otherwise it will be ignored and any submit orders will be based upon the user's api credentials. Leave as null or ignore if not explicitly required to use this parameter. | text | 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,
"webhook_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,
"source": null,
"fulfillment_id": 0
},
{
"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,
"webhook_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,
"source": null,
"fulfillment_id": 0
}
],
"validate_only": false,
"payment_token": "xxxx",
"account_key": null
}
Sample Code Library
curl --location --request POST 'https://test-api.finerworks.com/v3/submit_orders_v2' \
--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,
"webhook_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,
"source": null,
"fulfillment_id": 0
},
{
"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,
"webhook_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,
"source": null,
"fulfillment_id": 0
}
],
"validate_only": false,
"payment_token": "xxxx",
"account_key": null
}'require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://test-api.finerworks.com/v3/submit_orders_v2');
$request->setMethod(HTTP_Request2::METHOD_POST);
$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,
'webhook_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,
'source': null,
'fulfillment_id': 0
},
{
'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,
'webhook_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,
'source': null,
'fulfillment_id': 0
}
],
'validate_only': false,
'payment_token': 'xxxx',
'account_key': null
}');
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.com/v3/submit_orders_v2");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
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,
'webhook_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,
'source': null,
'fulfillment_id': 0
},
{
'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,
'webhook_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,
'source': null,
'fulfillment_id': 0
}
],
'validate_only': false,
'payment_token': 'xxxx',
'account_key': null
}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);var settings = {
"url": "https://test-api.finerworks.com/v3/submit_orders_v2",
"method": "POST",
"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,
'webhook_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,
'source': null,
'fulfillment_id': 0
},
{
'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,
'webhook_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,
'source': null,
'fulfillment_id': 0
}
],
'validate_only': false,
'payment_token': 'xxxx',
'account_key': null
}),
};
$.ajax(settings).done(function (response) {
console.log(response);
});var https = require('follow-redirects').https;
var options = {
'method': 'POST',
'hostname': 'test-api.finerworks.com',
'path': '/v3/submit_orders_v2',
'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 () {
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,
'webhook_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,
'source': null,
'fulfillment_id': 0
},
{
'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,
'webhook_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,
'source': null,
'fulfillment_id': 0
}
],
'validate_only': false,
'payment_token': 'xxxx',
'account_key': null
});
req.write(postData);
req.end();require "uri"
require "net/http"
url = URI("https://test-api.finerworks.com/v3/submit_orders_v2")
https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true
request = Net::HTTP::Post.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,
'webhook_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,
'source': null,
'fulfillment_id': 0
},
{
'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,
'webhook_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,
'source': null,
'fulfillment_id': 0
}
],
'validate_only': false,
'payment_token': 'xxxx',
'account_key': null
}"
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": "1f3c9a6c40e441e59eda9dbbe6cce19e",
"domain": null
},
"orders": [
{
"order_po": "PO_0001",
"order_id": 123456,
"order_confirmation_id": 411111111,
"order_guid": "00000000-0000-0000-0000-000000000000",
"order_email": null,
"order_confirmation_datetime": "2026-07-30T10:17:56.3666136-05:00",
"order_source": null
},
{
"order_po": "PO_0002",
"order_id": 123457,
"order_confirmation_id": 411111112,
"order_guid": "00000000-0000-0000-0000-000000000000",
"order_email": null,
"order_confirmation_datetime": "2026-07-30T10:17:56.3666136-05:00",
"order_source": null
}
],
"debug": null,
"misc": null
}