# Invoice basics

{% hint style="info" %}
The [invoice API](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/invoices) is only available in versions `2020-09-30` and higher.
{% endhint %}

In the Digital River APIs, an invoice represents a document associated with a sale you provide customers. Invoices itemize products or services rendered, including cost, quantity, fees, duties, and taxes. They also establish an obligation on the part of customers to pay you for the goods.

Invoices are especially useful when selling to other businesses. In business-to-business transactions, it's often customary to send customers an invoice, which they pay later, rather than immediately billing a credit card on file.

You use the [Invoices API](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/invoices) to [manage invoices](#managing-invoices). This API allows you to [create invoices](https://docs.digitalriver.com/digital-river-api/developer-resources/digital-river-api-reference/invoices#creating-an-invoice) for one-off transactions or to set up subscriptions and start billing them.

If you integrate with the [Invoices API](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/invoices), we recommend you familiarize yourself with the [invoice lifecycle](#the-invoice-lifecycle) and [billing process](#invoice-billing).

### Managing invoices <a href="#managing-invoices" id="managing-invoices"></a>

You can [create](#creating-an-invoice), [open](#opening-an-invoice), [void](#voiding-an-invoice), and [delete ](#deleting-an-invoice)invoices. The process of [collecting payment](#invoice-billing) on invoices is entirely handled by Digital River. After an invoice is paid, you can use the [Refunds API](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/refunds) to [issue refunds](#refunding-an-invoice) any needed refunds.

#### Creating an invoice <a href="#creating-an-invoice" id="creating-an-invoice"></a>

In a [`POST /invoices`](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/invoices/..#invoices-1) request, you can set `state` to either `draft` or `open`. The default value is `open`.

If you'd like us to immediately start the [billing process](#billing-optimization), set `state` to `open`.

Creating a `draft` invoice means you haven't yet authorized Digital River to capture any charges. However, draft invoices list the total taxes, fees, duties, and amounts for the goods rendered. As a result, they can be useful to include in billing reminders to customers.

Invoices are created in much the same way as [checkouts](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/checkouts). The major difference is that invoices allow you to [optimize billing](https://docs.digitalriver.com/digital-river-api/developer-resources/digital-river-api-reference/invoices#invoice-billing). Additionally, invoices can only be used to sell digital products, so you can't send any ship from values.

The following provides more information on the key parameters you can set when creating an invoice. For complete specifications, refer to the [Invoices API](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/invoices) reference page.

| Parameter              | Documentation                                                                                                                                                                                                                              |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `customerId`           | [Registered invoices](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/invoices)                                                                                                                                       |
| `sourceId`             | [Supported payment methods](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/payments/supported-payment-methods) and [Managing sources](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/payments/payment-sources/using-the-source-identifier) |
| `currency`             | [Selecting a currency](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/integration-options/checkouts/creating-checkouts/selecting-a-currency)                                                                                               |
| `state`                | [The invoice lifecycle](#the-invoice-lifecycle)                                                                                                                                                                                            |
| `locale`               | [Designating a locale](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/integration-options/checkouts/creating-checkouts/designating-a-locale)                                                                                               |
| `shipTo`               | [Ship to address](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/integration-options/checkouts/creating-checkouts/providing-address-information#ship-to-address)                                                                           |
| `discount`             | [Checkout level discount](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/integration-options/checkouts/creating-checkouts/applying-a-discount)                                                                                             |
| `collectionPeriodDays` | [Invoice billing](#invoice-billing)                                                                                                                                                                                                        |
| `billingOptimization`  | [Invoice billing optimization](#billing-optimization)                                                                                                                                                                                      |
| `items`                | [Describing the items](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/integration-options/checkouts/creating-checkouts/describing-the-items)                                                                                               |
| `taxInclusive`         | [Configuring taxes](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/integration-options/checkouts/creating-checkouts/configuring-taxes)                                                                                                     |
| `taxIdentifiers`       | [Tax identifiers](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/integration-options/checkouts/creating-checkouts/tax-identifiers)                                                                                                         |
| `chargeType`           | [Initiating a charge](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/integration-options/checkouts/creating-checkouts/initiating-a-charge)                                                                                                 |
| `customerType`         | [Setting the customer type](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/integration-options/checkouts/creating-checkouts/setting-the-customer-type)                                                                                     |
| `upstreamId`           | [Providing an upstream identifier](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/integration-options/checkouts/creating-checkouts/providing-an-upstream-identifier)                                                                       |

#### Opening an invoice <a href="#opening-an-invoice" id="opening-an-invoice"></a>

To open an already created invoice, send a [`POST /invoices/{id}/open`](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/invoices/..#invoices-id-open). Only `draft` invoices can be opened. So, before sending the request, you first determine the invoice's `state`.

You're instructing Digital River to initiate the [billing process](#invoice-billing) by opening an invoice.

Once opened, none of an invoice's attributes, other than `metadata`, can be updated. If you need to update customer or amount attributes, [void the invoice](#voiding-an-invoice) and create a new one.

#### Voiding an invoice <a href="#voiding-an-invoice" id="voiding-an-invoice"></a>

To void an invoice, send a [`POST /invoices/{id}/void`](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/invoices/..#invoices-id-void) request. This operation is similar to deleting an invoice but allows you to record when the invoice was created, opened, and voided.

Invoices in a voided state are not payable. You should void the invoice if you receive payment from the customer outside the normal flow (e.g., the customer pays by check). This is also a terminal state, which means voided invoices can't transition to another state.

Only `open` invoices can be voided. If an invoice is in any other state, and you attempt to void it, a `409 Conflict` is thrown:

{% tabs %}
{% tab title="Error" %}

```javascript
{
    "type": "conflict",
    "errors": [
        {
            "code": "invalid_state",
            "parameter": "state",
            "message": "Invoice 4fce39e4549845cf9d571a7676842a90 is not open. Only open invoices can be voided."
        }
    ]
}
```

{% endtab %}
{% endtabs %}

### Deleting an invoice

To permanently delete an invoice, send a [`DELETE/invoices/{id}`](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/invoices/..#invoices-id-2) request. This operation is similar to [voiding an invoice](#voiding-an-invoice), but no record is maintained for accounting purposes. Only `draft` invoices can be deleted.

### Refunding an invoice

Use the [Refunds API](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/refunds) to refund [charges ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/charges/charge-basics)[captured ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/charges/charge-basics#captures)when an invoice is paid. To partially or fully refund the invoice, send its `invoiceId` in a `POST /refunds`.

## Invoice billing

Once you move an [invoice's ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/invoices)`state` to `open`, Digital River initiates a billing process and attempts to [capture the charge(s)](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/charges/charge-basics#captures). With invoices, you can take advantage of our [billing optimization feature](#billing-optimization). If you use this feature, ensure your integration only displays [payment methods supported with invoices](#supported-payment-methods).

### Billing optimization

The [Invoices API](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/invoices) contains billing features unavailable in the [Checkouts API](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/checkouts). To use them, set `billingOptimization` to `true`. This setting prompts Digital River to make multiple [payment capture attempts](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/charges/charge-basics#captures) throughout the billing period, the length of which you can configure by setting `collectionPeriodDays` (the default setting is 30).

If Digital River successfully captures the charge(s), we move the invoice's `state` to `paid`. If the charge(s) are still not captured at the end of `collectionPeriodDays`, we move the invoice's `state` to `uncollectible` and create an `invoice.uncollectible` event.

The number of times Digital River has attempted to collect payment is represented by the invoice's `attemptCount`. This value can be useful for your analytics.

If you set `billingOptimization` to `false`, Digital River makes just one payment collection attempt. In this case, `collectionPeriodDays` does not affect the billing process. Depending on the result of that single collection attempt, we move the invoice's `state` to either `paid` or `uncollectible` and then [emit the corresponding event](#invoice-events).

An expired credit card, insufficient funds, or a closed credit card account are common reasons for an uncollectible invoice.

### Supported payment methods with invoices <a href="#supported-payment-methods" id="supported-payment-methods"></a>

If you set [`billingOptimization`](#billing-optimization) to `false`, then you can allow customers to use any [supported payment method](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/payments/supported-payment-methods) to pay an [invoice](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/invoices). This includes combining[ a primary source with one or more secondary sources](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/payments/payment-sources/using-the-source-identifier#combining-primary-and-secondary-payment-sources).

If `billingOptimization` is `true`, then an [invoice's](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/invoices) `payment.sources[]` should only contain a single [source](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/sources). Additionally, that object must be a [primary source](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/payments/payment-sources/using-the-source-identifier#primary-payment-sources) and support [reusability](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/payments/payment-sources#reusable-or-single-use). So, if you're using the billing optimization feature, restrict customers to payment methods that can be used in recurring transactions.

For a complete list of such payment methods, Refer to the [Supported payment methods](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/payments/supported-payment-methods) page for a complete list of such payment methods.

## The invoice lifecycle

An invoice has a defined lifecycle. Each time the [state of an invoice](#invoice-states) changes, Digital River creates a corresponding [event](#invoice-events).

### Invoice states

An invoice has the following states: `draft`, `open`, `paid`, `uncollectible`, or `void`.

Invoices in a `draft` state can either be [opened](#opening-an-invoice), which transitions them to an `open` state and initiate the [billing process](#invoice-billing), or they can be [deleted](#deleting-an-invoice) entirely.

An `open` invoice can then transition to `void`, `paid`, or `uncollectible`. All of these are terminal states. Invoices that are `void` or `uncollectible` are not payable.

<div align="left"><figure><img src="https://567528635-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx8fSFzVR3sg0TsNWwwVz%2Fuploads%2FJ4nFiFW3nLQf3rEqqLVt%2Fimage.png?alt=media&#x26;token=1b1b9ed9-c2c0-45bc-878b-1e07bc4552a4" alt=""><figcaption></figcaption></figure></div>

The `state` values for a successful invoice (i.e. the happy path) are `draft` > `open` > `paid` .

### Invoice events

When the [state of an invoice](#invoice-states) changes, an [event ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/events)that describes the change is created. For example, when an invoice's `state` changes from `open` to `paid` both an `invoice.paid` and an `invoice.updated` event is emitted.

All generated invoice events can be filtered and viewed by accessing the [Digital River Dashboard event log](https://docs.digitalriver.com/digital-river-api/administration/dashboard/developers/event-logs).

| 1) When an invoice is...                                   | (2) its state transitions to... | (3) and Digital River creates an ... event       |
| ---------------------------------------------------------- | ------------------------------- | ------------------------------------------------ |
| created but not yet authorized for billing                 | `draft`                         | `invoice.created`                                |
| simultaneously created and authorized for billing          | `open`                          | `invoice.created` and an `invoice.open`          |
| already created as a draft and then authorized for billing | `open`                          | `invoice.open` and an `invoice.updated`          |
| authorized for billing and then paid                       | `paid`                          | `invoice.paid` and an `invoice.updated`          |
| authorized for billing and then voided                     | `void`                          | `invoice.void` and an `invoice.updated`          |
| authorized for billing but cannot be collected             | `uncollectible`                 | `invoice.uncollectible` and an `invoice.updated` |