---
updatedAt: 2026-04-07T00:15:36.000Z
agentTools:
  projectIndex: https://docs.pelcro.com/llms.txt
---

# Invoices

Manage billing documents for subscriptions and one-time charges.

## Overview

Invoices represent billing documents sent to customers. They can be generated automatically from subscriptions or created manually for one-time charges. Each invoice tracks amounts due, payments received, and billing status.

***

## How It Works

1. **Invoice creation** - Invoices are created automatically when subscriptions renew or manually via the API
2. **Payment collection** - Invoices can be paid automatically or manually marked as paid
3. **Status tracking** - Track invoice lifecycle from draft to paid, void, or uncollectible

**Example:** When a subscription renews, the system automatically creates an invoice with the plan amount, applies any discounts, calculates taxes, and attempts to collect payment from the customer's default payment method.

***

## API Endpoints

| Method | Endpoint                                   | Description               |
| ------ | ------------------------------------------ | ------------------------- |
| `GET`  | `/api/v1/core/invoices`                    | List all invoices         |
| `POST` | `/api/v1/core/invoices`                    | Create an invoice         |
| `GET`  | `/api/v1/core/invoices/{id}`               | Get an invoice            |
| `PUT`  | `/api/v1/core/invoices/{id}`               | Update an invoice         |
| `POST` | `/api/v1/core/invoices/{id}/pay_offline`   | Record an offline payment |
| `POST` | `/api/v1/core/invoices/{id}/void`          | Void an invoice           |
| `POST` | `/api/v1/core/invoices/{id}/uncollectible` | Mark as uncollectible     |

***

## Important Behaviors

* **Soft delete**: Invoices are soft-deleted, not permanently removed.
* **Currency normalization**: The `currency` field is automatically lowercased before storage.
* **Metadata merge**: On update, metadata is merged with existing values, not replaced.
* **Update scope**: Only `metadata` and `purchase_order` are editable via update — other fields are immutable after creation.
* **Void restrictions**: Cannot void advance invoices or invoices with partial payments.
* **Uncollectible restrictions**: Only `open` or `past_due` invoices can be marked uncollectible. Advance invoices and those with partial payments are excluded.
* **Customer address default**: If `customer_address` is not provided on create, it auto-populates from the customer's default billing address.
* **Period end default**: If `period_end` is not provided, it defaults to `period_start`.
* **Expandable relationships**: `subscription`, `charge`, `user`, `discount` can be expanded via the `expand` query parameter.

## Invoice Statuses

| Status          | Description                                  |
| --------------- | -------------------------------------------- |
| `draft`         | Invoice is being prepared, not yet finalized |
| `open`          | Invoice is finalized and awaiting payment    |
| `paid`          | Payment has been collected successfully      |
| `past_due`      | Payment deadline has passed                  |
| `void`          | Invoice has been canceled                    |
| `uncollectible` | Invoice has been marked as uncollectible     |

***

## Billing Methods

| Method                 | Description                                                     |
| ---------------------- | --------------------------------------------------------------- |
| `charge_automatically` | System attempts to charge the customer's default payment method |
| `send_invoice`         | Customer receives an invoice to pay manually                    |

***

## Invoice Object

