Recaudo Docs
Sign up

Payments & customers

Invoices

Invoices let you manage charges with full support for installments (payments in installments), late fee policies and detailed payment tracking. Ideal for tuition, loans and recurring services.

Available endpoints

GET /v1/invoices List invoices
POST /v1/invoices Create invoice (with or without installments)
GET /v1/invoices/:id Get invoice
PATCH /v1/invoices/:id Update invoice
DELETE /v1/invoices/:id Delete invoice
POST /v1/invoices/:id/payments Record a payment (amount, SAT forma_pago, payment_date)
POST /v1/invoices/:id/void Void invoice
GET /v1/invoices/:id/installments List installments
PATCH /v1/invoices/:id/installments/:installment_id Update installment

Create invoice

Creates an invoice with items and optionally sets up automatic or manual installments.

curl -X POST https://recaudo.app/api/v1/invoices \
  -H "Authorization: Bearer sk_live_tu_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "8e250c25-9d84-4892-98ec-d71fc1fcd3c7",
    "document_date": "2024-01-15",
    "items": [
      {
        "description": "Colegiatura Enero 2024",
        "quantity": 1,
        "unit_price": 5000.00
      }
    ],
    "has_installments": true,
    "installment_count": 3,
    "installment_frequency": "monthly",
    "first_installment_due_date": "2024-01-20"
  }'
$response = $client->post('https://recaudo.app/api/v1/invoices', [
    'headers' => [
        'Authorization' => 'Bearer sk_live_tu_secret_key',
        'Content-Type' => 'application/json',
    ],
    'json' => [
        'customer_id' => '8e250c25-9d84-4892-98ec-d71fc1fcd3c7',
        'document_date' => '2024-01-15',
        'items' => [
[
    'description' => 'Colegiatura Enero 2024',
    'quantity' => 1,
    'unit_price' => 5000.00,
]
        ],
        'has_installments' => true,
        'installment_count' => 3,
        'installment_frequency' => 'monthly',
        'first_installment_due_date' => '2024-01-20',
    ]
]);
const response = await fetch('https://recaudo.app/api/v1/invoices', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_tu_secret_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    customer_id: '8e250c25-9d84-4892-98ec-d71fc1fcd3c7',
    document_date: '2024-01-15',
    items: [
      {
        description: 'Colegiatura Enero 2024',
        quantity: 1,
        unit_price: 5000.00
      }
    ],
    has_installments: true,
    installment_count: 3,
    installment_frequency: 'monthly',
    first_installment_due_date: '2024-01-20'
  })
});
response = requests.post(
    'https://recaudo.app/api/v1/invoices',
    headers={
        'Authorization': 'Bearer sk_live_tu_secret_key',
        'Content-Type': 'application/json',
    },
    json={
        'customer_id': '8e250c25-9d84-4892-98ec-d71fc1fcd3c7',
        'document_date': '2024-01-15',
        'items': [
{
    'description': 'Colegiatura Enero 2024',
    'quantity': 1,
    'unit_price': 5000.00
}
        ],
        'has_installments': True,
        'installment_count': 3,
        'installment_frequency': 'monthly',
        'first_installment_due_date': '2024-01-20'
    }
)

Installment parameters

Parameter Type Description
has_installments boolean Enable installments
installment_count integer Number of installments (2-48)
installment_frequency string weekly, biweekly o monthly
first_installment_due_date date Due date of the first installment
late_fee_policy_id uuid Late fee policy ID

Manual installments

For more control, you can define each installment manually with its own dates, amounts and payment status. Useful to import existing invoices with partial payments.

Manual installments example 
{
  "customer_id": "8e250c25-9d84-4892-98ec-d71fc1fcd3c7",
  "items": [
    { "description": "Servicio anual", "quantity": 1, "unit_price": 12000.00 }
  ],
  "installments": [
    {
      "due_date": "2024-01-15",
      "amount": 4000.00,
      "external_id": "FACT-001-P1",
      "is_paid": true,
      "amount_paid": 4000.00,
      "paid_at": "2024-01-10"
    },
    {
      "due_date": "2024-02-15",
      "amount": 4000.00,
      "external_id": "FACT-001-P2",
      "is_paid": false
    },
    {
      "due_date": "2024-03-15",
      "amount": 4000.00,
      "external_id": "FACT-001-P3",
      "is_paid": false
    }
  ]
}

Invoice object

Invoice object with installments 
{
  "id": "263bb741-94bf-4aa5-9f47-6e64b82ba7e9",
  "object": "invoice",
  "invoice_number": "INV-2024-0001",
  "external_id": "FACT-001",
  "status": "partial",
  "customer_id": "8e250c25-9d84-4892-98ec-d71fc1fcd3c7",
  "currency": "MXN",
  "subtotal": 5000.00,
  "tax_amount": 0,
  "total": 5000.00,
  "amount_paid": 1666.67,
  "amount_due": 3333.33,
  "document_date": "2024-01-15",
  "due_date": "2024-03-20",
  "has_installments": true,
  "installment_count": 3,
  "installment_frequency": "monthly",
  "items": [
    {
      "id": "ii_xyz789",
      "description": "Colegiatura Enero 2024",
      "quantity": 1,
      "unit_price": 5000.00,
      "total": 5000.00
    }
  ],
  "installments": [
    {
      "id": "inst_001",
      "installment_number": 1,
      "status": "paid",
      "principal_amount": 1666.67,
      "late_fee_amount": 0,
      "total_amount": 1666.67,
      "amount_paid": 1666.67,
      "amount_due": 0,
      "due_date": "2024-01-20",
      "paid_at": "2024-01-18T14:30:00Z",
      "days_overdue": 0,
      "external_id": null
    },
    {
      "id": "inst_002",
      "installment_number": 2,
      "status": "pending",
      "principal_amount": 1666.67,
      "late_fee_amount": 0,
      "total_amount": 1666.67,
      "amount_paid": 0,
      "amount_due": 1666.67,
      "due_date": "2024-02-20",
      "paid_at": null,
      "days_overdue": 0,
      "external_id": null
    },
    {
      "id": "inst_003",
      "installment_number": 3,
      "status": "pending",
      "principal_amount": 1666.66,
      "late_fee_amount": 0,
      "total_amount": 1666.66,
      "amount_paid": 0,
      "amount_due": 1666.66,
      "due_date": "2024-03-20",
      "paid_at": null,
      "days_overdue": 0,
      "external_id": null
    }
  ],
  "created_at": "2024-01-15T00:00:00Z"
}

Installment statuses

Status Description
pending Pending payment, not overdue
partial Partial payment received
paid Fully paid
overdue Overdue and unpaid (may generate late fees)
cancelled Cancelled (invoice voided)

Late fees

Overdue installments can generate late fees automatically according to the configured policy. The field late_fee_amount shows the accumulated late fee and is added to the total_amount of the installment.

Important: Late fees are calculated on the outstanding principal balance, not on previous late fees (avoids unwanted compound interest).

Was this page helpful? Thanks for letting us know.
Esc