Invoices

Invoices represent billable requests for payment from your clients. The invoices API allows you to create and manage invoice records.

List Invoices

GET /api/invoices

Description: Retrieves a paginated list of invoices. Supports filtering by status and search by invoice number or client name.

Authorization: API Key (Bearer Token) required.

Query Parameters:

Name
page
Type
integer
Description
Page number for pagination.
Name
limit
Type
integer
Description
Number of invoices per page.
Name
sortBy
Type
string
Description
Field to sort by (e.g., createdAt, dueDate).
Name
sortOrder
Type
string
Description
Sort order (asc or desc).
Name
status
Type
string
Description
Filter by invoice status (draft, sent, paid, overdue, cancelled, all).
Name
search
Type
string
Description
Search term for invoice number or client name.

Request

curl -X GET "https://your-summit-instance.com/api/invoices?status=paid&limit=5" \
     -H "Authorization: Bearer <YOUR_API_TOKEN>"

Response (Success: 200 OK)

{
  "data": [
    {
      "id": 1,
      "companyId": 1,
      "clientId": 1,
      "invoiceNumber": "INV-2023-001",
      "status": "paid",
      "issueDate": "2023-10-01",
      "dueDate": "2023-10-31",
      "subtotal": "100.00",
      "tax": "10.00",
      "taxRate": "10.00",
      "total": "110.00",
      "notes": "Payment for services rendered.",
      "currency": "IDR",
      "xenditInvoiceId": "xendit_inv_123",
      "xenditInvoiceUrl": "https://xendit.co/invoice/...",
      "recurring": "none",
      "nextDueDate": null,
      "createdAt": "2023-10-01T10:00:00.000Z",
      "updatedAt": "2023-10-15T14:30:00.000Z",
      "paidAt": "2023-10-15T14:30:00.000Z",
      "softDelete": false,
      "client": {
        "id": 1,
        "name": "Client Alpha",
        "email": "[email protected]"
      },
      "items": [
        {
          "id": 1,
          "invoiceId": 1,
          "description": "Web Development Service",
          "quantity": "10.00",
          "unitPrice": "10.00",
          "amount": "100.00",
          "createdAt": "2023-10-01T10:00:00.000Z",
          "updatedAt": "2023-10-01T10:00:00.000Z"
        }
      ]
    }
  ],
  "total": 1, // Matches the top-level total in README, not meta.total
  "page": 1,
  "limit": 5,
  "totalPages": 1
}

Create Invoice

POST /api/invoices

Description: Creates a new invoice. The subtotal, tax, and total will be calculated based on the items and taxRate provided. tax in the request body is ignored, use taxRate.

Authorization: API Key (Bearer Token) required.

Request Body: application/json

Name
clientId
Type
integer
Description
ID of the client.
Name
invoiceNumber
Type
string
Description
Unique invoice number.
Name
status
Type
string
Description
Invoice status (draft, sent, paid, overdue, cancelled).
Name
issueDate
Type
string
Description
Issue date (YYYY-MM-DD).
Name
dueDate
Type
string
Description
Due date (YYYY-MM-DD).
Name
taxRate
Type
number
Description
Tax rate as a percentage (e.g., 10 for 10%).
Name
notes
Type
string
Description
Additional notes for the invoice.
Name
currency
Type
string
Description
Currency code (e.g., IDR, USD).
Name
items
Type
array
Description
Array of invoice items.

Invoice Items (items[]):

Name
description
Type
string
Description
Description of the item.
Name
quantity
Type
number
Description
Quantity of the item.
Name
unitPrice
Type
string
Description
Unit price of the item (as string, e.g., "100.00").

Request

curl -X POST "https://your-summit-instance.com/api/invoices" \
     -H "Authorization: Bearer <YOUR_API_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
       "clientId": 1,
       "invoiceNumber": "INV-2023-002",
       "status": "draft",
       "issueDate": "2023-11-01",
       "dueDate": "2023-11-30",
       "taxRate": 10,
       "notes": "Design services for November.",
       "items": [
         {
           "description": "Logo Design",
           "quantity": 1,
           "unitPrice": "500.00"
         },
         {
           "description": "Website Mockup",
           "quantity": 2,
           "unitPrice": "250.00"
         }
       ]
     }'

Response (Success: 201 Created)

