v1.0

OpenAPI 2.0

Cargoplot API

Glossary of the codes, abbreviations and statuses this API returns

Cargoplot

The public Cargoplot API. Authenticate with a Personal Access Token sent in the X-Cargoplot-Key header.

Server

https://api.cargoplot.com

Client Libraries

Shell Curl

Document

Document Operations

get/v1/document/{document}/download
get/v1/shipment/{shipment}/document

Download a document

Returns the uploaded file, with the content type it was stored as.

The id is the document.id from GET /v1/shipment/{shipment}/document, not the slot id.

A document is readable when it is attached to a shipment in your organization and its type is one this API serves.

Path Parameters

document
Type: string
required

The document's numeric id, as carried by document.id in the shipment's document list.

Responses

application/json
application/json
application/json
application/json
application/json

get/v1/document/{document}/download

curl 'https://api.cargoplot.com/v1/document/{document}/download' \
  --header 'X-Cargoplot-Key: YOUR_SECRET_TOKEN'

Show Schema

string

The document file.

List a shipment's documents

Returns the document checklist for one shipment: every slot, whether or not a file has been uploaded into it.

A slot with no file has no document member; one with a file carries it. That is how you tell the two apart.

The list is not paginated. A shipment's checklist is a small, bounded set.

The path segment accepts either the Cargoplot reference (C2AE-XEE1) or the numeric id (7).

The checklist covers the document types this API serves.

Path Parameters

shipment
Type: string
required

The shipment's Cargoplot reference (C2AE-XEE1) or its numeric id (7).

Responses

application/json
application/json
application/json
application/json
application/json

get/v1/shipment/{shipment}/document

curl 'https://api.cargoplot.com/v1/shipment/{shipment}/document' \
  --header 'X-Cargoplot-Key: YOUR_SECRET_TOKEN'

Show Schema

{
  "documents": [
    {
      "id": "3",
      "type": "TYPE_COMMERCIAL_INVOICE",
      "status": "STATUS_RECEIVED",
      "document": {
        "id": "42",
        "file_name": "invoice.pdf"
      }
    }
  ]
}

A successful response.

Inquiry

Inquiry Operations

get/v1/inquiry
get/v1/inquiry/{inquiry}

List inquiries

Returns a cursor-paginated page of inquiries for the authenticated user's organization, most-recent first. Defaults to 50 inquiries per page; 100 is the maximum. Pass the after (or before) cursor from the previous response to fetch the next (or previous) page.

Each inquiry carries exactly one of fcl or lcl, never both, chosen by cargo_type: CARGO_TYPE_CONTAINERS is FCL, CARGO_TYPE_PACKAGES and CARGO_TYPE_PALLETS are LCL. Swagger 2.0 cannot express that exclusivity, so it is stated here.

Query Parameters

limit
Type: integer Format: int32

Page size, 1 to 100. Defaults to 50 when omitted or 0. A value above 100 or below 0 is rejected with 400.
after
Type: string