| Attribute                          | Type      | Description                                    |
| ---------------------------------- | --------- | ---------------------------------------------- |
| `id`                               | integer   | Unique identifier for the invoice              |
| `user_id`                          | integer   | ID of the customer (expandable)                |
| `subscription_id`                  | integer   | ID of the associated subscription (expandable) |
| `charge_id`                        | integer   | ID of the successful charge (expandable)       |
| `discount_id`                      | integer   | ID of the applied discount (expandable)        |
| `number`                           | string    | Invoice number                                 |
| `status`                           | string    | Invoice status (see statuses above)            |
| `currency`                         | string    | Three-letter ISO currency code                 |
| `amount_due`                       | integer   | Amount due in cents                            |
| `amount_paid`                      | integer   | Amount paid in cents                           |
| `amount_remaining`                 | integer   | Remaining amount in cents                      |
| `subtotal`                         | integer   | Subtotal before tax in cents                   |
| `tax`                              | integer   | Tax amount in cents                            |
| `total`                            | integer   | Total amount in cents                          |
| `paid`                             | boolean   | Whether the invoice has been paid              |
| `billing`                          | string    | Billing method                                 |
| `billing_reason`                   | string    | Reason for the invoice                         |
| `auto_advance`                     | boolean   | Whether invoice auto-finalizes                 |
| `due_date`                         | timestamp | Unix timestamp when payment is due             |
| `period_start`                     | timestamp | Unix timestamp of billing period start         |
| `period_end`                       | timestamp | Unix timestamp of billing period end           |
| `starting_balance`                 | integer   | Customer balance before invoice                |
| `ending_balance`                   | integer   | Customer balance after invoice                 |
| `plan_name`                        | string    | Name of the associated plan                    |
| `product_name`                     | string    | Name of the associated product                 |
| `customer_address`                 | object    | Customer's billing address                     |
| `hosted_invoice_url`               | string    | URL to hosted invoice page                     |
| `invoice_pdf`                      | string    | URL to download invoice PDF                    |
| `payment_link`                     | string    | URL for customer to pay                        |
| `post_payment_credit_notes_amount` | integer   | Credit notes after payment                     |
| `pre_payment_credit_notes_amount`  | integer   | Credit notes before payment                    |
| `is_imported`                      | boolean   | Whether invoice was imported                   |
| `notes`                            | string    | Invoice footer/notes                           |
| `metadata`                         | object    | Key-value pairs for storing additional data    |
| `finalized_at`                     | timestamp | Unix timestamp when finalized                  |
| `paid_at`                          | timestamp | Unix timestamp when paid                       |
| `voided_at`                        | timestamp | Unix timestamp when voided                     |
| `marked_uncollectible_at`          | timestamp | Unix timestamp when marked uncollectible       |
| `created_at`                       | timestamp | Unix timestamp of creation                     |
| `updated_at`                       | timestamp | Unix timestamp of last update                  |
| `deleted_at`                       | timestamp | Unix timestamp of deletion                     |

***

# Sub pages

* [List invoices](https://docs.pelcro.com/reference/api-core-list-invoices.md)
* [Get invoice](https://docs.pelcro.com/reference/get-invoice.md)
* [Pay invoice (offline)](https://docs.pelcro.com/reference/api-core-pay-invoice.md)
* [Void invoice](https://docs.pelcro.com/reference/api-core-void-invoice.md)
* [Update invoice](https://docs.pelcro.com/reference/update-invoice.md)
* [Mark invoice as uncollectible](https://docs.pelcro.com/reference/api-core-mark-as-uncollectible-invoices.md)
* [Create invoice](https://docs.pelcro.com/reference/create-invoice.md)
* [Apply balance to invoice](https://docs.pelcro.com/reference/api-core-apply-balance-to-invoice.md)

# Sibling pages

* [Overview](https://docs.pelcro.com/reference/api-core-intro.md)
* [Pagination](https://docs.pelcro.com/reference/api-core-pagination-limits.md)
* [Rate limits](https://docs.pelcro.com/reference/api-core-rate-limits.md)
* [Errors](https://docs.pelcro.com/reference/api-core-errors.md)
* [Sorting and filtering](https://docs.pelcro.com/reference/api-core-filtering-and-sorting.md)
* [Expanding relationships](https://docs.pelcro.com/reference/api-core-expanding-relationships.md)
* [Account](https://docs.pelcro.com/reference/api-core-account.md)
* [Analytics](https://docs.pelcro.com/reference/api-core-analytics.md)
* [Addresses](https://docs.pelcro.com/reference/api-core-addresses.md)
* [Bills](https://docs.pelcro.com/reference/api-core-bills.md)
* [Campaigns](https://docs.pelcro.com/reference/api-core-campaigns.md)
* [Charges](https://docs.pelcro.com/reference/api-core-charges.md)
* [Coupons](https://docs.pelcro.com/reference/api-core-coupons.md)
* [Customers](https://docs.pelcro.com/reference/api-core-customers.md)
* [E-commerce](https://docs.pelcro.com/reference/api-core-ecommerce.md)
* [Exports](https://docs.pelcro.com/reference/api-core-export.md)
* [Memberships](https://docs.pelcro.com/reference/api-core-membership.md)
* [Newsletters](https://docs.pelcro.com/reference/api-core-newsletters.md)
* [Organizations](https://docs.pelcro.com/reference/api-core-organizations.md)
* [Payment Methods](https://docs.pelcro.com/reference/api-core-source.md)
* [Plans](https://docs.pelcro.com/reference/api-core-plan.md)
* [Products](https://docs.pelcro.com/reference/api-core-product.md)
* [Refunds](https://docs.pelcro.com/reference/api-core-refunds.md)
* [Sites](https://docs.pelcro.com/reference/api-core-sites.md)
* [Subscriptions](https://docs.pelcro.com/reference/api-core-subscription.md)
* [Vendors](https://docs.pelcro.com/reference/api-core-vendors.md)
* [Webhooks](https://docs.pelcro.com/reference/api-core-webhook.md)