Skip to content
/
Void an invoice

Adfin API (1.0.0)

Adfin uses OAuth 2.0 access tokens to authenticate all API requests.

There are two contexts in which tokens are issued:

  • Biller Access Tokens — Generated via the Authorization Code flow when a biller connects their Adfin account. These tokens grant access to that biller's data (invoices, payment requests, customers, etc.).

  • Platform Access Tokens — Generated via the Client Credentials flow for Adfin's own integrations and system events. These tokens authenticate Adfin as the platform itself (not as a specific biller) and are required for endpoints like /api/webhook.

Download OpenAPI description
prod.json
prod.yaml
Languages
Servers
Mock server
https://developer.adfin.com/_mock/api-docs/prod/
Production API Server URL
https://api.adfin.com/api/
Staging API Server URL
https://api.staging.adfin.com/api/

oAuth2

Operations

Biller

Operations

Customers

Operations

Direct debit mandates

Operations

Invoices

Operations

Get an invoice by its id

Request

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Path
idstringrequired

The id of the invoice to get the details for

curl -i -X GET \
  'https://developer.adfin.com/_mock/api-docs/prod/invoices/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The Invoice data is successfully retrieved

Bodyapplication/json
idstring

The internal id of the invoice

invoiceNostring

The number of the invoice. Can be empty when creating the invoice without an invoice number,but it will be automatically generated when the invoice is pushed to an accounting software. Once set, serves as a unique value that can be used as an idempotency key.

descriptionstring

Short description of the invoice

totalAmountstring

The invoice total amount. Includes tax amount, amount paid or reduced with credit notes)

taxAmountstring

The invoice tax amount.

dueAmountstring

The invoice amount due (remaining to be paid).

creditNotesAmountstring

The total amount that is credited.

dueDatestring(date-time)

The due date of the invoice

issueDatestring(date-time)

The issue date date of the invoice

creationTimestring(date-time)

The date the invoice was created

lastUpdatedTimestring(date-time)

The date the invoice was last updated

paidTimestring(date-time)

The date the invoice was paid

statusstring

The invoice status

Enum"DRAFT""UNPAID""OVERDUE""SCHEDULED""SUBMITTED""PAID""VOID""SETTLED"
statusReasonCodestring

The reason as predefined code why the invoice is in a certain status

Enum"MISSING_PAYER_CONTACT_DETAILS""PENDING_ACTIVATION""PENDING_DD_MANDATE""PENDING_DD_CAPABILITY""MARKED_AS_PAID""WORKFLOW_COMPLETED""NOTIFICATION_DELIVERY_FAILED""BULK_PRUNE""STALE_DRAFT_CLEANUP""OTHER"
statusReasonstring

Custom details on why the invoice is in a certain status

invoiceSourcestring

The source of the invoice

Enum"FILE_UPLOAD""MANUAL""PR""EXTERNAL""SCHEDULE""PLATFORM"
customerobject(CustomerResponse)
itemsTaxTypestring

How tax is applied to line items from the invoice

Enum"EXCLUSIVE""INCLUSIVE""NONE"
instalmentPlanDetailsobject(InstalmentPlanDetails)
itemsArray of objects(LineItemResponse)

The list of items from the invoice

paymentRequestsArray of objects(PaymentRequestDetails)

The payment requests that were created for this invoice

scheduleDetailsobject(ScheduleDetails)
creditNotesArray of objects(CreditNoteResponse)

The list of credit notes from the invoice

fileSourcestring

The file source of invoice

Enum"NONE""FILE_UPLOAD""EXTERNAL""ADFIN""PENDING_ADFIN"
externalDataArray of objects(InvoiceExternalData)

References about this invoice from external platforms Adfin integrates with. Such as ID etc

creditControlStatusstring

The credit control status of the invoice

Enum"AT_RISK""EXPECTED""CONFIRMED"
workflowTypestring

The workflow type of the invoice

Enum"AUTO_COLLECT""ON_DEMAND""NONE"
customFieldsArray of objects(CustomField)

The list of custom fields that are applied to the invoice

