Introduction

The Joom merchant platform is an ecommerce platform. It allows merchants to upload and manage inventory for sale on Joom. The platform is intended to be full-featured so merchants can manage their inventory, fulfill orders.

Versioning

This is the V2 and current version of the Joom for Merchants API.

Date/Time Format

All dates and times in our API are always in UTC unless otherwise mentioned.

Authentication

Joom uses the OAuth 2.0 specification to authenticate your requests. For a detailed guide on how to authenticate, read our documentation.

Every request will need to be authenticated with an access token. When making requests, provide the access token as a GET or POST request parameter:

Parameter Type Example
access_token “1qaz2wsx3edc4rfv5tgb”

Alternatively, the access token can be included in the header in this format:

"Authorization: Bearer {access_token}"

Requests must be made over HTTPS. Any call made over HTTP will be rejected.


Response Scheme

Every response returned from the Joom API will have the same schema. This schema is intended to give you a predictable manner to check the status of your request and know where to get the data.

Scheme Attributes

Name Description
code Contains the status code for the request, 0 means success and any other number implies a failure
data This attribute will store the response data that was requested
message Sometimes will store a human readable status message to aid in debugging. It is generally used only for errors
paging If the number of results exceeds the limit for the request, this parameter will aid the client in paging to collect all the results

Example

Note: access token and format have been removed from the URLs for brevity.

{
  "code": 0,
  "data": [
    /* results will be here */
  ],
  "message": "",
  "paging": {
    "next": "https://api-merchant.joom.com/api/v2/product/multi-get?start=20&limit=10",
    "prev": "https://api-merchant.joom.com/api/v2/product/multi-get?start=10&limit=10"
  }
}

API Errors

The Joom API returns specific error data back to the client in the event of an error. Please see table below for attribute descriptions.

Error Attributes

Name Type Description Example
code number A unique number which represents the error that has occurred 4001
type string A unique human readable representation of the error “not_found”
message string A message describing the error that happened “We could not find a product for id: ’aaa’”
data Object most errors this will be empty

Example Request

> curl https://api-merchant.joom.com/api/v2/order/fulfill-one
-d "tracking_provider=USPSSSSSSSSSSSSSSSSSSSSSSSSS&tracking_number=12345679&id=098765432112345678901234&access_token=an_example_access_token"

Example Response

{
  "code": 1000,
  "data": 2003,
  "message": "Tracking provider is not one of the accepted providers on Joom"
}

HTTP Status Codes

As well as using specific error codes in the event of an error, this API tries to conform to conventional HTTP response codes to indicate success or failure. Any response code of the form 2xx is generally considered successful. A status code of 4xx means that there was an error with the inputs. Any code in the 5xx range means that the server experienced an unexpected error and means we screwed up!

The HTTP status code should be used as a quick reference, but to get specific details please refer to the error code provided in the response.


Pagination

For performance reasons it is necessary for this API to limit the number of results returned in each request. This limit varies per request, but there is always an upper bound on the number of items returned in any response. In the case that the number of results is too large, you may page through all the results with multiple requests.

If the results must be paginated the paging attribute will exist in the response. This attribute will contain next and prev which are URLs for fetching the next (or previous) page of data.

Example

Note: access token and format have been removed from the URLs for brevity.

{
  "code": 0,
  "data": [
    /* results will be here */
  ],
  "message": "",
  "paging": {
    "next": "https://api-merchant.joom.com/api/v2/product/multi-get?start=20&limit=10",
    "prev": "https://api-merchant.joom.com/api/v2/product/multi-get?start=10&limit=10"
  }
}

How to Debug

When API errors, it’ll still return a JSON response. The response contains information on exactly what caused the error.

For more information, check out API Errors

Example Request

> curl https://api-merchant.joom.com/api/v2/order/fulfill-one
-d "tracking_provider=USPSSSSSSSSSSSSSSSSSSSSSSSSS&tracking_number=12345679&id=098765432112345678901234&access_token=an_example_access_token"

Example Response

{
  "code": 1000,
  "data": "2003",
  "message": "Tracking provider is not one of the accepted providers on Joom"
}

Debugging

USPSSSSSSSSSSSSSSSSSSSSSSSSS is not a shipping provider, to fix, change it to USPS.

Example Request 2

> curl https://api-merchant.joom.com/api/v2/order/fulfill-one
-d "tracking_provider=USPS&tracking_number=12345679&id=098765432112345678901234&access_token=an_example_access_token"

Example Response 2

{
  "code": 0,
  "data": {
    "success": "True"
  },
  "message": "Your order is been processed right now!"
}