Akahu Merchants API

openapi: 3.2.0
info:
  title: Genie transaction enrichment Merchants 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.


    Genie 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.'
servers:
- url: https://api.genie.akahu.io/v1
tags:
- name: Merchants
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'
components:
  schemas:
    GenieErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
          - false
        message:
          type: string
          description: A description of the error that has occurred
      required:
      - success
      - message
    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'
    GenieTag:
      type: string
      description: A tag applied to an outlet or merchant, indicating a specific attribute that applies to that entity.
      enum:
      - subscription
      - closed
    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: []
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Token based API authentication
x-samples-languages:
- shell
- csharp
- java
- node
- python
- go
- php
- ruby
x-provenance:
  method: searched
  source: https://developers.akahu.nz/reference
  harvested: '2026-10-26'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://developers.akahu.nz/reference/geniegetcategory.md
  - https://developers.akahu.nz/reference/geniegetmerchant.md
  - https://developers.akahu.nz/reference/geniegetoutlet.md
  - https://developers.akahu.nz/reference/geniegetpublickey.md
  - https://developers.akahu.nz/reference/geniesearch.md
  - https://developers.akahu.nz/reference/post_feedback.md
  merge:
    pages: 6
    deduped: 22
    conflicts_kept_first: 0