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

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.

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

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

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

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:

  1. Create a Mozello account for testing
  2. Submit your integration manifest via Delivery service provider integration setup portal and receive your secret key
  3. Create available delivery methods using API
  4. Submit your integration for approval via Delivery service provider integration setup portal
  5. Upon successful approval, your integration will go live
  6. 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