Overview

Arta introductions

Arta provides support, insights, and guidance as you build your integration. Once your company’s subscription is in place, you will be introduced to your Client Success Manager and the Solutions team as your key contacts for development. They will provide you with steps to start with Arta, periodically check in during implementation, and complete end-to-end testing before launch.

The first step is to ensure your team’s leaders and developers have Arta Dashboard accounts and Owner permissions. For more on getting started on the Dashboard, visit our solutions page.

Arta will need to enable your account for API access. If you do not see a section for Developers on the left navigation bar, reach out to your Client Success Manager.

Mix and match products

Integrating with Arta can be fully powered by the API or incorporate integrated and no-code solutions. Our Solutions team will be able to provide suggestions on the options best suited for your business.

Arta has built no-code solutions to reduce the technical resources required to launch, which can be used for the entire user journey or for specific stages to complement an API implementation.

The primary reference materials mentioned in this article are:

Client app with all configurations, logs, and shipment management: dashboard.arta.io

Accessible guides and documentation for our solutions and services: manual.arta.io

Technical documentation for our API: api-reference.arta.io

Dashboard for developers

The Arta Dashboard includes a workspace for developers with key elements needed to build, test, and launch an integration.

Test mode

When an Organization is created, it will be in Test mode, Arta’s sandbox. A banner on all of the app pages will indicate which mode you are in. All integration testing should be done in Test mode. When you are ready to launch, contact your Client Success Manager about enabling Live mode.

Test mode has all of the same features as Live mode, including returning the same responses for API calls and webhooks, with one major difference: all service costs will be $1. To see requests with real pricing, reach out to your Client Success Manager.

Test mode supports unique configurations, even after your integration is live to test out new settings. Before launch, ensure your Communications Configurations are set on Live mode.

API Keys

To create a successful call to our API endpoints, you will need API key credentials unique to the Organization you want to create Requests and Shipments for. You can create keys on the Dashboard, under Developers > API Keys. While your account is in Test mode, you can only create Test keys. Once Arta has enabled Live mode, you can create Live mode keys.

There is an option for Publishable or Private keys. If you are using our Estimates widget, you should toggle on Publishable. For all other uses, keep the toggle off.

Logs

Also within the Developers tab are API logs. Every call will be recorded here. From the list view, you can see the status, timestamp, and reference information like the Request or Shipment ID. From the detail view, you can review API key ID, duration, action, and the content of the call and response.

Webhooks

The Dashboard is also where you configure webhooks, read more information on configuring webhook endpoints in this section of our API Reference.

Arta’s webhooks can be used to update your client-facing order or tracking pages with up-to-date shipment information or instigate internal processes (such as alerting warehousing teams a new shipment has been created in your inventory management system).

There is also a tab with the record of all Webhook Deliveries to aid in monitoring and troubleshooting. Learn about all webhook delivery types available.

Dashboard configurations

Within the Dashboard, there are settings for specific Arta features that primarily influence operational processes but can have a significant impact on the work of developers. We have a guide to our Recommended Configurations to help.

Users

Within Organization > Users, clients can add, remove, and edit the permissions of various team members. In order for someone to see the Dashboard, create API keys, or review logs, they will need to be invited to the Organization as an Owner.

Billing

Arta has two options for shipment billing: Terms or Prepaid. Our Client Success Managers or Solutions team will configure the Organization’s billing terms based on your implementation. If your terms are different than expected, reach out to your CSM.

Terms clients are sent an invoice for every booked shipment after the shipment has an ‘In transit’ status. When a shipment is booked, there will be no amount due immediately. Clients processing payments for their customer’s shipping and insurance would typically have Terms and receive invoices from Arta.

Prepaid clients are required to submit payment via credit card to Arta (on our hosted Checkout page) before the shipment will be fulfilled. There will be an Exception and an amount due on every shipment until payment is successfully submitted.

Read an overview and dive into the workflow of each option on our payments page.

Branding

If your company uses any of Arta’s no-code products, consider leveraging Branding for those UIs. Branding enables clients to provide brand continuity to their customers if they are moving between your own interface and Arta’s products. Arta supports brand assets including a logo, custom domains, brand color, and social media accounts. You can review all the optionality under Hosted Products > Branding.

Test mode supports unique Branding configurations.

Emails

Arta’s most commonly used no-code products are our Emails. Clients can configure Email Rules or Subscriptions from the dashboard. Settings are for every Request and Shipment, and Arta will send emails to the configured email address (e.g., Origin Contact, Destination Contact). From each Shipment you can see emails triggered, with delivery status and a permalink to the exact content sent.

Test mode supports unique Email settings.

Customs (ECD)

For Organizations shipping cross-border, Arta has built a feature - Export Customs Documents (ECD) - for intaking data required by customs from the Exporter of Record. Depending on your business, the Exporter of Record may be yourself (the company receiving the primary benefit of selling the object) or a customer (a seller within your marketplace).

If configured, Arta will send an email instructing the exporter to complete a short form, and authorize Arta to use this information with customs. Relevant data provided on the Request or Shipment will be pre-populated. There are fields that are not collected via API at this time, so the options for exporters are to complete the form or as a client you can choose to upload a Commercial Invoice and other required data via the dashboard or API. Learn more about uploading documents via API.

