Skip to main content

Freight Mileage Table Upsert Many V1 Ep

POST 
/v1/freight/mileage_table/upsert_many

Create/Update Mileage Tables

Creates or updates mileage table (base freight) rates in bulk. Each record is one whole effective-dated table, and its bands replace the table's bands entirely.

A record with id updates that table, and is the only way to change a table's effective_from. A record without id updates the table with the same counterparty, ratebook, region, product group and effective_from, or creates a new table if there is none. A new effective_from therefore schedules a new table.

To end a table, send it with an effective_to. Tables are never deleted. When a record updates an existing table, leaving out effective_to keeps the table's end date; send "effective_to": null to make it open-ended.

Records are processed in order and independently: a record that fails is reported in results while the others still apply. Impacted orders are repriced in one job once all records are applied.

Required Scopes (if.w)

Request​

A list of 1 to 2,000 records, each with the following attributes.

id: str | None = None
Internal identifier of the table to update. Omit to match on the fields below.

counterparty_id: str
Internal identifier of the counterparty. A carrier token can only write its own rates.

book_type: RateBookType = Cost
Cost for what a carrier is paid, Revenue for what a customer is billed.

freight_region_id: str | None = None
product_group: str | None = None
Leave unset for the fallback table used by every region or product group without its own.

unit: RateUnit
trucks, gallons, liters or tons.

rates: list[object]
At least one band, each with from_mile (a whole number, 0 or more), rate (0 or more) and an optional to_mile. Bands are sorted by from_mile, and each band ends where the next one starts, so a gap or overlap is closed up rather than rejected. Only the last band's to_mile is used, and it is required: it is the longest trip the table covers.

effective_from: datetime
effective_to: datetime | None = None
Only the date is used; any time of day and UTC offset are ignored. effective_to is exclusive, must be after effective_from, and an existing table's effective_to cannot be changed to a date before today. A new table may lie entirely in the past, but loading one reprices every order from its effective_from onward. A table may not overlap another table with the same counterparty, ratebook, region and product group, but it may start on the day the previous one ends. The exception is an earlier open-ended table: a later table replaces it from the later table's effective_from. If that later table has an effective_to, the series has no rate after that date until another table starts.


Response​

created_count: int, updated_count: int, error_count: int

results: list[object]
One entry per record, in request order: index (0-based position in the request), id of the table written, status (created, updated or error), and errors, each with the field at fault and a message.

Responses​

Successful Response

{
  "created_count": 0,
  "updated_count": 0,
  "error_count": 0,
  "results": [
    {
      "index": 0,
      "id": "string",
      "status": "created",
      "errors": [
        {
          "field": "string",
          "message": "string"
        }
      ]
    }
  ]
}
Loading...