Invoicing
Learn how to manage invoices and optimize billing.
In the Digital River APIs, an invoice represents a document, associated with a sale, that you provide to customers. Invoices itemize products or services rendered and include their 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 at a later time, rather than immediately billing a credit card on file.
You use the Invoices API to manage invoices . This API allows you to create invoices for one-off transactions or to set up subscriptions and start billing them.
If you integrate with the Invoices API, we recommend you familiarize yourself with the invoice lifecycle as well as the invoice billing 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 any needed refunds.
Creating a
draft invoice means you haven't yet authorized Digital River to capture any charges. However, draft invoices do 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. The major difference is that invoices allow you to optimize 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 reference page.
Parameter | Documentation |
|---|---|
customerId | |
sourceId | |
currency | |
state | |
locale | |
shipTo | |
discount | |
collectionPeriodDays | |
billingOptimization | |
items | |
taxInclusive | |
taxIdentifiers | |
chargeType | |
customerType | |
upstreamId |
To open an already created invoice, send a
POST/invoices/{id}/open. Only draft invoices can be opened. So, before sending the request, make you first determine the invoice's state.Once opened, none of an invoice's attributes, other than
metadata, can be updated. If you need to update customer or amount attributes, then void the invoice and create a new one.To void an invoice, send a
POST/invoices/{id}/void request . This operation is similar to deleting an invoice but it allows you to maintain a record of when the invoice was created, opened, and voided.Invoices in a voided 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'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:Error
{
"type": "conflict",
"errors": [
{
"code": "invalid_state",
"parameter": "state",
"message": "Invoice 4fce39e4549845cf9d571a7676842a90 is not open. Only open invoices can be voided."
}
]
}
To permanently delete an invoice, send a
DELETE/invoices/{id} request . This operation is similar to voiding an invoice but no record is maintained for accounting purposes. Only draft invoices can be deleted.Use the Refunds API to refund charges that are captured when an invoice is paid. To partially or fully refund the invoice, send its
invoiceId in a POST/refunds.Once you move an invoice's
state to open, Digital River initiates a billing process and attempts to capture the charge(s). With invoices, you can take advantage of our billing optimization feature. If you use this feature, make sure your integration only displays payment methods that are supported with invoices.The Invoices API contains billing features that are not available in the Checkouts API. To use them, set
billingOptimization to true. This setting prompts Digital River to make multiple payment capture attempts throughout the billing period, the length of which you can configure by setting collectionPeriodDays (the default setting is 30).If Digital River successfully capture 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 has no effect on 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.An expired credit card, insufficient funds, or a closed credit card account are all common reasons for an uncollectible invoice.
If you set
billingOptimization to false, then you can allow customers to use any supported payment method to pay an invoice. This includes combining a primary source with one or more secondary sources.If
billingOptimization is true, then an invoice's payment.sources[] should only contain a single source. Additionally, that object must be a primary source and it must support reusability. So, if you're using the billing optimization feature, restrict customers to payment methods that can be used in recurring transactions.An invoice has a defined lifecycle. Each time the state of an invoice changes, Digital River creates a corresponding event.
An invoice has the following states:
draft, open, paid, uncollectible, or void.Invoices in a
draft state can either be opened, which both transitions them to an open state and initiates the billing process, or they can be deleted 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.The
state values for a successful invoice (i.e. the happy path) are draft > open > paid .When the state of an invoice changes, an event 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 are emitted.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 |
Last modified 6mo ago