About Store API

Mozello Store API allows external applications to communicate and exchange data with Mozello online store. You can change product data and stock and you can receive notifications about orders, stock changes and payment status changes.

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/List, Create, Update and Delete actions with a resource. POST HTTP method is used for non-standard methods.

Payloads are in JSON format.

For authentication API key must be sent in an HTTP header of each request (see example below). API key can be generated from your Mozello account control panel under Store > Store settings > API.

Authorization: ApiKey MZL-d4fcd4c02c88eafaeaef7f87f6796f12

Example

Request (raw HTTP)

DELETE /v1/store/product/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_link. The maximum page size may be limited.

Reverse sorting

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

Filtering

List methods can use filter parameter to filter returned items by some field (e.g. created_at, modified_at). The filter parameter value is URL-encoded string in format <field><expression><value>. For an example filter=created_at%3E%3D2022-03-07%2008%3A45%3A10 that decodes to created_at>=2022-03-07 08:45:10.

Allowed expressions: >, <, =, <=, >=, <>.

Example

Request with request modifiers (raw HTTP)

LIST /v1/store/products/?filter=created_at%3E%3D2022-03-07%2008%3A45%3A10&desc=1&page_size=5 HTTP/1.1
Host: api.mozello.com

Response

{
    "error": false,
    "products": []
}

List products

GET /store/products/ - returns list of product data

Example return data:

{
    "products": [
        ...
    ],
    "next_page_uri": "/store/products/?page_size=20&page_start=id:222"
}

Supported request modifiers: pagination, reverse sorting, filtering by created_at, modified_at.

Get product

GET /store/product/<product-handle>/ - returns product data

Return values

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

Example return data:

{
    "handle": "uid-1234567890",
    "category": {
            "path": [
                {
                    "en": "Gadgets",
                    "lv": "Ierīces"
                },
                {
                    "en": "Smartphones",
                    "lv": "Viedtālruņi"
                }
            ]
        },
    "category_handle": "uid-123",
    "title": {
        "en": "Apple iPhone 12 Pro",
        "lv": null
    },
    "description": {
        "en": "A <b>rather good</b> phone.",
        "lv": "<b>Diezgan normāls</b> telefons."
    },
    "url": {
        "en": "apple-iphone-12-pro",
        "lv": null
    },
    "variants": [
        {
            "variant_no": 1,
            "variant_handle": "uid-1024",
            "option_name1": {
                "en": "Memory",
                "lv": "Atmiņa"
            },
            "option_name2": {
                "en": "Color",
                "lv": "Krāsa"
            },
            "option_name3": null,
            "option_value1": "128 GB",
            "option_value2":  {
                "en": "Space Grey",
                "lv": "Space Pelēka"
            },
            "option_value3": null,
            "price": null,
            "sale_price": null,
            "sku": "WHATEVR1",
            "stock": 1
        },
        {
            "variant_no": 2,
            "variant_handle": "uid-1025",
            "option_name1": {
                "en": "Memory",
                "lv": "Atmiņa"
            },
            "option_name2": {
                "en": "Color",
                "lv": "Krāsa"
            },
            "option_name3": null,
            "option_value1": "256 GB",
            "option_value2":    {
                "en": "Pacific Blue",
                "lv": "Klusā Okeāna Zila"
            },
            "option_value3": null,
            "price": null,
            "sale_price": null,
            "sku": "WHATEVR2",
            "stock": 5
        }
    ],
    "pictures": [
        {
            "handle": "uid-100001",
            "url": "https://example.mozfiles.com/phone1.jpg"
        },
        {
            "handle": "uid-100002",
            "url": "https://example.mozfiles.com/phone2.jpg"
        }
    ],
    "price": 100.5,
    "sale_price": 95,
    "sku": null,
    "stock": null,
    "visible": true,
    "featured": false,
    "tax": null,
    "vendor": "Apple",
    "model": "iPhone 12 Pro",
    "weight": 189
}

Add product

POST /store/product/ - add a product.

Parameters

Product handle is mandatory when creating new product. Only category or category handle can be specified, not both.

