Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

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

Example cURL

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.

PreviousTrade Order APIsNextGet Detail Trade Order

Last updated

Was this helpful?