Vagão vs. carruagem
The primary difference between vagão and carruagem lies in the purpose of the railway vehicle and the regional dialect. Generally, vagão is used for cargo and freight, whereas carruagem is intended for passengers. However, usage differs significantly between European and Brazilian Portuguese.
Vagão
B1This word refers to a railway vehicle used for transporting goods, freight, or animals. However, in Brazil, vagão is also the common everyday term used to describe passenger cars in subways and trains.
O comboio de carga tinha mais de cinquenta vagões cheios de madeira.
(The freight train had over fifty wagons full of wood.)
Eles trancaram o vagão para proteger a mercadoria durante a noite.
(They locked the freight car to protect the merchandise during the night.)
No Brasil, é comum dizer que o vagão do metrô está lotado às seis da tarde.
(In Brazil, it is common to say that the subway car is crowded at six in the evening.)
O transporte de carvão é feito em um vagão específico para minérios.
(Coal transport is done in a wagon specifically made for ores.)
Carruagem
B1In European Portuguese, this is the specific term for a railway vehicle designed to carry people, usually equipped with seats and windows. In Brazilian Portuguese, carruagem almost exclusively refers to a horse-drawn carriage and is not used for trains.
A minha passagem indica que o meu lugar é na carruagem número três.
(My ticket indicates that my seat is in carriage number three.)
Pedi um café e fiquei a olhar a paisagem pela janela da carruagem.
(I ordered a coffee and stood watching the landscape through the window of the passenger car.)
Em Portugal, é proibido fumar dentro de qualquer carruagem de passageiros.
(In Portugal, smoking is prohibited inside any passenger carriage.)
O revisor caminhou pela carruagem verificando os bilhetes de todos.
(The conductor walked through the carriage checking everyone's tickets.)
Summary
Use vagão for vehicles carrying things (cargo/freight) or, if you are in Brazil, for any train car including those for people. Use carruagem when referring to passenger cars in Portugal. In Brazil, avoid carruagem for trains as it sounds like a fairytale horse-drawn vehicle.