> ## Documentation Index
> Fetch the complete documentation index at: https://docs.global-e.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Upload shipment documents (Merchant to Global-e)
> Attach a customs document — the EAD and its MRN reference — to a shipment Global-e has already created, before the parcel is dispatched.
This API is enabled per merchant account by Global-e. If it is not enabled for your account, the request returns `403 Forbidden` with no response body.
**Typical integration sequence.** These APIs may be used together when an export declaration or bonded reporting is required, but they are **independent endpoints** — none is a prerequisite for another.
1. [Get shipping documents](/api-reference/get-shipping-documents) — obtain the label and tracking number
2. [Submit bonded information](/api-reference/submit-bonded-information) — report bonded vs free-circulation status per product *(when bonded reporting is required)*
3. [Get shipment information](/api-reference/get-shipment-information) — retrieve product, pricing and declaration header data *(when you need the data Global-e holds)*
4. Create the export document — your side, not a Global-e API
5. **Upload shipment documents** — upload the document and its reference to Global-e *(when a document must be attached)*
6. [Dispatch orders](/api-reference/dispatch-orders) — End of Day
Only steps 1 and 6 are universal. Steps 2 to 5 depend on the shipment type, the destination and your configuration. Where they apply, complete steps 2 and 5 **before End of Day / Dispatch orders**.
An export declaration is required only when the shipment leaves the EU customs territory **and** either contains bonded goods or contains free-circulation goods with a total value of €1,000 or more. When no declaration is required, steps 3 to 5 do not apply.
A successful response means Global-e has stored the document against the shipment. Global-e forwards the document and its reference to the carrier asynchronously afterwards, so a success response is not a confirmation that the carrier has accepted it.
## OpenAPI
````yaml api-reference/specs/uploadshipmentdocuments.yaml POST /api/shipments/documents/upload
openapi: 3.0.3
info:
title: UploadShipmentDocuments
version: 1.0.0
description: >-
The Upload Shipment Documents API lets you attach a customs document —
currently the EAD (Export Accompanying Document) and its MRN reference — to
a shipment that Global-e has already created. Global-e stores the document
against the shipment and forwards it, with its reference, to the carrier so
that the customs paperwork is in place before pickup.
servers:
- url: https://{globale_api_domain}
variables:
globale_api_domain:
default: globale_api_domain
description: Global-e API host, supplied to the merchant by Global-e.
security: []
tags:
- name: UploadShipmentDocuments
x-page-title: UploadShipmentDocuments
- name: 'Direction: Merchant → Global-e'
- name: 'Domain: Shipping'
paths:
/api/shipments/documents/upload:
post:
tags:
- UploadShipmentDocuments
summary: Attach customs documents to a shipment
description: >-
Attaches one or more customs documents to a shipment that Global-e has
already created. The current supported document type is the EAD (Export
Accompanying Document) — the customs export declaration PDF — together
with its MRN (Movement Reference Number), which is sent as the document
reference.
The shipment is identified by the tracking number returned by
GetShippingDocuments. If the shipment or any of its documents fails
validation, Global-e rejects the whole call and stores nothing.
Call this endpoint once the export document exists and before End of Day
/ DispatchOrders. Global-e accepts documents only while the parcel is in
an allowed status — for example Received in Hub or Shipped by Merchant.
A parcel that is no longer in an allowed status is rejected with A611.
Uploading a document of the same type again for the same tracking number
replaces the stored document and its reference — the latest upload wins.
Re-uploading is not an error while the parcel is still in an allowed
status.
This API is enabled per merchant account by Global-e. When it is not
enabled, the request returns 403 with no response body.
operationId: uploadShipmentDocuments
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UploadShipmentDocumentsRequest'
examples:
eadUpload:
summary: Attach an EAD and its MRN reference
value:
TrackingNumber: JD014600004882753258
Documents:
- DocumentType: EAD
DocumentReference: 26GB02I89012847596
DocumentData: JVBERi0xLjcNCi...
responses:
'200':
description: >-
The document was validated and stored against the shipment. Storage
only — Global-e forwards the document and its reference to the
carrier asynchronously afterwards, so this response is not a
confirmation that the carrier has accepted it.
content:
application/json:
schema:
$ref: '#/components/schemas/UploadShipmentDocumentsResponse'
example:
Success: true
'400':
description: >-
The call was rejected and nothing was stored. Codes A600 (invalid
request body), A610 (tracking number not found), A611 (parcel not in
an allowed status), A612 (unsupported document type), A613 (missing
document reference), A614 (invalid or missing document data), A615
(invalid document fields), A616 (document exceeds the maximum size),
A617 (no documents provided).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalidRequestBody:
summary: A600 — invalid request body
value:
Code: A600
Error: INVALID_REQUEST
Description: Request body must be a single shipment object.
trackingNumberNotFound:
summary: A610 — tracking number not found
value:
Code: A610
Error: INVALID_REQUEST
Description: Tracking number not found for this merchant.
parcelDispatched:
summary: A611 — parcel not in an allowed status
value:
Code: A611
Error: INVALID_REQUEST
Description: >-
Parcel not in an allowed status. Documents are only
accepted before End of Day.
unsupportedDocumentType:
summary: A612 — unsupported document type
value:
Code: A612
Error: INVALID_REQUEST
Description: Unsupported document type.
missingDocumentReference:
summary: A613 — missing document reference
value:
Code: A613
Error: INVALID_REQUEST
Description: Missing required reference.
invalidDocumentData:
summary: A614 — invalid or missing document data
value:
Code: A614
Error: INVALID_REQUEST
Description: Invalid or missing document data.
invalidDocumentFields:
summary: A615 — invalid document fields
value:
Code: A615
Error: INVALID_REQUEST
Description: Invalid document fields.
documentTooLarge:
summary: A616 — document exceeds the maximum size
value:
Code: A616
Error: INVALID_REQUEST
Description: Document exceeds maximum size.
noDocumentsProvided:
summary: A617 — no documents provided
value:
Code: A617
Error: INVALID_REQUEST
Description: No documents provided.
'401':
description: Authentication credentials are missing, invalid, or expired (A602).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
Code: A602
Error: UNAUTHORIZED
Description: Authentication failed.
'403':
description: >-
The Upload Shipment Documents API is not enabled for this merchant
account. No response body and no error code are returned. Contact
your Global-e account manager to have it enabled.
'500':
description: An unexpected error occurred in the Global-e system (A603).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
Code: A603
Error: INTERNAL_ERROR
Description: An unexpected error occurred while processing the request.
components:
schemas:
UploadShipmentDocumentsRequest:
type: object
title: UploadShipmentDocumentsRequest
required:
- TrackingNumber
- Documents
properties:
TrackingNumber:
type: string
description: >-
Tracking number of the shipment, as returned by
GetShippingDocuments. Identifies the shipment the documents are
attached to, and must belong to your merchant account.
example: JD014600004882753258
Documents:
type: array
minItems: 1
description: >-
The documents to attach to this shipment. At least one document must
be provided; an empty list is rejected with A617. The current
supported document type is EAD, and one EAD is attached per call.
The list is an array so that further document types can be added
later without changing the shape of the request.
items:
$ref: '#/components/schemas/ShipmentDocument'
UploadShipmentDocumentsResponse:
type: object
title: UploadShipmentDocumentsResponse
properties:
Success:
type: boolean
description: >-
Indicates that the document was stored against the shipment.
Returned only with HTTP 200, and always true. Failures are returned
as an error response instead.
example: true
ErrorResponse:
type: object
title: ErrorResponse
description: >-
General Global-e error envelope. Returned for every failure; the call is
rejected in full and nothing is stored.
properties:
Code:
type: string
description: Merchant-facing error code.
enum:
- A600
- A602
- A603
- A610
- A611
- A612
- A613
- A614
- A615
- A616
- A617
example: A610
Error:
type: string
description: >-
Short error category — INVALID_REQUEST for HTTP 400, UNAUTHORIZED
for HTTP 401, INTERNAL_ERROR for HTTP 500.
example: INVALID_REQUEST
Description:
type: string
description: Human-readable reason for the failure.
example: Tracking number not found for this merchant.
ShipmentDocument:
type: object
title: ShipmentDocument
required:
- DocumentType
- DocumentData
properties:
DocumentType:
type: string
description: >-
The type of document you are attaching. EAD is the Export
Accompanying Document — the customs export declaration. Any other
value is rejected with A612.
enum:
- EAD
example: EAD
DocumentReference:
type: string
description: >-
The customs reference of the document. Required when DocumentType is
EAD, where it carries the MRN (Movement Reference Number) of the
export declaration. Global-e rejects an EAD sent without a reference
with A613.
example: 26GB02I89012847596
DocumentData:
type: string
format: byte
description: >-
The document itself, base64-encoded. The file format follows from
DocumentType — a PDF for an EAD. The decoded document must not
exceed the maximum document size, currently 2 MB; a larger document
is rejected with A616.
example: JVBERi0xLjcNCi...
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.