Skip to main content
GET
/
api
/
sales
/
debts
Debts
curl --request GET \
  --url https://api.example.com/api/sales/debts
{
  "debt_id": "<string>",
  "user_id": "<string>",
  "user": {
    "name": "<string>",
    "surname": "<string>",
    "phone": "<string>"
  },
  "cart_id": "<string>",
  "cart": {
    "total": 123,
    "created_at": "<string>"
  },
  "amount": 123,
  "remaining": 123,
  "status": "<string>",
  "due_date": "<string>",
  "notes": "<string>",
  "created_at": "<string>",
  "updated_at": "<string>"
}

​
Overview

The debts API allows you to track customer payment obligations when full payment cannot be collected at the time of sale. Debts can be associated with carts (sales transactions) and track partial payments over time.

​
Authentication

All debt endpoints require authentication. Include a valid session token in your request.

​
List Debts

Retrieves all debts with customer and cart information, ordered by creation date (most recent first).

​
Query Parameters

​
status
string
Filter by debt status:
  • pending - Returns both ‘pending’ and ‘partial’ status debts
  • partial - Returns debts with partial payments made
  • paid - Returns fully paid debts

​
Response

​
debt_id
string
Unique identifier (UUID) for the debt
​
user_id
string
ID of the customer who owes the debt
​
user
object
Customer information
​
cart_id
string
Optional ID of the associated cart/sale
​
cart
object
Associated cart information (if applicable)
​
amount
number
Original debt amount
​
remaining
number
Remaining amount to be paid
​
status
string
Current status: pending, partial, or paid
​
due_date
string
Optional due date for payment
​
notes
string
Optional notes about the debt
​
created_at
string
Creation timestamp
​
updated_at
string
Last update timestamp

​
Example Request

# Get all pending debts
curl -X GET "https://api.example.com/api/sales/debts?status=pending" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Example Response

[
  {
    "debt_id": "debt123",
    "user_id": "user456",
    "user": {
      "name": "María",
      "surname": "González",
      "phone": "+34 612 345 678"
    },
    "cart_id": "cart789",
    "cart": {
      "total": 150.00,
      "created_at": "2024-01-15T10:00:00Z"
    },
    "amount": 150.00,
    "remaining": 100.00,
    "status": "partial",
    "due_date": "2024-02-15T00:00:00Z",
    "notes": "Pago en 2 cuotas acordado",
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-20T14:30:00Z"
  }
]

​
Create Debt

Creates a new debt record for a customer.

​
Request Body

​
user_id
string
required
ID of the customer who owes the debt
​
amount
number
required
Total debt amount
​
cart_id
string
Optional ID of the associated cart/sale
​
due_date
string
Optional due date in ISO 8601 format
​
notes
string
Optional notes about the payment arrangement
The remaining field is automatically set to equal amount when creating a debt. The status defaults to pending.

​
Response

Returns the created debt object with customer information.

​
Example Request

curl -X POST "https://api.example.com/api/sales/debts" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user456",
    "cart_id": "cart789",
    "amount": 150.00,
    "due_date": "2024-02-15T00:00:00Z",
    "notes": "Pago en 2 cuotas de 75€"
  }'

​
Get Debt

Retrieves detailed information about a specific debt.

​
Path Parameters

​
id
string
required
The unique identifier of the debt

​
Response

Returns the debt object with full customer and cart details.

​
Example Request

curl -X GET "https://api.example.com/api/sales/debts/debt123" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Update Debt

Updates a debt record, typically to record a payment or change the status.

​
Path Parameters

​
id
string
required
The unique identifier of the debt to update

​
Request Body

​
remaining
number
New remaining balance. If set to 0 or less, status is automatically set to paid
​
status
string
New status: pending, partial, or paid
​
due_date
string
New due date in ISO 8601 format
​
notes
string
Updated notes

​
Response

Returns the updated debt object.

​
Example Request - Record Payment

# Record a partial payment of 50€
curl -X PUT "https://api.example.com/api/sales/debts/debt123" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "remaining": 50.00,
    "status": "partial",
    "notes": "Primera cuota de 50€ pagada el 20/01/2024"
  }'

​
Example Request - Mark as Paid

curl -X PUT "https://api.example.com/api/sales/debts/debt123" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "remaining": 0,
    "notes": "Deuda saldada completamente"
  }'

​
Delete Debt

Deletes a debt record.

​
Path Parameters

​
id
string
required
The unique identifier of the debt to delete

​
Response

Returns a success confirmation.

​
Example Request

curl -X DELETE "https://api.example.com/api/sales/debts/debt123" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Example Response

{
  "success": true
}
Deleting a debt removes all payment history. Consider marking as paid instead if you need to maintain records.

​
Common Workflows

​
Recording Installment Payments

// Record a payment installment
const recordPayment = async (debtId, paymentAmount) => {
  const debt = await fetch(`/api/sales/debts/${debtId}`).then(r => r.json());
  const newRemaining = debt.remaining - paymentAmount;
  
  await fetch(`/api/sales/debts/${debtId}`, {
    method: 'PUT',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      remaining: newRemaining,
      status: newRemaining > 0 ? 'partial' : 'paid',
      notes: `Pago de ${paymentAmount}€ recibido. ${debt.notes || ''}`
    })
  });
};

​
Tracking Overdue Debts

// Get overdue debts
const overdueDebts = debts.filter(debt => {
  if (!debt.due_date || debt.status === 'paid') return false;
  return new Date(debt.due_date) < new Date();
});

​
Debt Summary Report

// Calculate debt statistics
const debtSummary = {
  totalOutstanding: debts
    .filter(d => d.status !== 'paid')
    .reduce((sum, d) => sum + d.remaining, 0),
  totalDebts: debts.length,
  paidDebts: debts.filter(d => d.status === 'paid').length,
  pendingDebts: debts.filter(d => d.status === 'pending').length,
  partialDebts: debts.filter(d => d.status === 'partial').length
};

Carts

Manage sales transactions that can create debts

Clients

Manage customer information

Build docs developers (and LLMs) love

Get started for freeTalk to us