Bulk Upload Documents

This endpoint allows uploading or updating multiple documents on an existing shipment in a single request.

How Bulk Document Upload Works: Each document in the request is validated and processed individually. If a document with the same document ID already exists in the shipment, its content will be updated. If the document does not exist, it will be created. 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 documents will only be uploaded to the carrier after the shipment is booked.

Prerequisites:

  • A document setting must be configured in your Carriyo account for each document being uploaded.
  • Each document must match an existing document setting either by document_id or document_name.

Important Behavior:

  • If any 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, its content will be replaced with the new content.
  • If the document does not exist in the shipment, it will be created.
  • The document content must be provided as a Base64-encoded string.
  • Only PDF format is currently supported.
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
Array
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

Documents uploaded or updated successfully. Returns the updated shipment object.

400

Bad Request - Document settings not found or validation failed.

404

Shipment not found.

post/shipments/{shipment_id}/documents/bulk
Request samples
application/json
[
  • {
    },
  • {
    }
]
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"
}