{
  "openapi": "3.1.0",
  "info": {
    "title": "ByModo API",
    "version": "1.0.0",
    "summary": "Rate, book, label, document and track freight programmatically.",
    "description": "The ByModo API covers one job end to end: find out what a shipment costs, book it, get the\npaperwork, and follow it until it arrives.\n\nThis reference documents the **integration API** — the endpoints an API key is for. The\nendpoints behind the ByModo web application (team and user administration, billing, onboarding,\ninternal operations) are deliberately not here. If you are looking for something that exists in\nthe dashboard but not in this reference, ask us rather than calling it: undocumented endpoints\nchange without notice.\n\n## Base URL\n\n```\nhttps://api.bymodo.com/api\n```\n\nEvery path in this reference is relative to that. There is no separate sandbox host; ask us for\na test account on the same base URL.\n\n## Authentication\n\nEvery endpoint needs an API key except public tracking, which needs nothing. Create keys in the\ndashboard under Settings → API keys. A key looks like `trf_live_…` and carries the permissions\nof the account that made it.\n\nSend it as a header:\n\n```\nX-API-Key: trf_live_your_key_here\n```\n\nor as a bearer token, if that suits your HTTP client better:\n\n```\nAuthorization: Bearer trf_live_your_key_here\n```\n\nKeys are shown once, at creation. Treat one as a password: it can book shipments that you will\nbe invoiced for.\n\n## The shape of an integration\n\nRating and booking are two calls, and the second one needs the first:\n\n1. `POST /rates` returns a `rate_request_id` and a list of `quotes`.\n2. `POST /shipments/bulk-from-rates` books the quote you chose, by `rate_request_id` plus the\n   `carrier_code` and `service_code` from that quote.\n\nBooking from a rate request is the path we recommend, because the price you were quoted is the\nprice you are charged. `POST /shipments` exists for booking without rating first, and re-rates\nthe shipment itself.\n\n## Service and carrier codes\n\n`carrier_code` and `service_code` identify a service you were quoted. Treat both as opaque:\nread them from a `/rates` response and pass them back unchanged. They are not a published list,\nthey are not stable across accounts, and inventing one will fail validation. Your available\nservices depend on your account's agreements, so two accounts rating the same shipment can\nlegitimately get different options.\n\nByModo carries as the agent of record. Your shipment travels under a ByModo tracking number and\nByModo paperwork whoever moves it, and tracking text you receive through this API is normalised\nto ByModo rather than passed through verbatim.\n\n## Units\n\nWatch this one, because the two endpoints you will call in sequence disagree.\n\n| Endpoint | Contact field | Weight | Dimensions |\n| --- | --- | --- | --- |\n| `POST /rates` | `contact` | `weight` | `length`, `width`, `height` |\n| `POST /shipments` | `name` | `weightKg` | `lengthCm`, `widthCm`, `heightCm` |\n\n`/rates` takes a `unitSystem` of `metric` or `imperial` and defaults to metric. `/shipments`\nnames its units in its fields and has no `unitSystem`. This is history rather than design, and\nit is documented rather than hidden because you will hit it on your first integration.\n\n## Errors\n\nErrors are JSON, with the same shape throughout:\n\n```json\n{ \"success\": false, \"error\": \"A description of what went wrong\" }\n```\n\nValidation failures use the Laravel convention, with a message per field:\n\n```json\n{\n  \"message\": \"The from.zip field is required.\",\n  \"errors\": { \"from.zip\": [\"The from.zip field is required.\"] }\n}\n```\n\n| Status | Meaning |\n| --- | --- |\n| `200` | Success. |\n| `201` | Created — a shipment or batch now exists. |\n| `401` | Missing, malformed or revoked API key. |\n| `403` | The key is valid but the account may not do this, or the feature is not enabled for it. |\n| `404` | No such record, or it belongs to another account. |\n| `422` | The request was understood and rejected; read `errors`. |\n| `429` | Too many requests. Back off and retry. |\n| `500` | Our fault. Retry; if it persists, tell us the time and the payload. |\n\nA rating call that reaches no carrier is still a `200` with an empty `quotes` array — it is a\nvalid answer to \"what will this cost\", not a failure.\n",
    "license": {
      "name": "Proprietary — © ByModo. All rights reserved.",
      "url": "https://bymodo.com"
    },
    "contact": {
      "name": "ByModo Support",
      "url": "https://bymodo.com",
      "email": "support@bymodo.com"
    }
  },
  "servers": [
    {
      "url": "https://api.bymodo.com/api",
      "description": "Production"
    }
  ],
  "security": [
    {
      "ApiKeyHeader": []
    },
    {
      "BearerToken": []
    }
  ],
  "tags": [
    {
      "name": "Rating",
      "description": "What a shipment costs, before you commit to it."
    },
    {
      "name": "Booking",
      "description": "Turning a quote into a shipment, one at a time or in bulk."
    },
    {
      "name": "Shipments",
      "description": "Reading back what you have booked."
    },
    {
      "name": "Labels and documents",
      "description": "The paperwork a shipment travels with."
    },
    {
      "name": "Tracking",
      "description": "Where a shipment is, including a public endpoint your own customers can call."
    },
    {
      "name": "Addresses and configuration",
      "description": "Validating an address and discovering what your account can ship."
    }
  ],
  "paths": {
    "/rates": {
      "post": {
        "tags": [
          "Rating"
        ],
        "summary": "Quote one shipment",
        "operationId": "queryRates",
        "description": "Prices a shipment across the services your account can use and returns every option, with\nno obligation to book any of them.\n\nKeep the `rate_request_id`. It is how you book the option you chose at the price you were\nquoted, through `POST /shipments/bulk-from-rates`. Rate requests are retained for a limited\nperiod; book on the same day to be safe.\n\nAn empty `quotes` array means no service would carry this shipment — commonly an\nunserviceable postal code or a package over a limit — and is returned as `200`.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RateRequest"
              },
              "examples": {
                "domestic": {
                  "summary": "A single parcel, Toronto to Montreal",
                  "value": {
                    "from": {
                      "contact": "Warehouse Team",
                      "company": "Acme Supplies",
                      "address": "100 King Street West",
                      "city": "Toronto",
                      "state": "ON",
                      "zip": "M5X1A9",
                      "country": "CA",
                      "phone": "+14165550100"
                    },
                    "to": {
                      "contact": "Marie Tremblay",
                      "address": "1200 Rue Sainte-Catherine",
                      "city": "Montreal",
                      "state": "QC",
                      "zip": "H3B4W8",
                      "country": "CA",
                      "phone": "+15145550199"
                    },
                    "packages": [
                      {
                        "description": "Books",
                        "weight": 4.5,
                        "length": 30,
                        "width": 20,
                        "height": 15,
                        "value": 120
                      }
                    ],
                    "unitSystem": "metric"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Every service that would carry this shipment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/rates/bulk": {
      "post": {
        "tags": [
          "Rating"
        ],
        "summary": "Quote many shipments",
        "operationId": "queryRatesBulk",
        "description": "Rates a list of shipments in one call. Each entry is rated independently and gets its own\n`rate_request_id`, so one unserviceable address does not cost you the rest of the batch.\n\nEach element takes the same fields as `POST /rates`.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "shipments"
                ],
                "properties": {
                  "shipments": {
                    "type": "array",
                    "minItems": 1,
                    "description": "One entry per shipment to rate.",
                    "items": {
                      "$ref": "#/components/schemas/RateRequest"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One result per shipment, in the order you sent them.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/RateResponse"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/shipments/bulk-from-rates": {
      "post": {
        "tags": [
          "Booking"
        ],
        "summary": "Book quotes you have already been given",
        "operationId": "createShipmentsFromRates",
        "description": "Books one or more shipments from rate requests, at the price you were quoted. This is the\nrecommended way to book: the quote is already priced, so there is no chance of the figure\nmoving between rating and booking.\n\nName the option per rate request, or once at the top level to apply to all of them. Omit\n`carrier_code` and `service_code` entirely and the cheapest quote on each rate request is\nbooked.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Send either `rate_requests` (per-entry control) or `rate_request_ids` (same choice\nfor all). Sending neither is a `422`.\n",
                "properties": {
                  "rate_requests": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                      "type": "object",
                      "required": [
                        "rate_request_id"
                      ],
                      "properties": {
                        "rate_request_id": {
                          "type": "string",
                          "description": "From a `/rates` response.",
                          "examples": [
                            "bym-8f3a21c7"
                          ]
                        },
                        "carrier_code": {
                          "type": "string",
                          "description": "From the quote you chose. Omit to take the cheapest."
                        },
                        "service_code": {
                          "type": "string",
                          "description": "From the quote you chose. Omit to take the cheapest."
                        }
                      }
                    }
                  },
                  "rate_request_ids": {
                    "type": "array",
                    "minItems": 1,
                    "description": "Book several rate requests with one choice of service.",
                    "items": {
                      "type": "string"
                    }
                  },
                  "carrier_code": {
                    "type": "string",
                    "description": "Applies to every entry that does not name its own."
                  },
                  "service_code": {
                    "type": "string",
                    "description": "Applies to every entry that does not name its own."
                  }
                }
              },
              "examples": {
                "chosenQuote": {
                  "summary": "Book one rate request on a chosen service",
                  "value": {
                    "rate_requests": [
                      {
                        "rate_request_id": "bym-8f3a21c7",
                        "carrier_code": "bymodo",
                        "service_code": "BYMODO_GROUND"
                      }
                    ]
                  }
                },
                "cheapest": {
                  "summary": "Book several, taking the cheapest quote on each",
                  "value": {
                    "rate_request_ids": [
                      "bym-8f3a21c7",
                      "bym-19b4d502"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One result per rate request, booked or failed individually.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "rate_request_id": {
                            "type": "string"
                          },
                          "success": {
                            "type": "boolean"
                          },
                          "shipment": {
                            "$ref": "#/components/schemas/Shipment"
                          },
                          "error": {
                            "type": "string",
                            "description": "Present instead of `shipment` when this entry failed."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "description": "Neither `rate_requests` nor `rate_request_ids` was supplied, or a rate request id does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/shipments": {
      "get": {
        "tags": [
          "Shipments"
        ],
        "summary": "List your shipments",
        "operationId": "listShipments",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "description": "Page size.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Restrict to one status.",
            "schema": {
              "$ref": "#/components/schemas/ShipmentStatus"
            }
          },
          {
            "name": "search",
            "in": "query",
            "description": "Matches a tracking number, reference or recipient.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of shipments, newest first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Shipment"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "Booking"
        ],
        "summary": "Book a shipment without rating first",
        "operationId": "createShipment",
        "description": "Books a single shipment, rating it as part of the call. Use this when you do not need to\nshow options first — a fixed lane, or a system that books straight from an order.\n\nNote the field names: this endpoint takes `name`, `weightKg` and `lengthCm`, where `/rates`\ntakes `contact`, `weight` and `length`. See **Units** above.\n\nIf you have already rated the shipment, prefer `POST /shipments/bulk-from-rates` so the\nprice cannot move between the quote and the booking.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ShipmentRequest"
              },
              "examples": {
                "single": {
                  "summary": "One parcel, booked directly",
                  "value": {
                    "from": {
                      "name": "Warehouse Team",
                      "address": "100 King Street West",
                      "city": "Toronto",
                      "state": "ON",
                      "zip": "M5X1A9",
                      "country": "CA",
                      "phone": "+14165550100"
                    },
                    "to": {
                      "name": "Marie Tremblay",
                      "address": "1200 Rue Sainte-Catherine",
                      "city": "Montreal",
                      "state": "QC",
                      "zip": "H3B4W8",
                      "country": "CA",
                      "phone": "+15145550199"
                    },
                    "packages": [
                      {
                        "description": "Books",
                        "weightKg": 4.5,
                        "lengthCm": 30,
                        "widthCm": 20,
                        "heightCm": 15,
                        "declaredValue": 120
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The shipment was booked.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "shipment": {
                      "$ref": "#/components/schemas/Shipment"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/shipments/bulk": {
      "post": {
        "tags": [
          "Booking"
        ],
        "summary": "Book several shipments",
        "operationId": "createShipmentsBulk",
        "description": "Books a list of shipments, each rated as part of the call. Entries succeed or fail\nindependently, so read every result rather than the status code alone.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "shipments"
                ],
                "properties": {
                  "shipments": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                      "$ref": "#/components/schemas/ShipmentRequest"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One result per shipment.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "success": {
                            "type": "boolean"
                          },
                          "shipment": {
                            "$ref": "#/components/schemas/Shipment"
                          },
                          "error": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/orders/bulk": {
      "post": {
        "tags": [
          "Booking"
        ],
        "summary": "Book a batch of orders",
        "operationId": "createOrdersBulk",
        "description": "The batch endpoint for order-management systems: up to 100 orders in one call, each naming\nthe service it should go on.\n\n`mode` decides whether you wait. `sync` books everything before responding, which is\nsimplest and slowest. `async` returns a `batch_id` immediately and books in the background;\npoll `GET /orders/bulk/{batchId}` for progress. Use `async` for anything over a handful.\n\nUnlike rating, `carrier_code` and `service_code` are **required** per order here: a batch\ndoes not choose a service for you. Take both from a `/rates` response.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "orders"
                ],
                "properties": {
                  "mode": {
                    "type": "string",
                    "enum": [
                      "sync",
                      "async"
                    ],
                    "default": "sync"
                  },
                  "orders": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 100,
                    "items": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/ShipmentRequest"
                        },
                        {
                          "type": "object",
                          "required": [
                            "carrier_code",
                            "service_code"
                          ],
                          "properties": {
                            "carrier_code": {
                              "type": "string",
                              "description": "From the quote you chose. Required here."
                            },
                            "service_code": {
                              "type": "string",
                              "description": "From the quote you chose. Required here."
                            },
                            "reference": {
                              "type": "string",
                              "description": "Your own order reference, echoed back on the result."
                            }
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Booked (`sync`), or accepted for background booking (`async`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "batch_id": {
                      "type": "string",
                      "description": "Present in `async` mode. Poll it for progress."
                    },
                    "results": {
                      "type": "array",
                      "description": "Present in `sync` mode, one entry per order.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "reference": {
                            "type": "string"
                          },
                          "success": {
                            "type": "boolean"
                          },
                          "shipment": {
                            "$ref": "#/components/schemas/Shipment"
                          },
                          "error": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/orders/bulk/{batchId}": {
      "get": {
        "tags": [
          "Booking"
        ],
        "summary": "Check a batch",
        "operationId": "getOrderBatch",
        "description": "Progress and per-order outcomes for a batch submitted with `mode: async`.",
        "parameters": [
          {
            "name": "batchId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Where the batch has got to.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "batch_id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "pending",
                        "processing",
                        "completed",
                        "failed"
                      ]
                    },
                    "total": {
                      "type": "integer"
                    },
                    "processed": {
                      "type": "integer"
                    },
                    "failed": {
                      "type": "integer"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "reference": {
                            "type": "string"
                          },
                          "success": {
                            "type": "boolean"
                          },
                          "shipment": {
                            "$ref": "#/components/schemas/Shipment"
                          },
                          "error": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/orders": {
      "get": {
        "tags": [
          "Shipments"
        ],
        "summary": "List your orders",
        "operationId": "listOrders",
        "description": "Orders as the order-management endpoints see them, which is the same underlying shipment in a flatter shape.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/ShipmentStatus"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of orders.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Shipment"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/orders/{id}": {
      "get": {
        "tags": [
          "Shipments"
        ],
        "summary": "Retrieve an order",
        "operationId": "getOrder",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The order.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Shipment"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/shipments/{id}": {
      "get": {
        "tags": [
          "Shipments"
        ],
        "summary": "Retrieve a shipment",
        "operationId": "getShipment",
        "parameters": [
          {
            "$ref": "#/components/parameters/ShipmentId"
          }
        ],
        "responses": {
          "200": {
            "description": "The shipment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Shipment"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "tags": [
          "Shipments"
        ],
        "summary": "Cancel a shipment",
        "operationId": "cancelShipment",
        "description": "Cancels a shipment that has not yet been collected. Once it is in transit, cancellation is\nno longer ours to give and this returns `422` — contact support instead.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ShipmentId"
          }
        ],
        "responses": {
          "200": {
            "description": "Cancelled.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "description": "Too late to cancel.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/shipments/{shipment}/details": {
      "get": {
        "tags": [
          "Shipments"
        ],
        "summary": "Retrieve a shipment with its full history",
        "operationId": "getShipmentDetails",
        "description": "The shipment, its packages, its documents and its tracking events in one response.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ShipmentRef"
          }
        ],
        "responses": {
          "200": {
            "description": "The shipment in full.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Shipment"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "events": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/TrackingEvent"
                          }
                        },
                        "documents": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Document"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/shipments/label": {
      "post": {
        "tags": [
          "Labels and documents"
        ],
        "summary": "Get a label",
        "operationId": "createLabel",
        "description": "Returns the shipping label for a booked shipment. Labels are generated once and kept, so\ncalling this again returns the same label rather than buying another.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "shipment_id"
                ],
                "properties": {
                  "shipment_id": {
                    "type": "string"
                  },
                  "format": {
                    "type": "string",
                    "enum": [
                      "pdf",
                      "zpl",
                      "png"
                    ],
                    "default": "pdf",
                    "description": "ZPL is for direct-to-printer label printers."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The label, as a URL and base64 content.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Label"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/shipments/{id}/label": {
      "get": {
        "tags": [
          "Labels and documents"
        ],
        "summary": "Retrieve a shipment's label",
        "operationId": "getShipmentLabel",
        "parameters": [
          {
            "$ref": "#/components/parameters/ShipmentId"
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "pdf",
                "zpl",
                "png"
              ],
              "default": "pdf"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The label.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Label"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/shipments/{shipment}/documents": {
      "get": {
        "tags": [
          "Labels and documents"
        ],
        "summary": "List a shipment's documents",
        "operationId": "listShipmentDocuments",
        "parameters": [
          {
            "$ref": "#/components/parameters/ShipmentRef"
          }
        ],
        "responses": {
          "200": {
            "description": "Documents that exist for this shipment.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Document"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/shipments/{shipment}/documents/generate": {
      "post": {
        "tags": [
          "Labels and documents"
        ],
        "summary": "Generate a document",
        "operationId": "generateShipmentDocument",
        "description": "Produces a document for a shipment from what ByModo already holds about it. Generating a\ndocument that already exists replaces it.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ShipmentRef"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "type"
                ],
                "properties": {
                  "type": {
                    "$ref": "#/components/schemas/DocumentType"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The document.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Document"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/shipments/{id}/documents/bill-of-lading": {
      "get": {
        "tags": [
          "Labels and documents"
        ],
        "summary": "Download the bill of lading",
        "operationId": "getBillOfLading",
        "description": "The bill of lading as a PDF. Generated on first request if it does not exist yet.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ShipmentId"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/PdfDocument"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/shipments/{id}/documents/commercial-invoice": {
      "get": {
        "tags": [
          "Labels and documents"
        ],
        "summary": "Download the commercial invoice",
        "operationId": "getCommercialInvoice",
        "description": "The commercial invoice as a PDF, for a shipment crossing a border. This is the customs\ndocument describing the goods and their value — not a ByModo invoice for your account.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ShipmentId"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/PdfDocument"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/shipments/{id}/documents/packing-list": {
      "get": {
        "tags": [
          "Labels and documents"
        ],
        "summary": "Download the packing list",
        "operationId": "getPackingList",
        "parameters": [
          {
            "$ref": "#/components/parameters/ShipmentId"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/PdfDocument"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/shipments/{shipment}/documents/{type}/download": {
      "get": {
        "tags": [
          "Labels and documents"
        ],
        "summary": "Download any document by type",
        "operationId": "downloadShipmentDocument",
        "parameters": [
          {
            "$ref": "#/components/parameters/ShipmentRef"
          },
          {
            "name": "type",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/DocumentType"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/PdfDocument"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/orders/track/{trackingNumber}": {
      "get": {
        "tags": [
          "Tracking"
        ],
        "summary": "Track a shipment publicly",
        "operationId": "trackPublic",
        "description": "Tracking for a single shipment, by tracking number, with **no authentication**. This is the\nendpoint to put behind your own order-status page or your customer's \"where is it\" email —\nit is safe to call from a browser.\n\nBecause it is public it returns only what a recipient should see: status, milestones, and an\nestimated delivery. It does not return addresses, prices or account information.\n\nTracking text is normalised to ByModo. A scan that a carrier signed with its own name\nreaches you as ByModo, because ByModo is the carrier of record on your customer's shipment.\n",
        "security": [],
        "parameters": [
          {
            "name": "trackingNumber",
            "in": "path",
            "required": true,
            "description": "A ByModo tracking number.",
            "schema": {
              "type": "string",
              "examples": [
                "BMD-4KQ81JZ0W2XR"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Where the shipment is.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrackingResult"
                }
              }
            }
          },
          "404": {
            "description": "No shipment with that tracking number.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/shipments/track": {
      "post": {
        "tags": [
          "Tracking"
        ],
        "summary": "Track up to 50 shipments",
        "operationId": "trackBulk",
        "description": "Tracking for many shipments in one call — the right way to refresh a dashboard, instead of\na loop over the single-shipment endpoint.\n\nEach entry resolves independently: a tracking number that cannot be found comes back with\n`success: false` and leaves the rest of the batch intact.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "tracking_numbers"
                ],
                "properties": {
                  "tracking_numbers": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 50,
                    "items": {
                      "type": "string"
                    }
                  }
                }
              },
              "examples": {
                "several": {
                  "value": {
                    "tracking_numbers": [
                      "BMD-4KQ81JZ0W2XR",
                      "BMD-7PLM32DQ9YTE"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One result per tracking number.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TrackingResult"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/shipments/track/{carrierCode}/{trackingNumber}": {
      "get": {
        "tags": [
          "Tracking"
        ],
        "summary": "Track one shipment",
        "operationId": "trackOne",
        "description": "Authenticated tracking for a shipment on your account, returning the same normalised\nmilestones as the public endpoint.\n\n`carrierCode` is the code from the quote this shipment was booked on. If you do not have it\nto hand, use `GET /orders/track/{trackingNumber}`, which does not need it.\n",
        "parameters": [
          {
            "name": "carrierCode",
            "in": "path",
            "required": true,
            "description": "The `carrier_code` this shipment was booked on.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "trackingNumber",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Where the shipment is.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrackingResult"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/shipments/validate-address": {
      "post": {
        "tags": [
          "Addresses and configuration"
        ],
        "summary": "Validate and normalise an address",
        "operationId": "validateAddress",
        "description": "Checks an address before you rate or book with it, and returns it normalised. Worth calling\non addresses typed by a person: a wrong postal code is the most common reason a rating call\ncomes back with no quotes.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "city_locality",
                  "state_province",
                  "postal_code",
                  "country_code"
                ],
                "properties": {
                  "address_line1": {
                    "type": "string"
                  },
                  "city_locality": {
                    "type": "string"
                  },
                  "state_province": {
                    "type": "string"
                  },
                  "postal_code": {
                    "type": "string"
                  },
                  "country_code": {
                    "type": "string",
                    "description": "Two-letter ISO country code."
                  }
                }
              },
              "examples": {
                "montreal": {
                  "value": {
                    "address_line1": "1200 Rue Sainte-Catherine",
                    "city_locality": "Montreal",
                    "state_province": "QC",
                    "postal_code": "H3B4W8",
                    "country_code": "CA"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The verdict, and the address as it should be written.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "verified",
                        "unverified",
                        "warning",
                        "error"
                      ]
                    },
                    "normalized": {
                      "type": "object",
                      "description": "The address in its canonical form. Use this when booking.",
                      "properties": {
                        "address_line1": {
                          "type": "string"
                        },
                        "city_locality": {
                          "type": "string"
                        },
                        "state_province": {
                          "type": "string"
                        },
                        "postal_code": {
                          "type": "string"
                        },
                        "country_code": {
                          "type": "string"
                        }
                      }
                    },
                    "messages": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/form-config/shipping": {
      "get": {
        "tags": [
          "Addresses and configuration"
        ],
        "summary": "Discover what your account can ship",
        "operationId": "getShippingFormConfig",
        "description": "The shipment types, package types and additional services available to your account. Read\nthis instead of hard-coding the options — what an account can use depends on its\nagreements, and this is the list that will actually pass validation.\n",
        "responses": {
          "200": {
            "description": "Shipment types and the options each one allows.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "shipment_types": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "code": {
                            "type": "string"
                          },
                          "label": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "package_types": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "code": {
                            "type": "string"
                          },
                          "label": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "additional_services": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "code": {
                            "type": "string"
                          },
                          "label": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/form-config/shipping/{type}/services": {
      "get": {
        "tags": [
          "Addresses and configuration"
        ],
        "summary": "Services for one shipment type",
        "operationId": "getShippingTypeServices",
        "description": "The additional services allowed for a given shipment type, such as tailgate or inside pickup.",
        "parameters": [
          {
            "name": "type",
            "in": "path",
            "required": true,
            "description": "A `code` from `GET /form-config/shipping`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Services available for that shipment type.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "code": {
                            "type": "string"
                          },
                          "label": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Your API key, from Settings → API keys in the dashboard."
      },
      "BearerToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "The same API key, sent as a bearer token."
      }
    },
    "parameters": {
      "ShipmentId": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "The shipment's id.",
        "schema": {
          "type": "string"
        }
      },
      "ShipmentRef": {
        "name": "shipment",
        "in": "path",
        "required": true,
        "description": "The shipment's id.",
        "schema": {
          "type": "string"
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "The API key is missing, malformed or revoked.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "No such record, or it belongs to another account.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "ValidationError": {
        "description": "The request was understood and rejected. `errors` names each field at fault.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ValidationError"
            }
          }
        }
      },
      "PdfDocument": {
        "description": "The document as a PDF.",
        "content": {
          "application/pdf": {
            "schema": {
              "type": "string",
              "format": "binary"
            }
          }
        }
      }
    },
    "schemas": {
      "RateAddress": {
        "type": "object",
        "description": "An address as **rating** takes it. Note `contact`, where booking takes `name`.\n",
        "required": [
          "contact",
          "address",
          "city",
          "zip",
          "country",
          "phone"
        ],
        "properties": {
          "contact": {
            "type": "string",
            "maxLength": 255,
            "description": "Person to contact at this address."
          },
          "company": {
            "type": "string",
            "maxLength": 255
          },
          "address": {
            "type": "string",
            "maxLength": 255
          },
          "city": {
            "type": "string",
            "maxLength": 255
          },
          "state": {
            "type": "string",
            "maxLength": 255,
            "description": "Province or state. Optional, but omitting it in Canada and the US costs you accuracy."
          },
          "zip": {
            "type": "string",
            "maxLength": 20,
            "description": "Postal or ZIP code."
          },
          "country": {
            "type": "string",
            "minLength": 2,
            "maxLength": 2,
            "description": "Two-letter ISO country code."
          },
          "phone": {
            "type": "string",
            "maxLength": 50
          }
        }
      },
      "ShipmentAddress": {
        "type": "object",
        "description": "An address as **booking** takes it. Note `name`, where rating takes `contact`.\n",
        "required": [
          "name",
          "address",
          "city",
          "zip",
          "country",
          "phone"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Person or company at this address."
          },
          "address": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "description": "Province or state."
          },
          "zip": {
            "type": "string",
            "description": "Postal or ZIP code."
          },
          "country": {
            "type": "string",
            "minLength": 2,
            "maxLength": 2,
            "description": "Two-letter ISO country code."
          },
          "phone": {
            "type": "string"
          }
        }
      },
      "RatePackage": {
        "type": "object",
        "description": "A package as **rating** takes it. Units follow `unitSystem`.",
        "required": [
          "description",
          "weight",
          "length",
          "width",
          "height"
        ],
        "properties": {
          "description": {
            "type": "string",
            "maxLength": 255,
            "description": "What is inside. Required."
          },
          "type": {
            "type": "string",
            "maxLength": 50,
            "description": "A `code` from `GET /form-config/shipping`."
          },
          "weight": {
            "type": "number",
            "minimum": 0.01
          },
          "length": {
            "type": "number",
            "minimum": 0.1
          },
          "width": {
            "type": "number",
            "minimum": 0.1
          },
          "height": {
            "type": "number",
            "minimum": 0.1
          },
          "value": {
            "type": "number",
            "minimum": 0,
            "description": "Declared value, for insurance and customs."
          }
        }
      },
      "ShipmentPackage": {
        "type": "object",
        "description": "A package as **booking** takes it. Always kilograms and centimetres.",
        "required": [
          "description",
          "weightKg",
          "lengthCm",
          "widthCm",
          "heightCm"
        ],
        "properties": {
          "description": {
            "type": "string"
          },
          "weightKg": {
            "type": "number",
            "minimum": 0.1
          },
          "lengthCm": {
            "type": "number",
            "minimum": 1
          },
          "widthCm": {
            "type": "number",
            "minimum": 1
          },
          "heightCm": {
            "type": "number",
            "minimum": 1
          },
          "declaredValue": {
            "type": "number",
            "minimum": 0
          }
        }
      },
      "AdditionalServices": {
        "type": "object",
        "description": "Accessorials, where the lane and the service support them.",
        "properties": {
          "tailgate_pickup": {
            "type": "boolean",
            "description": "No loading dock at collection."
          },
          "flat_deck_pickup": {
            "type": "boolean"
          },
          "residential_pickup": {
            "type": "boolean",
            "description": "Collecting from a home rather than a business."
          },
          "inside_pickup": {
            "type": "boolean",
            "description": "Collection from inside the building, not the kerb."
          },
          "dropoff_at_terminal": {
            "type": "boolean",
            "description": "You deliver to the terminal yourself."
          }
        }
      },
      "RateRequest": {
        "type": "object",
        "required": [
          "from",
          "to",
          "packages"
        ],
        "properties": {
          "from": {
            "$ref": "#/components/schemas/RateAddress"
          },
          "to": {
            "$ref": "#/components/schemas/RateAddress"
          },
          "packages": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/RatePackage"
            }
          },
          "unitSystem": {
            "type": "string",
            "enum": [
              "metric",
              "imperial"
            ],
            "default": "metric",
            "description": "Units for every weight and dimension in this request."
          },
          "shippingType": {
            "type": "string",
            "description": "A shipment type `code` from `GET /form-config/shipping`."
          },
          "additional_services": {
            "$ref": "#/components/schemas/AdditionalServices"
          }
        }
      },
      "ShipmentRequest": {
        "type": "object",
        "required": [
          "from",
          "to",
          "packages"
        ],
        "properties": {
          "from": {
            "$ref": "#/components/schemas/ShipmentAddress"
          },
          "to": {
            "$ref": "#/components/schemas/ShipmentAddress"
          },
          "packages": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/ShipmentPackage"
            }
          },
          "additionalServices": {
            "type": "array",
            "description": "Accessorials, each with an optional reference of your own.",
            "items": {
              "type": "object",
              "properties": {
                "serviceType": {
                  "type": "string"
                },
                "reference": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "Quote": {
        "type": "object",
        "description": "One priceable option. `total_amount` is what you will be charged; it is the only money\nfield you should build on.\n",
        "properties": {
          "carrier_code": {
            "type": "string",
            "description": "Opaque identifier for the service. Pass it back unchanged when booking."
          },
          "service_code": {
            "type": "string",
            "description": "Opaque identifier for the service level. Pass it back unchanged when booking."
          },
          "service_name": {
            "type": "string",
            "description": "The service as it should be shown to a person."
          },
          "total_amount": {
            "type": "number",
            "description": "The price of this option, in `currency`. This is the figure to display and to book on."
          },
          "currency": {
            "type": "string",
            "examples": [
              "CAD"
            ]
          },
          "transit_days": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Business days in transit, where the service quotes one."
          },
          "delivery_date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Estimated delivery, where the service quotes one."
          },
          "fuel_amount": {
            "type": "number",
            "description": "Fuel surcharge included in `total_amount`."
          },
          "fuel_percentage": {
            "type": "number"
          }
        }
      },
      "RateResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "rate_request_id": {
            "type": "string",
            "description": "Quote this when booking, to be charged the price you were quoted.",
            "examples": [
              "bym-8f3a21c7"
            ]
          },
          "quotes": {
            "type": "array",
            "description": "Every option that would carry the shipment. Empty means none would.",
            "items": {
              "$ref": "#/components/schemas/Quote"
            }
          }
        }
      },
      "ShipmentStatus": {
        "type": "string",
        "description": "Where a shipment is in its life, independent of any carrier's own vocabulary.",
        "enum": [
          "pending",
          "booked",
          "label_created",
          "in_transit",
          "out_for_delivery",
          "delivered",
          "exception",
          "cancelled"
        ]
      },
      "Shipment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "tracking_number": {
            "type": "string",
            "description": "The ByModo tracking number. This is the number on the paperwork and the one to track.",
            "examples": [
              "BMD-4KQ81JZ0W2XR"
            ]
          },
          "status": {
            "$ref": "#/components/schemas/ShipmentStatus"
          },
          "service_name": {
            "type": "string",
            "description": "The service this shipment travels on."
          },
          "total_amount": {
            "type": "number",
            "description": "What this shipment costs you."
          },
          "currency": {
            "type": "string"
          },
          "reference": {
            "type": [
              "string",
              "null"
            ],
            "description": "Your own reference, if you sent one."
          },
          "ship_from": {
            "type": "object",
            "additionalProperties": true
          },
          "ship_to": {
            "type": "object",
            "additionalProperties": true
          },
          "packages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ShipmentPackage"
            }
          },
          "label_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "Present once a label exists."
          },
          "estimated_delivery_date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "TrackingEvent": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "description": "The milestone, in ByModo's vocabulary rather than a carrier's."
          },
          "description": {
            "type": "string",
            "description": "What happened, normalised to ByModo."
          },
          "location": {
            "type": [
              "string",
              "null"
            ]
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "TrackingResult": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "tracking_number": {
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/ShipmentStatus"
          },
          "current_location": {
            "type": [
              "string",
              "null"
            ]
          },
          "estimated_delivery_date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "estimated_delivery_end": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "The far end of a delivery window, when one was quoted rather than a single time."
          },
          "is_complete": {
            "type": "boolean",
            "description": "Whether the journey is over, however the milestone is worded."
          },
          "events": {
            "type": "array",
            "description": "Newest first.",
            "items": {
              "$ref": "#/components/schemas/TrackingEvent"
            }
          },
          "error": {
            "type": [
              "string",
              "null"
            ],
            "description": "Present when this entry could not be resolved."
          }
        }
      },
      "DocumentType": {
        "type": "string",
        "enum": [
          "bill_of_lading",
          "commercial_invoice",
          "packing_list",
          "label",
          "proof_of_delivery"
        ]
      },
      "Document": {
        "type": "object",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/DocumentType"
          },
          "url": {
            "type": "string",
            "description": "Short-lived download URL."
          },
          "filename": {
            "type": "string"
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Label": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "tracking_number": {
            "type": "string"
          },
          "format": {
            "type": "string",
            "enum": [
              "pdf",
              "zpl",
              "png"
            ]
          },
          "label_url": {
            "type": "string",
            "description": "Short-lived download URL."
          },
          "label_data": {
            "type": [
              "string",
              "null"
            ],
            "description": "The label itself, base64 encoded."
          }
        }
      },
      "PaginationMeta": {
        "type": "object",
        "properties": {
          "current_page": {
            "type": "integer"
          },
          "per_page": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          },
          "last_page": {
            "type": "integer"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "const": false
          },
          "error": {
            "type": "string",
            "description": "What went wrong."
          }
        }
      },
      "ValidationError": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "description": "The first problem, as a sentence."
          },
          "errors": {
            "type": "object",
            "description": "One entry per field at fault, each a list of messages.",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}