officeobject(InvoiceOfficeResponse)
Response
application/json
{
  "id": "string",
  "invoiceNo": "string",
  "description": "string",
  "totalAmount": "string",
  "taxAmount": "string",
  "dueAmount": "string",
  "creditNotesAmount": "string",
  "dueDate": "2019-08-24T14:15:22Z",
  "issueDate": "2019-08-24T14:15:22Z",
  "creationTime": "2019-08-24T14:15:22Z",
  "lastUpdatedTime": "2019-08-24T14:15:22Z",
  "paidTime": "2019-08-24T14:15:22Z",
  "status": "DRAFT",
  "statusReasonCode": "MISSING_PAYER_CONTACT_DETAILS",
  "statusReason": "string",
  "invoiceSource": "FILE_UPLOAD",
  "customer": {
    "id": "string",
    "externalId": "string",
    "name": "string",
    "creationTime": "2019-08-24T14:15:22Z",
    "lastUpdatedTime": "2019-08-24T14:15:22Z",
    "people": [ … ],
    "addresses": [ … ],
    "directDebitMandate": { … },
    "billerBankAccount": { … },
    "timezone": "string",
    "discount": { … },
    "externalData": [ … ],
    "tags": [ … ],
    "status": "ACTIVE",
    "statusReasonCode": "MERGED",
    "settings": { … },
    "trackingItems": [ … ],
    "office": { … }
  },
  "itemsTaxType": "EXCLUSIVE",
  "instalmentPlanDetails": {
    "cadence": { … }
  },
  "items": [
    { … }
  ],
  "paymentRequests": [
    { … }
  ],
  "scheduleDetails": {
    "scheduleId": "string",
    "scheduleNo": "string",
    "type": "RECURRING"
  },
  "creditNotes": [
    { … }
  ],
  "fileSource": "NONE",
  "externalData": [
    { … }
  ],
  "creditControlStatus": "AT_RISK",
  "workflowType": "AUTO_COLLECT",
  "customFields": [
    { … }
  ],
  "office": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "trackingItemId": "c7c7fc03-0b17-402e-aa79-1d532a6db210",
    "details": { … }
  }
}

Update an invoice

Request

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Path
idstringrequired

The id of the invoice being updated

Bodyapplication/jsonrequired
invoiceNostring

The unique number of the invoice. Acts as an idempotency key.

Example: "INV-12345"
customerobject(CustomerDetails)
Example: "80349480-490b-4234-92e7-fad697e3d446"
descriptionstring

A short description or summary of the invoice.

Example: "Monthly subscription fee for January"
dueDatestring(date-time)

The due date for the invoice payment.

Example: "2025-12-15T23:59:59Z"
issueDatestring(date-time)

The date the invoice is issued.

Example: "2025-12-15T09:00:00Z"
itemsTaxTypestring

How tax is applied to line items from the invoice

Enum"EXCLUSIVE""INCLUSIVE""NONE"
itemsArray of objects(UpdateLineItemRequest)

The list of items included in this invoice.

instalmentPlanDetailsobject(InstalmentPlanDetails)
paymentRequestsArray of objects(UpdatePaymentRequestDetails)

Details for the invoice's payment requests. Only required for invoices with multiple payment requests (ex: instalments).

officeIdstring(uuid)

The unique identifier of the office associated with this invoice.

Example: "80349480-490b-4234-92e7-fad697e3d446"
curl -i -X PUT \
  'https://developer.adfin.com/_mock/api-docs/prod/invoices/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "invoiceNo": "INV-12345",
    "customer": {
      "id": "80349480-490b-4234-92e7-fad697e3d446"
    },
    "description": "Monthly subscription fee for January",
    "dueDate": "2025-12-15T23:59:59Z",
    "issueDate": "2025-12-15T09:00:00Z",
    "itemsTaxType": "EXCLUSIVE",
    "items": [
      {
        "id": "string",
        "description": "string",
        "unitAmount": 0,
        "quantity": 0,
        "taxRate": 0,
        "taxRateId": "string",
        "accountCodeId": "string",
        "productId": "string",
        "externalData": [
          {
            "id": "string",
            "connectorType": "XERO",
            "templateId": "string",
            "accountCode": "string"
          }
        ],
        "trackingItemIds": [
          "497f6eca-6276-4993-bfeb-53cbbbba6f08"
        ]
      }
    ],
    "instalmentPlanDetails": {
      "cadence": {
        "type": "INTERVAL",
        "timeUnit": "SECOND",
        "frequency": 1,
        "dayOfMonth": 0,
        "dates": [
          "2019-08-24T14:15:22Z"
        ],
        "startDate": "2019-08-24T14:15:22Z",
        "endDate": "2019-08-24T14:15:22Z",
        "count": 2
      }
    },
    "paymentRequests": [
      {
        "id": "3d6be112-2825-4ee6-8287-ea9171e20b36",
        "amount": 100,
        "payByDate": "2025-03-25T11:36:55.243Z"
      }
    ],
    "officeId": "80349480-490b-4234-92e7-fad697e3d446"
  }'

