Create a Zonos Checkout

This endpoint is used to send the cart info 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. The tempCartUUID will then be used to redirect the customer to the Zonos Checkout to complete the order.

Service end point - createTempCart

This API endpoint is used to securely pass the shopping cart details to the Zonos Checkout. When the details are posted to this endpoint, the API response will contain a tempCartUUID.

The tempCartUUID is a unique identifier for that customer’s temporary cart in the Zonos App. The tempCartUUID is passed as a URL query string parameter when redirecting the customer to the Zonos Checkout.

HTTPS request

HTTP Method POST
End Point URL https://api.iglobalstores.com/v1/createTempCart
Protocol HTTPS
Message Format JSON
Accept HTTP Header Accept: application/json
Content-Type HTTP Header Content-Type: application/json

Request parameters

Message Format JSON

{
    "storeId":999,
    "referenceId":"f5bde245-f55e-414d-b722-80b25161c12c",
    "externalConfirmationPageURL": "http://mystore.com/intlthankyou",
    "domesticShippingCharge": 12.50,
    "boxCount": "12x10x8(1)",
    "items": [
        {
            "description": "description including options, material content, etc",
            "itemCategory": "sunglasses",
            "productId": "17898-675234",
            "sku": "oakley-123",
            "unitPrice": 199.00,
            "quantity": 1,
            "length": 2.5,
            "width": 6.5,
            "height": 2.5,
            "weight": 4,
            "weightUnits": "OZ",
            "itemHSCode": null,
            "itemBrand": "Oakley",
            "countryOfOrigin": "CN",
            "status": null
        },
        {
            "description": "description including options, material content, etc",
            "itemCategory": "shoes",
            "productId": "17898-675235",
            "sku": "kicks123",
            "unitPrice": 179.00,
            "quantity": 1,
            "length": 2.5,
            "width": 6.5,
            "height": 2.5,
            "weight": 1,
            "weightUnits": "LB",
            "itemHSCode": null,
            "itemBrand": "Oakley",
            "countryOfOrigin": "CN",
            "status": null
        }
    ]
}

Request JSON definitions

storeId

Store id provided by Zonos.

Integer

Required

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

contShoppingURL

This field is used to pass a url to override the href of the “Continue Shopping” button inside the Zonos Checkout.

String

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 your 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

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 following specific format.

String

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

domesticShippingCharge

This field is used to pass a domestic shipping charge to the Zonos Checkout. This amount will be added to shipping. Can be configured to add to the shipping total or be broke out as a separate line item.

Positive floating point, two decimal places

items

A list of item maps.

JSON String

Required

items[index].description

This field is used to pass a full item description of the cart line item, including any item options, colors, etc.

String

Required

items[index].quantity

This field is used to pass the line item quantity.

String

Required

items[index].unitPrice

This field is used to pass the line item unit price.

Positive floating point, two decimal places / Integer

Required

items[index].imageURL

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].sku

This field is used to pass the item sku / upc / etc.

String

items[index].productId

This field is used to pass the item sku / upc / etc.

String

items[index].weight

This field is used to pass the item weight. 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].length

This field is used to pass the item length. Highly recommended for accurate shipping quotes. Length units are required in inches.

String - Positive floating point, two decimal places / Integer (Inches)

items[index].width

This field is used to pass the item width. Highly recommended for accurate shipping quotes. Width units are required in inches.

String - Positive floating point, two decimal places / Integer (Inches)

items[index].height

This field is used to pass the item height. Highly recommended for accurate shipping quotes. Height units are required in inches.

String - Positive floating point, two decimal places / Integer (Inches)

items[index].countryOfOrigin

This field is used to pass the item country of origin. Parameter can be country name or two digit ISO code.

String

items[index].itemURL

This field is used to pass the URL to the item product page.

String / URL

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].itemBrand

This field is used to pass the item brand.

String

items[index].itemCategory

Example values “shoes” or “shoes|sport-shoes|discount-shoes”

This field is used to pass the item category. May be passed pipe delimited if the item has more than one category.

String

items[index].itemHSCode

Example values “3926901000” or “3926.90.1000”

This field is used to pass the item HS code. May be with or without periods.

String

items[index].itemCustomization

This field is used to pass additional details about the item that are not shown in the Zonos Checkout, however can be retrieved through the “orderDetail” API service endpoint.

Additional String Data Types

Discounts, Coupons, and PromoCodes

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 parameter “unitPrice” and “nonShippable”:true.

Example Discount Item Map

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

HTTPS response

Success HTTP response

Message Format JSON

Example Success Response 200

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

Error HTTP responses

HTTP Response Codes Response Body Example/Description
400 - Unexpected character in request body. HTML Entity
406 - Not Acceptable. HTTP header for “Accept” is invalid. HTML Entity
415 - Unsupported media type. HTTP header for “Content-Type” is invalid. HTML Entity
422 - Unprocessable entity. HTML Entity
500 - “storeId” was incorrect or JSON body could not be parsed. HTML Entity

Example error response 422

<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>

Response JSON definitions

tempCartUUID

This parameter will contain a GUID assigned your customer’s international cart created in the Zonos system. String How To Use The tempCartUUID will be passed via URL query string parameter while redirecting the user’s browser to the Zonos Checkout.


Redirecting to the Zonos Checkout

After receiving a successful response containing the tempCartUUID, your server will send a redirect to 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

tempCartUUID

This value is obtained by calling the Zonos createTempCart API service endpoint.

String / GUID

Required

country

Destination country’s 2-digit ISO Code. We highly recommend passing this parameter for user experience. The country parameter will preselect the destination country inside the Zonos Checkout.

When utilizing 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