--- updatedAt: 2026-05-27T06:53:55.000Z agentTools: projectIndex: https://docs.track123.com/llms.txt --- # Register trackings You can register up to 100 tracking numbers per request. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "api reference", "version": "1.0" }, "servers": [ { "url": "https://api.track123.com/gateway/open-api" } ], "components": { "securitySchemes": { "sec0": { "type": "apiKey", "in": "header", "name": "Track123-Api-Secret" } } }, "security": [ { "sec0": [] } ], "tags": [ { "name": "Trackings" } ], "paths": { "/tk/v2.1/track/import": { "post": { "tags": [ "Trackings" ], "summary": "Register trackings", "description": "", "operationId": "register-package-trackings", "parameters": [ { "name": "Track123-Api-Secret", "in": "header", "description": "Your API key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "RAW_BODY": { "type": "array", "items": { "properties": { "trackNo": { "type": "string", "required": true, "description": "Tracking number" }, "orderCreateAt": { "type": "string", "description": "Order creation time" }, "courierCode": { "type": "string", "description": "The unique carrier code, if it is null, the system will auto-detect carrier base tracking number format" }, "orderNo": { "type": "string", "description": "Order number" }, "country": { "type": "string", "description": "Country code of destination: CN,US,GB" }, "shipTime": { "type": "string", "description": "Ship time" }, "customerEmail": { "type": "string", "description": "The customer email address associated with the order" }, "postalCode": { "type": "string", "description": "The postcode of the destination (15 letters or numbers, can contain +, -, and spaces)" }, "extendFieldMap": { "type": "object", "description": "Be used to add additional information, such as phone number", "properties": { "phoneSuffix": { "type": "string", "description": "The last 4 digits of the shipment sender's or recipient's phone number" } } }, "remark": { "type": "string", "description": "Remarks of this order" }, "custom1": { "type": "string", "description": "Custom field 1" }, "custom2": { "type": "string", "description": "Custom field 2" }, "lang": { "type": "string", "description": "Enter the ISO 639-1 Language Code to specify the customer or order language. This parameter applies only to a limited number of carriers that support multilingual tracking on their official websites. If not specified, results will be displayed in the default language. Please note that translation is not guaranteed for all carriers.", "default": "en" }, "translate": { "type": "boolean", "default": "false", "description": "If this field is set to true, tracking events will be translated using Microsoft Translator.\nOne tracking quota will be deducted per tracking number upon the first successful translation." }, "connectionId": { "type": "string", "description": "The connection ID generated when a customer binds their own carrier account credentials in [Track123 Developer > Carrier Connection](https://member.track123.com/carrierConnection). When this field is provided, the tracking data for this shipment will be retrieved using the customer's own carrier account credentials instead of the default Track123 credentials." } }, "required": [ "trackNo" ], "type": "object" } } } }, "examples": { "Request Example": { "value": [ { "trackNo": "LV209031969CN", "courierCode": "denmark-post", "orderNo": "x1234567890", "country": "CN", "shipTime": "2024-01-01 12:00:00", "customerEmail": "customer@track123.com", "postalCode": "000000", "extendFieldMap": { "phoneSuffix": "2390" }, "remark": "remark", "custom1": "customField1", "custom2": "customField2" } ] } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "examples": { "Success": { "value": "{\n \"code\": \"00000\",\n \"data\": {\n \"accepted\": [\n {\n \"trackNo\": \"LV209031969CN\",\n \"courierCode\": \"denmark-post\",\n \"postalCode\": \"000000\",\n \"orderNo\": \"x1234567890\",\n \"country\": \"CN\",\n \"shipTime\": \"2024-01-01 12:00:00\",\n \"customerEmail\": \"customer@track123.com\",\n \"remark\": \"remark\",\n \"extendFieldMap\": {\n \"phoneSuffix\": \"2390\"\n }\n }\n ],\n \"rejected\": [\n {\n \"index\": 2,\n \"trackNo\": \"LV209031969CN\",\n \"orderNo\": \"x1234567890\",\n \"courierCode\": \"denmark-post\",\n \"error\": {\n \"code\": \"A0400\",\n \"msg\": \"The order number has been imported\"\n }\n }\n ]\n },\n \"msg\": \"Success\",\n \"traceId\": \"79160aef7dde4df3ab53d77a5e783fad.161.17086538800398087\"\n}" } }, "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "00000", "description": "Service status code" }, "data": { "type": "object", "properties": { "accepted": { "type": "array", "description": "Successful registration of tracking number", "items": { "type": "object", "properties": { "trackNo": { "type": "string", "example": "LV209031969CN", "description": "Tracking number" }, "orderCreateAt": { "type": "string", "example": "2024-01-01 12:00:00", "description": "Order creation time" }, "courierCode": { "type": "string", "example": "denmark-post", "description": "The unique carrier code , if it is null, the system will auto-detect carrier base tracking number format" }, "postalCode": { "type": "string", "example": "000000", "description": "The postal code of the recipient's address. Refer to our article on [additional tracking fields](https://docs.track123.com/reference/additional-tracking-fields) for more details." }, "orderNo": { "type": "string", "example": "x1234567890", "description": "The order number generated by the merchant/platform." }, "country": { "type": "string", "example": "CN", "description": "Destination country" }, "shipTime": { "type": "string", "example": "2024-01-01 12:00:00", "description": "Ship time" }, "customerEmail": { "type": "string", "example": "customer@track123.com", "description": "The customer email address associated with the order filled in by the merchant/platform" }, "remark": { "type": "string", "example": "remark", "description": "Remark" }, "extendFieldMap": { "type": "object", "description": "Be used to add additional information, such as phone number", "properties": { "phoneSuffix": { "type": "string", "example": "2390", "description": "The last 4 digits of the shipment sender's or recipient's phone number. Refer to our article on [additional tracking fields](https://docs.track123.com/reference/additional-tracking-fields) for more details." } } } } } }, "rejected": { "type": "array", "description": "Rejected registration of tracking number", "items": { "type": "object", "properties": { "index": { "type": "integer", "example": 2, "default": 0 }, "trackNo": { "type": "string", "example": "LV209031969CN", "description": "Tracking number" }, "orderNo": { "type": "string", "example": "x1234567890", "description": "The order number generated by the merchant/platform." }, "courierCode": { "type": "string", "example": "denmark-post", "description": "Carrier code" }, "error": { "type": "object", "description": "Error", "properties": { "code": { "type": "string", "example": "A0400", "description": "Error code" }, "msg": { "type": "string", "example": "The order number has been imported", "description": "Error information" } } } } } } } }, "msg": { "type": "string", "example": "Success", "description": "The description information corresponding to the service status code or other auxiliary description information." }, "traceId": { "type": "string", "example": "79160aef7dde4df3ab53d77a5e783fad.161.17086538800398087" } } } } } } }, "deprecated": false } } }, "x-readme": { "headers": [], "explorer-enabled": true, "proxy-enabled": true, "samples-enabled": true } } ```