---
updatedAt: 2026-04-22T22:43:29.000Z
agentTools:
  projectIndex: https://developers.akahu.nz/llms.txt
---

# Get merchant

Retrieve details for a merchant.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Genie transaction enrichment API",
    "version": "1.0.0",
    "description": "Applications that use Akahu for bank account connectivity can use our transactions API to get high quality enriched transactions that include merchant and category information. We've built the Genie API to expose Akahu's transaction enrichment engine for applications that instead source raw transaction data themselves.\n\nGenie is entirely separate from the core Akahu API and does not require an Akahu App ID Token or App Secret to access. If you're keen to get your hands on an API key to try it out, get in touch with us at hello@akahu.nz.\n"
  },
  "x-samples-languages": [
    "shell",
    "csharp",
    "java",
    "node",
    "python",
    "go",
    "php",
    "ruby"
  ],
  "servers": [
    {
      "url": "https://api.genie.akahu.io/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Token based API authentication"
      }
    },
    "schemas": {
      "GenieTag": {
        "type": "string",
        "description": "A tag applied to an outlet or merchant, indicating a specific attribute that applies to that entity.",
        "enum": [
          "subscription",
          "closed"
        ]
      },
      "GenieCoordinates": {
        "type": "object",
        "description": "Latitude/longitude location coordinates.",
        "required": [
          "lat",
          "lon"
        ],
        "properties": {
          "lat": {
            "type": "number"
          },
          "lon": {
            "type": "number"
          }
        },
        "example": {
          "lat": -36.848461,
          "lon": 174.763336
        }
      },
      "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"
          }
        },
        "example": {
          "street": "125 Queen Street",
          "suburb": "Auckland CBD",
          "city": "Auckland",
          "region": "Auckland",
          "country": "New Zealand",
          "postal_code": "0620"
        }
      },
      "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": "#/components/schemas/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": "#/components/schemas/GenieAddress"
              }
            ]
          }
        },
        "example": {
          "accuracy": "establishment",
          "formatted": "12 Hastwell Street, Greytown 5712, New Zealand",
          "address": {
            "street": "12 Hastwell Street",
            "city": "Greytown",
            "region": "Wellington",
            "country": "New Zealand",
            "postal_code": "5712"
          },
          "coordinates": {
            "lat": -41.0809289,
            "lon": 175.4589657
          }
        }
      },
      "GenieMerchant": {
        "type": "object",
        "description": "A merchant match result from Genie.",
        "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": "#/components/schemas/GenieLocation"
              }
            ]
          },
          "tags": {
            "type": "array",
            "description": "Tags that apply to the merchant. For example, to indicate that the merchant provides a subscription service.",
            "items": {
              "$ref": "#/components/schemas/GenieTag"
            }
          }
        },
        "example": {
          "_id": "merchant_cjipiuvdk000lbpzytryqtjkv",
          "name": "FreshChoice",
          "logo": "https://cdn.akahu.nz/logos/merchants/merchant_cjipiuvdk000lbpzytryqtjkv",
          "website": "https://www.freshchoice.co.nz",
          "nzbn": "9429040683379",
          "tags": []
        }
      },
      "GenieErrorResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "message": {
            "type": "string",
            "description": "A description of the error that has occurred"
          }
        },
        "required": [
          "success",
          "message"
        ]
      }
    }
  },
  "paths": {
    "/merchants/{id}": {
      "get": {
        "summary": "Get merchant",
        "description": "Retrieve details for a merchant.",
        "operationId": "GenieGetMerchant",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The merchant identifier",
            "schema": {
              "type": "string"
            }
          }
        ],
        "tags": [
          "Merchants"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "item": {
                      "$ref": "#/components/schemas/GenieMerchant"
                    }
                  },
                  "required": [
                    "success",
                    "item"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenieErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenieErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenieErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate Limiting",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenieErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenieErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  }
}
```