> For the complete documentation index, see [llms.txt](https://docs.neox.vn/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neox.vn/docs/global/global-collections/integration/trade-orders/api-create-trade-order.md). # Create Trade Order #### Endpoint: POST /v2/gc/trade-orders #### Description: Create or update a PI/CI trade-contract order that provides the commercial background for collection funds. ## Request #### Request Body Field Descriptions (JSON) | Field Name | Type | Required | Description | | --------------------- | ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | requestId | string | Yes | Merchant-generated unique request ID (*UUID recommended*). Used for idempotency. | | tradeType | string | Yes | Type of trade. Enum: `GOODS_TRADE_COLLECTION`, `SERVICES_TRADE_COLLECTION`. | | isExchange | boolean | Yes | Whether the trade involves a foreign exchange conversion. | | orderReferenceId | string | Yes | Merchant-side reference number for the trade order (e.g. PI or CI number). | | currency | string | Yes | Currency of the trade order (e.g. `USD`, `EUR`, `HKD`). | | amount | number | Yes | Total trade amount in the specified `currency`. | | buyerName | string | No | **Goods trade only** (`tradeType=GOODS_TRADE_COLLECTION`). Name of the overseas buyer. | | buyerArea | string | No | **Goods trade only.** Country or region of the buyer (ISO 3166-1 alpha-3, e.g. `USA`). | | contractFiles | array | No | **Goods trade only.** List of contract document file paths. Each element is a `path` returned by the File Upload API (`POST /v2/gc/files/upload`). | | productName | string | No | **Goods trade only.** Name of the traded product. | | productCount | number | No | **Goods trade only.** Quantity of the traded product. | | productUnit | string | No | **Goods trade only.** Unit of measurement for the product. Enum: `PCS`, `KG`. | | tradePlatformName | string | No | **Goods trade only.** Name of the e-commerce or trading platform where the order was placed. | | productUrl | string | No | **Goods trade only.** URL of the product listing on the trading platform. | | logisticsStatus | string | No | **Goods trade only.** Shipment status of the goods. Enum: `UNSHIPPED`, `SHIPPED`. | | logisticsCompany | string | No | **Goods trade only.** Name of the logistics or courier company. | | logisticsNumber | string | No | **Goods trade only.** Tracking or waybill number issued by the logistics company. | | logisticsFiles | array | No | **Goods trade only.** List of logistics document file paths. Each element is a `path` returned by the File Upload API (`POST /v2/gc/files/upload`). | | logisticsExpectedTime | date string | No | **Goods trade only.** Expected delivery date of the shipment (YYYY-MM-DD). | | logisticsType | string | No | **Goods trade only.** Mode of transport. Enum: `SEA_TRANSPORT`, `AIR_TRANSPORT`, `LAND_TRANSPORT`, `POSTAL_PARCEL`. | | serviceCategory | string | No | **Services trade only** (`tradeType=SERVICES_TRADE_COLLECTION`). Category of the service. Enum: `GENERAL_TRADE`, `LOGISTICS_COSTS`, `TICKET_PURCHASE`. | | fundsNature | string | No | **Services trade only.** Description of the nature of the service funds. | | subMerchantId | string | No | Sub-merchant identifier. Required when operating on behalf of a sub-merchant. | | operate | string | No | Operation type for the trade order. Enum: `ADD`, `UPDATE`. Defaults to `ADD` when omitted. | | saveType | string | No | File save strategy. Enum: `NORMAL`, `IGNORE_FILE`. Use `IGNORE_FILE` to update order data without re-uploading documents. | | tradeRemark | string | No | Free-text remark or notes about the trade order. | | partnerSite | string | No | Partner or marketplace site identifier associated with the trade order. | | otherFiles | array | No | List of additional supporting document file paths. Each element is a `path` returned by the File Upload API (`POST /v2/gc/files/upload`). | | receiverArea | string | No | Country or region of the goods receiver (ISO 3166-1 alpha-3, e.g. `HKG`). | #### Request sample ```json { "requestId": "c7d8e9f0-1234-4a56-b789-abcdef012345", "tradeType": "GOODS_TRADE_COLLECTION", "isExchange": false, "orderReferenceId": "PI-2024-00182", "currency": "USD", "amount": 15800.00, "buyerName": "Global Retail GmbH", "buyerArea": "DEU", "contractFiles": [ "gpt/COMMERCIAL/20240301/contract_c7d8e9f0.pdf" ], "productName": "Industrial Gear Components", "productCount": 500, "productUnit": "PCS", "tradePlatformName": "Alibaba International", "productUrl": "https://www.alibaba.com/product/industrial-gear-components", "logisticsStatus": "SHIPPED", "logisticsCompany": "DHL Express", "logisticsNumber": "1234567890", "logisticsFiles": [ "gpt/LOGISTICS/20240301/waybill_c7d8e9f0.pdf" ], "logisticsExpectedTime": "2024-04-15", "logisticsType": "AIR_TRANSPORT", "operate": "ADD", "saveType": "NORMAL", "tradeRemark": "Q1 2024 export batch", "receiverArea": "DEU" } ``` ### Response #### Response Field Descriptions | Field Name | Type | Description | | ------------- | ------ | -------------------------------- | | code | number | Response code. | | state | number | State of the response. | | data | object | Created trade order details. | | message | string | Response message. | | neoResponseId | string | Unique NeoX response identifier. | #### `data` object fields: | Field Name | Type | Description | | ------------ | ------ | --------------------------------------------------------------------------- | | tradeOrderId | string | NeoX identifier assigned to the trade order. | | requestId | string | Echoes the merchant-supplied `requestId`. | | status | string | Current status of the trade order. Enum: `INIT`, `WAIT_MATCH`, `COMPLETED`. | #### Response sample ```json { "code": 1, "state": 2, "data": { "tradeOrderId": "TO-20240301-000182", "requestId": "c7d8e9f0-1234-4a56-b789-abcdef012345", "status": "WAIT_MATCH" }, "message": "Successful", "neoResponseId": "f1a2b3c4-5678-4def-9012-3456789abcde" } ``` ## Example cURL ```bash curl -X POST "https://{base_url_openapi}/v2/gc/trade-orders" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -H "Accept-Language: en" \ -d '{ "requestId": "c7d8e9f0-1234-4a56-b789-abcdef012345", "tradeType": "GOODS_TRADE_COLLECTION", "isExchange": false, "orderReferenceId": "PI-2024-00182", "currency": "USD", "amount": 15800.00, "buyerName": "Global Retail GmbH", "buyerArea": "DEU", "contractFiles": [ "gpt/COMMERCIAL/20240301/contract_c7d8e9f0.pdf" ], "productName": "Industrial Gear Components", "productCount": 500, "productUnit": "PCS", "tradePlatformName": "Alibaba International", "productUrl": "https://www.alibaba.com/product/industrial-gear-components", "logisticsStatus": "SHIPPED", "logisticsCompany": "DHL Express", "logisticsNumber": "1234567890", "logisticsFiles": [ "gpt/LOGISTICS/20240301/waybill_c7d8e9f0.pdf" ], "logisticsExpectedTime": "2024-04-15", "logisticsType": "AIR_TRANSPORT", "operate": "ADD", "saveType": "NORMAL", "tradeRemark": "Q1 2024 export batch", "receiverArea": "DEU" }' ``` ### Notes * Requires Bearer token in the Authorization header. * The Accept-Language header can be used to specify the response language (Support: "vi", "en"). * Use a unique `requestId` for each request to avoid duplicate creations. * The request body must be in JSON format. * Goods-specific fields (`buyerName`, `buyerArea`, `contractFiles`, `productName`, `productCount`, `productUnit`, `tradePlatformName`, `productUrl`, `logisticsStatus`, `logisticsCompany`, `logisticsNumber`, `logisticsFiles`, `logisticsExpectedTime`, `logisticsType`) are applicable only when `tradeType=GOODS_TRADE_COLLECTION`. * Services-specific fields (`serviceCategory`, `fundsNature`) are applicable only when `tradeType=SERVICES_TRADE_COLLECTION`. * All file-reference fields (`contractFiles`, `logisticsFiles`, `otherFiles`) must contain `path` values returned by the File Upload API (`POST /v2/gc/files/upload`). * Set `operate=UPDATE` and the original `requestId` to modify an existing trade order. Use `saveType=IGNORE_FILE` to update non-file fields without re-uploading documents.