Getting Started

A wrapper class library (DLL) is available for .NET clients to make working with the API much easier. If you do not wish to use the provided wrapper then you should read the Using Raw Requests for API Access article instead of this getting started guide.

Step 1: Get the Wrapper

The wrapper DLL is named MerchantTribe.CommerceDTO.dll and can be found in the /bin folder of your MerchantTribe store. If you're hosted with MerchantTribe and don't have the DLL you can get it from the github.com source code repository. The source code for MerchantTribe and the wrapper are both available at github.com/mmcconnell1618/MerchantTribe. The wrapper source code is located in the /App/src/MerchantTribe.CommerceDTO folder on GitHub.

Step 2: Reference the Wrapper

Start a new project in Visual Studio (or use an exsiting one). A console application is an easy way to get started. Right-click on the project in the Solution Explorer menu and choose "Add Refernce" and select the MerchantTribe.CommerceDTO.dll file that you copied or downloaded in step 1.

Step 3: Create a Client Api Helper

To get started you'll need to create an instance of the client API wrapper. You'll use this class to make all API calls. It requires the URL of your store and an API key as parameters. Add a "Using" (C#) or "Import" (VB.NET) statement to the top of your project's main file for the main namespace and the client api namespace:

using MerchantTribe.CommerceDTO;
using MerchantTribe.CommerceDTO.v1.Client;

Next, create the instance of the client API

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using MerchantTribe.CommerceDTO;
using MerchantTribe.CommerceDTO.v1.Client;

namespace ClientApiTest
{
    class Program
    {
        static void Main(string[] args)
        {
            Api api = new Api("http://localhost", "{My Key Goes Here}");
        }
    }
}

Step 4: Do Something Cool with the API

That's all you really need to do to get setup with the API. Now it's up to you to do something cool. Let's walk through some examples. First, we'll create a new category on our store.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using MerchantTribe.CommerceDTO;
using MerchantTribe.CommerceDTO.v1.Client;

namespace ClientApiTest
{
    class Program
    {
        static void Main(string[] args)
        {
            Api api = new Api("http://localhost", "{My Key Goes Here}");

            // Create a DTO object to create your new category
            MerchantTribe.CommerceDTO.v1.Catalog.CategoryDTO myCategory
                = new MerchantTribe.CommerceDTO.v1.Catalog.CategoryDTO();

            // Set some properties on the category
            myCategory.Name = "My New Category";
            myCategory.Description = "My New Category Description";
            myCategory.RewriteUrl = "my-new-category";
            
            // Create the Category
            var createResponse = api.CategoriesCreate(myCategory);

            // Check for Errors
            if (createResponse.Errors.Count > 0)
            {
                // Write out errors if any
                foreach (var error in createResponse.Errors)
                {
                    Console.WriteLine("Error: " + error.Description 
                                      + " | " + error.Code);
                }
            }
            else
            {
                // No errors, write out the new ID (bvin) of the category
                Console.WriteLine("New Category Created with ID of " 
                                    + createResponse.Content.Bvin);
            }
        }
    }
}

The example code above shows the full code to create a new client wrapper for the API, Create a Category, and Check to make sure it was created without errors. If you're comfortable writing .NET code then working with the API wrapper should be just like working with any other .NET class library. You don't need to know anything about REST, HTTP, etc.

For the next few examples we're going to show just the new lines of code instead of the entire listing. We're also going to skip checking the errors to make the code easier to read. In practice you probably want to create a helper function that checks the error count and is responsible for logging and alerting you to any errors.

First, we'd like to get back a list of all the categories in the store.

// List out all categories
var listResponse = api.CategoriesFindAll();

Console.WriteLine("Categories in Store:");
foreach (var category in listResponse.Content)
{
    Console.WriteLine(category.Name);
}

Next we'll update the category that we first created by setting it's source type to manual. This lets the merchant select which products belong to the category.

// Get the created category so that we can update
MerchantTribe.CommerceDTO.v1.Catalog.CategoryDTO toUpdate
    = createResponse.Content;
toUpdate.SourceType 
    = MerchantTribe.CommerceDTO.v1.Catalog.CategorySourceTypeDTO.Manual;
var updateReponse = api.CategoriesUpdate(toUpdate);

We haven't created any products yet so let's create a very simple item so that we have something to add to the category

// Create a simple product
MerchantTribe.CommerceDTO.v1.Catalog.ProductDTO myProduct
    = new MerchantTribe.CommerceDTO.v1.Catalog.ProductDTO();
myProduct.Sku = "TEST123";
myProduct.ProductName = "My Simple Product";
myProduct.UrlSlug = "cool-products/my-simple-product";
myProduct.SitePrice = 19.95m; // The 'm' suffix tells C# this is a decimal
var createProductResponse 
    = api.ProductsCreate(myProduct, null); // We're passing null for the image data

Lastly, we need to assign the product to our category. We need to get the Id values (bvin) of the category and product in order to associate them together. We grab the Bvin value from the just created product and the Bvin value from the category that we created above.

// Get the ID (bvin) of the newley created product and category
string createdProductBvin = createResponse.Content.Bvin;
string categoryBvin = toUpdate.Bvin;

// Assign the new product to our category
api.CategoryProductAssociationsQuickCreate(createdProductBvin, categoryBvin);

One more thing. Let's update the product's inventory to make sure we have some on hand to sell.

// Create Inventory Object for Product
MerchantTribe.CommerceDTO.v1.Catalog.ProductInventoryDTO inventory
    = new MerchantTribe.CommerceDTO.v1.Catalog.ProductInventoryDTO();
inventory.ProductBvin = createdProductBvin;

// Get the newly created inventory object and update
var inventoryResponse = api.ProductInventoryCreate(inventory);
var toUpdateInventory = inventoryResponse.Content;
toUpdateInventory.QuantityOnHand = 99;
api.ProductInventoryUpdate(toUpdateInventory);

// Update the product's inventory mode
var p = createProductResponse.Content;
p.InventoryMode 
    = MerchantTribe.CommerceDTO.v1.Catalog.ProductInventoryModeDTO.WhenOutOfStockHide;
api.ProductsUpdate(p);

What's Next

The examples above are all you need to know to get started with the API. The rest is simply exploring the wrapper class and finding the correct methods to work with the items that you're interested in.

See the API Reference Guide for a list of items and commands available.