---
title: "Savemerchantsettings"
method: PUT
path: "/v2/giftcards/merchants/settings"
tags: ["Gift Card Merchants"]
---

# Savemerchantsettings

`PUT /v2/giftcards/merchants/settings`

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

## Headers

- `X-Eposn-Merchant-Token` string, nullable

## Request body

- SaveMerchantSettingsRequest — Payload for saving per-location merchant settings.
  - `programId` string, nullable — LoyaltyDog programme ID to link to the active location
  - `locationId` string, nullable — Location to update; defaults to the first location if omitted
  - `merchantId` string, nullable — User ID of the merchant

## Response `200`

Successful Response

- MerchantSessionResponse — 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.
  - `id` string, required
  - `merchantId` string, required
  - `name` string, nullable, required
  - `platform` string, required
  - `programId` string, nullable, required
  - `active` boolean, required
  - `locationId` string, nullable, required
  - `locationName` string, nullable, required
  - `locations` MerchantLocationResponse[], required
    - `locationId` string, required
    - `locationName` string, nullable, required
    - `lastSeenAt` string, nullable, required
    - `programId` string, nullable, required
  - `cashierId` string, nullable
  - `terminalId` string, nullable
  - `role` string, nullable
  - `sessionToken` string, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/loyalty/apis/loyaltydog.md) · [All operations](https://skmtc.net/loyalty/apis/loyaltydog/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/loyalty/loyaltydog/versions/42b7b22af2b6/schema)