MOmollie
Sales Invoices API

Update sales invoice

Changed on

Certain details of an existing sales invoice can be updated. For draft it is all values listed below, but for statuses paid and issued there are certain additional requirements (paymentDetails and emailDetails, respectively).

patch/v2/sales-invoices/{salesInvoiceId}

Request

  • Base URL
    https://api.mollie.com
  • URL
    https://api.mollie.com/v2/sales-invoices/{salesInvoiceId}
  • Auth
    • HTTP bearer
    • or HTTP bearer
    • or OAuth 2
      Authorization code: https://my.mollie.com/oauth2/authorize
      Token URL: https://api.mollie.com/oauth2/tokens scopes: sales-invoices.write

Headers

idempotency-keystring
Example:123e4567-e89b-12d3-a456-426

A unique key to ensure idempotent requests. This key should be a UUID v4 string.

Request body

testmodeboolean nullable

Whether the entity was created in test mode or live mode. This field does not update the mode of the entity.

Most API credentials are specifically created for either live mode or test mode, in which case this parameter must not be sent. For organization-level credentials such as OAuth access tokens, you can enable test mode by setting testmode to true.

status'draft' | 'issued' | 'paid' | 'cancelled' | 'payment-reversed'

The status for the invoice to end up in.

A draft invoice is not paid or not sent and can be updated after creation. Setting it to issued sends it to the recipient so they may then pay through our payment system. To skip our payment process, set this to paid to mark it as paid. It can then subsequently be sent as well, same as with issued.

Dependent parameters:

  • paymentDetails is required if invoice should be set directly to paid
  • customerId and mandateId are required if a recurring payment should be used to set the invoice to paid
  • emailDetails optional for issued and paid to send the invoice by email
memostring nullable

A free-form memo you can set on the invoice, and will be shown on the invoice PDF.

paymentTerm'7 days' | '14 days' | '30 days' | '45 days' | '60 days' | '90 days' | '120 days' nullable

The payment term to be set on the invoice.

recipientIdentifierstring

An identifier tied to the recipient data. This should be a unique value based on data your system contains, so that both you and us know who we're referring to. It is a value you provide to us so that recipient management is not required to send a first invoice to a recipient.

isEInvoiceboolean

This indicates whether the invoice is an e-invoice. The default value is false and can't be changed after the invoice has been issued. When emailDetails is provided, an additional email is sent to the recipient.

E-invoicing is only available for merchants based in Belgium, Germany, and the Netherlands, and only when the recipient is also located in one of these countries.

When set to true, the invoice will be delivered via the Peppol network. In this case, the organizationNumber or vatNumber provided must match the identifier the recipient is actually registered with on Peppol, otherwise delivery will fail. Note: for recipients in Germany, the vatNumber is the required identifier for Peppol registration.

Example request

{
  "status": "draft",
  "memo": "An updated memo!",
  "paymentTerm": "30 days",
  "paymentDetails": {
    "source": "payment-link",
    "sourceReference": "pl_d9fQur83kFdhH8hIhaZfq"
  },
  "emailDetails": {
    "subject": "Your invoice is available",
    "body": "Please find your invoice enclosed."
  },
  "recipientIdentifier": "customer-xyz-0123",
  "recipient": {
    "type": "consumer",
    "title": "Mrs.",
    "givenName": "Jane",
    "familyName": "Doe",
    "organizationName": "Organization Corp.",
    "organizationNumber": "12345678",
    "vatNumber": "NL123456789B01",
    "email": "example@email.com",
    "phone": "+0123456789",
    "streetAndNumber": "Keizersgracht 126",
    "streetAdditional": "4th floor",
    "postalCode": "5678AB",
    "city": "Amsterdam",
    "region": "Noord-Holland",
    "country": "NL",
    "locale": "nl_NL"
  },
  "lines": [
    {
      "description": "LEGO 4440 Forest Police Station",
      "quantity": 1,
      "vatRate": "21.00",
      "unitPrice": {
        "currency": "EUR",
        "value": "10.00"
      },
      "discount": {
        "type": "amount",
        "value": "10.00"
      }
    }
  ],
  "discount": {
    "type": "amount",
    "value": "10.00"
  }
}

Response

The sales invoice object.

resourcestring required

Indicates the response contains a sales invoice object. Will always contain the string sales-invoice for this endpoint.

idstring required
mode'live' | 'test' required

Whether this entity was created in live mode or in test mode.

testmodeboolean nullable

Whether to create the entity in test mode or live mode.

Most API credentials are specifically created for either live mode or test mode, in which case this parameter must not be sent. For organization-level credentials such as OAuth access tokens, you can enable test mode by setting testmode to true.

invoiceNumberstring nullable

When issued, an invoice number will be set for the sales invoice.

profileIdstring nullable

The identifier referring to the profile this entity belongs to.

Most API credentials are linked to a single profile. In these cases the profileId must not be sent in the creation request. For organization-level credentials such as OAuth access tokens however, the profileId parameter is required.

status'draft' | 'issuing' | 'issued' | 'pending-payment' | 'paid' | 'overdue' | 'payment-reversed' | 'cancelled' | 'expired' | 'failed'

The current status of the invoice.

eInvoiceStatus'issuing' | 'issued' | 'failed'

The e-invoice submission status for the invoice, if it was configured to be an e-invoice.

vatScheme'standard' | 'one-stop-shop'