{
  "id": 2,
  "companyId": 1,
  "clientId": 1,
  "invoiceNumber": "INV-2023-002",
  "status": "draft",
  "issueDate": "2023-11-01T00:00:00.000Z",
  "dueDate": "2023-11-30T00:00:00.000Z",
  "subtotal": "1000.00",
  "tax": "100.00",
  "taxRate": "10.00",
  "total": "1100.00",
  "notes": "Design services for November.",
  "currency": "IDR",
  "xenditInvoiceId": null,
  "xenditInvoiceUrl": null,
  "recurring": "none",
  "nextDueDate": null,
  "createdAt": "2023-10-27T15:00:00.000Z",
  "updatedAt": "2023-10-27T15:00:00.000Z",
  "paidAt": null,
  "softDelete": false,
  "client": {
    "id": 1,
    "name": "Client Alpha",
    "email": "[email protected]"
  },
  "items": [
    {
      "id": 2,
      "invoiceId": 2,
      "description": "Logo Design",
      "quantity": "1.00",
      "unitPrice": "500.00",
      "amount": "500.00"
    },
    {
      "id": 3,
      "invoiceId": 2,
      "description": "Website Mockup",
      "quantity": "2.00",
      "unitPrice": "250.00",
      "amount": "500.00"
    }
  ]
}

Get Invoice Details

GET /api/invoices/{invoiceId}

Description: Retrieves the details of a specific invoice, including its items and client information.

Authorization: API Key (Bearer Token) required.

Path Parameters:

Name
invoiceId
Type
integer
Description
ID of the invoice to retrieve.

Request

curl -X GET "https://your-summit-instance.com/api/invoices/2" \
     -H "Authorization: Bearer <YOUR_API_TOKEN>"

Response (Success: 200 OK)

{
  "id": 2,
  "companyId": 1,
  "clientId": 1,
  "invoiceNumber": "INV-2023-002",
  "status": "draft",
  "issueDate": "2023-11-01T00:00:00.000Z",
  "dueDate": "2023-11-30T00:00:00.000Z",
  "subtotal": "1000.00",
  "tax": "100.00",
  "taxRate": "10.00",
  "total": "1100.00",
  "notes": "Design services for November.",
  "currency": "IDR",
  "xenditInvoiceId": null,
  "xenditInvoiceUrl": null,
  "recurring": "none",
  "nextDueDate": null,
  "createdAt": "2023-10-27T15:00:00.000Z",
  "updatedAt": "2023-10-27T15:00:00.000Z",
  "paidAt": null,
  "softDelete": false,
  "client": {
    "id": 1,
    "name": "Client Alpha",
    "email": "[email protected]"
  },
  "items": [
    {
      "id": 2,
      "invoiceId": 2,
      "description": "Logo Design",
      "quantity": "1.00",
      "unitPrice": "500.00",
      "amount": "500.00"
    },
    {
      "id": 3,
      "invoiceId": 2,
      "description": "Website Mockup",
      "quantity": "2.00",
      "unitPrice": "250.00",
      "amount": "500.00"
    }
  ]
}

Update Invoice

PUT /api/invoices/{invoiceId}

Description: Updates an existing invoice. The subtotal, tax, and total will be recalculated based on the provided items and taxRate.

Authorization: API Key (Bearer Token) required.

Path Parameters:

Name
invoiceId
Type
integer
Description
ID of the invoice to update.

Request Body: application/json (Same structure as Create Invoice. All fields are optional for an update; only provided fields will be changed.)

Request

curl -X PUT "https://your-summit-instance.com/api/invoices/2" \
     -H "Authorization: Bearer <YOUR_API_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
       "clientId": 1,
       "invoiceNumber": "INV-2023-002-MOD",
       "status": "sent",
       "issueDate": "2023-11-01",
       "dueDate": "2023-12-15",
       "taxRate": 11,
       "notes": "Updated design services.",
       "items": [
         {
           "description": "Logo Design Revision",
           "quantity": 1,
           "unitPrice": "550.00"
         }
       ]
     }'

Response (Success: 200 OK)

