makeup.land

Browse the catalog with tag, brand, near_hex (color-distance shade match), hue_family, and sort filters. Bearer becomes required when passing `phone` (rewards projection).

{
  "type": "object",
  "properties": {
    "q": {
      "description": "Natural-language query. Cross-lingual semantic search — `lipstick`, `שפתון`, `lápiz labial` each return Hebrew-tagged lipsticks (the sets may differ across languages but are semantically equivalent). Prefer this over `tag` for any category lookup that isn't already in exact Hebrew.",
      "type": "string"
    },
    "tag": {
      "description": "Filter by an EXACT tag string (case-insensitive, whitespace-trimmed; no translation, no substring). Tags are Hebrew (e.g. שפתון, ביוטי, עיניים, שפתיים). English category names rarely match — use `q` instead for natural-language queries.",
      "type": "string"
    },
    "brand": {
      "description": "Filter by brand slug or name.",
      "type": "string"
    },
    "near_hex": {
      "description": "Target hex color for shade matching ranked by color distance (redmean-weighted RGB, not CIE ΔE). Examples: '#C2185B', 'E8D4B8'. Each returned product carries a `shade_match: {hex, delta_e}` field with the closest variant swatch and its perceptual distance.",
      "type": "string",
      "pattern": "^#?[0-9A-Fa-f]{6}$"
    },
    "hue_family": {
      "description": "Post-filter on hue family. Must be paired with another filter. `neutral` is not a V1 hue family and is ignored.",
      "type": "string",
      "enum": [
        "red",
        "orange",
        "yellow",
        "green",
        "blue",
        "purple",
        "pink",
        "brown",
        "neutral"
      ]
    },
    "sort": {
      "description": "Sort order. Default: relevance.",
      "type": "string",
      "enum": [
        "price_asc",
        "price_desc",
        "popularity",
        "rating",
        "relevance"
      ]
    },
    "limit": {
      "description": "Page size, default 10.",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "page": {
      "description": "1-indexed page number.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "phone": {
      "description": "E.164 phone for per-customer rewards projection. REQUIRES bearer auth. Omit for anonymous catalog browse.",
      "type": "string",
      "pattern": "^\\+\\d{6,15}$"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Return every brand with product counts and slugs. Bearer required.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Check a gift card's remaining balance using its code. Public endpoint — no bearer required (gated on knowledge of the code).

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "minLength": 1,
      "description": "Gift card code (full string as printed on the card)."
    }
  },
  "required": [
    "code"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Return tags, ℳ-credit balance, M Club tier for the customer with the given E.164 phone. Bearer required.

{
  "type": "object",
  "properties": {
    "phone": {
      "type": "string",
      "pattern": "^\\+\\d{6,15}$",
      "description": "E.164 phone number, e.g. +972501234567."
    }
  },
  "required": [
    "phone"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Return the customer's most-recently-updated cart with per-line and total reward projection. Bearer + phone required.

{
  "type": "object",
  "properties": {
    "phone": {
      "type": "string",
      "pattern": "^\\+\\d{6,15}$",
      "description": "E.164 phone selecting the customer whose cart to return."
    }
  },
  "required": [
    "phone"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Recent orders with 6-axis status (order / payment / fulfillment / delivery / return / review). Bearer + phone required.

{
  "type": "object",
  "properties": {
    "phone": {
      "type": "string",
      "pattern": "^\\+\\d{6,15}$",
      "description": "E.164 phone selecting the customer."
    },
    "limit": {
      "description": "Page size.",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "page": {
      "description": "Ignored: /api/v1/orders has no paging and returns the most recent `limit` orders.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "phone"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Pending payment_requests on the customer's unpaid orders. Bearer + phone required.

{
  "type": "object",
  "properties": {
    "phone": {
      "type": "string",
      "pattern": "^\\+\\d{6,15}$",
      "description": "E.164 phone selecting the customer."
    }
  },
  "required": [
    "phone"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Top deal projections based on the customer's tags + M Club tier. Bearer + phone required.

{
  "type": "object",
  "properties": {
    "phone": {
      "type": "string",
      "pattern": "^\\+\\d{6,15}$",
      "description": "E.164 phone selecting the customer."
    },
    "limit": {
      "description": "Ignored: /api/v1/customers/best-deals takes no limit.",
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    }
  },
  "required": [
    "phone"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}