LogoLogo
System Status
2021-12-13
2021-12-13
  • 2021-12-13
  • Charges
    • Charge basics
  • Checkouts
  • Country specifications
  • Customers
  • Events
  • Fees
  • File Links
    • File link basics
  • Files
    • File basics
  • Fulfillments
  • Fulfillment cancellations
  • Fulfillment orders
  • Fulfillment returns
  • Inventory items
  • Inventory levels
  • Invoices
    • Invoice basics
  • Logistics returns
  • Orders
    • Order basics
  • Payouts
  • Plans
    • Plan basics
  • Refunds
  • Reservations
  • Returns
  • Sales summaries
  • Sales transactions
  • Shipments
  • Shipping labels
  • Shipping quotes
  • SKUs
  • SKU Groups
  • Sources
  • Subscriptions
    • Subscription basics
  • Tax identifiers
  • Webhooks
  • Drop-in checkout links
  • Drop-in checkout sessions
    • Checkout-sessions basics
  • Drop-in shipping quotes
  • Store credit callout
Powered by GitBook
On this page
  • Managing invoices
  • Deleting an invoice
  • Refunding an invoice
  • Invoice billing
  • Billing optimization
  • Supported payment methods with invoices
  • The invoice lifecycle
  • Invoice states
  • Invoice events
  1. Invoices

Invoice basics

Learn more about the invoices resource

PreviousInvoicesNextLogistics returns

Last updated 2 months ago

The is only available in versions 2020-09-30 and higher.

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 to . This API allows you to for one-off transactions or to set up subscriptions and start billing them.

If you integrate with the , we recommend you familiarize yourself with the and .

Managing invoices

You can , , , and invoices. The process of on invoices is entirely handled by Digital River. After an invoice is paid, you can use the to any needed refunds.

Creating an invoice

In a request, you can set state to either draft or open. The default value is open.

If you'd like us to immediately start the , 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 . The major difference is that invoices allow you to . 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 reference page.

Parameter
Documentation

customerId

sourceId

currency

state

locale

shipTo

discount

collectionPeriodDays

billingOptimization

items

taxInclusive

taxIdentifiers

chargeType

customerType

upstreamId

Opening an invoice

Voiding an invoice

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:

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

Deleting an invoice

Refunding an invoice

Invoice billing

Billing optimization

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.

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

Supported payment methods with invoices

The invoice lifecycle

Invoice states

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

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 .

Invoice events

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

and

To open an already created invoice, send a . 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 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, and create a new one.

To void an invoice, send a request. This operation is similar to deleting an invoice but allows you to record when the invoice was created, opened, and voided.

To permanently delete an invoice, send a request. This operation is similar to , but no record is maintained for accounting purposes. Only draft invoices can be deleted.

Use the to refund when an invoice is paid. To partially or fully refund the invoice, send its invoiceId in a POST /refunds.

Once you move an state to open, Digital River initiates a billing process and attempts to . With invoices, you can take advantage of our . If you use this feature, ensure your integration only displays .

The contains billing features unavailable in the . To use them, set billingOptimization to true. This setting prompts Digital River to make multiple throughout the billing period, the length of which you can configure by setting collectionPeriodDays (the default setting is 30).

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 .

If you set to false, then you can allow customers to use any to pay an . This includes combining.

If billingOptimization is true, then an payment.sources[] should only contain a single . Additionally, that object must be a and support . 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 page for a complete list of such payment methods.

An invoice has a defined lifecycle. Each time the changes, Digital River creates a corresponding .

Invoices in a draft state can either be , which transitions them to an open state and initiate the , or they can be entirely.

When the changes, an 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
billing process
void the invoice
emit the corresponding event
state of an invoice
event
opened
billing process
deleted
event
state of an invoice
Registered invoices
The invoice lifecycle
Invoice billing
Invoice billing optimization
invoice API
Invoices API
create invoices
Invoices API
Refunds API
checkouts
optimize billing
Invoices API
manage invoices
invoice lifecycle
billing process
create
open
void
delete
collecting payment
issue refunds
billing process
Refunds API
charges
invoice's
billing optimization feature
payment methods supported with invoices
Invoices API
Checkouts API
invoice
billingOptimization
invoice's
source
voiding an invoice
POST /invoices
POST /invoices/{id}/open
POST /invoices/{id}/void
DELETE/invoices/{id}
captured
capture the charge(s)
payment capture attempts
supported payment method
a primary source with one or more secondary sources
primary source
reusability
Supported payment methods
Supported payment methods
Managing sources
Selecting a currency
Designating a locale
Ship to address
Checkout level discount
Describing the items
Configuring taxes
Tax identifiers
Initiating a charge
Setting the customer type
Providing an upstream identifier