Important notes on handling images

Use Add product picture to add pictures after you have added the product.

Example

Add product:

{
    "product": {
        "handle": "uid-1234567890",
        "category": {
            "path": [
                {
                    "en": "Gadgets",
                    "lv": "Ierīces"
                },
                {
                    "en": "Smartphones",
                    "lv": "Viedtālruņi"
                }
            ]
        },
        "title": {
            "en": "Apple iPhone 12 Pro",
            "lv": null
        },
        "description": {
            "en": "A <b>rather good</b> phone.",
            "lv": "<b>Diezgan normāls</b> telefons."
        },
        "url": {
            "en": "apple-iphone-12-pro",
            "lv": null
        },
        "variants": [
            {
                "variant_no": 1,
                "option_name1": {
                    "en": "Memory",
                    "lv": "Atmiņa"
                },
                "option_name2": {
                    "en": "Color",
                    "lv": "Krāsa"
                },
                "option_name3": null,
                "option_value1": "128 GB",
                "option_value2":  {
                    "en": "Space Grey",
                    "lv": "Space Pelēka"
                },
                "option_value3": null,
                "price": null,
                "sale_price": null,
                "sku": "WHATEVR1",
                "stock": 1
            },
            {
                "variant_no": 2,
                "option_name1": {
                    "en": "Memory",
                    "lv": "Atmiņa"
                },
                "option_name2": {
                    "en": "Color",
                    "lv": "Krāsa"
                },
                "option_name3": null,
                "option_value1": "256 GB",
                "option_value2":    {
                    "en": "Pacific Blue",
                    "lv": "Klusā Okeāna Zila"
                },
                "option_value3": null,
                "price": null,
                "sale_price": null,
                "sku": "WHATEVR2",
                "stock": 5
            }
        ],
        "price": 100.5,
        "sale_price": 95,
        "sku": null,
        "stock": null,
        "visible": true,
        "featured": false,
        "tax": null,
        "vendor": "Apple",
        "model": "iPhone 12 Pro",
        "weight": 189
    }
}

Update product

PUT /store/product/<product-handle>/ - update product.

Parameters

Only category or category handle can be specified, not both.

Important notes on updating variants

While main product data can be updated partially, specifying separate fields, product variants cannot be updated partially, because they do not have their own product handles. Your options are as follows:

  • Update the product as normal and specify variants parameter which will completely overwrite existing variant data.
  • Use another API - batch_update_by_sku

Important notes on handling images

Use Add product picture and Delete product picture to change pictures for the product.

Example

Update product price:

{
    "product": {
        "price": 100.5,
    }
}

Delete product

DELETE /store/product/<product-handle>/ - deletes a particular product.

Add or update batch of products

POST /store/products/batch_update/ - updates a batch of products

Parameters

Only category or category handle can be specified, not both.

Notes on adding new products

  • Product handle is mandatory when creating new products
  • Use new, unique product handles to add new products

Notes on updating products

  • Either product handle or SKU parameter is mandatory when updating
  • If specified handle exists, corresponding product is updated.
  • If specified handle does not exist, new product is created.
  • If no handle is passed, SKU is used to identify product to be updated.
  • If SKU does not exist or same SKU exists on multiple items, entry is ignored.

Important notes on updating variants

While main product data can be updated partially, specifying separate fields, product variants cannot be updated partially, because they do not have their own product handles. Your options are as follows:

  • Update the product as normal and specify variants parameter which will completely overwrite existing variant data.
  • Use another API - products-update-by-sku

Important notes on handling images

For now, image upload is not implemented. The parameter is shown for future compatibility only. There will certainly be some limitations too. The implementation could work like some image uploader queue in the background.

Example

Add or update products with variants (depending on whether handle exists):

