> ## 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.

# Savemerchantsettings

> ### Save Per-Location Merchant Settings

Saves the `programId` for a specific merchant location.  Merchant identity
is resolved from the validated `X-Eposn-Merchant-Token` session, so
ownership is checked by confirming the programme belongs to that user.

Validation steps:
1. Parse and look up the `programId` — must exist in the Programme collection.
2. Confirm the programme type is ``GIFT_CARD``.
3. Confirm the programme's ``userId`` matches the authenticated user.
4. Upsert the `programId` onto the target location of the matching
   ``GiftCardMerchant`` document (matched by ``merchantId == str(user.id)``).

**Status Codes**:
- 200: Settings saved successfully
- 400: programId is invalid or wrong type
- 401: Not authenticated
- 403: Programme does not belong to this user
- 404: Programme or merchant not found



## OpenAPI

````yaml https://api.loyalty.dog/openapi.json put /v2/giftcards/merchants/settings
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/settings:
    put:
      tags:
        - Gift Card Merchants
      summary: Savemerchantsettings
      description: >-
        ### Save Per-Location Merchant Settings


        Saves the `programId` for a specific merchant location.  Merchant
        identity

        is resolved from the validated `X-Eposn-Merchant-Token` session, so

        ownership is checked by confirming the programme belongs to that user.


        Validation steps:

        1. Parse and look up the `programId` — must exist in the Programme
        collection.

        2. Confirm the programme type is ``GIFT_CARD``.

        3. Confirm the programme's ``userId`` matches the authenticated user.

        4. Upsert the `programId` onto the target location of the matching
           ``GiftCardMerchant`` document (matched by ``merchantId == str(user.id)``).

        **Status Codes**:

        - 200: Settings saved successfully

        - 400: programId is invalid or wrong type

        - 401: Not authenticated

        - 403: Programme does not belong to this user

        - 404: Programme or merchant not found
      operationId: saveMerchantSettings_v2_giftcards_merchants_settings_put
      parameters:
        - name: X-Eposn-Merchant-Token
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Eposn-Merchant-Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaveMerchantSettingsRequest'
      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:
    SaveMerchantSettingsRequest:
      properties:
        programId:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: Programid
          description: LoyaltyDog programme ID to link to the active location
        locationId:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: Locationid
          description: Location to update; defaults to the first location if omitted
        merchantId:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: Merchantid
          description: User ID of the merchant
      type: object
      title: SaveMerchantSettingsRequest
      description: Payload for saving per-location merchant settings.
    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
    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.

````