In the Digital River API, an Invoice represents a document, associated with a sale, that you provide to your customer. An Invoice itemizes the products or services rendered and includes their cost, quantity, fees, duties, and taxes. It also establishes an obligation on the part of the customer to pay you for those products and services.

Invoices can be especially useful when selling to other businesses. In these types of transactions, it's often customary to send customers an invoice, which they pay at a later time, rather than immediately billing a credit card you have on file.

You can manage invoices by using the Invoices API. This API allows you to create invoices for one-off transactions or to set up a subscription and start billing it.

It's also important to understand the various states of an invoice, which states are available for you to set, and how they influence the payment capture process.

Managing invoices

You can create, open, void, and delete invoices. The process of collecting payment on invoices is entirely handled by Digital River. After an invoice is paid, you can use the Refunds API to issue refunds.

Creating an invoice

By submitting a POST/invoices request, you can create an Invoice in either a draft or open state. If you don't provide a value, the default is open.

If you'd like us to immediately start the billing process, submit a POST/invoices request in an open state.

Creating an invoice in a draft state means you're not yet authorizing Digital River to capture the charge. Because invoices created in this state contain the total taxes, fees, duties, and amounts for the goods rendered, they can be useful for emailing renewal reminders to customers.

Invoices are created in much the same way as Checkouts. The major difference is the billing-related parameters that allow you to optimize billing and specify a collection period. Additionally, you do not specify ship from data since invoices are only used when selling digital products.

The following provides more information on the key parameters you can set when creating an Invoice. For a full list of parameters, refer to the Invoices API reference page.

Opening an invoice

Submit a POST/invoices/{id}/open request to open an invoice. Only invoices in a draft state can be opened. By submitting this request, you are instructing Digital River to initiate the invoice billing process.

After an invoice is opened, none of its attributes, other than metadata, can be updated. The only action you can take is to void the invoice. Once opened, if updates are required to customer or amount attributes, then the invoice should be voided and a new invoice created.

Voiding an invoice

Submit a POST/invoices/{id}/void request to void an invoice. Voiding is similar to deleting an invoice but maintains a record of when the invoice was created, opened, and voided.

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

Only invoices in an open state can be voided. If you attempt to void an invoice in any other state, you'll receive a 409 Conflict response.

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

Deleting an invoice

Submit a DELETE/invoices/{id} request to permanently delete an invoice. This action is similar to voiding an invoice but no record is maintained for accounting purposes. You can only delete an invoice when it is in a draft state.

Refunding an invoice

Use the Refunds API to refund charges created by a paid invoice. To do this, supply the invoice identifier when issuing refunds for an amount or for a percentage.

Invoice billing

Once you create an invoice in an open state or submit an open invoice request, Digital River starts the billing process and attempts to capture the charge.

Billing optimization

The Invoices API provides you billing enhancements that are not available in the Checkouts API. To take advantage of these benefits, you should set billingOptimization to true. This instructs Digital River to make multiple payment capture attempts over a period of time whose length you can specify using the collectionPeriodDays parameter. The default setting is 30 days.

During the collectionPeriodDays, if one of the internal orders that Digital River generates is able to successfully capture the charge, we move the Invoice into a paid state. However, if we're unable to collect payment within this time period, we mark the Invoice as uncollectibleand emit an invoice.uncollectible event.

If you'd like to view the number of times Digital River has attempted to collect payment, you find that data in the attemptCount attribute. This value can be useful for your analytics.

Setting billingOptimization to false means we attempt to collect payment just one-time. In this case, collectionPeriodDays has no effect on the billing process. After that one collection attempt, depending on the result, we move the Invoice into either a paid or uncollectible state and then emit the appropriate events.

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

Supported payment methods

As long as you turn off billing optimization, any payment method supported by either Drop-in or DigitalRiver.js can be used to fund an invoice transaction. However, if you set billingOptimization to true, we recommend you only allow customers to make purchases with credit cards.

In the Invoices API, you can also combine primary and secondary payment sources.

The invoice lifecycle

An invoice has a defined lifecycle. Each time the state of an invoice changes, a corresponding event is triggered that allows you to respond to that state change.

Invoice states

An Invoice can be in any of the following states: draft, open, paid, uncollectible, or void.

Invoices in a draft state can either be opened, which transitions them to an open state and makes them billable, or they can be deleted entirely.

When an invoice is in an open state, it can either become void, paid, or uncollectible. All of these are terminal states, meaning they can never transition to another state. Invoices that move into a void or uncollectible state are not payable.

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

Invoice events

When the state of an Invoice changes, an Event that describes the change is emitted. For example, when the state changes from open to paid both an invoice.paid and an invoice.updated event are emitted.