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. Does not require authentication.

Example responsejson

{
  "ok": true,
  "message": "Demo 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`
`inventory`	Exact inventory quantity match	`47`
`min_inventory`	Minimum inventory quantity filter	`10`
`max_inventory`	Maximum inventory quantity filter	`100`

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,
    "inventory": null,
    "min_inventory": null,
    "max_inventory": 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"],
    "image_url": "https://images.mapmydata.app/products/prod_nrt3e91199/primary.jpg",
    "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
      },
      "care": {
        "washable": true,
        "wash_method": "machine_wash",
        "dryer_safe": false
      },
      "rating": {
        "average": 4.2,
        "count": 1011
      }
    },
    "pricing": {
      "list": 33.99,
      "sale": 23.49,
      "markdown": true,
      "promotions": [
        {
          "code": "PROMO1",
          "description": "Seasonal markdown",
          "amount_off": 7,
          "stackable": false
        }
      ]
    },
    "availability": {
      "online": true,
      "store_pickup": true,
      "backorderable": false,
      "inventory_by_location": [
        { "location_id": "store_dallas", "location_type": "store", "quantity": 6 },
        { "location_id": "store_chicago", "location_type": "store", "quantity": 9 },
        { "location_id": "wh_tx_01", "location_type": "warehouse", "quantity": 45 }
      ]
    },
    "media": {
      "primary_image": {
        "url": "https://images.mapmydata.app/products/prod_nrt3e91199/primary.jpg",
        "alt_text": "Northstar Trail Terrain Slip-On - Ocean primary image"
      },
      "gallery": [
        {
          "type": "image",
          "url": "https://images.mapmydata.app/products/prod_nrt3e91199/1.jpg",
          "sort_order": 1,
          "metadata": { "angle": "front", "background": "white" }
        },
        {
          "type": "image",
          "url": "https://images.mapmydata.app/products/prod_nrt3e91199/2.jpg",
          "sort_order": 2,
          "metadata": { "angle": "side", "background": "white" }
        }
      ],
      "videos": [
        {
          "url": "https://videos.mapmydata.app/products/prod_nrt3e91199/overview.mp4",
          "duration_seconds": 30,
          "captions": { "en": true, "es": true }
        }
      ]
    },
    "variants": [
      {
        "variant_id": "var_nrt3e9a",
        "sku": "NRT-TRN-SLP-OCN-M",
        "color": "blue",
        "size": "M",
        "inventory": 6,
        "pricing": { "list": 33.99, "sale": 23.49 },
        "identifiers": { "upc": "000100101", "ean": "1000000100101" }
      }
    ],
    "related_products": [
      { "relationship_type": "cross_sell", "product_id": "prod_nrt3ea7ba", "score": 0.9 },
      { "relationship_type": "upsell", "product_id": "prod_nrt3eb8cb", "score": 0.8 }
    ],
    "reviews": [
      {
        "review_id": "rev_1001_1",
        "rating": 5,
        "title": "Great product",
        "author": {
          "id": "user_1001_1",
          "name": "Demo User 1001A",
          "badges": ["verified_buyer", "top_reviewer"]
        },
        "content": {
          "summary": "Really liked the fit and finish.",
          "pros": ["Comfortable", "Stylish", "Good value"],
          "cons": ["Runs slightly small"]
        }
      }
    ],
    "seo": {
      "slug": "northstar-trail-terrain-slip-on-blue",
      "meta": {
        "title": "Northstar Trail Terrain Slip-On - Ocean | Northstar",
        "description": "Shop Northstar Trail Terrain Slip-On - Ocean from Northstar in Apparel."
      }
    },
    "compliance": {
      "country_of_origin": "VN",
      "restricted_states": [],
      "hazardous_material": false
    },
    "audit": {
      "created_at": "2025-01-22T00:00:00.000Z",
      "updated_at": "2026-01-22T00:00:00.000Z",
      "source": {
        "system": "mapmydata-demo-seeder",
        "version": "1.0.0",
        "batch": "seed_batch_40"
      }
    }
  }
}

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
`brand`	string	Brand name
`category`	string	Product category
`department`	string	Department (Men, Women, Kids, Unisex)
`price`	number	Current sale price
`currency`	string	ISO 4217 currency code (e.g. `USD`)
`inventory`	integer	Total inventory quantity
`active`	boolean	Whether the product is active
`tags`	string[]	Keyword tags for search and filtering
`image_url`	string	Top-level primary image URL shortcut
`attributes`	object	Color, size, material, season, dimensions, care instructions, and rating summary
`attributes.care`	object	Wash and care instructions (`washable`, `wash_method`, `dryer_safe`)
`attributes.rating`	object	Aggregate rating (`average`, `count`)
`pricing`	object	List price, sale price, markdown flag, and promotions array
`availability`	object	Online, store pickup, backorder availability, and per-location inventory
`availability.store_pickup`	boolean	Whether in-store pickup is available
`availability.backorderable`	boolean	Whether the product can be backordered
`availability.inventory_by_location`	array	Per-location inventory with `location_id`, `location_type`, and `quantity`
`media`	object	Primary image object, gallery array, and videos array
`media.primary_image`	object	Primary image `url` and `alt_text`
`media.gallery`	array	Gallery items with `type`, `url`, `sort_order`, and `metadata`
`media.videos`	array	Video items with `url`, `duration_seconds`, and `captions`
`variants`	array	Variant records with size, color, inventory, per-variant pricing, and UPC/EAN identifiers
`related_products`	array	Cross-sell and upsell references with relationship type and relevance score
`reviews`	array	Review records with rating, author (id, name, badges), and structured content (summary, pros, cons)
`seo`	object	URL slug and meta title/description for SEO
`compliance`	object	Country of origin, restricted states, and hazardous material flag
`audit`	object	Creation and update timestamps, and source system metadata

