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

# Initmerchantsession

`POST /v2/giftcards/merchants/session`

## Request

- Base URL: `https://api.loyalty.dog`
- URL: `https://api.loyalty.dog/v2/giftcards/merchants/session`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/loyalty/apis/loyaltydog/docs/v2/giftcards/merchants/session/post.ts> (a function with typed inputs; its response is checked against the schema)

### 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' | 'square' | 'lightspeed'
  - `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

## Changes

- **2026-09-08** `a15e6601ef8d`: 2 info
  - added the new `lightspeed` enum value to the request property `platform`
  - added the new `square` enum value to the request property `platform`

[Operation history](https://skmtc.dev/loyalty/apis/loyaltydog/changes/v2/giftcards/merchants/session/post.md)

---

[API](https://skmtc.dev/loyalty/apis/loyaltydog.md) - [All operations](https://skmtc.dev/loyalty/apis/loyaltydog/llms.txt) - [OpenAPI document](https://skmtc.dev/loyalty/apis/loyaltydog/revisions/5803242b0551?raw)