# Create an invoice

Endpoint: POST /invoices
Version: 1.0.0
Security: Biller Access Token (Staging), Biller Access Token (Production)

## Request fields (application/json):

  - `invoiceNo` (string)
    The unique number of the invoice. Acts as an idempotency key. Will be generated if not provided.
    Example: "INV-12345"

  - `customer` (object)
    Contains the unique identifier for the customer.
    Example: {"id":"80349480-490b-4234-92e7-fad697e3d446"}

  - `customer.id` (string, required)
    The Adfin ID of the customer.
    Example: "80349480-490b-4234-92e7-fad697e3d446"

  - `description` (string)
    A short description or summary of the invoice.
    Example: "Monthly subscription fee for January"

  - `amount` (number)
    The invoice amount.

  - `dueDate` (string)
    The due date for the invoice payment.
    Example: "2025-12-15T23:59:59Z"

  - `issueDate` (string)
    The date the invoice is issued.
    Example: "2025-12-15T23:59:59Z"

  - `itemsTaxType` (string)
    Specifies how tax is applied to line items in an invoice.
* EXCLUSIVE: Line items are exclusive of tax.
* INCLUSIVE: Line items are inclusive tax.
* NONE: Line items have no tax.. 
Possible values (non-exclusive): EXCLUSIVE, INCLUSIVE, NONE

  - `instalmentPlanDetails` (object)
    Instalment plan details

  - `instalmentPlanDetails.cadence` (object, required)
    The cadence of the schedule

  - `instalmentPlanDetails.cadence.type` (string, required)
    The type of cadence.
* INTERVAL: Interval. Based on a startDate and an (optional) endDate
* INTERVAL_COUNT: Interval based on a startDate and a count
* DAY_OF_MONTH: Day of month. Based on a specific day of the month
* CUSTOM: Custom. Specific list of dates
. 
Possible values (non-exclusive): INTERVAL, INTERVAL_COUNT, DAY_OF_MONTH, CUSTOM

  - `instalmentPlanDetails.cadence.timeUnit` (string)
    Required if type is INTERVAL.
Defines the time unit (e.g., DAYS, MONTHS, etc.).
. 
Possible values (non-exclusive): SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, YEAR

  - `instalmentPlanDetails.cadence.frequency` (integer)
    Required if type is INTERVAL.
Frequency of recurrence (e.g., every N time units).

  - `instalmentPlanDetails.cadence.dayOfMonth` (integer)
    Required if type is DAY_OF_MONTH.
Specifies the day of the month the schedule applies.

  - `instalmentPlanDetails.cadence.dates` (array)
    Required if type is CUSTOM.
A list of exact custom dates for the cadence.

  - `instalmentPlanDetails.cadence.startDate` (string, required)
    The start date of the schedule

  - `instalmentPlanDetails.cadence.endDate` (string)
    The (optional) end date of the schedule

  - `instalmentPlanDetails.cadence.count` (integer)
    The total number of items. Required for INTERVAL_COUNT type

  - `items` (array)
    The list of items included in this invoice.
    Example: [[{"description":"Monthly Pro Plan Subscription","unitAmount":5000,"quantity":1},{"description":"Additional API Usage","unitAmount":2000,"quantity":1}]]

  - `items.description` (string)
    The description of the item.

  - `items.quantity` (number)
    The quantity of items.

  - `items.unitAmount` (number)
    The price per unit of the item.

  - `items.taxRate` (number)
    The tax rate percentage applied on the line item amount (quantity * unit amount).

  - `items.taxRateId` (string)
    Tax rate id for this line item. Use the Tax Rates API to manage your tax rates.
    Example: "d4f1c2b3-4a5b-678c-9d0e-f1a2b3c4d5e6"

  - `items.accountCodeId` (string)
    Sales account id for this line item. If you require specific sales accounts to be used, provide the account code id here. To recieve your account codes, contact support@adfin.com

  - `items.productId` (string)
    The base product id for this line item. Use the Items catalog API to manage your products.
    Example: "d4f1c2b3-4a5b-678c-9d0e-f1a2b3c4d5e6"

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

  - `paymentRequests.amount` (number, required)
    The payment request amount.
    Example: 100

  - `paymentRequests.payByDate` (string, required)
    The date by which the payment request should be paid
    Example: "2025-03-25T11:36:55.243Z"