Responses

The request was successful and the invoice was updated.

Bodyapplication/json
idstring

The internal id of the invoice

invoiceNostring

The number of the invoice. Can be empty when creating the invoice without an invoice number,but it will be automatically generated when the invoice is pushed to an accounting software. Once set, serves as a unique value that can be used as an idempotency key.

descriptionstring

Short description of the invoice

totalAmountstring

The invoice total amount. Includes tax amount, amount paid or reduced with credit notes)

taxAmountstring

The invoice tax amount.

dueAmountstring

The invoice amount due (remaining to be paid).

creditNotesAmountstring

The total amount that is credited.

dueDatestring(date-time)

The due date of the invoice

issueDatestring(date-time)

The issue date date of the invoice

creationTimestring(date-time)

The date the invoice was created

lastUpdatedTimestring(date-time)

The date the invoice was last updated

paidTimestring(date-time)

The date the invoice was paid

statusstring

The invoice status

Enum"DRAFT""UNPAID""OVERDUE""SCHEDULED""SUBMITTED""PAID""VOID""SETTLED"
statusReasonCodestring

The reason as predefined code why the invoice is in a certain status

Enum"MISSING_PAYER_CONTACT_DETAILS""PENDING_ACTIVATION""PENDING_DD_MANDATE""PENDING_DD_CAPABILITY""MARKED_AS_PAID""WORKFLOW_COMPLETED""NOTIFICATION_DELIVERY_FAILED""BULK_PRUNE""STALE_DRAFT_CLEANUP""OTHER"
statusReasonstring

Custom details on why the invoice is in a certain status

invoiceSourcestring

The source of the invoice

Enum"FILE_UPLOAD""MANUAL""PR""EXTERNAL""SCHEDULE""PLATFORM"
customerobject(CustomerResponse)
itemsTaxTypestring

How tax is applied to line items from the invoice

Enum"EXCLUSIVE""INCLUSIVE""NONE"
instalmentPlanDetailsobject(InstalmentPlanDetails)
itemsArray of objects(LineItemResponse)

The list of items from the invoice

paymentRequestsArray of objects(PaymentRequestDetails)

The payment requests that were created for this invoice

scheduleDetailsobject(ScheduleDetails)
creditNotesArray of objects(CreditNoteResponse)

The list of credit notes from the invoice

fileSourcestring

The file source of invoice

Enum"NONE""FILE_UPLOAD""EXTERNAL""ADFIN""PENDING_ADFIN"
externalDataArray of objects(InvoiceExternalData)

References about this invoice from external platforms Adfin integrates with. Such as ID etc

creditControlStatusstring

The credit control status of the invoice

Enum"AT_RISK""EXPECTED""CONFIRMED"
workflowTypestring

The workflow type of the invoice

Enum"AUTO_COLLECT""ON_DEMAND""NONE"
customFieldsArray of objects(CustomField)

The list of custom fields that are applied to the invoice

