Create a checkout

Explore the key/value pairs involved in creating a checkout.

This API endpoint is used to send cart information and items from the customer’s cart to the Zonos API.

You will receive a JSON response containing a tempCartUUID, a unique cart identifier in the Zonos System. This will be used to redirect the customer to the Zonos Checkout to complete the order.

Attributes

JSON key/value pairs in the request body

POST https://api.iglobalstores.com/v1/createTempCart

field	notes
`boxCount`	Example value: 22x15x15(1),8x8x4(2),32x22x14(1) Format: Comma-separated list of box dimensions and count. In the example above, there are a total of 4 boxes. The first box in the list will be 22 inches long, by 15 inches wide, by 15 inches high. There will only be one box used for that size. There will be two boxes of size: 8x8x4 inches. It is acceptable to pass the same box dimension multiple times if that is easy for you, like this: “22x15x15(1),22x15x15(1)”, which means 2 boxes of size: 22x15x15 inches.This field describes the boxes that will be used to ship the order. It is not expected that a merchant knows this at time of order; however, if it is known, it may be passed in the `string` format.
`contShoppingURL`	This field is used to pass a URL to override the HREF of the “Continue Shopping” button inside the Zonos Checkout. `string`
`domesticShippingCharge`	This field is used to pass a domestic shipping charge to the Zonos Checkout, and the amount will be added to shipping. This can be configured to add the shipping total or be broken out as a separate line item. `positive floating point, two decimal places`
`externalConfirmationPageURL`	This field is used to pass a URL of your order confirmation / thank you page. After a customer completes payment inside the Zonos Checkout, they will be redirected to this URL for order confirmation. This URL is frequently used to trigger a call to the Zonos “orderDetail” API service endpoint to retrieve the order detail and import the order into the system. `string`
`footerHTML`	This field is used to pass a URL encoded HTML string. This HTML string will be decoded and placed before the closing body tag on the checkout page. Commonly used to pass code for re-marketing, analytics, etc. `URL encoded string`
`items` REQUIRED	This field is a list of item maps. `JSON string`
`items[index].countryOfOrigin`	This field is used to pass the item country of origin. Parameter must be the country two-letter ISO code. `string`
`items[index].description` REQUIRED	This field is used to pass a full item description of the cart line item, including any item options, colors, etc. `string`
`items[index].height`	This field is used to pass the item height and is highly recommended for accurate shipping quotes. Height units are REQUIRED in inches. `string - positive floating point, two decimal places / integer (inches)`
`items[index].imageURL` REQUIRED	This field is used to pass the URL to the item product image. The URL must be HTTPS to display inside the Zonos Checkout. `string / HTTPS URL`
`items[index]itemBrand`	This field is used to pass the item brand`string`
`items[index]itemCategory`	This field is used to pass the item category and may be passed pipe delimited if the item has more than one category. Example values: “shoes” or “shoes\|sport-shoes\|discount-shoes”`string`
`items[index]itemCustomization`	This field is used to pass additional details about the item that are not shown in the Zonos Checkout; however, this can be retrieved through the “orderDetail” API service endpoint.
`items[index]itemHSCode`	This field is used to pass the item HS code and may be with or without periods. Example values: “3926901000” or “3926.90.1000”`string`
`items[index].itemURL`	This field is used to pass the URL to the item product page. `string / URL`
`items[index].length`	This field is used to pass the item length and is highly recommended for accurate shipping quotes. Length units are REQUIRED in inches. `string - positive floating point, two decimal places / integer (inches)`
`items[index].nonShippable`	This field is used to indicate if the item should be included in the shipping, duty, and tax calculations. Digital downloads, discount codes, handling fees, etc. should be passed with a value of “true”. `boolean: true or false`
`items[index].productId`	This field is used to pass the line item quantity. `string`
`items[index].quantity` REQUIRED	This field is used to pass the line item quantity. `string`
`items[index].sku`	This field is used to pass the item SKU / UPC / etc. `string`
`items[index].unitPrice` REQUIRED	This field is used to pass the line item unit price. `positive floating point, two decimal places / integer`
`items[index].weight`	This field is used to pass the item weight and is highly recommended for accurate shipping quotes. Weight units are defaulted to “LBS” unless another weight unit is passed in items[index].itemWeightUnits``string - positive floating point, two decimal places / integer
`items[index].weightUnits`	This field is used to override the default item weight units. Item weight units are defaulted to “LBS” unless another weight unit is passed in this field. `string - "LB", "OZ", "KG", or "G”`
`items[index].width`	This field is used to pass the item width and is highly recommended for accurate shipping quotes. Width units are REQUIRED in inches. `string - positive floating point, two decimal places / integer (inches)`
`misc1 - misc6`	This field is used to pass miscellaneous data associated with the order through the Zonos API to be retrieved along with the order data returned from the Zonos “orderDetail” API service endpoint. `string`
`referenceId`	This field is used to pass a unique reference identification value for the cart/session/etc. in your system. This can be used to look up the Zonos order ID via the Zonos “orderDetail” API service endpoint. `string`
`storeId` REQUIRED	Store ID provided by Zonos. `integer`

