Apply Lab Coupon to Visit (v1)

Method & Path

POST /api/v1/workspace/:workspaceId/labs/visits/:labVisitId/apply-lab-coupon

Actual backend path: /v1/workspace/:workspaceId/labs/visits/:labVisitId/apply-lab-coupon

Description

Apply (or clear) a lab coupon code on an existing lab visit. The backend recalculates totals based on test prices and the coupon.

Authentication

Required: JWT token in Authorization header

Persona Access:

• Workspace Owner: Allowed
• Staff: Allowed (role-based)

Required Permissions:

• labs.billing

Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer token: Bearer <token>
Content-Type	string	Yes	application/json

Path Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	Workspace identifier (MongoDB ObjectId)
labVisitId	string	Yes	Lab visit identifier (MongoDB ObjectId)

Request Body

{
  "labCouponCode": "WINTER10"
}

Field	Type	Required	Description
labCouponCode	string | null	Yes	Coupon code. Use null to clear coupon

Response 200 OK

{
  "labVisit": {
    "id": "507f1f77bcf86cd799439011",
    "workspaceId": "507f1f77bcf86cd799439012",
    "clientId": "507f1f77bcf86cd799439013",
    "labVisitType": "in-lab",
    "labVisitStatus": "pending",
    "labTestSnapshots": [
      { "test": { "testId": 101, "testTitle": "CBC" }, "designTest": null }
    ],
    "labVisitDate": "2026-01-10T12:00:00.000Z",
    "labVisitNotes": null,
    "labVisitPricing": {
      "labVisitSubtotal": 30,
      "labCouponId": "507f1f77bcf86cd799439055",
      "labCouponCode": "WINTER10",
      "labVisitDiscountAmount": 3,
      "labVisitTotal": 27
    },
    "deletedAt": null,
    "createdAt": "2026-01-10T12:00:00.000Z",
    "updatedAt": "2026-01-11T08:00:00.000Z"
  }
}

Common Errors

400 Bad Request: Invalid request body

401 Unauthorized: Missing or invalid authentication token

403 Forbidden: Insufficient permissions (labs.billing required)

404 Not Found: Workspace or lab visit not found

422 Validation Error: Invalid coupon code, invalid IDs, or cannot modify invoiced/cancelled visits