# Quotes and invoices

> What a shipment was quoted at booking, and what Cubic has invoiced for it.

| Method | Path | Returns |
|---|---|---|
| `GET` | `/v1/shipments/{reference}/quote` | The [quote](#shipmentquote) the shipment was booked on. |
| `GET` | `/v1/shipments/{reference}/invoices` | Every [invoice](#invoice) Cubic has issued to your account for the shipment. |

The quote is the price agreed at booking. The invoices are what is billed: they can add charges the quote did not cover, such as duties, storage or waiting time.

## Rules

- **What a shipment costs** is the sum of `total` over its invoices that are not `Cancelled`.
- **Every amount is a [Money](#money) object.** Read its `currency`; an account can be invoiced in more than one.
- **Paying an invoice does not change the shipment's `updatedAt`.** Read the invoices again for the current `status` and `openBalance`.
- **A shipment booked without a quote** returns `404 quote_not_found`. Do not retry.

## Quote example

```json
{
  "lineItems": [
    {
      "section": "Freight",
      "description": "Ocean Freight",
      "quantity": 2,
      "unit": "PerFortyFtHighCubeContainer",
      "unitPrice": {
        "amount": 2450,
        "currency": "USD"
      },
      "total": {
        "amount": 4900,
        "currency": "USD"
      }
    },
    {
      "section": "Destination",
      "description": "Destination Terminal Handling",
      "quantity": 2,
      "unit": "PerFortyFtHighCubeContainer",
      "unitPrice": {
        "amount": 310,
        "currency": "USD"
      },
      "total": {
        "amount": 620,
        "currency": "USD"
      }
    },
    {
      "section": "Destination",
      "description": "Import Customs Clearance",
      "quantity": 1,
      "unit": "PerShipment",
      "unitPrice": {
        "amount": 95,
        "currency": "USD"
      },
      "total": {
        "amount": 95,
        "currency": "USD"
      }
    },
    {
      "section": "Destination",
      "description": "Delivery",
      "quantity": 2,
      "unit": "PerFortyFtHighCubeContainer",
      "unitPrice": {
        "amount": 540,
        "currency": "USD"
      },
      "total": {
        "amount": 1080,
        "currency": "USD"
      }
    },
    {
      "section": "Other",
      "description": "Insurance",
      "quantity": 1,
      "unit": "PerShipment",
      "unitPrice": {
        "amount": 120,
        "currency": "USD"
      },
      "total": {
        "amount": 120,
        "currency": "USD"
      }
    }
  ],
  "subtotal": {
    "amount": 6815,
    "currency": "USD"
  },
  "discount": null,
  "total": {
    "amount": 6815,
    "currency": "USD"
  },
  "remarks": "Rates exclude UK import duty and VAT.",
  "acceptedAt": "2026-09-16T13:05:00Z"
}
```

## Invoices example

```json
{
  "data": [
    {
      "number": "10482",
      "status": "Paid",
      "issueDate": "2026-09-30",
      "dueDate": "2026-10-30",
      "lineItems": [
        {
          "description": "Ocean Freight",
          "note": null,
          "quantity": 2,
          "unit": "PerFortyFtHighCubeContainer",
          "unitPrice": {
            "amount": 2450,
            "currency": "USD"
          },
          "amount": {
            "amount": 4900,
            "currency": "USD"
          },
          "taxRate": null,
          "tax": {
            "amount": 0,
            "currency": "USD"
          }
        },
        {
          "description": "Insurance",
          "note": null,
          "quantity": 1,
          "unit": "PerShipment",
          "unitPrice": {
            "amount": 120,
            "currency": "USD"
          },
          "amount": {
            "amount": 120,
            "currency": "USD"
          },
          "taxRate": null,
          "tax": {
            "amount": 0,
            "currency": "USD"
          }
        }
      ],
      "openBalance": {
        "amount": 0,
        "currency": "USD"
      },
      "currency": "USD",
      "subtotal": {
        "amount": 5020,
        "currency": "USD"
      },
      "tax": {
        "amount": 0,
        "currency": "USD"
      },
      "total": {
        "amount": 5020,
        "currency": "USD"
      },
      "creditApplied": {
        "amount": 0,
        "currency": "USD"
      }
    },
    {
      "number": "10517",
      "status": "Unpaid",
      "issueDate": "2026-11-10",
      "dueDate": "2026-12-10",
      "lineItems": [
        {
          "description": "Destination Terminal Handling",
          "note": null,
          "quantity": 2,
          "unit": "PerFortyFtHighCubeContainer",
          "unitPrice": {
            "amount": 310,
            "currency": "USD"
          },
          "amount": {
            "amount": 620,
            "currency": "USD"
          },
          "taxRate": null,
          "tax": {
            "amount": 0,
            "currency": "USD"
          }
        },
        {
          "description": "Import Customs Clearance",
          "note": null,
          "quantity": 1,
          "unit": "PerShipment",
          "unitPrice": {
            "amount": 95,
            "currency": "USD"
          },
          "amount": {
            "amount": 95,
            "currency": "USD"
          },
          "taxRate": null,
          "tax": {
            "amount": 0,
            "currency": "USD"
          }
        },
        {
          "description": "Delivery",
          "note": null,
          "quantity": 2,
          "unit": "PerFortyFtHighCubeContainer",
          "unitPrice": {
            "amount": 540,
            "currency": "USD"
          },
          "amount": {
            "amount": 1080,
            "currency": "USD"
          },
          "taxRate": null,
          "tax": {
            "amount": 0,
            "currency": "USD"
          }
        },
        {
          "description": "Storage",
          "note": "Port storage, 2 days beyond the free time",
          "quantity": 2,
          "unit": "PerDay",
          "unitPrice": {
            "amount": 85,
            "currency": "USD"
          },
          "amount": {
            "amount": 170,
            "currency": "USD"
          },
          "taxRate": null,
          "tax": {
            "amount": 0,
            "currency": "USD"
          }
        }
      ],
      "openBalance": {
        "amount": 1965,
        "currency": "USD"
      },
      "currency": "USD",
      "subtotal": {
        "amount": 1965,
        "currency": "USD"
      },
      "tax": {
        "amount": 0,
        "currency": "USD"
      },
      "total": {
        "amount": 1965,
        "currency": "USD"
      },
      "creditApplied": {
        "amount": 0,
        "currency": "USD"
      }
    }
  ]
}
```

## ShipmentQuote

| Field | Type | Description |
|---|---|---|
| `lineItems` | [QuoteLineItem](#quotelineitem)[] | The quoted charges, in the order the Cubic app lists them. Charges included in another charge are not listed. |
| `subtotal` | [Money](#money) | The quoted price before any discount. Always USD; charges quoted in another currency are converted at the current exchange rate, so it can move from one read to the next. It can be more than the sum of `lineItems` when the price includes a charge that is not itemised. |
| `discount` | [Money](#money) \| null | A promotional discount, as a negative USD amount. `null` when there is none. |
| `total` | [Money](#money) | The quoted price: `subtotal` plus `discount`. Always USD. |
| `remarks` | string \| null | Terms and conditions written on the quote, such as what the price excludes. `null` when there are none. |
| `acceptedAt` | string \| null | When the quote was accepted. ISO 8601, UTC. `null` on quotes accepted before December 2025. |

### QuoteLineItem

| Field | Type | Description |
|---|---|---|
| `section` | string | Which part of the journey the charge belongs to. The Cubic app groups the breakdown by it. Values: `Origin`, `Freight`, `Destination`, `Customs`, `Other`. |
| `description` | string | Name of the charge. |
| `quantity` | number | How many `unit`s are charged. Can be fractional, for example for weights. |
| `unit` | string | What one unit of `quantity` is. `PerShipment`: once for the shipment. `PerAllContainersCount`: per container of any size. `PerTeu`: per twenty-foot equivalent unit. `PerChargeableWeight`: per kg of chargeable weight. `PerCwt`: per hundredweight (100 lb). `MaximumWeightOrMeasurement`: per revenue ton, the greater of cubic metres and metric tons. The other values name what they count. Values: `PerShipment`, `PerAllContainersCount`, `PerTwentyFtContainer`, `PerFortyFtContainer`, `PerFortyFtHighCubeContainer`, `PerFortyFtTempControlContainer`, `PerFortyFiveFtHighCubeContainer`, `PerTeu`, `PerChargeableWeight`, `PerKg`, `PerCwt`, `PerCBM`, `MaximumWeightOrMeasurement`, `PerPallet`, `PerCarton`, `PerHour`, `PerDay`. |
| `unitPrice` | [Money](#money) | Price of one `unit`. |
| `total` | [Money](#money) | `unitPrice` times `quantity`, rounded to the cent. |

## Invoice

| Field | Type | Description |
|---|---|---|
| `number` | string | Invoice number, as printed on the invoice. |
| `status` | string | `Unpaid`: not paid yet; it is overdue once `dueDate` has passed. `Scheduled`: a payment is scheduled. `Paid`: paid. `PartiallyCredited`: part of it was settled with a credit note and the rest is unpaid. `Credited`: settled in full with credit notes. `Cancelled`: voided; it is not owed and does not count towards the shipment's cost. Values: `Unpaid`, `Scheduled`, `Paid`, `PartiallyCredited`, `Credited`, `Cancelled`. |
| `issueDate` | string | Issue date, `yyyy-MM-dd`. |
| `dueDate` | string | Due date, `yyyy-MM-dd`. |
| `currency` | string | ISO 4217 currency code. Values: `USD`, `EUR`, `GBP`, `CAD`, `ILS`, `AUD`, `JPY`, `CNY`, `HKD`, `INR`, `KRW`, `SGD`, `THB`, `TWD`, `VND`. |
| `lineItems` | [InvoiceLineItem](#invoicelineitem)[] | The charges on the invoice, as printed on it. |
| `subtotal` | [Money](#money) | Sum of the line `amount`s, before tax. |
| `tax` | [Money](#money) | Sum of the line `tax`es. |
| `total` | [Money](#money) | `subtotal` plus `tax`: the invoiced amount. |
| `creditApplied` | [Money](#money) | Credit notes applied to this invoice. |
| `openBalance` | [Money](#money) | What is still to be paid. `0` once the invoice is paid, credited or cancelled. |

### InvoiceLineItem

| Field | Type | Description |
|---|---|---|
| `description` | string | Name of the charge. |
| `note` | string \| null | Text printed under the charge on the invoice. `null` when there is none. |
| `quantity` | number | How many `unit`s are charged. Can be fractional. |
| `unit` | string | What one unit of `quantity` is. `PerShipment`: once for the shipment. `PerAllContainersCount`: per container of any size. `PerTeu`: per twenty-foot equivalent unit. `PerChargeableWeight`: per kg of chargeable weight. `PerCwt`: per hundredweight (100 lb). `MaximumWeightOrMeasurement`: per revenue ton, the greater of cubic metres and metric tons. The other values name what they count. Values: `PerShipment`, `PerAllContainersCount`, `PerTwentyFtContainer`, `PerFortyFtContainer`, `PerFortyFtHighCubeContainer`, `PerFortyFtTempControlContainer`, `PerFortyFiveFtHighCubeContainer`, `PerTeu`, `PerChargeableWeight`, `PerKg`, `PerCwt`, `PerCBM`, `MaximumWeightOrMeasurement`, `PerPallet`, `PerCarton`, `PerHour`, `PerDay`. |
| `unitPrice` | [Money](#money) | Price of one `unit`, before tax. |
| `amount` | [Money](#money) | `unitPrice` times `quantity`, rounded to the cent, before tax. |
| `taxRate` | number \| null | Tax rate as a fraction, for example `0.18` for 18% VAT. `null` when no tax is charged. |
| `tax` | [Money](#money) | Tax on `amount`, rounded to the cent. `0` when none. |

## Money

| Field | Type | Description |
|---|---|---|
| `amount` | number | Amount in `currency`, in major units (dollars, not cents). Totals have at most 2 decimals; unit prices up to 4. |
| `currency` | string | ISO 4217 currency code. Values: `USD`, `EUR`, `GBP`, `CAD`, `ILS`, `AUD`, `JPY`, `CNY`, `HKD`, `INR`, `KRW`, `SGD`, `THB`, `TWD`, `VND`. |