This document is a draft / work in progress as this API is still in development. Please contact us, if you would like to begin using this API.

About Delivery API

Mozello Delivery API allows integration of third party delivery, courier and shipping services into Mozello online stores and Mozello platform. There are two types of integration for different use cases:

  • Private integration - you want to use a third party delivery service provider for your own Mozello store
  • Public integration - you represent a delivery service provider and want to offer your service to all Mozello customers

The technology is similar in both use cases, however public integration involves some extra steps and is subject to approval by Mozello, whereas private integration can be done and tested without involvement from Mozello.

Basics

You add one or more delivery methods that can have one or more of the following features:

  • delivery method lists predefined pickup points
  • delivery method can auto-calculate price
  • delivery method is restricted to specific countries
  • delivery method allows printing shipping labels

Mozello store owner can enable any number of these delivery methods for their stores to be used during checkout.

API calls

Basics

The base URL for all API calls is https://api.mozello.com/v1/

API calls are made to the corresponding API URL which, in turn responds with a JSON object. Optional properties might be omitted or returned as null. The returned HTTP status will be 200 for successful or partially successful API calls, and 4XX or 5XX for unsuccessful API calls.

GET, POST, PUT and DELETE HTTP methods are used for standard API methods that perform Get, Create, Update and Delete actions with a resource. POST HTTP method is used for non-standard methods.

List methods that return multiple items implement pagination. These methods take page_size parameter and may return link to the next page as next_page_link. The maximum page size may be limited. HTTP GET method is used for List methods.

Payloads are in JSON format.

For authentication API key must be sent in an HTTP header of each request:

Authorization: ApiKey <api-key>

Example

Request (raw HTTP)

DELETE /v1/store/delivery_method/uid-1234567890/ HTTP/1.1
Host: api.mozello.com

Success response

{
    "error": false
}

Error response

{
    "error": true,
    "error_code": 401,
    "error_message": "Unauthorized"
}

List delivery methods

GET /store/delivery_methods/ - returns list of delivery methods

Limited to delivery service provider or website that owns the delivery methods.

Example return data:

{
    "delivery_methods": [
        ...
    ]
}

Get delivery method

GET /store/delivery_method/<delivery-method-handle>/ - returns delivery method data

Return values

Returns delivery method which corresponds to delivery method data structure. Missing values may be omitted.

Example return data:

{
    "handle": "uid-1234567890",
    "name": "fancypost-courier",
    "title": {
        "en": "Fancypost courier",
        "de": "Fancypost Kurierdienst"
    },
    "phone_required": false,
    "available_countries_from": ["US", "UK", "DE", "LV", "LT"],
    "available_countries_to": ["US", "UK", "DE", "LV", "LT", "EE", "PL", "FR"],
    "print_label_url": null,
    "checkout_url": null,
    "checkout_calculate_prices": false
}

Add delivery method

POST /store/delivery_method/ - add a delivery method.

Parameters

Parameter checkout_url determines whether this is a dynamic delivery method.

Parameter checkout_calculate_prices cannot be changed later.

Example

Add delivery method:

{
    "delivery_method": {
        "name": "fancypostcourier",
        "title": {
            "en": "Fancypost courier",
            "de": "Fancypost Kurierdienst"
        },
        "phone_required": false,
        "available_countries_from": ["US", "UK", "DE", "LV", "LT"],
        "available_countries_to": ["US", "UK", "DE", "LV", "LT", "EE", "PL", "FR"],
        "print_label_url": "https://fancypostservice.com/mozello-delivery-api-print",
        "checkout_url": "https://fancypostservice.com/mozello-delivery-api-checkout",
        "checkout_calculate_prices": false
    }
}

Update delivery method

PUT /store/delivery_method/<delivery-method-handle>/ - update delivery method.

Parameters

Parameter checkout_url can only be changed if it's set to URL to another URL. It can't be set from null to URL or vice versa.

Example

Update delivery method title:

{
    "delivery_method": {
        "title": {
            "en": "Fancypost courier delivery",
            "de": "Fancypost Kurierdienst",
            "lv": "Fancypost kurjera piegāde"
        }
    }
}

Delete delivery method

DELETE /store/delivery_method/<delivery-method-handle>/ - deletes a particular delivery method.

List pickup points of delivery method

GET /store/delivery_method/<delivery-method-handle>/pickup_points/ - returns list of pickup points

Example return data:

{
    "pickup_points": [
        ...
    ]
}

