---
title: "v2-uploadOrderDocument - Upload a document for an order"
method: POST
path: "/v2/orders/{order_id}/documents"
tags: ["Orders"]
---

# v2-uploadOrderDocument - Upload a document for an order

`POST /v2/orders/{order_id}/documents`

## Request

- Base URL: `https://miraklconnect.com/api`
- URL: `https://miraklconnect.com/api/v2/orders/{order_id}/documents`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/mirakl/apis/mirakl-connect-apis/docs/v2/orders/:order_id/documents/post.ts> (a function with typed inputs; its response is checked against the schema)

<div class="extension-title">Description</div>

Use this API to upload a document for an order or its related entities (e.g. returns).

Supported document types are :
  - <code>RETURN_LABEL</code>
  - <code>CUSTOMER_INVOICE</code>


<div class="api-description-extension">
<div class="extension-title">Call Frequency</div>

<div class="recommended-call-frequency">Recommended usage: On each document upload</div>
<div class="max-call-frequency">Maximum usage: On each document upload</div>
</div>

## Path parameters

- `order_id` string, required

## Request body `multipart/form-data`

- object
  - `file` string, binary, required: The document file to upload. Maximum file size: <code>10 MB</code>. Supported formats are : - <code>PDF</code> - <code>JPEG</code> - <code>PNG</code> - <code>CSV</code>
  - `metadata` UploadOrderDocumentMetadata, required
    - `entity` object: The entity this document is associated with. Required on some marketplaces when type is: - <code>RETURN_LABEL</code>
      - `id` string, required: The id of the entity (e.g. <code>returnId</code> for entity_type : <code>RETURN</code>) this document is associated with.
      - `type` 'RETURN', required: The type of entity this document is associated with.
    - `filename` string, required: Name of the document (only this field counts as the file name). We recommend including a way to distinguish the document type in this field.
    - `type` 'RETURN_LABEL' | 'CUSTOMER_INVOICE', required: Type of the document

## Response `202`

Accepted. The document upload request will be processed asynchronously.

- AsynchronousActionResponse
  - `action_id` string, required: The unique identifier for the asynchronous action. It should be used with the [v2-getActionStatus API](#operation/v2-getActionStatus) to retrieve current action status and potential errors.
  - `tracking_id` string: **Deprecated:** This field was previously used to obtain the action ID. It has been replaced by `action_id` and contains the same value. It is retained for backward compatibility.

## Other responses

- `400`: The document has not been uploaded because of wrong or missing parameters, invalid/unsupported file type, or file size exceeds limit.
- `404`: The document has not been uploaded because the order or entity does not exist.

## Changes

- **2026-10-14** `d12b10bceb6a`: 2 breaking, 3 info
  - request property `metadata/entity/type` was restricted to a list of enum values
  - request property `metadata/type` was restricted to a list of enum values
  - added the new `CUSTOMER_INVOICE` enum value to the request property `metadata/type`
  - added the new `RETURN` enum value to the request property `metadata/entity/type`
  - …1 more

[Operation history](https://skmtc.dev/mirakl/apis/mirakl-connect-apis/changes/v2/orders/:order_id/documents/post.md)

---

[API](https://skmtc.dev/mirakl/apis/mirakl-connect-apis.md) - [All operations](https://skmtc.dev/mirakl/apis/mirakl-connect-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/mirakl/apis/mirakl-connect-apis/revisions/c0527a972b89?raw)