Invoice intents and offers

An invoice intent says: "I have an invoice like this and I am thinking of selling it. What can you offer?" You describe the invoice, and Invoier answers with financing offers. Nothing is sold until you create an invoice from the intent.

That makes the intent useful for two different things:

You want to	Use
Show your user a price, without selling anything	a temporary intent
Sell the invoice	a regular intent, followed by `POST /invoices`

What you send

An intent needs three things:

amount with currency and value.
debtor.customerId, the customer that owes the money.
A time: either duration in days, or invoiceDate together with dueDate.

{
  "invoiceIntent": {
    "amount": { "currency": "SEK", "value": 10000 },
    "debtor": { "customerId": "59579f8a-ee7e-11ed-87be-0336f75f8fb6" },
    "duration": 30
  }
}

You cannot give duration together with dueDate, and dueDate has to be after invoiceDate. With only duration, the invoice date is taken to be today.

Sending the same request again returns the intent that already exists. Add your own idempotencyToken if you want two intents for the same amount, customer and time.

Offers

The answer contains financing.offers. Each offer says what Invoier would pay and what it costs.

Field	Meaning
`financedAmount`	How much you get paid up front
`financingCost`	What financing costs, excluding VAT. `vat` is the VAT on top of that
`terms.durationInDays`	The time the offer is for
`terms.fees`	How the cost is made up, such as a `YEARLY_INTEREST` in percent and a `FIXED` fee
`terms.financingRatio`	The share of the invoice that is financed
`terms.requiresManualReview`	Whether a person at Invoier has to look at the invoice before it is financed
`offerType`	`INDICATIVE_BID` means an estimate. It is not a promise

The first offer comes back immediately and is an indication. More offers can arrive during the next seconds as Invoier collects them, so the offers you see just after creating an intent can differ from the final ones.

Waiting for the final offers

Poll GET /invoice-intents/{invoiceIntentId} until invoiceIntentStatus is COMPLETED. It takes at most about a minute. Before that the status is COLLECTING_OFFERS, or in some setups PENDING_FINANCING_OFFERS and COLLECTING_FINANCING_OFFERS. Treat anything other than COMPLETED as still working.

curl "$BASE_URL/invoice-intents/$INTENT_ID" -H "Authorization: $API_KEY"

If you only need a number to show, you can show the first offer straight away and refresh it when the status is COMPLETED.

Temporary intents: price checks

Add "invoiceIntentType": "TEMPORARY" to ask for a price without any commitment.

{
  "invoiceIntent": {
    "invoiceIntentType": "TEMPORARY",
    "amount": { "currency": "SEK", "value": 10000 },
    "debtor": { "customerId": "59579f8a-ee7e-11ed-87be-0336f75f8fb6" },
    "duration": 30
  }
}

A temporary intent:

gets offers in the same way as a regular one,
gets no attachment targets, since there is nothing to send,
is only guaranteed to be kept for an hour, and
cannot be used to create an invoice. Creating one from it is a 400.

When your user decides to sell, create a regular intent (without invoiceIntentType) and continue from there. The offers can differ from the ones you showed, so show the final terms before the user agrees.

From intent to invoice

A regular intent also gets attachmentTargets, which is where you send the invoice PDF, see Attachments. After that, POST /invoices with the invoiceIntentId creates the invoice.

If you and your user agree on a financing cost, you can state it as an ask when you create the invoice: financing.offers with one entry, financingCost and optionally financedAmount. Both are capped at the invoice amount and must use the invoice currency. Invoier receives your ask next to the offers it has collected.

Seeing your intents

GET /invoice-intents lists them, newest first, and GET /invoice-intents/{invoiceIntentId} fetches one. metadata is yours to use, for example for your own invoice number.