Overview

The Shopmonkey API is based on the REST standard. When you make a request to the REST API, you will specify an HTTP method and a path. Additionally, you might also specify request headers and path, query, or body parameters. The API will return the response status code, response headers, and potentially a response body.

The REST API reference documentation describes the HTTP method, path, and parameters for every operation. It also displays example requests and responses for each operation.

https://api.shopmonkey.cloud

Versioning

The Shopmonkey API is versioned and this version is part of the URL for the APIs.

The current version of the API is v3 and will be the first part of the path for any URL.

https://api.shopmonkey.cloud/v3

Any breaking changes will be released in a new API version. Breaking changes are changes that can potentially break an integration. Breaking changes include:

• removing an entire operation
• removing or renaming a parameter
• removing or renaming a response field
• adding a new required parameter
• making a previously optional parameter required
• changing the type of a parameter or response field
• removing enum values
• adding a new validation rule to an existing parameter
• changing authentication or authorization requirements

Any non-breaking changes will be available in the current API versions without changing the version. Non-breaking changes are changes that should not break an integration and include:

• adding an operation
• adding an optional parameter
• adding an optional request header
• adding a response field
• adding a response header
• adding enum values

When a new API version is released, the previous API version will be supported for at least 12 more months following the release of the new API version.

Authentication

To access the endpoints within the Shopmonkey API, authentication is mandatory. This guide explains the authentication mechanisms available. Shopmonkey employs OAuth Bearer Tokens as a method for authenticating API requests.

Making API requests without authentication or with an incorrect key results in a 401 HTTP status error, while requests with valid keys but insufficient permissions yield a 403 HTTP status error. It's mandatory to make all API requests over HTTPS, as requests over plain HTTP are rejected.

OAuth2 with Bearer token

Authentication with the Shopmonkey API is facilitated through OAuth2, specifically via the /auth/login endpoint. To authenticate, you must acquire an access token by logging in with your email and password. Here's the procedure to authenticate your requests using a Bearer token:

curl https://api.shopmonkey.cloud/v3/auth/login \
  -X POST -H 'Content-Type: application/json' \
  --data '{ "email": "user@example.com", "password": "yourpassword", "audience": "api" }'

This will return a response shaped like

{
  "success": true,
  "data": {
    "token": "your_bearer_token_here",
    ...
  }
}

For all subsequent calls you will use that token as a Bearer token in the header.

curl https://api.shopmonkey.cloud/v3/user/me \
  -H "Authorization: Bearer ${SM_TOKEN}"

Replace the SM_TOKEN with your token or set it in your environment.

Always keep your token safe and reset it if you suspect it has been compromised.

Creating and using a long lived API key

For certain operations, you might need a long lived API Key. You can generate a new API Key, optionally with an expiration date, with the apikey route. The expires parameter is the number of seconds until expiry. This key will have the permissions of the authenticated user requesting the key.

curl https://api.shopmonkey.cloud/v3/auth/apikey/86400 \
  -H "Authorization: Bearer your_bearer_token_here"

curl https://api.shopmonkey.cloud/v3/auth/apikey \
  -H "Authorization: Bearer your_bearer_token_here"

Invalidating your Bearer token

You can invalidate your API token and make it no longer usable by making an API request to the logout endpoint:

curl https://api.shopmonkey.cloud/v3/auth/logout \
  -H "Authorization: Bearer ${SM_TOKEN}"

Once you invalidate your token, it will no longer be usable.

Rate Limiting

The Shopmonkey API is rate limited. This means that you can only make a certain number of requests at a certain rate over a period of time. We use rate limiting to help protect the API and to make sure accidental issues don't overwhelm our system.

The rate limits are defined by your logged in state:

• Non Authenticated Requests: 10 requests per second
• Authenticated Requests: 5,000 requests per hour

If you are rate limited, you will receive a 429 HTTP status code. In addition, every response from the Shopmonkey API has the following HTTP headers to help you understand the limits programatically:

• x-ratelimit-limit: the rate limit based on your state
• x-ratelimit-remaining: the remaining number of requests before you are limited
• x-ratelimit-reset: the epoch time in seconds when the rate limit will be reset

