Developers

Guides

ARTA Estimates

The ARTA Estimates widget allows you to display non-bookable shipping estimates to your customers during the product discovery phase, in order to give your customers the all-in cost insights they’re looking for. Our mobile-friendly javascript widget is easy to set up and is designed to reduce drop-offs caused by surprise shipping costs further down the conversion funnel.

  • Quick setup — Install in your apps with just a few lines of javascript using the artajs library
  • Performant — ARTA provides estimates across all service tiers in under two seconds on average.
  • Works across devices — mobile friendly layout works well across a wide variety of view ports.
  • Insurance & White Glove Services — estimates will reflect Insurance and white glove services if requested.
  • Global — get cost estimates for shipping across the globe.
Configuration Demo
Visit the ARTA Estimates demo microsite, estimates-demo.arta.io, to preview common layout and presentation configurations.

↗ View demo

ARTA Estimates
ARTA Estimates

Getting started

1. Create a publishable API Key

ARTA Estimates 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 API client 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 Estimates widget.

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 artajs on your site

The Estimates widget is powered by a javascript library called artajs. artajs is semantically versioned and the latest version is 1.0.0.

To install artajs, copy and paste the following snippet before the closing </body> HTML tag on your site. You can include this javascript globally or can just include it on those pages where you want the Estimates widget available for your users (typically on your product pages):

<script src="https://cdn.arta.io/artajs/1.0.0/arta.js"></script>

3. Configure artajs on your site

Once the script above is completely loaded, Arta.configure may be called to validate the API key, object(s), origin destination and other optional settings.

A promise is returned upon successful validation, at which point the UI can be updated (for example, to show or enable an "Estimate Shipping" button).

Minimal configuration object and optional UI interaction upon validation:

<script>
  Arta.configure({
    apiKey: 'YOUR_PUBLISHABLE_API_KEY_TOKEN',
    objects: [
      {
        depth: 2,
        width: 36,
        height: 24,
        subtype: 'painting_unframed',
        unit_of_measurement: 'in',
        weight_unit: 'lb',
        value_currency: 'USD',
        value: 100.0,
        weight: 1
      }
    ],
    origin: {
      address_line_1: '123 Main St',
      city: 'Anytown',
      region: 'NY',
      country: 'US',
      postal_code: '12345'
    }
  }).then((response) => {
    if (response && response.ok) {
      // Arta is ready. Enable the "Estimate Shipping" button (Optional)
    }
  });
</script>

Configuration parameters:

{
  additional_services: array[string], // Optional; an array of ARTA shipping services you'd like to require for the estimates
  apiKey: string, // Required; a publishable API key token associated with your organization
  currency: string, // Optional; alphabetic three-letter code. Defaults to "USD"
  insurance: string, // Optional; the id of an insurance type.
  internal_reference: string, // Optional; this field can be used to pass through any data about the request you may want returned unaltered for your own later usage
  objects: array[object], // Required; array of objects (see example above)
  origin: object, // Required; origin location (see example above)
  position: string, // Optional; defines the placement on the page for the ARTA Estimates modal window; accepts: "right" (default), "center", "left"
  preferred_quote_types: array[string], // Optional; 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"
  pricing_display: string, // Optional; defines how you want estimated prices presented on the results view; accepts: "starts_at" (default), "range"
  public_reference: string // Optional; a client defined name for the resource
}

You may call Arta.configure() multiple times on the same page to change configuration. This is useful if your web site has multiple products displayed on the same page and you would like to configure different products for shipping price estimation.

4. Open the Estimates modal

Now that artajs is configured, you can enable your customers to open the the Estimates modal window by adding an Arta.open() function handler to a user interface element.

<buton onClick="Arta.open()">Estimate Shipping</button>

Provided that the configuration has successfully validated, Arta.open() will open the Estimates modal window in the placement you have configured. The position setting is optional and accepts "right" (default), "center", or "left".

The end user begins their journey by providing the postal code or city + country where they intend to ship the objects.

Once the end user submits their destination information, ARTA will display a range of shipping costs or the lowest option depending on the pricing_display setting you have previously configured. The pricing_display setting is optional and accepts "starts_at" (default) or "range",

The end user can close the widget or provide a new destination address to get updated estimates.

Closing the modal window programattically

The modal window provides a close button, but you may also programmatically call the Arta.close() to close the modal window without any direct user interaction.

← Metadata Endpoints