{
    "products": [
        {
            "handle": "uid-1234567890",
            "category": {
                "path": [
                    {
                        "en": "Gadgets",
                        "lv": "Ierīces"
                    },
                    {
                        "en": "Smartphones",
                        "lv": "Viedtālruņi"
                    }
                ]
            },
            "title": {
                "en": "Apple iPhone 12 Pro",
                "lv": null
            },
            "description": {
                "en": "A <b>rather good</b> phone.",
                "lv": "<b>Diezgan normāls</b> telefons."
            },
            "url": {
                "en": "apple-iphone-12-pro",
                "lv": null
            },
            "pictures": [
                "https://www.example.com/image-file-1.jpg",
                "https://www.example.com/image-file-2.jpg"
            ],
            "variants": [
                {
                    "variant_no": 1,
                    "variant_handle": "uid-1024",
                    "option_name1": {
                        "en": "Memory",
                        "lv": "Atmiņa"
                    },
                    "option_name2": {
                        "en": "Color",
                        "lv": "Krāsa"
                    },
                    "option_name3": null,
                    "option_value1": "128 GB",
                    "option_value2":  {
                        "en": "Space Grey",
                        "lv": "Space Pelēka"
                    },
                    "option_value3": null,
                    "price": null,
                    "sale_price": null,
                    "sku": "WHATEVR1",
                    "stock": 1
                },
                {
                    "variant_no": 2,
                    "variant_handle": "uid-1025",
                    "option_name1": {
                        "en": "Memory",
                        "lv": "Atmiņa"
                    },
                    "option_name2": {
                        "en": "Color",
                        "lv": "Krāsa"
                    },
                    "option_name3": null,
                    "option_value1": "256 GB",
                    "option_value2":    {
                        "en": "Pacific Blue",
                        "lv": "Klusā Okeāna Zila"
                    },
                    "option_value3": null,
                    "price": null,
                    "sale_price": null,
                    "sku": "WHATEVR2",
                    "stock": 5
                }
            ],
            "price": 100.5,
            "sale_price": 95,
            "sku": null,
            "stock": null,
            "visible": true,
            "featured": false,
            "tax": null,
            "vendor": "Apple",
            "model": "iPhone 12 Pro",
            "weight": 189
        }
    ]
}

Update price by handle:

{
    "products": [
        {
            "handle": "uid-1234567890",
            "price": 100.5
        }
    ]
}

Update stock or price by sku

POST /store/products/batch_update_by_sku/ - updates price or stock based on SKU. Useful when variants are used as separate products with separate SKUs.

Parameters

  • products - array of SKU items
    • sku - unique, existing SKU
    • price - product or variant price
    • special_price - product or variant special price
    • stock - product or variant stock

Notes on updating products by SKU

  • SKU and one of product or product variant properties are required
  • If SKU does not exist or same SKU exists on multiple items, entry is ignored.
  • Please observe item rate limits when updating multiple products

Example

Update some products or product variants by SKU:

{
    "products": [
        {
            "sku": "SOMESKU1",
            "stock": 5
        },
        {
            "sku": "SOMESKU2",
            "price": 50.55
        }
    ]
}

Delete products

POST /store/products/batch_delete/ - deletes products by handle or SKU.

Parameters

  • products - array of product handles or SKUs
    • handle or sku

Notes on deleting products

  • If handle is specified, product with that handle is deleted
  • If SKU is specified, all products with that SKU are deleted

Example

Delete some products:

{
    "products": [
        {
            "sku": "SOMESKU1"
        },
        {
            "handle": "uid-1234567890"
        }
    ]
}

List product pictures

GET /store/product/<product-handle>/pictures/ - returns list of product pictures

Example return data:

{
    "pictures": [
        {
            "uid": "uid-1234567890",
            "url": "https://site-1234567890.mozfiles.com/files/1234567890/catitems/image1234567890.jpg"
        }
    ]
}

Add product picture

POST /store/product/<product-handle>/picture/ - add a product picture.

Parameters

Example

Add product picture:

{
    "picture": {
        "filename": "greenshirt.jpg",
        "data": "/9j/2wBDAAMCAgICAgMCAgIDAwMDBAYEBAQEBAgGBgUGCQgKCgkICQkKDA8MCgsOCwkJDRENDg8QEBEQCgwSExIQEw8QEBD/yQALCAABAAEBAREA/8wABgAQEAX/2gAIAQEAAD8A0s8g/9k="
    }
}