In addition, when you are rate limited, you we also see the header retry-after which is the number of seconds you should wait before retrying your request.

Errors

In this guide, we will talk about what happens when something goes wrong while you work with the Shopmonkey API. Mistakes happen, and mostly they will be yours, not ours. Let's look at some status codes and error types you might encounter.

You can tell if your request was successful by checking the status code when receiving an API response. If a response comes back unsuccessful, you can use the error type and error message to figure out what has gone wrong and do some rudimentary debugging (before contacting support).

Status codes

Here is a list of the different categories of status codes returned by the Shopmonkey API. Use these to understand if a request was successful.

Error types

{
  "success": false,
  "code": "API-0efe28",
  "message": "No way this is happening!?",
  "documentation_url": "https://shopmonkey.dev/error/API-0efe28"
}

Cloud Regions

The Shopmonkey Cloud runs in multiple locations in North America to provide the highest level of availability, performance and business continuity.

The Shopmonkey Cloud uses the concept of Super Regions, Regions and Availability Zones.

Super Regions

A super region is a geographic region where the majority of our infrastructure runs in a highly available configuration. Inside each of the super regions, we have smaller city regions (called "regions"). Our super regions are divided geographically into the following:

• US West - the Western United States and Canada region in North America - us-west
• US Central - the Central United States and Canada region in North America - us-central
• US East - the Eastern United States and Canada region in North America - us-east

Regions

Inside each of the super regions, we have smaller city regions which are located in various cities inside the geographic area. We are currently located in 11 regions:

• Montréal, Québec - northamerica-northeast1 in us-east
• Toronto, Ontario - northamerica-northeast2 in us-east
• Moncks Corner, South Carolina - us-east1 in us-east
• Ashburn, Virginia - us-east4 in us-east
• Columbus, Ohio - us-east5 in us-east
• Council Bluffs, Iowa - us-central1 in us-central
• Dallas, Texas - us-south1 in us-central
• The Dalles, Oregon - us-west1 in us-west
• Los Angeles, California - us-west2 in us-west
• Salt Lake City, Utah - us-west3 in us-west
• Las Vegas, Nevada - us-west4 in us-west

Availability Zones

An availability zone is a physical data center in close proximity (but not too close for disaster situations) in a city. For each region, we run in a minimum of three availability zones. This means that if one data center had a disaster (say a fiber cut or fire in the building that caused an outage in connectivity or power) another center across the city would still be operational.

High Availability

From a business continuity standpoint, this means we can suffer a full region failure (i.e. a Hurricane on the East Coast of the US) and we still have 2 super regions and likely at least 8 other cities still able to service your traffic.

For each super region, we have an active-active replica of our core components, namely our database, messaging infrastructure and other critical systems that make the product work.

Each region is located inside the high speed, low latency private network of our cloud provider. That means even if a request comes in to one city – say Los Angeles, California and it needs to service that request in Dallas, Texas – it's super fast given the high speed backbone of the cloud provider (vs. the public Internet which has to traverse a lot of different providers).

The other aspect of this architecture is that we can distribute load (i.e. your activity while you're using the product) across a lot of different regions. Instead of one location and set of infrastructure taking all the burden, we can now distribute that load across 11 different regions, which often have their own traffic distribution based on timezones. It also means any failure (although we hope to make any failures completely transparent and behind the scenes) is localized to a smaller set of customers given this diffusion.

You can see see your nearest region and the latency and mileage by visiting https://api.shopmonkey.cloud.

Debugging

Each request to the Shopmonkey API returns the following three HTTP headers to assist in debugging regional routing:

• x-request-id: the unique id for the request
• x-director-region: the routing server region that handled your request
• x-region: the api server region that handled your request

In normal operations, the super region and region your API request will be routed to will be based on the location of the shop your API key is associated with and the geographic location of your client. This happens transparently within our network. In the case of a failure, your requests will be routed automatically to another available region or super region transparently without any required intervention.

In the event you are experiencing an unexpected API error, please share the x-request-id value from the HTTP headers with our Support Team to assist in debugging.