Invoices#

Invoices are statements of amounts owed by a tenant. They track the status of payments from creation through collection.

The Invoice object#

Attribute	Type	Description
`id`	string	Unique identifier with `inv_` prefix
`object`	string	Always `"invoice"`
`customer`	string	Customer ID
`status`	enum	`draft`, `open`, `paid`, `void`, `uncollectible`
`amount_due`	integer	Amount owed in smallest currency unit
`amount_paid`	integer	Amount already paid
`amount_remaining`	integer	Amount still owed
`currency`	string	Three-letter ISO 4217 currency code
`due_date`	timestamp	Payment due date
`line_items`	array	Array of invoice line items
`subtotal`	integer	Subtotal before tax
`tax`	integer	Total tax amount
`total`	integer	Total after tax
`description`	string	Description of the invoice
`pdf_url`	string	URL of the generated PDF
`hosted_invoice_url`	string	URL for hosted payment page
`payment_intent`	string	Associated PaymentIntent ID
`metadata`	hash	Key-value pairs
`finalized_at`	timestamp	When the invoice was finalized
`paid_at`	timestamp	When the invoice was paid
`created`	timestamp	Time at which the object was created
`livemode`	boolean	Whether this is a live mode object

{
  "id": "inv_abc123",
  "object": "invoice",
  "customer": "cus_123456789",
  "status": "open",
  "amount_due": 125000,
  "amount_paid": 0,
  "amount_remaining": 125000,
  "currency": "eur",
  "due_date": 1708732800,
  "line_items": [
    {
      "id": "ii_item1",
      "description": "Monthly rent — Unit 4B",
      "amount": 120000,
      "currency": "eur",
      "quantity": 1
    },
    {
      "id": "ii_item2",
      "description": "Parking space",
      "amount": 5000,
      "currency": "eur",
      "quantity": 1
    }
  ],
  "subtotal": 125000,
  "tax": 0,
  "total": 125000,
  "pdf_url": "https://files.casapay.com/invoices/inv_abc123.pdf",
  "hosted_invoice_url": "https://pay.casapay.com/inv/inv_abc123",
  "metadata": {
    "lease_id": "lease_789",
    "period": "2025-02"
  },
  "finalized_at": 1706227200,
  "created": 1706140800,
  "livemode": false
}

Create an Invoice#

POST /v1/invoices

Parameter	Type	Required	Description
`customer`	string	Yes	Customer ID
`due_date`	timestamp	No	Payment due date
`line_items`	array	No	Invoice line items
`line_items[].description`	string	Yes	Line item description
`line_items[].amount`	integer	Yes	Amount in smallest currency unit
`line_items[].currency`	string	Yes	ISO 4217 currency code
`line_items[].quantity`	integer	No	Quantity (default: 1)
`description`	string	No	Invoice description
`tax_rates`	array	No	Tax rate IDs to apply
`metadata`	hash	No	Key-value pairs

curl https://api.casapay.com/v1/invoices \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_123456789",
    "due_date": 1708732800,
    "line_items": [
      {
        "description": "Monthly rent — Unit 4B",
        "amount": 120000,
        "currency": "eur"
      },
      {
        "description": "Parking space",
        "amount": 5000,
        "currency": "eur"
      }
    ]
  }'

{
  "id": "inv_abc123",
  "object": "invoice",
  "status": "draft",
  "amount_due": 125000,
  "currency": "eur",
  "created": 1706140800
}

Retrieve an Invoice#

GET /v1/invoices/:id

curl https://api.casapay.com/v1/invoices/inv_abc123 \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"

Update an Invoice#

Updates a draft invoice. Only invoices in draft status can be updated.

POST /v1/invoices/:id

Parameter	Type	Description
`due_date`	timestamp	Updated due date
`description`	string	Updated description
`metadata`	hash	Updated metadata

curl https://api.casapay.com/v1/invoices/inv_abc123 \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{"due_date": 1709337600}'

Delete an Invoice#

Permanently deletes a draft invoice. Finalized invoices cannot be deleted — use void instead.

DELETE /v1/invoices/:id

curl -X DELETE https://api.casapay.com/v1/invoices/inv_abc123 \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"

List Invoices#

GET /v1/invoices

Parameter	Type	Description
`customer`	string	Filter by customer
`status`	string	Filter by status
`due_date[gte]`	timestamp	Due date on or after
`due_date[lte]`	timestamp	Due date on or before
`limit`	integer	Number of objects to return (1–100)
`starting_after`	string	Cursor for pagination

curl "https://api.casapay.com/v1/invoices?customer=cus_123456789&status=open" \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"

Finalize an Invoice#

Finalizes a draft invoice, locking it for payment. The invoice status changes from draft to open.

POST /v1/invoices/:id/finalize

curl -X POST https://api.casapay.com/v1/invoices/inv_abc123/finalize \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"

Send an Invoice#

Sends a finalized invoice to the customer via email.

POST /v1/invoices/:id/send

curl -X POST https://api.casapay.com/v1/invoices/inv_abc123/send \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"

Void an Invoice#

Voids a finalized invoice that hasn't been paid. Voided invoices cannot be unvoided.

POST /v1/invoices/:id/void

curl -X POST https://api.casapay.com/v1/invoices/inv_abc123/void \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"

Mark Invoice Uncollectible#

Marks an open invoice as uncollectible. This is typically done after exhausting payment attempts.

POST /v1/invoices/:id/mark_uncollectible

curl -X POST https://api.casapay.com/v1/invoices/inv_abc123/mark_uncollectible \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"