Delete product picture

DELETE /store/product/<product-handle>/picture/<picture-handle>/ - deletes a particular product picture.

List categories

GET /store/categories/ - returns list of category data

Example return data:

{
    "categories": [
        ...
    ],
    "next_page_uri": "/store/categories/?page_size=20&page_start=id:222"
}

Get category

GET /store/category/<category-handle>/ - returns category data

Return values

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

Example return data:

{
    "handle": "uid-123",
    "title": {
        "en": "Gadgets",
        "lv": "Ierīces"
    },
    "level": 1,
    "previous_handle": null,
    "parent_handle": "uid-321",
    "seo_url": "gadgets",
    "picture": "https://www.example.com/image-file-1.jpg"
}

Add category

POST /store/category/ - add a category.

Parameters

Example

Add category:

{
    "category": {
        "title": {
            "en": "Gadgets",
            "lv": "Ierīces"
        },
        "previous_handle": null,
        "parent_handle": "uid-321",
        "seo_url": "gadgets",
        "picture": {
            "filename": "gadgets.jpg",
            "data": "/9j/2wBDAAMCAgICAgMCAgIDAwMDBAYEBAQEBAgGBgUGCQgKCgkICQkKDA8MCgsOCwkJDRENDg8QEBEQCgwSExIQEw8QEBD/yQALCAABAAEBAREA/8wABgAQEAX/2gAIAQEAAD8A0s8g/9k="
        }
    }
}

Update category

PUT /store/category/<category-handle>/ - update category.

Parameters

Example

Update category:

{
    "category": {
        "title": {
            "en": "Electronics",
            "lv": "Elektronika"
        },
        "seo_url": "electronics"
    }
}

Delete category

DELETE /store/category/<category-handle>/ - deletes a particular category.

Additional conditions

The category must not contain sub-categories. Any products from this category will have their category unassigned.

Move category

POST /store/category/<category-handle>/move/ - move category in category tree.

Parameters

  • category - only parent_handle and previous_handle
    • parent_handle - handle of the new parent or null
    • previous_handle - handle of the sibling category to move after or null

Additional conditions

The operation will fail if invalid move is requested or level constraints are breached.

Example

Move category:

{
    "parent_handle": null,
    "previous_handle": "uid-234"
}

List orders

GET /store/orders/ - returns list of order data

Parameters

  • archived - whether to list archived orders, true, false

Example return data:

{
    "orders": [
        ...
    ],
    "next_page_uri": "/store/orders/?page_size=20&archived=true&page_start=id:222"
}

Supported request modifiers: pagination, reverse sorting, filtering by created_at.

Get order

GET /store/order/<order-number>/ - returns order data

Return values

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

Example return data:

{
    "order_id": "MZ-1234567-123456",
    "created_at": "2020-12-30 15:25:33",
    "payment_status": "pending",
    "dispatched": false,
    "archived": false,
    "name": "John Smith",
    "company": "Universal Exports LTD",
    "vat_id": "LV40001234567",
    "company_id": "40001234567",
    "email": "johnsmith@exmaple.com",
    "phone": "+371 22222222",
    "country_name": "Latvia",
    "country_code": "lv",
    "address": "Summer street 10",
    "city": "Riga",
    "province_code": "",
    "zip": "LV-1000",
    "shipping": {
        "country_name": "Latvia",
        "country_code": "lv",
        "address": "Summer street 10",
        "city": "Riga",
        "province_code": "",
        "zip": "LV-1000",
        "pickup_point_id": ""
    },
    "notes": "",
    "payment_method": "paypal",
    "shipping_method": "omniva-latvija",
    "shipping_tracking_code": "AA111111111111EE",
    "shipping_tracking_url": "",
    "currency": "EUR",
    "subtotal": 100,
    "shipping_price": 10,
    "shipping_tax_inclusive_percent": 21,
    "shipping_tax_exclusive_percent": null,
    "taxes": 23.1,
    "total": 133.1,
    "discount_code": "",
    "discount_amount": 0,
    "cart": [
        {
            "product_handle": "uid-1234567890",
            "product_name": "Trousers, Red, XXL, TR-12345",
            "product_variant": ["Red", "XXL"],
            "product_variant_handle": "uid-1024",
            "product_price": 50,
            "product_price_discounted": null,
            "product_sku": "TR-12345",
            "product_quantity": 1,
            "product_value": 50,
            "weight": 700,
            "tax_inclusive_percent": 21,
            "tax_exclusive_percent": null
        },
        {
            "product_name": "Sweater",
            "product_price": 50,
            "product_price_discounted": null,
            "product_quantity": 1,
            "product_value": 50,
            "weight": 400,
            "tax_inclusive_percent": 21,
            "tax_exclusive_percent": null
        }
    ],
    "print_url": "https://www.mozello.com/m/invoice/333444555/"
}

