> 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.neox.vn/docs/global/global-collections/integration/trade-orders/api-create-trade-order.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.