Invoices

The Invoices API allows you to generate and manage invoices with client information, series tracking, and comprehensive invoice management capabilities.

Overview

Use the Invoices API to:

Create new invoices with client information

Manage invoice series and folio numbers

List and filter existing invoices

Track invoice status and history

Generate PDF invoices

Handle invoice-client relationships

Endpoints

POST /v2/invoices

Create a new invoice.

Authentication Required: Yes

Request Body

{
  "clientId": "client_123",
  "amount": 1000.0,
  "currency": "MXN",
  "description": "Professional services",
  "series": "A",
  "items": [
    {
      "description": "Consulting services",
      "quantity": 1,
      "unitPrice": 800.0,
      "amount": 800.0
    },
    {
      "description": "Setup fee",
      "quantity": 1,
      "unitPrice": 200.0,
      "amount": 200.0
    }
  ],
  "dueDate": "2024-02-15T00:00:00.000Z",
  "issueDate": "2024-01-15T00:00:00.000Z"
}

Parameters

Parameter	Type	Required	Description
`clientId`	string	Yes	Client identifier
`amount`	number	Yes	Total invoice amount
`currency`	string	No	Currency code (default: MXN)
`description`	string	No	Invoice description
`series`	string	No	Invoice series (default: A)
`items`	array	No	Invoice line items
`dueDate`	string	No	Invoice due date (ISO 8601)
`issueDate`	string	No	Invoice issue date (ISO 8601)

Response

Success Response (201 Created):

{
  "data": {
    "id": "inv_456",
    "client": {
      "rfc": "XAXX010101000",
      "name": "Cliente Example",
      "legalName": "Cliente Example S.A. de C.V."
    },
    "status": "draft",
    "amount": 1000.0,
    "currency": "MXN",
    "series": "A",
    "invoice": {
      "folioNumber": "A001"
    },
    "description": "Professional services",
    "dueDate": "2024-02-15T00:00:00.000Z",
    "issueDate": "2024-01-15T00:00:00.000Z",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "items": [
      {
        "description": "Consulting services",
        "quantity": 1,
        "unitPrice": 800.0,
        "amount": 800.0
      },
      {
        "description": "Setup fee",
        "quantity": 1,
        "unitPrice": 200.0,
        "amount": 200.0
      }
    ]
  },
  "message": "Invoice created successfully"
}

GET /v2/invoices

List invoices with optional filtering.

Authentication Required: Yes

Query Parameters

Parameter	Type	Description
`limit`	number	Number of results to return (default: 20, max: 100)
`offset`	number	Number of results to skip
`clientId`	string	Filter by client ID
`status`	string	Filter by invoice status
`series`	string	Filter by invoice series
`from`	string	Filter invoices from date (ISO 8601)
`to`	string	Filter invoices to date (ISO 8601)
`minAmount`	number	Filter by minimum amount
`maxAmount`	number	Filter by maximum amount

Response

Success Response (200 OK):

{
  "data": [
    {
      "id": "inv_456",
      "client": {
        "rfc": "XAXX010101000",
        "name": "Cliente Example"
      },
      "status": "sent",
      "amount": 1000.0,
      "currency": "MXN",
      "series": "A",
      "invoice": {
        "folioNumber": "A001"
      },
      "timestamp": "2024-01-15T10:30:00.000Z"
    }
  ],
  "message": "Invoices retrieved successfully",
  "totalResults": 1,
  "hasMore": false,
  "next": null
}

GET /v2/invoices/{invoiceId}

Get a specific invoice by ID.

Authentication Required: Yes

Response

Success Response (200 OK):

{
  "data": {
    "id": "inv_456",
    "client": {
      "rfc": "XAXX010101000",
      "name": "Cliente Example",
      "legalName": "Cliente Example S.A. de C.V.",
      "email": "cliente@example.com"
    },
    "status": "sent",
    "amount": 1000.0,
    "currency": "MXN",
    "series": "A",
    "invoice": {
      "folioNumber": "A001"
    },
    "description": "Professional services",
    "dueDate": "2024-02-15T00:00:00.000Z",
    "issueDate": "2024-01-15T00:00:00.000Z",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "items": [
      {
        "description": "Consulting services",
        "quantity": 1,
        "unitPrice": 800.0,
        "amount": 800.0
      },
      {
        "description": "Setup fee",
        "quantity": 1,
        "unitPrice": 200.0,
        "amount": 200.0
      }
    ]
  },
  "message": "Invoice retrieved successfully"
}

PUT /v2/invoices/{invoiceId}

Update an existing invoice.

Authentication Required: Yes

Request Body

{
  "description": "Updated professional services",
  "dueDate": "2024-03-01T00:00:00.000Z"
}

DELETE /v2/invoices/{invoiceId}

Delete (cancel) an invoice.

Authentication Required: Yes

Invoice Status

Status	Description
`draft`	Invoice is in draft state
`sent`	Invoice has been sent to client
`paid`	Invoice has been paid
`overdue`	Invoice is past due date
`cancelled`	Invoice has been cancelled
`refunded`	Invoice has been refunded

Invoice Series

Invoice series help organize and categorize your invoices:

Series A: Default series for standard invoices

Series B: Can be used for different business units

Custom Series: Create custom series as needed

Each series maintains its own folio number sequence (A001, A002, etc.).

Code Examples

Create an Invoice

JavaScript/Node.js:

Python:

List Invoices with Filtering

cURL:

Error Handling

Common Error Responses

Validation Error (400 Bad Request):

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request parameters",
    "details": {
      "amount": "Amount must be greater than 0",
      "clientId": "Client ID is required",
      "items": "At least one item is required"
    }
  },
  "message": "Request validation failed"
}

Client Not Found (404 Not Found):

{
  "error": {
    "code": "client_not_found",
    "message": "The specified client does not exist"
  },
  "message": "Client validation failed"
}

Best Practices

Client Validation: Ensure client exists before creating invoices

Series Management: Use consistent series for better organization

Item Details: Include detailed line items for transparency

Due Dates: Set appropriate due dates based on your payment terms

Status Tracking: Monitor invoice status changes for follow-up

Currency Consistency: Use consistent currency codes (ISO 4217)

Integration with Payments

Link invoices with payments for complete transaction tracking:

Next Steps

Manage client information

Process payments for invoices

Set up webhooks for invoice notifications

Invoices

Invoices#

Overview#

Endpoints#

POST /v2/invoices#

Request Body#

Parameters#

Response#

GET /v2/invoices#

Query Parameters#

Response#

GET /v2/invoices/{invoiceId}#

Response#

PUT /v2/invoices/{invoiceId}#

Request Body#

DELETE /v2/invoices/{invoiceId}#

Invoice Status#

Invoice Series#

Code Examples#

Create an Invoice#

List Invoices with Filtering#

Error Handling#

Common Error Responses#

Best Practices#

Integration with Payments#

Next Steps#

Invoices

Overview

Endpoints

POST /v2/invoices

Request Body

Parameters

Response

GET /v2/invoices

Query Parameters

Response

GET /v2/invoices/{invoiceId}

Response

PUT /v2/invoices/{invoiceId}

Request Body

DELETE /v2/invoices/{invoiceId}

Invoice Status

Invoice Series

Code Examples

Create an Invoice

List Invoices with Filtering

Error Handling

Common Error Responses

Best Practices

Integration with Payments

Next Steps