officeobject(InvoiceOfficeResponse)
Response
application/json
{
  "id": "string",
  "invoiceNo": "string",
  "description": "string",
  "totalAmount": "string",
  "taxAmount": "string",
  "dueAmount": "string",
  "creditNotesAmount": "string",
  "dueDate": "2019-08-24T14:15:22Z",
  "issueDate": "2019-08-24T14:15:22Z",
  "creationTime": "2019-08-24T14:15:22Z",
  "lastUpdatedTime": "2019-08-24T14:15:22Z",
  "paidTime": "2019-08-24T14:15:22Z",
  "status": "DRAFT",
  "statusReasonCode": "MISSING_PAYER_CONTACT_DETAILS",
  "statusReason": "string",
  "invoiceSource": "FILE_UPLOAD",
  "customer": {
    "id": "string",
    "externalId": "string",
    "name": "string",
    "creationTime": "2019-08-24T14:15:22Z",
    "lastUpdatedTime": "2019-08-24T14:15:22Z",
    "people": [ … ],
    "addresses": [ … ],
    "directDebitMandate": { … },
    "billerBankAccount": { … },
    "timezone": "string",
    "discount": { … },
    "externalData": [ … ],
    "tags": [ … ],
    "status": "ACTIVE",
    "statusReasonCode": "MERGED",
    "settings": { … },
    "trackingItems": [ … ],
    "office": { … }
  },
  "itemsTaxType": "EXCLUSIVE",
  "instalmentPlanDetails": {
    "cadence": { … }
  },
  "items": [
    { … }
  ],
  "paymentRequests": [
    { … }
  ],
  "scheduleDetails": {
    "scheduleId": "string",
    "scheduleNo": "string",
    "type": "RECURRING"
  },
  "creditNotes": [
    { … }
  ],
  "fileSource": "NONE",
  "externalData": [
    { … }
  ],
  "creditControlStatus": "AT_RISK",
  "workflowType": "AUTO_COLLECT",
  "customFields": [
    { … }
  ],
  "office": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "trackingItemId": "c7c7fc03-0b17-402e-aa79-1d532a6db210",
    "details": { … }
  }
}

Void an invoice

Request

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Path
idstringrequired

The id of the invoice

Bodyapplication/jsonrequired
reasonCodestring
reasonstring
curl -i -X PUT \
  'https://developer.adfin.com/_mock/api-docs/prod/invoices/{id}:void' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "reasonCode": "string",
    "reason": "string"
  }'

Responses

The invoice was voided

Manually mark an invoice as paid

Request

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Path
idstringrequired

The id of the invoice to be marked as paid

curl -i -X PUT \
  'https://developer.adfin.com/_mock/api-docs/prod/invoices/{id}:mark-as-paid' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The invoice was successfully marked as paid

Activate (send) an invoice

Request

Security
Biller Access Token (Production) or Biller Access Token (Staging)
Path
idstringrequired

The id of the invoice

Bodyapplication/jsonrequired
collectionMethodstring

How the payment is expected to be collected for this invoice.

Enum"ONE_TIME_PAYMENT""DIRECT_DEBIT_PAYMENT""NONE"
customMessagestring

An optional message that will be sent to the customer when the invoice is activated.

templateIdstring

The schedule template id used for sending the invoice to customer.

curl -i -X PUT \
  'https://developer.adfin.com/_mock/api-docs/prod/invoices/{id}:activate' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "collectionMethod": "ONE_TIME_PAYMENT",
    "customMessage": "string",
    "templateId": "string"
  }'

Responses

The invoice was activated

Retrieve a list of invoices by filter

Request

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Query
invoiceNostring

The invoice number.

customerIdstring

The id of the customer associated to the invoice.

externalCustomerIdstring

The id of the customer from the platform that is integrating with Adfin.

statusesArray of strings

The status of the invoice.

  • DRAFT: The invoice does not contain contact details for the payer or it is not yet distributed.
  • UNPAID: The invoice is not yet paid.
  • OVERDUE: The invoice is not yet paid and it is passed the due date.
  • SCHEDULED: The invoice is scheduled to collect the payment via Direct Debit.
  • SUBMITTED: The remaining due amount on the invoice is covered by submitted (but not yet confirmed) Direct Debit payments.
  • PAID: The invoice payment has been captured.
  • SETTLED: The invoice is paid out.
  • VOID: The invoice was voided.
statusReasonsArray of strings

The status reason codes of the invoice.

dueStartDatestring(date-time)

The start date after which the invoices due date should be, including the start date.

dueEndDatestring(date-time)

The end date before which the invoices due date should be, including the end date.

issueStartDatestring(date-time)

The start date after which the invoices issue date should be, including the start date.

issueEndDatestring(date-time)

The end date before which the invoices issue date should be, including the end date.

paidStartTimestring(date-time)

The start time after which the invoice was paid, including the paid start time.

paidEndTimestring(date-time)

The end time after which the invoice was paid, including the paid end time.

lastUpdatedStartTimestring(date-time)

The start time after which the invoices last updated time should be, including the start time.

lastUpdatedEndTimestring(date-time)

The end time before which the invoices last updated time should be, including the end time.

