# Malomo.js Reference This is the API reference for Malomo.js. Use Malomo.js' API to retrieve shipment information and build delightful post-purchase experiences for your customers. ### Including Malomo.js However you're using Malomo.js, you always begin by including the library and setting your API key. To get started, include this script on your pages -- it should always be loaded directly from ****: ```javascript ``` ### `Malomo` object #### `Malomo(publishableKey[, options])` Use `Malomo(publishableKey[, options])` to create an instance of the `Malomo` object. Your Malomo publishable key is required when calling this function as it identifies your account. This function accepts an optional `options` object. Available options are documented below: * `url` - the URL used when making API calls. Defaults to `https://api.gomalomo.com`. #### `malomo.elements()` Create pre-built UI components that allow you to add post-purchase elements to any page. #### `malomo.retrieveOrder(query)` Retrieve an `Order` using either it's `id` or `alternate_id`. ```javascript malomo.retrieveOrder({ id: 'ccb71edc-2952-4709-8880-9cb08c26724a' }) .then( function(response) { // Handle response } ); ``` Please note that `metadata` will not be included on `Order` objects when using Malomo.js. This method will return a `Promise` which resolves with a `Response` object. This object contains `body`, `headers` and `status` properties. #### `malomo.fetchOrder()` Retrieve an Order by automatically using values stored as URL query parameters `_m_id` and `_m_alt_id`. If both `_m_id` and `_m_alt_id` are both present then `_m_id` will be used. ```javascript malomo.fetchOrder() .then( function(response) { // Handle response } ); ``` This method will return a `Promise` which resolves with an array of `Response` objects. This object contains `body`, `headers` and `status` properties. ### `Elements` object #### `elements.create(type, options)` Creates an instance of a specific Element. This method takes a `type` of Element to create and an `options` object. **Element `type`** * `shipmentTracker` - renders a complete block that can be used for displaying the status of a shipment **Element `options`** * `classNamePrefix` - a string appended to all CSS class names rendered by an element. Defaults to `malomo`. #### `elements.create('shipmentTracker', options)` Creates an Element that renders a complete shipment tracking experience. \ **Options**

