How custom fields update when several people track the same container

What this guide is for

This guide is for teams where several people, teams, or systems track the same containers in one OpenTrack account. It explains what happens to custom field values (customFields, also called additional fields) when a container or master bill is tracked more than once, and how to clear a value.

It assumes:

• The fields you use are already enabled for your account. See Adding Additional Fields.
• You send tracking requests with POST /v1/containers/{containerId}, POST /v1/master-bills/{masterBillNumber}, or Bulk Upload.

Everyone in your account shares one set of values per container

Custom field values belong to the tracked container in your account, not to the person or API key that sent them.

• All users, teams, and API keys in your account read and write the same values for a container.
• Another OpenTrack account that tracks the same container keeps its own separate values. Their requests never change yours.
• A tracked container is matched on container number plus master bill. The same container under a different master bill is tracked separately and has its own values.

Tracking again only changes the fields you send

You can send the same container or master bill as many times as you like. OpenTrack never tracks the same container and master bill pair twice. A repeat request updates custom fields like this:

Because ignored fields don't return an error, read the container back with GET /v1/containers/{containerId} to confirm what was saved. customFields comes back as a list of name and value pairs.

Example. Your ops team tracks a container with poNumber and customer. Later, your finance system tracks the same container with this body:

{
  "masterBillNumber": "MAEU123456789",
  "scacCode": "MAEU",
  "customFields": {
    "poNumber": "",
    "movementCost": "1250.00"
  }
}

Result: poNumber keeps the ops team's value, customer is unchanged, and movementCost is added.

Master bill requests update every container on the bill

Sending customFields on POST /v1/master-bills/{masterBillNumber} writes those values to the master bill and to every container already tracked on it.

• For each field you send, the value replaces whatever was set on the individual containers.
• Containers found later on that master bill start with the master bill's values.
• Blank values are ignored here too, so they don't clear anything.

Tip: if a field differs from container to container (for example poNumber on a consolidated master bill), send it on POST /v1/containers/{containerId} and leave it out of the master bill request.

Clearing a value takes an edit in the dashboard

Tracking requests can't clear a custom field. Sending null or "" keeps the current value, so one team re-tracking a container never wipes out data another team entered.

To clear a value, edit the container in the OpenTrack dashboard and remove it there. Clearing a field on a master bill in the dashboard clears it on that master bill's containers as well.

Send values in the format each field expects

OpenTrack checks each value against the field's type before saving it.

destinationAddress is only saved when it matches one of the receiving facilities on your account. Otherwise it's ignored. See Keep Track of Container Destinations and Receiving Facilities.

Reference numbers are shared across the master bill

referenceNumbers are not custom fields. They're stored on the master bill, so every container on that master bill shows the same set.

Combining list values on re-send

If a reference number holds a list of values, like several PO numbers, you can ask OpenTrack support to turn on a setting that combines list values instead of replacing them. With it on, when someone tracks the container again and re-sends that reference number with a list, the new values are added to the ones already stored. This only applies to the reference numbers included in the new request.

Checklist for teams that share containers ✅

• Agree on which team or system owns each field.
• Send only the fields you own. Leave the rest out of the request.
• Use container requests for values that differ by container. Master bill requests overwrite every container on the bill.
• Clear values in the dashboard, not through the API.
• Confirm results with GET /v1/containers/{containerId}.