paymentLinkLastSeenTimestring(date-time)

The start time before which the payment link was seen.

searchTextstring

The text to search for in the invoices.

includeCountboolean

Whether the response should include details on total count and counts per statuses

creditControlStatusesArray of strings

The credit control status of the invoice.

  • AT_RISK: The invoice is at risk of not being paid.
  • EXPECTED: The invoice is expected to be paid.
  • CONFIRMED: The invoice is paid.
Items Enum"AT_RISK""EXPECTED""CONFIRMED"
cashflowStatusesArray of strings

The cashflow status of the payment request.

  • UNPAID – not yet paid.
  • PROCESSING – expected to be paid.
  • PAID_OUT – already paid out.
Items Enum"UNPAID""PROCESSING""PAID_OUT"
cashflowPeriodStartDatestring(date-time)

Start of the cashflow period (inclusive)

cashflowPeriodEndDatestring(date-time)

End of the cashflow period (inclusive)

directDebitMandateStatusesArray of strings

The direct debit mandate status.

  • NO_MANDATE: invoices linked to customers without a mandate
  • AWAITING_SIGNATURE: invoices linked to customers awaiting signature
  • SIGNED: invoices linked to customers with a signed mandate, but not yet active
  • ACTIVE: invoices linked to customers with an active mandate.
  • MIGRATING: invoices linked to customers with an active mandate which is being migrated to a different payment service provider.
Items Enum"NO_MANDATE""AWAITING_SIGNATURE""SIGNED""ACTIVE""MIGRATING"
workflowTypesArray of strings

The workflow type.

  • AUTO_COLLECT: automatic collection workflow, such as direct debit
  • ON_DEMAND: on demain workflow, such as via open banking and card payments
Items Enum"AUTO_COLLECT""ON_DEMAND""NONE"
minAmountnumber>= 0

amount greater than or equal to

maxAmountnumber>= 0

amount less than or equal to

reviewSessionIdstring

The review session ID to filter invoices by

invoiceIdsArray of strings

List of invoice IDs to filter by

scheduleIdstring

The id of the schedule associated to the invoice.

fieldValueIdsArray of strings

List of field value IDs to filter invoices by their associated field mappings.

pageinteger>= 0

Zero-based page index (0..N)

Default 0
sizeinteger>= 1

The size of the page to be returned

Default 50
sortArray of strings

Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.

Default ["creationTime,DESC"]
curl -i -X GET \
  'https://developer.adfin.com/_mock/api-docs/prod/invoices?invoiceNo=string&customerId=string&externalCustomerId=string&statuses=string&statusReasons=string&dueStartDate=2019-08-24T14%3A15%3A22Z&dueEndDate=2019-08-24T14%3A15%3A22Z&issueStartDate=2019-08-24T14%3A15%3A22Z&issueEndDate=2019-08-24T14%3A15%3A22Z&paidStartTime=2019-08-24T14%3A15%3A22Z&paidEndTime=2019-08-24T14%3A15%3A22Z&lastUpdatedStartTime=2019-08-24T14%3A15%3A22Z&lastUpdatedEndTime=2019-08-24T14%3A15%3A22Z&paymentLinkLastSeenTime=2019-08-24T14%3A15%3A22Z&searchText=string&includeCount=true&creditControlStatuses=AT_RISK&cashflowStatuses=UNPAID&cashflowPeriodStartDate=2019-08-24T14%3A15%3A22Z&cashflowPeriodEndDate=2019-08-24T14%3A15%3A22Z&directDebitMandateStatuses=NO_MANDATE&workflowTypes=AUTO_COLLECT&minAmount=0&maxAmount=0&reviewSessionId=string&invoiceIds=string&scheduleId=string&fieldValueIds=string&page=0&size=50&sort=creationTime%2CDESC' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The list of invoices for the specified filter.

Bodyapplication/json
idstring

The internal id of the invoice

invoiceNostring

The number of the invoice. Can be empty when creating the invoice without an invoice number,but it will be automatically generated when the invoice is pushed to an accounting software. Once set, serves as a unique value that can be used as an idempotency key.

descriptionstring

Short description of the invoice

totalAmountstring

The invoice total amount. Includes tax amount, amount paid or reduced with credit notes)

taxAmountstring

The invoice tax amount.

dueAmountstring

The invoice amount due (remaining to be paid).