## Response 200 fields (application/json):

  - `id` (string)
    The internal id of the invoice

  - `invoiceNo` (string)
    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.

  - `description` (string)
    Short description of the invoice

  - `totalAmount` (string)
    The invoice total amount. Includes tax amount, amount paid or reduced with credit notes)

  - `taxAmount` (string)
    The invoice tax amount.

  - `dueAmount` (string)
    The invoice amount due (remaining to be paid).

  - `creditNotesAmount` (string)
    The total amount that is credited.

  - `dueDate` (string)
    The due date of the invoice

  - `issueDate` (string)
    The issue date date of the invoice

  - `creationTime` (string)
    The date the invoice was created

  - `lastUpdatedTime` (string)
    The date the invoice was last updated

  - `paidTime` (string)
    The date the invoice was paid

  - `status` (string)
    The status of the invoice.
* DRAFT: The invoice is created, but not yet activated (sent)
* UNPAID: The invoice is not yet paid.
* 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.
* OVERDUE: The invoice is not yet paid and it is passed the due date.
* PAID: The invoice payment has been captured.
* SETTLED: The invoice is paid out.
* VOID: The invoice was voided.. 
Possible values (non-exclusive): DRAFT, UNPAID, OVERDUE, SCHEDULED, SUBMITTED, PAID, VOID, SETTLED

  - `statusReasonCode` (string)
    The reason why the invoice is in a certain status.
* MISSING_PAYER_CONTACT_DETAILS - The invoice is missing the contact details of payer.
* PENDING_ACTIVATION - The invoice is not yet distributed by Adfin.. 
Possible values (non-exclusive): MISSING_PAYER_CONTACT_DETAILS, PENDING_ACTIVATION, PENDING_DD_MANDATE, PENDING_DD_CAPABILITY, MARKED_AS_PAID, WORKFLOW_COMPLETED, NOTIFICATION_DELIVERY_FAILED, BULK_PRUNE, OTHER

  - `statusReason` (string)
    Custom details on why the invoice is in a certain status

  - `invoiceSource` (string)
    The source of the invoice. 
Possible values (non-exclusive): FILE_UPLOAD, MANUAL, PR, EXTERNAL, SCHEDULE, PLATFORM

  - `customer` (object)
    The customer details.

  - `customer.id` (string)
    The Adfin id of the customer.

  - `customer.externalId` (string)
    The id of the customer from the platform that is integrating with Adfin.

  - `customer.name` (string)
    The full name of the customer.

  - `customer.creationTime` (string)
    The time the customer was created.

  - `customer.lastUpdatedTime` (string)
    The last time when the customer was updated.

  - `customer.people` (array)
    The list of people assigned to the customer.

  - `customer.people.id` (string)
    The internal id of the person.

  - `customer.people.firstName` (string)
    The first name of the person.

  - `customer.people.lastName` (string)
    The last name of the person.

  - `customer.people.email` (string)
    The email of the person.

  - `customer.people.phoneNo` (string)
    The phone number of the person.

  - `customer.people.isPrimaryContact` (boolean)
    True if this person is a primary contact.

  - `customer.people.isIncludedInCommunications` (boolean)
    True if this person is included in the customers communications.

  - `customer.addresses` (array)
    The list of the addresses for the customer.

  - `customer.addresses.id` (string)
    The internal id of the address.

  - `customer.addresses.city` (string)
    The name of the city.

  - `customer.addresses.postalCode` (string)
    The postal code.

  - `customer.addresses.country` (string)
    The name of the biller country.

  - `customer.addresses.addressLine1` (string)
    The name of the street, and the house or building number.

  - `customer.directDebitMandate` (object)
    Direct Debit details.

  - `customer.directDebitMandate.id` (string)
    The id of the direct debit mandate.

  - `customer.directDebitMandate.status` (string)
    The status of the Direct Debit Mandate, if any present.
* CREATED: The Direct Debit Mandate was created with success.
* PENDING: The Direct Debit Mandate was signed and accepted by the customer and it is in the Payment Provider's accepted timeframe.
* ACTIVE: The Direct Debit Mandate was confirmed by the Payment Provider.
* CANCELLED: The Direct Debit Mandate was cancelled directly by the customer.
* MIGRATING: The Direct Debit Mandate is in process of migrating from one payment provider to another.. 
Possible values (non-exclusive): CREATED, PENDING, ACTIVE, CANCELLED, MIGRATING

  - `customer.directDebitMandate.statusReasonCode` (string)
    The reason why the direct debit mandate is in a certain status.
