---
updatedAt: 2026-05-27T11:57:12.000Z
agentTools:
projectIndex: https://developers.opentrack.co/llms.txt
---
# Get Master Bill Status
Receive a status update for all containers on a master bill or booking using just the master bill or booking number.
Container-level `customFields` are not included in this response. To retrieve custom fields for a specific container, use `GET /v1/containers/{containerId}`.
# OpenAPI definition
```json
{
"openapi": "3.0.0",
"servers": [
{
"description": "Production",
"url": "https://api.opentrack.co"
}
],
"info": {
"version": "v1",
"title": "OpenTrack API",
"contact": {
"email": "support@opentrack.co"
},
"x-logo": {
"url": "https://s3-us-west-1.amazonaws.com/opentrack.co/images/opentrack_logo_dark.png",
"altText": "OpenTrack Logo"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"paths": {
"/v1/master-bills/{masterBillNumber}": {
"get": {
"summary": "Get Master Bill Status",
"description": "Receive a status update for all containers on a master bill or booking using just the master bill or booking number.\n\nContainer-level `customFields` are not included in this response. To retrieve custom fields for a specific container, use `GET /v1/containers/{containerId}`.",
"operationId": "getMasterBillStatus",
"x-readme": {
"explorer-enabled": false
},
"tags": [
"/master-bills"
],
"parameters": [
{
"name": "masterBillNumber",
"in": "path",
"required": true,
"description": "The identifier of the master bill or booking number to retrieve",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Expected response to a valid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MasterBillStatus"
}
}
}
},
"429": {
"description": "Usage Error - From Rate Limitation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"ApiKeyAuth": {
"type": "apiKey",
"name": "Opentrack-API-Key",
"in": "header"
}
},
"schemas": {
"MasterBillStatus": {
"required": [
"number",
"scacCode",
"createdAt",
"status"
],
"properties": {
"status": {
"type": "string",
"enum": [
"LOCATING",
"TRACKED",
"ARCHIVED"
]
},
"number": {
"type": "string",
"example": "MAEU589677982"
},
"scacCode": {
"type": "string",
"example": "MAEU"
},
"settings": {
"type": "object",
"example": {
"setting1": true
}
},
"referenceNumbers": {
"type": "object",
"example": {
"productId": "SKU123456789",
"forwardingConsolNumber": "CN105489"
}
},
"containers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ContainerStatus"
}
}
}
},
"ContainerStatus": {
"required": [
"containerId",
"createdAt",
"scacCode",
"account",
"status"
],
"properties": {
"account": {
"$ref": "#/components/schemas/Account"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "The timestamp of the response"
},
"containerId": {
"type": "string",
"example": "MRKU2642087"
},
"completionReason": {
"type": "string",
"description": "Indicates why tracking was stopped. If this property has any value, then tracking is no longer active"
},
"scacCode": {
"description": "The scac code of the ocean carrier",
"type": "string",
"example": "MRKU"
},
"masterBillNumber": {
"type": "string",
"example": "MAEU589677982"
},
"masterBill": {
"description": "An object that includes all information stored on the container's Master Bill",
"$ref": "#/components/schemas/MasterBill"
},
"tradeType": {
"type": "string",
"enum": [
"import",
"export",
"international"
]
},
"steamshipLine": {
"type": "string",
"example": "Maersk"
},
"vessel": {
"description": "The vessel performing the mother voyage (terminating at final discharge port). Learn more here",
"$ref": "#/components/schemas/Vessel"
},
"currentVessel": {
"description": "The vessel which the container is currently on. Learn more here",
"$ref": "#/components/schemas/Vessel"
},
"loadingVessel": {
"description": "The vessel on which the container is first loaded at its port of loading. Can be different from the mother vessel if the container has a transshipment stop. Learn more here",
"$ref": "#/components/schemas/Vessel"
},
"loadingVoyageNumber": {
"description": "The operating carrier identifier for the voyage on which the container is first loaded at its port of loading. Can be different from the mother vessel voyage if the container has a transshipment stop. Learn more here",
"type": "string"
},
"voyageNumber": {
"description": "The operating carrier identifier for the mother voyage",
"type": "string"
},
"vesselName": {
"type": "string",
"deprecated": true,
"description": "⚠️ Deprecated ⚠️ Please access vessel object properties instead"
},
"vesselImo": {
"type": "string",
"deprecated": true,
"description": "⚠️ Deprecated ⚠️ Please use the imo property of the vessel object instead"
},
"equipmentType": {
"type": "string",
"deprecated": true,
"example": "40/SD/96",
"description": "⚠️ Deprecated ⚠️ Please use the standardized \"containerSize\" and \"containerType\" fields instead."
},
"containerSize": {
"type": "string",
"example": "FORTY_FT",
"enum": [
"TWENTY_FT",
"FORTY_FT",
"FORTY_FT_HC",
"FORTY_FIVE_FT_HC"
],
"description": "The size of container based on a simplified set of ISO standard sizes"
},
"containerType": {
"type": "string",
"example": "DRY",
"enum": [
"DRY",
"FLAT_RACK",
"OPEN",
"REEFER",
"TANK",
"VENTILATED"
],
"description": "The type of container based on a simplified set of ISO standard types"
},
"grossWeight": {
"type": "number",
"description": "The gross weight of the container - including the weight of the container itself. It is either reported by the carrier or approximated by adding the weight of the container to the weight of the cargo when only the cargo weight is reported. Weight is standardized to kilograms."
},
"itNumber": {
"type": "string",
"description": "Inland Transit Number"
},
"status": {
"$ref": "#/components/schemas/Status"
},
"carrierReleasedDate": {
"type": "string",
"format": "date-time",
"description": "The date at which the ocean carrier released the freight"
},
"customsReleasedDate": {
"type": "string",
"format": "date-time",
"description": "The date at which customs released the freight"
},
"etaAtTerminal": {
"description": "The ETA to the final discharge port",
"type": "string",
"format": "date-time"
},
"etdFromOrigin": {
"description": "The ETD from the initial port of loading",
"type": "string",
"format": "date-time"
},
"earlyReturnDate": {
"description": "The earliest date at which a container will be physically accepted for loading on a particular vessel at the origin port",
"type": "string",
"format": "date-time"
},
"cutoffDate": {
"description": "The physical cutoff date for accepting new containers for loading on a particular vessel at the origin port",
"type": "string",
"format": "date-time"
},
"railEarlyReturnDate": {
"description": "The earliest date at which a container will be physically accepted for loading on a particular train at the origin rail ramp",
"type": "string",
"format": "date-time"
},
"railCutoff": {
"description": "The physical cutoff date for accepting new containers for loading at the origin rail ramp",
"type": "string",
"format": "date-time"
},
"shippingInstructionCutoff": {
"description": "The cutoff date for accepting shipping instructions (aka Document Cutoff)",
"type": "string",
"format": "date-time"
},
"lastFreeDay": {
"description": "The last free day before demurrage is incurred, at the ocean terminal at the final discharge port",
"type": "string",
"format": "date-time"
},
"lineLastFreeDay": {
"description": "The last free day before demurrage is incurred, issued by the steamship line. Can apply to either ocean terminal or final rail station depending on isRailMove",
"type": "string",
"format": "date-time"
},
"detentionLastFreeDay": {
"type": "string",
"format": "date-time",
"description": "The last free day before detention per diem is incurred"
},
"appointmentDate": {
"description": "The pickup appointment date/time booked at the final discharge port",
"type": "string",
"format": "date-time"
},
"demurrageOwedAtPort": {
"description": "The amount of demurrage currently owed at the port",
"type": "number",
"example": 250
},
"demurrageOwedAtPortDecimal": {
"description": "The amount of demurrage currently owed at the port (in cents)",
"type": "number",
"example": 25000
},
"demurrageIncurred": {
"description": "The total value of demurrage incurred at the port",
"type": "number",
"example": 250
},
"demurrageIncurredDecimal": {
"description": "The total value of demurrage incurred (in cents)",
"type": "number",
"example": 25000
},
"origin": {
"description": "The inland origin",
"$ref": "#/components/schemas/Location"
},
"portOfLoading": {
"type": "string",
"example": "HAIPHONG",
"deprecated": true,
"description": "⚠️ Deprecated ⚠️ Please use the originPort object instead."
},
"originPort": {
"description": "The initial ocean port of loading",
"$ref": "#/components/schemas/Location"
},
"portOfDischarge": {
"type": "string",
"example": "LONG BEACH, CA",
"deprecated": true,
"description": "⚠️ Deprecated ⚠️ Please use the destinationPort object instead."
},
"terminalAtPortOfDischarge": {
"type": "string",
"example": "PCT"
},
"destinationPort": {
"description": "The final ocean port of discharge",
"$ref": "#/components/schemas/Location"
},
"destination": {
"type": "string",
"example": "Columbus",
"deprecated": true,
"description": "⚠️ Deprecated ⚠️ Please use the finalDestination object instead."
},
"finalDestination": {
"description": "The container's final delivery destination",
"$ref": "#/components/schemas/Location"
},
"currentLocation": {
"description": "The location of the last known facility that handled the container",
"$ref": "#/components/schemas/Location"
},
"lastKnownPosition": {
"$ref": "#/components/schemas/Position",
"description": "The last known coordinates of the container. This can be a point on the water or inland"
},
"lastKnownPositionDate": {
"type": "string",
"format": "date-time",
"description": "The timestamp of the last known position of the container"
},
"terminalAtDestinationPort": {
"description": "The terminal at the final port of discharge for the ocean leg",
"$ref": "#/components/schemas/Terminal"
},
"terminalAtOriginPort": {
"description": "The terminal at the initial port of loading for the ocean leg",
"$ref": "#/components/schemas/Terminal"
},
"yardLocation": {
"type": "string",
"description": "The specific location of the container indicated by the terminal at port of discharge",
"example": "E7W"
},
"holds": {
"type": "array",
"description": "A list of holds affecting the container, both currently active and resolved. For a comprehensive list of holds types and codes, check out this guide",
"items": {
"$ref": "#/components/schemas/Hold"
}
},
"history": {
"type": "array",
"items": {
"$ref": "#/components/schemas/HistoryEvent"
}
},
"timeline": {
"type": "array",
"items": {
"$ref": "#/components/schemas/HistoryEvent"
}
},
"confirmedOnBoardDate": {
"type": "string",
"format": "date-time",
"deprecated": true,
"description": "⚠️ Deprecated ⚠️ Please access timestamp in history instead"
},
"vesselArrivedDate": {
"type": "string",
"format": "date-time",
"deprecated": true,
"description": "⚠️ Deprecated ⚠️ Please access timestamp in history instead"
},
"dischargedDate": {
"type": "string",
"format": "date-time",
"deprecated": true,
"description": "⚠️ Deprecated ⚠️ Please access timestamp in history instead"
},
"outgatedDate": {
"type": "string",
"format": "date-time",
"deprecated": true,
"description": "⚠️ Deprecated ⚠️ Please access timestamp in history instead"
},
"deliveredDate": {
"type": "string",
"format": "date-time",
"deprecated": true,
"description": "⚠️ Deprecated ⚠️ Please access timestamp in history instead"
},
"emptyReturnedDate": {
"type": "string",
"format": "date-time",
"deprecated": true,
"description": "⚠️ Deprecated ⚠️ Please access timestamp in history instead"
},
"etaAtDestination": {
"type": "string",
"description": "The ETA to the final rail facility",
"format": "date-time"
},
"etnAtDestination": {
"type": "string",
"description": "The predicted ETN (Estimated Time of Notification) at the final destination rail facility",
"format": "date-time"
},
"isRailMove": {
"type": "boolean",
"description": "Indicates whether or not the container is expected to have a rail leg at destination"
},
"railCarrier": {
"type": "object",
"description": "The rail carrier of the final rail leg",
"properties": {
"name": {
"type": "string",
"example": "UNION PACIFIC RAILROAD COMPANY"
},
"scacCode": {
"type": "string",
"example": "UP"
}
}
},
"finalRailStation": {
"type": "object",
"description": "The destination facility of the final rail leg",
"properties": {
"name": {
"type": "string",
"example": "GLOBAL 4"
},
"fsac": {
"type": "string",
"example": "72804"
},
"unlocode": {
"type": "string",
"example": "USCHI"
},
"firmsCode": {
"type": "string",
"example": "I206"
}
}
},
"lastFreeDayAtRailStation": {
"description": "The last free day before demurrage is incurred, at the final rail station",
"type": "string",
"format": "date-time"
},
"demurrageOwedAtRailStation": {
"description": "The amount of demurrage currently owed at the final rail station",
"type": "number",
"example": 250
},
"demurrageIncurredAtRailStation": {
"description": "The total amount of demurrage incurred at the final rail station",
"type": "number",
"example": 250
},
"customFields": {
"description": "Additional fields that allow you to add and store data on the container inside OpenTrack. To learn more, see our help guide.",
"type": "object",
"example": {
"customer": "CustomerABC",
"poNumber": "PO12345"
}
},
"trackingPage": {
"description": "URL to public TrackIt page for this container",
"type": "string"
},
"truckingCarrier": {
"description": "Trucking carrier for this container",
"$ref": "#/components/schemas/TruckingCarrier"
},
"dispatchedTruckingCarrier": {
"description": "Dispatched Trucking carrier for this container",
"$ref": "#/components/schemas/TruckingCarrier"
},
"chassisNumber": {
"description": "Chassis number for this container",
"type": "string"
},
"pickupNumber": {
"description": "Pickup number for this container",
"type": "string"
},
"sealNumber": {
"description": "Seal number for this container",
"type": "string"
},
"deliveryAppointmentDate": {
"type": "string",
"format": "date-time",
"description": "The timestamp of the delivery appointment date of the container"
},
"receivingFacility": {
"description": "Receiving facility for this container",
"$ref": "#/components/schemas/ReceivingFacility"
},
"offDockFacility": {
"description": "Off-dock storage facility for this container",
"$ref": "#/components/schemas/OffDockFacility"
}
}
},
"Vessel": {
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"example": "MAERSK EMERALD"
},
"imo": {
"type": "string",
"example": "9347566"
},
"mmsi": {
"type": "string",
"example": "538007481"
},
"countryCode": {
"type": "string",
"nullable": true,
"description": "ISO 3166-1 alpha-2 country code for the vessel's flag",
"example": "US"
},
"operator": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "ONE"
},
"scacCode": {
"type": "string",
"example": "ONEY"
}
}
}
}
},
"TruckingCarrier": {
"required": [
"scac"
],
"properties": {
"name": {
"type": "string",
"example": "Trucking Carrier INC"
},
"scac": {
"type": "string",
"example": "TCI"
}
}
},
"ReceivingFacility": {
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"example": "2163 S Riverside Ave, Colton, CA 92324, USA"
},
"firmsCode": {
"type": "string",
"example": "WBK5"
}
}
},
"OffDockFacility": {
"required": [
"name",
"unlocode"
],
"properties": {
"name": {
"type": "string",
"example": "ITS LONG BEACH"
},
"firmsCode": {
"type": "string",
"example": "W185"
},
"unlocode": {
"type": "string",
"example": "USLGB"
}
}
},
"Hold": {
"required": [
"type",
"reportedAt"
],
"properties": {
"type": {
"description": "Generally Terminal, Line, Customs or USDA.
Demurrage was previously reported as a hold, but that is being deprecated in favor of the demurrageOwed/demurrageIncurred properties",
"type": "string",
"example": "Terminal"
},
"code": {
"description": "A more specific description of the hold",
"type": "string",
"example": "TMF"
},
"remarks": {
"type": "string",
"example": "Please pay online"
},
"amountDue": {
"type": "integer",
"example": 200
},
"reportedAt": {
"type": "string",
"format": "date-time"
},
"resolvedAt": {
"type": "string",
"format": "date-time"
}
}
},
"HistoryEvent": {
"required": [
"milestone",
"location",
"timestamp"
],
"properties": {
"milestone": {
"$ref": "#/components/schemas/Status"
},
"location": {
"$ref": "#/components/schemas/Location"
},
"timestamp": {
"type": "string",
"format": "date-time"
},
"vessel": {
"description": "The vessel transporting the container if applicable",
"$ref": "#/components/schemas/Vessel"
}
}
},
"Location": {
"required": [
"name",
"coordinates",
"type"
],
"properties": {
"name": {
"type": "string"
},
"type": {
"type": "string",
"description": "Can be: port, locality",
"enum": [
"port",
"locality"
]
},
"unlocode": {
"type": "string",
"description": "Present when the location type is port"
},
"timezone": {
"type": "string"
},
"coordinates": {
"$ref": "#/components/schemas/Point"
}
}
},
"Position": {
"required": [
"coordinates"
],
"properties": {
"coordinates": {
"$ref": "#/components/schemas/Point"
}
}
},
"Point": {
"type": "object",
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90,
"example": 40.678858019
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180,
"example": -74.118213003
}
}
},
"Terminal": {
"required": [
"name",
"address",
"firmsCode"
],
"properties": {
"name": {
"type": "string",
"example": "TTI"
},
"address": {
"type": "string",
"example": "301 Mediterranean Way, Long Beach, CA 90802, United States"
},
"firmsCode": {
"type": "string",
"example": "Z952"
}
}
},
"Status": {
"type": "string",
"description": "The current status of the container. Can either be a lifecycle milestone, or a status indicating that OpenTrack is still searching for information about the container. Click here for more information",
"enum": [
"DISCOVERING",
"DISCOVERED",
"BOOKED",
"NOT_FOUND",
"EMPTY_OUTGATED",
"FULL_INGATED_AT_ORIGIN_RAIL_FACILITY",
"LOADED_ON_RAIL_AT_ORIGIN",
"DEPARTED_ON_RAIL_FROM_ORIGIN",
"ARRIVED_AT_ORIGIN_PORT_RAIL_FACILITY",
"UNLOADED_FROM_RAIL_AT_ORIGIN_PORT",
"FULL_INGATED",
"LOADED_ON_BARGE_AT_ORIGIN",
"BARGE_DEPARTED_FROM_ORIGIN",
"BARGE_BERTHED_AT_ORIGIN_PORT",
"DISCHARGED_FROM_BARGE_AT_ORIGIN_PORT",
"LOADED",
"VESSEL_DEPARTED",
"VESSEL_ARRIVED_AT_TRANSSHIPMENT_PORT",
"VESSEL_BERTHED_AT_TRANSSHIPMENT_PORT",
"DISCHARGED_AT_TRANSSHIPMENT_PORT",
"LOADED_AT_TRANSSHIPMENT_PORT",
"VESSEL_DEPARTED_FROM_TRANSSHIPMENT_PORT",
"VESSEL_ARRIVED",
"VESSEL_BERTHED",
"DISCHARGED",
"LOADED_ON_BARGE_AT_DESTINATION_PORT",
"BARGE_DEPARTED_FROM_DESTINATION_PORT",
"BARGE_BERTHED_AT_DESTINATION",
"DISCHARGED_FROM_BARGE_AT_DESTINATION",
"AVAILABLE",
"FULL_OUTGATED",
"FULL_INGATED_TO_RAIL_FACILITY",
"LOADED_ON_RAIL",
"DEPARTED_ON_RAIL",
"ARRIVED_AT_RAIL_FACILITY",
"UNLOADED_FROM_RAIL",
"AVAILABLE_AT_RAIL_FACILITY",
"FULL_OUTGATED_FROM_RAIL_FACILITY",
"FULL_INGATED_TO_OFFDOCK_FACILITY",
"AVAILABLE_AT_OFFDOCK_FACILITY",
"FULL_OUTGATED_FROM_OFFDOCK_FACILITY",
"FULL_DROPPED_OFF_AT_TRUCKER_YARD",
"FULL_PICKED_UP_FROM_TRUCKER_YARD",
"DELIVERED",
"EMPTY_READY_FOR_PICKUP",
"EMPTY_PICKED_UP_FOR_RETURN",
"EMPTY_DROPPED_OFF_AT_TRUCKER_YARD",
"EMPTY_PICKED_UP_FROM_TRUCKER_YARD",
"EMPTY_RETURNED"
],
"example": "AVAILABLE"
},
"Account": {
"required": [
"domain"
],
"properties": {
"domain": {
"type": "string",
"example": "acme.com",
"description": "The organization domain name. i.e acme.com"
},
"region": {
"type": "string",
"example": "LAX",
"description": "The region of the sub-account"
}
}
},
"Error": {
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
}
},
"MasterBill": {
"required": [
"number"
],
"properties": {
"number": {
"type": "string"
},
"referenceNumbers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the reference number property that was provided",
"example": "assigneeId"
},
"value": {
"type": "string",
"description": "The value of the reference number that was provided",
"example": "branch-1"
}
}
}
}
}
}
}
}
}
```