Getting Started

Getting Started with OrderMesh API

Welcome to the OrderMesh Developer Portal. Our API is organized around REST, featuring predictable resource-oriented URLs and standard HTTP methods. We support cross-origin resource sharing (CORS), allowing you to interact securely with our API from client-side applications.

Base URLs

All API requests must be directed to:

https://api.ordermesh.io/

Authentication

The OrderMesh API leverages OAuth 2.0 for secure authentication. To interact with protected resources, you must include a Bearer Token in your API request headers.

There are two distinct ways to obtain an access token. Choosing the correct method is critical for the stability and security of your integration.

1. User Credentials (Development & Testing ONLY)

Using your OrderMesh Platform Username and Password is intended strictly for manual testing, initial development, and using the "Try It Out" console in this documentation portal.

Endpoint: POST /user/v1/login

Authentication Flow: Ideal for rapid prototyping and exploring endpoints manually.

⚠️ IMPORTANT: Never use Username/Password for production integrations. These credentials expire and are subject to security rotations, which will cause your production integration to break.

Sample Request:

2. Client Credentials (Production Standard)

For secure, machine-to-machine communication in a production environment, you must use a Client ID and Client Secret.

Setup: Log in to the OrderMesh Portal, navigate to Merchants → Authentication → Create Client.

Endpoint: POST /user/v1/clients/token

Access Control: The client secret is displayed only once. Store it securely (e.g., in a secret manager). Only production-level personnel should have access to these credentials.

Sample Request:

Making API Calls

To make API calls, include the access token in the Authorization header.

Required Headers

Header	Value	Description
Authorization	`Bearer <your_access_token>`	The word "Bearer" followed by a space and your token.
Content-Type	`application/json`	Specifies the media type of the resource.

Example API Call (Create Order)

Handling Token Expiry

Token expiry behavior differs depending on the authentication method used:

Client Credentials – Client access tokens have a lifespan of 24 hours and do not support a refresh flow. Your integration must automatically reauthenticate using your Client ID and Secret when the token expires.

User Credentials – When your access token expires, use the refresh token to obtain a new one without re-entering credentials.

Endpoint: POST /user/v1/refresh

Sample Request:

{
  "refreshToken": "your_refresh_token"
}

Sample Response

{
  "accessToken": "new_access_token",
  "scope": "email profile",
  "tokenType": "Bearer",
  "refreshToken": "new_refresh_token",
  "expiresIn": 3600
}

API Patterns

Pagination

We use page-based pagination for most GET requests. You can specify the size and number of pages using the following parameters:

page: (Optional) Page number (defaults to 1).

pageSize: (Optional) Items to return in response (defaults to 50).

Metadata

Some objects like Order and OrderItem can contain a meta parameter. You can use this to attach custom key-value data for internal tracking.

🛑 NOTE: Do not store sensitive information (bank account numbers, card details, etc.) as metadata.

Getting Started with OrderMesh API#

Base URLs#

Authentication#

1. User Credentials (Development & Testing ONLY)#

2. Client Credentials (Production Standard)#

Making API Calls#

Required Headers#

Example API Call (Create Order)#

Handling Token Expiry#

Sample Response#

API Patterns#

Pagination#

Metadata#

Getting Started with OrderMesh API

Base URLs

Authentication

1. User Credentials (Development & Testing ONLY)

2. Client Credentials (Production Standard)

Making API Calls

Required Headers

Example API Call (Create Order)

Handling Token Expiry

Sample Response

API Patterns

Pagination

Metadata