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, 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 (see example below). API key can be generated from your Mozello account control panel under Catalog > Catalog Settings > API.
Authorization: ApiKey MZL-d4fcd4c02c88eafaeaef7f87f6796f12
Example
Request (raw HTTP)
DELETE /v1/store/product/uid-1234567890/ HTTP/1.1
Host: api.mozello.comSuccess response
{
"error": false
}Error response
{
"error": true,
"error_code": 401,
"error_message": "Unauthorized"
}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"
}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,
"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
}
],
"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"
}Add product
POST /store/product/ - add a product.
Parameters
- product - product data, except pictures.
Product handle is mandatory when creating new product. Only category or category handle can be specified, not both.
Important notes on handling images
For now, image upload is not implemented.
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"
}
}Update product
PUT /store/product/<product-handle>/ - update product.
Parameters
- product - product data, except handle and pictures.
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
For now, image upload is not implemented.
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
- products - array of product data items, except pictures
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
},
"images": [
"https://www.example.com/image-file-1.jpg",
"https://www.example.com/image-file-2.jpg"
],
"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"
}
]
}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 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",
"images": [
"https://www.example.com/image-file-1.jpg",
"https://www.example.com/image-file-2.jpg"
]
}Add category
POST /store/category/ - add a category.
Parameters
- category - category data, except handle and level
Important notes on handling images
For now, image upload is not implemented.
Example
Add category:
{
"category": {
"title": {
"en": "Gadgets",
"lv": "Ierīces"
},
"previous_handle": null,
"parent_handle": "uid-321",
"seo_url": "gadgets"
}
}Update category
PUT /store/category/<category-handle>/ - update category.
Parameters
- category - category data, except handle, level, previous_handle and parent_handle
Important notes on handling images
For now, image upload is not implemented.
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"
}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",
"name": "John Smith",
"company": "Universal Exports LTD",
"vat_id": "LV40001234567",
"company_id": "40001234567",
"email": "johnsmith@exmaple.com",
"phone": "+371 22222222",
"country": "Latvia",
"address": "Summer street 10",
"city": "Riga",
"province": "",
"zip": "LV-1000",
"shipping": {
"country": "Latvia",
"address": "Summer street 10",
"city": "Riga",
"province": "",
"zip": "LV-1000",
},
"notes": "",
"payment_method": "paypal",
"shipping_method": "omniva-latvija",
"currency": "EUR",
"subtotal": 100,
"shipping_price": 10,
"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_price": 50,
"product_sku": "TR-12345",
"product_quantity": 1,
"product_discount": 0
},
{
"product_name": "Sweater",
"product_price": 50,
"product_quantity": 1,
"product_discount": 0
}
],
"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
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",
"PAYMENT_CHANGED",
"PRODUCT_CHANGED",
"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", "PAYMENT_CHANGED", "PRODUCT_CHANGED", "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
"name": "John Smith",
"company": "Universal Exports LTD",
"vat_id": "LV40001234567",
"company_id": "40001234567",
"email": "johnsmith@exmaple.com",
"phone": "+371 22222222",
"country": "Latvia",
"address": "Summer street 10",
"city": "Riga",
"province": "",
"zip": "LV-1000",
"shipping": {
"country": "Latvia",
"address": "Summer street 10",
"city": "Riga",
"province": "",
"zip": "LV-1000"
},
"notes": "",
"payment_method": "paypal",
"shipping_method": "omniva-latvija",
"currency": "EUR",
"subtotal": 100,
"shipping_price": 10,
"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_price": 50,
"product_sku": "TR-12345",
"product_quantity": 1,
"product_discount": 0
},
{
"product_handle": "uid-1234567891",
"product_name": "Sweater, SW-12345",
"product_price": 50,
"product_sku": "SW-12345",
"product_quantity": 1,
"product_discount": 0
}
],
"print_url": "https://www.mozello.com/m/invoice/333444555/"
}
}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"
}
}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,
"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"
}
}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"
}
}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,
"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,
"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"
}
}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"
}
}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"
}Product data structure
Product data used in API calls and notifications. Detailed description of fields.
- handle - string
- category - category path
- category_handle - string or null, category handle
- title - multilanguage text
- description - multilanguage text
- url - multilanguage text
- variants - null or array
- variant_no - number
- option_name1 - multilanguage text
- option_name2 - multilanguage text
- option_name3 - multilanguage text
- option_value1 - multilanguage text
- option_value2 - multilanguage text
- option_value3 - multilanguage text
- price - float
- sale_price - float
- sku - string
- stock - null or integer
- pictures - null or array
- uid - string
- url - string
- price - float
- sale_price - float
- sku - string
- stock - null or integer
- visible - boolean
- featured - boolean
- tax - float
- vendor - string
- model - string
Product category path data structure
Product category path data used in API calls and notifications.
- path - array of multilanguage text. Maximum array length is 2.
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
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"
- name - string
- company - string
- vat_id - string
- company_id - string
- email - string
- phone - string
- country - string
- address - string
- city - string
- province - string
- zip - string
- shipping
- country - string
- address - string
- city - string
- province - string
- zip - string
- notes - string
- payment_method - string
- shipping_method - string
- currency - string
- subtotal - float
- shipping_price - float
- taxes - float
- total - float
- discount_code - string
- discount_amount - float
- cart
- product_handle - string
- product_name - string
- product_variant - array of string
- product_price - float
- product_sku - string
- product_quantity - integer
- product_discount - 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.
Mozello will retry failed notifications for 48 hours.
