TGC Shopify App
TradeGlobal Commerce’s (TGC) Shopify App enables merchants to easily integrate our fully landed cost quoting engine into the merchant’s Shopify store checkout. Once a download link is provided, the merchant simply downloads the app into their store, creates the desired international shipping zones, and enables “TradeGlobal Commerce” for the shipping rates. Additionally, this app enables merchant’s to leverage TGC’s shipping portal to generate international shipping labels by automatically loading orders into our system via the merchant’s Shopify store. The following sections will explain how to configure and use the TGC Shopify App.
Included in this installation
- POST CarrierService - our app will execute a POST CarrierService call to add TradeGlobal Commerce as one of your usable shipping methods within your Shopify store.
- CarrierService Webhook - This creates a webhook within Shopify to call our quoting service within the checkout of your Shopify store.
- LoadOrder Webhook - This creates a webhook within your Shopify store that is executed upon an orders/create call within Shopify. The purpose of this is to load the given international order into TradeGlobal Commerce so that international shipping labels can be created. This webhook also performs a PUT on the given Shopify order to update the order with the calculated duties and taxes.
Installation Instructions
To download our Shopify app, you must first request a download link. When requesting the download link, you will need to provide your shop domain. Click here to request a download link.
Once you have downloaded our Shopify app into your store using the provided download link, you will need to configure your store to enable our app to quote shipping options. Use the following steps to properly setup your store to use TGC.
-
After the app has been downloaded, navigate to your store settings by clicking “Settings” at the bottom left of the screen
-
Once the Settings page has loaded, click on “Shipping and Delivery”
-
Click on “Manage Rates”
-
In this section, you will need to create your international zones. DO NOT use the “Rest of World” zone for destinations that you wish to use TGC shipping services. It will not work with the app. You will need to create a zone for each country.
To create a zone, click on “Create shipping zone”
-
Once the Create zone panel appears, select the desired country from the country listing and click “Done”
-
You will now see your selected country in the list of shipping zones however, there will also be a dialog indicating that there are no rates. This is where you will enable TGC to quote shipping options for this country. Click “Add rate”
-
Once the add rate panel appears, click the “Use carrier or app to calculate rates” radio button. Then select “TradeGlobal Commerce” and click “Done”.
-
You will now see TradeGlobal Commerce as the shipping rate listing for the selected country in this list of shipping zones. You will need to repeat these steps for all international destinations that you are wanting to ship to.
Please Note… In some instances TradeGlobal Commerce may be automatically added to your domestic shipping zone. Please remove TradeGlobal Commerce from the domestic shipping zone as we have found leaving it enabled will cause the app to not work when trying to retrieve shipping options from international zones.
Handling Fees
When obtaining a shipping option using Shopify’s CarrierService API, the only fee returned is a total amount. When shipping internationally, merchants will want to know all fees involved such as duties and taxes. To update the order in Shopify with what the included duties and taxes are, our app will execute a secondary call that updates the Shopify order with the duties and taxes upon checkout. Please note... The duties and taxes are included in the total amount that is returned in the CarrierService response. Once the order is loaded, you can view these details in the “Additional Details” panel when viewing the order in Shopify.
If you are wanting to map these fees into another system such as an order management system (OMS), you will need to pulls the values within the “note_attributes” array within the Shopify order object. Below is a sample shopify order json object containing the note_attributes object.
{
"order": {
"id": 3283557089480,
"email": "",
"closed_at": null,
"created_at": "2021-02-23T10:18:02-05:00",
"updated_at": "2021-02-23T10:18:50-05:00",
"number": 29,
"note": null,
"token": "62ab7ddd4a000ba141ed2e62f8881576",
"gateway": "bogus",
"test": true,
"total_price": "90.33",
"subtotal_price": "72.00",
"total_weight": 136,
"total_tax": "0.00",
"taxes_included": false,
"currency": "USD",
"financial_status": "paid",
"confirmed": true,
"total_discounts": "0.00",
"total_line_items_price": "72.00",
"cart_token": "b0128c619b8f6035f8fe83cd339c086f",
"buyer_accepts_marketing": false,
"name": "#1029",
"referring_site": "",
"landing_site": "/?_bt=eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaEpJaDUyYVhOcFlteGxMV1JsZGk1dGVYTm9iM0JwWm5rdVkyOXRCam9HUlZRPSIsImV4cCI6IjIwMjEtMDItMjNUMTY6MTU6NDkuNDMxWiIsInB1ciI6InBlcm1hbmVudF9wYXNzd29yZF9ieXBhc3MifX0=--7621050f73fc4ec9f14b920ff973072ffef99791",
"cancelled_at": null,
"cancel_reason": null,
"total_price_usd": "90.33",
"checkout_token": "51c86f160498bafd09879872a989bca6",
"reference": null,
"user_id": null,
"location_id": null,
"source_identifier": null,
"source_url": null,
"processed_at": "2021-02-23T05:17:30-05:00",
"device_id": null,
"phone": null,
"customer_locale": "en",
"app_id": 580111,
"browser_ip": "65.24.154.20",
"client_details": {
"accept_language": "en-US,en;q=0.9",
"browser_height": 922,
"browser_ip": "65.24.154.20",
"browser_width": 1587,
"session_hash": null,
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.182 Safari/537.36"
},
"landing_site_ref": null,
"order_number": 1029,
"discount_applications": [],
"discount_codes": [],
"note_attributes": [
{
"name": "VAT",
"value": "3.6000"
},
{
"name": "PST",
"value": "5.7600"
},
{
"name": "Duty",
"value": "0.0000"
}
],
"payment_details": {
"credit_card_bin": "1",
"avs_result_code": null,
"cvv_result_code": null,
"credit_card_number": "•••• •••• •••• 1",
"credit_card_company": "Bogus"
},
"payment_gateway_names": [
"bogus"
],
"processing_method": "direct",
"checkout_id": 19283161252040,
"source_name": "web",
"fulfillment_status": null,
"tax_lines": [],
"tags": "",
"contact_email": "test@tgc.com",
"order_status_url": "https://visible-dev.myshopify.com/53786902728/orders/62ab7ddd4a000ba141ed2e62f8881576/authenticate?key=94f747bbb64788d5b49d4dc25541bf4c",
"presentment_currency": "USD",
"total_line_items_price_set": {
"shop_money": {
"amount": "72.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "72.00",
"currency_code": "USD"
}
},
"total_discounts_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "USD"
}
},
"total_shipping_price_set": {
"shop_money": {
"amount": "18.33",
"currency_code": "USD"
},
"presentment_money": {
"amount": "18.33",
"currency_code": "USD"
}
},
"subtotal_price_set": {
"shop_money": {
"amount": "72.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "72.00",
"currency_code": "USD"
}
},
"total_price_set": {
"shop_money": {
"amount": "90.33",
"currency_code": "USD"
},
"presentment_money": {
"amount": "90.33",
"currency_code": "USD"
}
},
"total_tax_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "USD"
}
},
"line_items": [
{
"id": 9291825905864,
"variant_id": 38089405006024,
"title": "tarte travel-size water foundation Broad Spectrum SPF 15 - rich sand",
"quantity": 6,
"sku": "846733047437",
"variant_title": "",
"vendor": "Visible Dev",
"fulfillment_service": "manual",
"product_id": 6260550205640,
"requires_shipping": true,
"taxable": true,
"gift_card": false,
"name": "tarte travel-size water foundation Broad Spectrum SPF 15 - rich sand",
"variant_inventory_management": "shopify",
"properties": [],
"product_exists": true,
"fulfillable_quantity": 6,
"grams": 23,
"price": "12.00",
"total_discount": "0.00",
"fulfillment_status": null,
"price_set": {
"shop_money": {
"amount": "12.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "12.00",
"currency_code": "USD"
}
},
"total_discount_set": {
"shop_money": {
"amount": "0.00",
"currency_code": "USD"
},
"presentment_money": {
"amount": "0.00",
"currency_code": "USD"
}
},
"discount_allocations": [],
"duties": [],
"admin_graphql_api_id": "gid://shopify/LineItem/9291825905864",
"tax_lines": [],
"origin_location": {
"id": 2741029044424,
"country_code": "US",
"province_code": "OH",
"name": "Visible Dev",
"address1": "3603 Poole Road",
"address2": "",
"city": "Cincinnati",
"zip": "45251"
}
}
],
"fulfillments": [],
"refunds": [],
"total_tip_received": "0.0",
"original_total_duties_set": null,
"current_total_duties_set": null,
"admin_graphql_api_id": "gid://shopify/Order/3283557089480",
"shipping_lines": [
{
"id": 2740901707976,
"title": "Standard Shipping",
"price": "18.33",
"code": "TARTECOSMETICS:88c2b93e-67da-4d1f-97ef-c4e1263a9c05",
"source": "TradeGlobal Commerce",
"phone": null,
"requested_fulfillment_service_id": null,
"delivery_category": null,
"carrier_identifier": "820057082cb859d3625014b1b8197eba",
"discounted_price": "18.33",
"price_set": {
"shop_money": {
"amount": "18.33",
"currency_code": "USD"
},
"presentment_money": {
"amount": "18.33",
"currency_code": "USD"
}
},
"discounted_price_set": {
"shop_money": {
"amount": "18.33",
"currency_code": "USD"
},
"presentment_money": {
"amount": "18.33",
"currency_code": "USD"
}
},
"discount_allocations": [],
"tax_lines": []
}
],
"billing_address": {
"first_name": "Bryan",
"address1": "123 Main Street",
"phone": null,
"city": "Toronto",
"zip": "M5S 2A2",
"province": "Ontario",
"country": "Canada",
"last_name": "Testcase",
"address2": "",
"company": null,
"latitude": 43.6826923,
"longitude": -79.2994142,
"name": "Bryan Testcase",
"country_code": "CA",
"province_code": "ON"
},
"shipping_address": {
"first_name": "Bryan",
"address1": "123 Main Street",
"phone": null,
"city": "Toronto",
"zip": "M5S 2A2",
"province": "Ontario",
"country": "Canada",
"last_name": "Testcase",
"address2": "",
"company": null,
"latitude": 43.6826923,
"longitude": -79.2994142,
"name": "Bryan Testcase",
"country_code": "CA",
"province_code": "ON"
}
}
}
Error Handling
One limitation of using webhooks with the Shopify CarrierService API is that it doesn't by default allow for error messages returned by third party applications to be displayed. This presents challenges when trying to troubleshoot quoting issues. With a Shopify Plus account, you do have the option of scripting custom error messages in the checkout. If you decide to do this, you can use the following information to determine how you want to display an error message to your customers that are returned by TGC quoting service.
Error Object
Whenever a quote service error is triggered, you will receive an error object back in the response with the following fields.
| Field | Description | Data Type |
|---|---|---|
| ErrorCode | Number indicating the error code of the particular quoting service error. | Integer |
| ErrorMessage | Description of the error returned by the TGC web service | String |
| SKU | Indicates the identifier of the product that triggered the web service error. This field will only be populated when there is a product data issue associated with the SKU passed in the web service request. | String |
| SuggestedWebsiteErrorMessage | Many times, the web service error returned is not in a customer friendly format. Instead of mapping out custom error messages based on ErrorCode values, you can default to always pulling the error message returned in this field as we've tried to make these as customer friendly as possible. | String |
Example Responses
SKU with a dimension value of zero is passed in the request
{
"ErrorCode": 2021,
"ErrorMessage": "Invalid product. - The following SKU has missing or invalid dimensions:951745040_TEST",
"SKU": "951745040111",
"SuggestedWebsiteErrorMessage": "The following SKU is not available for international shipping at this time.
Please remove the item from your cart to proceed with checkout. SKU: 951745040111"
}
SKU missing a HSCode is passed in the request
{
"ErrorCode": 2022,
"ErrorMessage": "Invalid product list - Product with SKU (951745040_TEST) does not have a harmonized code",
"SKU": "951745040_TEST",
"SuggestedWebsiteErrorMessage": "The following item is currently not available for international shipping.
Please remove from your cart to proceed with checkout. SKU: 951745040_TEST"
}
When selected country is not enabled in TGC
{
"ErrorCode": 2007,
"ErrorMessage": "Country Shipping Restriction - Currently cannot ship to (ZW)",
"SKU": null,
"SuggestedWebsiteErrorMessage": "Unable to retrieve shipping options because the given country
is currently not enabled for international shipments."
}
CarrierService Error Codes
| Error Code | Description |
|---|---|
| 1000 | Generic Error - Unknown or Generic service error |
| 2000 | Invalid Credentials - The credentials assigned to the given Shopify store are missing or invalid |
| 2001 | Invalid Address - The ship to address passed is missing a necessary field. The missing field will be indiciated in the error message. |
| 2002 | Invalid Cart - Thrown when a quote request is passed with a null cart value, or when there are no cart items in the cart. |
| 2003 | Invalid MerchantCode - The merchant code assigned to the given shopify store domain is missing or invalid. |
| 2005 | Invalid Country - The country code provided in the ship to address is invalid. |
| 2006 | Invalid Product List - Item in the cart in not in TGC. The SKU will be provided in the error message. |
| 2007 | Restricted Country - The provided ship to country is not enabled in TGC. |
| 2008 | Restricted Item - Item in the cart is restricted from shipping to the given destrination. The restricted SKU will appear in the error message |
| 2009 | Invalid Currency - Currency code passed is invalid or not enabled in TGC |
| 2011 | No Rates Found - Occurs when shipping rates cannot be found for the given destination and weight. Typically occurs when the product weight exceeds the max weight value in TGC's freight tables |
| 2012 | Save Cart Failed - Typically occurs when a database error is triggered in TGC when the quote is being saved. |
| 2013 | Invalid Quotes - Quotes could not be generated for the given cart. |
| 2014 | Database Error - Generic TGC database error |
| 2015 | Generic Logistics Error - Generic error when obtaining shipping methods. |
| 2021 | Invalid Product - Occurs when an item is missing necessary product data such as dimensions. SKU will be provided in the error message. |
| 2022 | Invalid HTC - Item in the cart is missing a HSCode. The SKU will be provided in the error message. |