creditNotesAmountstring

The total amount that is credited.

dueDatestring(date-time)

The due date of the invoice

issueDatestring(date-time)

The issue date date of the invoice

creationTimestring(date-time)

The date the invoice was created

lastUpdatedTimestring(date-time)

The date the invoice was last updated

paidTimestring(date-time)

The date the invoice was paid

statusstring

The invoice status

Enum"DRAFT""UNPAID""OVERDUE""SCHEDULED""SUBMITTED""PAID""VOID""SETTLED"
statusReasonCodestring

The reason as predefined code why the invoice is in a certain status

Enum"MISSING_PAYER_CONTACT_DETAILS""PENDING_ACTIVATION""PENDING_DD_MANDATE""PENDING_DD_CAPABILITY""MARKED_AS_PAID""WORKFLOW_COMPLETED""NOTIFICATION_DELIVERY_FAILED""BULK_PRUNE""STALE_DRAFT_CLEANUP""OTHER"
statusReasonstring

Custom details on why the invoice is in a certain status

invoiceSourcestring

The source of the invoice

Enum"FILE_UPLOAD""MANUAL""PR""EXTERNAL""SCHEDULE""PLATFORM"
customerobject(CustomerResponse)
itemsTaxTypestring

How tax is applied to line items from the invoice

Enum"EXCLUSIVE""INCLUSIVE""NONE"
instalmentPlanDetailsobject(InstalmentPlanDetails)
itemsArray of objects(LineItemResponse)

The list of items from the invoice

paymentRequestsArray of objects(PaymentRequestDetails)

The payment requests that were created for this invoice

scheduleDetailsobject(ScheduleDetails)
creditNotesArray of objects(CreditNoteResponse)

The list of credit notes from the invoice

fileSourcestring

The file source of invoice

Enum"NONE""FILE_UPLOAD""EXTERNAL""ADFIN""PENDING_ADFIN"
externalDataArray of objects(InvoiceExternalData)

References about this invoice from external platforms Adfin integrates with. Such as ID etc

creditControlStatusstring

The credit control status of the invoice

Enum"AT_RISK""EXPECTED""CONFIRMED"
workflowTypestring

The workflow type of the invoice

Enum"AUTO_COLLECT""ON_DEMAND""NONE"
customFieldsArray of objects(CustomField)

The list of custom fields that are applied to the invoice

officeobject(InvoiceOfficeResponse)
Response
application/json
{
  "id": "string",
  "invoiceNo": "string",
  "description": "string",
  "totalAmount": "string",
  "taxAmount": "string",
  "dueAmount": "string",
  "creditNotesAmount": "string",
  "dueDate": "2019-08-24T14:15:22Z",
  "issueDate": "2019-08-24T14:15:22Z",
  "creationTime": "2019-08-24T14:15:22Z",
  "lastUpdatedTime": "2019-08-24T14:15:22Z",
  "paidTime": "2019-08-24T14:15:22Z",
  "status": "DRAFT",
  "statusReasonCode": "MISSING_PAYER_CONTACT_DETAILS",
  "statusReason": "string",
  "invoiceSource": "FILE_UPLOAD",
  "customer": {
    "id": "string",
    "externalId": "string",
    "name": "string",
    "creationTime": "2019-08-24T14:15:22Z",
    "lastUpdatedTime": "2019-08-24T14:15:22Z",
    "people": [ … ],
    "addresses": [ … ],
    "directDebitMandate": { … },
    "billerBankAccount": { … },
    "timezone": "string",
    "discount": { … },
    "externalData": [ … ],
    "tags": [ … ],
    "status": "ACTIVE",
    "statusReasonCode": "MERGED",
    "settings": { … },
    "trackingItems": [ … ],
    "office": { … }
  },
  "itemsTaxType": "EXCLUSIVE",
  "instalmentPlanDetails": {
    "cadence": { … }
  },
  "items": [
    { … }
  ],
  "paymentRequests": [
    { … }
  ],
  "scheduleDetails": {
    "scheduleId": "string",
    "scheduleNo": "string",
    "type": "RECURRING"
  },
  "creditNotes": [
    { … }
  ],
  "fileSource": "NONE",
  "externalData": [
    { … }
  ],
  "creditControlStatus": "AT_RISK",
  "workflowType": "AUTO_COLLECT",
  "customFields": [
    { … }
  ],
  "office": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "trackingItemId": "c7c7fc03-0b17-402e-aa79-1d532a6db210",
    "details": { … }
  }
}

