Docs
Sign in

Upload a document to a carrier

Required roles:
AdminAccount ManagerManagerOperator
Updated June 18, 20266 min read

UPS, FedEx, DHL Express, and Emirates Courier Express accept your own documents over their APIs. A signed commercial invoice, a certificate of origin, a customs declaration: you upload the file, and Carriyo forwards it to the carrier in the background.

There are three parts. An admin registers the uploadable document and maps it to the relevant carrier accounts (steps 1 and 2). Those are one-time steps. After that, any operator can attach a PDF to a shipment in the Dashboard or via the API (step 3). Carriyo uploads it once the shipment is booked.

Before you start

  • Registering a document (step 1) requires the admin role; mapping it to a carrier (step 2) also accepts account-manager. Uploading to a shipment (step 3) is available to any operator with access to shipments.
  • Carriyo forwards documents to the carrier only for UPS, FedEx, DHL Express, and Emirates Courier Express. For other carriers, Carriyo stores the document but does not forward it.
  • If you plan to upload via the API, make sure your API key is in place. See View API access details.

1. Register the uploadable document

Before a document can be attached to any shipment, an admin registers it under Settings → Administration → Documents. Go to the Uploadable Documents section and click ADD UPLOADABLE DOCUMENT.

Register an uploadable document under Settings → Documents.

Fill in:

  • Document Name. The label operators and API callers will use to identify this document. Pick something unambiguous: Customs Invoice, Certificate of Origin, Customs Declaration. The name must match exactly when uploading via the API.
  • Shipment Type. Forward Shipment or All Shipments. Use All Shipments to also cover reverse shipments.
  • Document Type. The category: Commercial Invoice, Certificate, Packing List, or Other. Carriers use this to classify the document on their side.
  • Document quick print is Active. Turn on if you want the document in the Quick Print shortlist on the Shipments list page. Leave off for documents you don't print often.
  • Document is Active. Controls whether the document is available to upload. Leave it on so operators and API callers can attach it to shipments; turn it off to register the document without making it available yet.

Name the document. The upload API matches on this exact value.

Click ADD UPLOADABLE DOCUMENT to save. The new document appears in the Uploadable Documents list, ready to be mapped.

2. Map the document to your carrier accounts

After a document is registered, an admin maps it to every carrier that should receive it. Carriers maintain their own document type lists. DHL Express, for instance, accepts a Commercial Invoice, a Certificate of Origin, and a Customs Declaration. The mapping tells Carriyo which carrier-side type matches each Carriyo document. Without it, Carriyo holds the document but never forwards it.

Open Settings → Carrier Accounts and click the account you want to configure. The Document Upload section is on the Account Setup tab. Each row is one mapping: a Carriyo Document on the left, the matching carrier-side document on the right. The right-hand column is labeled with the carrier's name. For a DHL Express account it reads DHL Document, for an Emirates Courier Express account it reads Emirates Courier Express Document, and so on.

Document Upload maps your documents to the carrier's own types.

To add a mapping, click Add Document. A new row appears with two dropdowns.

Click Add Document to add a mapping row.

  • Carriyo Document. Pick the document you registered in step 1.
  • Carrier-side document (the column labeled with the carrier's name, e.g. DHL Document). Pick the closest match from the carrier's list. The labels and codes are the carrier's; refer to their documentation if you're unsure which type a regulator expects.

Map your document to the carrier's matching type.

Click SAVE in the top-right corner. Repeat for every carrier that should accept this document. The same Carriyo document can be mapped on as many carrier accounts as you need.

Add Document is disabled?

The Add Document button on the carrier account is grayed out until at least one uploadable document is registered under Settings → Documents. Complete step 1 first.

3. Upload the document to a shipment

With the document registered (step 1) and mapped (step 2), any operator can attach a PDF to any shipment. Carriyo handles the upload to the carrier in the background.

In the Dashboard: open the shipment's Documents card. Click Add Document, pick the document from the Select a document dropdown, and upload the PDF.

Open the upload dialog from the shipment's Documents card.

Select the document and upload the PDF.

Via the API: POST to /shipments/{id}/documents (upload-document) with the document content as a Base64-encoded PDF. To upload several at once, use /shipments/{id}/documents/bulk (bulk-upload-documents). Identify the document with either document_id or document_name. When using document_name, the value must match the Document Name from step 1 exactly, including capitalization and spacing.

When Carriyo sends the document to the carrier

Carriyo stores the document right away. Whether it also pushes the document to the carrier depends on the shipment's status:

  • Before booking (draft, pending, error): the document is held in Carriyo. Once the shipment is booked and a tracking number is received, Carriyo automatically uploads it to the carrier.
  • After booking: the document is stored and immediately queued for carrier upload.

If the document is not mapped on the carrier account, Carriyo stores it but does not forward it. carrier_upload_status stays blank.

4. Check the upload status

Once a shipment is booked, Carriyo uploads each mapped document to the carrier in the background. The shipment's Documents card shows everything that's attached and where it came from:

  • AUTO-GENERATED. Produced by Carriyo at booking.
  • CARRIER-GENERATED. Provided by the carrier (typically the airway bill or shipping label).
  • ADDED BY USER. Uploaded by an operator or via the API. Look for this tag to confirm your uploadable document is attached to the shipment.

The uploaded document appears, tagged ADDED BY USER.

If Carriyo can't sync an uploaded document to the carrier, a retry icon appears next to it. Click the icon to trigger another attempt.

For developers building monitoring or recovery into their own tools, the API exposes a per-document carrier_upload_status (pending, complete, error) plus a retry endpoint.

Common mistakes

  • document_name mismatch in the API. Carriyo looks up the document setting by exact string match on the name. Any difference (capitalization, trailing space) returns 400. Use document_id to avoid case-sensitivity issues.
  • Forgetting the carrier mapping. Without a row in Document Upload on the carrier account, Carriyo stores the document but does not forward it. The shipment looks fine; carrier_upload_status stays blank.
  • Mapping only one carrier when the shipment can route to several. If a shipping rule can pick a different carrier for the same shipment type, map the document on every carrier the rule might choose.
  • Attaching a non-PDF. The upload endpoint and the dashboard dialog both expect a PDF. Other file types are rejected at upload time.
  • Expecting sync on a draft shipment. Documents on a draft, pending, or error shipment are held until booking. carrier_upload_status only starts after a tracking number is received.