POS Retrieval Operations

Connection Status: Responses

The endpoint returns the standard response envelope. The data object carries the connection-status payload produced by the authoritative service; execute the request above against your environment to see the fields it currently returns.

{
  "status": "ok",
  "message": "",
  "data": {
    "organizationId": 3682,
    "organizationName": "POS Sandbox - Test 7A",
    "locationId": 5102,
    "address": "300 Test 7A Medical Retail Way",
    "city": "Las Cruces",
    "posApiConnectionStatus": "prepared"
  }
}

Unauthorized

Returned with HTTP 401 when the Bearer token is missing, malformed, expired, or fails signature verification.

{
    "status": "error",
    "message": "Unauthorized.",
    "data": null
}

Service Unreachable

If the authoritative service cannot be reached or replies with an error, the response uses the shared error format with HTTP 200 and the originating message.

{
    "status": "error",
    "message": "Unable to process request.",
    "data": null
}

Inventory: Successful Response

{
    "status": "ok",
    "message": "",
    "data": {
        "roomType": "retail",
        "inventory": [
            {
                "inventoryId": 1789,
                "barCode": "1234567890123456",
                "productType": "Infused Cannabis Material (Volatile Solvent) Packaged",
                "productName": "Example Infused Product",
                "strainName": "Blue Dream",
                "medicalOnly": false,
                "availableQuantity": 24,
                "saleUnit": "pkg",
                "quantityMustBeWholeNumber": true,
                "packageContentQuantity": 0.5,
                "packageContentUnit": "g",
                "servingsPerPackage": null,
                "totalThcPercent": 1.88,
                "totalThcMgPerGram": 18.77,
                "totalThcMgPerMl": null,
                "totalThcMgPerPackage": 9.39,
                "delta9ThcPercent": 1,
                "delta9ThcMgPerGram": 10,
                "delta9ThcMgPerMl": null,
                "delta9ThcMgPerPackage": 5,
                "expirationDate": "2027-04-18"
            },
            {
                "inventoryId": 1790,
                "barCode": "9876543210987654",
                "productType": "Deli Style Cannabis",
                "productName": null,
                "strainName": "Northern Lights",
                "medicalOnly": false,
                "availableQuantity": 142.75,
                "saleUnit": "g",
                "quantityMustBeWholeNumber": false,
                "packageContentQuantity": null,
                "packageContentUnit": null,
                "servingsPerPackage": null,
                "totalThcPercent": 9.39,
                "totalThcMgPerGram": 93.85,
                "totalThcMgPerMl": null,
                "totalThcMgPerPackage": null,
                "delta9ThcPercent": 5,
                "delta9ThcMgPerGram": 50,
                "delta9ThcMgPerMl": null,
                "delta9ThcMgPerPackage": null,
                "expirationDate": "2027-04-11"
            }
        ]
    }
}

An empty inventory array is a successful response. It means the requested room exists and the location has the required license, but no inventory currently meets the requirements for dispensing.

Room Fields

Inventory Fields

Inventory Included in the Response

Inventory is returned only when it:

• Belongs to the authorized organization and location.
• Is located in the requested Retail or Consumption room.
• Has a product type designated as retailable.
• Has a positive available quantity.
• Has passed testing and has a current expiration date when its product type requires retail testing and expiration.
• Is not scheduled for destruction and has not been destroyed.
• Is not subject to an active administrative case restriction that blocks dispensing.

Inventory that does not meet these conditions is omitted from the response.

Medical-Only Inventory

Medical-only inventory may be included in the response because it remains eligible for a Medical customer. The POS should not allow an item with "medicalOnly": true to be selected for an Adult-Use customer. The internal dispense operation independently validates this rule when the order is submitted.

Quantity Handling

The POS should use availableQuantity, saleUnit, and quantityMustBeWholeNumber together. Example packaged item:

{
    "availableQuantity": 24,
    "saleUnit": "pkg",
    "quantityMustBeWholeNumber": true
}

The POS may accept quantities such as 1, 2, or 3, but not 1.5. Example unpackaged flower item:

{
    "availableQuantity": 142.75,
    "saleUnit": "g",
    "quantityMustBeWholeNumber": false
}

The POS may accept a fractional quantity such as 3.5. Example unpackaged liquid item:

{
    "availableQuantity": 500,
    "saleUnit": "mL",
    "quantityMustBeWholeNumber": false
}

Use in the Subsequent Dispense Request

For each selected item, the POS will later submit:

{
    "inventoryId": 1789,
    "quantity": 1,
    "dollarAmount": 15.00,
    "taxAmount": 1.25
}

The inventory endpoint supplies inventoryId and the information needed to collect a valid quantity. The POS supplies dollarAmount and taxAmount from its own sales transaction. The POS does not need to return the product name, product type, strain, barcode, medical-only indicator, sale unit, or available quantity in the dispense request.

