MerchantHQ API

MerchantHQ
1.0.0

Base URL 
https://app.merchanthq.com/api

MerchantHQ Onboarding Process

Workflow: How a New User Registers and Starts Using the API

The following workflow outlines how to start using the MerchantHQ API to manage merchants, channels, and user profiles.

1. Generate a Token

From your MerchantHQ dashboard, generate a new API token.

2. Authentication

To authenticate with the MerchantHQ API, include the token in the Authorization header of your API requests.

Authorization: Bearer <your-token>

3. Create a Merchant

The user can create a merchant account after logging in.

Endpoint:

POST /api/2024-09/merchants

Headers:

{
  "Authorization": "Bearer your~access-token"
}

Request Body:

{
  "name": "Mega Store"
}

Response (200 OK):

{
  "data": {
    "id": 1,
    "name": "Mega Store",
    "created_at": "2024-10-21 14:20:37",
    "updated_at": "2024-10-21 14:20:37"
  }
}

4. Add Channel to a Merchant

After creating a merchant, the user can add a channel (such as Amazon) by providing the necessary authorization details.

Endpoint:

POST /api/2024-09/channels

Headers:

{
  "Authorization": "Bearer your~access-token"
}

Request Body:

{
  "name": "Amazon Channel 1",
  "merchant_id": 1,
  "type": "amazon"
}

Response (200 OK):

{
  "data": {
    "id": 1,
    "name": "Amazon Channel 1",
    "created_at": "2024-10-21 16:58:14",
    "updated_at": "2024-10-21 16:58:14"
  }
}

5. Configure Amazon Channel Connection

After creating the channel, you need to configure the Amazon connection data with authorization tokens.

Endpoint:

POST /api/2024-09/channels/amazon/{channel}/connection-data

Headers:

{
  "Authorization": "Bearer your~access-token"
}

Request Body:

{
  "access_token": "amzn1.application-oa2-client.xxxxx",
  "access_token_expires_at": "2024-10-10 14:59:16",
  "refresh_token": "Atzr|IwExxxxxxx",
  "marketplace_id": "ATVPDKIKX0DER"
}

Response (200 OK):

{
  "data": {
    "id": 1,
    "name": "Amazon Channel 1",
    "created_at": "2024-10-21 16:58:14",
    "updated_at": "2024-10-21 16:58:14"
  }
}

Login with Amazon.

Step 1: Get LWA Authorization URL

The first step to integrate an Amazon channel is to obtain the Login with Amazon (LWA) authorization URL. The user will be redirected to this URL to allow MerchantHQ access to their Amazon seller account.

Endpoint:

GET /api/2024-09/channel/amazon/{channel}/get-auth-url

Response (200 OK):

{
  "url": "https://sellingpartnerapi-na.amazon.com/apps/authorize/consent?application_id=amzn1.sp.solution.b5794417-19aa-4823-bc20-513553753eca\u0026state=eyJpdiI6ImVFZE5Peno2R0NtRTRiR2FFWjlBWGc9PSIsInZhbHVlIjoiS3d5cStnQVdUTG5rMWo3QkxHdXUxN0ZpQlZKNzZ3WVJLb0YzMEVFeFZibz0iLCJtYWMiOiI3ZDcxZWY1MjQ2ZTRhZDJkZTU3NWRlMTI0ZjVhMzJhMDg2YTUyZjNlYjQ1ZjZkYmE5YmNkZjE1ZTlkYWE2MDJmIiwidGFnIjoiIn0%3D"
}
Step 2: Authorize via Amazon

Once the user visits the provided URL, they will complete the authorization process on Amazon’s side. Upon successful authorization, Amazon will redirect to a predefined URL with an authorization code.

6. Get Profile Information

The user can retrieve their profile information to verify details or update their profile later.

Endpoint:

GET /api/2024-09/users/current

Headers:

{
  "Authorization": "Bearer your~access-token"
}

Response (200 OK):

{
  "data": {
    "id": 1,
    "name": "John Doe",
    "email": "john.doe@example.com",
    "created_at": "2024-10-21 14:20:37",
    "updated_at": "2024-10-21 14:20:37"
  }
}

7. List Merchants

The user can retrieve a list of all merchants they have access to.

Endpoint:

GET /api/2024-09/merchants

Headers:

{
  "Authorization": "Bearer your~access-token"
}

Response (200 OK):

{
  "data": [
    {
      "id": 1,
      "name": "Mega Store",
      "created_at": "2024-10-21 14:20:37",
      "updated_at": "2024-10-21 14:30:22"
    }
  ],
  "links": {
    "first": "https://merchanthq.jasaratech.com/api/2024-09/merchants?page=1",
    "last": "https://merchanthq.jasaratech.com/api/2024-09/merchants?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https://merchanthq.jasaratech.com/api/2024-09/merchants",
    "per_page": 10,
    "to": 1,
    "total": 1
  }
}

8. Call Amazon API

The user can make authorized API calls to Amazon for a specific channel.

Endpoint:

POST /api/2024-09/channel/amazon/{channel}/call/{url}

Headers:

{
  "Authorization": "Bearer your~access-token"
}

Path Parameters:

  • {channel}: The UUID of the channel (e.g., 1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4).
  • {url}: The Amazon API endpoint (e.g., reports/2021-06-30/reports).

Response (200 OK):

{
  "response": "Amazon API response."
}

Summary

  1. Create merchants
  2. Add Amazon channels.
  3. Use the access token to make API calls to Amazon Seller API.

This is version 1.0.0 of this API documentation. Last update on Aug 15, 2025.