https://api.nexscope.ai/alibaba1688/invoiceAmountRun this API
Send a JSON request to execute this API and receive the documented response payload.
Endpoint
| Method | POST |
| Path | https://api.nexscope.ai/alibaba1688/invoiceAmount |
| Auth | Bearer API key |
| Content-Type | application/json |
Before testing 1688 procurement
Examples illustrate the request format. Product, SKU, address, logistics and order IDs are not verified for your account. Replace them with actual values before running a request.
Authorization and where to get your values
- Get an authorization URL
Use your Nexscope API key and an
accountNamelabel of your choice. Your Nexscope key identifies your Nexscope account. Open the returned URL in your browser to authorize your own 1688 buyer account; its tokens are stored securely by the Nexscope backend.Authorization is supported by LinkFox Agent, Nexscope's strategic partner in China. You will see "LinkFox Agent" on the 1688 authorization page. Authorize your own 1688 account; Nexscope links it to your Nexscope user account.
Use data only within the scope of your authorization and in accordance with applicable local laws, regulations, and platform terms.
The permission descriptions and agreement notice on the 1688 authorization page are in Chinese. Use your browser's translation feature and select English to read them. Changing your browser's language alone does not switch these sections to English.
1688 authorization page — English reference translation 
This translated screenshot is provided for reference only. Please refer to the actual 1688 authorization page and applicable agreements. The translation does not change the official page or indicate that your account is authorized.
Open the full-size translated screenshotComplete authorization within 10 minutes of requesting the URL. If the link expires or authorization fails, request a new URL and try again. Check authorized accounts afterward; the redirect page alone does not verify authorization.
Getting an authorization URL and checking authorized accounts each cost 10 credits per call. Internal token exchange and refresh are not charged separately. Other procurement calls use their configured credit price.
- Check authorized accounts
Continue with buyer operations only when an account has
status=ACTIVEandexpired=false. Returning from the authorization page alone does not confirm success. Tokens and refresh are handled by the backend. Use a real product ID from a selected 1688 product or search result. Query its SKUs and use a returned
specIdwhen selecting a specification.Query your addresses and select a returned
addressId, or supply the documentedaddressParam.Use your existing order ID or the
orderIdreturned by order creation. Send it asaliOrderId,orderIdListororderIdsas required by the selected API. Keep all IDs as strings. Existing-order queries do not require creating a new order.For a shipment, select
logisticsIdfrom the order logistics result. For an invoice, copy each order's amount from the invoice amount result unchanged in cents and provide your actual invoice title details.
Request parameters and response index
Each link opens the complete request schema, required and conditional fields, types, supported values and response schema. These summaries do not replace the schemas. All operations use POST JSON and your Nexscope API key.
| Operation | Request parameters | Business response and next step |
|---|---|---|
| authorizeUrl | accountName: a nonblank buyer-account label. | authorizeUrl: open manually and complete authorization within 10 minutes. |
| authorizedStores | An empty object; the current Nexscope user is selected automatically. | stores[].accountName, status and expired. Continue only with ACTIVE and expired=false. |
| receiveAddressList | An empty object; uses your authorized buyer account. | items[].addressId and recipient/address details. Use your actual addressId. |
| sku | offerId: a positive decimal ID string. | skuList[].specId, price and amountOnSale. Select specId for a product specification. |
| orderPreview | addressId or addressParam, cargoParamList and flow; optional invoiceParam. | status, sumPayment, sumCarriage, discountFee, cargoList and payment/promotion options. Stop if status=false. |
| createOrder | Address, cargo and flow inputs; confirmCreateOrder=true. See the schema for optional creation fields; invoiceParam is preview-only. | success, orderId and business messages. Save orderId for later reconciliation. |
| paymentUrl | orderIdList: a nonempty string array; confirmGetPaymentUrl=true. | success, payUrl, errorMessage and errorCode. Never open or pay automatically. |
| orderStatus | aliOrderId: the actual order ID as a string. | aliOrderId, aliStatus and normalizedStatus. |
| logistics | aliOrderId: the actual order ID as a string. | logisticsOrders[].logisticsId, logisticsBillNo, logisticsCompanyName and status. |
| logisticsTrace | aliOrderId; optional logisticsId from logistics. | traceList[].traceTime, location, traceDescription and traceStatus. Times use Asia/Shanghai. |
| confirmReceive | aliOrderId and confirmReceive=true. | success and aliOrderId. Confirm receipt only after checking the shipment. |
| cancelOrder | aliOrderId and confirmCancel=true; optional cancelReason and remark. | success, aliOrderId, compatibility orderId and message. Cancellation is not a refund request. |
| invoiceAmount | orderIds: a nonempty array of positive decimal ID strings. | orderInvoiceAmountModelList[].orderId/amount and retCodes. Copy each amount unchanged in cents. |
| invoiceApply | invoiceApplyModelList with orderId, amount, invoiceType and purchaserInvoiceTitleModel; confirmApplyInvoice=true. | successList and failedList, including per-order errors. Inspect both lists even when the platform code is 0. |
Send product, SKU and order IDs as strings. For direct API requests, provide flow explicitly: general, fenxiao or boutiquefenxiao. The procurement Skill scripts default an omitted flow to general. Use distribution modes only when intended.
Preview totals, shipping and discounts are in cents; cargoList.finalUnitPrice and cargoList.amount are in yuan. SKU prices and stock are indicative; the preview determines purchasability and final amounts. Keep invoiceAmount values unchanged in cents.
Nexscope returns code, msg, data, ts, time, cost and traceId. Numeric outer code=0 means platform success; HTTP 200 alone does not. The procurement result keeps its provider code/message/data wrapper; inspect the business result inside data.data, including status, success and invoice rows. The outer cost field is elapsed time, not credits.
Actions that require confirmation
Confirm each exact action and its parameters separately. The confirmation field must be the JSON boolean true, not a string or number. Changing the account, order, goods, address, invoice details or other parameters requires a new confirmation. Online test requests confirmation before execution.
confirmCreateOrder: Create a real order after a successful preview.confirmGetPaymentUrl: Retrieve a payment link; this does not make a payment.confirmReceive: Confirm receipt of the exact order.confirmCancel: Attempt to cancel the exact order; this does not request a refund.confirmApplyInvoice: Submit invoice applications with the confirmed title and exact per-order amounts.
Do not automatically retry an uncertain write after a timeout or network error. Check order or invoice state first, then obtain confirmation for any further attempt. Never automatically open a payment link or make a payment.
Errors and how to recover
Check the HTTP status, Nexscope outer code and business result separately. Supplier 1002/1003/1005 codes are not Nexscope outer codes. Gateway HTTP authentication or credit errors can also occur; do not rely on HTTP status alone.
11209: API key is missing or does not exist. Supply your Nexscope API key; this can be returned with HTTP 200.99001: Invalid parameters or missing confirmation. Follow the English message, correct the request and confirm again when necessary. Procurement pricing configuration errors also require support to check the service configuration.13007: Buyer authorization is unavailable, or a procurement service/proxy call failed. Read the message and check authorization when indicated; not every 13007 requires reauthorization. Do not switch to another buyer or repeat an uncertain write.13011: Insufficient Nexscope credits. Check your Nexscope balance.99000: Unexpected service failure. Keep the traceId when provided and contact support; reconcile uncertain writes before any retry.code=0with businessstatus=falseorsuccess=false: The business operation failed or partially failed. Stop dependent actions and inspect business messages and per-order results. INVOICE_ALREADY_APPLIED means the order is already invoiced; do not resubmit the whole batch.
Request parameters
| Name | Type | Required | Description |
|---|---|---|---|
orderIds | array | required | orderIds Minimum items: 1 |
orderIds[] | string | required | Exact positive integer identifier. Send as a JSON string. Pattern: ^[1-9][0-9]*$ |
Response example
Platform response envelope. code 0 indicates success or acceptance; data contains the business result.
{
"code": 0,
"cost": "0",
"data": {
"orderInvoiceAmountModelList": [
{
"amount": 840,
"orderId": "3309156590237728779"
}
],
"retCodes": [
"SUCCESS"
],
"success": true
},
"msg": null,
"time": "2026-10-20T00:00:00Z",
"traceId": null,
"ts": "0"
}Response fields
| Name | Type | Required | Description |
|---|---|---|---|
code | integer | optional | Nexscope transport/business envelope code; 0 means the request was processed. Inspect data for operation outcomes. |
cost | string | optional | Processing time in milliseconds, not credits. |
data | object | optional | Data value used by this API operation. |
data.code | string | optional | Upstream business code. |
data.message | string | optional | Message value used by this API operation. |
data.orderInvoiceAmountModelList | array | optional | Order invoice amount model list value used by this API operation. |
data.orderInvoiceAmountModelList[] | object | required | Item in data orderInvoiceAmountModelList. |
data.orderInvoiceAmountModelList[].amount | number | optional | Cents; copy unchanged into invoiceApply. |
data.orderInvoiceAmountModelList[].orderId | string | optional | Exact positive integer identifier. Send as a JSON string. Pattern: ^[1-9][0-9]*$ |
data.retCodes | array | optional | Ret codes value used by this API operation. |
data.retCodes[] | any | required | Item in data retCodes. |
data.subCode | string | optional | Sub code value used by this API operation. |
data.subMessage | string | optional | Sub message value used by this API operation. |
data.success | boolean | optional | Inspect this business outcome even when HTTP status is 200. |
msg | string | null | optional | Safe response message. |
time | string | optional | Server response time. |
traceId | string | null | optional | Request trace identifier. |
ts | string | optional | Server timestamp. |
Responses
| Code | Description |
|---|---|
| 200 | Default HTTP response for both success and many business errors. Only outer JSON code 0 indicates success or asynchronous acceptance; inspect data for the result. |
| 429 | Execution admission rate limit; honor Retry-After when present. |
| 503 | Execution admission is temporarily unavailable; honor Retry-After when present. |
| Opt-in | X-Nexscope-Http-Status: semantic maps controller-handled business errors to HTTP status on run and task routes. Pre-authentication failures, such as a missing API key (code 11209), may still return HTTP 200 before this mapping. Always check the outer JSON code; malformed requests and infrastructure failures may also return non-200 HTTP responses. |
Data source, freshness, and limitations
Source, freshness, coverage, rate limits, and estimation notes are not specified in this API definition unless they appear in the request or response field documentation above. Do not assume official marketplace data or real-time freshness when it is not explicitly documented.