The Arta Estimates widget

Arta Estimates is a mobile-friendly widget enabling you to present dynamic shipping estimates for your customers on your own site. Easy to setup with a low-code SDK, Estimates is designed to help you improve conversion by avoiding shipping cost-related surprises in your checkouts.

Estimates can be added to your Shopify stores and custom websites in minutes.

Features

Built on top of Arta’s TypeScript client SDK, arta-browser, Estimates’ pre-built user interface can be extensively customized and is easy to set up.

You just provide the origin location, object details, and a few optional configurations and the arta-browser SDK will do the rest.

Buyers quickly add their postal code or city and can see non-bookable shipping estimates for the products they’re interested in.

Quick Setup – Install in your apps with just a few lines of JavaScript using the arta-browser SDK
Performant – On average, Arta provides estimates across all service tiers in just a few seconds
Works across devices – Features a mobile-responsive design that works well across a variety of viewports
Configurable –
- Estimates will reflect insurance and white-glove services if requested
- Use custom colors and fonts to match your brand
- Customize all text served to your customers
- Control where the widget opens on the screen
- Show prices as a range or just reveal the lowest cost
Global – Get cost estimates for shipping across the globe

Demo & key links

Estimates demo app – an interactive preview of common layout and presentation configurations

arta-browser on GitHub

arta-browser on NPM

Getting started

1. Create a publishable API Key

arta-browser requires a publishable API Key token to run on your site.

Arta API Keys are either publishable or private. Private API keys have access to the full breadth of the Arta API and must be kept secret and used exclusively with server-to-server API calls. Publishable API keys have access to a limited set of API endpoints and are safe to include in your front-end client applications.

You may manage API keys with the Arta dashboard or through the API itself. For our walk through, we’ll create the publishable key via the API.

Using a private key associated with your organization, perform an API call to “the Create an API Key” endpoint to generate a publishable API key for your organization.

curl \
 -X POST https://api.arta.io/api_keys \
 -H "Content-Type: application/json" \
 -H "Authorization: Arta_APIKey s0e1t2e3c4a5s6t7r8o9n10o11m12y" \
 -d '{"api_key":{"is_public":true}}'

This will create a new, publishable API key and return the token to be used in configuring the arta-browser SDK.

Note that you can optionally also generate publishable test mode API keys and use those with the Estimates widget. When using a test-mode API key token, all estimates will return test-mode pricing as described in the API testing guide.

2. Install arta-browser on your site

The Estimates widget is powered by a JavaScript/TypeScript SDK called arta-browser.

You can install arta-browser with a <script> tag using a free CDN network or as a package through npm.

Installing with a <script> tag

arta-browser is distributed via the jsDelivr Content Delivery Network (CDN). To install arta-browser via the CDN, copy and paste the following snippet before the closing </body> HTML tag wherever you want the Estimates widget available for your users (typically on your product pages):

<script src="https://cdn.jsdelivr.net/npm/@artaio/arta-browser@latest/dist/bundle.js"></script>

And once the above script is loaded the Arta object should be available and you can proceed to “Basic usage” below.

Installing with as a package via npm

Alternatively you install the @artaio/arta-browser package in your JavaScript and TypeScript applications using the npm package manager.

In your project, install the package with

npm install @artaio/arta-browser

And you can then import the Arta object in your project’s files

import Arta from "@artaio/arta-browser";

Basic usage

Once arta-browser is installed, you’ll need to configure the library with the API key you generated in step 1 above.

For example, if you have used the npm distribution strategy above,

import Arta from "@artaio/arta-browser";

Arta.init("<YOUR_API_KEY>");

Then, we’ll initialize an instance of the Estimates widget using the estimate function with an origin location and a list of objects.

const objects = [
  {
    height: 24,
    subtype: "painting_unframed",
    unit_of_measurement: "in",
    value_currency: "USD",
    value: 100.0,
    weight: 2,
    weight_unit: "lb",
    width: 36,
  },
];

const origin = {
  address_line_1: "87 Richardson St",
  city: "Brooklyn",
  region: "NY",
  country: "US",
  postal_code: "11249",
};

const requestSettings = {
  origin,
  objects,
};

const estimate = Arta.estimate(requestSettings);

The estimate function can optionally receive a second argument with additional configuration settings, but we’ll skip that for now.

