Skip to content
Heatwave Docs

International Forms (Commercial Invoice, BOL, USMCA, Declarations)

This document describes how international shipping forms are generated and how product- and global-level attachments (USMCA certificates and Declarations of Steel/Aluminum/Copper) are included in the PDFs produced by Heatwave.

Scope

  • Delivery-level forms: Commercial Invoice (CI), Bill of Lading (BOL), and a combined “All International Forms” PDF.
  • Item-level attachments: usmca_certificate (one or more, attached to Items used on a Delivery).
  • Global/store-level attachment: declaration_of_steel_aluminimum_copper (a single Upload, attached at the top level and included if present).

Key implementations

  • Shipping::CiGenerator appends USMCA item certificates to the CI PDF:

    • File: app/services/shipping/ci_generator.rb
    • Behavior: Builds CI via Pdf::CommercialInvoice, then combines any Upload with category usmca_certificate that are linked to the Items present on the Delivery.
    • Result: A single CI PDF that contains the invoice followed by any matching USMCA certificates.

  • Delivery#generate_all_international_forms_pdf combines all international forms:

    • File: app/models/delivery.rb (method generate_all_international_forms_pdf)
    • Base set: Adds CI (including CI with combined USMCA from CiGenerator when generated) and BOL to the list.
    • Attachments: Appends item-linked usmca_certificate uploads; also appends the latest Upload with category declaration_of_steel_aluminimum_copper if present.
    • Output: A single all_intl_forms_pdf upload on the Delivery, suitable for printing/archiving.

Attachment categories and where to add them

  • usmca_certificate (Item-level)

    • Attach one or more PDFs to the Item records used on a Delivery.
    • Path: Upload category on Item → :usmca_certificate (see app/models/upload.rb, MODEL_TO_CATEGORIES)
    • Inclusion logic:
      • Shipping::CiGenerator includes all usmca_certificate uploads linked to Items on the Delivery.
      • Delivery#generate_all_international_forms_pdf also includes them when generating the combined forms.

  • declaration_of_steel_aluminimum_copper (Global/Site-level)

    • Attach a single PDF via Upload with category :declaration_of_steel_aluminimum_copper.
    • The “All International Forms” generator will include the latest such upload when present.

When are forms generated?

  • CI generation
    • Via Shipping::CiGenerator (e.g., from Delivery#generate_ci_pdf), typically after labels are generated or on-demand for international shipments.
  • “All International Forms”
    • Via Delivery#generate_all_international_forms_pdf, usually after CI/BOL are available or on explicit request.

Cross-border rules

  • USMCA certificates are included when present.
  • The current implementation does not hard-enforce a country check (e.g., US/CA/MX); inclusion is content-driven. If needed, add a guard to only include USMCA docs for US↔CA↔MX shipments.

Operational notes

  • Ensure Items have the correct coo (country of origin) and any necessary certificates uploaded before label generation.
  • If CI generation precedes item attachment updates, re-generate CI or “All International Forms” after attachments are added.

Testing checklist

  1. Attach a usmca_certificate PDF to an Item used by a Delivery with an international destination.
  2. Generate CI (e.g., Delivery#generate_ci_pdf) and verify the combined CI now contains the USMCA PDF(s) after the invoice pages.
  3. Generate “All International Forms” (Delivery#generate_all_international_forms_pdf) and verify:
    • First pages: CI (with USMCA if present),
    • Then: BOL (if applicable),
    • Then: Any additional USMCA certificates not already present,
    • Then: Global declaration_of_steel_aluminimum_copper (if present).

Related commits (context)

  • CI + USMCA inclusion improvements:
    • 8fd724196586492efcfba98416a80752791df728
    • 3edd1f53117de44bfe4329cdc6c6547577c9e350
    • 71a183b8ca28cd80f3935dc519877c92e6236c4c

Key code references

  • app/services/shipping/ci_generator.rb
  • app/models/delivery.rb (methods: generate_ci_pdf, generate_all_international_forms_pdf)
  • app/models/upload.rb (categories: :usmca_certificate, :declaration_of_steel_aluminimum_copper)

Troubleshooting

  • CI missing USMCA pages: Confirm the certificate is attached to the specific Item(s) present on the Delivery and re-generate CI.
  • “All forms” missing declaration: Verify an Upload exists with category declaration_of_steel_aluminimum_copper.
  • Form order: CI first, then BOL, followed by certificate/declaration pages.