---
title: "Initmerchantsession"
method: POST
path: "/v2/giftcards/merchants/session"
tags: ["Gift Card Merchants"]
---

# Initmerchantsession

`POST /v2/giftcards/merchants/session`

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

## Request body

- InitMerchantSessionRequest — 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.
  - `appToken` string, required
  - `merchantId` string, required — Platform-specific merchant/company identifier
  - `name` string, nullable — Human-readable merchant/company name
  - `platform` 'eposnow' | 'shopify' | 'clover' | 'wordpress'
  - `locationId` string, nullable — Platform-specific location identifier
  - `locationName` string, nullable
  - `programId` string, nullable — Linked LoyaltyDog programme ID (per location)
  - `userId` string, nullable — Optional LoyaltyDog User ID to link/onboard this merchant
  - `role` string, nullable — Role of the merchant
  - `cashierId` string, nullable — Platform-specific cashier identifier
  - `terminalId` string, nullable — Platform-specific terminal identifier

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