MapMyData Product API Documentation

Overview

The MapMyData Product API is a secure product catalog interface intended for applications that need structured access to product information. The API supports single-record retrieval, collection retrieval with query controls, and bulk access patterns commonly used in catalog, merchandising, personalization, and data synchronization workflows.

Built for integration flows

Authenticate once, receive an access token, then use that token to request protected product data across downstream endpoints.

Rich, nested catalog structure

Product objects include attributes, pricing, inventory, media, variants, reviews, and audit metadata for realistic mapping and schema handling.

Authentication

The API uses the OAuth 2.0 Client Credentials flow. Clients exchange a client_id and client_secret for a bearer access token, then include that token on subsequent API requests.

Token endpoint

POST https://dev-ij8d8xnp6zjae8hn.us.auth0.com/oauth/token

Use this endpoint to request an access token for the https://api.mapmydata.app audience.

Required request fields

Field	Description
`client_id`	OAuth client identifier
`client_secret`	OAuth client secret
`audience`	`https://api.mapmydata.app`
`grant_type`	`client_credentials`

Request access tokencurl

curl --request POST \
  --url https://dev-ij8d8xnp6zjae8hn.us.auth0.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{
    "client_id":"YOUR_CLIENT_ID",
    "client_secret":"YOUR_CLIENT_SECRET",
    "audience":"https://api.mapmydata.app",
    "grant_type":"client_credentials"
  }'

Successful token responsejson

{
  "access_token": "eyJ...",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Use token on API requestshttp

Authorization: Bearer YOUR_ACCESS_TOKEN

Quick start

1. Request a token

Authenticate against the OAuth token endpoint and retrieve a bearer token.

2. Call the catalog

Use the returned token to request product data from the protected catalog endpoints.

3. Retrieve the format you need

Browse product collections, fetch a single product, or request multiple products by explicit ID.

Quick start flowcurl

# 1) Request access token
curl --request POST \
  --url https://dev-ij8d8xnp6zjae8hn.us.auth0.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{
    "client_id":"YOUR_CLIENT_ID",
    "client_secret":"YOUR_CLIENT_SECRET",
    "audience":"https://api.mapmydata.app",
    "grant_type":"client_credentials"
  }'

# 2) List products
curl --request GET \
  --url 'https://api.mapmydata.app/products?page=1&limit=10&sort=price&order=asc' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

# 3) Fetch a single product
curl --request GET \
  --url https://api.mapmydata.app/products/prod_nrt3e91199 \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Health endpoint

GET /health

Returns a lightweight operational status response for platform and integration monitoring.

Example responsejson

{
  "ok": true,
  "message": "Product API is running"
}

List products

GET /products

Returns a paginated collection of products. Supports filtering, sorting, and keyword search to support browsing, incremental retrieval, and operational catalog workflows.

Supported query parameters

Parameter	Description	Example
`page`	Page number	`1`
`limit`	Page size	`25`
`sort`	Sort by `name`, `price`, `brand`, `category`, `inventory`, `updated_at`, or `sku`	`price`
`order`	`asc` or `desc`	`asc`
`brand`	Filter by brand	`Acme`
`category`	Filter by category	`Footwear`
`department`	Filter by department	`Women`
`active`	Filter by active status	`true`
`min_price`	Minimum price filter	`20`
`max_price`	Maximum price filter	`100`
`q`	Keyword search across selected fields	`trail`

Example requestcurl

curl --request GET \
  --url 'https://api.mapmydata.app/products?page=1&limit=25&brand=Acme&sort=price&order=asc' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Example responsejson

