---
updatedAt: 2026-05-27T11:57:12.000Z
agentTools:
  projectIndex: https://developers.opentrack.co/llms.txt
---

# Track a Master Bill or Booking

The master bill tracking request endpoint allows you to import a master bill or booking number to be tracked by OpenTrack.

Once a master bill or booking number has been imported for tracking, we will gather all of the containers associated with it, and you will be able to retrieve all available container status and milestone data via webhooks (if subscribed) or via the GET /containers endpoint.

In order to successfully provide tracking, please provide the Master Bill of Lading number or booking number issued by the carrier and SCAC code.

See <a href="/docs/carrier-terminal-coverage" target="_blank">All Supported Carriers</a> for a list of supported carriers.


# 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}": {
      "post": {
        "summary": "Track a Master Bill or Booking",
        "description": "The master bill tracking request endpoint allows you to import a master bill or booking number to be tracked by OpenTrack.\n\nOnce a master bill or booking number has been imported for tracking, we will gather all of the containers associated with it, and you will be able to retrieve all available container status and milestone data via webhooks (if subscribed) or via the GET /containers endpoint.\n\nIn order to successfully provide tracking, please provide the Master Bill of Lading number or booking number issued by the carrier and SCAC code.\n\nSee <a href=\"/docs/carrier-terminal-coverage\" target=\"_blank\">All Supported Carriers</a> for a list of supported carriers.\n",
        "operationId": "trackMasterBill",
        "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 track",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "Master Bill or Booking to Track",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MasterBillTrackingRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Master Bill Tracking Accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MasterBillTrackingAccepted"
                }
              }
            }
          },
          "400": {
            "description": "MasterBill Tracking Rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Usage Error - From Rate Limitation or Subscription Plan Cap",
            "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": {
      "MasterBillTrackingAccepted": {
        "required": [
          "number",
          "scacCode",
          "createdAt",
          "status"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "LOCATING",
              "TRACKED",
              "ARCHIVED"
            ]
          },
          "number": {
            "type": "string",
            "example": "MAEU589677982"
          },
          "scacCode": {
            "type": "string",
            "example": "MAEU"
          },
          "referenceNumbers": {
            "type": "object",
            "example": {
              "productId": "SKU123456789",
              "forwardingConsolNumber": "CN105489"
            }
          }
        }
      },
      "MasterBillTrackingRequest": {
        "properties": {
          "scacCode": {
            "type": "string",
            "example": "MAEU",
            "description": "It is required to include a valid ocean carrier SCAC code in one of two places: Here in the scacCode field, or prefixed to the Master Bill number."
          },
          "referenceNumbers": {
            "type": "object",
            "example": {
              "productId": "SKU123456789",
              "forwardingConsolNumber": "CN105489"
            }
          }
        }
      },
      "Error": {
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```