Opaque cursor: fetch the page after this cursor (from a previous response's cursor.after). Cannot be combined with before.
before
Type: string

Opaque cursor: fetch the page before this cursor (from a previous response's cursor.before). Cannot be combined with after.
order
Type: string enum

Sort direction. Defaults to descending.
values
- ORDER_UNSPECIFIED
- ORDER_ASC
- ORDER_DESC
order_by
Type: string enum
Field to sort by. Defaults to newest first. The sort is part of the cursor, so it cannot change while paging through a result set.

INQUIRY_ORDER_BY_UNSPECIFIED: Falls back to the server default (newest first, by id).
values
- INQUIRY_ORDER_BY_UNSPECIFIED
- INQUIRY_ORDER_BY_REFERENCE
- INQUIRY_ORDER_BY_STATUS
- INQUIRY_ORDER_BY_CARGO_READY_DATE
- INQUIRY_ORDER_BY_CREATE_TIME
search
Type: string

Free-text search across inquiry reference, description and origin/destination city. Narrows results; does not reorder them.
filter.status
Type: array string[] enum
Match inquiries in any of these states.

STATUS_UNSPECIFIED: No status reported.

STATUS_RECEIVED: Submitted, and waiting to be priced.

STATUS_PRICES_REQUESTED: Rates are being gathered for it.

STATUS_QUOTES_PROPOSED: One or more quotes are ready to review.

STATUS_QUOTE_ACCEPTED: A quote was accepted. The shipment follows from here.

STATUS_CANCELLED: Withdrawn. No quote will follow.
values
- STATUS_UNSPECIFIED
- STATUS_RECEIVED
- STATUS_PRICES_REQUESTED
- STATUS_QUOTES_PROPOSED
- STATUS_QUOTE_ACCEPTED
- STATUS_CANCELLED
filter.cargo_ready_date
Type: string

Filter on the cargo ready date. One of YYYY-MM-DD, gte:YYYY-MM-DD, lte:YYYY-MM-DD or YYYY-MM-DD..YYYY-MM-DD.

Responses

application/json
application/json
application/json
application/json
application/json

get/v1/inquiry

curl https://api.cargoplot.com/v1/inquiry \
  --header 'X-Cargoplot-Key: YOUR_SECRET_TOKEN'

Show Schema

{
  "inquiries": [
    {
      "id": "string",
      "create_time": "2026-09-17T19:52:57.186Z",
      "update_time": "2026-09-17T19:52:57.186Z",
      "status": "STATUS_UNSPECIFIED",
      "requester_user_id": "string",
      "organization_id": "string",
      "reference": "C3AT-XHM0",
      "description": "string",
      "origin": {
        "revision": 1,
        "region_code": "string",
        "language_code": "string",
        "postal_code": "string",
        "sorting_code": "string",
        "administrative_area": "string",
        "locality": "string",
        "sublocality": "string",
        "address_lines": [
          "string"
        ],
        "recipients": [
          "string"
        ],
        "organization": "string"
      },
      "destination": {
        "revision": 1,
        "region_code": "string",
        "language_code": "string",
        "postal_code": "string",
        "sorting_code": "string",
        "administrative_area": "string",
        "locality": "string",
        "sublocality": "string",
        "address_lines": [
          "string"
        ],
        "recipients": [
          "string"
        ],
        "organization": "string"
      },
      "cargo_ready_date": "2026-09-17",
      "cargo_type": "CARGO_TYPE_UNSPECIFIED",
      "transport_modes": [
        "TRANSPORT_MODE_UNSPECIFIED"
      ],
      "special_contents": [
        "SPECIAL_CONTENTS_UNSPECIFIED"
      ],
      "incoterms": [
        "INCOTERM_UNSPECIFIED"
      ],
      "max_transit_days": 1,
      "min_review_score": 1,
      "hs_code_count": 1,
      "timeslot_delivery": true,
      "gas_measurement": true,
      "storage": true,
      "side_loader_delivery": true,
      "total_volume": 1,
      "total_weight": 1,
      "port_of_loading": "string",
      "port_of_discharge": "string",
      "insured_goods_value": {
        "currency": "EUR",
        "amount_cents": 150000
      },
      "carriers": [
        "string"
      ],
      "suppliers": [
        {
          "name": "string",
          "email": "string",
          "phone": "string",
          "address": "string"
        }
      ],
      "fcl": {
        "containers": [
          {
            "type": "CONTAINER_TYPE_UNSPECIFIED",
            "quantity": 1,
            "dropoff_terminal_code": "string"
          }
        ],
        "min_free_demurrage_days": 1,
        "min_free_detention_days": 1
      },
      "lcl": {
        "components": [
          {
            "width": 1.2,
            "height": 1.5,
            "depth": 0.8,
            "weight": 250,
            "quantity": 4
          }
        ],
        "tail_lift": true,
        "pallet_exchange": true
      }
    }
  ],
  "cursor": {
    "after": "string",
    "before": "string"
  }
}

A successful response.

Get an inquiry

Returns a single inquiry from the authenticated user's organization.

The path segment accepts either the Cargoplot reference (C3AT-XHM0) or the numeric id (7). An all-digit value is tried as an id first and then as a reference, so a reference that happens to be all digits stays reachable.

The inquiry is rendered exactly as it appears in the inquiries array of GET /v1/inquiry.

Path Parameters

inquiry
Type: string
required

The inquiry's Cargoplot reference (C3AT-XHM0) or its numeric id (7).

Responses

application/json
application/json
application/json
application/json
application/json

get/v1/inquiry/{inquiry}

curl 'https://api.cargoplot.com/v1/inquiry/{inquiry}' \
  --header 'X-Cargoplot-Key: YOUR_SECRET_TOKEN'

Show Schema

{
  "id": "string",
  "create_time": "2026-09-17T19:52:57.186Z",
  "update_time": "2026-09-17T19:52:57.186Z",
  "status": "STATUS_UNSPECIFIED",
  "requester_user_id": "string",
  "organization_id": "string",
  "reference": "C3AT-XHM0",
  "description": "string",
  "origin": {
    "revision": 1,
    "region_code": "string",
    "language_code": "string",
    "postal_code": "string",
    "sorting_code": "string",
    "administrative_area": "string",
    "locality": "string",
    "sublocality": "string",
    "address_lines": [
      "string"
    ],
    "recipients": [
      "string"
    ],
    "organization": "string"
  },
  "destination": {
    "revision": 1,
    "region_code": "string",
    "language_code": "string",
    "postal_code": "string",
    "sorting_code": "string",
    "administrative_area": "string",
    "locality": "string",
    "sublocality": "string",
    "address_lines": [
      "string"
    ],
    "recipients": [
      "string"
    ],
    "organization": "string"
  },
  "cargo_ready_date": "2026-09-17",
  "cargo_type": "CARGO_TYPE_UNSPECIFIED",
  "transport_modes": [
    "TRANSPORT_MODE_UNSPECIFIED"
  ],
  "special_contents": [
    "SPECIAL_CONTENTS_UNSPECIFIED"
  ],
  "incoterms": [
    "INCOTERM_UNSPECIFIED"
  ],
  "max_transit_days": 1,
  "min_review_score": 1,
  "hs_code_count": 1,
  "timeslot_delivery": true,
  "gas_measurement": true,
  "storage": true,
  "side_loader_delivery": true,
  "total_volume": 1,
  "total_weight": 1,
  "port_of_loading": "string",
  "port_of_discharge": "string",
  "insured_goods_value": {
    "currency": "EUR",
    "amount_cents": 150000
  },
  "carriers": [
    "string"
  ],
  "suppliers": [
    {
      "name": "string",
      "email": "string",
      "phone": "string",
      "address": "string"
    }
  ],
  "fcl": {
    "containers": [
      {
        "type": "CONTAINER_TYPE_UNSPECIFIED",
        "quantity": 1,
        "dropoff_terminal_code": "string"
      }
    ],
    "min_free_demurrage_days": 1,
    "min_free_detention_days": 1
  },
  "lcl": {
    "components": [
      {
        "width": 1.2,
        "height": 1.5,
        "depth": 0.8,
        "weight": 250,
        "quantity": 4
      }
    ],
    "tail_lift": true,
    "pallet_exchange": true
  }
}

A successful response.

Invoice

Invoice Operations

get/v1/invoice
get/v1/invoice/{invoice}
get/v1/invoice/{invoice}/download
get/v1/shipment/{shipment}/invoice

List invoices

Returns a cursor-paginated page of invoices for the authenticated user's organization, most-recent first. Defaults to 50 invoices per page; 100 is the maximum. Pass the after (or before) cursor from the previous response to fetch the next (or previous) page.

The page lists invoices that have been issued to your organization.

Query Parameters

limit
Type: integer Format: int32

Page size, 1 to 100. Defaults to 50 when omitted or 0. A value above 100 or below 0 is rejected with 400.
after
Type: string

Opaque cursor: fetch the page after this cursor (from a previous response's cursor.after). Cannot be combined with before.
before
Type: string

Opaque cursor: fetch the page before this cursor (from a previous response's cursor.before). Cannot be combined with after.
order
Type: string enum

Sort direction. Defaults to descending.
values
- ORDER_UNSPECIFIED
- ORDER_ASC
- ORDER_DESC
order_by
Type: string enum
Field to sort by. Defaults to newest first. The sort is part of the cursor, so it cannot change while paging through a result set.

INVOICE_ORDER_BY_UNSPECIFIED: Falls back to the server default (newest first, by id).
values
- INVOICE_ORDER_BY_UNSPECIFIED
- INVOICE_ORDER_BY_REFERENCE
- INVOICE_ORDER_BY_STATUS
- INVOICE_ORDER_BY_ISSUE_DATE
- INVOICE_ORDER_BY_DUE_DATE
- INVOICE_ORDER_BY_PUBLISHED_AT
- INVOICE_ORDER_BY_AMOUNT_EX_VAT
- INVOICE_ORDER_BY_AMOUNT_INC_VAT
- INVOICE_ORDER_BY_CREATE_TIME
search
Type: string

Free-text search across the invoice reference. Narrows results; does not reorder them.
filter.status
Type: array string[] enum
Match invoices in any of these states.

STATUS_UNSPECIFIED: No status reported.

STATUS_PUBLISHED: Issued to you and payable.

STATUS_PAID: Settled in full.

STATUS_DISPUTED: Queried. The amount is under discussion.

STATUS_IN_COLLECTION: Overdue, and handed to a collection agency.

STATUS_IN_PAYMENT_PLAN: Being settled in agreed instalments.

STATUS_FORFEITED: Written off. No further settlement is expected.
values
- STATUS_UNSPECIFIED
- STATUS_PUBLISHED
- STATUS_PAID
- STATUS_DISPUTED
- STATUS_IN_COLLECTION
- STATUS_IN_PAYMENT_PLAN
- STATUS_FORFEITED
filter.issue_date
Type: string

Filter on the issue date. One of YYYY-MM-DD, gte:YYYY-MM-DD, lte:YYYY-MM-DD or YYYY-MM-DD..YYYY-MM-DD.
filter.due_date
Type: string

Filter on the due date. Same formats as issue_date.

Responses

application/json
application/json
application/json
application/json

get/v1/invoice

curl https://api.cargoplot.com/v1/invoice \
  --header 'X-Cargoplot-Key: YOUR_SECRET_TOKEN'

Show Schema

{
  "invoices": [
    {
      "id": "7",
      "reference": "F2401-C2AE-XEE1",
      "shipment_id": "12",
      "status": "STATUS_PUBLISHED",
      "issue_date": "2026-07-01",
      "due_date": "2026-07-31"
    }
  ],
  "cursor": {
    "after": "string",
    "before": "string"
  }
}

A successful response.

Get an invoice

Returns a single invoice from the authenticated user's organization.

The path segment accepts either the invoice reference (F2401-C2AE-XEE1) or the numeric id (7). An all-digit value is tried as an id first and then as a reference, so a reference that happens to be all digits stays reachable.

The invoice is rendered exactly as it appears in the invoices array of GET /v1/invoice.

Path Parameters

invoice
Type: string
required

The invoice's reference (F2401-C2AE-XEE1) or its numeric id (7).

Responses

application/json
application/json
application/json
application/json
application/json

get/v1/invoice/{invoice}

curl 'https://api.cargoplot.com/v1/invoice/{invoice}' \
  --header 'X-Cargoplot-Key: YOUR_SECRET_TOKEN'

Show Schema

{
  "id": "7",
  "reference": "F2401-C2AE-XEE1",
  "shipment_id": "12",
  "status": "STATUS_PUBLISHED",
  "issue_date": "2026-07-01",
  "due_date": "2026-07-31"
}

A successful response.

Download an invoice PDF

Returns the invoice document as application/pdf.

Addressed exactly as GET /v1/invoice/{invoice}.

Path Parameters

invoice
Type: string
required

The invoice's reference (F2401-C2AE-XEE1) or its numeric id (7).

Responses

application/json
application/json
application/json
application/json
application/json

get/v1/invoice/{invoice}/download

curl 'https://api.cargoplot.com/v1/invoice/{invoice}/download' \
  --header 'X-Cargoplot-Key: YOUR_SECRET_TOKEN'

Show Schema

string

The invoice PDF.

List a shipment's invoices

Returns a cursor-paginated page of the invoices raised for one shipment. Paging, ordering and filtering behave exactly as they do on GET /v1/invoice.

The path segment accepts either the Cargoplot reference (C2AE-XEE1) or the numeric id (7).

Path Parameters

shipment
Type: string
required

The shipment's Cargoplot reference (C2AE-XEE1) or its numeric id (7).

Query Parameters

limit
Type: integer Format: int32

Page size, 1 to 100. Defaults to 50 when omitted or 0.
after
Type: string

Opaque cursor: fetch the page after this cursor. Cannot be combined with before.
before
Type: string

Opaque cursor: fetch the page before this cursor. Cannot be combined with after.
order
Type: string enum

Sort direction. Defaults to descending.
values
- ORDER_UNSPECIFIED
- ORDER_ASC
- ORDER_DESC
order_by
Type: string enum
Field to sort by. Defaults to newest first.

INVOICE_ORDER_BY_UNSPECIFIED: Falls back to the server default (newest first, by id).
values
- INVOICE_ORDER_BY_UNSPECIFIED
- INVOICE_ORDER_BY_REFERENCE
- INVOICE_ORDER_BY_STATUS
- INVOICE_ORDER_BY_ISSUE_DATE
- INVOICE_ORDER_BY_DUE_DATE
- INVOICE_ORDER_BY_PUBLISHED_AT
- INVOICE_ORDER_BY_AMOUNT_EX_VAT
- INVOICE_ORDER_BY_AMOUNT_INC_VAT
- INVOICE_ORDER_BY_CREATE_TIME
search
Type: string

Free-text search across the invoice reference.
filter.status
Type: array string[] enum
Match invoices in any of these states.

STATUS_UNSPECIFIED: No status reported.

STATUS_PUBLISHED: Issued to you and payable.

STATUS_PAID: Settled in full.

STATUS_DISPUTED: Queried. The amount is under discussion.

STATUS_IN_COLLECTION: Overdue, and handed to a collection agency.

STATUS_IN_PAYMENT_PLAN: Being settled in agreed instalments.

STATUS_FORFEITED: Written off. No further settlement is expected.
values
- STATUS_UNSPECIFIED
- STATUS_PUBLISHED
- STATUS_PAID
- STATUS_DISPUTED
- STATUS_IN_COLLECTION
- STATUS_IN_PAYMENT_PLAN
- STATUS_FORFEITED
filter.issue_date
Type: string

Filter on the issue date. One of YYYY-MM-DD, gte:YYYY-MM-DD, lte:YYYY-MM-DD or YYYY-MM-DD..YYYY-MM-DD.
filter.due_date
Type: string

Filter on the due date. Same formats as issue_date.

Responses

application/json
application/json
application/json
application/json
application/json

get/v1/shipment/{shipment}/invoice

curl 'https://api.cargoplot.com/v1/shipment/{shipment}/invoice' \
  --header 'X-Cargoplot-Key: YOUR_SECRET_TOKEN'

Show Schema

{
  "invoices": [
    {
      "id": "7",
      "reference": "F2401-C2AE-XEE1",
      "shipment_id": "12",
      "status": "STATUS_PUBLISHED",
      "issue_date": "2026-07-01",
      "due_date": "2026-07-31"
    }
  ],
  "cursor": {
    "after": "string",
    "before": "string"
  }
}

A successful response.

Organization

Organization Operations

get/v1/profile/organization

Get the authenticated user's organization

Returns the organization the authenticated user currently belongs to.

The response carries the organization's own id, which is the value every shipment, inquiry and user reports as organization_id.

It covers the organization's identity and trade registration details; the full field set is below.

type is one of TYPE_CLIENT (ships cargo), TYPE_FORWARDER (moves it), TYPE_SUPPLIER, or TYPE_UNSPECIFIED when the stored value is not one of those.

postal_address.region_code is populated only when the stored country is a genuine CLDR region code, and is an empty string otherwise rather than carrying a country name, which would fail validation as a country code and take the whole address down with it.

Responses

application/json
application/json
application/json
application/json
application/json
application/json

get/v1/profile/organization

curl https://api.cargoplot.com/v1/profile/organization \
  --header 'X-Cargoplot-Key: YOUR_SECRET_TOKEN'

Show Schema

{
  "id": "42",
  "name": "Coffee Importers B.V.",
  "vat": "NL001234567B01",
  "eori": "NL001234567",
  "coc": "12345678",
  "website": "https://example.com",
  "contact_email": "info@example.com"
}

A successful response.

User

User Operations

get/v1/profile/user
get/v1/user/{user}

Get the authenticated user

Returns the user the request's credential authenticates as.

Rendered exactly as GET /v1/user/{user} renders the same person, so the two are interchangeable for a caller that already knows its own id.

Responses

application/json
application/json
application/json
application/json
application/json
application/json

get/v1/profile/user

curl https://api.cargoplot.com/v1/profile/user \
  --header 'X-Cargoplot-Key: YOUR_SECRET_TOKEN'

Show Schema

{
  "id": "7",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "email": "ada@example.com",
  "phone": "+31 10 123 4567",
  "language": "en",
  "organization_id": "42"
}

A successful response.

Get a user

Resolves one user in the authenticated caller's organization by id. This is what makes a shipment's client_user_id and an inquiry's requester_user_id resolvable.

Rendered exactly as GET /v1/profile/user renders the caller.

There is no user list endpoint: ids arrive on the shipment and inquiry records that reference them.

An id from an older record may no longer resolve, which is expected rather than a fault — see client_user_id for when.

Path Parameters

user
Type: string Format: uint64
required

The user's numeric id, as carried by a shipment's client_user_id or an inquiry's requester_user_id.

Responses

application/json
application/json
application/json
application/json
application/json
application/json

get/v1/user/{user}

curl 'https://api.cargoplot.com/v1/user/{user}' \
  --header 'X-Cargoplot-Key: YOUR_SECRET_TOKEN'

Show Schema

{
  "id": "7",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "email": "ada@example.com",
  "phone": "+31 10 123 4567",
  "language": "en",
  "organization_id": "42"
}

A successful response.

Shipment

Shipment Operations

get/v1/shipment
get/v1/shipment/{shipment}

List shipments

Returns a cursor-paginated page of shipments for the authenticated user's organization, most-recent first. Defaults to 50 shipments per page; 100 is the maximum. Pass the after (or before) cursor from the previous response to fetch the next (or previous) page.

Each shipment carries exactly one of fcl or lcl, never both, chosen by cargo_type: CARGO_TYPE_CONTAINERS is FCL, CARGO_TYPE_PACKAGES and CARGO_TYPE_PALLETS are LCL. Swagger 2.0 cannot express that exclusivity, so it is stated here.

Query Parameters

limit
Type: integer Format: int32

Page size, 1 to 100. Defaults to 50 when omitted or 0. A value above 100 or below 0 is rejected with 400.
after
Type: string

Opaque cursor: fetch the page after this cursor (from a previous response's cursor.after). Cannot be combined with before.
before
Type: string

Opaque cursor: fetch the page before this cursor (from a previous response's cursor.before). Cannot be combined with after.
order
Type: string enum

Sort direction. Defaults to descending.
values
- ORDER_UNSPECIFIED
- ORDER_ASC
- ORDER_DESC
order_by
Type: string enum
Field to sort by. Defaults to newest first. The sort is part of the cursor, so it cannot change while paging through a result set.

SHIPMENT_ORDER_BY_UNSPECIFIED: Falls back to the server default (newest first, by id).
values
- SHIPMENT_ORDER_BY_UNSPECIFIED
- SHIPMENT_ORDER_BY_REFERENCE
- SHIPMENT_ORDER_BY_STATUS
- SHIPMENT_ORDER_BY_ETD
- SHIPMENT_ORDER_BY_ETA
- SHIPMENT_ORDER_BY_CARGO_READY_DATE
- SHIPMENT_ORDER_BY_CREATE_TIME
search
Type: string

Free-text search across shipment reference, description and origin/destination city. Narrows results; does not reorder them.
filter.status
Type: array string[] enum
Match shipments in any of these states.

STATUS_UNSPECIFIED: No status reported.

STATUS_ACTIVE: Booked and under way, or being prepared to move.

STATUS_COMPLETED: Delivered and closed.

STATUS_CANCELLED: Called off. It will not move.

STATUS_ON_HOLD: Paused. Still live, but not progressing.
values
- STATUS_UNSPECIFIED
- STATUS_ACTIVE
- STATUS_COMPLETED
- STATUS_CANCELLED
- STATUS_ON_HOLD
filter.etd
Type: string

Filter on estimated departure. One of YYYY-MM-DD, gte:YYYY-MM-DD, lte:YYYY-MM-DD or YYYY-MM-DD..YYYY-MM-DD.
filter.eta
Type: string

Filter on estimated arrival. Same formats as etd.

Responses

application/json
application/json
application/json
application/json

get/v1/shipment

curl https://api.cargoplot.com/v1/shipment \
  --header 'X-Cargoplot-Key: YOUR_SECRET_TOKEN'

Show Schema

{
  "shipments": [
    {
      "id": "7",
      "reference": "C2AE-XEE1",
      "forwarder_reference": "FWD-42",
      "description": "20 pallets of coffee",
      "status": "STATUS_ACTIVE",
      "etd": "2026-07-10",
      "cargo_ready_date": "2026-07-01"
    }
  ],
  "cursor": {
    "after": "string",
    "before": "string"
  }
}

A successful response.

Get a shipment

Returns a single shipment from the authenticated user's organization.

The path segment accepts either the Cargoplot reference (C2AE-XEE1) or the numeric id (7). An all-digit value is tried as an id first and then as a reference, so a reference that happens to be all digits stays reachable.

The shipment is rendered exactly as it appears in the shipments array of GET /v1/shipment.

Path Parameters

shipment
Type: string
required

The shipment's Cargoplot reference (C2AE-XEE1) or its numeric id (7).

Responses

application/json
application/json
application/json
application/json
application/json

get/v1/shipment/{shipment}

curl 'https://api.cargoplot.com/v1/shipment/{shipment}' \
  --header 'X-Cargoplot-Key: YOUR_SECRET_TOKEN'

Show Schema

{
  "id": "7",
  "reference": "C2AE-XEE1",
  "forwarder_reference": "FWD-42",
  "description": "20 pallets of coffee",
  "status": "STATUS_ACTIVE",
  "etd": "2026-07-10",
  "cargo_ready_date": "2026-07-01"
}

A successful response.

Tracking

Tracking Operations

get/v1/shipment/{shipment}/tracking

Get shipment tracking

Returns one unpaginated shipment tracking response. The timeline is nested under the key naming the shipment's transport mode, so a response carries exactly one of them and a reader never has to guess which.

For sea freight that key is sea, and its containers originate from the authenticated organization's shipment.

For air freight it is air, whose milestones sit at the shipment level because air cargo has no container to hang them on.

A known shipment with no movement data still returns its mode key, with the containers it is known to hold and empty events arrays.

The path segment accepts the Cargoplot reference (C2AE-XEE1) or numeric id (7).

Path Parameters

shipment
Type: string
required

The shipment's Cargoplot reference (C2AE-XEE1) or numeric id (7).

Responses

application/json
application/json
application/json
application/json
application/json
application/json

get/v1/shipment/{shipment}/tracking

curl 'https://api.cargoplot.com/v1/shipment/{shipment}/tracking' \
  --header 'X-Cargoplot-Key: YOUR_SECRET_TOKEN'

Show Schema

{
  "etd": "2026-09-05",
  "eta": "2026-09-17",
  "sea": {
    "containers": [
      {
        "container_number": "string",
        "container_type": "CONTAINER_TYPE_UNSPECIFIED",
        "status": "CONTAINER_TRACKING_STATUS_UNSPECIFIED",
        "events": [
          {
            "type": "SEA_TRACKING_EVENT_TYPE_UNSPECIFIED",
            "state": "TRACKING_EVENT_STATE_UNSPECIFIED",
            "timestamp": "2026-09-17T19:52:57.186Z",
            "location": {
              "un_locode": "string",
              "name": "string"
            },
            "vessel": {
              "name": "string",
              "voyage": "string"
            }
          }
        ],
        "discharge_date": "2026-09-17",
        "gate_out_time": "2026-09-17T19:52:57.186Z",
        "empty_return_time": "2026-09-17T19:52:57.186Z",
        "discharge_terminal": "string"
      }
    ]
  },
  "air": {
    "status": "AIR_TRACKING_STATUS_UNSPECIFIED",
    "events": [
      {
        "type": "AIR_TRACKING_EVENT_TYPE_UNSPECIFIED",
        "state": "TRACKING_EVENT_STATE_UNSPECIFIED",
        "timestamp": "2026-09-17T19:52:57.186Z",
        "location": {
          "iata": "string",
          "name": "string"
        },
        "flight": {
          "number": "string",
          "airline": "string"
        },
        "cargo": {
          "pieces": 1,
          "weight_kg": 1,
          "volume_cbm": 1
        }
      }
    ]
  }
}

A successful response.

Cargoplot API

Document

Download a document

List a shipment's documents

Inquiry

List inquiries

Get an inquiry

Invoice

List invoices

Get an invoice

Download an invoice PDF

List a shipment's invoices

Organization

Get the authenticated user's organization

User

Get the authenticated user

Get a user

Shipment

List shipments

Get a shipment

Tracking

Get shipment tracking

Models

enum DocumentMediaType

enum VatTypeCategory

{} apiHttpBody

{} Money

enum cargoplotCargoType

enum cargoplotContainerType

enum cargoplotDocumentSlotStatus

enum cargoplotDocumentType

enum cargoplotIncoterm

enum cargoplotSpecialContents

enum cargoplotTransportMode

{} googleRpcStatus

{} protobufAny

{} typePostalAddress

{} v1AirTracking

{} v1AirTrackingEvent

enum v1AirTrackingEventType

{} v1AirTrackingLocation

enum v1AirTrackingStatus

{} CargoComponent

{} v1Container

enum v1ContainerTrackingStatus

{} v1Cursor

{} v1DocumentDetails

{} FclDetails

{} v1GetShipmentTrackingResponse

{} InquiryFclDetails

{} v1InquiryFilter

{} InquiryLclDetails

enum v1InquiryOrderBy

{} InquiryResponse

enum v1InquiryResponseStatus

{} v1InvoiceFilter

{} v1InvoiceLineItem

enum v1InvoiceOrderBy

{} InvoiceResponse

enum v1InvoiceResponseStatus

{} LclDetails

{} v1ListInquiriesResponse

{} v1ListInvoicesResponse

{} v1ListShipmentDocumentsResponse

{} v1ListShipmentsResponse

enum v1Order

{} OrganizationResponse

enum v1OrganizationResponseType

{} v1PreferredSailing

{} v1PreferredSailingDetails

{} v1SeaTracking

{} v1SeaTrackingEvent

enum v1SeaTrackingEventType

{} v1SeaTrackingLocation

{} ShipmentDocumentResponse

{} v1ShipmentFilter

enum v1ShipmentOrderBy

{} ShipmentResponse

enum v1ShipmentResponseStatus

{} v1ShippedContainer