Get pickup point

GET /store/delivery_method/<delivery-method-handle>/pickup_point/<pickup-point-id>/ - returns pickup point

Return values

Returns pickup point which corresponds to pickup point data structure. Missing values may be omitted.

Example return data:

{
    "id": "LV100001",
    "title": "Smartpost Narvesen Bērzpils",
    "address": "Bērzpils iela 1a",
    "city": "Balvi",
    "zip": "4501",
    "country": "LV"
}

Add pickup point

POST /store/delivery_method/<delivery-method-handle>/pickup_point/ - add a pickup point.

You can specify multiple comma separated delivery method handles.

Parameters

Pickup point id must be unique for this delivery method.

Example

Add pickup point:

{
    "pickup_point": {
        "id": "LV100001",
        "title": "Smartpost Narvesen Bērzpils",
        "address": "Bērzpils iela 1a",
        "city": "Balvi",
        "zip": "4501",
        "country": "LV"
    }
}

Update pickup point

PUT /store/delivery_method/<delivery-method-handle>/pickup_point/<pickup-point-id>/ - update pickup point.

You can specify multiple comma separated delivery method handles.

Parameters

Example

Update pickup point title:

{
    "pickup_point": {
        "title": "Smartpost Bērzpils Narvesen"
    }
}

Delete pickup point

DELETE /store/delivery_method/<delivery-method-handle>/pickup_point/<pickup-point-id>/ - deletes a particular pickup point.

You can specify multiple comma separated delivery method handles.

Batch replace pickup points

POST /store/delivery_method/<delivery-method-handle>/pickup_points/batch-replace/ - set all pickup points at once, replacing all existing (if any) for this delivery method.

You can specify multiple comma separated delivery method handles.

Parameters

Each pickup point id must be unique for this delivery method.

Limited to 10000 items.

Example

Batch replace pickup points:

{
    "pickup_points": [
        {
            "id": "LV100001",
            "title": "Smartpost Narvesen Bērzpils",
            "address": "Bērzpils iela 1a",
            "city": "Balvi",
            "zip": "4501",
            "country": "LV"
        },
        {
            "id": "LV100002",
            "title": "Smartpost top! Saulieša",
            "address": "Augusta Saulieša iela 2",
            "city": "Cesvaine",
            "zip": "4871",
            "country": "LV"
        }
    ]
}

API data structures

Multilanguage text data structure

Multilanguage text data is object with language codes as keys and text values in the corresponding language as values. The language codes must be present in the website.

Alternatively, a simple string can be used instead of the text data object if the website only uses a single language or only the value in the default language needs to be modified.

Example

{
    "en": "Memory",
    "fr": "Mémoire"
}

Delivery method data structure

  • handle - string, unique identifier
  • name - string
  • title - multilanguage text
  • phone_required - boolean, set to true if this delivery method must know phone for delivery
  • available_countries_from - array of 2-letter ISO country code. This delivery method will only be available to stores located in these countries
  • available_countries_to - array of 2-letter ISO country code. This delivery method will only be available to shipping destinations in these countries
  • print_label_url - URL if label printing via API enabled, or null
  • checkout_url - URL if dynamic delivery methods via API enabled, or null
  • checkout_calculate_prices - boolean, set to true if checkout_url will calculate delivery prices dynamically

Pickup point data structure

  • id - string, unique identifier
  • title - multilanguage text
  • address - string
  • city - string
  • zip - string
  • country - 2-letter ISO country code

Dynamic delivery methods

You can offer a real-time generated list of delivery methods to customer during checkout based on shipping location, origin location and cart content. During checkout, Mozello will make a request to the specified URL and display the returned delivery methods in the delivery selection of the checkout form.

Property checkout_url must be set to URL hosted on your infrastructure for delivery method to become a dynamic delivery method. If checkout_calculate_prices set to true, then store owner can't set their own price for these delivery methods as they will be automatically calculated by your page.

If dynamic delivery method has pickup points, they are ignored and not used.

