The Invoices resource is only available in versions 2020-09-30
and higher.
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.
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.
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 attempt to capture the charge and 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.
Parameter | Description |
| Refer to Using the customer identifier​ |
| Refer to Using the source identifier​ ​ |
| Refer to Selecting a currency​ |
| Refer to The invoice lifecycle​ |
| Refer to Designating a locale |
| Refer to Ship to address​ |
| Refer to Checkout level discount​ |
| Refer to Invoice billing​ |
| Refer to Invoice billing​ |
| Refer to Describing the items |
| Refer to Configuring taxes |
| Refer to Tax identifiers​ |
| Refer to Initiating a charge |
| Refer to Using customer type​ |
| Refer to Providing an upstream identifier​ |
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.
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."}]}
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.
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.
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.
The Invoices API provides you billing enhancements that are not available in the Checkouts API. To take advantage of these benefits, you should set the billingOptimization
parameter to true
. If you do this, we make multiple payment capture attempts over a period of time. This period is specified by collectionPeriodDays
, which, if not configured, defaults to 30
.
When Digital River successfully captures the charge, we move the Invoice into a paid
state. If we're unable to collect payment within the collectionPeriodDays
, we mark the Invoice as uncollectible
.
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.
An expired credit card, insufficient funds, or a closed credit card account are all possible reasons for an uncollectible invoice.
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.
An Invoice has a defined lifecycle and 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
.
Additionally, when the state
changes, an Event that represents that change is created. For example, when the state
changes from open
to paid
both an invoice.paid
and an invoice.updated
event are emitted.
1) When the Invoice is... | (2) the state transitions to... | (3) and an ... event is/are emitted. |
created but not yet authorized for billing |
|
|
simultaneously created and authorized for billing |
|
|
already created as a draft and then authorized for billing |
|
|
already authorized for billing and then paid |
|
|
already authorized for billing and then voided |
|
|
already authorized for billing but cannot be collected |
|
|
​