Authoritative Validation

The inventory response represents inventory availability at the time the request was processed. Inventory quantities, testing status, expiration status, room assignment, case restrictions, or destruction status may change after the response is received. The subsequent dispense operation is authoritative. It reloads and locks the selected inventory records and independently verifies:

• Organization and location ownership.
• Retail or Consumption room assignment.
• Required location license.
• Testing and expiration eligibility.
• Retailable product type.
• Medical-only restrictions.
• Current available quantity.
• Whole-number package quantities.
• Administrative case restrictions.
• Destruction status.
• Adult-Use purchase limits.
• Medical unit limits.
• THC and Delta-9 THC calculations.

The POS should perform reasonable preliminary validation using the inventory response, but it must handle a dispense rejection if inventory is no longer eligible when the order is submitted.

Endpoint-Specific Errors

Invalid Room Type:

{
    "status": "error",
    "errorCode": "INVALID_RETAIL_INVENTORY_ROOM_TYPE",
    "message": "Room Type must be Retail or Consumption.",
    "data": null
}

Required License Not Available:

{
    "status": "error",
    "errorCode": "ACTIVE_LOCATION_LICENSE_REQUIRED",
    "message": "Unable to process request. This location does not have an active, non-expired license or valid temporary access for this activity.",
    "data": null
}

The required license is based on the requested room:

• retail requires a valid Retail license.
• consumption requires a valid Consumption license.

Requested Room Not Found:

{
    "status": "error",
    "errorCode": "RETAIL_DISPENSE_INVENTORY_FAILED",
    "message": "Unable to process request. Retail room not found.",
    "data": null
}

For a Consumption request, the message is: Unable to process request. Consumption room not found.

General Inventory Retrieval Failure:

{
    "status": "error",
    "errorCode": "RETAIL_DISPENSE_INVENTORY_FAILED",
    "message": "Unable to retrieve retail dispense inventory.",
    "data": null
}

Delivery Options: Successful Response

{
    "status": "ok",
    "message": "",
    "data": {
        "retailerDelivery": {
            "allowed": true,
            "available": true,
            "drivers": [
                {
                    "driverId": 12,
                    "firstName": "Jane",
                    "lastName": "Smith",
                    "driversLicenseLastFour": "1234"
                }
            ],
            "vehicles": [
                {
                    "vehicleId": 8,
                    "year": "2024",
                    "make": "Ford",
                    "model": "Transit",
                    "licensePlate": "ABC123"
                }
            ]
        },
        "courierDelivery": {
            "available": true,
            "couriers": [
                {
                    "courierRetailAgreementId": 17,
                    "courierOrganizationId": 200,
                    "courierLocationId": 300,
                    "orgName": "Example Courier",
                    "premiseAddress1": "100 Example Road",
                    "premiseCity": "Albuquerque",
                    "courierLicenseId": 45,
                    "courierLicenseNum": "COURIER-123",
                    "displayText": "Example Courier - 100 Example Road, Albuquerque - License: COURIER-123",
                    "drivers": [
                        {
                            "driverId": 25,
                            "firstName": "Robert",
                            "lastName": "Jones",
                            "driversLicenseLastFour": "5678"
                        }
                    ],
                    "vehicles": [
                        {
                            "vehicleId": 19,
                            "year": "2023",
                            "make": "Mercedes-Benz",
                            "model": "Sprinter",
                            "licensePlate": "XYZ789"
                        }
                    ]
                }
            ]
        }
    }
}

Empty arrays are valid. For example, a location may have no active courier agreements, or a delivery method may be allowed but not currently have the required driver and vehicle records.

retailerDelivery Fields

Contains the retailer location's own delivery resources.

A location can have { "allowed": true, "available": false }. This means retailer-operated delivery is permitted, but the location does not currently have both a driver and vehicle available in the system.

courierDelivery Fields

Contains delivery resources available through active courier agreements.

A courier may appear in the couriers array even when that specific courier currently has no drivers or no vehicles. The POS system should only allow selection of a courier that has both an available driver and vehicle.

Courier Fields

Driver Fields

Vehicle Fields

Using the Returned Values in a Dispense

For retailer-operated delivery, the dispense request must contain:

{
    "deliveryFulfillmentType": "retailer",
    "retailerDriverId": 12,
    "retailerVehicleId": 8
}

For courier delivery, the dispense request must contain:

{
    "deliveryFulfillmentType": "courier",
    "courierRetailAgreementId": 17,
    "courierDriverId": 25,
    "courierVehicleId": 19
}

The selected courier driver and vehicle must belong to the courier location associated with the selected agreement. The selected retailer driver and vehicle must belong to the requesting retailer organization and location.

Endpoint-Specific Errors

In addition to the common errors, this call may return:

