Lab Testing Order Update Guide

Latest Update Time: 2026-06-23 00:00:00

Use the lab testing order update API to modify an existing LT order.

See the Lab Testing Introduction for base URL, authentication, and required headers.

Endpoint

PUT https://ppapi.qima.com/v1.2/lt/orders/{orderId}

This API additionally requires the Content-Type: application/json header.

Prerequisites

In addition to the required headers and authentication setup:

Permission to update lab testing orders
The LT orderId from an order search, order create, or order detail response
An order in a status that allows updates
Custom fields pre-configured in the target environment by the QIMA development or business team, if you plan to use the customFields section

Path Parameters

Parameter	Required	Description
`orderId`	Yes	QIMA internal LT order ID to update, for example `ba70d368-801d-447e-ba55-0d1269d81188`.

Request Body Overview

Section	Required	Description
`generalInformation`	Yes	Booking-level information. `bookingRefNo` and `submissionType` are required.
`product`	Yes	Product details. `productName` is required.
`additionalRecipients`	No	Email recipients for report, invoice, and quotation notifications.
`customFields`	No	Custom fields for your LT program. Must be configured in advance by the QIMA development or business team in the target environment before use.

Unlike order create, the update payload does not include testAssignments, sampleCollection, specialInstruction, or accreditationList.

Custom Fields Prerequisite

The customFields section is optional, but it cannot be used until QIMA has configured the corresponding custom field definitions for your account in that environment. Contact the QIMA development or business team before sending custom field values in update requests.

Request Example

curl --location --request PUT 'https://ppapi.qima.com/v1.2/lt/orders/<order-id>' \
  --header 'Ai-Api-Access-Token: {your api access token}' \
  --header 'Ai-User-Id: {your user ID}' \
  --header 'Authorization: Bearer {your token}' \
  --header 'Referer: https://preprodmy.qima.com/' \
  --data-raw '{
    "generalInformation": {
        "bookingRefNo": "BOOK-2026-001",
        "supplierId": "",
        "programId": "",
        "submissionType": "Testing",
        "testLocation": "Dongguan",
        "requestTurnAroundTime": "Regular",
        "accreditationRequired": "Yes",
        "description": "Updated lab testing order via API"
    },
    "product": {
        "productName": "Children Toy Sample",
        "purchaseOrderNo": "PO-2026-001",
        "sku": "SKU-2026-001",
        "materials": "Cotton, Polyester",
        "ageGrade": "3+",
        "manufacturerFactoryName": "ABC Factory",
        "buyerName": "XYZ Company",
        "agencyName": "Agency ABC",
        "shipmentDate": "2025-12-31",
        "distributionRegions": ["Austria"],
        "distributionCountries": ["China"],
        "originCountries": ["Japan"]
    },
    "additionalRecipients": {
        "reportEmailTo": "report@example.com",
        "reportEmailCC": "cc@example.com",
        "invoiceEmailTo": "invoice@example.com",
        "invoiceEmailCC": "invoice-cc@example.com",
        "quotationEmailTo": "quotation@example.com",
        "quotationEmailCC": "quotation-cc@example.com"
    },
    "customFields": [
        {
            "module": "SampleInfo",
            "label": "Test Field 3",
            "value": "Updated by API integration"
        }
    ]
}'

Request Field Notes

Field	Notes
`generalInformation.bookingRefNo`	Required. Client-side booking reference number.
`generalInformation.submissionType`	Required. Common value: `Testing`.
`generalInformation.programId`	Optional. Leave empty to use the default program when applicable.
`generalInformation.supplierId`	Optional. Use a valid supplier ID when the supplier already exists in QIMA.
`generalInformation.requestTurnAroundTime`	Turnaround time request, such as `Regular`.
`generalInformation.accreditationRequired`	Whether accreditation is required, for example `Yes` or `No`.
`product.productName`	Required. Product name for the LT order.
`customFields`	Optional. Only supported after QIMA development or business teams configure the custom field definitions in the target environment.
`customFields[].module`	Must match a module name configured by QIMA for your account.
`customFields[].label`	Must match a field label configured by QIMA for your account.
`customFields[].value`	Value to store for the configured custom field.

