Explore APIs

Welcome to our API Documentation!


Our API is organized around REST and contains predictable, resource-oriented URLs. We use common HTTP methods such as GET, POST, PUT,PATCH and DELETE which can be understood and used by off-the-shelf HTTP clients. We also support cross-origin resource sharing (CORS) which allows you to interact securely with our API from a client-side web application.

Base URLs

All API requests have to be sent to this URL:

https://api.ordermesh.io/

Authentication

The OrderMesh API leverages OAuth 2.0 for secure authentication and authorization. This ensures a straightforward and protected integration process. Authentication requires obtaining an access token that must be included in your API requests. However, you can obtain your access token in two ways:

  1. You can use your Username and Password that you use to login to OrderMesh platform or

  2. You can use Your Client ID and Client Secret.

Authenticating via Username and Password

For creating an account on the OrderMesh Portal, you'll be prompted to use a Username and a Password. To request an access token, you can use your username and password to make a POST request to the user/login endpoint: 

http://api.ordermesh.io/user/v1/login

Sample Request:

{

"password": "PASSWORD"

"username": "EMAIL@ordermesh.io",

}

Sample Response: //short version

{

  "access_token": "your_access_token",

"scope": "email profile",

"tokenType": "Bearer",

  "refresh_token": "your_refresh_token",

"expires_in": 900, //The lifetime of the access token in seconds

}

Authenticating via Client ID and Client Secret

For a more secure way of authenticating, sign in to the OrderMesh Portal using your username and password, navigate to Merchants →Authentication →Create Client to fetch Your Client ID and Client Secret.

Note: The client secret is displayed only once, so make sure to store it securely. If needed, you can generate a new client secret from the portal.

To request an access token, use your client_id and client_secret to make a POST request to the user/clients/token endpoint: 

http://api.ordermesh.io/user/v1/clients/token

Sample Request:

{

   "client_id": "YOUR_CLIENT_ID",

   "client_secret": "YOUR_CLIENT_SECRET"

}

Sample Response: // waiting on Adam for guidance on the exact example payload and response

{

  "access_token": "your_access_token",

"scope": "email profile",

"tokenType": "Bearer",

"refresh_token": "your_refresh_token",

  "expires_in": 900, // The lifetime of the access token in seconds

}

Making API Calls

To make API calls, include the access token in the Authorization header of your requests. The header should be in the format:

  • Authorization: Bearer <your_access_token>. 

Additionally, set the Content-Type header to specify the media type of the resource, typically application/json for API calls.

Headers:

  • Authorization: Contains the word Bearer followed by a space and your access_token.

  • Content-Type: Specifies the media type of the resource, typically application/json for API calls.

Example API Call:

To create an order, you would make a POST request to the order creation endpoint with the authorization token in the header:

POST /api/orders HTTP/1.1

Host: api.company.com

Authorization: Bearer your_access_token

Content-Type: application/json

{

  "orderDetails": {

  // JSON structure containing order payload

  }

}

Handling Token Expiry

When your access token expires, use the refresh token to obtain a new one without re-entering credentials. To refresh the token, make a POST request to the token endpoint depending on the credentials you used for authenticating:

  • If you used Username and Password - make a POST request with the refresh token to /v1/users/refresh endpoint.

  • If you used your Client ID and Client Secret - make a POST request with the refresh token to /v1/users/clients/refresh endpoint.

Refresh Request:

{

  "refresh_token": "your_refresh_token",

}

Refresh Response:

{

  "access_token": "new_access_token",

  "expires_in": 3600, // New lifetime of the access token

  "refresh_token": "new_refresh_token" // Only if refresh token rotation is enabled

}

Pagination

Our API contains page-based pagination which involves using a page and pageSize parameters that you can use with most of our GET requests. You have the option to specify the size and number of pages you wish to get in response, by including the parameters in the request URL.

  • page - optional - page number, how many items to skip / defaults to 1

  • pageSize - optional - how many items to return in response / defaults to 50 


Metadata

Some objects like order and orderItem can contain a meta parameter. You can use this parameter to attach key-value data to these objects with any information you want to be attached to the object. 

You can specify up to ? keys, with key names up to ? characters long and values up to ? characters long.

Note: Don’t store any sensitive information (bank account numbers, card details, and so on) as metadata.


Continue to Webhooks Overview