Option	Description
`appearance.theme`	A theme that can be used to style the appearance of Malomo.js. Supported value is `light`.
`order` (required)	The `Order` object provided to this Element.
`carrierInfo.linkToCarrier`	A boolean that determines whether to render a tracking code as text or a link that can take a user to the carriers tracking page.
`carrierInfo.rootClassName`	The class name to use for the root carrier info element. Note that `classNamePrefix` is still applied to the generated class name. Defaults to `carrier-info`.
`carrierInfo.showIf`	A function to determine whether to render carrier information. If the function returns `false` carrier information will not be rendered. If `true` is returned then carrier information will be rendered. An `Order` object will be passed as the first argument and a `Shipment` object as the second argument. Defaults to `true`.
`carrierInfo.showImage`	A boolean that determines whether to render the carrier logo. If `false` the image will not be shown. Defaults to `true`.
`corso.shopId`	A shop id associated with a Corso account. When present this will enable Corso support when rendering the `shipmentTracker` element.
`countdown.minDaysLeft`	An integer indicating when to render a countdown depending on how many days are left until a shipment is delivered. A countdown will not contain a value until the number of days left is equal or less than the value of this options. If a value is not provided then the countdown will always contain a value as long as the number of days left is greater than zero.
`countdown.rootClassName`	The class name to use for the root countdown element. Note that `classNamePrefix` is still applied to the generated class name. Defaults to `countdown`.
`countdown.showIf`	A function to determine whether to render a countdown. If the function returns `false` a countdown will not be rendered. If `true` is returned then a countdown will be rendered. An `Order` object will be passed as the first argument and a `Shipment` object as the second argument. Defaults to `true`.
`deliveryDate.format`	The format the date will be displayed as. Defaults to `EEEE, MMMM d` (e.g. Saturday, February 29). For more information on how to format a date please see date-fn's `format` documentation.
`deliveryDate.rootClassName`	The class name to use for the delivery date root element. Note that `classNamePrefix` is still applied to the generated class name. Defaults to `delivery-date`.
`deliveryDate.showIf`	A function to determine whether to render a delivery date. If the function returns `false` a delivery date will not be rendered. If `true` is returned then a delivery date will be rendered. An `Order` object will be passed as the first argument and a `Shipment` object as the second argument. Defaults to `true`.
`deliveryState.rootClassName`	The class name to use for the delivery state root element. Note that `classNamePrefix` is still applied to the generated class name. Defaults to `delivery-state`.
`deliveryState.showIf`	A function to determine whether to render a delivery state. If the function returns `false` a delivery state will not be rendered. If `true` is returned then a delivery state will be rendered. An `Order` object will be passed as the first argument and a `Shipment` object as the second argument. Defaults to `true`.
`deliveryState.states`	An object containing overrides for the state to display. Defaults are provided below.
`events.dateFormat`	The format of the date to be displayed for each event. Defaults to `MM d` (e.g. February 29). For more information on how to format a date please see date-fn's `format` documentation.
`events.enumerate`	A function that can apply enumeration logic to the events. This is can be used for sorting or filtering out events. An array of events will be passed as the only argument.
`events.rootClassName`	The class name to use for each shipping event root element. Note that `classNamePrefix` is still applied to the generated class name. Defaults to `events`.
`events.showIf`	A function to determine whether to render shipment events. If the function returns `false` then shipment events will not be rendered. If `true` is returned then shipment events will be rendered. An `Order` object will be passed as the first argument and a `Shipment` object as the second argument. Defaults to `true`.
`events.timeFormat`	The format for the time to be displayed for each event. Defaults to `h:mm a` (e.g. 12:00 AM). For more information on how to format a date please see date-fn's `format` documentation.
`returnActions.initiateReturnLinkText`	The text for the "initiate return" link that deep links into the returns platform. Defaults to `Start a return or an exchange`
`returnActions.initiateReturnPromptText`	The prompt text that appears next to the "initiate return" link. Defaults to `Need to make a change?`
`returnActions.relatedReturnsText`	Header text for the "related returns" section. Below that section are all the returns/exchanges related to the current order being tracked. Defaults to `Related Returns`
`returnActions.returnStatusLinkText`	The text for the "Return Status" button that allows customers to view the status of their return. Defaults to `Return Status`
`returnActions.rootClassName`	The class name prefix to use for each element in the "return actions" section. Defaults to `return-actions`
`returnActions.showIf`	A function to determine whether to render the "return actions" section/any returns or exchanges information. If the function returns `false` then the customer will not have an ability to interact with returns or exchanges on the tracking page. Defaults to `true` if the Loop Returns integration is installed correctly, and if at least one shipment from the order has been `delivered`. To remove the requirement for the order to have a `delivered` shipment, you can set the function to: `(order) => { return order.body.return_url; }`
`returnActions.viewOriginalOrderLinkText`	The text for the link back to the original order when viewing a return. Defaults to `View original order`
`statusMessage.messages`	An object containing overrides for the message to display. Defaults are provided below.
`statusMessage.rootClassName`	The class name to use for the status message root element. Note that `classNamePrefix` is still applied to the generated class name. Defaults to `status-message`.
`statusMessage.showIf`	A function to determine whether to render a status message. If the function returns `false` then a status message will not be rendered. If `true` is returned then a status message will be rendered. An `Order` object will be passed as the first argument and a `Shipment` object as the second argument. Defaults to `true`.
`statusMessage.stopOn`	An array of status keys that will only render the provided statuses if they occur in a shipments tracking history. This is useful in situations like `return_to_sender` where it may be more useful to show the end user the `return_to_sender` status message rather than the remaining event statuses as it makes it's way back to the sender. Defaults to `false`.

