24/7 Support: 800.608.6482

Get Started

Developer Docs

JSON API

Getting Started | Miva JSON API

1. API Endpoints

2. Authentication

3. JSON Request Format

4. JSON Response & Error Handling

5. Throttling & Timeouts

6. Client Side Requests

6. Working With Dates & Times


Overview

The Miva JSON API allows any external system to both push data to Miva and pull data from Miva. The JSON API is the same underlying functions as the Miva admin to push and pull data via JavaScript. Any external system that needs to get or push data back to Miva should use the JSON API.


Requirements

To use the Miva JSON API you must be using Miva 9.12.00 or greater.


API Endpoints

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

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

Note: Some stores use an alternate folder name other than "/mm5" such as "Merchant2" or "/store/". You can see what folder structure is being used under Domain Settings -> Site Configuration.


Authentication

Access to the API is determined by an API Access Token. This token is generated in the Miva admin under Users - > API Tokens

It has an IP address restriction as well as user level access control. This determines the functions the API Token can run based on the user it is tied to.

Edit API Token


Allowed IP Addresses:

Each access token is restricted to a list of IP addresses you want to have access to make API calls. It accepts a comma separated list of IPs.

  1. Permit Calls to the Following Functions - This setting gives you the ability to explicitly set which functions the API Token can run. The format is:

store_code:Module:module_code:TemplateOrderEmailList_Load_Query

Syntax Examples

Function Domain-level function
store_code:Function Store-level function
Module:module_code:Function Domain-level module function
store_code:Module:module_code:Function Store-level module function

API Access Token

The API Access token needs to be passed with each API request in the JSON object. While technically the api_token can be passed as a POST/GET parameter the best practice for keeping the token obfuscated is pass it in the body of the request in the JSON data.

Example:


JSON Request Format

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

Required JSON Data with Each Request

  1. API_Token - Token used to access the API. Controls IP restrictions and Access Control
  2. Store_Code - The Miva store code 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 API Function Reference Guide for details on all available functions.


JSON Response & Error Handling

All response 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:

Some success response will contain additional data as well. For example when OrderItem_Update the success response looks like this:


Error Responses

Errors are returned in the following format:.


Required Fields Validation Error

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

Example:


Throttling and Timeouts

API Throttling

There is no throttling we enforce on API requests. To the server it will appear just like any other http request. Miva will process the request and then return the results back to the client. This does mean that the burden is placed on the developer doing any integration to prevent API requests inadvertently causing a Denial Of Service attack because a client made too many API requests.

API Timeouts

The API uses the same timeouts defined the the Miva’s stores mivavm.conf file. These are the global timeouts used across any Miva page for each site. If you need adjust timeouts, it would need to be adjusted for the entire site, not just the API requests. Default timeout in most Miva stores is 60 seconds.

Logging

API requests are not logged separately against regular requests. The server's access logs can be used to help troubleshoot any API related issues.

Client Side Requests

While this API does return data in a JSON format, it is not intended to be used directly in client side (browser) requests via JavaScript. This is because in order to do this the API Access Token would be viewable and not secure. In order to access the Miva JSON API via client side code it is recommended that a middle server side processing layer be used. In this architecture, you can safely obfusicate the API Access token. Your client side code would make AJAX calls to a Miva page (or any server side script) that that script would be what makes the call to the API using MvCALL or simular passing the correct API access token with each request.

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.

This website uses cookies to identify visitors, track visitors to our website, store login session information and to remember your user preferences. By continuing to use this site you agree to our use of cookies. Learn More.

This website uses cookies. By continuing to use this site you agree to our use of cookies. Learn More.

Accept

Miva believes that all online businesses should have access to a scalable ecommerce platform that can meet their unique business requirements. Miva offers PCI compliant ecommerce, hosting, and custom website design and development solutions. Miva customers have processed over $100 billion in online sales since 1997.

Copyright © 2016 Miva, Inc - All Rights Reserved   Privacy Policy | Store Policy

Links
Contact Us
Receive Tips & Updates

Copyright © 2017 Miva, Inc - All Rights Reserved

Back To The Top