* PENDING_DD_CAPABILITY - The direct debit mandate was signed, but not yet submitted to the payment provider as the biller onboarding is still in progress.
* PENDING_ACTIVATION - The direct debit mandate was signed, but not yet activated by the payment provider.
* MIGRATED - The direct debit mandate was migrated to a new payment provider.
* BANK_ACCOUNT_CHANGED - The direct debit mandate was created due to a bank account change (bank switching).
* INCORRECT_BANK_DETAILS - The direct debit mandate has incorrect bank account details.
* OTHER - Unknown reason. 
Possible values (non-exclusive): PENDING_DD_CAPABILITY, PENDING_ACTIVATION, MIGRATED, BANK_ACCOUNT_CHANGED, INCORRECT_BANK_DETAILS, OTHER

  - `customer.directDebitMandate.statusReason` (string)
    Reason explaining the current status of the direct debit mandate, especially useful for failure cases.

  - `customer.directDebitMandate.creationTime` (string)
    The time when the mandate was created

  - `customer.directDebitMandate.lastUpdatedTime` (string)
    The last time when the mandate was updated

  - `customer.directDebitMandate.authorisationTime` (string)
    The time when the mandate was signed by the customer

  - `customer.directDebitMandate.submissionTime` (string)
    The time when the mandate was submitted to the payment provider

  - `customer.directDebitMandate.url` (string)
    The URL where the customer can sign the direct debit mandate.

  - `customer.timezone` (string)
    The timezone of the customer.

  - `customer.discount` (object)
    The customer discount details.

  - `customer.discount.percentage` (number)
    The discount as a percentage to be applied for the invoices.

  - `customer.discount.period` (integer)
    The period in hours until the discount expires.

  - `customer.externalData` (array)
    References about this customer from external platforms Adfin integrates with, such as ID, etc.

  - `customer.externalData.connectorType` (string, required)
    The customer connector type. 
Possible values (non-exclusive): XERO, QUICKBOOKS

  - `customer.externalData.id` (string, required)
    The ID of the Customer in the external platform.

  - `customer.externalData.name` (string)
    The name of the Customer in the external platform.

  - `customer.tags` (array)
    The tag ids associated with the customer.

  - `itemsTaxType` (string)
    Specifies how tax is applied to line items in an invoice.
* EXCLUSIVE: Line items are exclusive of tax.
* INCLUSIVE: Line items are inclusive tax.
* NONE: Line items have no tax.. 
Possible values (non-exclusive): EXCLUSIVE, INCLUSIVE, NONE

  - `instalmentPlanDetails` (object)
    Instalment plan details

  - `instalmentPlanDetails.cadence` (object, required)
    The cadence of the schedule

  - `instalmentPlanDetails.cadence.type` (string, required)
    The type of cadence.
* INTERVAL: Interval. Based on a startDate and an (optional) endDate
* INTERVAL_COUNT: Interval based on a startDate and a count
* DAY_OF_MONTH: Day of month. Based on a specific day of the month
* CUSTOM: Custom. Specific list of dates
. 
Possible values (non-exclusive): INTERVAL, INTERVAL_COUNT, DAY_OF_MONTH, CUSTOM

  - `instalmentPlanDetails.cadence.timeUnit` (string)
    Required if type is INTERVAL.
Defines the time unit (e.g., DAYS, MONTHS, etc.).
. 
Possible values (non-exclusive): SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, YEAR

  - `instalmentPlanDetails.cadence.frequency` (integer)
    Required if type is INTERVAL.
Frequency of recurrence (e.g., every N time units).

  - `instalmentPlanDetails.cadence.dayOfMonth` (integer)
    Required if type is DAY_OF_MONTH.
Specifies the day of the month the schedule applies.

  - `instalmentPlanDetails.cadence.dates` (array)
    Required if type is CUSTOM.
