> ## Documentation Index > Fetch the complete documentation index at: https://developers.cubbo.com/llms.txt > Use this file to discover all available pages before exploring further. # Upload shipping documents to an order > Attaches one or more files (shipping labels, invoices, other printable documents) to an order. Files are sent as base64 strings inside a JSON body, not as multipart form data. Use it to provide the shipping label of an order that ships with your own carrier, or to add documents the warehouse must print and include in the package. - Documents are appended; documents that have content are not removed. Use `PUT /orders/{id}` with `shipping_documents` if you need to replace the ones you uploaded before. - An existing document of the same `printing_type` whose file is empty is replaced by the one you upload, so the warehouse prints the new file instead of the empty one. Use this to fix a label that arrived empty. - If you send a document without `metadata`, it keeps the metadata of the empty document it replaces. For a `label`, if no empty document had any, it takes the metadata sent with a label URL of this order that has not given back a label yet. - Each file must have content, and a file declared as `application/pdf` must be a PDF. Otherwise the request is refused with `422` and nothing is stored or removed. - The order can be in any status. If the order is in `error` (for example because its label was missing), it is automatically re-processed after the upload. - Accepted file types: PDF, PNG and JPEG, each under 5 MB. `metadata` is free-form JSON of at most 10 KB. - At least one document is required. - Requires an API user with the "orders update" permission and access to the store. ## OpenAPI ````yaml /openapi.yaml patch /orders/{id}/upload-shipping-documents openapi: 3.1.0 info: title: Cubbo Clients API version: '1.0' summary: >- Orders, inventory, replenishments, returns, shipping and webhooks for Cubbo fulfillment. description: > The Cubbo Clients API connects your store, ERP or marketplace with Cubbo's fulfillment network. All endpoints except `POST /auth/token` require a bearer token; see the Authentication guide. Request and response bodies are JSON. Errors are JSON objects with an `error` key. contact: name: Cubbo integrations email: integraciones@cubbo.com servers: - url: https://api.cubbo.com/v1 description: Production security: - bearerAuth: [] tags: - name: Authentication description: Exchange client credentials for a bearer token. - name: Orders description: Create, update, hold, cancel and read sales orders. - name: Shipping labels description: Read the shipping labels generated for an order. - name: Inventory description: Products and stock per store. - name: Lots description: Lot-level inventory for products with expiration or batch tracking. - name: Reports description: Bulk reports for reconciliation. - name: Replenishments description: Inbound shipments to the warehouse. - name: Returns description: Returns and exchanges. - name: Stores description: Store provisioning and settings. - name: Shipping methods description: Available shipping methods, coverage and quotes. - name: Click and collect description: Pickup points and in-store pickup orders. paths: /orders/{id}/upload-shipping-documents: patch: tags: - Orders summary: Upload shipping documents to an order description: > Attaches one or more files (shipping labels, invoices, other printable documents) to an order. Files are sent as base64 strings inside a JSON body, not as multipart form data. Use it to provide the shipping label of an order that ships with your own carrier, or to add documents the warehouse must print and include in the package. - Documents are appended; documents that have content are not removed. Use `PUT /orders/{id}` with `shipping_documents` if you need to replace the ones you uploaded before. - An existing document of the same `printing_type` whose file is empty is replaced by the one you upload, so the warehouse prints the new file instead of the empty one. Use this to fix a label that arrived empty. - If you send a document without `metadata`, it keeps the metadata of the empty document it replaces. For a `label`, if no empty document had any, it takes the metadata sent with a label URL of this order that has not given back a label yet. - Each file must have content, and a file declared as `application/pdf` must be a PDF. Otherwise the request is refused with `422` and nothing is stored or removed. - The order can be in any status. If the order is in `error` (for example because its label was missing), it is automatically re-processed after the upload. - Accepted file types: PDF, PNG and JPEG, each under 5 MB. `metadata` is free-form JSON of at most 10 KB. - At least one document is required. - Requires an API user with the "orders update" permission and access to the store. operationId: uploadOrderShippingDocuments parameters: - name: id in: path required: true description: Cubbo order id. schema: type: integer example: 123456 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ShippingDocumentsUploadRequest' example: shipping_documents: - filename: label.pdf base64_data: >- JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwvTGVuZ3RoIDMgMCBSL0ZpbHRlci9GbGF0ZURlY29kZT4+CnN0cmVhbQ== content_type: application/pdf printing_type: label document_type: base64 metadata: tracking_number: TRACK0000001 carrier: DHL responses: '200': description: The documents were stored. content: application/json: schema: $ref: '#/components/schemas/ShippingDocumentsUploadResponse' example: message: 'Shipping documents uploaded: label.pdf' '401': $ref: '#/components/responses/Unauthorized' '422': description: Validation error. content: application/json: schema: $ref: '#/components/schemas/Error' examples: emptyList: value: error: >- shipping_documents is expected to be an array of at least one element. missingField: value: error: Parameter base64_data is required orderNotFound: value: error: Couldn't find Order with 'id'=123456 emptyFile: value: error: shipping document label.pdf is empty notAPdf: value: error: shipping document label.pdf is not a PDF '500': description: >- Unexpected error. Also returned when a file is rejected for its type (other than PDF, PNG or JPEG), size (over 5 MB) or metadata (over 10 KB). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: unexpected error security: - bearerAuth: [] components: schemas: ShippingDocumentsUploadRequest: type: object description: One or more documents, each sent as base64 inside the JSON body. required: - shipping_documents properties: shipping_documents: type: array minItems: 1 description: Documents to attach to the order. items: $ref: '#/components/schemas/ShippingDocumentUpload' ShippingDocumentsUploadResponse: type: object description: Confirmation listing the stored file names. required: - message properties: message: type: string description: Confirmation message with the uploaded file names, comma separated. example: 'Shipping documents uploaded: label.pdf' Error: type: object description: Error body returned by every failed request. required: - error properties: error: type: string description: >- Human-readable description of the failure. For `401` responses it is always `Unauthorized`. example: Parameter store_id is required message: type: string description: >- Present on `401` responses only; the reason the request was rejected. example: invalid token code: type: - string - 'null' description: >- Stable machine-readable code, present on some order, return and replenishment errors. example: ORDER_ALREADY_EXISTS context: type: - object - 'null' description: >- Extra data about the failure when available, for example the id of the conflicting order. additionalProperties: true example: order_id: 987654 ShippingDocumentUpload: type: object description: >- A document sent as base64. Same fields as the documents accepted by `PUT /orders/{id}`, except that the content key is `base64_data`. required: - filename - base64_data - content_type - printing_type - document_type properties: filename: type: string description: File name, including extension. example: label.pdf base64_data: type: string description: >- File contents encoded in base64. A `data:...;base64,` prefix is tolerated. example: JVBERi0xLjQKJcOkw7zDtsOfCg== content_type: type: string description: MIME type of the file. PDF, PNG and JPEG are accepted. enum: - application/pdf - image/png - image/jpeg example: application/pdf printing_type: type: string description: >- How the warehouse must print and use the document. `label` is a shipping label; `document` is any other printable to include in the package. enum: - label - document - difal_bill - difal_payment_receipt - identifier_label - oxxo_digital_card example: label document_type: type: string description: >- Origin of the document. Use `base64` for documents you upload; `file` marks Cubbo-generated documents and is never replaced by `PUT /orders/{id}`. enum: - base64 - url - file example: base64 metadata: type: object description: >- Free-form JSON stored with the document (at most 10 KB), for example the tracking number of a label. additionalProperties: true example: tracking_number: TRACK0000001 carrier: DHL responses: Unauthorized: description: >- Missing or invalid token, wrong credentials, or no access to the requested store. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalidToken: value: error: Unauthorized message: invalid token noHeader: value: error: Unauthorized message: no authorization header found storeNotAllowed: value: error: Unauthorized message: not allowed to show? this Store securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Token returned by `POST /auth/token`, sent as `Authorization: Bearer `. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.