Update order

PUT /store/order/<order-number>/ - updates order

Parameters

  • order
    • payment_status - new payment status paid, pending or failed
    • archived - new archived status true, false
    • dispatched - new dispatched status true, false. When set to true, order is automatically archived
    • shipping_tracking_code - new delivery tracking code
    • shipping_tracking_url - new delivery tracking URL

Example

Update Order Status:

{
    "order": {
        "payment_status": "paid",
        "archived": false
    }
}

Get store notifications (webhooks)

GET /store/notifications/ - returns configured notifications.

Example return data

{
    "notifications_url": "https://www.example.com/notifications.php",
    "notifications_wanted": [
        "ORDER_CREATED",
        "ORDER_DELETED",
        "PAYMENT_CHANGED",
        "DISPATCH_CHANGED",
        "PRODUCT_CHANGED",
        "PRODUCT_DELETED",
        "STOCK_CHANGED"
    ]
}

Update store notifications (webhooks)

PUT /store/notifications/ - changes notification configuration. Updates or removes the URL to which Mozello sends notifications.

Parameters

  • notifications_url - the new URL or null
  • notifications_wanted - array of notifications to send

Example

Update notifications.

{
    "notifications_url": "https://www.example.com/notifications.php",
    "notifications_wanted": ["ORDER_CREATED", "ORDER_DELETED", "PAYMENT_CHANGED", "DISPATCH_CHANGED", "PRODUCT_CHANGED", "PRODUCT_DELETED", "STOCK_CHANGED"]
}

API notifications

Notifications are sent via HTTPS call and contain data payload in JSON format.

Notifications include specific HTTP headers:

  • X-Mozello-API-Version - API version number
  • X-Mozello-Hash - Hash to verify notification data integrity
  • X-Mozello-Alias - Website alias

Verifying notification authenticity

The X-Mozello-Hash HTTP header should be used to verify whether this HTTPS call is coming from Mozello. The signature hash is computed by running a sha256 HMAC hash function on the entire POST data body.

PHP example for validating received POST data

$signature = base64_encode(hash_hmac('sha256', $post_body, $api_key, true));
// check if hash matches
$headers = getallheaders();
if ($signature === $headers['X-Mozello-Hash']) {
    // Your code here
}

ORDER_CREATED

Triggered when order is created, but before payment is received.

Order corresponds to order data structure. Missing values may be omitted.

Example

