Selling an invoice

From customer to invoice in four steps.

This guide takes an invoice from your invoicing system to Invoier in four steps. The requests need the key of an onboarded account, and use $BASE_URL for your base URL.

Text

POST /customers ► POST /invoice-intents ► (send the PDF) ► POST /invoices

See Invoice intents and offers and Attachments for the details behind steps 2 and 3.

1. Register the customer

The customer is the company that owes the money, the debtor. Register it with its organisation number. A Swedish organisation number may be written with or without a dash.

Bash

curl -X POST "$BASE_URL/customers" \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "nationalOrgNumber": { "country": "SE", "orgNumber": "559146-3327" },
      "metadata": { "myCustomerNumber": 8 }
    }
  }'

The response contains the customerId that you need next. If the customer already exists it is returned with 200, so you can call this every time you sell an invoice to a company.

2. Create an invoice intent

An invoice intent tells Invoier what you plan to sell. Give it the amount, the debtor and either a duration in days or an invoiceDate together with a dueDate.

Bash

curl -X POST "$BASE_URL/invoice-intents" \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceIntent": {
      "amount": { "currency": "SEK", "value": 1000 },
      "debtor": { "customerId": "59579f8a-ee7e-11ed-87be-0336f75f8fb6" },
      "duration": 30
    }
  }'

Sending the same request again returns the intent you already created. You cannot send dueDate and duration together, and dueDate must be after invoiceDate. An unknown customerId is a 400.

The response contains:

• invoiceIntentId and invoiceIntentStatus, which is COLLECTING_OFFERS at first (some setups use PENDING_FINANCING_OFFERS and COLLECTING_FINANCING_OFFERS).
• financing.offers, with financedAmount, financingCost and terms. The first offer is indicative.
• attachmentTargets, which says where to send the invoice PDF, see step 3.

Wait for the final offers

More offers arrive in the background, so poll GET /invoice-intents/{invoiceIntentId} until invoiceIntentStatus is COMPLETED. That takes at most about a minute. Show the offers to your user, and continue when they accept. To only show a price without selling, use a temporary intent, see Invoice intents and offers.

3. Send the invoice PDF

Create the invoice in your own invoicing system, and deliver the PDF to one of the attachmentTargets of the invoice intent. Which targets you get depends on your setup.

Target	How to use it
Email (emailAddress)	Put the address in BCC when you send the invoice. This is the simplest way.
Url (url)	Upload the file to the url. For a presigned form, post the file together with all returned fields.

Every target has an expiresAt. It is when the target stops working, not the invoice. Email addresses last 7 days and upload urls 5 days. A file can be at most 20 MB.

The transferNotice of a target is a text that must appear in the invoice PDF, which is how the invoice is recognised.

4. Create the invoice

When the PDF has been sent, create the invoice from the intent.

Bash

curl -X POST "$BASE_URL/invoices" \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice": {
      "invoiceIntentId": "<invoiceIntentId>",
      "reference": "2024-0001",
      "addresses": [
        { "labels": ["contact"], "emailAddress": "[email protected]",
          "phoneNumber": "[phone]" },
        { "labels": ["billing"], "emailAddress": "[email protected]" }
      ]
    }
  }'

• invoiceIntentId is the only required field.
• reference is usually the invoice number. It has to be unique, and casing is ignored.
• transactionReference is optional, for example an OCR number.
• The invoice needs a contact address with an emailAddress. You can add billing addresses as well.
• If you send invoiceDate and dueDate they must match the duration of the invoice intent.

If an invoice already exists for the intent you get 200 and the existing invoice.

Follow the invoice

Poll GET /invoices/{invoiceId} and read invoiceStatus. It is AWAITING_ATTACHMENTS until the PDF has been received and READY after that. The invoice then goes through review and ends up FINANCED or NOT_FINANCED. GET /invoices can be filtered on invoiceStatus, and GET /invoices/{invoiceId}/attachments/{attachmentId} downloads an attachment.

To withdraw an invoice, call DELETE /invoices/{invoiceId}.