{% tabs %} {% tab title="HTML" %} ```markup

``` {% endtab %} {% tab title="JavaScript" %} ```javascript let element = elements.create('shipmentTracker', {order: order}); element.mount('#shipment-tracker'); ``` {% endtab %} {% tab title="Result" %} ```markup

Estimated Delivery

Monday, August 2

4 days left

Latest Activity

July 29 3:53 AM

Arrived at USPS Origin Facility

carson

``` {% endtab %} {% endtabs %} **Delivery state defaults** * `noDate` - Check back for an estimated delivery date * `default` - Estimated Delivery * `delivered` - Delivered **Status message defaults** * `unknown` - ready to go * `pre_transit` - ready to go * `in_transit` - on its way * `out_for_delivery` - out for delivery * `delivered` - delivered * `available_for_pickup` - available for pickup * `return to sender` - returning to sender * `failure` - failed to delivery * `cancelled` - cancelled * `error` - error #### `elements.create('orderLookup', options)` Creates an Element that renders a complete order lookup experience. The `orderLookup` element provides a consumer with the ability to lookup their own order. Once an order lookup element is rendered consumer will be able to locate their order by providing either their order number and the email address they made the purchase with or their shipment tracking code. **Options** | **Option** | Description | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `callback` **(required)** | The function used when an order is successfully located. This function will typically be responsible for redirecting a user to a Malomo tracking page. | | `rootClassName` | The class name to use for the root element. Note that `classNamePrefix` is still applied to the generated class name. Defaults to `order-lookup`. | {% tabs %} {% tab title="HTML" %} ```markup

``` {% endtab %} {% tab title="JavaScript" %} ```javascript let classback = function() { let url = new URL(document.URL); url.searchParams.append(`_m_id`, resp.body['id']); window.location.href = url; } let element = elements.create('shipmentTracker', {callback: callback}); element.mount('#order-lookup'); ``` {% endtab %} {% tab title="Result" %} ```markup

We are having trouble locating your order. Please try re-entering your order details. If you haven't received your shipping details yet, it's possible your order is still being fulfilled and you won't be able to track your order yet.

Order Number

Email Address

Tracking Number

``` {% endtab %} {% endtabs %} ### `Element` object #### `element.mount(domElement)` Attaches your Element inside a DOM element. This method accepts a CSS selector (e.g. `#shipment-tracker`), an `HTMLElement` or a `Promise` which resolves with an `HTMLElement`. This method will return a Promise that resolves with the element mounted. You can pass the return value of this method to another mount function to ensure that Element will be mounted in relation to the returned Element. {% tabs %} {% tab title="HTML" %} ```markup

``` {% endtab %} {% tab title="JavaScript" %} ```javascript element.mount('#some-element'); ``` {% endtab %} {% tab title="Result" %} ```markup

Saturday, February 29

``` {% endtab %} {% endtabs %} #### `element.mountAfter(domElement)` Similar to `element.mount(domElement)` but attaches your Element *after* the element specified by `domElement`. {% tabs %} {% tab title="HTML" %} ```markup

Hello, world!

``` {% endtab %} {% tab title="JavaScript" %} ```javascript element.mountAfter('#some-element'); ``` {% endtab %} {% tab title="Result" %} ```markup

Hello, world!

Saturday, February 29

``` {% endtab %} {% endtabs %} #### `element.mountBefore(domElement)` Similar to `element.mount(domElement)` but attaches your Element *before* the element specified by `domElement`. {% tabs %} {% tab title="HTML" %} ```markup

Hello, world!

``` {% endtab %} {% tab title="JavaScript" %} ```javascript element.mountBefore('#some-element'); ``` {% endtab %} {% tab title="Result" %} ```markup

Saturday, February 29

Hello, world!

``` {% endtab %} {% endtabs %}