24/7 Support: 800.608.6482

Get Started

Developer Docs

Getting Started | Miva JSON API

1. API Endpoints

2. Authentication

3. Request Parameters

4. JSON Response & Error Handling

5. Throttling & Timeouts

6. Client Side Requests


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 10.00.00 or greater.


API Endpoints

Every store has its own unique API endpoint tied on 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 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. Run as User - The first option is to run as user. This would inherit the existing privileges as that user. Its strongly recommended you create an “apiuser” and give them the appropriate permissions under Edit Store -> User Groups
  2. 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

The API Access token needs to be passed with each API request as a http parameter with the following name:

API_Token=XXXXXXX


Request Parameters

The Miva JSON API takes name/value pairs for request data and will always return JSON as its output.

Both GET and POST actions will work for the API calls, however it is recommend you always use POST to prevent the API_Token from getting saved in the access logs.

Required Parameters

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


Multi-Value Parameters

Some functions perform operations on list of products. This means you’ll be passing name/value pairs as multi-value lists.

These lists can be passed in 1 of 2 ways

  1. Pipe Delimited List: size|color
  2. Example:

  3. JavaScript Array - Multi-Value Parameters can also be formatted into a JavaScript Array
  4. Example:


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

If the request was successful executed the response will typically look like this:

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


Error Responses

If a request is not successful, an error response will be returned. Anytime an error is returned the success value will always return a 0. The error code and error message will change based on the error being returned. There are two types of error responses.

  1. Standard Error


Required Fields Validation Error

This is returned with one of the required fields for a function is not passed or the value is invalid.

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.

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