Accessing the API with cURL
Using cURL can be a great way to quickly play around with the API and get an understanding of how the link based API navigation within a Hypermedia API works.
Requirements
As this tutorial will make use of cURL, you will need a command line tool that includes support for it. Terminal on OSX supports it out of the box, as it does for most Linux distributions. On Windows it's not available by default, but you can make use of something like Cygwin or if you have Git installed, it's included Bash shell.
You will also need to get an Access Token for a Foxy Store so we can actually connect to the API. If you've already got a Foxy store, you can quickly generate an OAuth Client and a store_full_access token set for your existing store from the Foxy Administraiton. Check the quick start guide on the Authentication page for details on that.
If you don't have a store, you can sign up for one at foxycart.com - it's free! If you would prefer to go all in with playing with the API, you can also follow the instructions on the White-Label Integration Guide to create a client, user and store through the API with cURL as well.
Within this example, the Access Token used within the Authorization: Bearer header will be a7eIEB6o21jS937Snl4jg0BEP9827bgo3ngod21f, you'll need to substitute in your own.
Access the store
Unless you have some relation URI's already cached, you'll generally start from the API homepage - which allows you to access everything that the protected resource your token is authenticated for contains.
➔ curl -H "FOXY-API-VERSION: 1" -H "Authorization: Bearer a7eIEB6o21jS937Snl4jg0BEP9827bgo3ngod21f" https://api.foxycart.com
{
"_links": {
"curies": [
{
"name": "fx",
"href": "https://api.foxycart.com/rels/{rel}",
"templated": true
}
],
"self": {
"href": "https://api.foxycart.com/",
"title": "Your API starting point."
},
"fx:property_helpers": {
"href": "https://api.foxycart.com/property_helpers",
"title": "Various helpers used for determing valid property values."
},
"https://api.foxycart.com/rels": {
"href": "https://api.foxycart.com/rels",
"title": "Custom Link Relationships supported by this API."
},
"fx:reporting": {
"href": "https://api.foxycart.com/reporting",
"title": "The Reporting API Home."
},
"fx:encode": {
"href": "https://api.foxycart.com/encode",
"title": "POST here to encode a body of html for use with our HMAC cart encryption."
},
"fx:user": {
"href": "https://api.foxycart.com/users/46686",
"title": "Your API home page."
},
"fx:store": {
"href": "https://api.foxycart.com/stores/41000",
"title": "The current store for your authentication token"
},
"fx:stores": {
"href": "https://api.foxycart.com/users/46686/stores",
"title": "Your stores"
},
"fx:token": {
"href": "https://api.foxycart.com/token",
"title": "The OAuth endpoint for obtaining a new access_token using an existing refresh_token. Post www-form-url-encoded data as follows: grant_type=refresh_token&refresh_token={refresh_token}&client_id={client_id}&client_secret={client_secret}",
"type": "application/json"
}
},
"message": "Welcome to the FoxyCart API! Our hope is to be as self-documenting and RESTful as possible. Please let us know if you have any questions by emailing us at helpdesk@foxycart.com. As a last resort, you could read the documentation at http://wiki.foxycart.com. Your first action should be to create an OAuth Client, then a user, followed by a store."
}Within the API homepage response, you can see a number of links - but the majority of the information we're after will be found by loading the fx:store relation. Copy the href returned for your store and load the API again, but using that link.
➔ curl -H "FOXY-API-VERSION: 1" -H "Authorization: Bearer a7eIEB6o21jS937Snl4jg0BEP9827bgo3ngod21f" https://api.foxycart.com/stores/41000
{
"_links": {
"curies": [
{
"name": "fx",
"href": "https://api.foxycart.com/rels/{rel}",
"templated": true
}
],
"self": {
"href": "https://api.foxycart.com/stores/41000",
"title": "This Store"
},
"fx:attributes": {
"href": "https://api.foxycart.com/stores/41000/attributes",
"title": "Attributes for This Store"
},
"fx:store_version": {
"href": "https://api.foxycart.com/property_helpers/store_versions/24",
"title": "This store version"
},
"fx:users": {
"href": "https://api.foxycart.com/stores/41000/users",
"title": "Users for This Store"
},
"fx:user_accesses": {
"href": "https://api.foxycart.com/stores/41000/user_accesses",
"title": "User Access for This Store"
},
"fx:customers": {
"href": "https://api.foxycart.com/stores/41000/customers",
"title": "Customers for This Store"
},
"fx:carts": {
"href": "https://api.foxycart.com/stores/41000/carts",
"title": "Carts for This Store"
},
"fx:transactions": {
"href": "https://api.foxycart.com/stores/41000/transactions",
"title": "Transactions for This Store"
},
"fx:subscriptions": {
"href": "https://api.foxycart.com/stores/41000/subscriptions",
"title": "Subscriptions for This Store"
},
"fx:subscription_settings": {
"href": "https://api.foxycart.com/store_subscription_settings/41000",
"title": "Subscription Settings for This Store"
},
"fx:process_subscription_webhook": {
"href": "https://api.foxycart.com/stores/41000/process_subscription_webhook",
"title": "POST here to resend the daily subscription webhook notification for this store"
},
"fx:item_categories": {
"href": "https://api.foxycart.com/stores/41000/item_categories",
"title": "Item Categories for This Store"
},
"fx:taxes": {
"href": "https://api.foxycart.com/stores/41000/taxes",
"title": "Taxes for This Store"
},
"fx:payment_method_sets": {
"href": "https://api.foxycart.com/stores/41000/payment_method_sets",
"title": "Payment Method Sets for This Store"
},
"fx:coupons": {
"href": "https://api.foxycart.com/stores/41000/coupons",
"title": "Coupons for This Store"
},
"fx:template_sets": {
"href": "https://api.foxycart.com/stores/41000/template_sets",
"title": "Template Sets for This Store"
},
"fx:cart_templates": {
"href": "https://api.foxycart.com/stores/41000/cart_templates",
"title": "Cart Templates for This Store"
},
"fx:cart_include_templates": {
"href": "https://api.foxycart.com/stores/41000/cart_include_templates",
"title": "Cart Include Templates for This Store"
},
"fx:checkout_templates": {
"href": "https://api.foxycart.com/stores/41000/checkout_templates",
"title": "Checkout Templates for This Store"
},
"fx:receipt_templates": {
"href": "https://api.foxycart.com/stores/41000/receipt_templates",
"title": "Receipt Templates for This Store"
},
"fx:email_templates": {
"href": "https://api.foxycart.com/stores/41000/email_templates",
"title": "Email Templates for This Store"
},
"fx:error_entries": {
"href": "https://api.foxycart.com/stores/41000/error_entries",
"title": "Error Entries for This Store"
},
"fx:downloadables": {
"href": "https://api.foxycart.com/stores/41000/downloadables",
"title": "Downloadables for This Store"
},
"fx:payment_gateways": {
"href": "https://api.foxycart.com/stores/41000/payment_gateways",
"title": "Payment Gateways for This Store"
},
"fx:hosted_payment_gateways": {
"href": "https://api.foxycart.com/stores/41000/hosted_payment_gateways",
"title": "Hosted Payment Gateways for This Store"
},
"fx:fraud_protections": {
"href": "https://api.foxycart.com/stores/41000/fraud_protections",
"title": "Fraud Protections for This Store"
},
"fx:payment_methods_expiring": {
"href": "https://api.foxycart.com/stores/41000/payment_methods_expiring",
"title": "Customer payment methods which are about to expire"
},
"fx:store_shipping_methods": {
"href": "https://api.foxycart.com/stores/41000/store_shipping_methods",
"title": "Shipping methods supported by this store"
},
"fx:integrations": {
"href": "https://api.foxycart.com/stores/41000/integrations",
"title": "Third party integrations which have been granted OAuth access to this store"
},
"fx:native_integrations": {
"href": "https://api.foxycart.com/stores/41000/native_integrations",
"title": "Third party integrations which require credentials and configuration."
},
"fx:activate_store_monthly_url": {
"href": "https://signup.foxycart.com/cart?...",
"title": "Follow this link in your browser to pay for your monthly subscription and activate this store",
"type": "text/html"
},
"fx:activate_store_yearly_url": {
"href": "https://signup.foxycart.com/cart?...",
"title": "Follow this link in your browser to pay for your yearly subscription and activate this store",
"type": "text/html"
}
},
"store_version_uri": "https://api.foxycart.com/property_helpers/store_versions/24",
"store_name": "Johns Test Store",
"store_domain": "johnsteststore",
"use_remote_domain": false,
"store_url": "http://www.example.com/",
"receipt_continue_url": null,
"store_email": "orders@example.com",
"from_email": null,
"use_email_dns": false,
"bcc_on_receipt_email": true,
"postal_code": "77018",
"region": "TX",
"country": "US",
"locale_code": "en_US",
"timezone": "America/Los_Angeles",
"hide_currency_symbol": false,
"hide_decimal_characters": false,
"use_international_currency_symbol": false,
"language": "english",
"logo_url": null,
"checkout_type": "default_account",
"use_webhook": false,
"webhook_url": null,
"webhook_key": null,
"use_cart_validation": false,
"use_single_sign_on": false,
"single_sign_on_url": null,
"customer_password_hash_type": "md5",
"customer_password_hash_config": null,
"features_multiship": false,
"products_require_expires_property": false,
"shipping_address_type": "determine_by_company",
"unified_order_entry_password": null,
"affiliate_id": 0,
"is_active": false,
"first_payment_date": null,
"date_created": "2016-09-08T23:55:17-0700",
"date_modified": "2016-09-08T23:55:17-0700"
}As you can see - this is a much bigger response - with a whole stack of links that cover all of the different aspects of a store. All aspects of the store can be managed through the URI's provided here. If this was within your integration, at this point you'd cache the fx:store URI so that you can easily use it again later on, without needing to re-request the API homepage.
Creating a Category
Now that we've got the basics of moving through the API - let's make a new category. Just to confirm what's there - let's request the fx:item_categories URI first:
➔ curl -H "FOXY-API-VERSION: 1" -H "Authorization: Bearer a7eIEB6o21jS937Snl4jg0BEP9827bgo3ngod21f" https://api.foxycart.com/stores/41000/item_categories
{
"_links": {
"curies": [
{
"name": "fx",
"href": "https://api.foxycart.com/rels/{rel}",
"templated": true
}
],
"self": {
"href": "https://api.foxycart.com/stores/41000/item_categories",
"title": "This Collection"
},
"first": {
"href": "https://api.foxycart.com/stores/41000/item_categories?offset=0",
"title": "First Page of this Collection"
},
"prev": {
"href": "https://api.foxycart.com/stores/41000/item_categories?offset=0",
"title": "Previous Page of this Collection"
},
"next": {
"href": "https://api.foxycart.com/stores/41000/item_categories?offset=0",
"title": "Next Page of this Collection"
},
"last": {
"href": "https://api.foxycart.com/stores/41000/item_categories?offset=0",
"title": "Last Page of this Collection"
}
},
"_embedded": {
"fx:item_categories": [
{
"_links": {
"curies": [
{
"name": "fx",
"href": "https://api.foxycart.com/rels/{rel}",
"templated": true
}
],
"self": {
"href": "https://api.foxycart.com/item_categories/79457",
"title": "DEFAULT"
},
"fx:store": {
"href": "https://api.foxycart.com/stores/41000",
"title": "This Store"
},
"fx:email_templates": {
"href": "https://api.foxycart.com/stores/41000/email_templates",
"title": "Email Templates for this store"
},
"fx:tax_item_categories": {
"href": "https://api.foxycart.com/item_categories/79457/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": "notshipped",
"max_downloads_per_customer": 3,
"max_downloads_time_period": 24,
"default_weight": 1,
"default_weight_unit": "LBS",
"default_length_unit": "IN",
"shipping_flat_rate_type": "per_order",
"shipping_flat_rate": 0,
"handling_fee_type": "none",
"handling_fee": 0,
"handling_fee_minimum": 0,
"handling_fee_percentage": 0,
"customs_value": 0,
"discount_type": null,
"discount_name": null,
"discount_details": null,
"send_customer_email": false,
"send_admin_email": false,
"admin_email": null,
"date_created": "2016-09-08T23:55:18-0700",
"date_modified": "2016-09-08T23:55:18-0700"
}
]
},
"total_items": "1",
"returned_items": 1,
"limit": 20,
"offset": 0
}Just the default category exists currently. Let's add in a new category whose products are shipping with a flat rate of $15. To do that we simply POST to the same fx:item_categories URI, passing through the needed parameters as detailed on the API reference page for this relation
➔ curl -H "FOXY-API-VERSION: 1" -H "Authorization: Bearer a7eIEB6o21jS937Snl4jg0BEP9827bgo3ngod21f" https://api.foxycart.com/stores/41000/item_categories -d "code=flat_rate&name=Flat+Rate+Shipping&item_delivery_type=flat_rate&shipping_flat_rate=15&shipping_flat_rate_type=per_order"
{
"_links": {
"curies": [
{
"name": "fx",
"href": "https://api.foxycart.com/rels/{rel}",
"templated": true
}
],
"self": {
"href": "https://api.foxycart.com/item_categories/79460",
"title": "flat_rate"
},
"fx:store": {
"href": "https://api.foxycart.com/stores/41000",
"title": "This Store"
},
"fx:email_templates": {
"href": "https://api.foxycart.com/stores/41000/email_templates",
"title": "Email Templates for this store"
},
"fx:tax_item_categories": {
"href": "https://api.foxycart.com/item_categories/79460/tax_item_categories",
"title": "Tax Item Category relationships"
}
},
"message": "item_category 79460 created successfully."
}Success! Now let's load the fx:item_categories URI again and see all of our store categories:
➔ curl -H "FOXY-API-VERSION: 1" -H "Authorization: Bearer a7eIEB6o21jS937Snl4jg0BEP9827bgo3ngod21f" https://api.foxycart.com/stores/41000/item_categories
{
"_links": {
"curies": [
{
"name": "fx",
"href": "https://api.foxycart.com/rels/{rel}",
"templated": true
}
],
"self": {
"href": "https://api.foxycart.com/stores/41000/item_categories",
"title": "This Collection"
},
"first": {
"href": "https://api.foxycart.com/stores/41000/item_categories?offset=0",
"title": "First Page of this Collection"
},
"prev": {
"href": "https://api.foxycart.com/stores/41000/item_categories?offset=0",
"title": "Previous Page of this Collection"
},
"next": {
"href": "https://api.foxycart.com/stores/41000/item_categories?offset=0",
"title": "Next Page of this Collection"
},
"last": {
"href": "https://api.foxycart.com/stores/41000/item_categories?offset=0",
"title": "Last Page of this Collection"
}
},
"_embedded": {
"fx:item_categories": [
{
"_links": {
"curies": [
{
"name": "fx",
"href": "https://api.foxycart.com/rels/{rel}",
"templated": true
}
],
"self": {
"href": "https://api.foxycart.com/item_categories/79457",
"title": "DEFAULT"
},
"fx:store": {
"href": "https://api.foxycart.com/stores/41000",
"title": "This Store"
},
"fx:email_templates": {
"href": "https://api.foxycart.com/stores/41000/email_templates",
"title": "Email Templates for this store"
},
"fx:tax_item_categories": {
"href": "https://api.foxycart.com/item_categories/79457/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": "notshipped",
"max_downloads_per_customer": 3,
"max_downloads_time_period": 24,
"default_weight": 1,
"default_weight_unit": "LBS",
"default_length_unit": "IN",
"shipping_flat_rate_type": "per_order",
"shipping_flat_rate": 0,
"handling_fee_type": "none",
"handling_fee": 0,
"handling_fee_minimum": 0,
"handling_fee_percentage": 0,
"customs_value": 0,
"discount_type": null,
"discount_name": null,
"discount_details": null,
"send_customer_email": false,
"send_admin_email": false,
"admin_email": null,
"date_created": "2016-09-08T23:55:18-0700",
"date_modified": "2016-09-08T23:55:18-0700"
},
{
"_links": {
"curies": [
{
"name": "fx",
"href": "https://api.foxycart.com/rels/{rel}",
"templated": true
}
],
"self": {
"href": "https://api.foxycart.com/item_categories/79460",
"title": "flat_rate"
},
"fx:store": {
"href": "https://api.foxycart.com/stores/41000",
"title": "This Store"
},
"fx:email_templates": {
"href": "https://api.foxycart.com/stores/41000/email_templates",
"title": "Email Templates for this store"
},
"fx:tax_item_categories": {
"href": "https://api.foxycart.com/item_categories/79460/tax_item_categories",
"title": "Tax Item Category relationships"
}
},
"admin_email_template_uri": "",
"customer_email_template_uri": "",
"code": "flat_rate",
"name": "Flat Rate Shipping",
"item_delivery_type": "flat_rate",
"max_downloads_per_customer": 3,
"max_downloads_time_period": 24,
"default_weight": 1,
"default_weight_unit": "LBS",
"default_length_unit": "IN",
"shipping_flat_rate_type": "per_order",
"shipping_flat_rate": 15,
"handling_fee_type": "none",
"handling_fee": 0,
"handling_fee_minimum": 0,
"handling_fee_percentage": 0,
"customs_value": 0,
"discount_type": null,
"discount_name": null,
"discount_details": null,
"send_customer_email": false,
"send_admin_email": false,
"admin_email": null,
"date_created": "2016-09-09T06:07:31-0700",
"date_modified": "2016-09-09T06:07:31-0700"
}
]
},
"total_items": "2",
"returned_items": 2,
"limit": 20,
"offset": 0
}There we go - our store now has two categories, the default category created with the store, and our brand new flat rate category we just created.
Modifying a category
We know we can create a resource - but what if we need to change a resource. The default category that was created with the store is currently set to a delivery type of notshipped. Let's say we actually wanted the default for our store to be for the products to be shipping using live rates, and for the default weight for our products to be 2.5lbs.
As we just need to modify a couple fields - we can make use of a PATCH request. The PATCH request allows us to just pass through the fields we want to change, compared to a PUT which would require that we pass all of the required fields for the resource. You'll need to consult how these are specified within your language, within a cURL request, you pass the request flag to specify.
For this request, we grab the self URI from within the default category in the previous response, and send our PATCH request there:
➔ curl -H "FOXY-API-VERSION: 1" -H "Authorization: Bearer a7eIEB6o21jS937Snl4jg0BEP9827bgo3ngod21f" -X PATCH https://api.foxycart.com/item_categories/79457 -d "item_delivery_type=shipped&default_weight=2.5"
{
"_links": {
"curies": [
{
"name": "fx",
"href": "https://api.foxycart.com/rels/{rel}",
"templated": true
}
],
"self": {
"href": "https://api.foxycart.com/item_categories/79457",
"title": "DEFAULT"
},
"fx:store": {
"href": "https://api.foxycart.com/stores/41000",
"title": "This Store"
},
"fx:email_templates": {
"href": "https://api.foxycart.com/stores/41000/email_templates",
"title": "Email Templates for this store"
},
"fx:tax_item_categories": {
"href": "https://api.foxycart.com/item_categories/79457/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": 2.5,
"default_weight_unit": "LBS",
"default_length_unit": "IN",
"shipping_flat_rate_type": "per_order",
"shipping_flat_rate": 0,
"handling_fee_type": "none",
"handling_fee": 0,
"handling_fee_minimum": 0,
"handling_fee_percentage": 0,
"customs_value": 0,
"discount_type": null,
"discount_name": null,
"discount_details": null,
"send_customer_email": false,
"send_admin_email": false,
"admin_email": null,
"date_created": "2016-09-08T23:55:18-0700",
"date_modified": "2016-09-09T06:21:07-0700"
}Viewing Transactions
Now we've set up our categories how we want - and some customers have placed some orders, so let's fetch those using the API. We'll need to GET the fx:transactions link from the API homepage as we fetched it earlier using our store_full_access token:
"fx:transactions": {
"href": "https://api.foxycart.com/stores/41000/transactions",
"title": "Transactions for This Store"
}The GET request will return a response that includes recent transactions embedded within it. For the sake of this example, a parameter has been added to the URI to limit the returned transactions 1 per page by appending ?limit=1 (the default is 20):
➔ curl -H "FOXY-API-VERSION: 1" -H "Authorization: Bearer a7eIEB6o21jS937Snl4jg0BEP9827bgo3ngod21f" https://api.foxycart.com/stores/41000/transactions?limit=1
{
"_links": {
"curies": [
{
"name": "fx",
"href": "https://api.foxycart.com/rels/{rel}",
"templated": true
}
],
"self": {
"href": "https://api.foxycart.com/stores/41000/transactions",
"title": "This Collection"
},
"first": {
"href": "https://api.foxycart.com/stores/41000/transactions?offset=0",
"title": "First Page of this Collection"
},
"prev": {
"href": "https://api.foxycart.com/stores/41000/transactions?offset=0",
"title": "Previous Page of this Collection"
},
"next": {
"href": "https://api.foxycart.com/stores/41000/transactions?offset=0",
"title": "Next Page of this Collection"
},
"last": {
"href": "https://api.foxycart.com/stores/41000/transactions?offset=0",
"title": "Last Page of this Collection"
}
},
"_embedded": {
"fx:transactions": [
{
"_links": {
"curies": [
{
"name": "fx",
"href": "https://api.foxycart.com/rels/{rel}",
"templated": true
}
],
"self": {
"href": "https://api.foxycart.com/transactions/1105668353",
"title": "This Transaction"
},
"fx:attributes": {
"href": "https://api.foxycart.com/transactions/1105668353/attributes",
"title": "Attributes for this Transaction"
},
"fx:store": {
"href": "https://api.foxycart.com/stores/41000",
"title": "This Store"
},
"fx:receipt": {
"href": "https://johnsteststore.foxycart.com/receipt?id=7b07ade6235d1505cc3b46adh386ecf305ih720a3f07481aeb7b7ca262259f0a",
"title": "This Receipt",
"type": "text/html"
},
"fx:customer": {
"href": "https://api.foxycart.com/customers/21464751",
"title": "This Customer"
},
"fx:items": {
"href": "https://api.foxycart.com/transactions/1105668353/items",
"title": "The Items for this Transaction"
},
"fx:payments": {
"href": "https://api.foxycart.com/transactions/1105668353/payments",
"title": "The Payments for this Transaction"
},
"fx:applied_taxes": {
"href": "https://api.foxycart.com/transactions/1105668353/applied_taxes",
"title": "The Applied Taxes for this Transaction"
},
"fx:custom_fields": {
"href": "https://api.foxycart.com/transactions/1105668353/transaction_custom_fields",
"title": "The Custom Fields for this Transaction"
},
"fx:discounts": {
"href": "https://api.foxycart.com/transactions/1105668353/discounts",
"title": "The Discounts for this Transaction"
},
"fx:shipments": {
"href": "https://api.foxycart.com/transactions/1105668353/shipments",
"title": "The Shipments for this Transaction"
},
"fx:billing_addresses": {
"href": "https://api.foxycart.com/transactions/1105668353/billing_addresses",
"title": "The Billing Addresses for this Transaction"
},
"fx:process_webhook": {
"href": "https://api.foxycart.com/transactions/1105668353/process_webhook",
"title": "POST here to resend the webhook notification for this transaction"
},
"fx:send_emails": {
"href": "https://api.foxycart.com/transactions/1105668353/send_emails",
"title": "POST here to resend emails for this transaction."
}
},
"id": 1105668353,
"is_test": true,
"hide_transaction": false,
"data_is_fed": false,
"transaction_date": "2016-09-13T22:26:42-07:00",
"locale_code": "en_US",
"customer_first_name": "Montgomery",
"customer_last_name": "Scott",
"customer_tax_id": "",
"customer_email": "mscott@example.com",
"customer_ip": "192.168.0.1",
"ip_country": "United States",
"total_item_price": 15,
"total_tax": 0,
"total_shipping": 15,
"total_future_shipping": 0,
"total_order": 30,
"status": "",
"date_created": null,
"date_modified": "2016-09-13T22:26:42-0700"
}
]
},
"total_items": "26",
"returned_items": 1,
"limit": 1,
"offset": 0
}Zooming additional information
By default, the transaction request will just return the base transaction information - that which is associated with the transaction relation. As you can see though - the transaction has a whole stack of additional information included in relations which would be relevant. This is where zooming comes into play.
Zooming allows you to embed information connected to a given resource directly into the response, saving you separate requests to fetch that information. For a transaction, this includes the relations for customer, payments, items, applied_taxes, custom_fields, discounts, shipments, billing_addresses. Some zoomable relations have relations they can in turn zoom on as well, for example items has item_options and item_category. If you wanted to embed all of that information in the response to collect everything we can about this transaction - that would look like this:
?zoom=customer,payments,items,items:item_options,items:item_category,applied_taxes,custom_fields,discounts,shipments,billing_addressesRe-using our previous request, let's say we just wanted to pull in the cart details - so items and it's relations - that would look like this:
➔ curl -H "FOXY-API-VERSION: 1" -H "Authorization: Bearer a7eIEB6o21jS937Snl4jg0BEP9827bgo3ngod21f" https://api.foxycart.com/stores/41000/transactions?limit=1&zoom=items,items:item_options,items:item_category
{
"_links": {
...
},
"_embedded": {
"fx:transactions": [
{
"_links": {
"curies": [
{
"name": "fx",
"href": "https://api.foxycart.com/rels/{rel}",
"templated": true
}
],
"self": {
"href": "https://api.foxycart.com/transactions/1105668353",
"title": "This Transaction"
},
"fx:attributes": {
"href": "https://api.foxycart.com/transactions/1105668353/attributes",
"title": "Attributes for this Transaction"
},
"fx:store": {
"href": "https://api.foxycart.com/stores/41000",
"title": "This Store"
},
"fx:receipt": {
"href": "https://johnsteststore.foxycart.com/receipt?id=7b07ade6235d1505cc3b46adh386ecf305ih720a3f07481aeb7b7ca262259f0a",
"title": "This Receipt",
"type": "text/html"
},
"fx:customer": {
"href": "https://api.foxycart.com/customers/21464751",
"title": "This Customer"
},
"fx:items": {
"href": "https://api.foxycart.com/transactions/1105668353/items",
"title": "The Items for this Transaction"
},
"fx:payments": {
"href": "https://api.foxycart.com/transactions/1105668353/payments",
"title": "The Payments for this Transaction"
},
"fx:applied_taxes": {
"href": "https://api.foxycart.com/transactions/1105668353/applied_taxes",
"title": "The Applied Taxes for this Transaction"
},
"fx:custom_fields": {
"href": "https://api.foxycart.com/transactions/1105668353/transaction_custom_fields",
"title": "The Custom Fields for this Transaction"
},
"fx:discounts": {
"href": "https://api.foxycart.com/transactions/1105668353/discounts",
"title": "The Discounts for this Transaction"
},
"fx:shipments": {
"href": "https://api.foxycart.com/transactions/1105668353/shipments",
"title": "The Shipments for this Transaction"
},
"fx:billing_addresses": {
"href": "https://api.foxycart.com/transactions/1105668353/billing_addresses",
"title": "The Billing Addresses for this Transaction"
},
"fx:process_webhook": {
"href": "https://api.foxycart.com/transactions/1105668353/process_webhook",
"title": "POST here to resend the webhook notification for this transaction"
},
"fx:send_emails": {
"href": "https://api.foxycart.com/transactions/1105668353/send_emails",
"title": "POST here to resend emails for this transaction."
}
},
"_embedded": {
"fx:items": [
{
"_links": {
"curies": [
{
"name": "fx",
"href": "https://api.foxycart.com/rels/{rel}",
"templated": true
}
],
"self": {
"href": "https://api.foxycart.com/items/71772434",
"title": "This Item"
},
"fx:store": {
"href": "https://api.foxycart.com/stores/41000",
"title": "This Store"
},
"fx:transaction": {
"href": "https://api.foxycart.com/transactions/1105668353",
"title": "This Transaction"
},
"fx:item_category": {
"href": "https://api.foxycart.com/item_categories/79460",
"title": "This Item Category"
},
"fx:item_options": {
"href": "https://api.foxycart.com/items/71772434/item_options",
"title": "Item Options for This Item"
},
"fx:shipment": {
"href": "https://api.foxycart.com/transactions/1105668353/shipment",
"title": "Shipment for this Item"
}
},
"_embedded": {
"fx:item_category": {
"_links": {
"curies": [
{
"name": "fx",
"href": "https://api.foxycart.com/rels/{rel}",
"templated": true
}
],
"self": {
"href": "https://api.foxycart.com/item_categories/79460",
"title": "flat_rate"
},
"fx:store": {
"href": "https://api.foxycart.com/stores/41000",
"title": "This Store"
},
"fx:email_templates": {
"href": "https://api.foxycart.com/stores/41000/email_templates",
"title": "Email Templates for this store"
},
"fx:tax_item_categories": {
"href": "https://api.foxycart.com/item_categories/79460/tax_item_categories",
"title": "Tax Item Category relationships"
}
},
"admin_email_template_uri": "",
"customer_email_template_uri": "",
"code": "flat_rate",
"name": "Flat Rate Shipping",
"item_delivery_type": "flat_rate",
"max_downloads_per_customer": 3,
"max_downloads_time_period": 24,
"default_weight": 1,
"default_weight_unit": "LBS",
"default_length_unit": "IN",
"shipping_flat_rate_type": "per_order",
"shipping_flat_rate": 15,
"handling_fee_type": "none",
"handling_fee": 0,
"handling_fee_minimum": 0,
"handling_fee_percentage": 0,
"customs_value": 0,
"discount_type": null,
"discount_name": null,
"discount_details": null,
"send_customer_email": false,
"send_admin_email": false,
"admin_email": null,
"date_created": "2016-09-09T06:07:31-0700",
"date_modified": "2016-09-09T06:07:31-0700"
}
},
"item_category_uri": "https://api.foxycart.com/item_categories/79460",
"name": "My Test Product",
"price": 15,
"quantity": 1,
"quantity_min": 0,
"quantity_max": 0,
"weight": 1,
"code": "test1",
"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": "",
"length": 0,
"width": 0,
"height": 0,
"expires": 0,
"date_created": null,
"date_modified": "2016-09-13T22:23:32-0700"
}
]
},
"id": 1105668353,
"is_test": true,
"hide_transaction": false,
"data_is_fed": false,
"transaction_date": "2016-09-13T22:26:42-07:00",
"locale_code": "en_US",
"customer_first_name": "Montgomery",
"customer_last_name": "Scott",
"customer_tax_id": "",
"customer_email": "mscott@example.com",
"customer_ip": "192.168.0.1",
"ip_country": "United States",
"total_item_price": 15,
"total_tax": 0,
"total_shipping": 15,
"total_future_shipping": 0,
"total_order": 30,
"status": "",
"date_created": null,
"date_modified": "2016-09-13T22:26:42-0700"
}
]
},
"total_items": "26",
"returned_items": 1,
"limit": "1",
"offset": 0
}You'll see within the response above that the response has the same embedded fx:transactions object, but then it in turn has an embedded object containing fx:items which in turn has an embedded object containing fx:item_category and fx:item_options. From that response we now have a complete view of what this customer ordered in a single request.
Filtering
Along with zooming on related information, you can also filter the results of requests. The API supports a number of different filters, including exact, partial and range filters. For this example, let's find all transactions for the customers email by using an exact filter of customer_email=mscott@example.com:
➔ curl -H "FOXY-API-VERSION: 1" -H "Authorization: Bearer a7eIEB6o21jS937Snl4jg0BEP9827bgo3ngod21f" https://api.foxycart.com/stores/41000/transactions?limit=1&customer_email=mscott@example.com
{
"_links": {
...
},
"_embedded": {
"fx:transactions": [
{
"_links": {
...
},
"id": 1105668353,
"is_test": true,
"hide_transaction": false,
"data_is_fed": false,
"transaction_date": "2016-09-13T22:26:42-07:00",
"locale_code": "en_US",
"customer_first_name": "Montgomery",
"customer_last_name": "Scott",
"customer_tax_id": "",
"customer_email": "mscott@example.com",
"customer_ip": "192.168.0.1",
"ip_country": "United States",
"total_item_price": 15,
"total_tax": 0,
"total_shipping": 15,
"total_future_shipping": 0,
"total_order": 30,
"status": "",
"date_created": null,
"date_modified": "2016-09-13T22:26:42-0700"
}
]
},
"total_items": "3",
"returned_items": 1,
"limit": "1",
"offset": 0
}For the sake of this example, the two _links objects have been emptied, and while we're still limiting the response to 1 transaction per page - you can see from the total_items at the bottom of the response that this customer has placed 3 orders with the store.
And much more!
Hopefully these examples provide a quick overview for interacting with the Foxy API - obviously there is a whole lot more you can do. Take a look at the API Reference for a complete listing of it's structure, and the Cheatsheet for a quick overview of technical aspects of interacting with the API.