Solutions

Based on your business needs, Arta may recommend a variety of products. Often a mix of no-code and integrated products will provide the quickest to implement and most comprehensive client experience.

To check on the status of Arta’s services, visit: https://status.arta.io/

API

The Arta API is a token-authenticated REST-based API. Arta has intentionally built our API for quick-to-market integrations using easy-to-understand standard HTTP responses and predictable URLs. The API also powers highly complex logistics and provides the customization required for our one-of-a-kind clients.

Endpoints

You can review all of our endpoints within our API Reference site. Each endpoint has specific capabilities, such as creating a request, retrieving metadata lists, or updating email rules. All calls must be authorized with your API Keys for your Organization.

The functionality of the API is also built into the Dashboard, and some actions (such as Create an Email Rules or Update an Organization) are more easily taken in the Dashboard.

Metadata lists will update infrequently over time, but nothing will be removed without a new version of the API. Arta will be in touch with all clients with advanced notice for any planned upgrades, and existing versions will continue to function.

Requests

Creating a Request

The entry endpoint in our shipping services is to Create a Request. The Request includes an origin, destination, and object(s) basic information, and the response from Arta will include available quotes based on that information. All responses from Arta include unique IDs (e.g., Request ID, Quote ID) as well as client-provided references (e.g., Public Reference, Object Public Reference) to aid in reconciling information between our two systems.

One required Object characteristic that is unique to Arta is our concept of Object Types. This is a metadata list of varying object descriptions that we use to understand what kind of object you are shipping, and best determine packaging and transportation options. If you have questions about how to map your data to our Types or have questions about incorporating Types into your inventory management system, reach out to your Client Success Manager and our Solutions team can assist.

Other required information is more standard to the industry (dimensions, value, street address). If you have any questions about data mapping or integrity, Arta is happy to discuss.

A Request can have varying amounts of information about a potential shipment. If early in the customer’s journey you may only have the buyer’s postcode and country, this is still a valid Request. As long as all required information is provided (required fields are highlighted in our API Reference), Arta will create a Request and respond with Quotes.

Status

Requests are returned with a Status, typically “Quoted” which indicates that we have successfully provided rates. Occasionally, Arta will return “Disqualified” which relays that even though the data was valid we are unable to provide instant shipping pricing. When Requests are booked, their status will change to “Closed”. If the Request is more than 30 days old, it will be “Expired” and will no longer be bookable.

Bookable

For calls with limited information, the Requests will be “non-bookable” or estimated shipping costs. When complete information is provided (a complete street address for both locations, contact information, for example), the response will indicate that this Request is bookable.

Quotes

Request responses will likely include multiple Quote Types. Each will have varied Services and in Live mode, pricing. In your call, clients can filter for Preferred Quote Types, request quotes in a specific Currency, or opt in to Insurance, which will be reflected in the quotes in our response. Not all Quote Types are available for every request. Arta provides the service best suited for the shipment. Availability ranges by geography, volume, and value and does change over time.

Many of our customers filter which quotes their customers ultimately see (and simplify into a sum total shipping cost) and brand the Quote Types to match their brand language. We recommend doing this after the API call to see what options are available and react accordingly to avoid requesting only specific types that may not be available.

Shipments

Creating a Shipment

Once there is a bookable Request and a preferred Quote you would like to book, you will Create a Shipment. At this time you can update the Public and Internal Reference if you capture a PO number or unique Invoice number when processing a client’s payment.

Arta’s human-readable unique reference for every shipment is the Shortcode.

Arta advises that the call to Create a Shipment is after you have successfully processed payment for the object and shipping costs (if on Terms) and the object is ready to ship. Once you have created a Shipment, our team is getting to work on fulfillment and will be contacting the origin location regarding release. If there is a delay between the buyer’s payment and the object being ready, you can delay sending the Create a Shipment call for up to 30 days.

Arta’s response for Shipments include a Status, which will update as it moves through the fulfillment lifecycle and eventually delivers at it’s destination.

Shipments will also include the booked Request ID or Hosted Session ID for reference. Shipments will also include the public URL, which can be shared with customers immediately after booking and leads to our Tracking product.

Packages

The shipment response also includes details on the Packages that the object(s) will be packed in for transport. This information can be used to set expectations with customers about how many packages will be arriving, and when.

Each package for Parcel and Self Ship will have tracking details that include carrier (UPS, FedEx, DHL), a tracking number from that carrier and a URL. If you are using another system to share tracking information and send notifications, these details can support that workflow. Arta’s Tracking page also includes all of this information and a branded version of the carrier updates.

Exceptions

Arta provides notices when a shipment is halted from delivery for various reasons, including outstanding payments, customs clearance, and missed deliveries. Using webhooks or the Dashboard Inbox Notifications, your team can be notified of new Exceptions on a Shipment. Exceptions will be added to the Shipment record in real time and can be retrieved with a GET call.

One Exception that may be immediately present on a booked Shipment is the EEI Form. This is the status of the Export Customs Documents (ECD) form required for cross-border shipping.