Successful Response

HTTP 200 OK means the order was updated successfully. The response structure matches order create and wraps the updated order details in content.

{
  "message": "Success",
  "content": {
    "generalInformation": {
      "orderId": "ba70d368-801d-447e-ba55-0d1269d81188",
      "qimaRefNo": "T-26012282",
      "bookingRefNo": "BOOK-2026-001",
      "testDate": "",
      "reportDate": "",
      "status": "Validation",
      "client": "Lifelong QIMA Sandbox",
      "clientId": "0F521098B7154460A50303EEE7A61A16",
      "supplier": "",
      "supplierId": "",
      "submitter": "Lifelong QIMA Sandbox",
      "submitterId": "0F521098B7154460A50303EEE7A61A16",
      "program": "DEFAULT",
      "programId": "05ef9e73-479a-40c2-a2db-812daaed3e1e"
    },
    "product": {
      "productName": "Children Toy Sample",
      "purchaseOrderNo": "PO-2026-001",
      "sku": "SKU-2026-001",
      "materials": "Cotton, Polyester",
      "ageGrade": "3+",
      "program": "DEFAULT",
      "programId": "05ef9e73-479a-40c2-a2db-812daaed3e1e",
      "distributionRegions": ["Austria"],
      "distributionCountries": ["China"],
      "originCountries": ["Japan"],
      "manufacturerFactoryName": "ABC Factory",
      "agencyName": "Agency ABC",
      "buyerName": "XYZ Company",
      "shipmentDate": "",
      "bookingRemark": ""
    },
    "tests": [
      {
        "testId": "24671365-76d4-4ed7-b6be-2b92d6bfa59f",
        "clientTestId": null,
        "testName": "EN 71-3:2019-Toys-Migration of Certain Elements (Cat III) - All Inclusive",
        "testResult": null
      }
    ],
    "customFields": [
      {
        "module": "SampleInfo",
        "label": "Test Field 3",
        "value": "Updated by API integration"
      }
    ],
    "sampleCollection": [
      {
        "method": "Courier",
        "carrier": "DHL",
        "trackingNo": "TRACK-2026-001",
        "remarks": "Handle with care",
        "inspectionOrderReference": null
      }
    ],
    "additionalRecipients": {
      "reportEmailTo": "report@example.com",
      "reportEmailCC": "cc@example.com",
      "invoiceEmailTo": "invoice@example.com",
      "invoiceEmailCC": "invoice-cc@example.com",
      "quotationEmailTo": "quotation@example.com",
      "quotationEmailCC": "quotation-cc@example.com"
    },
    "attachments": null
  }
}

Response Field Notes

Field	Notes
`content.generalInformation.orderId`	QIMA internal LT order ID. Same as the `orderId` in the request path.
`content.generalInformation.qimaRefNo`	QIMA lab order reference number, for example `T-26012282`.
`content.generalInformation.status`	Current order status after the update.
`content.generalInformation.bookingRefNo`	Echo of the client booking reference sent in the request.
`content.tests`	Assigned tests with QIMA test names and IDs.
`content.sampleCollection`	Sample collection details currently stored on the order.
`content.attachments`	Attachments linked to the order. Usually `null` unless files were uploaded separately.

Common Errors

See common authentication errors for 401 and 403 responses.

Status	Meaning	Recommended Action
`400 Bad Request`	Request body failed validation.	Check required fields such as `bookingRefNo`, `submissionType`, and `productName`. Verify that any `customFields` were pre-configured by QIMA in the target environment.
`404 Not Found`	The order does not exist or is not accessible.	Confirm the `orderId` is correct and belongs to the authenticated account.
`500 Internal Server Error`	Order update failed on the server.	Contact QIMA support with the request time and `orderId`.

Next Steps

Retrieve full lab testing order details to confirm the updated values — see the Order Detail Guide.
Upload attachments to the order when additional documents are required — see the Order Attachments Guide.
Retrieve lab testing order test results when the report is available — see the Order Results Guide.

Documents