The next step is to validate the Estimates instance we’ve just configured. The validate function is required and checks the object details, origin parameters, and any additional settings for correctness

A promise is returned and, upon successful validation, your user interface can be updated (for example, to show or enable an “Estimate Shipping” button). Lets use this isReady attribute on the estimate instance to determine whether or not to display a button that triggers the opening of the Arta Estimates widget.

await esimate.validate();

// estimate.open() will render the widget
esimate.isReady && <Button onClick={() => estimate.open()}>Estimate Shipping</button>

Calling the open function in the example above will render the widget on the page.

Clicking the close button on the Arta Estimates interface will automatically close the widget, but you may also close it programatically using the close function.

estimate.close();

Configuration options

The Arta Estimates widget provides a broad set of possible configurations. You can customize the colors, currency, insurance settings, position, the modal’s size, and more.

The estimate function receives two potential arguments. The first argument defines settings related to the shipping quote requests you’ll generate in the Estimates widget. The second argument defines settings related to the presentation and text of the widget itself.

For reference, you can find the full list of configuration types and their accepted values in in the SDK’s types files.

Request settings

The request settings argument supports a number of optional configurations beyond the required objects and origin fields. Typically, setting these will modify the shipping quote requests generated by the widget. Here are a few of the primary request settings you can configure:

additional_services – an array of Arta shipping services you’d like to require for the estimates
currency – alphabetic three-letter code; accepts one of: “CAD”, “EUR”, “CHF” ,”GBP”, “HKD”, “USD” (default)
insurance – the ID of an insurance type; for example, ‘arta_transit_insurance’
preferred_quote_types – defines the Arta quote types you would like returned in your Arta Estimates session; when not present Arta will attempt to return estimates for all quote types; accepts any combination of the following: “parcel”, “select”, “premium”, or “self_ship” (if enabled for your Arta organization)
public_reference – enables you to define a label for the requests that we’ll generate in the Estimates widget; this may be useful when you want to quickly find estimates in the Arta Dashboard with a reference ID that points to orders or products in your own systems

Widget configuration

The arta-browser SDK also enables you to extensively configure the presentation of the Arta Estimates widget. These settings do not impact the shipping quote requests themselves, but provide control over color, placement, how prices are communicated, and the copy text throughout the widget.

Within the style namespace:

color – an object defining the color of elements on Estimates widget; this includes various states of backgrounds, borders, buttons, and text; you can view the full list of options in the types file
fontFamily – defines the font family to be used in rendering the text in the modal window
position – defines the placement on the page for the modal window to be rendered on the page; accepts: “right” (default), “center”, “left”
pricing_display – defines how you want estimated prices presented on the results view; accepts: “starts_at” (default), “range”

Within the text namespace:

detailOriginLabel – defines the label placed next to the origin location in the modal; defaults to (origin)
detailDestinationLabel – defines the label placed next to the destination location in the modal; defaults to (destination)
header.title – defines the title presented in the modal’s header; defaults to Estimate Shipping Costs

You can view the full list of text options in the types file.

Here’s a full example highlighting some of the optional settings. It specifies that shipping estimate prices should be in Euros. Additionally, it sets the Estimates widget to be centered in the view and to have a blue color for the hover state of the primary button.

import Arta from '@artaio/arta-browser';

Arta.init('<YOUR_API_KEY>');

const objects = [
  {
    height: 24,
    subtype: "painting_unframed",
    unit_of_measurement: "in",
    value_currency: "USD",
    value: 100.0,
    weight: 2,
    weight_unit: "lb",
    width: 36,
  },
];

const origin = {
  address_line_1: "87 Richardson St",
  city: "Brooklyn",
  region: "NY",
  country: "US",
  postal_code: "11249",
};

const requestSettings = {
  origin,
  objects,
  currency: "EUR",
};

const widgetConfig = {
  style: {
    color: {
      buttonBackgroundHover: "#0000FF",
    },
    position: "center",
    pricingDisplay: "range",
  },
  text: {
    header: {
      title: "Estimate shipping",
    },
  },
};

const estimate = Arta.estimate(requestSettings, widgetConfig);

await esimate.validate();

esimate.isReady && <Button onClick={() => estimate.open()}>Estimate Shipping</button>

Dashboard Estimates

Estimates