Create an invoice

Request

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Bodyapplication/jsonrequired
invoiceNostring

The unique number of the invoice. Acts as an idempotency key. Will be generated if not provided.

Example: "INV-12345"
customerobject(CustomerDetails)
Example: "80349480-490b-4234-92e7-fad697e3d446"
descriptionstring

A short description or summary of the invoice.

Example: "Monthly subscription fee for January"
amountnumber

The invoice amount.

dueDatestring(date-time)

The due date for the invoice payment.

Example: "2025-12-15T23:59:59.000Z"
issueDatestring(date-time)

The date the invoice is issued.

Example: "2025-12-15T23:59:59.000Z"
itemsTaxTypestring

How tax is applied to line items from the invoice

Enum"EXCLUSIVE""INCLUSIVE""NONE"
instalmentPlanDetailsobject(InstalmentPlanDetails)
itemsArray of objects(NewLineItemRequest)

The list of items included in this invoice.

paymentRequestsArray of objects(CreatePaymentRequestDetails)

Details for the invoice's payment requests. Only required for invoices with multiple payment requests (ex: instalments).

officeIdstring(uuid)

The unique identifier of the office associated with this invoice.

Example: "80349480-490b-4234-92e7-fad697e3d446"
curl -i -X POST \
  https://developer.adfin.com/_mock/api-docs/prod/invoices \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "invoiceNo": "INV-12345",
    "customer": {
      "id": "80349480-490b-4234-92e7-fad697e3d446"
    },
    "description": "Monthly subscription fee for January",
    "amount": 0,
    "dueDate": "2025-12-15T23:59:59.000Z",
    "issueDate": "2025-12-15T23:59:59.000Z",
    "itemsTaxType": "EXCLUSIVE",
    "instalmentPlanDetails": {
      "cadence": {
        "type": "INTERVAL",
        "timeUnit": "SECOND",
        "frequency": 1,
        "dayOfMonth": 0,
        "dates": [
          "2019-08-24T14:15:22Z"
        ],
        "startDate": "2019-08-24T14:15:22Z",
        "endDate": "2019-08-24T14:15:22Z",
        "count": 2
      }
    },
    "items": [
      {
        "description": "string",
        "quantity": 0,
        "unitAmount": 0,
        "taxRate": 0,
        "taxRateId": "d4f1c2b3-4a5b-678c-9d0e-f1a2b3c4d5e6",
        "accountCodeId": "string",
        "productId": "d4f1c2b3-4a5b-678c-9d0e-f1a2b3c4d5e6",
        "trackingItemIds": [
          "497f6eca-6276-4993-bfeb-53cbbbba6f08"
        ]
      }
    ],
    "paymentRequests": [
      {
        "amount": 100,
        "payByDate": "2025-03-25T11:36:55.243Z"
      }
    ],
    "officeId": "80349480-490b-4234-92e7-fad697e3d446"
  }'

Responses

The request was successful and the invoice was created.

Bodyapplication/json
idstring

The internal id of the invoice

invoiceNostring

The number of the invoice. Can be empty when creating the invoice without an invoice number,but it will be automatically generated when the invoice is pushed to an accounting software. Once set, serves as a unique value that can be used as an idempotency key.

descriptionstring

Short description of the invoice

totalAmountstring

The invoice total amount. Includes tax amount, amount paid or reduced with credit notes)

taxAmountstring

The invoice tax amount.

dueAmountstring

The invoice amount due (remaining to be paid).

creditNotesAmountstring

The total amount that is credited.

dueDatestring(date-time)

The due date of the invoice

issueDatestring(date-time)

The issue date date of the invoice

creationTimestring(date-time)

The date the invoice was created

lastUpdatedTimestring(date-time)

The date the invoice was last updated

paidTimestring(date-time)

The date the invoice was paid

statusstring

The invoice status

Enum"DRAFT""UNPAID""OVERDUE""SCHEDULED""SUBMITTED""PAID""VOID""SETTLED"
statusReasonCodestring

The reason as predefined code why the invoice is in a certain status