A list of exact custom dates for the cadence.

  - `instalmentPlanDetails.cadence.startDate` (string, required)
    The start date of the schedule

  - `instalmentPlanDetails.cadence.endDate` (string)
    The (optional) end date of the schedule

  - `instalmentPlanDetails.cadence.count` (integer)
    The total number of items. Required for INTERVAL_COUNT type

  - `items` (array)
    The list of items from the invoice

  - `items.id` (string)
    The ID of the line item to update.

  - `items.description` (string)
    The description of the item.

  - `items.quantity` (number)
    The quantity of items.

  - `items.unitAmount` (number)
    The price per unit of the item.

  - `items.taxRate` (number)
    The tax rate percentage applied on the line item amount (quantity * unit amount).

  - `items.taxAmount` (number)
    The tax amount added on top of the line item amount.

  - `items.totalAmount` (number)
    The total price of the item.

  - `items.taxDetails` (object)
    The tax details response.

  - `items.taxDetails.id` (string)
    The ID of the tax rate.

  - `items.taxDetails.rate` (number)
    The actual rate value.

  - `items.accountDetails` (object)
    The account details response.

  - `items.accountDetails.id` (string)
    The ID of the account code.

  - `items.accountDetails.code` (string)
    The account code value.

  - `items.productDetails` (object)
    The product details response.

  - `items.productDetails.id` (string)
    The ID of the product.

  - `items.productDetails.code` (string)
    The product code value.

  - `items.trackingGroupIds` (array)
    Tracking groups attached to this line item.

  - `items.trackingGroupIds.groupId` (string)
    Tracking group id.

  - `items.trackingGroupIds.itemId` (string)
    Tracking group selection option id.

  - `items.externalData` (array)
    Information about this line item captured from external systems

  - `items.externalData.id` (string)
    The ID from the external platform

  - `items.externalData.connectorType` (string)
    The connector type. 
Possible values (non-exclusive): XERO, QUICKBOOKS, BRIDGE, STRIPE, PLATFORM

  - `items.externalData.templateId` (string)
    The template ID from external platform from which this line item is created. Cannot use both the template ID and the account code.

  - `items.externalData.accountCode` (string)
    The account code from external platform from which this line item is created. Cannot use both the template ID and the account code.

  - `paymentRequests` (array)
    The payment requests that were created for this invoice

  - `paymentRequests.id` (string)
    The internal id of the payment request

  - `paymentRequests.paymentRequestNo` (string)
    The payment request number

  - `paymentRequests.description` (string)
    Short description of the payment request

  - `paymentRequests.totalAmount` (number)
    The payment request amount

  - `paymentRequests.paidAmount` (number)
    The total amount that is paid

  - `paymentRequests.currencyCode` (string)
    The default currency of the biller.. 
Possible values (non-exclusive): AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTN, BWP, BYR, BZD, CAD, CDF, CHF, CLP, CNY, COP, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GGP, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, IMP, INR, IQD, IRR, ISK, JEP, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLL, SOS, SPL, SRD, STD, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TVD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VEF, VND, VUV, WST, XAF, XCD, XDR, XOF, XPF, YER, ZAR, ZMW, ZWD

  - `paymentRequests.payByDate` (string)
    The (optional) date until when user recommended the payer to pay

  - `paymentRequests.creationTime` (string)
    The date the payment request was created

  - `paymentRequests.lastNotificationSentTime` (string)
    The date the payment request was last sent to the customer

  - `paymentRequests.lastUpdatedTime` (string)
    The date the payment request was last updated

  - `paymentRequests.paidTime` (string)
    The date the payment request paid

  - `paymentRequests.paymentInitiationDate` (string)
    The date when payment is initiated for this payment request (only for Direct Debit)

  - `paymentRequests.chargeDate` (string)
    The date on which the customer will have their account debited

  - `paymentRequests.payoutDate` (string)
    The date on which the biller will get paid out for the payment

  - `paymentRequests.distributionTime` (string)
    The date when the payment request was distributed

  - `paymentRequests.status` (string)
    The status of the payment request.
* DRAFT: The payment request does not contain contact details for the payer or it is not yet distributed.
* UNPAID: The payment request is not yet paid.
* OVERDUE: THe payment request is not yet paid and is past the pay by date.
* SCHEDULED: The payment request is scheduled to collect the payment via Direct Debit.
* SUBMITTED: The remaining due amount on the payment request is covered by submitted (but not yet confirmed) Direct debit payments.
* PAID: The payment request payment is captured.
* VOID: The payment request is voided.
* SETTLED: The payment request is paid out.
. 
Possible values (non-exclusive): DRAFT, UNPAID, OVERDUE, SCHEDULED, SUBMITTED, PAID, VOID, SETTLED

  - `paymentRequests.statusReason` (string)
    Custom details on why the payment request is in a certain status

  - `paymentRequests.reference` (string)
    The payment request reference

  - `paymentRequests.payments` (array)
    The payments made as part of this payment request

  - `paymentRequests.payments.id` (string, required)
    The internal id of the payment

  - `paymentRequests.payments.paymentRequestId` (string, required)
    The ID of the payment request

  - `paymentRequests.payments.creationTime` (string, required)
    The date when the payment was initiated

  - `paymentRequests.payments.lastUpdatedTime` (string)
    The last time when the payment was updated

  - `paymentRequests.payments.amount` (number, required)
    The paid amount

  - `paymentRequests.payments.status` (string, required)
    Statuses for payments. 