During checkout, Mozello will make an HTTP POST request to a predefined URL specified as checkout_url property for delivery method. The POST request will contain the following fields:

  • delivery_method_name – name of the delivery method
  • amount – a total amount, for example, 10.02
  • currency – a 3-letter currency identifier, for example, EUR, USD
  • seller_name – the name of the seller, as specified in store settings
  • seller_id – ID of the seller, as specified in store settings
  • seller_vat – VAT ID of the seller, as specified in store settings
  • seller_address – address of the seller, as specified in store settings
  • seller_country – country of the seller, as specified in site settings
  • shipping_street – the street address of the buyer, as entered
  • shipping_city – the city of the buyer, as entered
  • shipping_state – the state of the buyer, as entered
  • shipping_zip – the postal code of the buyer, as entered
  • shipping_country_code – a 2-letter country code, for example, es (Spain), de (Germany)
  • cart - JSON encoded contents of the shopping cart
  • language_code – a 2-letter user interface language code, for example en (English), lv (Latvian)
  • website_alias – alias name of Mozello website, e.g. supershop (for supershop.mozello.com)
  • website_domain – domain name of the online shop, for example, www.example.com
  • optional custom fields in case of public integration; these come from integration settings form defined in the public integration manifest and filled-in by the particular Mozello online store admin in store delivery settings.
  • signature – signature hash computed on a string resulting in concatenation of your API key and the rest of the POST field data

Return a list of delivery methods that are available for the customer in JSON format:

  • delivery_methods – array of delivery methods
    • title - method title to display. Use language_code to display title in customer's language
    • reference - optional. Will be used for delivery_method_reference field for label printing
    • phone_required - optional. Set to true if phone is required for this delivery method
    • price - required if checkout_calculate_prices property set for delivery metohd. Use currency to return price in the correct currency

Return empty delivery_methods array if none of your delivery methods is applicable.

Maximum server timeout is 10s, the recommended timeout is under 2s for optimal user experience.

Example

Response to dynamic delivery methods request:

{
    "delivery_methods": [
        {
            "title": "Smartpost overnight delivery",
            "price": 8.50
        },
        {
            "title": "Smartpost standard delivery",
            "price": 5.50
        }
    ]
}

Label printing

Developers host pages for creating shipment labels on their own infrastructure. You can host the page anywhere, and build it with the tech stack of your choice.

You can display interface to request any additional or missing information that might be required for printing the shipment label in this page, such as delivery priority, shipment weight, dimensions etc.

Button for printing label will appear for all orders purchased with your delivery method if url to page for printing the label is set as property for delivery method

When Print Label button is pressed, Mozello will make an HTTP POST request to a predefined label printing URL specified as print_label_url property for delivery method.

The POST request will contain the following fields:

  • label_request_id – unique identifier for this label request
  • order_id – a unique, numeric order identifier
  • invoice_id – a unique invoice number e.g. M-1234567890-1234567890
  • delivery_method_name – name of the delivery method
  • delivery_method_reference – reference of the delivery method
  • amount – a total amount, for example, 10.02
  • currency – a 3-letter currency identifier, for example, EUR, USD
  • seller_name – the name of the seller, as specified in store settings
  • seller_id – ID of the seller, as specified in store settings
  • seller_vat – VAT ID of the seller, as specified in store settings
  • seller_address – address of the seller, as specified in store settings
  • seller_country – country of the seller, as specified in site settings
  • shipping_first_name – the first name of the buyer, as entered
  • shipping_last_name – the last name of the buyer, as entered
  • shipping_company – the name of the company, as entered
  • shipping_company_id – the company ID, as entered
  • shipping_company_vat – the company VAT ID, as entered
  • shipping_email – the email address of the buyer, as entered
  • shipping_pickup_point_id – id of pickup point if applicable
  • shipping_street – the street address of the buyer, as entered
  • shipping_city – the city of the buyer, as entered
  • shipping_state – the state of the buyer, as entered
  • shipping_zip – the postal code of the buyer, as entered
  • shipping_country_code – a 2-letter country code, for example, es (Spain), de (Germany)
  • shipping_phone – phone number of the buyer if entered
  • cart - JSON encoded contents of the shopping cart
  • language_code – a 2-letter user interface language code, for example en (English), lv (Latvian)
  • website_alias – alias name of Mozello website, e.g. supershop (for supershop.mozello.com)
  • website_domain – domain name of the online shop, for example, www.example.com
  • callback_url – a URL address to redirect after label is generated or canceled
  • optional custom fields in case of public integration; these come from integration settings form defined in the public integration manifest and filled-in by the particular Mozello online store admin in store delivery settings.
  • signature – signature hash computed on a string resulting in concatenation of your API key and the rest of the POST field data

Display the interface for collecting any additional data if required. Generate label as PDF file. Send a GET request to callback_url with following parameters:

  • label_request_id – the same label request id that was received
  • label_url – url to printable label as PDF file
  • tracking_code – optional tracking code
  • signaturesignature hash

