Shipping Payload
The following is an example payload which is utilised as part of the custom shipping endpoint and custom shipping code functionality for Foxy stores. The payload shows a cart with two products (one live rate and one flat rate) along with a coupon.
{ "_links": { "curies": [ { "name": "fx", "href": "https://api.foxycart.com/rels/{rel}", "templated": true } ], "self": { "href": "https://api.foxycart.com/carts/123456789", "title": "This Cart" }, "fx:attributes": { "href": "https://api.foxycart.com/carts/123456789/attributes", "title": "Attributes for This Cart" }, "fx:store": { "href": "https://api.foxycart.com/stores/12345", "title": "This Store" }, "fx:items": { "href": "https://api.foxycart.com/carts/123456789/items", "title": "The Items for This Cart" }, "fx:discounts": { "href": "https://api.foxycart.com/carts/123456789/discounts", "title": "Discounts for this Cart" }, "fx:applied_coupon_codes": { "href": "https://api.foxycart.com/carts/123456789/applied_coupon_codes", "title": "Coupon Codes applied to this Cart" }, "fx:custom_fields": { "href": "https://api.foxycart.com/carts/123456789/cart_custom_fields", "title": "The Custom Fields for this Cart" }, "fx:create_session": { "href": "https://api.foxycart.com/carts/123456789/session", "title": "POST here to create a browser session link" } }, "_embedded": { "fx:items": [ { "_links": { "curies": [ { "name": "fx", "href": "https://api.foxycart.com/rels/{rel}", "templated": true } ], "self": { "href": "https://api.foxycart.com/items/113551331", "title": "This Item" }, "fx:store": { "href": "https://api.foxycart.com/stores/12345", "title": "This Store" }, "fx:cart": { "href": "https://api.foxycart.com/carts/123456789", "title": "This Cart" }, "fx:item_category": { "href": "https://api.foxycart.com/item_categories/23456", "title": "This Item Category" }, "fx:item_options": { "href": "https://api.foxycart.com/items/113551331/item_options", "title": "Item Options for This Item" }, "fx:attributes": { "href": "https://api.foxycart.com/items/113551331/attributes", "title": "Attributes for This Item" }, "fx:discount_details": { "href": "https://api.foxycart.com/items/113551331/discount_details", "title": "The Discounts for this Item" }, "fx:coupon_details": { "href": "https://api.foxycart.com/items/113551331/coupon_details", "title": "The Coupons for this Item" } }, "_embedded": { "fx:item_options": [ { "_links": { "curies": [ { "name": "fx", "href": "https://api.foxycart.com/rels/{rel}", "templated": true } ], "self": { "href": "https://api.foxycart.com/item_options/337999590", "title": "This Item Option" }, "fx:store": { "href": "https://api.foxycart.com/stores/12345", "title": "This Store" }, "fx:cart": { "href": "https://api.foxycart.com/carts/123456789", "title": "This Cart" }, "fx:item": { "href": "https://api.foxycart.com/items/113551331", "title": "This Item" } }, "name": "Colour", "value": "Sparkletoots", "price_mod": 0, "weight_mod": 0, "date_created": null, "date_modified": null } ], "fx:item_category": { "_links": { "curies": [ { "name": "fx", "href": "https://api.foxycart.com/rels/{rel}", "templated": true } ], "self": { "href": "https://api.foxycart.com/item_categories/23456", "title": "DEFAULT" }, "fx:store": { "href": "https://api.foxycart.com/stores/12345", "title": "This Store" }, "fx:email_templates": { "href": "https://api.foxycart.com/stores/12345/email_templates", "title": "Email Templates for this store" }, "fx:tax_item_categories": { "href": "https://api.foxycart.com/item_categories/23456/tax_item_categories", "title": "Tax Item Category relationships" } }, "admin_email_template_uri": "", "customer_email_template_uri": "", "code": "DEFAULT", "name": "Default for all products", "item_delivery_type": "shipped", "max_downloads_per_customer": 3, "max_downloads_time_period": 24, "default_weight": 30, "default_weight_unit": "LBS", "default_length_unit": "IN", "shipping_flat_rate_type": "per_order", "shipping_flat_rate": 5, "handling_fee_type": "none", "handling_fee": 0, "handling_fee_minimum": 0, "handling_fee_percentage": 0, "customs_value": 0, "discount_type": "", "discount_name": "", "discount_details": "", "send_customer_email": false, "send_admin_email": false, "admin_email": "", "date_created": null, "date_modified": "2019-09-12T12:41:34-0700" } }, "item_category_uri": "https://api.foxycart.com/item_categories/23456", "name": "Fancy Widget", "price": 80.95, "quantity": 1, "quantity_min": 0, "quantity_max": 0, "weight": 30, "code": "abc123", "parent_code": "", "discount_name": "", "discount_type": "", "discount_details": "", "subscription_frequency": "", "subscription_start_date": null, "subscription_next_transaction_date": null, "subscription_end_date": null, "is_future_line_item": false, "shipto": "", "url": "", "image": "https://placekitten.com/200/300", "length": 0, "width": 0, "height": 0, "expires": 0, "date_created": null, "date_modified": "2020-09-24T16:31:07-0700" } ], "fx:discounts": [], "fx:custom_fields": [], "fx:shipment": { "address_name": "", "first_name": "Jane", "last_name": "Doe", "email": "Jane@example.tld", "customer_id": "3456789", "company": "NewCo", "address1": "555 Mulberry Dr", "address2": "", "city": "SAN DIEGO", "region": "CA", "postal_code": "92107", "country": "US", "origin_region": "NY", "origin_postal_code": "11110", "origin_country": "US", "shipping_service_id": 0, "shipping_service_description": "", "is_residential": true, "item_count": 1, "package_count": 1, "package_weight": 30, "package_length": 0, "package_width": 0, "package_height": 0, "total_weight": 30, "total_customs_value": 0, "total_handling_fee": 0, "total_flat_rate_shipping": 0, "total_item_price": 80.95, "total_tax": 0, "total_shipping": 0, "total_price": 80.95 }, "fx:shipping_results": [], "fx:customer": { "_links": { "curies": [ { "name": "fx", "href": "https://api.foxycart.com/rels/{rel}", "templated": true } ], "self": { "href": "https://api.foxycart.com/customers/3456789", "title": "This Customer" }, "fx:attributes": { "href": "https://api.foxycart.com/customers/3456789/attributes", "title": "Attributes for this Customer" }, "fx:store": { "href": "https://api.foxycart.com/stores/12345", "title": "This Store" }, "fx:default_billing_address": { "href": "https://api.foxycart.com/customers/3456789/default_billing_address", "title": "Default Billing Address for this Customer" }, "fx:default_shipping_address": { "href": "https://api.foxycart.com/customers/3456789/default_shipping_address", "title": "Default Shipping Address for this Customer" }, "fx:default_payment_method": { "href": "https://api.foxycart.com/customers/3456789/default_payment_method", "title": "Default Payment Method for this Customer" }, "fx:transactions": { "href": "https://api.foxycart.com/stores/12345/transactions?customer_id=3456789", "title": "Transactions for this Customer" }, "fx:subscriptions": { "href": "https://api.foxycart.com/stores/12345/subscriptions?customer_id=3456789", "title": "Subscriptions for this Customer" }, "fx:customer_addresses": { "href": "https://api.foxycart.com/customers/3456789/addresses", "title": "Addresses for this Customer" } }, "_embedded": { "fx:attributes": [ { "_links": { "curies": [ { "name": "fx", "href": "https://api.foxycart.com/rels/{rel}", "templated": true } ], "self": { "href": "https://api.foxycart.com/customer_attributes/1690200", "title": "This customer attribute" }, "fx:store": { "href": "https://api.foxycart.com/stores/12345", "title": "This Store" }, "fx:customer": { "href": "https://api.foxycart.com/customers/3456789", "title": "This Customer" } }, "name": "Loyalty_Points", "value": "5087", "visibility": "public", "date_created": "2019-09-13T12:19:11-0700", "date_modified": "2020-09-08T10:26:54-0700" }, { "_links": { "curies": [ { "name": "fx", "href": "https://api.foxycart.com/rels/{rel}", "templated": true } ], "self": { "href": "https://api.foxycart.com/customer_attributes/1776235", "title": "This customer attribute" }, "fx:store": { "href": "https://api.foxycart.com/stores/12345", "title": "This Store" }, "fx:customer": { "href": "https://api.foxycart.com/customers/3456789", "title": "This Customer" } }, "name": "Loyalty_Level", "value": "Blue", "visibility": "public", "date_created": "2019-10-11T05:48:24-0700", "date_modified": "2019-12-23T11:10:13-0800" } ] }, "id": 3456789, "last_login_date": "2020-09-24T16:31:24-0700", "first_name": "Jane", "last_name": "Doe", "email": "Jane@example.tld", "tax_id": "", "password_salt": "", "password_hash": "$P$Bjh123NnD860QG1jM9DrhjwGbPabKM1", "password_hash_type": "phpass", "password_hash_config": "8", "forgot_password": "", "forgot_password_timestamp": null, "is_anonymous": false, "date_created": "2019-09-13T12:08:02-0700", "date_modified": "2020-09-24T16:31:24-0700" } }, "customer_uri": "", "template_set_uri": "", "payment_method_uri": "", "language": "", "locale_code": "en_US", "use_customer_shipping_address": false, "billing_first_name": null, "billing_last_name": null, "billing_company": null, "billing_address1": null, "billing_address2": null, "billing_city": "SAN DIEGO", "billing_state": "CA", "billing_postal_code": "92107", "billing_country": "US", "billing_phone": null, "customer_email": null, "shipping_first_name": null, "shipping_last_name": null, "shipping_company": null, "shipping_address1": null, "shipping_address2": null, "shipping_city": "SAN DIEGO", "shipping_state": "CA", "shipping_postal_code": "92107", "shipping_country": "US", "shipping_phone": null, "total_item_price": 80.95, "total_tax": 0, "total_shipping": 0, "total_future_shipping": 0, "total_order": 80.95, "date_created": null, "date_modified": "2020-09-24T16:31:07-0700", "currency_code": "USD", "currency_symbol": "$", "customer_ip": "1.1.1.1", "ip_country": "United States", "session_name": "fcsid", "session_id": "123458kabr94e8srpk06h109s1", "total_discount": 0, "total_future_item_price": 0 }
Notes:
- The items included in the payload will only be those for the shipping address being requested. This means if your store is using multiship and the customer enters a shipping address for a shipto, only the products for that shipto will be included in the payload.
- If the customer is authenticated on the checkout, then the
fx:customernode will be included, along with any attributes associated with the customer. - Please review this link for complete information on custom fields (
fx:custom_fields) in relation to the custom shipping code or endpoint using thedata-fc-shipping-custom-fieldattribute on custom checkout fields. - The payload includes several
_linksarrays. These contain helpful URI's that could be used through the Hypermedia API if you're also making use of that. If not, these can be safely ignored. - USPS uses some custom country names in their API integration which we've worked around using the following modifications. If you're doing a custom integration with them, you may need to do something similar. Please note that the data on this wiki may not be up to date, so contact us if you run into any questions or issues with the below.
"ISO Code", "Normal Name", "USPS Preferred Name" "AS", "American Samoa", "United States" "BL", "Saint Bartholemy", "Saint Bartholomew (Guadeloupe)" "CC", "Cocos (Keeling) Islands", "Cocos Island (Australia)" "CD", "Congo, the Democratic Republic of the", "Congo, Democratic Republic of the" "CF", "Central African Republic", "Central African Rep." "CG", "Congo", "Congo, Republic of the" "CI", "Cote D'Ivoire", "Côte d’Ivoire" "CK", "Cook Islands", "Cook Islands (New Zealand)" "CX", "Christmas Island", "Christmas Island (Australia)" "EH", "Western Sahara", "Morocco" "FK", "Falkland Islands (Malvinas)", "Falkland Islands" "FR", "France, Metropolitan", "France" "GB", "United Kingdom", "Great Britain and Northern Ireland" "GE", "Georgia", "Georgia, Republic of" "GS", "South Georgia and the South Sandwich Islands", "South Georgia (Falkland Islands)" "GU", "Guam", "United States" "GW", "Guinea-bissau", "Guinea-Bissau" "ID", "East Timor", "East Timor (Indonesia)" "IM", "Isle of Man", "Isle of Man (Great Britain)" "IO", "British Indian Ocean Territory", "Maldives" "IR", "Iran, Islamic Republic of", "Iran" "KN", "Saint Kitts and Nevis", "Saint Kitts (St. Christopher and Nevis)" "KP", "Korea, Democratic People's Republic of", "Korea, Democratic People's Republic of (North Korea)" "KR", "Korea, Republic of", "Korea, Republic of (South Korea)" "LA", "Lao People's Democratic Republic", "Laos" "LY", "Libyan Arab Jamahiriya", "Libya" "MC", "Monaco", "Monaco (France)" "MD", "Moldova, Republic of", "Moldova" "ME", "Yugoslavia", "Montenegro, Republic of" "MF", "Saint Martin", "Saint Martin (Guadeloupe)" "MH", "Marshall Islands", "Marshall Islands, Republic of the" "MK", "Macedonia, The Former Yugoslav Republic of", "Macedonia, Republic of" "MM", "Myanmar", "Myanmar (Burma)" "MO", "Macau Special Administrative Region of China", "Macau (Macao)" "MP", "Northern Mariana Islands", "United States" "NF", "Norfolk Island", "Norfolk Island (Australia)" "NU", "Niue", "Niue (New Zealand)" "PN", "Pitcairn", "Pitcairn Island" "PR", "Puerto Rico", "United States" "PW", "Palau", "United States" "RE", "Réunion", "Reunion" "RS", "Serbia", "Serbia, Republic of" "RU", "Russian Federation", "Russia" "SJ", "Svalbard and Jan Mayen Islands", "Norway" "SK", "Slovakia", "Slovak Republic" "SY", "Syrian Arab Republic", "Syrian Arab Republic (Syria)" "TK", "Tokelau", "Tokelau (Union) Group (Western Samoa)" "TL", "Timor-Leste", "East Timor (Indonesia)" "TW", "Taiwan, Province of China", "Taiwan" "TZ", "Tanzania, United Republic of", "Tanzania" "UM", "United States Minor Outlying Islands", "United States" "VA", "Holy See (Vatican City State)", "Vatican City" "VG", "Virgin Islands, British", "British Virgin Islands" "VI", "Virgin Islands, U.S.", "United States" "WS", "Samoa", "United States" "YT", "Mayotte", "Mayotte (France)"