Possible values (non-exclusive): PENDING, SUBMITTED, SENT, SUCCESS, CANCELLED, FAILED, SETTLED

  - `paymentRequests.payments.paymentMethod` (string, required)
    Payment method types. 
Possible values (non-exclusive): BANK_PAYMENT, CARD, APPLE_PAY, GOOGLE_PAY, DIRECT_DEBIT, IMPORTED, MANUAL_BANK_TRANSFER, BANK_TRANSFER, AMEX

  - `paymentRequests.payments.channelPaymentId` (string, required)
    Unique identifier for the payment in the payment provider's system

  - `paymentRequests.payments.channelPaymentUrl` (string)
    The URL generated by the payment provider to perform the payment

  - `paymentRequests.payments.channelReferenceId` (string)
    The remittance reference ID for bank payments

  - `paymentRequests.payments.externalData` (array)
    References about this payment from external platforms Adfin integrates with

  - `paymentRequests.payments.externalData.id` (string)
    ID of the payment in the external platform

  - `paymentRequests.payments.metadata` (object)

  - `paymentRequests.discounts` (array)
    The discounts applied to this payment request

  - `paymentRequests.discounts.totalAmount` (number)
    The discounted amount

  - `paymentRequests.discounts.expirationDate` (string)
    The date until when the discount is valid

  - `paymentRequests.paymentLink` (object)
    Payment link details.

  - `paymentRequests.paymentLink.url` (string)
    The payment URL.

  - `paymentRequests.paymentLink.lastSeenTime` (string)
    The date when the payment link was seen for the last time

  - `paymentRequests.distribution` (object)
    Information about how a payment request is distributed and collected.

  - `paymentRequests.distribution.collectionMethod` (string)
    How the payment is expected to be collected for this payment request.. 
Possible values (non-exclusive): ONE_TIME_PAYMENT, DIRECT_DEBIT_PAYMENT, NONE

  - `paymentRequests.distribution.customMessage` (string)
    An optional message that will be sent to the customer when the payment request is distributed.

  - `paymentRequests.distribution.templateId` (string)
    The schedule template id used for sending the payment request to customer.

  - `paymentRequests.workflowType` (string)
    The workflow type of the payment request. 
Possible values (non-exclusive): AUTO_COLLECT, ON_DEMAND, NONE

  - `paymentRequests.customFields` (array)
    The list of custom fields that are applied to the payment request

  - `paymentRequests.customFields.fieldId` (string)
    The ID of the field definition.

  - `paymentRequests.customFields.fieldValueId` (string)
    The ID of the specific field value.

  - `scheduleDetails` (object)
    The details about the schedule associated with a payment request

  - `scheduleDetails.scheduleId` (string, required)
    The internal id of the schedule

  - `scheduleDetails.scheduleNo` (string, required)
    The schedule number

  - `scheduleDetails.type` (string)
    The type of schedule.
* RECURRING: Recurring Payment Request.
. 
Possible values (non-exclusive): RECURRING

  - `creditNotes` (array)
    The list of credit notes from the invoice

  - `creditNotes.id` (string)
    Credit note id.

  - `creditNotes.number` (string)
    Credit note number.

  - `creditNotes.amount` (number)
    Credit note amount.

  - `creditNotes.valueDate` (string)
    Date when credit note was applied.

  - `creditNotes.externalData` (array)
    References about this credit note from external platforms Adfin integrates with. Such as ID etc

  - `creditNotes.externalData.id` (string)
    ID of the Credit Note in the external platform

  - `fileSource` (string)
    The file source of invoice. 
Possible values (non-exclusive): NONE, FILE_UPLOAD, EXTERNAL, ADFIN, PENDING_ADFIN

  - `externalData` (array)
    References about this invoice from external platforms Adfin integrates with. Such as ID etc

  - `externalData.id` (string)
    ID of the Invoice in the external platform

  - `creditControlStatus` (string)
    The credit control status of the invoice. 
Possible values (non-exclusive): AT_RISK, EXPECTED, CONFIRMED

  - `workflowType` (string)
    The workflow type of the invoice. 
Possible values (non-exclusive): AUTO_COLLECT, ON_DEMAND, NONE

  - `customFields` (array)
    The list of custom fields that are applied to the invoice


## Response 400 fields

## Response 401 fields

## Response 422 fields

## Response 500 fields