Additional string data types

items[index].itemDescriptionLong
items[index].itemDescriptionDetailed
items[index].itemFabricContent
items[index].itemColor
items[index].itemLtlClass
items[index].status
items[index].itemMaterial

To send discounts, coupons, and promo codes to Zonos through the server post, they must be passed as a separate item with a negative value for parameters: “unitPrice” and “nonShippable”:true.

EXAMPLE DISCOUNT ITEM MAP

{
  "description": "Discount (10OFF) - 10% OFF",
  "unitPrice": -15.5,
  "quantity": 1,
  "nonShippable": true
}

HTTPS response

Success HTTP response

Message format: JSON

EXAMPLE SUCCESS RESPONSE

{
  "tempCartUUID": "826b8f22-0de6-4717-90c7-366def7d0782"
}

Response JSON definitions

field	notes
`tempCartUUID`	This parameter will contain a GUID assigned to your customer’s international cart and created in the Zonos system.This filed will be passed via a URL query `string` parameter while redirecting the user’s browser to the Zonos Checkout.

Error HTTP responses

Error code	meaning
400	Unexpected character in request body.
406	Not Acceptable. HTTP header for “Accept” is invalid.
415	Unsupported media type. HTTP header for “Content-Type” is invalid.
422	Unprocessable entity.
500	“storeId” was incorrect or JSON body could not be parsed.

EXAMPLE ERROR RESPONSE

<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
    <title>Error 422 Unprocessable Entity</title>
  </head>
  <body>
    <h2>HTTP ERROR 422</h2>
    <p>
      Problem accessing /v2/createTempCart. Reason:
      <pre>Unprocessable Entity</pre>
    </p>
    <h2>The request entity had the following errors:</h2>
    <ul>
      <li>items may not be empty (was null)</li>
      <li>items may not be null (was null)</li>
    </ul>
  </body>
</html>

Redirecting to the Zonos Checkout

After receiving a successful response containing the tempCartUUID, your server will send a redirect from the customer's browser to the Zonos Checkout with the appropriate URL query string parameters covered below.

Example Redirect URL: https://[yourassignedsubdomain].iglobalstores.com/?tempCartUUID=826b8f22-0de6-4717-90c7-366def7d0782&country=CA

Note: [yourassignedsubdomain] - Contact your Zonos implementation team member to receive your Zonos.com subdomain.

URL request parameters

field	notes
`tempCartUUID` REQUIRED	This value is obtained by calling the Zonos `createTempCart` API service endpoint. `string / GUID`
`country`	Destination country’s two-letter ISO code. We highly recommend passing this parameter for user experience. The `country` parameter will preselect the destination country inside the Zonos Checkout.When using the Zonos Hello JS (JavaScript) on the site, you may obtain this value by calling the JavaScript method: `zonos.country()`. `string` (Length: 2)

Additional string data types

customerName
customerCompany
customerEmail
customerPhone
customerAltPhone
customerAddress1
customerAddress2
customerCity
customerState
customerZip

Was this page helpful?

Questions?

See Zonos

policies and agreements.