- Making a request
- XML, JSON
- Handling errors
- Check the requests and responses
- Result limiting
- Rate limiting
Getting started with the API documentation and wrappers for VersaCommerce
The VersaCommerce API follows the principals of a restful Webservice. It´s implemented as XML OR JSON over HTTP using all four verbs (GET/POST/PUT/DELETE). Every resource, like product, collection, page or order, has its own URL.
To use the VersaCommerce API you will need an application registration for your store.
- SignUp as an developer: https://app.versacommerce.de/developer/signup
- Login to your developer account: https://app.versacommerce.de/developer
- Register your app:
- Your applications name
- A short description
- A redirect url, where your shop should send the token parameter to.
- An optional URL where your customers can configure their settings
- Several optional URL´s of actions in your App, the title of the link poiting to each action and the location of the link in the VersaCommerce Backend
- If you need only read or also write access
- Authentication is managed via HTTP Basic authentication. Every request must include the Authorization HTTP Header.
Every VersaCommerce API-Call will look like this:
For detailed information see: Authentication
Making a request
All URLs start with http://shopdomain.versacommerce.de/api/. If we change the API in backward-incompatible ways, we’ll add a version marker and maintain stable support for the old URLs.
In curl, that looks like:
$ curl -u user:pass -H 'User-Agent: MyApp (firstname.lastname@example.org)' <a href="http://APPLICATION_KEY:PASSWORD@shopdomain.versacommerce.de/api/any-resource.xml">http://APPLICATION_KEY:PASSWORD@shopdomain.versaco...</a>
To create something, it’s the same deal except you also have to include the Content-Type header and the JSON/XML data:
We support XML and JSON for serialization of data. Our format is to have no root element and we use snake_case to describe attribute keys (JSON). This means that you have to send Content-Type: application/json; charset=utf-8 when you’re POSTing or PUTing data into VersaCommerce. All API URLs end in .json to indicate that they accept and return JSON. All API URLs end in .xml to indicate that they accept and return XML.
If VersaCommerce is having trouble, you might see a 5xx error. 500 means that the app is entirely down, but you might also see 502 Bad Gateway, 503 Service Unavailable, or 504 Gateway Timeout. It’s your responsibility in all of these cases to retry your request later.
Check the requests and responses
Use Fiddler for Windows, or Charles for OS X to debug your HTTP requests and responses.
You can receive max 250 records per request. The default limit is 150. If you need to handle more records, you should request them in batches. Use the query params “limit” and “offset” to batch through your results.
You can perform up to 500 requests per 10 second period from the same IP address for the same account.