Example nested paths

attributes.dimensions.width_in attributes.care.wash_method attributes.rating.average pricing.promotions[0].code availability.inventory_by_location[0].location_type media.primary_image.url media.gallery[0].metadata.angle media.videos[0].duration_seconds variants[0].identifiers.upc variants[0].pricing.sale related_products[0].product_id reviews[0].content.pros seo.meta.title compliance.country_of_origin audit.source.batch

JSON schema

Full JSON Schema (Draft-07) for the product response object. All nested objects and arrays are included.

Product schemajson

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Product",
  "type": "object",
  "properties": {
    "id":           { "type": "string",  "description": "Internal product identifier" },
    "external_id":  { "type": "string",  "description": "Source system identifier" },
    "sku":          { "type": "string",  "description": "Merchant-facing SKU" },
    "name":         { "type": "string",  "description": "Product name" },
    "display_name": { "type": "string",  "description": "Display-ready product name" },
    "brand":        { "type": "string" },
    "category":     { "type": "string" },
    "department":   { "type": "string" },
    "price":        { "type": "number" },
    "currency":     { "type": "string",  "example": "USD" },
    "inventory":    { "type": "integer" },
    "active":       { "type": "boolean" },
    "tags":         { "type": "array", "items": { "type": "string" } },
    "image_url":    { "type": "string", "format": "uri", "description": "Top-level primary image URL" },

    "attributes": {
      "type": "object",
      "properties": {
        "color":       { "type": "string" },
        "color_label": { "type": "string" },
        "size":        { "type": "string" },
        "material":    { "type": "string" },
        "season":      { "type": "string" },
        "dimensions": {
          "type": "object",
          "properties": {
            "width_in":  { "type": "number" },
            "height_in": { "type": "number" },
            "depth_in":  { "type": "number" }
          }
        },
        "care": {
          "type": "object",
          "properties": {
            "washable":    { "type": "boolean" },
            "wash_method": { "type": "string", "enum": ["machine_wash", "hand_wash"] },
            "dryer_safe":  { "type": "boolean" }
          }
        },
        "rating": {
          "type": "object",
          "properties": {
            "average": { "type": "number", "minimum": 1, "maximum": 5 },
            "count":   { "type": "integer" }
          }
        }
      }
    },

    "pricing": {
      "type": "object",
      "properties": {
        "list":     { "type": "number" },
        "sale":     { "type": "number" },
        "markdown": { "type": "boolean" },
        "promotions": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "code":        { "type": "string" },
              "description": { "type": "string" },
              "amount_off":  { "type": "number" },
              "stackable":   { "type": "boolean" }
            }
          }
        }
      }
    },

    "availability": {
      "type": "object",
      "properties": {
        "online":        { "type": "boolean" },
        "store_pickup":  { "type": "boolean" },
        "backorderable": { "type": "boolean" },
        "inventory_by_location": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "location_id":   { "type": "string" },
              "location_type": { "type": "string", "enum": ["store", "warehouse"] },
              "quantity":      { "type": "integer" }
            }
          }
        }
      }
    },

    "media": {
      "type": "object",
      "properties": {
        "primary_image": {
          "type": "object",
          "properties": {
            "url":      { "type": "string", "format": "uri" },
            "alt_text": { "type": "string" }
          }
        },
        "gallery": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "type":       { "type": "string", "enum": ["image"] },
              "url":        { "type": "string", "format": "uri" },
              "sort_order": { "type": "integer" },
              "metadata": {
                "type": "object",
                "properties": {
                  "angle":      { "type": "string" },
                  "background": { "type": "string" }
                }
              }
            }
          }
        },
        "videos": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "url":              { "type": "string", "format": "uri" },
              "duration_seconds": { "type": "integer" },
              "captions": {
                "type": "object",
                "additionalProperties": { "type": "boolean" }
              }
            }
          }
        }
      }
    },

    "variants": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "variant_id": { "type": "string" },
          "sku":        { "type": "string" },
          "color":      { "type": "string" },
          "size":       { "type": "string" },
          "inventory":  { "type": "integer" },
          "pricing": {
            "type": "object",
            "properties": {
              "list": { "type": "number" },
              "sale": { "type": "number" }
            }
          },
          "identifiers": {
            "type": "object",
            "properties": {
              "upc": { "type": "string" },
              "ean": { "type": "string" }
            }
          }
        }
      }
    },

    "related_products": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "relationship_type": { "type": "string", "enum": ["cross_sell", "upsell"] },
          "product_id":        { "type": "string" },
          "score":             { "type": "number", "minimum": 0, "maximum": 1 }
        }
      }
    },

    "reviews": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "review_id": { "type": "string" },
          "rating":    { "type": "number", "minimum": 1, "maximum": 5 },
          "title":     { "type": "string" },
          "author": {
            "type": "object",
            "properties": {
              "id":       { "type": "string" },
              "name":     { "type": "string" },
              "badges":   { "type": "array", "items": { "type": "string" } }
            }
          },
          "content": {
            "type": "object",
            "properties": {
              "summary": { "type": "string" },
              "pros":    { "type": "array", "items": { "type": "string" } },
              "cons":    { "type": "array", "items": { "type": "string" } }
            }
          }
        }
      }
    },

    "seo": {
      "type": "object",
      "properties": {
        "slug": { "type": "string" },
        "meta": {
          "type": "object",
          "properties": {
            "title":       { "type": "string" },
            "description": { "type": "string" }
          }
        }
      }
    },

    "compliance": {
      "type": "object",
      "properties": {
        "country_of_origin":  { "type": "string" },
        "restricted_states":  { "type": "array", "items": { "type": "string" } },
        "hazardous_material": { "type": "boolean" }
      }
    },

    "audit": {
      "type": "object",
      "properties": {
        "created_at": { "type": "string", "format": "date-time" },
        "updated_at": { "type": "string", "format": "date-time" },
        "source": {
          "type": "object",
          "properties": {
            "system":  { "type": "string" },
            "version": { "type": "string" },
            "batch":   { "type": "string" }
          }
        }
      }
    }
  }
}

Error responses

401 Unauthorized

Returned when the Authorization header is absent, or when the bearer token is malformed, expired, or has an invalid audience.

Missing tokenjson

{
  "error": "missing_bearer_token"
}

Invalid tokenjson

{
  "error": "unauthorized",
  "message": "Token expired"
}

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

JSON schema

Error responses

401 Unauthorized

404 Not Found

400 Bad Request