# Invoices

An invoice is a bill for a list of goods and services provided.
If your invoice includes subscription items, it also includes the corresponding service periods and prices.

## Invoice components

An invoice is sent from a merchant's [organization](/docs/dev-docs/organizations-and-websites#organizations) to a [customer](/docs/dev-docs/customers).
The customer may have a billing address and delivery address.
After the first transaction is received and the invoice becomes `partially-paid`, the billing address cannot be changed.
Invoices are sequentially numbered for each customer.
If an invoice is associated with a subscription, the `subscriptionId` value is displayed.
Invoices contain line items.
Each line item may have a product ID, plan ID, quantity, service period and pricing information.

An invoice may have associated [coupons & discounts](#coupons-and-discounts), [shipping](/docs/settings/shipping), [taxes](#taxes), [transactions](/docs/dev-docs/transactions), and [credit memos](/docs/dev-docs/credit-memos).

## Invoice lifecycle

This section describes the invoice lifecycle and related terms.

Deleting invoices is not recommended, it may also be illegal in some jurisdictions.

### Invoice status

The following are all invoice status types.

| Status  | Description |
|  --- | --- |
| `abandoned` | Invoice is not paid, or not paid in full, and has been abandoned by the merchant. |
| `paid` | Invoice is paid by the customer. |
| `partially-paid` | Invoice amount is partially paid by the customer. |
| `partially-refunded` | Invoice amount is partially refunded to the customer. |
| `past-due` | Invoice is issued to the customer.
It is not paid.
The payment time-frame has exceeded by more than 24 hours. |
| `refunded` | Invoice amount is fully refunded to the customer. |
| `unpaid` | Invoice is issued to the customer.
It is not paid.
The payment time-frame has not exceeded. |
| `voided` | Invoice amount is set to zero.
Voiding retains the invoice number and lists it in reports but changes the amounts to zero. |
| `disputed` | Invoice amount paid is disputed by the customer or merchant. |
| `draft` | Invoice that is not issued yet. |
| `quotation` | Invoice with an issued quote.
Once the invoice is issued, quote items cannot be modified and must be manually sent to the customer. |


### Invoice issued and paid on or by due date

This section describes the invoice lifecycle for an invoice that is paid on or by the due date.


```mermaid
%%{init: {"flowchart": {"htmlLabels": false}}}%%
graph LR;
    A(1 Invoice issued) --> |Full payment| B(2 Invoice paid in full)
```

1. An upcoming invoice is issued and assigned the `unpaid` status.
2. The invoice is paid in full and assigned the `paid` status.


When an invoice is paid, it may be refunded or disputed.
If an invoice is disputed, you may want to suspend the subscription service until the dispute is resolved.
For more information, see [Pause a subscription](/docs/data-tables/manage-subscriptions#pause-a-subscription) or the [Pause a subscription](/docs/dev-docs/api/orders/postsubscriptionpause/) operation.

### Invoice issued and partially paid

This section describes the invoice lifecycle for an invoice that is partially paid.


```mermaid
%%{init: {"flowchart": {"htmlLabels": false}}}%%
graph LR;
    A(1 Invoice issued) --> |Partial payment| C(2 Partially paid)
    C --> |Remaining balance paid| B(Paid)
    B --> |Amount refunded|E(Refunded)
    B --> |Amount refunded|F(Partially refunded)
    C --> |Amount refunded|E(Refunded)
    C --> F(Partially refunded)
```

1. An upcoming invoice is issued and assigned the `unpaid` status.
2. The invoice is partially paid and is assigned the `partially-paid` status.
After the first transaction is received and the invoice becomes `partially-paid`, the billing address cannot be changed.
From the partially-paid state:
  - If the customer pays the remaining amount, the invoice is assigned the `paid` status.
This amount can be `partially-refunded`, or fully `refunded`.
  - If the customer does not pay the remaining amount, the partially paid amount can be `partially-refunded`, or fully `refunded`.


### Invoice issued and not paid

This section describes the invoice lifecycle for an invoice that is not paid.


```mermaid
%%{init: {"flowchart": {"htmlLabels": false}}}%%
graph LR;
    A(1 Invoice issued) --> |No payment| B(2 Unpaid)
    B --> |24 hours after due time| C(Past Due)
    C --> D(Abandoned)
    C -.-> |Reissued| A
    B -.-> |Reissued| A
    D -.-> |Reissued| A
```

1. An upcoming invoice is issued and assigned the `unpaid` status.
2. The invoice is not paid on or before the due date, it retains the `unpaid` status for 24 hours.
3. The invoice exceeds the 24 hour time-frame.
The invoice is assigned the `past-due` status.
4. The invoice is not paid within the `past-due` time-frame.
5. The merchant decides to abandon the collection of payment.
Or, the autopay retry attempt limit is exceeded.
The invoice is assigned the `abandoned` status.


## Usage

If you follow the suggested order workflow, you may utilize the invoice using the `expand=recentInvoice` query string parameter and value on the order API requests.
You may also retrieve any invoice by its ID, for example: `GET invoices/123`.

In other resources, the invoice ID may be referred to as the `invoiceId`, `recentInvoiceId`, `initialInvoiceId` or a value with "invoiceId" in the name.

## Webhooks

Use webhooks to notify your systems when certain events occur, and to collect information about the events.
For more information, see [Webhooks](/docs/dev-docs/webhooks-configuration).

To record paid invoices in your own system, or push the data to third parties, create a trigger on the [Invoice paid](/docs/automations/event-types) event.

Rebilly also provides custom webhooks, that enable you to control the payload using placeholders.
These may be useful for integrating directly to third parties without needing to mediate the requests and responses.

## Automate emailing invoices

Use Rebilly to email invoices to your customers.
For more information, see [Automate emailing invoices](/docs/tutorials/automate-emailing-invoices).

## Taxes

Rebilly supports automated tax calculations internationally, using the location of your organization and the location of your customer.
You may also manually adjust the taxes on an unpaid invoice.
Rebilly calculates taxes after an invoice is issued and recalculates them on every invoice change.
The shipping amount is added to tax calculations.
For more information, see [Taxes](/docs/settings/taxes).

To calculate taxes:

- The product must be taxable.
- Your organization must have a full address.
- The customer must have a full address.


If you would like to use third-party tax calculators, [Contact us](/support/).

## Coupons and discounts

For more information on coupons and discounts, see [Coupons and discounts](/docs/settings/coupons-and-discounts) and the [Coupons](/docs/dev-docs/api/coupons/) operations.