Invoice Endpoints

Overview

The Invoices API allows you to manage invoices programmatically. Invoices represent sales documents issued to customers, with support for payments, taxes, discounts, and multi-currency.

Invoice Object

The invoice object contains the following fields:

integer

Unique identifier for the invoice

workspace_id

integer

ID of the workspace this invoice belongs to

contact_id

integer

ID of the customer contact

document_subtype_id

integer

ID of the document subtype (determines NCF format for Dominican Republic)

document_number

string

Invoice number (e.g., “INV-0001”, “B0100000001”)

issue_date

date

Date the invoice was issued (YYYY-MM-DD)

due_date

date

Payment due date (YYYY-MM-DD)

status

enum

Invoice status: pending_payment, partially_paid, paid, cancelled, draft

subtotal_amount

decimal

Subtotal before taxes and discounts

tax_amount

decimal

Total tax amount

discount_amount

decimal

Total discount amount

total_amount

decimal

Final total amount

amount_due

decimal

Outstanding balance (total_amount - amount_paid)

amount_paid

decimal

Total amount paid toward this invoice

currency_id

integer

Currency for this invoice

payment_term

string

Payment terms (e.g., “Net 30”, “Due on Receipt”)

notes

string

Additional notes or terms and conditions

items

array

Array of invoice line items

payments

array

Array of payments applied to this invoice

salesmen

array

Array of salesmen associated with this invoice

created_at

timestamp

Creation timestamp

updated_at

timestamp

Last update timestamp

List Invoices

Retrieve a paginated list of invoices.

Query Parameters

page

integer

default:"1"

Page number for pagination

per_page

integer

default:"15"

Number of items per page (max 100)

filter[status]

string

Filter by invoice status: pending_payment, paid, partially_paid, cancelled

filter[contact_id]

integer

Filter by customer contact ID

filter[issue_date]

date

Filter by issue date (YYYY-MM-DD)

sort

string

default:"-issue_date"

Sort field (prefix with - for descending). Options: issue_date, document_number, total_amount

Response

{
  "data": [
    {
      "id": 1,
      "workspace_id": 2,
      "contact_id": 45,
      "document_subtype_id": 3,
      "document_number": "B0100000001",
      "issue_date": "2024-03-15",
      "due_date": "2024-04-14",
      "status": "pending_payment",
      "subtotal_amount": "1250.00",
      "tax_amount": "225.00",
      "discount_amount": "0.00",
      "total_amount": "1475.00",
      "amount_due": "1475.00",
      "amount_paid": "0.00",
      "currency_id": 1,
      "payment_term": "Net 30",
      "notes": "Terms and conditions apply",
      "created_at": "2024-03-15T10:30:00Z",
      "updated_at": "2024-03-15T10:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 15,
    "total": 42
  }
}

Example

curl -X GET "https://acme.yourdomain.com/api/v1/invoices?filter[status]=pending_payment&sort=-issue_date" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Get Invoice

Retrieve a specific invoice by ID, including related items, payments, and contact information.

Path Parameters

integer

required

Invoice ID

Response

{
  "data": {
    "id": 1,
    "workspace_id": 2,
    "contact_id": 45,
    "document_subtype_id": 3,
    "document_number": "B0100000001",
    "issue_date": "2024-03-15",
    "due_date": "2024-04-14",
    "status": "partially_paid",
    "subtotal_amount": "1250.00",
    "tax_amount": "225.00",
    "discount_amount": "0.00",
    "total_amount": "1475.00",
    "amount_due": "975.00",
    "amount_paid": "500.00",
    "contact": {
      "id": 45,
      "name": "Acme Corporation",
      "email": "[email protected]",
      "phone": "+1-809-555-0123"
    },
    "items": [
      {
        "id": 1,
        "product_id": 78,
        "description": "Premium Product",
        "quantity": "10.00",
        "unit_price": "125.00",
        "discount": "0.00",
        "subtotal": "1250.00",
        "tax_amount": "225.00",
        "total": "1475.00",
        "product": {
          "id": 78,
          "name": "Premium Product",
          "sku": "PROD-001"
        },
        "taxes": [
          {
            "id": 1,
            "name": "ITBIS",
            "rate": "18.00"
          }
        ]
      }
    ],
    "payments": [
      {
        "id": 10,
        "amount": "500.00",
        "payment_date": "2024-03-20",
        "payment_method": "transfer",
        "bank_account": {
          "id": 2,
          "name": "Main Account"
        }
      }
    ],
    "salesmen": [
      {
        "id": 5,
        "full_name": "John Doe"
      }
    ]
  }
}

Example

curl -X GET https://acme.yourdomain.com/api/v1/invoices/1 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Create Invoice

Create a new invoice.

Request Body

contact_id

integer

required

Customer contact ID

document_subtype_id

integer

required

Document subtype ID (determines NCF sequence)

issue_date

date

required

Invoice issue date (YYYY-MM-DD)

due_date

date

Payment due date (YYYY-MM-DD)

payment_term

string

Payment terms (e.g., “Net 30”)

notes

string

Additional notes or terms

currency_id

integer

Currency ID (defaults to workspace default currency)

items

array

required

Array of invoice line items

items[].product_id

integer

required

Product ID for this line item

items[].description

string

Line item description (defaults to product name)

items[].quantity

decimal

required

Quantity

items[].unit_price

decimal

required

Unit price

items[].discount

decimal

default:"0"

Discount amount or percentage

items[].tax_ids

array

Array of tax IDs to apply to this item

salesman_ids

array

Array of salesman IDs associated with this invoice

Response

{
  "data": {
    "id": 42,
    "workspace_id": 2,
    "contact_id": 45,
    "document_subtype_id": 3,
    "document_number": "B0100000042",
    "issue_date": "2024-03-20",
    "due_date": "2024-04-19",
    "status": "pending_payment",
    "total_amount": "1475.00",
    "created_at": "2024-03-20T14:30:00Z"
  },
  "message": "Factura creada exitosamente."
}

Example

curl -X POST https://acme.yourdomain.com/api/v1/invoices \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "contact_id": 45,
    "document_subtype_id": 3,
    "issue_date": "2024-03-20",
    "due_date": "2024-04-19",
    "payment_term": "Net 30",
    "notes": "Terms and conditions apply",
    "items": [
      {
        "product_id": 78,
        "description": "Premium Product",
        "quantity": 10,
        "unit_price": 125.00,
        "discount": 0,
        "tax_ids": [1]
      }
    ],
    "salesman_ids": [5]
  }'