An unexpected database or processing error may also return DELIVERY_OPTIONS_FAILED with a more specific message describing the failure.

Medical Card Lookup: Successful Patient Response

{
    "status": "ok",
    "message": "",
    "data": {
        "medicalCannabisCardId": "4UX58G5R4G",
        "cardType": "Patient",
        "patient": {
            "applicationId": "4UX58G5R4G"
        },
        "caregiver": null,
        "units": {
            "limit": 425,
            "usedLast90Days": 250,
            "remaining": 175
        }
    }
}

Successful Caregiver Response

When the submitted card belongs to a caregiver, the response identifies the card as a caregiver card and returns both the patient and caregiver information.

{
    "status": "ok",
    "message": "",
    "data": {
        "medicalCannabisCardId": "6L9YE6W8J7",
        "cardType": "Caregiver",
        "patient": {
            "applicationId": "6L9YE6W8J7"
        },
        "caregiver": {
            "expirationDate": "2027-01-10T00:00:00.000Z"
        },
        "units": {
            "limit": 425,
            "usedLast90Days": 250,
            "remaining": 175
        }
    }
}

Card Fields

Patient Fields

Caregiver Fields

The caregiver object is returned only when cardType is Caregiver.

Unit Fields

The remaining amount is calculated as remaining = limit - usedLast90Days. The returned remaining amount will not be less than zero.

Medical Unit Calculation

The Department of Health lookup identifies the patient associated with the submitted card. The internal application then calculates Medical units already used by finding completed Medical dispenses for that patient during the previous 90 days. Voided dispenses are not counted because only orders with a current status of Complete are included. The unit values represent the information available when the lookup is processed. They may change if another Medical dispense is completed before the current order is submitted.

Use in the Dispense Workflow

The POS should use this endpoint before submitting a Medical dispense to:

1. Confirm that the submitted card can be located.
2. Confirm the patient associated with the card.
3. Identify whether the submitted card is a patient or caregiver card.
4. Display the applicable expiration information.
5. Retrieve the patient's currently remaining Medical units.
6. Perform preliminary validation of the proposed order.

The POS must send the original card ID with the subsequent dispense request:

{
    "customerType": "medical",
    "medicalCannabisCardId": "4UX58G5R4G"
}

The POS should not send patient names, caregiver names, Medical-unit totals, or internal patient identifiers back with the dispense request.

Preliminary Versus Authoritative Validation

The medical-card lookup is preliminary and informational. It does not:

• Reserve any Medical units.
• Guarantee that the patient will still have the same units remaining at checkout.
• Replace the medical-card validation performed during the dispense.
• Complete or authorize a sale.

When a Medical dispense is submitted, the internal application performs the Department of Health lookup again and recalculates the patient's available units. The dispense operation is authoritative. A dispense may therefore be rejected even if an earlier card lookup succeeded. For example:

• Another dispense may have used some of the patient's units.
• The Department of Health service may return different information.
• The card may no longer be accepted.
• The proposed order may exceed the remaining units.

The POS must handle a checkout rejection and display the returned error to the user.

Card Expiration

The response includes the patient and caregiver expiration dates returned by the Department of Health service. The current internal implementation returns this information to the caller but does not independently reject the card solely by comparing the returned expiration date with the current date. The POS may display the expiration date, but it should rely on the success or failure returned by the Department of Health lookup and the subsequent authoritative dispense validation.

Data Not Returned

The internal Department of Health lookup obtains additional information that is intentionally not returned through the POS endpoint. The POS response does not expose:

• Patient or caregiver date of birth.
• Internal patient Medical identifiers.
• The raw Department of Health response.
• Internal database or audit information.

These values are not required for POS validation or checkout.

License Requirement

The authorized POS location must have an active, non-expired Retail or Consumption license, or valid temporary access for one of those activities. The inventory-case restriction check is not performed for this endpoint because no inventory item is being selected or modified.

Endpoint-Specific Errors

Missing or Invalid Card ID:

{
    "status": "error",
    "errorCode": "INVALID_MEDICAL_CANNABIS_CARD_ID",
    "message": "A valid Medical Cannabis Card ID is required.",
    "data": null
}

This error is returned when the card ID:

• Is missing.
• Is null.
• Is not submitted as a string.
• Contains only whitespace.

Card ID Too Long:

{
    "status": "error",
    "errorCode": "INVALID_MEDICAL_CANNABIS_CARD_ID",
    "message": "Medical Cannabis Card ID cannot exceed 100 characters.",
    "data": null
}

Card Not Found:

{
    "status": "error",
    "errorCode": "MEDICAL_CARD_LOOKUP_FAILED",
    "message": "Unable to process request. Medical Cannabis Card ID not found.",
    "data": null
}

Department of Health Authorization Failure:

