> ## Documentation Index > Fetch the complete documentation index at: https://docs.poderp.com/llms.txt > Use this file to discover all available pages before exploring further. # Upload Order File > Import an Excel order list using the same template parser and factory validation as the operator upload screen. Customer ownership comes from the API key. The operation always creates orders; no selectedUser, customerId or action is needed. Database changes are rolled back if any row fails. Image downloads and downstream order processing are asynchronous. This endpoint becomes available after the backend release containing it is deployed. Upload an Excel order list with the same parsing template used by operators in the order import screen. This endpoint uses your existing customer API key. > [!NOTE] > > Availability requires the backend release containing this endpoint to be deployed. ## Prepare the order file 1. Call [List Order Templates](https://docs.poderp.com/api-reference/endpoint/list-order-templates.md) and choose an enabled order template. 2. Prepare one `.xlsx` or `.xls` file whose headers match the template's `columns`. The file must contain at least one data row. 3. Include your customer name in the filename, as in the operator workflow. For customer `ZTQ`, `26ZTQ018.xlsx` is valid. 4. Send a `multipart/form-data` request. Let your HTTP client generate the multipart boundary. The API key determines the order customer. Do not send `selectedUser`, `customerId`, `action` or an operator login token. This endpoint always imports orders and preserves the existing Excel order and factory validation rules. ## Example ```bash theme={null} curl --request POST 'https://api.platform.poderp.com/api/openapi/order/upload' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --form 'templateId=YOUR_TEMPLATE_ID' \ --form 'file=@26ZTQ018.xlsx' \ --form 'urlSplitToken=0' \ --form 'namingType=default' \ --form 'newImageDownload=true' \ --form 'needDownloadImage=false' ``` This example matches the screenshot workflow: import orders, use pipe-separated image URLs, select the new downloader, and disable image downloads. Set `needDownloadImage=true` to create image download tasks. To include attachments, repeat the field: ```bash theme={null} --form 'attachments=@notes.pdf' \ --form 'attachments=@artwork.zip' ``` Supported attachment formats include archives (`zip`, `rar`, `7z`, `tar`, `gz`), spreadsheets (`xlsx`, `xls`, `csv`), documents (`pdf`, `doc`, `docx`), images (`jpg`, `jpeg`, `png`, `gif`, `bmp`, `webp`) and text (`txt`, `json`, `xml`). Attachments are stored with the order batch; they do not replace image URLs in the spreadsheet. ## Options | Field | Default | Meaning | | - | - | - | | `templateId` | Required | Template ID from List Order Templates | | `file` | Required | One Excel order list | | `attachments` | None | Optional attachment files | | `urlSplitToken` | `0` | `0`: pipe, `1`: semicolon, `2`: newline | | `namingType` | `default` | `default`, `simple`, `random`, or `sku` | | `needDownloadImage` | `true` | Enable asynchronous image downloads | | `newImageDownload` | `false` | Use the new downloader when image downloads are enabled | ## Success and follow-up queries ```json theme={null} { "success": true, "totalRows": 12, "mainOrderId": "1234567890123456789", "uniqueRequestId": "server-generated-batch-key", "errors": [] } ``` Save `uniqueRequestId`. Use it with [Query Orders](https://docs.poderp.com/api-reference/endpoint/query-order.md), [Query Waybills](https://docs.poderp.com/api-reference/endpoint/query-waybills.md) and [Query Trackings](https://docs.poderp.com/api-reference/endpoint/query-trackings.md). A successful upload means the order batch was imported; factory matching, shipment creation and image downloads can still be pending. ## Validation failures If a row fails validation, HTTP 400 includes Excel row numbers. No orders from that file are committed: ```json theme={null} { "success": false, "totalRows": 12, "mainOrderId": null, "uniqueRequestId": null, "errors": [ { "rowIndex": 2, "errors": ["SKU validation failed"] } ] } ``` Other request errors (such as an empty file, unsupported format, unavailable template or malformed workbook) return HTTP 400 with `code`, `msg` and optional `data`. Missing or invalid API keys return HTTP 401. Existing order numbers are rejected by the Excel import duplicate checks. The endpoint does not accept a client-generated idempotency key. If a request times out, check the order batch in the operator dashboard before uploading the same file again. ## OpenAPI ````yaml POST /api/openapi/order/upload openapi: 3.1.0 info: title: Pod ERP OpenAPI description: Pod ERP Open API for order management license: name: MIT version: 2.0.0 servers: - url: https://api.platform.poderp.com security: - bearerAuth: [] paths: /api/openapi/order/upload: post: summary: Upload Order File description: >- Import an Excel order list using the same template parser and factory validation as the operator upload screen. Customer ownership comes from the API key. The operation always creates orders; no selectedUser, customerId or action is needed. Database changes are rolled back if any row fails. Image downloads and downstream order processing are asynchronous. This endpoint becomes available after the backend release containing it is deployed. operationId: uploadOrderFile requestBody: required: true content: multipart/form-data: schema: type: object required: - templateId - file properties: templateId: type: integer format: int64 description: Enabled order template ID from List Order Templates. file: type: string format: binary description: >- One non-empty .xlsx or .xls order file. Filename must contain the authenticated customer name; headers must match the selected template. attachments: type: array items: type: string format: binary description: >- Optional attachments. Repeat the attachments multipart field for multiple files. namingType: type: string enum: - default - simple - random - sku default: default urlSplitToken: type: string enum: - '0' - '1' - '2' default: '0' description: 'Image URL separator: 0 = pipe, 1 = semicolon, 2 = newline.' needDownloadImage: type: boolean default: true description: >- Create asynchronous image download tasks. Set false to import orders only. newImageDownload: type: boolean default: false description: >- Use the new image downloader. Ignored when needDownloadImage is false. responses: '200': description: Order batch imported; downstream processing may still be pending content: application/json: schema: $ref: '#/components/schemas/OrderFileUploadResponse' '400': description: Row validation failure, or request/file/template error content: application/json: schema: oneOf: - $ref: '#/components/schemas/OrderFileUploadResponse' - $ref: '#/components/schemas/OrderFileErrorResponse' '401': description: Missing or invalid API key components: schemas: OrderFileUploadResponse: type: object required: - success - totalRows - errors properties: success: type: boolean totalRows: type: integer mainOrderId: type: - string - 'null' description: Created batch ID, encoded as a string to preserve precision. uniqueRequestId: type: - string - 'null' description: >- Server-generated batch key for Query Orders, Query Waybills and Query Trackings. Only returned on success. errors: type: array items: $ref: '#/components/schemas/OrderFileRowError' OrderFileErrorResponse: type: object required: - code - msg properties: code: type: string msg: type: string data: {} OrderFileRowError: type: object required: - rowIndex - errors properties: rowIndex: type: integer description: Excel row number, starting at 2 for the first data row. errors: type: array items: type: string securitySchemes: bearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.