Creating an invoice automatically generates stock movements if products track inventory. The document number is auto-generated based on the document subtype’s NCF sequence.

Update Invoice

Update an existing invoice.

Invoices can only be updated if their status is pending_payment. Invoices that are paid, partially_paid, or cancelled cannot be edited.

Path Parameters

integer

required

Invoice ID

Request Body

Same as Create Invoice endpoint. All fields are optional.

Response

{
  "data": {
    "id": 42,
    "document_number": "B0100000042",
    "total_amount": "1650.00",
    "updated_at": "2024-03-20T15:45:00Z"
  },
  "message": "Factura actualizada exitosamente."
}

Delete Invoice

Delete an invoice.

Only invoices with status pending_payment or draft can be deleted. Paid or partially paid invoices must have their payments removed first.

Path Parameters

integer

required

Invoice ID

Response

{
  "message": "Factura eliminada exitosamente."
}

Download Invoice PDF

Download invoice as PDF document.

Path Parameters

integer

required

Invoice ID

Response

Returns a PDF file with Content-Type: application/pdf.

Example

curl -X GET https://acme.yourdomain.com/api/v1/invoices/1/pdf \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o invoice-001.pdf

Validate NCF

Validate NCF (Dominican tax receipt number) for an invoice.

Request Body

ncf

string

required

NCF number to validate

document_subtype_id

integer

required

Document subtype ID

Response

{
  "valid": true,
  "message": "NCF is valid and available."
}

Payments

Record payments against invoices

Quotations

Convert quotations to invoices

Contacts

Manage customer information

Products

Product catalog management

Getting Started

Endpoints

Invoice Endpoints

Overview

Invoice Object

List Invoices

Query Parameters

Response

Example

Get Invoice

Path Parameters

Response

Example

Create Invoice

Request Body

Response

Example

Update Invoice

Path Parameters

Request Body

Response

Delete Invoice

Path Parameters

Response

Download Invoice PDF

Path Parameters

Response

Example

Validate NCF

Request Body

Response

Payments

Quotations

Contacts

Products

Build docs developers (and LLMs) love

Getting Started

Endpoints

​Overview

​Invoice Object

​List Invoices

​Query Parameters

​Response

​Example

​Get Invoice

​Path Parameters

​Response

​Example

​Create Invoice

​Request Body

​Response

​Example

​Update Invoice

​Path Parameters

​Request Body

​Response

​Delete Invoice

​Path Parameters

​Response

​Download Invoice PDF

​Path Parameters

​Response

​Example

​Validate NCF

​Request Body

​Response

​Related Resources

Payments

Quotations

Contacts

Products

Build docs developers (and LLMs) love

Overview

Invoice Object

List Invoices

Query Parameters

Response

Example

Get Invoice

Path Parameters

Response

Example

Create Invoice

Request Body

Response

Example

Update Invoice

Path Parameters

Request Body

Response

Delete Invoice

Path Parameters

Response

Download Invoice PDF

Path Parameters

Response

Example

Validate NCF

Request Body

Response

Related Resources