Blog
Category: Developers
MerchantOS API Changes
Posted on January 16, 2012 at 12:00 am by Nathan Horter
It’s been one year since we first introduced our API. It’s taken a lot of work to get where we are and it will take even more to get where we want to go with our API. We’ve seen ever increasing use of our API for external integrations like Perkville and internal projects like adding new inventory and generating packing lists. We wouldn’t have been able to make many of the improvements listed below without the valuable feedback of our API users. Thank you for your feedback and suggestions.
We are proud to annouce some changes and improvements to our API that are coming in our next release. Here is a quick overview of what is coming.
API Errors Returned in the Requested Format
Now when the API encounters an error instead of returning an html error page it will return error information in the format that was selected in the request (XML or JSON). This should allow for better error handling by client applications.
Fixes to API Datetimes
There was a bug that was causing some datetimes in the API to be returned incorrectly. Datetimes are now returned as GMT corrected for the timezone set in account.
Add Category and Tags to Receipt Template Items
We had a request to load the Item Category and Tags on the XML returned in the receipt template. This change will give access to those values to people using custom receipt templates.
Load Customer and Employee on Workorders
Another request we had was to load Customer and Employee information on returned Workorder objects. This gives access to the Customer name and address and Employee details for a Workorder without having to make more requests.
Sale Write Access
The biggest change that we have made is open up write access to Sales via the API. This is an important step forward for our API as it exposes more of the functionality of our application via our API. There are some important caveats to the functionality that we have exposed:
- Refunds and Returns are not yet supported
- Sales can be Archived (using the Delete method) or Completed, but they cannot be Unarchived or Uncompleted
- We have made every effort to fully test Sale write access via the API, but proceed with caution. If you find an error or discrepancy please contact us and let us know so we can correct it.
We still have plenty of work to do to improve our API including improving performance and exposing write access to more objects. We’re excited about these changes as they allow us to make big improvements to our product in the future.
If you have an API question, comment, suggestion or issue feel free to contact Nate at nate@merchantos.com.
API Updates
Posted on October 18, 2011 at 8:35 am by Nathan Horter
We’ve been getting lots of great feed back about our API. There are several projects that have been using it and we’ve been working with them to answer their questions and solve some problems that they have been running into.
In our latest release we’ve made a few adjustments to how the API works. None of these changes should break compatibility.
Reduced API Rate Limit Penalty
We had a penalty included in our API for when an application went over their call limit. We had found that this penalty was too harsh and we’ve reworked it to allow applications using our API to hit the call limit occasionally without penalizing them.
Return 503 When Over Rate Limit
Previously we had been returning a 500 error when an application went over it’s call limit. We’ve changed that to a 503 Service Unavailable error as that better reflects the error.
JSON input and output
We’ve also been working on adding JSON input and output for requests. Previously we could output JSON, but now we can accept JSON for requests that require a request body.
Disabled WWW-Authenticate header for AJAX Requests
If you are sending an AJAX request we will no longer be sending the WWW-Authenticate header as this causes UI issues with browsers. All other clients will still receive the WWW-Authenticate header when their request could not be authenticated.
Setting a Default Limit on Listing Requests
Previously we did not page results by default. This was causing issues with very large result sets. Now listing requests (such as requesting all items) will by default return 100 objects per request. This behavior can be over-ridden using the limit and offset query parameters (see the API search manual page: https://manual.merchantos.com/index.php/API_Searching). We are also returning the total count of objects, the current offset and limit for a request as attributes on the outer object tag when we automatically limit a request.
Tagging
We have added the ability to write tags through our API. Objects supporting tags (currently only Items) will have a Tags element containing the tags on the object if there are any. The count of the tags will be returned as an attribute of the Tags element.
Tags can be added to an Object by adding xml similar to below:
<Tags>
<Tag>
<name>foobar</name>
</Tag>
</Tags>
The tag does not have to already exist in the account you are accessing, it will be generated when your object is submitted.
All Tags can be accesses through the new Account/<AccountNumber>/Tag endpoint. This will show you how many tags there are as well as what objects are associated with that tag.
Bug fix to IN queries
We fixed a bug that was preventing queries with the IN search operator from executing properly. Queries like the following should now execute:
https://api.merchantos.com/Account/<AccountNumber>/Item?itemID=IN,[2,4,6,8]
More Improvements to Come!
We’re open to your feed back. If you have any questions about the changes we’re introducing please feel free to contact us. If you are having a problem with our API let us know and we will work with you to resolve it. Thanks again to all of the developers using our API for their valuable feedback. We’re working on even more improvements and we will post again when they are released.
Developer Digest
Posted on September 1, 2011 at 5:53 pm by Rob Richards
This month we check in with Vice President of Engineering Nathan Horter. Nate’s primary job is to make sure that your vendors are seamlessly integrated with MerchantOS, so as to cause you as little pain as possible. Nate also works on the back end infrastructure of our software, ensuring that everything is running smoothly behind the scenes.
What are you working on lately that customers might be affected by?
I’m currently working on overhauling our Shopify integration to improve it’s efficiency and squash some bugs. There shouldn’t be a huge difference in functionality once this update is released, but we will have solved most of the bugs that people have reported to us about the Shopify integration.
I’m also working on fleshing out some missing functionality in our API and starting on implementing webhooks. This will add Sale write capability to our API, which is a much needed feature for several integrations people are working on. Webhooks will allow our users to send notifications from our system to other web based services when certain actions are taken (like when an item is saved, or a transaction is completed, etc).
What’s your big idea for the future (that you’re willing to share)?
The biggest thing we’re working toward right now is separating the backend data (the numbers, and information stored in our system) from the front end representation (the experience that our users have interacting with the system). This allows us to be more flexible in creating our front end design and gives our users the opportunity to adjust the front end to their needs more easily. It’s a slow process, but it means that our software will become more scalable, flexible, and robust.
What is one thing you want every customer to know about you?
I’m always interested in helping our users get their vendors integrated with our system. It usually works best if a retailer talks to the vendor about integrating with MerchantOS. It’s difficult for us to get our foot in the door and convince them that integrating is in everyone’s best interest. Having a retailer, who does business with them, ask them to integrate makes more of an impact. If you’ve talked with a vendor and they are interested in integrating, have them contact me at nate@merchantos.com or 866-554-2453 ext. 95.
Ivan the Developer
Posted on June 22, 2011 at 4:04 pm by Rob Richards
This month we catch up with founder and CEO, Ivan Stanojevic to get the inside scoop on the behind the scenes work he does to keep MerchantOS software ahead of the competition.
First off, what hats do you wear when it comes to software development?
IVAN: My two main roles with the product are making sure it’s always available to our customers, and keeping each new release in line with our vision. I don’t spend any time writing code directly used in our software.
We have a growing infrastructure of servers that provide our web based service to our customers. I keep that infrastructure healthy and get our content delivered to our customers reliably and fast. Most recently I have been working on adding in a new data center and preparing to use some newer technologies to speed up our systems. We’re also scaling up our infrastructure with more capacity.
When working on the actual point of sale system, I spend a lot of time reviewing support requests to see where our software can improve, help the developers decide what to do next, test out new features and fixes, and make sure those changes both meet our customer’s needs and are simple to use.
What have you got going on right now?
IVAN: Right now I’m working on adding in a new data center with Amazon Web Services. This will allow us to scale our infrastructure much more quickly and save us the hassle of managing our own hardware.
This change should have no effect on our customers at first, but will allow us to speed some things up later.
What’s your big idea for the future?
IVAN: I don’t really have any one big idea. There are tons of changes we have to make to keep our system innovative and further improve it’s simplicity. We’re going to just keep rolling out the improvements.
“I don’t think our software will ever reach a point where it couldn’t be better.”
There are many new technologies coming along that can change how retailers are able to serve their customers. Two active areas I see are with mobile and payment processing.
We’re definitely going to be spending more time on mobile devices and you’ll be seeing those changes coming along.
We’re also watching the payments industry closely. I am hoping for some disruptive technologies that can compete with and change the traditional credit card industry into something that better serves retailers. As we see great ideas emerge we want to be ready to jump in and use those technologies in our product.
Before we go, what is the one thing you want every customer to know about you?
IVAN: I’m willing to talk to any customer. Email me at ivan@merchantos.com or call at 866 554 2453 ext. 91. I can’t promise a quick response but I do eventually get to everyone.
Related Articles
Using ActiveMQ for Web Services Integration
Posted on February 23, 2011 at 9:02 pm by Nathan Horter
If you’ve been reading our Blog over the last few months you’ve read about the integrations we’ve been creating with other web based applications like Freshbooks and MailChimp. These integrations allow our customers to use high quality web based applications with their data from MerchantOS and allow us to focus on making our application better.
Getting two completely different applications to talk to each other is no easy task. And we want MerchantOS to talk to more than just one other application. We needed a way to make creating new integrations easy and scalable.
We solved this problem using an idea called a Message Bus. In software design a message bus is a common connection among many programs we can send messages over. We’ve implemented our Message Bus using Apache ActiveMQ. Using this Message Bus layout we can create topics, send messages to those topics and have all (or some) of our integrations read those messages.
This means that you can, for example, create a customer in MerchantOS and have that customer’s information automatically exported into FreshBooks and MailChimp. And since we track where we have sent that customer’s information we can update it when you change it in MerchantOS in the future. This type of integration saves you time since all of your data is updated at once. But this is only a simple example, what about a something more complex?
We have an integration with Shopify that goes a step farther than just being able to export data from MerchantOS. With our Shopify integration orders that are placed in your Shopify shop will automatically be imported into MerchantOS. This automatically creates a new invoice and transaction.
This is a powerful feature by itself, but it’s power is multiplied when you have an integration with FreshBooks and MailChimp. With all three of those integrations turned on in MerchantOS:
- MerchantOS receives an order from your Shopify account and creates an invoice in MerchantOS.
- MerchantOS then exports that invoice to FreshBooks so you can email it to the customer .
- MerchantOS also exports the customer’s information to MailChimp so you can send that customer emails about specials or other notifications later.
All automatically.
We’re going to be adding more integrations soon, so let us know what you would like to see us integrate with next!
Challenges For Our iPad Point of Sale Dream
Posted on October 11, 2010 at 6:39 pm by Ivan Stanojevic
I’ve spent a couple weeks tinkering with the iPad and the end result has been frustration.
What is possible right now
If you’re willing to use the onscreen keyboard to search for items or if you can use our categorical menu (check out the video), you’re going to be able to have a device you can sell product with while roaming the shop with your customers. If you need bar code scanner compatibility, the iPad isn’t quite there yet. You can also plug in either a USB barcode scanner or USB credit card reader via the camera connector kit but you will lose onscreen keyboard functionality while that device is plugged in. This really hinders the efficiency of using the iPad for now.
Here’s a list of issues I couldn’t work around
- If card reader or scanner are plugged in, no onscreen keyboard pops up.
- Can’t charge iPad while any other USB device is plugged in. I tried using this pass-through iPhone / iPod / iPad connector which allows you to add Power via a mini-USB cable. The iPad seemed to stop listening to USB devices plugged in once voltage came in.
- iPad tends to crash with more than one USB device plugged in (using a hub).
- No printing support (You can email receipts and printing support is coming in iOS 4.2)
Awesome iPad Accessory
During all this experimentation I did get to try out an iPad mount kit made by ram-mounts. This mount system is hands down awesome! It uses a ball connector allowing you to swivel the iPad around however you want and there are many mounting options. Sturdiness was certainly good enough to use in a retail environment for the mount setup I used.
There is some hope
iOS 4.2 appears to be adding in some powerful features including the ability to print to a remote printer. It is possible though not likely this update might allow USB devices to function better.
And even more hope…
Mobile device support is becoming more of a priority as we develop our system. We plan to experiment with more tablet style devices and, over a long period of time, officially support mobile devices by creating browser based pages designed for those devices.
Echoes from the Developer’s Cave
Posted on October 8, 2010 at 3:59 pm by Murdoc Trammell
Roughly one week ago the company held an hour long office meeting in the cave. This dimly lit corner office is where our programmers Justin, Luke, and Nate make primitive dry-erase drawings that regular people can’t understand and where they feel comfortable speaking in a manner I’m not sure is actually derived from the English language. Sincerest apologies to those of you who got shafted waiting for Bryn and I to get back to you the afternoon we had this meeting.
During this discussion our company made several important decisions. The most memorable argument being that iPads are really awesome despite the fact that they’re an Apple product. As per Ivan:
iPads are the most perfectly designed tablet PC, engineered by the brightest minds of our galaxy. More on this later.
The other important decisions pertain to what the developers are going to continue to pursue. Justin follows Marketplace on public radio and other sources to catch up on the economy. He’s become the office Alan Greenspan. One of the things he brought up was how much businesses are still hurting in this economy. He followed up with the drastic pricing incentives stores are doing just to get people in the door and pointed out that this may be affecting your businesses.
No one is immune to this penny-pinching plague.
When faced with a choice between upgrading MerchantOS with new integrations & fancy features to entice new customers or resolving the limits MerchantOS currently has, we’re going to stand behind the folks who have come this far with us. It’s our current customer base that has helped MerchantOS grow to this level of magnitude. With 716 customers and more sign-ups every day, it looks like we’ve got this Point of Sales thing down.
With that said, the developers are going to work on revamping both the price structure as well as the discounts to meet your needs. With your feedback and our programming talent we’ll help you get through these tough times.
We want to thank you all for the feedback you’ve given us. We’ve implemented a new system to communicate with the developers what changes/fixes need to be prioritized. So keep reminding us which issues matter the most, it always helps to email specifics to support@merchantos.com.
I hope you enjoyed reading this to some degree. I plan on updating you folks with what I’ve been hearing from the developers from time to time. If you don’t enjoy reading these blogs, then I don’t feel guilty for distracting you from any real work.
Cheers!
-Murdoc
Single Sign-On with OpenID and Google Part 2
Posted on April 15, 2010 at 1:22 pm by Nathan Horter
A Quick Review
Wouldn’t it be nice if we didn’t have to remember so many passwords? With the proliferation of Software as a Service (SaaS) applications on the internet there are more and more things that we need to remember a username and password to access. This is where Single Sign-On (SSO) comes in. Single Sign-On is the idea that you can sign-on with one set of credentials and be signed-on to multiple services all at once.
In Part 1 we covered some of the basics of what Single Sign-On is and how we send end-users off from our site to their Identity Provider to verify their identity.
Getting the Id Back
Once the user has successfully logged in to their Identity Provider and decided to allow our site to know what their identity is, the user will be returned to the call back URL that we specified with the necessary information in browser. We just need to verify it and decide what to do next.
In Part 1 we told the Identity Provider to send the end-user to a script called call_back.php to complete the process of logging in the user. Lets start writing that script:
// See the examples/consumer/common.php file in OpenID Enabled library package.
// This provides some utility functions used below.
require_once 'common.php';
session_start();
// Create a new OpenID consumer to receive our Identity Provider response.
// To create the consumer we need to setup a store for the OpenID information
$store_path = '/tmp/_php_consumer_test';
$store = new Auth_OpenID_FileStore($store_path);
// Once we have a store for the information we need to create a new consumer.
$consumer =& new Auth_OpenID_Consumer($store);
// The GApps_OpenID_Discovery allows the consumer to find openid's for Google Apps.
new GApps_OpenID_Discovery($consumer);
// To complete the discovery process we need to pass the same callback url that we sent to the Identity Provider.
// This ensures that we can check the signature the Identity Provider sent us.
$server_url = 'http://myserver:80';
$response = $consumer->complete($server_url.'/callback.php');We now have the response from the Identity Provider. With the response we can now check the status of the OpenId discovery and get the returned OpenId.
$openid = '';
switch($response->status)
{
case 'success':
$openid = $response->endpoint->claimed_id;
break;
case 'cancel':
case 'failure':
case 'setup_needed':
default:
// If we got a status we don't understand we should take an appropriate action.
break;
}
if (!empty($openid))
{
// We have an openid, we need to check if it's associated with a login in our system.
}
else
{
// We didn't get an openid, generate an error
}What you do with the OpenID once you have it is dependent on how you handle logins on your site. You could check to see if the OpenID is already associated with an account on your site and if not then prompt the end-user to create a new account. In our case we only want to associate OpenID’s with existing end-user accounts. We store the OpenID in our database with an association to an existing account. If the OpenID is not associated then we prompt the user to enter their existing credentials (loging them in) so we can associate their OpenID with their account.
Round Up
Implementing Single Sign-On allows your users to access their data using one set of credentials, rather than having to remember a different set of credentials for each site. This means they can remember fewer more secure passwords rather than have to remember more less secure passwords (or use the same password across many sites).
For SaaS applications that target businesses implementing SSO with Google makes it possible for you to get your application listed in the Google Apps Marketplace. This gives your application access to over 2 million businesses that use Google’s enterprise applications.
Single Sign-On with OpenID and Google Part 1
Posted on April 6, 2010 at 9:57 am by Nathan Horter
What is this “Single Sign-On”
Wouldn’t it be nice if we didn’t have to remember so many passwords? With the proliferation of Software as a Service (SaaS) applications on the internet there are more and more things that we need to remember a username and password to access. This is where Single Sign-On (SSO) comes in. Single Sign-On is the idea that you can sign-on with one set of credentials and be signed-on to multiple services all at once.
Right now the most popular SSO implementation is OpenID. OpenID is a standard that defines how SSO id’s look and how you find who can verify an SSO id. OpenID’s typically look like a URL:
http://example.com/id/1234But other services will accept an email address as the OpenID:
1234@example.comIn both cases example.com is the Identity Provider.
(more…)
Join Us For A Whiteboard Session – LIVE
Posted on July 17, 2009 at 4:07 pm by Justin Laing
WHEN: 11am PST on Thursday July 23rd
WHERE: http://www.ustream.tv/channel/merchantos
We will be putting on a live whiteboard session next Thursday, and you can join in! We’ll be broadcasting live on USTREAM (a live video streaming website) and taking questions via chat. From 11am to Noon PST you can help shape the future of your retail software with us. We’d love to get your input, have you share your ideas with other customers, and generally get your help in steering the direction of our company.
Feel free to enter questions you have ahead of time as comments on this post. You can always call us if you have questions or comments at 866-554-2453 also.
Or you can watch and participate from right here (though I recommend the USTREAM site):
Free Videos by Ustream.TV