Skip to content
MothershipDevelopers

API referenceInvoices

Retrieve an invoice

Retrieves an invoice.

GET/invoices/{invoiceId}
Environment
https://sandbox.api.mothership.com/beta
curl --request GET \
  --url 'https://sandbox.api.mothership.com/beta/invoices/9b2e6d41-0c7a-4f3e-8d15-6a4c2e9f1b70' \
  --header "Authorization: Bearer $MOTHERSHIP_API_TOKEN" \
  --header 'Accept: application/json'
Reads your token from $MOTHERSHIP_API_TOKEN
Response
{
: {
: "3f1c2a9e-5b7d-4e8a-9c61-2d4f8b0e7a15",
: "2026-03-19T17:00:00.000Z",
: "2026-03-19T17:00:00.000Z",
: "2026-04-18",
: 1,
: 1,
: [
{
: "3f1c2a9e-5b7d-4e8a-9c61-2d4f8b0e7a15",
: "2026-03-19T17:00:00.000Z",
: 1
}
],
: [
{
: 2,
: "additional",
: 7900,
: 7900,
: 7900,
: 7900,
: "T-shirts"
}
],
: [
{
: "3f1c2a9e-5b7d-4e8a-9c61-2d4f8b0e7a15",
: "2026-03-19T17:00:00.000Z",
: 1
}
],
: "usd",
: "open",
: "PO-1042",
: "T-shirts",
: "shipment",
: "3f1c2a9e-5b7d-4e8a-9c61-2d4f8b0e7a15"
}
}

Hover a key to see what it means. Click it to jump to the field.

Invoice statuses

The value of status can be in one of the following states.

StatusDescription
openThe invoice has not been paid, or payment is still processing.
paidThe invoice has been fully paid.
unpaidListed in the spec for compatibility. The API does not return it today.
pastDueThe invoice is not fully paid and past its due date.
voidThe invoice has been voided and is not due for payment, nor has been paid previously.

Each line item's type is listed in Invoice line items. Line item amounts are in cents.

Authorization

Authorization: Bearer <token>

Your sandbox API token. See Authentication.

Path parameters

  • invoiceIdstringRequired

    ID of the invoice to fetch

Responses

    • dataobjectRequired
      • idstringRequired

        The ID of the invoice

      • createdAtstringRequired

        When the invoice was created, as an ISO 8601 string.

      • updatedAtstringRequired

        When the invoice was last updated, as an ISO 8601 string.

      • lineItemsarray of objectsRequired

        The individual line items that make up the invoice

      • statusstringRequired

        The status of the invoice

        openpaidunpaidpastDuevoidWhat each value means →
      • referenceNumberstringRequired

        Reference number of the invoice. It is not guaranteed to be unique, or to match the reference number of the entity it belongs to.

      • descriptionstringRequired

        The description of the invoice

      • entityTypestringRequired

        The invoiceable entity type, most commonly 'shipment'. Payment processing fee invoices use 'payment'.

        shipmentclaimstatementpayment
      • entityIdstringRequired

        ID of the entity the invoice is for. For a shipment, the shipment reference number when available. For a payment processing fee invoice, the finance payment UUID.

      • dueDatestring

        When the invoice must be paid by, as an ISO 8601 string.

      • totalnumber

        Invoice total, in US cents.

      • amountDuenumber

        Amount still due on the invoice, in US cents.

      • creditsarray of objects

        The credits applied to the invoice

      • paymentsarray of objects

        The payments applied to the invoice

      • currencystring

        Three-letter ISO currency code, in lowercase. Defaults to 'usd'.

What's next

Invoice line items

What each line item type means.