Gift cards (admin API)

Admin routes of the gift cards module. Every route needs a staff session and the permission named on it; send X-Resolve-Locale: false to receive every locale of a translatable field for editing.

GET /v1/admin/gift-cards

List gift cards

Parameters:

• isActive in query (boolean, optional).
• page in query (number, min 1, optional).
• pageSize in query (number, min 1, optional).
• purchasedBy in query (string, optional).
• recipientEmail in query (string, optional).
• sortBy in query (string, optional).
• sortOrder in query ("asc", "desc", optional).

Responses:

• 200: Gift cards retrieved.
• 401: Unauthorized.
• 403: Insufficient permissions.

POST /v1/admin/gift-cards

Issue gift card

Request body: CreateGiftCardAdminDto.

Responses:

• 201: Gift card issued.
• 400: Invalid input.
• 401: Unauthorized.
• 403: Insufficient permissions.

GET /v1/admin/gift-cards/{id}

Get gift card by ID

Parameters:

• id in path (string, required).

Responses:

• 200: Gift card retrieved.
• 401: Unauthorized.
• 403: Insufficient permissions.
• 404: Gift card not found.

PATCH /v1/admin/gift-cards/{id}

Update gift card

Parameters:

• id in path (string, required).

Request body: UpdateGiftCardAdminDto.

Responses:

• 200: Gift card updated.
• 400: Invalid input.
• 401: Unauthorized.
• 403: Insufficient permissions.
• 404: Gift card not found.

POST /v1/admin/gift-cards/{id}/adjust

Adjust gift card balance

Parameters:

• id in path (string, required).

Request body: AdjustGiftCardBalanceDto.

Responses:

• 200: Balance adjusted.
• 400: Invalid input (zero delta, overdraw, inactive).
• 401: Unauthorized.
• 403: Insufficient permissions.
• 404: Gift card not found.

POST /v1/admin/gift-cards/{id}/resend

Resend gift card email

Parameters:

• id in path (string, required).

Responses:

• 200: Email queued.
• 400: No recipient on file / card inactive.
• 401: Unauthorized.
• 403: Insufficient permissions.
• 404: Gift card not found.

Schemas

AdjustGiftCardBalanceDto

• amount (number, required).
• reason (string, min length 3, max length 500, required).
• referenceId (string, max length 128, optional).

CreateGiftCardAdminDto

• initialBalance (number, min 1, required).
• currency (string, pattern ^[A-Z]{3}$, required).
• code (string, pattern ^[A-Z0-9]{8,20}$, optional).
• recipientEmail (string, email, optional).
• recipientName (string, max length 100, optional).
• personalMessage (TranslatableDto, optional).
• purchasedBy (string, optional).
• expiresAt (string, optional).
• isActive (boolean, optional).

TranslatableDto

• fr (string, optional).
• en (string, optional).
• ar (string, optional).
• default (string, required).

UpdateGiftCardAdminDto

• isActive (boolean, optional).