Enum"MISSING_PAYER_CONTACT_DETAILS""PENDING_ACTIVATION""PENDING_DD_MANDATE""PENDING_DD_CAPABILITY""MARKED_AS_PAID""WORKFLOW_COMPLETED""NOTIFICATION_DELIVERY_FAILED""BULK_PRUNE""STALE_DRAFT_CLEANUP""OTHER"
statusReasonstring

Custom details on why the invoice is in a certain status

invoiceSourcestring

The source of the invoice

Enum"FILE_UPLOAD""MANUAL""PR""EXTERNAL""SCHEDULE""PLATFORM"
customerobject(CustomerResponse)
itemsTaxTypestring

How tax is applied to line items from the invoice

Enum"EXCLUSIVE""INCLUSIVE""NONE"
instalmentPlanDetailsobject(InstalmentPlanDetails)
itemsArray of objects(LineItemResponse)

The list of items from the invoice

paymentRequestsArray of objects(PaymentRequestDetails)

The payment requests that were created for this invoice

scheduleDetailsobject(ScheduleDetails)
creditNotesArray of objects(CreditNoteResponse)

The list of credit notes from the invoice

fileSourcestring

The file source of invoice

Enum"NONE""FILE_UPLOAD""EXTERNAL""ADFIN""PENDING_ADFIN"
externalDataArray of objects(InvoiceExternalData)

References about this invoice from external platforms Adfin integrates with. Such as ID etc

creditControlStatusstring

The credit control status of the invoice

Enum"AT_RISK""EXPECTED""CONFIRMED"
workflowTypestring

The workflow type of the invoice

Enum"AUTO_COLLECT""ON_DEMAND""NONE"
customFieldsArray of objects(CustomField)

The list of custom fields that are applied to the invoice

officeobject(InvoiceOfficeResponse)
Response
application/json
{
  "id": "string",
  "invoiceNo": "string",
  "description": "string",
  "totalAmount": "string",
  "taxAmount": "string",
  "dueAmount": "string",
  "creditNotesAmount": "string",
  "dueDate": "2019-08-24T14:15:22Z",
  "issueDate": "2019-08-24T14:15:22Z",
  "creationTime": "2019-08-24T14:15:22Z",
  "lastUpdatedTime": "2019-08-24T14:15:22Z",
  "paidTime": "2019-08-24T14:15:22Z",
  "status": "DRAFT",
  "statusReasonCode": "MISSING_PAYER_CONTACT_DETAILS",
  "statusReason": "string",
  "invoiceSource": "FILE_UPLOAD",
  "customer": {
    "id": "string",
    "externalId": "string",
    "name": "string",
    "creationTime": "2019-08-24T14:15:22Z",
    "lastUpdatedTime": "2019-08-24T14:15:22Z",
    "people": [ … ],
    "addresses": [ … ],
    "directDebitMandate": { … },
    "billerBankAccount": { … },
    "timezone": "string",
    "discount": { … },
    "externalData": [ … ],
    "tags": [ … ],
    "status": "ACTIVE",
    "statusReasonCode": "MERGED",
    "settings": { … },
    "trackingItems": [ … ],
    "office": { … }
  },
  "itemsTaxType": "EXCLUSIVE",
  "instalmentPlanDetails": {
    "cadence": { … }
  },
  "items": [
    { … }
  ],
  "paymentRequests": [
    { … }
  ],
  "scheduleDetails": {
    "scheduleId": "string",
    "scheduleNo": "string",
    "type": "RECURRING"
  },
  "creditNotes": [
    { … }
  ],
  "fileSource": "NONE",
  "externalData": [
    { … }
  ],
  "creditControlStatus": "AT_RISK",
  "workflowType": "AUTO_COLLECT",
  "customFields": [
    { … }
  ],
  "office": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "trackingItemId": "c7c7fc03-0b17-402e-aa79-1d532a6db210",
    "details": { … }
  }
}

Get the file for a specific invoice

Request

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Path
idstringrequired
curl -i -X GET \
  'https://developer.adfin.com/_mock/api-docs/prod/invoices/{id}/file' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The invoice file is successfully returned

Bodyapplication/octet-stream
any(StreamingResponseBody)

Recurring invoices

Operations

Payment requests

Operations

Recurring payment requests

Operations

Payments

Operations

Tax rates

Operations

Items

Operations

Workflows

Operations

Webhooks

Operations