# Register a document for a label

Products
            Plans
          
        
        
          
            
              
              Formerly ShipEngine
            
            
              Free
              Advanced
              Enterprise
            
          
          
            
              
            
            
              Free
              Starter
              Standard
              Premium
            
          
        
      
      
        
          Learn about products and plans
          
        
      
    

Register a carrier document against a label. The response returns an upload target; upload the document file to that target, then call the send documents endpoint to transmit it to the carrier. Carrier information is resolved automatically from the label.

Endpoint: POST /v2/labels/{label_id}/documents
Version: 2.0.0
Security: api_keys

## Path parameters:

  - `label_id` (string, required)
    Label 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, the ShipStation API itself, or the underlying ShipEngine platform.
    Enum: "carrier", "order_source", "ShipStation", "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", "freight_connection_inactive", "freight_provider_id_required", "freight_shipment_not_found", "freight_tracking_not_available", "freight_tracking_not_found", "freight_shipment_not_batchable", "freight_provider_already_connected"

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

  - `errors.field_name` (string)
    The name of the field that caused the error (only present for validation errors)
    Example: "inventory_warehouse_id"

  - `errors.field_value` (string)
    The invalid value that was provided for the field (only present for validation errors)
    Example: "invalid-id"