Requests and Responses

Every request is a POST with a JSON body to the store’s endpoint. Every response, success or error, is JSON.

API Endpoints#

Every store has its own unique API endpoint associated with the domain name. The format will be as follows:

https://www.domain.com/mm5/json.mvc

JSON Request Format#

The Miva JSON API accepts data in JSON format passed in the body of the request. The data sent will be determined by the function you wish to run, and whether you are pushing or pulling data. Please see each function’s specific definition on which json data is needed.

Required JSON Data with Each Request

1. Miva_Request_Timestamp - (Only required for an integration to be listed on the app store) The unix timestamp from when the request was generated. Miva will only run a request in a 30 second window from this time.
2. Store_Code - The Miva store code of the store you wish to execute the function against.
3. Function - The function to execute

Then depending on the function you’re running, it will have its own required json you must pass to get the correct data out or to push the correct data in. See the function reference for every available function.

Binary Encoding Header#

Miva 10 introduces a new optional header which you can pass in API requests to enable you to pass in binary data as the payload. If omitted, json data is assumed.

X-Miva-API-Binary-Encoding: (json,base64)

JSON Response & Error Handling#

All responses to the JSON API, whether it was successful or an error is returned, will be formatted valid JSON.

Success Response

Successful calls return their data as a JSON structure in the following format:

{
    "success": true,
    "data": call-specific data
}

Some success responses will contain additional data. For example, with “OrderItem_Update”, the success response looks like this:

{
    "success": true,
    "data": {
        "total": 19.0,
        "formatted_total": "$19.00"
    }
}

Error Responses#

Errors are returned in the following format:

{
    "success": false,
    "error_code": "unique error code",
    "error_message": "description of error"
}

Required Fields Validation Error#

Some errors will include additional fields with further information about input validation errors:

Example:

{
    "success": 0,
    "error_code": "MER-JSN-00018",
    "error_message": "Invalid value for field 'Product_Weight': Please enter a number",
    "validation_error": true,
    "error_field": "Product_Weight",
    "error_field_message": "Please enter a number"
}

Dates & Times#

All date/time fields in the API will return Unix timestamps. You’ll need convert the unix time to the proper date format depending on your needs.

Client Side Requests#

The JSON API is not able to be used in untrusted client requests via JavaScript/AJAX. This is because doing so will expose your API credentials in the header of each request. There are special API functions intended to be called clientside without an API key needed. Specifics on these coming soon.