Data model

Design Philosophy

Shipwell's mission is to connect, automate, and optimize the supply chains of the world. Our data model philosophy is to create a connected, collaborative, and performant structure to enable global logistics. Additionally, we use a Services Orient Architecture with many microservices that control and maintain the data model. The vast majority of our services use battle-hardened and use ACID-compliant databases. We make constant improvements to our data model and strive to ensure that changes are made that are backward compatible. When we make breaking changes, we ensure that our integration partners and users are aware of the change.

Our model starts with the concept of Company which is a core resource in our API. This company has Master Data such as Locations, Carriers, Customers, Suppliers, GL codes, etc. Master Data is used with Purchase Orders, Products, and other constraints and business processes to plan and create Shipments. Shipments represent the execution and movement of goods and this is where Shipwell creates relationships with Carriers (vendors in many of our endpoints. We will be renaming many endpoints to carrier in v3.0.0) in the data model. This vendor assignment allows collaboration and transparency between companies. Shared information such as tracking, documents, eta's, messages, notes, and bids/quotes are shared only when companies perform certain actions such as sending out a request for quoting or running an auction, or automatically assigning a vendor from vendor assignment based on the routing guide or loadboad book now.

High-Level Model

Meta Model

Detailed Hierarchy

Shipwell's detailed data hierarchy is easy to understand after consideration of the quoting, auctions, and vendor assignment relationships. In version 2, the shipment core resource is at the center. Each shipment (depending on the state of the shipment) can have stops, shipment line items, tags, documents, associated tenders, rfqs, purchase orders, line items, charge line items, vendor assignments, messages, notes, tracking, timeline events, and many other connected sub-resources. Additionally, if you have connected a FMS you will also have Bills, Invoices, and associated transactions. Based on the configuration of the company, meaning if the company is a Shipper, 3PL, Carrier, or Supplier, you will have other objects and capabilities that tie to these core models.

Detailed model


The platform requires a unique email address with every verified user. This user can only belong to one Company at a time in the current platform. The user model has associated permissions that define what the user can do in the platform such as billing, create a purchase order, a shipment, create carriers, create settlements, and others. We will be adding to these permissions and scopes in future versions.


The current tenancy model is the Company. Every company in the platform (Customers, Carriers, Suppliers, etc) are automatically given their own Company resource and tenant. Companies created in the platform also generate a relationship between the creating company and the one being created. Each company can have associated Identifying Codes that are relevant for their company such as MC, DOT, EIN, MX, SCAC and other codes. The Carrier core resource is a special type of company as this will get additional fields relevant for carriers that are used for things like compliance monitoring, performance, contracts, and more.


Supply chains are built on relationships and trust between two parties. We have created the ability for you to create Shipper to Carrier relationships and Carrier to Shipper relationships. This is where information such as markups, rate shares, and other shared information is stored. This allows you to easily share shipment, messages, and provide a quote with a simple sharing object. We have easily enabled trade between your company and your customers without the need for extensive integration and expensive infrastructure.


The platform can support a variety of document types for use on shipments and email communications. The following types can be stored within the platform:

  • TXT
  • CSV
  • XLS
  • XLSX
  • DOC
  • DOCX
  • ODF
  • PDF
  • JPG
  • JPEG
  • SVG
  • PNG
  • TIFF
  • GIF
  • BMB

If you are looking to use a document type not on this list, reach out to your Shipwell representative for more information.

Copyright © Shipwell 2024. All right reserved.