Overview
Miva Merchant has a XML layer that allows you to perform any action you could do via the admin (add a product, update inventory, update tracking numbers) programmatically via XML tags. These XML tags are referred to as "Miva Provisioning". Typically to make Miva process these XML tags and execute them you would:
- Upload a file to a certain directory with a specific name [OR]
- Import a xml file via Miva native admin import
Now with the Remote Provisioning Module you have access to execute the same XML tags via a http POST/GET
The remote provisioning module handles all the security and authentication as well as management of the Access Tokens (API Keys). Keys can be revoked and anytime and are limited by IP address for security.
Once the Remote Provisioning Module is installed there are two methods to call into Miva.
- XML Request
- SOAP Request
Each request method has a separate URL endpoint and are provided to you by the module, once installed.
Screenshots:
When creating an access token you will give it a name as well as IP restrictions. You will also be required to explicitly give the access token permissions to execute certain XML commands.
For example, if you 3rd party resource will be pushing up new products, then the product_add tag will need to be added to this Store Level access tag.
Access Restrictions:
IP Address – The IP address of the remote system must be added to the allowed IP addresses prior to use
Header Access Token – Each request to push data to Miva Merchant must contain an access key defined by the module. This access token needs to be passed in the header of each request with the following name:
MMProvision-Access-Token
This access token will be created by you after the module is installed.
Tag Restrictions – Each XML tag you wish to process must be explicitly allowed at the store level. This list will be created and provided by Miva during the integration.
Sample Request
Here is a sample request using PHP and Curl. This sample will attempts to create a new product in the store using the Product_Add XML tag.
Notice the Access Token must be passed as a header in the request using the name: MMProvision-Access-Token
The xml_data being passed posted in the request must also contain the
Based on if the command is run or not, and if there are any errors you will get the the following Error Messages as a response (see next section).
Error Handling
Error Handling
There are two statuses for the response.
- error
An error will only occur if access is denied, or the required XML tags are missing. When and status of error is returned that means the XML was never executed.
- processed
Processed means that all validation was passed and the XML was processed by Miva. Only problems will be returned as messages. If a tag gets executed successfully no message is returned.
Responses will always be XML.
Lineno – Line Number of the error in the original XML request
Tag – Tag which was executing when the error occurred
If an error occurs, Miva will log it and move on to the next XML tag. An error does not stop the rest of the XML from executing. Multiple errors will be defined with one error per message tag.
Access Denied Errors
There are two reasons you will get an access denied error. Invalid IP address or Invalid Header value
Invalid IP Address
To fix this issue, make sure you have the externals system public IP address whitelisted in the Remote Provisioning Module.
Invalid Access Header
This issue is fixed by ensuring that you're passing the correct header value of MMProvision-Access-Token which contains the Access Token generated by the remote provisioning module.
Update Order Status
Miva XML Provisioning Tags for creating shipments and marking an order as shipped, with tracking number and carrier information.
Updating order status at the item level in Miva involves two parts. First, you need create a shipment of the products in the order. This can be a single shipment that would contain all products in the order, or you can choose to create a shipment that only contains some of the products in the order.
Create Shipment
The Code tag in the above XML is a unique shipment code for the shipment. If there is only going to be a single shipment for the order, using the order id is recommended. If an order has 2 shipments you would use 1000-1 and 1000-2. However these are only suggestions. If the ERP system as a different way of generating shipment ids for each shipment, then these can be used as well. As long as this code is unique it will be accepted.
Mark Shipment As Shipped
Code – Shipment Code to Mark As shipped. This must match with the code you used in your OrderShipment_Add XML<
MarkAsShipped – 1/Yes
Tracking Number – Tracking Number from Shipping Carrier
Tracking Type – CanadaPost, Endicia, FedEx, UPS, USPS. These values are used to determine the link used in the Shipment Shipped Email.
Ship Date – Date and Time order was shipped.
Depending on the settings setup in Miva for the Shipment Emails, the XML code above will also trigger an Shipment Shipped Email to the customer. This can be turned off if the ERP system needs to send this email.
The two blocks of XML code above does not need to be sent in two separate requests. It can process both functions in a single call.
Backorder Items In an Order
If one or more items are backordered you can mark them as backordered using the following XML. There is a backorder notice email which if set to automatic will also trigger a separate email to the customer letting them know which items are on backorder.
Update Inventory
Miva XML Provisioning Tags for updating inventory counts & messages
Updating inventory in Miva is done though the InventoryProductSettings_Update XML tag. It allows you to update inventory counts as well as inventory settings on a per product basis.
Update Inventory
Product_Code – Miva Product Code of the product to update. If updating an inventory variant, this should be the non-active part product code for the specific variant.
CurrentStock - Total available stock of that product available to sell. This value overwrites any current stock defined in Miva.
All Product Inventory Options
Updated Multiple Products At Once
Update Multiple
CurrentStock Tag
The CurrentStock tag above does NOT take into account inventory in baskets. So if you have 10 products in baskets and you push up inventory of 25, when those baskets expire and are deleted the 10 from baskets will be added to the 25 for a total of 35.
If you want to update inventory and need Miva to include stock in baskets use the following tag:
Note this uses the Basket Inventory Module which must be installed in the store to use this tag.
AdjustStockBy vs CurrentStock
There are two tags to update inventory counts for a product. They cannot be used together in the same request. It is an either or.
Changes To Existing Order
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent nec massa tristique arcu ferme.
Update Customer Assigned To Order
XML
Change Bill To / Ship To
Note
This does not update the customer record. Only the bill to ship to for the order it was applied to.
XML
Remove Charges and Add New
You cannot append to current charges. Any time this charges tag is set up to Miva all existing charges on the order are deleted, the new charges are added and the order total is updated to reflect the new charges.
XML
Recalculate Shipping
XML
Shipping Module - This is the module code of the shipping module to use
Shipping Module Data - This is the Method Name To use when Recalculating shipping
Update Items In Order
Sending the Items tag will delete all existing items on the order and replace them with the new items present in the XML.
The following code allows you to add an item to an order without modifying other items in the order
You can also update a single item in an order if you have its line_id
XML
Possible Values For Status: Pending, Picking, Shipped, Cancelled, Backordered, RMA Issued, Returned
Delete Item From Order By line_id
XML
Update Order Custom Field Value
This code will allow you to change the value of a Custom Order Field for a specific order
XML
Add New Order
Add new order into Miva via API call
This XML allows you to create a new order in Miva explicitly setting the Order ID. The 3rd party system creating the orders will need to ensure the ID field does not overlap with orders generated in Miva
1. Add New Order
XML
Order Custom Fields
HTML
Customers
The following code walks though how to Add / Remove and Update Customer Accounts in Miva via XML Provisioning
Add New Customer
The customer must not currently exists for this to run successfully. The login field must be unique as well as lost customer password email. The password will be encrypted upon import.
XML
Update Customer
The Customer Login field must already exist in Miva. If not, an error will be returned. Not all fields need to be included. Only Fields included in the XML will be updated. All other fields will remain unchanged.
XML
Delete A Customer
XML
Update Custom Customer Fields
customer - login of the customer you wish to update
field - custom field code you wish to update
Any existing value will get replaced with the value passed in the XML tag
XML
Assign Customer To Availability Group
This code allows you to assign a specific customer to an Availability Group
Assign Customer To Availability Group
Remove Customer From Availability Group
XML
Products
This page has the XML to Add, Update and Delete Products
1. Add Product
Product Data is don by multiple XML tags. Most require the basic product record to be created before you can use them.
XML
Note: The thumbnail and fullsizeimage fields above are for the "Legacy Images" and should not be used. They are only there for legacy purposes. Adding Images should be done using the XML below
Alternate Display Page - This is optional and should only be included is you have a specific template you want this product to use.
Canonical Category Code - optional field to all you to specify a default category for this product. This does not assign the product to the category but instead is used to populate breadcrumbs / category tree when no category code is known.
Update Existing Products
All fields are optional in the product update and only fields pass will be updated. Other fields not included in the update will remain unchanged.
XML
Product Delete
XML
Adding Product Images
The actual file must exist on the server for this XML to process. Images can be uploaded via the miva admin, or via FTP. The default path is graphics/00000001/ for images but any path will work. The image type should already exist as well. Unless specified otherwise Miva's root directory is the /mm5/ folder so a relative path is relative to the the /mm5/ folder. The full path to the image below would be:
http://www.domain.com/mm5/graphics/00000001/s2k_silver_front.jpg
XML
Custom Product Fields
Multiple Custom Field Updates can be passed in the same Module tag
XML