Freights

These endpoints is used for freight publishing to freight exchanges via SpotGo platform.

Limitations

Currently, API only supports 2 locations as maximum

If coordinates are not provided with the location, coordinates will be get using third-party service base on the country and postal code

Loading/Unloading maximum end date is DateTimeUTC.Now + 30 days

The loading start date must be greater than DateTimeUTC.Now + 15 minutes

1 Request equal 1 freight per user

Workflow

Every 30-60 minutes each freight is uplifted (updated) on external exchanges to make it stand out

If all payment information is provided and price auto increase functionality is enabled it will increase the price every X hours

If the Loading location datetime range is provided for instance 2023-06-22 08:00 - 17:00 system automatically updates loading DateTime until it reaches 2023-06-22 17:00

When the loading end time reaches DateTime UTC.Now the freight automatically is archived and deleted from all exchanges

Recomendations

Do not delete and create freights trying to make them more visible as it's already done by SpotGo.

Distribute the freights publishing and updates in time to avoid hit rate limits from Freight Exchanges and SpotGo.

Provide externalNumber for better traceability

Webhook events

Freight events (`eventType: Freight`)

SpotGo delivers an HTTP POST (JSON body) to your callbackUrl. The freight payload is intentionally small: use dataUrl to fetch the full freight with your API key.

Event	When it fires	Typical use
`freight.created`	A freight is created (via API or SpotGo platform).	Sync newly published freights into your TMS.
`freight.updated`	Freight content or external data is updated.	Refresh freight details after edits or price/location changes.
`freight.archived`	Freight is archived / deleted (including automatic archive when loading end time is reached).	Remove or close the freight in your system.

Important behaviour

id in the webhook body is the freightId (GUID string).

dataUrl for active freights points to GET /api/v1/freights/{freightId}.

dataUrl for archived freights points to GET /api/v1/freights/archive/{freightId}.

Publisher uplift / exchange board refresh alone does not emit a webhook; only freight create, content/external-data update, and archive do.

Duplicate notifications are possible; design your consumer to be idempotent.

Freight offer events (`eventType: FreightOffers`)

Offer webhooks include the offer details in payload. There is no dataUrl for offer events.

Event	When it fires	Typical use
`freight.offer.created`	A new offer is placed on a freight (API, share link, carrier portal, or exchange ingestion).	Notify dispatch / create bid in TMS.
`freight.offer.updated`	An existing offer is edited (price, contact, comments, etc.).	Refresh bid details.
`freight.offer.declined`	Freight owner declines an offer.	Mark bid as declined.
`freight.offer.canceled`	Offer is canceled (e.g. by the bidder).	Mark bid as canceled.
`freight.offer.rejected`	An approval-pending offer is rejected.	Mark bid as rejected.

Not emitted today

Offer accept — accepting an offer does not send a dedicated offer webhook (the freight may later emit freight.archived when it is closed).

Offer approval request / reset — no dedicated webhook events.

Offer status values (`payload.status`)

Value	Meaning
`Active`	Offer is active
`Cancelled`	Offer was canceled
`Accepted`	Offer was accepted
`ApprovalPending`	Offer awaits approval
`Declined`	Offer was declined

Freight Exchanges Mappings

1 - Trans.eu
2 - Timocom
3 - Teleroute
4 - Cargo.lt
5 - LardiTrans
6 - Spedition.Net
7 - Della.eu
8 - Cargopedia.Net
9 - 123Cargo.eu
10 - FaFa
11 - Spedimo
12 - Nexogen
13 - WTransnet
14 - Roolz
15 - Haulage Exchange
16 - Transporeon Marketplace
100 - Inside

Limitations#

Workflow#

Recomendations#

Webhook events#

Freight events (eventType: Freight)#

Freight offer events (eventType: FreightOffers)#

Offer status values (payload.status)#

Freight Exchanges Mappings#