{
    "event": "ORDER_CREATED",
    "order": {
        "order_id": "MZ-1234567-123456",
        "created_at": "2020-12-30 15:25:33", // YYYY-MM-DD HH:MM:SS
        "payment_status": "pending", // always pending for ORDER_CREATED
        "dispatched": false,
        "archived": false,
        "name": "John Smith",
        "company": "Universal Exports LTD",
        "vat_id": "LV40001234567",
        "company_id": "40001234567",
        "email": "johnsmith@exmaple.com",
        "phone": "+371 22222222",
        "country_name": "Latvia",
        "country_code": "lv",
        "address": "Summer street 10",
        "city": "Riga",
        "province_code": "",
        "zip": "LV-1000",
        "shipping": {
            "country_name": "Latvia",
            "country_code": "lv",
            "address": "Summer street 10",
            "city": "Riga",
            "province_code": "",
            "zip": "LV-1000",
            "pickup_point_id": ""
        },
        "notes": "",
        "payment_method": "paypal",
        "shipping_method": "omniva-latvija",
        "shipping_tracking_code": "AA111111111111EE",
        "shipping_tracking_url": "",
        "currency": "EUR",
        "subtotal": 100,
        "shipping_price": 10,
        "shipping_tax_inclusive_percent": 21,
        "shipping_tax_exclusive_percent": null,
        "taxes": 23.1,
        "total": 133.1,
        "discount_code": "",
        "discount_amount": 0,
        "cart": [
            {
                "product_handle": "uid-1234567890",
                "product_name": "Trousers, Red, XXL, TR-12345",
                "product_variant": ["Red", "XXL"],
                "product_variant_handle": "uid-1024",
                "product_price": 50,
                "product_price_discounted": null,
                "product_sku": "TR-12345",
                "product_quantity": 1,
                "product_value": 50,
                "weight": 700,
                "tax_inclusive_percent": 21,
                "tax_exclusive_percent": null
            },
            {
                "product_handle": "uid-1234567891",
                "product_name": "Sweater, SW-12345",
                "product_price": 50,
                "product_price_discounted": null,
                "product_sku": "SW-12345",
                "product_quantity": 1,
                "product_value": 50,
                "weight": 400,
                "tax_inclusive_percent": 21,
                "tax_exclusive_percent": null
            }
        ],
        "print_url": "https://www.mozello.com/m/invoice/333444555/"
    }
}

ORDER_DELETED

Triggered when order is deleted manually.

Order corresponds to order data structure. Missing values may be omitted.

Example

See example from ORDER_CREATED.

PAYMENT_CHANGED

Triggered on payment status change either manual or automatic.

Order corresponds to order data structure. Missing values may be omitted.

Example

{
    "event": "PAYMENT_CHANGED",
    "order": {
        // full order data for convenience with the new payment status
        "payment_status": "paid"
    }
}

DISPATCH_CHANGED

Triggered on dispatch status change.

Order corresponds to order data structure. Missing values may be omitted.

Example

{
    "event": "DISPATCH_CHANGED",
    "order": {
        // full order data for convenience with the new payment status
        "dispatched": true
    }
}

PRODUCT_CHANGED

Triggered when product data has been changed manually by an operator. Does not happen upon product import.

Product corresponds to product data structure. Missing values may be omitted.

Example

{
    "event": "PRODUCT_CHANGED",
    "product": {
        "handle": "uid-1234567890",
        "category": {
            "path": [
                {
                    "en": "Gadgets",
                    "lv": "Ierīces"
                },
                {
                    "en": "Smartphones",
                    "lv": "Viedtālruņi"
                }
            ]
        },
        "category_handle": "uid-123",
        "title": {
            "en": "Apple iPhone 12 Pro",
            "lv": null
        },
        "description": {
            "en": "A <b>rather good</b> phone.",
            "lv": "<b>Diezgan normāls</b> telefons."
        },
        "url": {
            "en": "apple-iphone-12-pro",
            "lv": null
        },
        "variants": [
            {
                "variant_no": 1,
                "variant_handle": "uid-1024",
                "option_name1": {
                    "en": "Memory",
                    "lv": "Atmiņa"
                },
                "option_name2": {
                    "en": "Color",
                    "lv": "Krāsa"
                },
                "option_name3": null,
                "option_value1": "128 GB",
                "option_value2":  {
                    "en": "Space Grey",
                    "lv": "Space Pelēka"
                },
                "option_value3": null,
                "price": null,
                "sale_price": null,
                "sku": "WHATEVR1",
                "stock": 1
            },
            {
                "variant_no": 2,
                "variant_handle": "uid-1025",
                "option_name1": {
                    "en": "Memory",
                    "lv": "Atmiņa"
                },
                "option_name2": {
                    "en": "Color",
                    "lv": "Krāsa"
                },
                "option_name3": null,
                "option_value1": "256 GB",
                "option_value2":    {
                    "en": "Pacific Blue",
                    "lv": "Klusā Okeāna Zila"
                },
                "option_value3": null,
                "price": null,
                "sale_price": null,
                "sku": "WHATEVR2",
                "stock": 5
            }
        ],
        "price": 100.5,
        "sale_price": 95,
        "sku": null,
        "stock": null,
        "visible": true,
        "featured": false,
        "tax": null,
        "vendor": "Apple",
        "model": "iPhone 12 Pro",
        "weight": 189
    }
}