Using the API for Arta’s Hosted Products

The API also enables clients to create a Booking session or share a Request. Our Hosted Products can also be created via the Dashboard or spreadsheet, so we refer to them as ‘No-Code’. However, using the API to generate these UIs can provide less administrative work, while still providing the out of the box booking experience and automating the transition from your current interface to Arta.

The intended workflow is to process payment for the object(s) sold, and then generate a Hosted session for your buyer, and direct them to Arta to review and book shipping. As Arta will be processing payments, this does require two transactions for the customer.

Booking

Booking does not require destination data, because the workflow anticipates that the buyer will be completing their address and contract information within the UI. Customers are able to edit their delivery information as well within Booking.

Share Request

In a similar call, you can create a session for quote review and booking where the client cannot edit their address or generate multiple sets of quotes. This is similar to a single Request call, with a public facing UI already built for the API response. The client will land immediately on quote review, skipping the address entry page, and be able to proceed with booking and payment.

Share Request is ideal for companies who have already assessed and charged sales tax based on the destination address and do not want to provide customers with the optionality of updating their address after checkout.

Payments

From both Booking and Share Request, customers can select a quote to book and submit payment to Arta via credit card for their shipment. For these workflows Arta recommends your Organization to be Prepaid, so Arta knows to collect payment from the customer before fulfillment. Learn more about Terms versus Prepaid at our payments page.

At this time Arta only accepts payment via major credit card. Customers can provide an email for an emailed receipt, which would need a configured Email Rule.

If a payment fails or a client drops off before submitting payment, the Shipment will be created with a ‘Prepayment Required’ Exception. You can monitor for these in the Dashboard, receiving Inbox Notifications or subscribing to the Action Required email for Exceptions. Arta will not proceed with fulfillment until payment has been received and the Exception resolved.

Tracking

As soon as the Shipment is booked, there is a URL associated to the Shipment. Typically clients direct their customers to this Hosted Product for status updates, estimates delivery date(s), and tracking numbers. From this page clients can also enroll in text updates.

For an integrated post-booking experience, clients can utilize our webhooks and retrieve shipment records for added information on collection and delivery dates, carriers, and exception notices. The webhooks can be used to trigger calls to Arta, update shipment records, and the information you pass to your customers.

Webhooks

As mentioned under Dashboard Configurations, webhooks can be used to update your client facing order or tracking pages with up-to-date shipment information or instigate internal processes. Most commonly, updating shipment status’ on order pages or triggering emails to clients with shipment updates.

Webhook Endpoints will need to be configured within your Organization’s dashboard. Arta has various webhooks that can trigger different actions dependent on your businesses needs and desired customer experience, which are documented in our Manual. If you have questions about how to best utilize this information, please reach out to your Client Success Manager and our Solutions team will be happy to discuss options with you.

Arta will continue to retry your endpoint if there is not a successful receipt with exponential backoff.

Hosted Products

Arta has built pre-sale, checkout, and post-sale user interfaces that can be personalized with your company’s assets to provide a no-code solution that still feels custom to your brand.

Estimates

The Arta Estimates is a mobile-friendly widget that provides a pop-up module for your product page for customers to quickly generate shipping costs before proceeding to checkout.

By providing shipping costs during browsing, customers can understand all-in costs to reduce cart abandonment, and you can better track buyer interest and geography. The widget uses our API to provide the same instant rates for our multiple quote types, with various display configurations.

Arta also provides access to Estimates within our Dashboard. If your company is looking for a back-office tool to get quotes quickly for customers, reach out to your Client Success Manager to learn more. Arta will upload your inventory to enable quoting to delivery destinations worldwide with a few clicks.

Booking

Arta can also host the entire quote generation, review, selection, and payment experience for your customers with Booking. Using an API call or the Dashboard to generate Booking sessions, as the client you would provide the origin location and object details and our UI would do the rest.

The client would land on an address entry form, which can be pre-populated if you have this information, and when they submit the form the customer would be presented with all of Arta’s quotes available for their shipment. The client can edit their address, review quote options, and book their preferred option. Typically for Prepaid organizations, customers will be prompted to submit payment via credit card. With a successful payment, customers will be directed straight to Tracking to monitor their shipment.

Although you are not building the UI for these transactions, you still have full visibility. Clients can see all the rates customers receive, who has selected a quote, and if shipments are booked from your Dashboard or the API.

Tracking

Every Arta shipment has a public Tracking page that provides real time shipment status, estimated delivery day(s), and Exceptions messages. This page supports Branding customization.

The Tracking URL is accessible from the Dashboard or API, and can be surfaced to clients in your UI after checkout, or all Arta Emails link to the unique Tracking page for each shipment.

Tracking and Emails are used by a majority of our clients, so they can focus on their core business (getting the sale!) and not the complex task of updating clients about the status of their shipment through to delivery. Tracking enables customers to register for text updates in addition to existing Email Rules.

Shopify

If you are considering an e-commerce tool for your online storefront or are already hosting your sales on Shopify, Arta has built an app to bring Arta’s shipping and insurance products into your store.

For a complete overview of the app, read our Manual section on Shopify.