Shipping Options
Uri: https://api.finerworks.com/v3/list_shipping_options
Method: POST

Provides a list of available shipping options with the required shipping_code to be used when submitting an order.

Body

Requests shipping options by using order details to be submitted via order details object in the body.

NameDescriptionTypeAdditional information
order_po

This be a unique order identifier or reference number. For example, an order numnber generated by your shopping cart or application. If you are just calculating shipping or testing any random string or number will suffice

 text

order_key

This should be left as null. It will be generated when the order is submitted.

 globally unique identifier

None.
recipient

Name and address of address you want order sent to.

 address

Required
order_items

A list of individual products based on sku to be processed and shipped with order.

 array (product)

Required
shipping_code

Shipping code that must be included with any orders. Will be required when submitting an order. Use the list_shipping_options to get specific codes or enter one of these codes: EC = Economy (Cheapest), SD = UPS Ground, FS = Fastest Availabled

 text

Required
ship_by_date

Optional date it needs to ship by

 date

None.
customs_tax_info

Optional for customs tax id and type whe shipping internationally

 customs_tax_info

None.
gift_message

Optional message to print out on the packing slip for the recipient to see.

 text

None.
test_mode

Optional - You can flag this order as a test order. Default is false if left empty or not included.

 boolean

None.
webhook_order_status_url

Optional - order status webhook. Location were we can post JSON object with order status details. See fetch_order_status response (orders) for json format.

 text

None.
document_url

May be a single page document. Must be a JPG or PDF (8.5x11)

 text

Max length: 200
acct_number_ups

FinerWorks registered UPS account. Used to ship under your own account.

 text

Max length: 50
acct_number_fedex

FinerWorks registered FEDEX account. Used to ship under your own account.

 text

Max length: 50
custom_data_1

Optional data which may be used by developers.

 text

Max length: 255
custom_data_2

Optional data which may be used by developers.

 text

Max length: 255
custom_data_3

Optional data which may be used by developers.

 text

Max length: 255

Example JSON Body

application/json, text/json

{
  "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
}

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 '{
  "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
}'
                            
                        


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('{
  '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
}');
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", "{
  '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
},  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({
  '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
}),
};

$.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({
  "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
});

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 = "{
  '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
}"

    response = https.request(request)
    puts response.read_body

NameDescriptionTypeAdditional information
status

response_status

None.
options

array (shipping_option)

None.

Example JSON Response

application/json, text/json

{
  "status": {
    "success": true,
    "status_code": 200,
    "message": "",
    "debug": null
  },
  "options": [
    {
      "rate": 9.95,
      "shipping_method": "USPS Priority Mail",
      "shipping_code": "SD",
      "calculated_total": {
        "order_po": "PO_0001",
        "order_subtotal": 122.0,
        "order_shipping_rate": 9.95,
        "order_discount": 0.0,
        "order_sales_tax": 11.28,
        "order_sales_tax_rate": 0.825,
        "order_credits_used": 0.0,
        "order_grand_total": 152.28,
        "product_pricing": [
          {
            "product_qty": 1,
            "product_sku": "AP1556P466112",
            "product_code": "5M41M9S8X10F131S13X15J2S9X11G1",
            "product_price": 8.0,
            "add_frame_price": 9.0,
            "add_mat_1_price": 10.0,
            "add_mat_2_price": 0.0,
            "add_glazing_price": 10.0,
            "add_color_correct_price": 0.0,
            "total_price": 122.0,
            "info": null,
            "debug": null
          }
        ]
      }
    },
    {
      "rate": 21.05,
      "shipping_method": "UPS Ground",
      "shipping_code": "SD",
      "calculated_total": {
        "order_po": "PO_0001",
        "order_subtotal": 122.0,
        "order_shipping_rate": 21.05,
        "order_discount": 0.0,
        "order_sales_tax": 11.44,
        "order_sales_tax_rate": 0.825,
        "order_credits_used": 0.0,
        "order_grand_total": 154.49,
        "product_pricing": [
          {
            "product_qty": 1,
            "product_sku": "AP1556P466112",
            "product_code": "5M41M9S8X10F131S13X15J2S9X11G1",
            "product_price": 8.0,
            "add_frame_price": 9.0,
            "add_mat_1_price": 10.0,
            "add_mat_2_price": 0.0,
            "add_glazing_price": 10.0,
            "add_color_correct_price": 0.0,
            "total_price": 122.0,
            "info": null,
            "debug": null
          }
        ]
      }
    }
  ]
}