> ## Documentation Index
> Fetch the complete documentation index at: https://docs.loyalty.dog/llms.txt
> Use this file to discover all available pages before exploring further.

# Initmerchantsession

> ### Init or Refresh Merchant Session

Called by eposn-giftcards immediately after resolving a valid platform token.
Looks up the merchant by `(merchantId, platform)`.  If a record exists the
info is updated; if not, a new `GiftCardMerchant` document is created.

Locations are stored as embedded sub-documents.  If `locationId` is provided,
the matching location is upserted within the merchant document.

`programId` is stored **per location** — if supplied it will update only the
active location's `programId`, not a merchant-level field.

**Returns**:
- Full merchant context including the active location's `programId` so callers
  can build a session without an additional API round-trip.

**Status Codes**:
- 200: Merchant record created or updated successfully
- 401: HMAC authentication failed



## OpenAPI

````yaml https://api.loyalty.dog/openapi.json post /v2/giftcards/merchants/session
openapi: 3.1.0
info:
  title: LoyaltyDog
  description: >-

    Welcome to the LoyaltyDog API! This API provides access to our loyalty
    program features, allowing you to integrate with various platforms and
    manage your loyalty data.


    Want to query LoyaltyDog via an AI assistant (Claude, Cursor, Windsurf)? See
    the [MCP Integration guide](https://loyaltydog.ai/playground#mcp).
        
  termsOfService: https://loyalty.dog/loyalty-program-terms-service
  contact:
    name: LoyaltyDog Support
    url: https://loyalty.dog/contact-us
    email: support@loyalty.dog
  version: 1.0.1
servers:
  - url: https://api.loyalty.dog
    description: Production
security:
  - bearerAuth: []
paths:
  /v2/giftcards/merchants/session:
    post:
      tags:
        - Gift Card Merchants
      summary: Initmerchantsession
      description: >-
        ### Init or Refresh Merchant Session


        Called by eposn-giftcards immediately after resolving a valid platform
        token.

        Looks up the merchant by `(merchantId, platform)`.  If a record exists
        the

        info is updated; if not, a new `GiftCardMerchant` document is created.


        Locations are stored as embedded sub-documents.  If `locationId` is
        provided,

        the matching location is upserted within the merchant document.


        `programId` is stored **per location** — if supplied it will update only
        the

        active location's `programId`, not a merchant-level field.


        **Returns**:

        - Full merchant context including the active location's `programId` so
        callers
          can build a session without an additional API round-trip.

        **Status Codes**:

        - 200: Merchant record created or updated successfully

        - 401: HMAC authentication failed
      operationId: initMerchantSession_v2_giftcards_merchants_session_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitMerchantSessionRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantSessionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    InitMerchantSessionRequest:
      properties:
        appToken:
          type: string
          maxLength: 512
          minLength: 1
          title: Apptoken
        merchantId:
          type: string
          maxLength: 100
          minLength: 1
          title: Merchantid
          description: Platform-specific merchant/company identifier
        name:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: Name
          description: Human-readable merchant/company name
        platform:
          $ref: '#/components/schemas/PlatformProvider'
          default: eposnow
        locationId:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: Locationid
          description: Platform-specific location identifier
        locationName:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: Locationname
        programId:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: Programid
          description: Linked LoyaltyDog programme ID (per location)
        userId:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: Userid
          description: Optional LoyaltyDog User ID to link/onboard this merchant
        role:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: Role
          description: Role of the merchant
        cashierId:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: Cashierid
          description: Platform-specific cashier identifier
        terminalId:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: Terminalid
          description: Platform-specific terminal identifier
      type: object
      required:
        - appToken
        - merchantId
      title: InitMerchantSessionRequest
      description: |-
        Payload sent by eposn-giftcards after resolving a platform token.

        Fields are intentionally generic so that EPOS Now, Shopify, and future
        platforms all use the same endpoint.
    MerchantSessionResponse:
      properties:
        id:
          type: string
          title: Id
        merchantId:
          anyOf:
            - $ref: '#/components/schemas/PydanticObjectId'
            - type: 'null'
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        platform:
          type: string
          title: Platform
        programId:
          anyOf:
            - type: string
            - type: 'null'
          title: Programid
        active:
          type: boolean
          title: Active
        locationId:
          anyOf:
            - type: string
            - type: 'null'
          title: Locationid
        locationName:
          anyOf:
            - type: string
            - type: 'null'
          title: Locationname
        locations:
          items:
            $ref: '#/components/schemas/MerchantLocationResponse'
          type: array
          title: Locations
        cashierId:
          anyOf:
            - type: string
            - type: 'null'
          title: Cashierid
        terminalId:
          anyOf:
            - type: string
            - type: 'null'
          title: Terminalid
        role:
          anyOf:
            - type: string
            - type: 'null'
          title: Role
        sessionToken:
          anyOf:
            - type: string
            - type: 'null'
          title: Sessiontoken
      type: object
      required:
        - id
        - merchantId
        - name
        - platform
        - programId
        - active
        - locationId
        - locationName
        - locations
      title: MerchantSessionResponse
      description: |-
        Returned after a successful merchant session init or validation.

        Contains everything needed to populate the eposn-giftcards session
        without an additional core_api round-trip.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PlatformProvider:
      type: string
      enum:
        - eposnow
        - shopify
        - clover
        - wordpress
      title: PlatformProvider
    PydanticObjectId:
      type: string
      maxLength: 24
      minLength: 24
      pattern: ^[0-9a-f]{24}$
      example: 5eb7cf5a86d9755df3a6c593
    MerchantLocationResponse:
      properties:
        locationId:
          type: string
          title: Locationid
        locationName:
          anyOf:
            - type: string
            - type: 'null'
          title: Locationname
        lastSeenAt:
          anyOf:
            - type: string
            - type: 'null'
          title: Lastseenat
        programId:
          anyOf:
            - type: string
            - type: 'null'
          title: Programid
      type: object
      required:
        - locationId
        - locationName
        - lastSeenAt
        - programId
      title: MerchantLocationResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT access token obtained from POST /v2/token.

````