{
  "data": [
    {
      "id": "prod_nrt3e91199",
      "external_id": "ext_catalog_nrt_1001",
      "sku": "NRT-TRN-SLP-OCN",
      "name": "Trail Terrain Slip-On",
      "display_name": "Northstar Trail Terrain Slip-On - Ocean",
      "brand": "Northstar",
      "category": "Apparel",
      "department": "Women",
      "price": 23.49,
      "currency": "USD",
      "inventory": 47,
      "active": true
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 1000,
    "has_next": true,
    "has_prev": false
  },
  "sort": {
    "field": "price",
    "order": "asc"
  },
  "applied_filters": {
    "brand": "Acme",
    "category": null,
    "department": null,
    "active": null,
    "min_price": null,
    "max_price": null,
    "q": null
  }
}

Get product by ID

GET /products/:id

Returns the complete product object for a specific internal product identifier.

Example requestcurl

curl --request GET \
  --url https://api.mapmydata.app/products/prod_nrt3e91199 \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Example responsejson

{
  "data": {
    "id": "prod_nrt3e91199",
    "external_id": "ext_catalog_nrt_1001",
    "sku": "NRT-TRN-SLP-OCN",
    "name": "Trail Terrain Slip-On",
    "display_name": "Northstar Trail Terrain Slip-On - Ocean",
    "brand": "Northstar",
    "category": "Apparel",
    "department": "Women",
    "price": 23.49,
    "currency": "USD",
    "inventory": 47,
    "active": true,
    "tags": ["northstar", "apparel", "summer", "blue"],
    "attributes": {
      "color": "blue",
      "color_label": "Ocean",
      "size": "M",
      "material": "mesh",
      "season": "Summer",
      "dimensions": {
        "width_in": 8.5,
        "height_in": 10.4,
        "depth_in": 2.25
      }
    },
    "pricing": {
      "list": 33.99,
      "sale": 23.49,
      "markdown": false,
      "promotions": [
        {
          "code": "PROMO1",
          "description": "Member savings",
          "amount_off": 7,
          "stackable": false
        }
      ]
    },
    "variants": [
      {
        "variant_id": "var_nrt3e9a",
        "sku": "NRT-TRN-SLP-OCN-M",
        "color": "blue",
        "size": "M"
      }
    ],
    "audit": {
      "created_at": "2025-01-22T00:00:00.000Z",
      "updated_at": "2026-01-22T00:00:00.000Z"
    }
  }
}

Bulk fetch products

GET /products/bulk?ids=...

Retrieves multiple products in a single request using a comma-separated list of product IDs. This endpoint is useful for cart hydration, recommendation retrieval, merchandising workflows, and multi-record data ingestion.

Example requestcurl

curl --request GET \
  --url 'https://api.mapmydata.app/products/bulk?ids=prod_nrt3e91199,prod_smt3eb11aa,prod_evr3ec11bb' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Example responsejson

{
  "data": [
    {
      "id": "prod_nrt3e91199",
      "sku": "NRT-TRN-SLP-OCN",
      "name": "Trail Terrain Slip-On"
    },
    {
      "id": "prod_smt3eb11aa",
      "sku": "SMT-TRN-RUN-CRM",
      "name": "Horizon Terrain Runner"
    }
  ],
  "missing_ids": ["prod_missing123"],
  "requested_count": 3,
  "returned_count": 2
}

Product model

Product payloads are intentionally structured to support modern downstream uses including storefront rendering, synchronization pipelines, metadata extraction, data mapping, and schema-aware integrations.

Field	Type	Description
`id`	string	Internal product identifier
`external_id`	string	External source-system identifier
`sku`	string	Merchant-facing SKU
`name`	string	Product name
`display_name`	string	Display-ready product name
`attributes`	object	Structured product attributes
`pricing`	object	List, sale, and promotion metadata
`availability`	object	Online, pickup, warehouse, and store inventory data
`media`	object	Primary image, gallery, and video content
`variants`	array	Variant records with identifiers and pricing
`reviews`	array	Review metadata and nested author details
`audit`	object	Creation, update, and source metadata

Example nested paths

attributes.dimensions.width_in pricing.promotions[0].code availability.inventory_by_location[1].quantity media.gallery[0].metadata.angle variants[0].sku reviews[0].author.badges[1] audit.source.batch

Error responses

401 Unauthorized

Returned when the access token is missing, malformed, expired, or invalid for the requested audience.

Examplejson

{
  "error": "unauthorized",
  "message": "Invalid audience"
}

404 Not Found

Returned when a requested product ID does not exist in the catalog.

Examplejson

{
  "error": "product_not_found",
  "id": "prod_unknown"
}

400 Bad Request

Returned when required request parameters are missing or malformed.

Examplejson

{
  "error": "missing_ids",
  "message": "Provide ids as a comma-separated query param."
}

Commerce-grade product data, built for modern integrations.

Overview

Built for integration flows

Rich, nested catalog structure

Authentication

Token endpoint

Required request fields

Quick start

1. Request a token

2. Call the catalog

3. Retrieve the format you need

Health endpoint

List products

Supported query parameters

Get product by ID

Bulk fetch products

Product model

Example nested paths

Error responses

401 Unauthorized

404 Not Found

400 Bad Request