// Similar to Create Invoice response, with updated fields and recalculated totals.
// Example (actual response will vary based on what was updated):
{
  "id": 2,
  "companyId": 1,
  "clientId": 1,
  "invoiceNumber": "INV-2023-002-MOD",
  "status": "sent",
  "issueDate": "2023-11-01T00:00:00.000Z",
  "dueDate": "2023-12-15T00:00:00.000Z",
  "subtotal": "550.00", // Recalculated
  "tax": "60.50",      // Recalculated (550 * 0.11)
  "taxRate": "11.00",
  "total": "610.50",   // Recalculated
  "notes": "Updated design services.",
  "currency": "IDR", // Assuming currency wasn't changed
  "xenditInvoiceId": null, // Assuming not affected by this update
  "xenditInvoiceUrl": null,
  "recurring": "none",
  "nextDueDate": null,
  "createdAt": "2023-10-27T15:00:00.000Z", // Original creation date
  "updatedAt": "2023-10-27T18:00:00.000Z", // New update timestamp
  "paidAt": null,
  "softDelete": false,
  "client": {
    "id": 1,
    "name": "Client Alpha",
    "email": "[email protected]"
  },
  "items": [
    {
      "id": 4, // Assuming new/updated item ID
      "invoiceId": 2,
      "description": "Logo Design Revision",
      "quantity": "1.00",
      "unitPrice": "550.00",
      "amount": "550.00"
    }
  ]
}

Delete Invoice

DELETE /api/invoices/{invoiceId}

Description: Soft deletes an invoice.

Authorization: API Key (Bearer Token) required.

Path Parameters:

Name
invoiceId
Type
integer
Description
ID of the invoice to delete.

Request

curl -X DELETE "https://your-summit-instance.com/api/invoices/2" \
     -H "Authorization: Bearer <YOUR_API_TOKEN>"

Response (Success: 200 OK)

{
  "message": "Invoice deleted successfully"
}

Send Invoice Email

POST /api/invoices/{invoiceId}/send-email

Description: Sends the specified invoice to the client via email. If the invoice status is draft, it will be updated to sent.

Authorization: API Key (Bearer Token) required.

Path Parameters:

Name
invoiceId
Type
integer
Description
ID of the invoice to send.

Error Responses:

400 Bad Request: If the client has no email address.
404 Not Found: If the invoice or sender information is not found.

Request

curl -X POST "https://your-summit-instance.com/api/invoices/1/send-email" \
     -H "Authorization: Bearer <YOUR_API_TOKEN>"

Response (Success: 200 OK)

{
  "message": "Email sent successfully",
  "data": { "id": "resend_email_id" }
}

Create Xendit Payment Link for Invoice

POST /api/invoices/{invoiceId}/create-xendit-invoice

Description: Generates a Xendit payment link for the specified invoice and updates the invoice record with the Xendit invoice ID and URL.

Authorization: API Key (Bearer Token) required.

Path Parameters:

Name
invoiceId
Type
integer
Description
ID of the invoice to create a payment link for.

Request Body (Optional): application/json

Name
regenerate
Type
boolean
Description
Set to true to force regeneration of the link.

Error Responses:

404 Not Found: If the invoice does not exist.

Request

curl -X POST "https://your-summit-instance.com/api/invoices/1/create-xendit-invoice" \
     -H "Authorization: Bearer <YOUR_API_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
       "regenerate": false
     }' # Optional body

Response (Success: 200 OK)

{
  "message": "Xendit payment link created successfully",
  "xenditInvoiceUrl": "https://checkout.xendit.co/web/invoices/inv_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "invoice": {
    "id": 1,
    "companyId": 1,
    "clientId": 1,
    "invoiceNumber": "INV-2023-001",
    "status": "sent", // Status might change to sent if not already
    "issueDate": "2023-10-01T00:00:00.000Z",
    "dueDate": "2023-10-31T00:00:00.000Z",
    "total": "110.00",
    "subtotal": "100.00",
    "taxAmount": "10.00", // Note: README uses taxAmount here, but tax in other responses
    "currency": "IDR",
    "notes": "Payment for services rendered.",
    "xenditInvoiceId": "inv_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "xenditInvoiceUrl": "https://checkout.xendit.co/web/invoices/inv_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "createdAt": "2023-10-01T10:00:00.000Z",
    "updatedAt": "2023-10-27T16:00:00.000Z",
    "softDelete": false
  }
}

Download Invoice PDF

GET /api/invoices/{invoiceId}/pdf

Description: Generates and downloads a PDF version of the specified invoice.

Authorization: API Key (Bearer Token) required.

Path Parameters:

Name
invoiceId
Type
integer
Description
ID of the invoice to download.

Request

curl -X GET "https://your-summit-instance.com/api/invoices/1/pdf" \
     -H "Authorization: Bearer <YOUR_API_TOKEN>" \
     -o invoice-001.pdf

Response (Success: 200 OK): The response body will be the PDF file.

Content-Type: application/pdf
Content-Disposition: attachment; filename="invoice-INV-XXXX.pdf"