24/7 Support: 800.608.6482

Get Started

Developer Docs

Overview

RPM

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:

1. Sample Request

2. Error Handling

3. Update Order Status

4. Update Inventory

5. Changes to Existing Orders

6. Add New Order

7. Customers

8. Products

  1. Upload a file to a certain directory with a specific name [OR]
  2. 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.

  1. XML Request
  2. SOAP Request

Each request method has a separate URL endpoint and are provided to you by the module, once installed.

Screenshots:

RPM

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.

RPM

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 tags as well as the tags to identify the store which is being updated.

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.

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

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

Basket Inventory

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.

500 - This takes the current stock in Miva and adds 500 to it.

500 - This replaces the existing stock value with 500 ignoring what the previous stock was.

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,ReturnedDelete Item From Order By lind_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

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 © 2016 Miva, Inc - All Rights Reserved

Back To The Top