Create Invoice

Create a new invoice in your InvestGlass system for billing clients and managing accounts receivable.

Overview

The InvestGlass API allows you to programmatically create invoices for your clients, enabling seamless integration with your financial workflows. This endpoint supports creating invoices with multiple line items, tax calculations, and client billing information.

HTTP Request

POST https://app.investglass.com/api/v1/invoices

Authentication

All InvestGlass API requests require authentication using a Bearer token. Include your access token in the request header:

Authorization: Bearer YOUR_ACCESS_TOKEN

To generate an access token, visit your InvestGlass profile settings and create a new API token under the "API Access" section.

Required Permissions

To create invoices, your access token must have the invoices:write permission scope.

Request Body

The create invoice endpoint accepts a JSON payload with the following structure:

Invoice Object

Parameter	Type	Required	Description
`title`	string	Yes	Invoice title or number
`client_id`	integer	Yes	ID of the client contact from your InvestGlass CRM
`due_date`	string	No	Invoice due date (ISO 8601 format)
`currency`	string	No	Invoice currency (defaults to account currency)
`tax_rate`	decimal	No	Tax rate as a percentage (e.g., 8.5 for 8.5% tax)
`notes`	string	No	Additional notes for the invoice
`positions`	array	Yes	Array of line items (see Position Object below)

Position Object

Each line item in the positions array should contain:

Parameter	Type	Required	Description
`description`	string	Yes	Description of the service or product
`quantity`	decimal	Yes	Quantity of items
`unit_price`	decimal	Yes	Price per unit
`tax_rate`	decimal	No	Tax rate for this line item (overrides invoice tax rate)

Example Request

{
  "title": "Investment Advisory Services - Q4 2024",
  "client_id": 12345,
  "due_date": "2024-12-31T23:59:59Z",
  "currency": "USD",
  "tax_rate": 8.5,
  "notes": "Quarterly advisory services and portfolio management",
  "positions": [
    {
      "description": "Portfolio Management Services",
      "quantity": 1,
      "unit_price": 2500.00,
      "tax_rate": 8.5
    },
    {
      "description": "Financial Planning Consultation",
      "quantity": 4,
      "unit_price": 350.00,
      "tax_rate": 8.5
    }
  ]
}

Response

Success Response (201 Created)

{
  "id": 78901,
  "invoice_number": "INV-2024-001",
  "title": "Investment Advisory Services - Q4 2024",
  "client_id": 12345,
  "client_name": "John Smith",
  "status": "draft",
  "subtotal": 3900.00,
  "tax_amount": 331.50,
  "total_amount": 4231.50,
  "currency": "USD",
  "due_date": "2024-12-31T23:59:59Z",
  "created_at": "2024-10-15T14:30:22Z",
  "updated_at": "2024-10-15T14:30:22Z",
  "positions": [
    {
      "id": 1001,
      "description": "Portfolio Management Services",
      "quantity": 1.0,
      "unit_price": 2500.00,
      "line_total": 2500.00,
      "tax_rate": 8.5,
      "tax_amount": 212.50
    },
    {
      "id": 1002,
      "description": "Financial Planning Consultation",
      "quantity": 4.0,
      "unit_price": 350.00,
      "line_total": 1400.00,
      "tax_rate": 8.5,
      "tax_amount": 119.00
    }
  ]
}

Error Response (400 Bad Request)

{
  "error": "validation_failed",
  "message": "The request contains invalid parameters",
  "details": {
    "client_id": ["Client not found"],
    "positions": ["At least one position is required"]
  }
}

Invoice Statuses

Created invoices start with a status of draft and can be transitioned through the following states:

draft - Invoice is created but not yet sent
sent - Invoice has been sent to the client
partial - Invoice is partially paid
paid - Invoice is fully paid
overdue - Invoice is past due date and unpaid
cancelled - Invoice has been cancelled

Code Examples

cURL

curl -X POST https://app.investglass.com/api/v1/invoices \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Investment Advisory Services - Q4 2024",
    "client_id": 12345,
    "due_date": "2024-12-31T23:59:59Z",
    "currency": "USD",
    "tax_rate": 8.5,
    "positions": [
      {
        "description": "Portfolio Management Services",
        "quantity": 1,
        "unit_price": 2500.00
      }
    ]
  }'

Python

import requests
import json

url = "https://app.investglass.com/api/v1/invoices"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}

invoice_data = {
    "title": "Investment Advisory Services - Q4 2024",
    "client_id": 12345,
    "due_date": "2024-12-31T23:59:59Z",
    "currency": "USD",
    "tax_rate": 8.5,
    "positions": [
        {
            "description": "Portfolio Management Services",
            "quantity": 1,
            "unit_price": 2500.00
        }
    ]
}

response = requests.post(url, headers=headers, json=invoice_data)
if response.status_code == 201:
    invoice = response.json()
    print(f"Invoice created with ID: {invoice['id']}")
else:
    print(f"Error creating invoice: {response.text}")

JavaScript

const createInvoice = async () => {
  try {
    const response = await fetch('https://app.investglass.com/api/v1/invoices', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        title: 'Investment Advisory Services - Q4 2024',
        client_id: 12345,
        due_date: '2024-12-31T23:59:59Z',
        currency: 'USD',
        tax_rate: 8.5,
        positions: [
          {
            description: 'Portfolio Management Services',
            quantity: 1,
            unit_price: 2500.00
          }
        ]
      })
    });

    if (response.ok) {
      const invoice = await response.json();
      console.log('Invoice created:', invoice.id);
    } else {
      console.error('Error creating invoice:', await response.text());
    }
  } catch (error) {
    console.error('Request failed:', error);
  }
};

Related Endpoints

List Invoices - Retrieve all invoices
Get Invoice - Get a specific invoice by ID
Update Invoice - Update an existing invoice
Delete Invoice - Delete a draft invoice
Send Invoice - Send an invoice to a client

Best Practices

Always validate client IDs before creating invoices to ensure they exist in your InvestGlass system
Use descriptive titles that help both you and your clients identify the invoice purpose
Set appropriate due dates based on your billing terms and client agreements
Include detailed position descriptions to provide clarity on charges
Test with small amounts before implementing in production systems