Example without variants

{
    "event": "PRODUCT_CHANGED",
    "product": {
        "handle": "uid-1234567890",
        "category": {
            "path": [
                {
                    "en": "Gadgets",
                    "lv": "Ierīces"
                },
                {
                    "en": "Smartphones",
                    "lv": "Viedtālruņi"
                }
            ]
        },
        "category_handle": "uid-123",
        "title": {
            "en": "Apple iPhone 12 Pro 256 GB Space Grey",
            "lv": null
        },
        "description": {
            "en": "A <b>rather good</b> phone.",
            "lv": "<b>Diezgan normāls</b> telefons."
        },
        "url": {
            "en": "apple-iphone-12-pro-256-gb-space-grey",
            "lv": null
        },
        "variants": null,
        "price": 100.5,
        "sale_price": 95,
        "sku": "WHATEVR1",
        "stock": 5,
        "visible": true,
        "featured": false,
        "tax": null,
        "vendor": "Apple",
        "model": "iPhone 12 Pro 256 GB Space Grey",
        "weight": 189
    }
}

STOCK_CHANGED

Triggered when product stock has changed in Mozello for products that use this feature. Does not happen upon product import.

Product corresponds to product data structure. Missing values may be omitted.

Example

{
    "event": "STOCK_CHANGED",
    "product": {
        "handle": "uid-1234567890",
        "category": {
            "path": [
                {
                    "en": "Gadgets",
                    "lv": "Ierīces"
                },
                {
                    "en": "Smartphones",
                    "lv": "Viedtālruņi"
                }
            ]
        },
        "category_handle": "uid-123",
        "title": {
            "en": "Apple iPhone 12 Pro",
            "lv": null
        },
        "description": {
            "en": "A <b>rather good</b> phone.",
            "lv": "<b>Diezgan normāls</b> telefons."
        },
        "url": {
            "en": "apple-iphone-12-pro",
            "lv": null
        },
        "variants": [
            {
                "variant_no": 1,
                "variant_handle": "uid-1024",
                "option_name1": {
                    "en": "Memory",
                    "lv": "Atmiņa"
                },
                "option_name2": {
                    "en": "Color",
                    "lv": "Krāsa"
                },
                "option_name3": null,
                "option_value1": "128 GB",
                "option_value2":  {
                    "en": "Space Grey",
                    "lv": "Space Pelēka"
                },
                "option_value3": null,
                "price": null,
                "sale_price": null,
                "sku": "WHATEVR1",
                "stock": 0
            },
            {
                "variant_no": 2,
                "variant_handle": "uid-1025",
                "option_name1": {
                    "en": "Memory",
                    "lv": "Atmiņa"
                },
                "option_name2": {
                    "en": "Color",
                    "lv": "Krāsa"
                },
                "option_name3": null,
                "option_value1": "256 GB",
                "option_value2":    {
                    "en": "Pacific Blue",
                    "lv": "Klusā Okeāna Zila"
                },
                "option_value3": null,
                "price": null,
                "sale_price": null,
                "sku": "WHATEVR2",
                "stock": 5
            }
        ],
        "price": 100.5,
        "sale_price": 95,
        "sku": null,
        "stock": null,
        "visible": true,
        "featured": false,
        "tax": null,
        "vendor": "Apple",
        "model": "iPhone 12 Pro",
        "weight": 189
    }
}

Example without variants

