# Register a document for a shipment

Register a carrier document against a shipment. The response returns an upload target; upload the document file to that target so it can later be sent to the carrier.

Endpoint: POST /v1/shipments/{shipment_id}/documents
Version: 1.1.202604070904
Security: api_key

## Path parameters:

  - `shipment_id` (string, required)
    Shipment ID
    Example: "se-28529731"

## Request fields (application/json):

  - `type` (string, required)
    The type of document being registered.
    Enum: "commercial_invoice", "certificate_of_origin", "usmca_commercial_invoice_certification_of_origin", "usmca_certification_of_origin", "pro_forma_invoice", "other", "authorization_form", "export_accompanying_document", "export_license", "import_permit", "one_time_nafta", "power_of_attorney", "packing_list", "sed_document", "shippers_letter_of_instruction", "declaration", "section_232_customs_affidavit"

  - `format` (string)
    The file format of the document. Defaults to PDF when omitted.
    Enum: "PDF", "PNG"

  - `file_name` (string, required)
    The file name of the document, including its extension.
    Example: "usmca-certification-of-origin.pdf"

## Response 200 fields (application/json):

  - `document_id` (string)
    The unique identifier assigned to the registered document.
    Example: "019eb24e-cd4e-7609-b740-c2324fe93272"

  - `upload` (object)
    The pre-signed Amazon S3 target the document file must be uploaded to.
    Example: {"url":"https://carrier-doc-upload.s3.amazonaws.com","fields":{"Content-Type":"application/pdf","key":"019eb24e-cd4e-7609-b740-c2324fe93272.pdf","x-amz-meta-document-id":"019eb24e-cd4e-7609-b740-c2324fe93272","x-amz-meta-seller-id":"8801990","X-Amz-Algorithm":"AWS4-HMAC-SHA256","X-Amz-Credential":"ASIA.../20260610/us-east-1/s3/aws4_request","X-Amz-Date":"20260610T161249Z","Policy":"eyJleHBpcmF0aW9uIjoi...","X-Amz-Signature":"b81189b9df29...","X-Amz-Security-Token":"IQoJb3JpZ2lu..."}}

  - `upload.url` (string)
    The Amazon S3 endpoint to upload the document file to via an HTTP POST with multipart/form-data.
    Example: "https://carrier-doc-upload.s3.amazonaws.com"

  - `upload.fields` (object)
    The S3 presigned-POST form fields. Include every field exactly as returned in the upload request, followed by a file part containing the document content.
    Example: {"Content-Type":"application/pdf","key":"019eb24e-cd4e-7609-b740-c2324fe93272.pdf","x-amz-meta-document-id":"019eb24e-cd4e-7609-b740-c2324fe93272","x-amz-meta-seller-id":"8801990","X-Amz-Algorithm":"AWS4-HMAC-SHA256","X-Amz-Credential":"ASIA.../20260610/us-east-1/s3/aws4_request","X-Amz-Date":"20260610T161249Z","Policy":"eyJleHBpcmF0aW9uIjoi...","X-Amz-Signature":"b81189b9df29...","X-Amz-Security-Token":"IQoJb3JpZ2lu..."}

  - `upload.fields.Content-Type` (string)
    The MIME type of the document; matches the registered document format.
    Example: "application/pdf"

  - `upload.fields.key` (string)
    The S3 object key the file will be stored under.
    Example: "019eb24e-cd4e-7609-b740-c2324fe93272.pdf"

  - `upload.fields.x-amz-meta-document-id` (string)
    S3 object metadata: the registered document's unique identifier.
    Example: "019eb24e-cd4e-7609-b740-c2324fe93272"

  - `upload.fields.x-amz-meta-seller-id` (string)
    S3 object metadata: the seller's identifier.
    Example: "8801990"

  - `upload.fields.X-Amz-Algorithm` (string)
    The AWS signing algorithm used for the pre-signed POST.
    Example: "AWS4-HMAC-SHA256"

  - `upload.fields.X-Amz-Credential` (string)
    The AWS credential scope used to sign the upload.
    Example: "ASIA.../20260610/us-east-1/s3/aws4_request"

  - `upload.fields.X-Amz-Date` (string)
    The timestamp the signature was generated, in ISO 8601 basic format.
    Example: "20260610T161249Z"

  - `upload.fields.Policy` (string)
    The base64-encoded S3 POST policy defining the conditions the upload must satisfy, such as the allowed key, content type, size, and expiration.
    Example: "eyJleHBpcmF0aW9uIjoi..."

  - `upload.fields.X-Amz-Signature` (string)
    The signature authorizing the upload, derived from the policy and credentials.
    Example: "b81189b9df29..."

  - `upload.fields.X-Amz-Security-Token` (string)
    The temporary AWS session token for the credentials.
    Example: "IQoJb3JpZ2lu..."

## Response 400 fields (application/json):

  - `request_id` (string, required)
    A UUID that uniquely identifies the request id.
This can be given to the support team to help debug non-trivial issues that may occur
    Example: "aa3d8e8e-462b-4476-9618-72db7f7b7009"

  - `errors` (array, required)
    The errors associated with the failed API call

  - `errors.error_source` (string, required)
    The source of the error, as indicated by the name this informs us if the API call failed because of the
carrier, the order source, or the ShipEngine API itself.
    Enum: "carrier", "order_source", "shipengine"

  - `errors.error_type` (string, required)
    The type of error
    Enum: "account_status", "business_rules", "validation", "security", "system", "integrations"

  - `errors.error_code` (string, required)
    The error code specified for the failed API Call
    Enum: "auto_fund_not_supported", "batch_cannot_be_modified", "carrier_conflict", "carrier_disconnected", "carrier_not_connected", "carrier_not_supported", "confirmation_not_supported", "default_warehouse_cannot_be_deleted", "field_conflict", "field_value_required", "forbidden", "identifier_conflict", "identifiers_must_match", "insufficient_funds", "invalid_address", "invalid_billing_plan", "invalid_field_value", "invalid_identifier", "invalid_status", "invalid_string_length", "label_images_not_supported", "meter_failure", "order_source_not_active", "rate_limit_exceeded", "refresh_not_supported", "request_body_required", "return_label_not_supported", "settings_not_supported", "subscription_inactive", "terms_not_accepted", "tracking_not_supported", "trial_expired", "unauthorized", "unknown", "unspecified", "verification_failure", "warehouse_conflict", "webhook_event_type_conflict", "customs_items_required", "incompatible_paired_labels", "invalid_charge_event", "invalid_object", "no_rates_returned", "file_not_found", "shipping_rule_not_found", "service_not_determined", "no_rates_returned", "funding_source_registration_in_progress", "insurance_failure", "funding_source_missing_configuration", "funding_source_error", "freight_connection_inactive", "freight_provider_id_required", "freight_provider_already_connected", "freight_shipment_not_found", "freight_tracking_not_available", "freight_tracking_not_found", "freight_shipment_not_batchable"

  - `errors.message` (string, required)
    An error message associated with the failed API call
    Example: "Body of request cannot be null."

  - `errors.carrier_id` (string)
    A string that uniquely identifies the carrier that generated the error.
    Example: "se-28529731"

  - `errors.carrier_code` (string)
    The name of the shipping carrier that generated the error, such as fedex, dhl_express, stamps_com, etc.
    Example: "dhl_express"

  - `errors.field_name` (string)
    The name of the field that caused the error
    Example: "shipment.ship_to.phone_number"