{"_id":"54cc2149380ecd0d00ca18d2","category":{"_id":"54cc2149380ecd0d00ca18ae","__v":2,"pages":["54cc2149380ecd0d00ca18d2","54cc2149380ecd0d00ca18d3","54cc2149380ecd0d00ca18d4","54cc2149380ecd0d00ca18d5","555236587988e10d003452e9"],"project":"5436a1e1d0ffee0e00f18f8c","version":"54cc2148380ecd0d00ca18aa","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-10-09T15:31:35.377Z","from_sync":false,"order":3,"slug":"easyship-widget","title":"EasyShip Widget"},"parentDoc":null,"project":"5436a1e1d0ffee0e00f18f8c","version":{"_id":"54cc2148380ecd0d00ca18aa","__v":2,"forked_from":"5436a1e1d0ffee0e00f18f8f","project":"5436a1e1d0ffee0e00f18f8c","createdAt":"2015-01-31T00:26:48.753Z","releaseDate":"2015-01-31T00:26:48.753Z","categories":["54cc2149380ecd0d00ca18ab","54cc2149380ecd0d00ca18ac","54cc2149380ecd0d00ca18ad","54cc2149380ecd0d00ca18ae","54cc2149380ecd0d00ca18af","54cc2149380ecd0d00ca18b0","54cc2149380ecd0d00ca18b1","54cc2149380ecd0d00ca18b2","54cc2149380ecd0d00ca18b3","552f29ca633a5b0d00e99d09"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.1.0","version":"1.1"},"__v":5,"user":"543967302e0fd70e00ec63d3","updates":[],"next":{"pages":[],"description":""},"createdAt":"2014-10-11T17:55:02.328Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"never","params":[],"url":""},"isReference":false,"order":0,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Prerequisites\"\n}\n[/block]\nYou'll need an official ShippingEasy Partner account before integrating the EasyShip widget into your codebase. Contact product:::at:::shippingeasy.com if your company would like to become a partner.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"1. Include the script tag\"\n}\n[/block]\nYou can integrate EasyShip with a minimal amount of client-side code. First you will need to include the EasyShip javascript library, initialized with a few configuration options.\n\nHere's the simplest configuration, setting the session token on the script tag. In this case the token is shared for all EasyShip triggers on the page:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<script\\n  src=\\\"https://app.shippingeasy.com/easyship.js\\\"\\n  data-partner-key=\\\"XXX\\\"\\n  data-token=\\\"dc02eec82448924a6a8d0ad4a1174af41e342fc2d45962e702ac137bd\\\">\\n</script>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Atrtibute\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"data-partner-key\",\n    \"1-0\": \"data-token\",\n    \"0-1\": \"Your public API key given to you when your ShippingEasy partner account was created.\",\n    \"1-1\": \"A special, time-limited session token that you generate on your server and pass down to the client-side code when rendering the page. This is not needed if you write your own custom token function and assign it to EasyShip.\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"2. Create an EasyShip button or link\"\n}\n[/block]\nNext, you will need to create a trigger to initialize the EasyShip modal for each order on your page. Here's an example of attaching EasyShip behavior to a button:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<button class=\\\"easyship-trigger\\\"\\n  data-order-number=\\\"XXX123\\\"\\n  data-ship-from-name=\\\"ShippingEasy Inc.\\\"\\n  data-ship-from-address=\\\"609 Castle Ridge Rd\\\"\\n  data-ship-from-city=\\\"Austin\\\"\\n  data-ship-from-state=\\\"TX\\\"\\n  data-ship-from-postal-code=\\\"78746\\\"\\n  data-ship-from-postal-code-override=\\\"99501\\\"\\n  data-ship-from-country=\\\"USA\\\"\\n  data-ship-from-phone-number=\\\"512-699-4421\\\"\\n  data-ship-to-first-name=\\\"Theo\\\"\\n  data-ship-to-last-name=\\\"Mills\\\"\\n  data-ship-to-company=\\\"Acme Inc\\\"\\n  data-ship-to-address=\\\"7500 Happy Lane\\\"\\n  data-ship-to-city=\\\"Austin\\\"\\n  data-ship-to-state=\\\"TX\\\"\\n  data-ship-to-postal-code=\\\"78701\\\"\\n  data-ship-to-country=\\\"USA\\\"\\n  data-ship-to-email=\\\"test@etet.com\\\"\\n  data-ship-to-phone-number=\\\"512-777-1234\\\"\\n  data-ship-to-residential=true\\n  data-line-item-description-1=\\\"Socks\\\"\\n  data-line-item-quantity-1=\\\"1\\\"\\n  data-line-item-value-cents-1=\\\"1000\\\"\\n  data-line-item-weight-in-ounces-1=\\\"16\\\"\\n  data-line-item-country-of-manufacture-1=\\\"USA\\\"\\n  data-pounds=\\\"1\\\"\\n  data-ounces=\\\"3\\\">EasyShip</button>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nThe data attributes include details about the order that is ready to be shipped and are used to pre-populate the shipment form inside the EasyShip modal. The \"easyship-trigger\" class on the element adds an on-click event to trigger the EasyShip modal.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Attribute\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"data-order-number\",\n    \"0-1\": \"The unique order identifier from your system.\",\n    \"1-0\": \"data-ship-from-name\",\n    \"2-0\": \"data-ship-from-address\",\n    \"1-1\": \"Name of the person or company sending the package.\",\n    \"2-1\": \"The sender's street address.\",\n    \"3-0\": \"data-ship-from-address2\",\n    \"3-1\": \"Additional field for the sender's street address.\",\n    \"4-0\": \"data-ship-from-city\",\n    \"4-1\": \"The sender's city\",\n    \"5-0\": \"data-ship-from-state\",\n    \"5-1\": \"The sender's state\",\n    \"6-0\": \"data-ship-from-province\",\n    \"6-1\": \"The sender's province\",\n    \"7-0\": \"data-ship-from-postal-code\",\n    \"7-1\": \"The sender's postal code\",\n    \"8-0\": \"data-ship-from-postal-code-plus-4\",\n    \"8-1\": \"The sender's postal code plus 4\",\n    \"10-0\": \"data-ship-from-country\",\n    \"10-1\": \"The sender's country\",\n    \"11-0\": \"data-ship-from-email\",\n    \"11-1\": \"The sender's email address\",\n    \"12-0\": \"data-ship-from-phone-number\",\n    \"12-1\": \"The sender's phone number\",\n    \"13-0\": \"data-ship-from-residential\",\n    \"13-1\": \"*Boolean *\\nSet to **true** if the sender's address is residential, **false** if address is commercial\",\n    \"14-0\": \"data-ship-to-first-name\",\n    \"14-1\": \"First name of recipient.\",\n    \"15-0\": \"data-ship-to-last-name\",\n    \"15-1\": \"Last name of the recipient.\",\n    \"16-0\": \"data-ship-to-company\",\n    \"16-1\": \"Name of the recipient's company.\",\n    \"17-0\": \"data-ship-to-address\",\n    \"18-0\": \"data-ship-to-address2\",\n    \"19-0\": \"data-ship-to-city\",\n    \"20-0\": \"data-ship-to-state\",\n    \"21-0\": \"data-ship-to-province\",\n    \"22-0\": \"data-ship-to-postal-code\",\n    \"23-0\": \"data-ship-to-postal-code-plus-4\",\n    \"24-0\": \"data-ship-to-country\",\n    \"25-0\": \"data-ship-to-email\",\n    \"26-0\": \"data-ship-to-phone-number\",\n    \"27-0\": \"data-ship-to-residential\",\n    \"27-1\": \"*Boolean *\\nSet to **true** if the recipient's address is residential, **false** if address is commercial\",\n    \"28-0\": \"data-pounds\",\n    \"29-0\": \"data-ounces\",\n    \"30-0\": \"data-line-item-quantity-[1..5]\",\n    \"31-0\": \"data-weight-in-ounces-[1..5]\",\n    \"32-0\": \"data-line-item-value-cents-[1..5]\",\n    \"33-0\": \"data-line-item-description-[1..5]\",\n    \"34-0\": \"data-line-item-country-of-manufacture-[1..5]\",\n    \"34-1\": \"The country in which the item was manufactured. This is needed for customs forms if the order is international. Defaults to \\\"United States\\\" if not specified.\",\n    \"33-1\": \"*Required for each line item.*\\n\\nThe description or item name of the nth line item.\",\n    \"31-1\": \"*Integer*\\n\\n*Required for each line item.*\\n\\nThe number of ounces that the nth line item weighs. Note that the sum of all line items should match the order's total weight.\",\n    \"32-1\": \"*Integer*\\n\\n*Required for each line item.*\\n\\nThe value of the nth line item in cents. E.g. $1.00 would be represented as \\\"100\\\".\",\n    \"30-1\": \"*Integer*\\n\\n*Required for each line item.*\\n\\nThe quantity of the nth line item.\",\n    \"29-1\": \"*Integer or Float*\\nThe number of ounces the order weighs.\",\n    \"28-1\": \"*Integer*\\nThe number of pounds the order weighs.\",\n    \"26-1\": \"The recipient's phone number\",\n    \"25-1\": \"The recipient's email address\",\n    \"24-1\": \"The recipient's country\",\n    \"23-1\": \"The recipient's postal code plus 4\",\n    \"22-1\": \"The recipient's postal code\",\n    \"21-1\": \"The recipient's province if address is international\",\n    \"20-1\": \"The recipient's state if address is domestic\",\n    \"19-1\": \"The recipient's city\",\n    \"18-1\": \"Additional field for the recipient's street address.\",\n    \"17-1\": \"The recipient's street address.\",\n    \"9-0\": \"data-ship-from-postal-code-override\",\n    \"9-1\": \"Optional origin postal code (USPS only)\"\n  },\n  \"cols\": 2,\n  \"rows\": 35\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Line items\",\n  \"body\": \"Line items are only needed if the order is international, because they are used to generate a customs form for the shipment.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"3. Generate a session token from your server\"\n}\n[/block]\nIn order to authenticate the Ajax calls coming from the the client-side EasyShip modal, a session token must first be generated on your server. Session tokens are generated using our REST partner API and require that you first have a Parter API key and API secret. The token is included in the Javascript configuration options, as detailed in \"Client-side setup\".\n\nOur API calls require that the request be signed using your key and secret. The session token call also requires that a \"customer identifier\" is included so that we can associate specific EasyShip sessions with a customer in your system. This identifier should be unique to your system, as it will be used to reconcile label purchases made against your partner account.\n\nSession tokens can be created to live from 5 seconds to 30 minutes and may be marked as `single use` to ensure every request is freshly authenticated.\n\n### Custom token function\n\nIt is possible to write your own token function that will be executed before every EasyShip request. There are several benefits to taking this approach:\n\n* To create short-lived, single-use tokens, increasing the security of your EasyShip communications\n* Preventing a session token from expiring as a user waits on a page\n\nIdeally this function would make a remote request to a token generating endpoint on your server. Here's is an example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"EasyShip.token = function (orderNumber) {\\n  var $token = \\\"\\\";\\n  $.ajax({\\n    url: \\\"/tokens\\\",\\n    type: \\\"post\\\",\\n    dataType: \\\"json\\\",\\n    async:false,\\n    data: { \\\"order_number\\\": orderNumber }\\n  }).done(function(data) {\\n      $token = data.token;\\n    }\\n  );\\n  return $token;\\n}\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]","excerpt":"EasyShip is a simple, embeddable shipping widget that provides a fully managed label printing solution within e-commerce platforms or marketplaces. It allows merchants to seamlessly generate shipping labels and fulfill e-commerce orders with minimal development effort.","slug":"quick-start","type":"basic","title":"Quick start"}

Quick start

EasyShip is a simple, embeddable shipping widget that provides a fully managed label printing solution within e-commerce platforms or marketplaces. It allows merchants to seamlessly generate shipping labels and fulfill e-commerce orders with minimal development effort.

[block:api-header] { "type": "basic", "title": "Prerequisites" } [/block] You'll need an official ShippingEasy Partner account before integrating the EasyShip widget into your codebase. Contact product@shippingeasy.com if your company would like to become a partner. [block:api-header] { "type": "basic", "title": "1. Include the script tag" } [/block] You can integrate EasyShip with a minimal amount of client-side code. First you will need to include the EasyShip javascript library, initialized with a few configuration options. Here's the simplest configuration, setting the session token on the script tag. In this case the token is shared for all EasyShip triggers on the page: [block:code] { "codes": [ { "code": "<script\n src=\"https://app.shippingeasy.com/easyship.js\"\n data-partner-key=\"XXX\"\n data-token=\"dc02eec82448924a6a8d0ad4a1174af41e342fc2d45962e702ac137bd\">\n</script>", "language": "html" } ] } [/block] [block:parameters] { "data": { "h-0": "Atrtibute", "h-1": "Description", "0-0": "data-partner-key", "1-0": "data-token", "0-1": "Your public API key given to you when your ShippingEasy partner account was created.", "1-1": "A special, time-limited session token that you generate on your server and pass down to the client-side code when rendering the page. This is not needed if you write your own custom token function and assign it to EasyShip." }, "cols": 2, "rows": 2 } [/block] [block:api-header] { "type": "basic", "title": "2. Create an EasyShip button or link" } [/block] Next, you will need to create a trigger to initialize the EasyShip modal for each order on your page. Here's an example of attaching EasyShip behavior to a button: [block:code] { "codes": [ { "code": "<button class=\"easyship-trigger\"\n data-order-number=\"XXX123\"\n data-ship-from-name=\"ShippingEasy Inc.\"\n data-ship-from-address=\"609 Castle Ridge Rd\"\n data-ship-from-city=\"Austin\"\n data-ship-from-state=\"TX\"\n data-ship-from-postal-code=\"78746\"\n data-ship-from-postal-code-override=\"99501\"\n data-ship-from-country=\"USA\"\n data-ship-from-phone-number=\"512-699-4421\"\n data-ship-to-first-name=\"Theo\"\n data-ship-to-last-name=\"Mills\"\n data-ship-to-company=\"Acme Inc\"\n data-ship-to-address=\"7500 Happy Lane\"\n data-ship-to-city=\"Austin\"\n data-ship-to-state=\"TX\"\n data-ship-to-postal-code=\"78701\"\n data-ship-to-country=\"USA\"\n data-ship-to-email=\"test@etet.com\"\n data-ship-to-phone-number=\"512-777-1234\"\n data-ship-to-residential=true\n data-line-item-description-1=\"Socks\"\n data-line-item-quantity-1=\"1\"\n data-line-item-value-cents-1=\"1000\"\n data-line-item-weight-in-ounces-1=\"16\"\n data-line-item-country-of-manufacture-1=\"USA\"\n data-pounds=\"1\"\n data-ounces=\"3\">EasyShip</button>", "language": "html" } ] } [/block] The data attributes include details about the order that is ready to be shipped and are used to pre-populate the shipment form inside the EasyShip modal. The "easyship-trigger" class on the element adds an on-click event to trigger the EasyShip modal. [block:parameters] { "data": { "h-0": "Attribute", "h-1": "Description", "0-0": "data-order-number", "0-1": "The unique order identifier from your system.", "1-0": "data-ship-from-name", "2-0": "data-ship-from-address", "1-1": "Name of the person or company sending the package.", "2-1": "The sender's street address.", "3-0": "data-ship-from-address2", "3-1": "Additional field for the sender's street address.", "4-0": "data-ship-from-city", "4-1": "The sender's city", "5-0": "data-ship-from-state", "5-1": "The sender's state", "6-0": "data-ship-from-province", "6-1": "The sender's province", "7-0": "data-ship-from-postal-code", "7-1": "The sender's postal code", "8-0": "data-ship-from-postal-code-plus-4", "8-1": "The sender's postal code plus 4", "10-0": "data-ship-from-country", "10-1": "The sender's country", "11-0": "data-ship-from-email", "11-1": "The sender's email address", "12-0": "data-ship-from-phone-number", "12-1": "The sender's phone number", "13-0": "data-ship-from-residential", "13-1": "*Boolean *\nSet to **true** if the sender's address is residential, **false** if address is commercial", "14-0": "data-ship-to-first-name", "14-1": "First name of recipient.", "15-0": "data-ship-to-last-name", "15-1": "Last name of the recipient.", "16-0": "data-ship-to-company", "16-1": "Name of the recipient's company.", "17-0": "data-ship-to-address", "18-0": "data-ship-to-address2", "19-0": "data-ship-to-city", "20-0": "data-ship-to-state", "21-0": "data-ship-to-province", "22-0": "data-ship-to-postal-code", "23-0": "data-ship-to-postal-code-plus-4", "24-0": "data-ship-to-country", "25-0": "data-ship-to-email", "26-0": "data-ship-to-phone-number", "27-0": "data-ship-to-residential", "27-1": "*Boolean *\nSet to **true** if the recipient's address is residential, **false** if address is commercial", "28-0": "data-pounds", "29-0": "data-ounces", "30-0": "data-line-item-quantity-[1..5]", "31-0": "data-weight-in-ounces-[1..5]", "32-0": "data-line-item-value-cents-[1..5]", "33-0": "data-line-item-description-[1..5]", "34-0": "data-line-item-country-of-manufacture-[1..5]", "34-1": "The country in which the item was manufactured. This is needed for customs forms if the order is international. Defaults to \"United States\" if not specified.", "33-1": "*Required for each line item.*\n\nThe description or item name of the nth line item.", "31-1": "*Integer*\n\n*Required for each line item.*\n\nThe number of ounces that the nth line item weighs. Note that the sum of all line items should match the order's total weight.", "32-1": "*Integer*\n\n*Required for each line item.*\n\nThe value of the nth line item in cents. E.g. $1.00 would be represented as \"100\".", "30-1": "*Integer*\n\n*Required for each line item.*\n\nThe quantity of the nth line item.", "29-1": "*Integer or Float*\nThe number of ounces the order weighs.", "28-1": "*Integer*\nThe number of pounds the order weighs.", "26-1": "The recipient's phone number", "25-1": "The recipient's email address", "24-1": "The recipient's country", "23-1": "The recipient's postal code plus 4", "22-1": "The recipient's postal code", "21-1": "The recipient's province if address is international", "20-1": "The recipient's state if address is domestic", "19-1": "The recipient's city", "18-1": "Additional field for the recipient's street address.", "17-1": "The recipient's street address.", "9-0": "data-ship-from-postal-code-override", "9-1": "Optional origin postal code (USPS only)" }, "cols": 2, "rows": 35 } [/block] [block:callout] { "type": "info", "title": "Line items", "body": "Line items are only needed if the order is international, because they are used to generate a customs form for the shipment." } [/block] [block:api-header] { "type": "basic", "title": "3. Generate a session token from your server" } [/block] In order to authenticate the Ajax calls coming from the the client-side EasyShip modal, a session token must first be generated on your server. Session tokens are generated using our REST partner API and require that you first have a Parter API key and API secret. The token is included in the Javascript configuration options, as detailed in "Client-side setup". Our API calls require that the request be signed using your key and secret. The session token call also requires that a "customer identifier" is included so that we can associate specific EasyShip sessions with a customer in your system. This identifier should be unique to your system, as it will be used to reconcile label purchases made against your partner account. Session tokens can be created to live from 5 seconds to 30 minutes and may be marked as `single use` to ensure every request is freshly authenticated. ### Custom token function It is possible to write your own token function that will be executed before every EasyShip request. There are several benefits to taking this approach: * To create short-lived, single-use tokens, increasing the security of your EasyShip communications * Preventing a session token from expiring as a user waits on a page Ideally this function would make a remote request to a token generating endpoint on your server. Here's is an example: [block:code] { "codes": [ { "code": "EasyShip.token = function (orderNumber) {\n var $token = \"\";\n $.ajax({\n url: \"/tokens\",\n type: \"post\",\n dataType: \"json\",\n async:false,\n data: { \"order_number\": orderNumber }\n }).done(function(data) {\n $token = data.token;\n }\n );\n return $token;\n}", "language": "javascript" } ] } [/block]