Upload Document

This endpoint allows uploading a document to an existing shipment. Documents can be used for shipping purposes such as commercial invoices, packing lists, certificates, etc.

How Document Upload Works:

Documents are first uploaded and stored in Carriyo, and then synced to the carrier system. You can upload documents at any stage of the shipment lifecycle - before or after the shipment is booked. However, the document will only be uploaded to the carrier after the shipment is booked.

  • Before booking: The document is stored in Carriyo and will be automatically uploaded to the carrier once the shipment is booked (if carrier upload is configured).
  • After booking: The document is stored in Carriyo and immediately queued for upload to the carrier (if carrier upload is configured and the carrier supports it).

Prerequisites:

  • A document setting must be configured in your Carriyo account before uploading documents.
  • The document must match an existing document setting either by document_id or document_name.

Important Behavior:

  • If the document setting is not found, the request will be rejected with a 400 error.
  • If a document with the same document ID already exists in the shipment, the request will be rejected.
  • The document content must be provided as a Base64-encoded string.
  • Only PDF format is currently supported.
  • Security validation is performed on the document content to ensure it matches the expected format.

Automatic Carrier Sync: If the document setting is configured for carrier upload, Carriyo will automatically sync the document to the carrier when all of the following conditions are met:

  • A carrier is assigned to the shipment
  • The shipment is booked (has a tracking number)
  • The carrier supports document upload

Supported Carriers: At the moment, document upload synchronization to carrier is supported only for:

  • DHL
  • FedEx

For other carriers, documents will be stored in Carriyo but will not be synced to the carrier system.

The sync happens asynchronously. The carrier_upload_status field in the document object will indicate the status of this upload:

  • pending: Upload to carrier is in progress
  • complete: Document was successfully uploaded to the carrier
  • error: Upload failed - check the message field for details

If the carrier upload fails, you can use the Retry Document Upload endpoint to attempt the upload again.

The shipment_id is used as a path parameter to identify the shipment. Alternatively the merchant provided shipment reference (partner_shipment_reference) can also be used instead of the shipment_id.

SecurityOAuth2-Production or OAuth2-Demo
Request
path Parameters
shipment_id
required
string

The Carriyo shipment ID or the merchant provided partner_shipment_reference.

header Parameters
x-api-key
required
string
tenant-id
required
string
Content-Type
required
string
Default: application/json
Request Body schema: application/json
required
document_id
string

The ID of the document setting to use for this upload. The document setting must be pre-configured in your Carriyo account. Either document_id or document_name must be provided.

document_name
string

The name of the document setting to use for this upload. If multiple document settings have the same name, the first match will be used. Either document_id or document_name must be provided.

content_base64
required
string

The document content encoded as a Base64 string. Currently only PDF format is supported.

Responses
200

Document uploaded successfully. Returns the updated shipment object.

400

Bad Request - Document settings not found, document already exists, or validation failed.

404

Shipment not found.

post/shipments/{shipment_id}/documents
Request samples
application/json
{
  • "document_id": "DOC123",
  • "content_base64": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFI+PgplbmRvYmoKMiAwIG9iago..."
}
Response samples
application/json
{
  • "shipment_id": "XYZABC123",
  • "entity_type": "FORWARD",
  • "merchant": "MY_BRAND",
  • "references": {
    },
  • "carrier_account": {
    },
  • "payment": {
    },
  • "insurance": {
    },
  • "collection": {
    },
  • "delivery": {
    },
  • "pickup": {
    },
  • "dropoff": {
    },
  • "items": [
    ],
  • "freight": {
    },
  • "customs": {
    },
  • "charges": [
    ],
  • "parcels": [
    ],
  • "post_shipping_info": {
    },
  • "custom_attributes": { },
  • "order_date": "2022-01-01T09:00:00.000Z",
  • "order_type": "HOME_DELIVERY",
  • "creation_date": "2022-01-01T09:00:00.000Z",
  • "update_date": "2022-01-01T09:00:00.000Z",
  • "confirmation_date": "2022-01-01T09:00:00.000Z",
  • "estimated_process_date": "2019-08-24T14:15:22Z",
  • "promised_delivery_date": "2022-01-01T09:00:00.000Z",
  • "original_promised_delivery_date": "2022-01-01T09:00:00.000Z",
  • "estimated_shipping_cost": {
    },
  • "language": "en",
  • "return_request_id": "rma_123abcXYZ"
}