GenieMerchant

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/akahu/main/json-schema/akahu-genie-merchant-schema.json",
  "title": "GenieMerchant",
  "description": "A merchant match result from Genie.",
  "x-generated": "2026-10-27",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/akahu-genie-transaction-enrichment-api-openapi.yml#/components/schemas/GenieMerchant",
  "type": "object",
  "required": [
    "_id",
    "name",
    "logo"
  ],
  "properties": {
    "_id": {
      "type": "string",
      "description": "The unique merchant identifier."
    },
    "name": {
      "type": "string",
      "description": "The merchant's name (trading name)."
    },
    "logo": {
      "type": "string",
      "description": "A URL referencing the merchant's logo. If no logo is available, a placeholder image is provided."
    },
    "logo_is_placeholder": {
      "type": "boolean",
      "description": "A boolean flag, set to `true` if the `logo` URL points to a placeholder image rather than the merchant's real logo (i.e. there is no logo available for this merchant). This flag may be useful if you would prefer not to display placeholder logos or replace them with your own."
    },
    "website": {
      "type": "string",
      "description": "The URL for the merchant's website."
    },
    "phone": {
      "type": "string",
      "description": "The merchant's phone number."
    },
    "nzbn": {
      "type": "string",
      "description": "The merchant's NZBN (New Zealand Business Number)."
    },
    "location": {
      "description": "The merchant's location.",
      "allOf": [
        {
          "$ref": "#/$defs/GenieLocation"
        }
      ]
    },
    "tags": {
      "type": "array",
      "description": "Tags that apply to the merchant. For example, to indicate that the merchant provides a subscription service.",
      "items": {
        "$ref": "#/$defs/GenieTag"
      }
    }
  },
  "$defs": {
    "GenieAddress": {
      "type": "object",
      "required": [
        "street",
        "city",
        "region",
        "country",
        "postal_code"
      ],
      "properties": {
        "street": {
          "type": "string"
        },
        "suburb": {
          "type": "string"
        },
        "city": {
          "type": "string"
        },
        "region": {
          "type": "string"
        },
        "country": {
          "type": "string"
        },
        "postal_code": {
          "type": "string"
        }
      }
    },
    "GenieCoordinates": {
      "type": "object",
      "description": "Latitude/longitude location coordinates.",
      "required": [
        "lat",
        "lon"
      ],
      "properties": {
        "lat": {
          "type": "number"
        },
        "lon": {
          "type": "number"
        }
      }
    },
    "GenieLocation": {
      "type": "object",
      "description": "A physical location.",
      "required": [
        "accuracy",
        "formatted",
        "coordinates"
      ],
      "properties": {
        "accuracy": {
          "type": "string",
          "enum": [
            "country",
            "region",
            "locality",
            "sublocality",
            "establishment"
          ]
        },
        "formatted": {
          "type": "string"
        },
        "coordinates": {
          "$ref": "#/$defs/GenieCoordinates"
        },
        "address": {
          "description": "The address fields in a structured format. This is available on almost all establishment-level locations, however it may occasionally be missing,",
          "allOf": [
            {
              "$ref": "#/$defs/GenieAddress"
            }
          ]
        }
      }
    },
    "GenieTag": {
      "type": "string",
      "description": "A tag applied to an outlet or merchant, indicating a specific attribute that applies to that entity.",
      "enum": [
        "subscription",
        "closed"
      ]
    }
  }
}