{
    "status": "error",
    "errorCode": "MEDICAL_CARD_LOOKUP_FAILED",
    "message": "Unable to process request. DOH API authorization failed.",
    "data": null
}

Department of Health Timeout:

{
    "status": "error",
    "errorCode": "MEDICAL_CARD_LOOKUP_FAILED",
    "message": "Unable to process request. DOH API request timed out.",
    "data": null
}

Required Location License Not Available:

{
    "status": "error",
    "errorCode": "ACTIVE_LOCATION_LICENSE_REQUIRED",
    "message": "Unable to process request. This location does not have an active, non-expired license or valid temporary access for this activity.",
    "data": null
}

General Lookup Failure:

{
    "status": "error",
    "errorCode": "MEDICAL_CARD_LOOKUP_FAILED",
    "message": "Unable to look up Medical Cannabis Card.",
    "data": null
}

Order Lookup: Successful Response

{
    "status": "ok",
    "message": "",
    "data": {
        "retailDispenseTicketId": 4217,
        "orderNumber": "1234567890123456",
        "orderSource": "api",
        "dispenseInternalRequestId": "7693ae51-135b-4755-a15e-f7aac21bc33a",
        "roomType": "retail",
        "ticketStatus": "Complete",
        "createdDateTime": "2026-07-25T15:42:31",
        "dispenseDateTime": "2026-07-25T15:42:41",
        "customerType": "adult-use",
        "dispenseType": "in-store",
        "deliveryFulfillmentType": null,
        "deliveryAddress": null,
        "travelRoute": null,
        "totalItems": 2,
        "totalDollarAmount": 40.00,
        "totalTaxAmount": 3.20,
        "grandTotalAmount": 43.20,
        "voidedDateTime": null,
        "voidReason": null,
        "items": [
            {
                "inventoryId": 1789,
                "barCode": "9876543210987654",
                "productType": "Cannabis Flower Packaged",
                "productName": "Blue Dream 3.5g",
                "strainName": "Blue Dream",
                "quantity": 2,
                "unit": "pkg",
                "dollarAmount": 30.00,
                "taxAmount": 2.40,
                "lineTotalAmount": 32.40
            },
            {
                "inventoryId": 1790,
                "barCode": "4567890123456789",
                "productType": "Cannabis Edible Packaged",
                "productName": "Fruit Chews",
                "strainName": null,
                "quantity": 1,
                "unit": "pkg",
                "dollarAmount": 10.00,
                "taxAmount": 0.80,
                "lineTotalAmount": 10.80
            }
        ]
    }
}

Order Header Fields

Order Item Fields

Web and API Orders

Orders created through either the web application or POS API may be retrieved. For a web-created order:

{
    "orderSource": "web",
    "dispenseInternalRequestId": null
}

For a POS API-created order:

{
    "orderSource": "api",
    "dispenseInternalRequestId": "7693ae51-135b-4755-a15e-f7aac21bc33a"
}

A web-created order may be viewed through this endpoint, but it cannot be voided through the POS API. It must be voided through the web application. Only orders originally created through the POS API may be voided through the POS void endpoint.

Location Restrictions

The endpoint only returns orders belonging to the organization and location associated with the authorized POS location token. An order belonging to another organization or location is returned as not found. A currently active Retail or Consumption license is not required for this historical lookup. The POS may still retrieve an earlier order after the location's license status has changed.

Endpoint-Specific Errors

No Identifier or Multiple Identifiers:

{
    "status": "error",
    "errorCode": "INVALID_ORDER_LOOKUP_IDENTIFIER",
    "message": "Provide exactly one of Retail Dispense Ticket ID, Order Number, or Dispense Internal Request ID.",
    "data": null
}

Invalid Retail Dispense Ticket ID:

{
    "status": "error",
    "errorCode": "INVALID_RETAIL_DISPENSE_TICKET_ID",
    "message": "A valid Retail Dispense Ticket ID is required.",
    "data": null
}

Invalid Order Number:

{
    "status": "error",
    "errorCode": "INVALID_ORDER_NUMBER",
    "message": "Order Number must be provided as a string.",
    "data": null
}

An order number exceeding the supported maximum length also returns INVALID_ORDER_NUMBER.

Invalid Dispense Internal Request ID:

{
    "status": "error",
    "errorCode": "INVALID_DISPENSE_INTERNAL_REQUEST_ID",
    "message": "A valid Dispense Internal Request ID is required.",
    "data": null
}

Order Not Found:

{
    "status": "error",
    "errorCode": "RETAIL_DISPENSE_ORDER_NOT_FOUND",
    "message": "Unable to process request. Order not found.",
    "data": null
}

General Lookup Failure:

{
    "status": "error",
    "errorCode": "RETAIL_DISPENSE_ORDER_LOOKUP_FAILED",
    "message": "Unable to retrieve retail dispense order.",
    "data": null
}