The VAT scheme to create the invoice for. You must be enrolled with One Stop Shop enabled to use it.

vatMode'exclusive' | 'inclusive'

The VAT mode to use for VAT calculation. exclusive mode means we will apply the relevant VAT on top of the price. inclusive means the prices you are providing to us already contain the VAT you want to apply.

memostring nullable

A free-form memo you can set on the invoice, and will be shown on the invoice PDF.

metadataobject nullable

Provide any data you like as a JSON object. We will save the data alongside the entity. Whenever you fetch the entity with our API, we will also include the metadata. You can use up to approximately 1kB.

paymentTerm'7 days' | '14 days' | '30 days' | '45 days' | '60 days' | '90 days' | '120 days' nullable

The payment term to be set on the invoice.

customerIdstring

The identifier referring to the customer you want to attempt an automated payment for. If provided, mandateId becomes required as well. Only allowed for invoices with status paid.

mandateIdstring

The identifier referring to the mandate you want to use for the automated payment. If provided, customerId becomes required as well. Only allowed for invoices with status paid.

recipientIdentifierstring

An identifier tied to the recipient data. This should be a unique value based on data your system contains, so that both you and us know who we're referring to. It is a value you provide to us so that recipient management is not required to send a first invoice to a recipient.

isEInvoiceboolean

This indicates whether the invoice is an e-invoice. The default value is false and can't be changed after the invoice has been issued. When emailDetails is provided, an additional email is sent to the recipient.

E-invoicing is only available for merchants based in Belgium, Germany, and the Netherlands, and only when the recipient is also located in one of these countries.

When set to true, the invoice will be delivered via the Peppol network. In this case, the organizationNumber or vatNumber provided must match the identifier the recipient is actually registered with on Peppol, otherwise delivery will fail. Note: for recipients in Germany, the vatNumber is the required identifier for Peppol registration.

createdAtstring

The entity's date and time of creation, in ISO 8601 format.

issuedAtstring nullable

If issued, the date when the sales invoice was issued, in ISO 8601 format.

paidAtstring nullable

If paid, the date when the sales invoice was paid, in ISO 8601 format.

dueAtstring nullable

If issued, the date when the sales invoice payment is due, in ISO 8601 format.

Example response

{
  "resource": "sales-invoice",
  "id": "invoice_4Y0eZitmBnQ6IDoMqZQKh",
  "mode": "live",
  "invoiceNumber": "INV-0000001",
  "profileId": "pfl_QkEhN94Ba",
  "status": "draft",
  "eInvoiceStatus": "issuing",
  "vatScheme": "standard",
  "vatMode": "exclusive",
  "memo": "This is a memo!",
  "paymentTerm": "30 days",
  "paymentDetails": [
    {
      "source": "payment-link",
      "sourceReference": "pl_d9fQur83kFdhH8hIhaZfq"
    }
  ],
  "emailDetails": {
    "subject": "Your invoice is available",
    "body": "Please find your invoice enclosed."
  },
  "customerId": "cst_8wmqcHMN4U",
  "mandateId": "mdt_pWUnw6pkBN",
  "recipientIdentifier": "customer-xyz-0123",
  "recipient": {
    "type": "consumer",
    "title": "Mrs.",
    "givenName": "Jane",
    "familyName": "Doe",
    "organizationName": "Organization Corp.",
    "organizationNumber": "12345678",
    "vatNumber": "NL123456789B01",
    "email": "example@email.com",
    "phone": "+0123456789",
    "streetAndNumber": "Keizersgracht 126",
    "streetAdditional": "4th floor",
    "postalCode": "5678AB",
    "city": "Amsterdam",
    "region": "Noord-Holland",
    "country": "NL",
    "locale": "nl_NL"
  },
  "lines": [
    {
      "description": "LEGO 4440 Forest Police Station",
      "quantity": 1,
      "vatRate": "21.00",
      "unitPrice": {
        "currency": "EUR",
        "value": "10.00"
      },
      "discount": {
        "type": "amount",
        "value": "10.00"
      }
    }
  ],
  "discount": {
    "type": "amount",
    "value": "10.00"
  },
  "amountDue": {
    "currency": "EUR",
    "value": "10.00"
  },
  "subtotalAmount": {
    "currency": "EUR",
    "value": "10.00"
  },
  "totalAmount": {
    "currency": "EUR",
    "value": "10.00"
  },
  "totalVatAmount": {
    "currency": "EUR",
    "value": "10.00"
  },
  "discountedSubtotalAmount": {
    "currency": "EUR",
    "value": "10.00"
  },
  "createdAt": "2024-03-20T09:13:37+00:00",
  "issuedAt": "2024-10-03T10:47:38+00:00",
  "paidAt": "2024-10-04T10:47:38+00:00",
  "dueAt": "2024-11-01T10:47:38+00:00",
  "_links": {
    "self": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "invoicePayment": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "pdfLink": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "documentation": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "next": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "previous": {
      "href": "https://...",
      "type": "application/hal+json"
    }
  }
}

Changes

  • 01847046d5d0Revision changes
    • breaking

      removed the enum value payment_reversed of the request property ////

    • warning

      added the new payment-reversed enum value to the / response property for the response status

    • info

      added the new payment-reversed enum value to the request property ////

    • info

      removed the payment_reversed enum value from the / response property for the response status

  • e7490e43bca3Revision changes
    • info

      added the new payment_reversed enum value to the request property ////