Invoices

Create and manage customer invoices

Overview

Invoices track billing for services rendered. They can contain multiple line items, apply taxes, and integrate with QuickBooks for accounting. Invoices support various payment statuses and can be exported for reporting.

List Invoices

Retrieve a paginated list of invoices with filtering.

query InfiniteInvoices($first: Int!, $after: String, $filter: InvoiceFilter) {
  infiniteInvoices(first: $first, after: $after, filter: $filter) {
    edges {
      node {
        id
        number
        status
        total
        balance
        dueDate
        customer {
          id
          firstName
          lastName
        }
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# Variables
{
  "first": 20,
  "filter": {
    "status": "SENT",
    "dueDateLte": "2024-02-01T00:00:00Z"
  }
}

Response:

{
  "data": {
    "infiniteInvoices": {
      "edges": [
        {
          "node": {
            "id": "inv_001",
            "number": "INV-2024-0001",
            "status": "SENT",
            "total": 150.00,
            "balance": 150.00,
            "dueDate": "2024-01-31T00:00:00Z",
            "customer": {
              "id": "cust_456",
              "firstName": "John",
              "lastName": "Smith"
            }
          },
          "cursor": "eyJpZCI6Imludl8wMDEifQ=="
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "eyJpZCI6Imludl8wMDEifQ=="
      }
    }
  }
}

Get Single Invoice

Retrieve a single invoice with all details.

query Invoice($selector: InvoiceSelector!) {
  invoice(selector: $selector) {
    id
    number
    status
    subtotal
    tax
    total
    paidAmount
    balance
    dueDate
    paidAt
    customer {
      id
      firstName
      lastName
      email
    }
    lineItems {
      id
      description
      quantity
      unitPrice
      amount
      service {
        id
        name
      }
    }
    notes
    quickbooksId
    createdAt
    updatedAt
  }
}

# Variables
{
  "selector": {
    "id": "inv_001"
  }
}

Response:

{
  "data": {
    "invoice": {
      "id": "inv_001",
      "number": "INV-2024-0001",
      "status": "SENT",
      "subtotal": 137.61,
      "tax": 12.39,
      "total": 150.00,
      "paidAmount": 0,
      "balance": 150.00,
      "dueDate": "2024-01-31T00:00:00Z",
      "paidAt": null,
      "customer": {
        "id": "cust_456",
        "firstName": "John",
        "lastName": "Smith",
        "email": "john@example.com"
      },
      "lineItems": [
        {
          "id": "li_001",
          "description": "Weekly Pool Cleaning - January",
          "quantity": 2,
          "unitPrice": 75.00,
          "amount": 150.00,
          "service": {
            "id": "svc_001",
            "name": "Pool Cleaning"
          }
        }
      ],
      "notes": "Thank you for your business!",
      "quickbooksId": "QB-INV-12345",
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-15T10:00:00Z"
    }
  }
}

Create Invoice

Create a new invoice for a customer.

mutation CreateInvoice($input: CreateInvoiceInput!) {
  createInvoice(input: $input) {
    id
    number
    status
    total
    customer {
      id
      firstName
      lastName
    }
    createdAt
  }
}

# Variables
{
  "input": {
    "customerId": "cust_456",
    "dueDate": "2024-02-15T00:00:00Z",
    "lineItems": [
      {
        "description": "Pool Repair - Filter Replacement",
        "quantity": 1,
        "unitPrice": 250.00,
        "serviceId": "svc_002"
      }
    ],
    "taxId": "tax_001",
    "notes": "Parts and labor included"
  }
}

Response:

{
  "data": {
    "createInvoice": {
      "id": "inv_002",
      "number": "INV-2024-0002",
      "status": "DRAFT",
      "total": 271.25,
      "customer": {
        "id": "cust_456",
        "firstName": "John",
        "lastName": "Smith"
      },
      "createdAt": "2024-01-20T09:00:00Z"
    }
  }
}

Record Payment

Record a payment against an invoice.

mutation PayInvoice($id: ID!, $input: PayInvoiceInput!) {
  payInvoice(id: $id, input: $input) {
    id
    status
    paidAmount
    balance
    paidAt
  }
}

# Variables
{
  "id": "inv_001",
  "input": {
    "amount": 150.00,
    "paymentMethod": "CREDIT_CARD",
    "reference": "txn_abc123"
  }
}

Response:

{
  "data": {
    "payInvoice": {
      "id": "inv_001",
      "status": "PAID",
      "paidAmount": 150.00,
      "balance": 0,
      "paidAt": "2024-01-20T15:00:00Z"
    }
  }
}

REST Endpoints

Export invoices to CSV format.

GET/invoices/export/csv

Export invoices to CSV format

curl -X GET "https://api.poolservicemanager.com/invoices/export/csv?startDate=2024-01-01&endDate=2024-01-31&status=PAID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o invoices.csv

Field Reference

Field	Type	Description
`id`	`ID!`	Unique identifier
`number`	`String!`	Invoice number
`customer`	`Customer!`	Customer being billed
`status`	`InvoiceStatus!`	Status (DRAFT, SENT, PAID, OVERDUE, CANCELLED)
`subtotal`	`Float!`	Subtotal before tax
`tax`	`Float!`	Tax amount
`total`	`Float!`	Total amount due
`paidAmount`	`Float!`	Amount paid
`balance`	`Float!`	Remaining balance
`dueDate`	`DateTime!`	Payment due date
`paidAt`	`DateTime`(nullable)	When invoice was paid
`lineItems`	`[InvoiceLineItem!]!`	Invoice line items
`notes`	`String`(nullable)	Invoice notes
`quickbooksId`	`String`(nullable)	QuickBooks invoice ID
`createdAt`	`DateTime!`	Creation timestamp
`updatedAt`	`DateTime!`	Last update timestamp