{
    "event": "STOCK_CHANGED",
    "product": {
        "handle": "uid-1234567890",
        "category": {
            "path": [
                {
                    "en": "Gadgets",
                    "lv": "Ierīces"
                },
                {
                    "en": "Smartphones",
                    "lv": "Viedtālruņi"
                }
            ]
        },
        "category_handle": "uid-123",
        "title": {
            "en": "Apple iPhone 12 Pro 256 GB Space Grey",
            "lv": null
        },
        "description": {
            "en": "A <b>rather good</b> phone.",
            "lv": "<b>Diezgan normāls</b> telefons."
        },
        "url": {
            "en": "apple-iphone-12-pro-256-gb-space-grey",
            "lv": null
        },
        "variants": null,
        "price": 100.5,
        "sale_price": 95,
        "sku": "WHATEVR1",
        "stock": 0,
        "visible": true,
        "featured": false,
        "tax": null,
        "vendor": "Apple",
        "model": "iPhone 12 Pro 256 GB Space Grey",
        "weight": 189
    }
}

PRODUCT_DELETED

Triggered when has been deleted manually by an operator.

Product corresponds to product data structure. Missing values may be omitted.

Example

See example from PRODUCT_CHANGED.

API data structures

API options structure

API options allow to control some behavior when calling API functions.

  • text_update_mode - "overwrite", "merge". The default is overwrite.
    This flag controls how multilanguage text field is updated during UPDATE operation in cases when some languages are omitted in multilanguage text parameter.
    • overwrite - texts in all languages of the multilanguage field are cleared and replaced by the multilanguage text parameter.
    • merge - the languages present in the multilanguage text parameter are updated and the languages omitted from the multilanguage text parameter are not changed.

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

Picture data structure

Picture data used in API calls when adding or replacing image. Will not be returned when List, Get used.

  • filename - string
  • data - string, base64 encoded image file

Product data structure

Product data used in API calls and notifications. Detailed description of fields.

Product category path data structure

Product category path data used in API calls and notifications.

Category data structure

Category data used in API calls and notifications.

  • handle - string
  • title - multilanguage text
  • level - integer 1..3
  • previous_handle - string or null, handle of previous sibling
  • parent_handle - string or null, handle of parent sibling
  • seo_url - string
  • picture - category picture when adding or updating category or image URL when returning category data.

Order data structure

Order data used in API calls and notifications. Detailed description of fields.

  • order_id - string
  • created_at - date
  • payment_status - "paid", "pending", "failed"
  • dispatched - boolean
  • archived - boolean
  • name - string
  • company - string
  • vat_id - string
  • company_id - string
  • email - string
  • phone - string
  • country_name - string (English name)
  • country_code - string (2 letter ISO code)
  • address - string
  • city - string
  • province_code - string
  • zip - string
  • shipping - can be null if shipping address not set
    • country_name - string (English name)
    • country_code - string (2 letter ISO code)
    • address - string
    • city - string
    • province_code - string
    • zip - string
    • pickup_point_id - string
  • notes - string
  • payment_method - "cash", "wire", "paypal" or "gateway"
  • payment_method_details - string, gateway name
  • shipping_method - string
  • shipping_method_details - string
  • shipping_tracking_code - string
  • shipping_tracking_url - string
  • currency - string
  • subtotal - float
  • shipping_price - float
  • shipping_price_original - float, shipping price before discount
  • shipping_tax_inclusive_percent - null or float
  • shipping_tax_exclusive_percent - null or float
  • taxes - float
  • total - float
  • discount_code - string
  • discount_amount - float
  • cart
    • product_handle - string
    • product_name - string
    • product_variant - null or array of string
    • product_variant_handle - null or string
    • product_price - float, price as ordered
    • product_price_original - float, price before discount
    • product_sku - string
    • product_quantity - whole number
    • weight - null or whole number, weight in grams
    • tax_inclusive_percent - null or float, item tax rate (tax inclusive)
    • tax_exclusive_percent - null or float, item tax rate (tax exclusive)
  • taxes_details - summary of taxes
    • title - string
    • tax_amount - float
    • tax_percent - float
  • print_url - string/url

Rate limits and failures

When sending product updates, please do not send more than 1000 items at a time.

Do not send more than 5 API requests per second. Also, anything over 300 requests per minute will result in temporary Access Denied 403 status. Please contact us, if you need more.

Mozello will retry failed notifications for 48 hours.