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_uri. 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 MZL-d4fcd4c02c88eafaeaef7f87f6796f12

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"
}

Request modifiers

Additional GET parameters might serve as request modifiers. These can be used for sorting, filtering and pagination. See description of the method for request modifiers available to it.

Pagination

Reverse sorting

List methods can use desc parameter with value 1 to swap the default order.

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": "api-1234567890",
    "reference": "fancypost-courier",
    "title": {
        "en": "Fancypost courier",
        "de": "Fancypost Kurierdienst"
    },
    "available_countries_from": ["US", "UK", "DE", "LV", "LT"],
    "available_countries_to": ["US", "UK", "DE", "LV", "LT", "EE", "PL", "FR"],
    "print_label_url": null
}

Add delivery method

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

Parameters

delivery_method - delivery method data, except handle.

Example

Add delivery method:

{
    "delivery_method": {
        "reference": "fancypostcourier",
        "title": {
            "en": "Fancypost courier",
            "de": "Fancypost Kurierdienst"
        },
        "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"
    }
}

Update delivery method

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

Parameters

delivery_method - delivery method data, except handle and checkout_calculate_prices.

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": [
        ...
    ]
}

Supported request modifiers: pagination, reverse sorting.

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",
    "attributes": {
        "delivery_company_id": 3344
    }
}

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 - pickup point data.

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",
        "attributes": ""
    }
}

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

pickup_point - pickup point data, except id.

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

pickup_points - array of pickup point data.
country - optional string. Country code to replace pickup points in the specified country only.
is_initialization - optional boolean, default: true. Start a new list.
is_finalization - optional boolean, default: true. Finish the list and publish the pickup points.

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

Limited to 100 items. Larger lists must be split and uploaded by portions. Set is_initialization: true for the first portion only and set is_finalization: true for the last portion only.

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",
            "attributes": ""
        },
        {
            "id": "LV100002",
            "title": "Smartpost top! Saulieša",
            "address": "Augusta Saulieša iela 2",
            "city": "Cesvaine",
            "zip": "4871",
            "country": "LV",
            "attributes": ""
        }
    ],
    "is_initialization": true,
    "is_finalization": true
}

List configured values of custom fields for delivery provider

POST /store/delivery_provider_settings/ - returns list of custom fields

In case of public delivery provider, returns custom fields and their values as configured in Store settings / Delivery / Integrations for the website that owns the specified order.

Parameters

order_uuid - the universally unique order identifier

Limited to delivery service provider only.

Example return data:

{
    "fields": [
        "field_name": "ABC",
        "some_other_field_name": "DEF"
    ]
}

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, read-only
title - multilanguage text
reference - string, passed as parameter to label printing.
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

Pickup point data structure

id - string, unique identifier
title - multilanguage text
address - string
city - string
zip - string
country - 2-letter ISO country code
attributes - object or empty string. Use attributes to store additional data required for label printing.

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_uuid – the universally unique order identifier
invoice_id – the unique invoice number e.g. M-1234567890-1234567890
delivery_method_handle – handle of the delivery method
delivery_method_name – name of the delivery method
delivery_method_title – title 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 delivery street address, as entered
shipping_city – the delivery city, as entered
shipping_state – the delivery state, as entered
shipping_zip – the delivery postal code, as entered
shipping_country_code – a delivery 2-letter country code, for example, es (Spain), de (Germany)
The following fields are added if different delivery address or pickup point was used:
- buyer_street – the street address of the buyer, as entered
- buyer_city – the city of the buyer, as entered
- buyer_state – the state of the buyer, as entered
- buyer_zip – the postal code of the buyer, as entered
- buyer_country_code – a 2-letter country code of the buyer, for example, es (Spain), de (Germany)
shipping_phone – phone number of the buyer if entered
cart - JSON encoded contents of the shopping cart
weight - a total weight in whole grams
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
signature – signature hash computed on a string resulting in concatenation of your API key and the rest of the POST field data

To obtain values of optional custom fields in case of public integration, use API function /store/delivery_provider_settings/. Custom fields 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.

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
tracking_url – optional tracking URL
signature – signature hash

In case of error, send GET request to callback_url with following parameters:

label_request_id – the same label request id that was received
error_msg – string

Authentication

Getting your API secret key

For private integration, you will find your per-website API key under Store > Store 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:

Create a Mozello account for testing
Contact us for access to Delivery service provider integration setup portal
Submit your integration manifest via Delivery service provider integration setup portal and receive your secret key
Create available delivery methods using API
Submit your integration for approval via Delivery service provider integration setup portal
Upon successful approval, your integration will go live
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

Home