# MerchantHQ ## Description This is version `1.0.0` of this API documentation. Last update on Aug 15, 2025. # 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 ``` ### 3. **Create a Merchant** The user can create a merchant account after logging in. **Endpoint:** ``` POST /api/2024-09/merchants ``` **Headers:** ```json { "Authorization": "Bearer your~access-token" } ``` **Request Body:** ```json { "name": "Mega Store" } ``` **Response (200 OK):** ```json { "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:** ```json { "Authorization": "Bearer your~access-token" } ``` **Request Body:** ```json { "name": "Amazon Channel 1", "merchant_id": 1, "type": "amazon" } ``` **Response (200 OK):** ```json { "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:** ```json { "Authorization": "Bearer your~access-token" } ``` **Request Body:** ```json { "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):** ```json { "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):** ```json { "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:** ```json { "Authorization": "Bearer your~access-token" } ``` **Response (200 OK):** ```json { "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:** ```json { "Authorization": "Bearer your~access-token" } ``` **Response (200 OK):** ```json { "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:** ```json { "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):** ```json { "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. ## Servers - Production server (uses live data): https://app.merchanthq.com/api (Production server (uses live data)) ## Authentication ## Endpoints and operations ### [Channels](https://docs.merchanthq.com/group/endpoint-channels.md) - [List of channels](https://docs.merchanthq.com/operation/operation-get-channels.md) - [Create a channel](https://docs.merchanthq.com/operation/operation-create-channel.md) - [Show channel](https://docs.merchanthq.com/operation/operation-get-channel.md) - [Update channel](https://docs.merchanthq.com/operation/operation-update-channel.md) - [Delete channel](https://docs.merchanthq.com/operation/operation-delete-channel.md) - [Store Amazon channel connection data](https://docs.merchanthq.com/operation/operation-store-amazon-channel-connection-data.md) - [Get Amazon channel authorization URL](https://docs.merchanthq.com/operation/operation-get-amazon-auth-url.md) - [Retrieve data from Amazon API](https://docs.merchanthq.com/operation/operation-proxy-amazon-api-get.md) - [Update data in Amazon API](https://docs.merchanthq.com/operation/operation-proxy-amazon-api-put.md) - [Send data to Amazon API](https://docs.merchanthq.com/operation/operation-proxy-amazon-api-post.md) - [Delete data from Amazon API](https://docs.merchanthq.com/operation/operation-proxy-amazon-api-delete.md) - [Partially update data in Amazon API](https://docs.merchanthq.com/operation/operation-proxy-amazon-api-patch.md) - [Search catalog items](https://docs.merchanthq.com/operation/operation-search-channel-catalog-items.md) ### [Merchants](https://docs.merchanthq.com/group/endpoint-merchants.md) - [List of merchants](https://docs.merchanthq.com/operation/operation-get-merchants.md) - [Create a merchant](https://docs.merchanthq.com/operation/operation-create-merchant.md) - [Show merchant data](https://docs.merchanthq.com/operation/operation-show-merchant.md) - [Update a merchant](https://docs.merchanthq.com/operation/operation-update-merchant.md) - [Delete merchant](https://docs.merchanthq.com/operation/operation-delete-merchant.md) ### [Products](https://docs.merchanthq.com/group/endpoint-products.md) - [List of products](https://docs.merchanthq.com/operation/operation-get-products.md) - [Create a product](https://docs.merchanthq.com/operation/operation-create-product.md) - [Show product data](https://docs.merchanthq.com/operation/operation-show-product.md) - [Update a product](https://docs.merchanthq.com/operation/operation-update-product.md) - [Delete product](https://docs.merchanthq.com/operation/operation-delete-product.md) - [List product images](https://docs.merchanthq.com/operation/operation-get-product-images.md) - [Create a product image](https://docs.merchanthq.com/operation/operation-create-product-image.md) - [Create a product identifier](https://docs.merchanthq.com/operation/operation-create-product-identifier.md) - [Delete a product identifier](https://docs.merchanthq.com/operation/operation-delete-product-identifier.md) ### [Sourcing](https://docs.merchanthq.com/group/endpoint-sourcing.md) - [List of suppliers](https://docs.merchanthq.com/operation/operation-get-suppliers.md) - [Create a supplier](https://docs.merchanthq.com/operation/operation-create-supplier.md) - [Show supplier data](https://docs.merchanthq.com/operation/operation-show-supplier.md) - [Update a supplier](https://docs.merchanthq.com/operation/operation-update-supplier.md) - [Delete supplier](https://docs.merchanthq.com/operation/operation-delete-supplier.md) - [List of supplier items](https://docs.merchanthq.com/operation/operation-get-supplier-items.md) - [Create a supplier item](https://docs.merchanthq.com/operation/operation-create-supplier-item.md) - [Show supplier item data](https://docs.merchanthq.com/operation/operation-show-supplier-item.md) - [Update a supplier item](https://docs.merchanthq.com/operation/operation-update-supplier-item.md) - [Delete supplier item](https://docs.merchanthq.com/operation/operation-delete-supplier-item.md) - [Create a supplier item identifier](https://docs.merchanthq.com/operation/operation-create-supplier-item-identifier.md) - [Delete a supplier item identifier](https://docs.merchanthq.com/operation/operation-delete-supplier-item-identifier.md) ### [Users](https://docs.merchanthq.com/group/endpoint-users.md) - [Get current user](https://docs.merchanthq.com/operation/operation-get-current-user.md) - [Update current user](https://docs.merchanthq.com/operation/operation-update-current-user.md) - [List of users for a merchant](https://docs.merchanthq.com/operation/operation-get-merchant-memberships.md) - [Invite user to merchant](https://docs.merchanthq.com/operation/operation-invite-user-to-merchant.md) - [Remove user from merchant](https://docs.merchanthq.com/operation/operation-remove-user-from-merchant.md) ### [Marketplaces](https://docs.merchanthq.com/group/endpoint-marketplaces.md) - [List of marketplaces](https://docs.merchanthq.com/operation/operation-get-marketplaces.md) - [List of marketplace catalog items](https://docs.merchanthq.com/operation/operation-get-marketplace-catalog-items.md) - [Get a marketplace catalog item](https://docs.merchanthq.com/operation/operation-get-marketplace-catalog-item.md) - [List catalog item images](https://docs.merchanthq.com/operation/operation-get-marketplace-catalog-item-images.md) - [List catalog item sales ranks](https://docs.merchanthq.com/operation/operation-get-marketplace-catalog-item-sales-ranks.md) - [List of marketplace catalog item imports](https://docs.merchanthq.com/operation/operation-get-marketplace-catalog-item-imports.md) - [Request a marketplace catalog item import](https://docs.merchanthq.com/operation/operation-post-marketplace-catalog-item-import.md) - [Get current offers for a marketplace catalog item](https://docs.merchanthq.com/operation/operation-getmarketplacecatalogitemcurrentoffers.md) - [Get price history for a marketplace catalog item](https://docs.merchanthq.com/operation/operation-getmarketplacecatalogitempricehistory.md) ### [Supplier Scraping](https://docs.merchanthq.com/group/endpoint-supplier-scraping.md) - [List supplier scraping requests](https://docs.merchanthq.com/operation/operation-getsupplierscrapingrequests.md) - [Create a new supplier scraping request](https://docs.merchanthq.com/operation/operation-createsupplierscrapingrequest.md) - [Get a supplier scraping request](https://docs.merchanthq.com/operation/operation-getsupplierscrapingrequest.md) - [List supplier scraping attempts](https://docs.merchanthq.com/operation/operation-getsupplierscrapingattempts.md) ### [Forecasting](https://docs.merchanthq.com/group/endpoint-forecasting.md) - [List opportunity forecasts](https://docs.merchanthq.com/operation/operation-get-opportunity-forecasts.md) - [Calculate new opportunity forecast](https://docs.merchanthq.com/operation/operation-calculate-opportunity-forecast.md) - [List sales volume forecasts](https://docs.merchanthq.com/operation/operation-get-sales-volume-forecasts.md) [Powered by Bump.sh](https://bump.sh)