Authentication

Getting your API secret key

For private integration, you will find your per-website API key under Catalog > Catalog settings > API.

For public integration, you will receive your global Mozello API key when signing up via Delivery service provider integration setup portal.

Request signing

Callback requests have to contain digital signature in a signature parameter.

Similarly, POST redirect requests to your label generator URL and checkout URL for dynamic delivery methods will contain digital signature in the signature POST parameter.

Computing signature hash

The signature hash is computed by running a sha256 HMAC hash function on the concatenation of string data of all request data fields except signature.

Pseudo code for generating signature

message = label_request_id + label_url
signature = HMAC_SHA256(message, api_key)

PHP example for generating signature

// prepare data array for POST request
$data = array(
    'label_request_id' => $label_request_id,
    'label_url' => $label_url
);
// generate data string
$message = '';
foreach ($data as $key => $value) {
    if ($key != 'signature') {
        $message = $message . $value;
    }
}
// calculate signature hash and add it to POST data
$data['signature'] = base64_encode(hash_hmac('sha256', $message, $api_key, true));

PHP example for validating received POST data

// generate data string
$message = '';
foreach ($_POST as $key => $value) {
    if ($key != "signature") {
        $message = $message . $value;
    }
}
// calculate signature hash
$signature = base64_encode(hash_hmac('sha256', $message, $api_key, true));
// check if hash matches
if ($signature == $_POST['signature']) {
    // Your code here
}

Considerations

  • You need a web server that will host your integration pages / code
  • HTTPS (SSL) connecton is mandatory

Public integration

Use case

Public integration may be of interest to courier, delivery and shipping companies that want to offer their services to all Mozello customers.

How it works?

The public integration technology and process is very similar to private, individual integration described above, but with the following benefits to the delivery company:

  • Delivery methods of the company are added to the list of available delivery methods for all Mozello users (subject to filtering by country)
  • Any qualified online store on Mozello platform can use the integration

The integration process

Prerequisites:

  • Understanding of this API
  • You need to be an established delivery company

The process:

  1. Create a Mozello account for testing
  2. Contact us for access to Delivery service provider integration setup portal
  3. Submit your integration manifest via Delivery service provider integration setup portal and receive your secret key
  4. Create available delivery methods using API
  5. Submit your integration for approval via Delivery service provider integration setup portal
  6. Upon successful approval, your integration will go live
  7. Update your integration details via Delivery service provider integration setup portal any time

Public integration manifest

Public integration partners will have to submit a structured data manifest (in JSON format) containing information about your platform.

Upon signing up and submitting the manifest, you will receive a global (as opposed to per-website as in private integration) secret key that will be used to compute hashes.

Manifest example

{
    "app_type": "DELIVERY_SERVICE",
    "app_title": "Fancypost",
    "app_vendor": {
        "company_name": "Fancypost Inc",
        "support_email": "support@fancypostservice.com",
        "support_phone": "+1 555 0101 1234",
        "developer_email": "dev@fancypostservice.com"
    },
    "delivery_api_data_fields": [
        {
            "id": "customer_id",
            "title": {
                "en": "Your Customer ID",
                "de": "Ihre Kundennummer"
            },
            "type": "text",
            "required": true
        },
        {
            "id": "api_key",
            "title": {
                "en": "Your Secret Key",
                "de": "Ihre geheimen Schlüssel"
            },
            "type": "password",
            "required": true
        }
    ],
    "delivery_service_info": {
        "info_url": {
            "en": "https://fancypostservice.com",
            "de": "https://fancypostservice.com/de/"
        }
    }
}

Manifest reference

* denotes mandatory fields

  • app_type * - always DELIVERY_SERVICE
  • app_title * - title of delivery service provider, non-localizable string
  • app_vendor * - info about the developer of the integration
    • company_name * - name of company that represent the delivery service provider
    • support_email * - support e-mail
    • support_phone * - support phone number
    • developer_email * - e-mail for informing about critical and breaking API changes
  • delivery_api_data_fields - array of delivery service data field object, this data will be collected from user and passed in POST request to label generator URL
    • id * - field id (form data parameter name)
    • title * - field label, either string or languages object
    • type * - field type - text, password, checkbox, email
    • required - if the field is mandatory
  • delivery_service_info - for display and promotional purposes
    • info_url - either string or languages object