Invoices

scope: invoices

Read-only access to your organization's invoices. View invoice details, line items, totals, and payment status. All monetary amounts are returned in cents alongside an ISO 4217 currency code (currently USD).

Endpoints

GET

/v0/invoices

List all invoices (paginated, filterable by status)

GET

/v0/invoices/:id

Get a single invoice with line items

Invoice Statuses

Invoices progress through several statuses. Internal states like draft and accumulating are not exposed through the API — you only see invoices that have been finalized and sent.

Status	Description	Action Required?
`unpaid`	Invoice has been sent and is awaiting payment.	Yes
`pending_payment`	A payment has been submitted and is being processed.	No
`paid`	Invoice has been fully paid. Terminal state.	No
`cancelled`	Invoice was cancelled. No payment needed. Terminal state.	No
`refunded`	Payment was received but has been refunded to your balance.	No
`collecting`	Invoice is overdue and has been forwarded to collections.	Urgent

List Invoices

Returns a paginated list of all invoices for your organization. Use the query parameters to filter by status or search across invoice details and line items.

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status: unpaid, pending_payment, paid, cancelled, refunded, collecting
`search`	string	Search by invoice ID, invoice key, name, notes, line item titles, or line item descriptions
`sortBy`	string	Sort field: createdAt, updatedAt, dueDate (default: createdAt)
`sortOrder`	string	Sort direction: asc or desc (default: desc)
`skip`	number	Number of records to skip (default: 0)
`take`	number	Number of records to return (default: 10, max: 10)

GET /v0/invoices?status=unpaid&sortBy=dueDate&sortOrder=asc

[
  {
    "id": "5",
    "status": "unpaid",
    "name": "Outbound Shipment #22",
    "notes": "",
    "dueDate": "2026-03-10T00:00:00.000Z",
    "items": [
      {
        "id": "12",
        "title": "Pick & Pack Labor",
        "description": "50 units picked and packed",
        "quantity": 50,
        "unitCost": 25,
        "totalCost": 1250
      },
      {
        "id": "13",
        "title": "Shipping Materials",
        "description": "Boxes and tape",
        "quantity": 1,
        "unitCost": 500,
        "totalCost": 500
      }
    ],
    "totalAmount": 1750,
    "currency": "USD",
    "createdAt": "2026-03-04T10:00:00.000Z",
    "updatedAt": "2026-03-04T10:00:00.000Z",
    "deletedAt": null
  }
]

Get Invoice

Retrieve a single invoice by its ID. Returns 404 if the invoice does not exist or belongs to another organization.

GET /v0/invoices/5

{
  "id": "5",
  "status": "unpaid",
  "name": "Outbound Shipment #22",
  "notes": "",
  "dueDate": "2026-03-10T00:00:00.000Z",
  "items": [
    {
      "id": "12",
      "title": "Pick & Pack Labor",
      "description": "50 units picked and packed",
      "quantity": 50,
      "unitCost": 25,
      "totalCost": 1250
    },
    {
      "id": "13",
      "title": "Shipping Materials",
      "description": "Boxes and tape",
      "quantity": 1,
      "unitCost": 500,
      "totalCost": 500
    }
  ],
  "totalAmount": 1750,
  "currency": "USD",
  "createdAt": "2026-03-04T10:00:00.000Z",
  "updatedAt": "2026-03-04T10:00:00.000Z",
  "deletedAt": null
}

Response Fields

Parameter	Type	Description
`id`*	string	Unique invoice ID
`status`*	enum	Current invoice status (see status table above)
`name`*	string	Invoice description (e.g. "Outbound Shipment #22")
`notes`*	string	Additional notes on the invoice
`dueDate`*	ISO 8601	Payment due date
`items`*	array	Line items on this invoice
`items[].id`*	string	Line item ID
`items[].title`*	string	Line item title (e.g. "Pick & Pack Labor")
`items[].description`*	string	Detailed description of the charge
`items[].quantity`*	number	Number of units billed
`items[].unitCost`*	int64	Cost per unit in cents (see Conventions)
`items[].totalCost`*	int64	Line total in cents (quantity × unitCost)
`totalAmount`*	int64	Invoice total in cents (sum of all line item totals)
`currency`*	string	ISO 4217 currency code (currently always "USD")
`createdAt`*	ISO 8601	When the invoice was created
`updatedAt`*	ISO 8601	Last update timestamp
`deletedAt`	ISO 8601 \| null	Timestamp when the invoice was soft-deleted, null if active

Currency & Amounts

All monetary values are 64-bit integers in cents (smallest currency unit). To convert to dollars, divide by 100. The currency field indicates the currency — currently USD. See Conventions for storage and handling guidelines.

API Value (cents)	Display Value
`1750`	$17.50
`25`	$0.25
`100000`	$1,000.00

Error Responses

401Unauthorized

Missing or invalid access token. See Authentication.

403Missing required scope: invoices

Your OAuth token does not have the invoices scope. Request the scope during authorization.

404Invoice not found

The invoice ID does not exist or does not belong to your organization.

Read-only

Invoices are generated by the 3PLGuys system when shipments are processed, services are rendered, or storage fees are calculated. They cannot be created or modified through the API. For billing questions, contact developer@3plguys.com.

Warehouses

Notifications