Skip to content
/
Create a recurring invoic...

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 when a platform authenticates as itself rather than as one of its billers. A platform uses one to manage its own webhook subscriptions under /api/apps/{clientId}/webhooks.

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

Verifications

Operations

Customers

Operations

Direct debit mandates

Operations

Invoices

Operations

Recurring invoices

Operations

Retrieve a recurring 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/schedules/invoices/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
idstring

The Adfin ID of the recurring invoice.

Example: "1"
recurringInvoiceNostring

A system-generated, unique identifier for the recurring invoice. Automatically created using the prefix SCH followed by a numeric sequence (e.g., SCH-1, SCH-2, ...).

Example: "SCH-42"
nextIssueDatestring(date-time)

The next date a new invoice will be automatically generated.

Example: "2025-10-15T00:00:00Z"
statusstring

Indicates the current status of the recurring invoice. Possible values might include:

  • DRAFT – currently not generating new invoices
  • ACTIVE – currently generating new invoices
  • FINISHED – has finished all planned occurrences
  • CANCELLED – has been cancelled before finishing all planned occurrences
Example: "ACTIVE"
cadenceobject(IntervalCadence)
invoiceDetailsobject(RecurringInvoiceDetails)
creationTimestring(date-time)

The date and time when the recurring invoice was created.

Example: "2025-09-27T12:00:00Z"
lastUpdatedTimestring(date-time)

The date and time when the recurring invoice was last updated.

Example: "2025-10-01T08:30:00Z"
totalInvoicesinteger(int32)

The total number of invoices this recurring invoice is expected to generate based on cadence, start date, and end date.

Example: 10
amountnumber

The total amount of the recurring invoice. Calculated based on the sum of all invoice line items across all occurrences.

Example: 1234.5
nextInvoicesArray of objects(NextInvoiceResponse)

A list of upcoming invoices to be generated. Ordered by index and date, and limited to a maximum of 12 items.

Response
application/json
{
  "id": "1",
  "recurringInvoiceNo": "SCH-42",
  "nextIssueDate": "2025-10-15T00:00:00Z",
  "status": "ACTIVE",
  "cadence": {
    "timeUnit": "WEEK",
    "frequency": 2,
    "startDate": "2025-01-01T00:00:00.000Z",
    "endDate": "2025-12-31T23:59:59.000Z"
  },
  "invoiceDetails": {
    "customer": { … },
    "paymentTerm": { … },
    "distribution": { … },
    "description": "Monthly subscription for January",
    "currencyCode": "GBP",
    "itemsTaxType": "INCLUSIVE",
    "items": [ … ]
  },
  "creationTime": "2025-09-27T12:00:00Z",
  "lastUpdatedTime": "2025-10-01T08:30:00Z",
  "totalInvoices": 10,
  "amount": 1234.5,
  "nextInvoices": [
    { … }
  ]
}

Update a recurring invoice

Request

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

The Adfin ID of the recurring invoice

Bodyapplication/jsonrequired
cadenceobject(IntervalCadence)
invoiceDetailsobject(RecurringInvoiceDetails)
curl -i -X PUT \
  'https://developer.adfin.com/_mock/api-docs/prod/schedules/invoices/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "cadence": {
      "timeUnit": "WEEK",
      "frequency": 2,
      "startDate": "2025-01-01T00:00:00.000Z",
      "endDate": "2025-12-31T23:59:59.000Z"
    },
    "invoiceDetails": {
      "customer": {
        "id": "80349480-490b-4234-92e7-fad697e3d446"
      },
      "paymentTerm": {
        "timeUnit": "DAY",
        "value": 30
      },
      "distribution": {
        "collectionMethod": "AUTO_COLLECT",
        "customMessage": "Please find your invoice attached. Thank you for your business!",
        "approvedForSending": true
      },
      "description": "Monthly subscription for January",
      "currencyCode": "GBP",
      "itemsTaxType": "INCLUSIVE",
      "items": [
        {
          "description": "Pro Plan Subscription",
          "unitAmount": 5000,
          "quantity": 1,
          "taxRate": 0.1
        }
      ]
    }
  }'

Responses

The request has succeeded and has resulted in one recurring invoice being updated

Bodyapplication/json
idstring

The Adfin ID of the recurring invoice.

Example: "1"
recurringInvoiceNostring

A system-generated, unique identifier for the recurring invoice. Automatically created using the prefix SCH followed by a numeric sequence (e.g., SCH-1, SCH-2, ...).

Example: "SCH-42"
nextIssueDatestring(date-time)

The next date a new invoice will be automatically generated.

Example: "2025-10-15T00:00:00Z"
statusstring

Indicates the current status of the recurring invoice. Possible values might include:

  • DRAFT – currently not generating new invoices
  • ACTIVE – currently generating new invoices
  • FINISHED – has finished all planned occurrences
  • CANCELLED – has been cancelled before finishing all planned occurrences
Example: "ACTIVE"
cadenceobject(IntervalCadence)
invoiceDetailsobject(RecurringInvoiceDetails)
creationTimestring(date-time)

The date and time when the recurring invoice was created.

Example: "2025-09-27T12:00:00Z"
lastUpdatedTimestring(date-time)

The date and time when the recurring invoice was last updated.

Example: "2025-10-01T08:30:00Z"
totalInvoicesinteger(int32)

The total number of invoices this recurring invoice is expected to generate based on cadence, start date, and end date.

Example: 10
amountnumber

The total amount of the recurring invoice. Calculated based on the sum of all invoice line items across all occurrences.

Example: 1234.5
nextInvoicesArray of objects(NextInvoiceResponse)

A list of upcoming invoices to be generated. Ordered by index and date, and limited to a maximum of 12 items.

Response
application/json
{
  "id": "1",
  "recurringInvoiceNo": "SCH-42",
  "nextIssueDate": "2025-10-15T00:00:00Z",
  "status": "ACTIVE",
  "cadence": {
    "timeUnit": "WEEK",
    "frequency": 2,
    "startDate": "2025-01-01T00:00:00.000Z",
    "endDate": "2025-12-31T23:59:59.000Z"
  },
  "invoiceDetails": {
    "customer": { … },
    "paymentTerm": { … },
    "distribution": { … },
    "description": "Monthly subscription for January",
    "currencyCode": "GBP",
    "itemsTaxType": "INCLUSIVE",
    "items": [ … ]
  },
  "creationTime": "2025-09-27T12:00:00Z",
  "lastUpdatedTime": "2025-10-01T08:30:00Z",
  "totalInvoices": 10,
  "amount": 1234.5,
  "nextInvoices": [
    { … }
  ]
}

Delete a recurring invoice

Request

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

The Adfin ID of the recurring invoice to be deleted

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

Responses

The recurring invoice was deleted

Cancel a recurring invoice

Request

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

The Adfin ID of the recurring invoice

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

Responses

The recurring invoice has been cancelled

Activate a recurring invoice

Request

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

The Adfin ID of the recurring invoice

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

Responses

The recurring invoice has been activated

Create a recurring invoice

Request

The recurring invoice is created as a draft. Nothing is generated or sent to the customer until it is activated, either via PUT /schedules/invoices/{id}:activate or from the console.

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Bodyapplication/jsonrequired
cadenceobject(IntervalCadence)required
Example: {"type":"INTERVAL","timeUnit":"MONTH","frequency":1,"startDate":"2025-01-01T00:00:00.000Z"}
cadence.​timeUnitstringrequired

Determines whether the cadence repeats in weeks, months or years. Common values:

  • WEEK
  • MONTH
  • YEAR
Example: "MONTH"
cadence.​frequencyinteger(int32)>= 1required

Combined with timeUnit to determine how often the cadence occurs. For example:

  • frequency = 2 and timeUnit = WEEK → every 2 weeks
  • frequency = 1 and timeUnit = MONTH → every month
Example: 1
cadence.​startDatestring(date-time)required

The first occurrence happens at this time. Format: ISO 8601 with milliseconds, e.g. 2025-01-01T00:00:00.000Z. Timestamps without milliseconds are rejected.

Example: "2025-01-01T00:00:00.000Z"
cadence.​endDatestring(date-time)

Optional end date for the cadence. If provided, the generation stops at or before this date. If omitted, the cadence continues indefinitely.

Example: "2025-12-31T23:59:59.000Z"
invoiceDetailsobject(RecurringInvoiceDetails)required
Example: {"customer":{"id":"80349480-490b-4234-92e7-fad697e3d446"},"paymentTerm":{"timeUnit":"DAY","value":30},"distribution":{"collectionMethod":"AUTO_COLLECT","customMessage":"Please find your invoice attached. Thank you for your business!","approvedForSending":true},"description":"Monthly subscription for January","currencyCode":"GBP","itemsTaxType":"INCLUSIVE","items":[{"description":"Pro Plan Subscription","unitAmount":5000,"quantity":1}]}
invoiceDetails.​customerobject(ScheduleCustomerDetails)required
Example: {"id":"80349480-490b-4234-92e7-fad697e3d446"}
invoiceDetails.​customer.​idstringrequired

The Adfin ID of the customer.

Example: "80349480-490b-4234-92e7-fad697e3d446"
invoiceDetails.​paymentTermobject(PaymentTerm)
Example: {"timeUnit":"DAY","value":30}
invoiceDetails.​distributionobject(CollectionDetails)required
Example: {"collectionMethod":"AUTO_COLLECT","customMessage":"Please find your invoice attached. Thank you for your business!","approvedForSending":true}
invoiceDetails.​distribution.​collectionMethodstring

How the payment is expected to be collected. For example:

  • AUTO_COLLECT: Collected automatically via direct debit. Takes effect once the customer has an active direct debit mandate; until they sign, collection waits with status reason PENDING_DD_MANDATE.
  • ON_DEMAND: Collected via other payment methods (eg. CARD, APPLE_PAY, GOOGLE_PAY, BANK).
  • NONE: No payment collection is initiated automatically.
Enum"AUTO_COLLECT""ON_DEMAND""NONE"
Example: "AUTO_COLLECT"
invoiceDetails.​distribution.​templateIdstring(uuid)

The workflow template ID used for sending the invoice or payment request to the customer. Optional — if null, the system default template will be used.

Example: "d290f1ee-6c54-4b01-90e6-d701748f0851"
invoiceDetails.​distribution.​customMessagestring

An optional message that will be sent to the customer when the invoice or payment request is distributed. Can be used for personalized greetings or additional instructions.

Example: "Please find your invoice attached. Thank you for your business!"
invoiceDetails.​distribution.​approvedForSendingbooleanrequired

Boolean flag specifying whether the invoice or payment request is approved for sending. Defaults to true if not explicitly set.

Default true
Example: true
invoiceDetails.​descriptionstring

A short summary or purpose of the invoice. Appears in both the invoice document and customer communications.

Example: "Monthly subscription for January"
invoiceDetails.​currencyCodestringrequired

The three-letter ISO 4217 currency code (e.g., GBP, EUR, USD). Indicates the currency in which the invoice is issued.

Example: "GBP"
invoiceDetails.​itemsTaxTypestringrequired

Defines how tax is applied to the invoice line items.

Possible values:

  • INCLUSIVE: Tax is included in item prices.
  • EXCLUSIVE: Tax is added on top of item prices.
  • NONE: No tax applied.
Example: "INCLUSIVE"
invoiceDetails.​itemsArray of objects(NewLineItemRequest)required

The list of line items included in the invoice. Each item represents a product, service, or fee with its own amount and tax configuration.

Example: [{"description":"Pro Plan Subscription","unitAmount":5000,"quantity":1}]
invoiceDetails.​items[].​descriptionstring

The description of the item.

invoiceDetails.​items[].​quantitynumber

The quantity of items.

invoiceDetails.​items[].​unitAmountnumber

The price per unit of the item.

invoiceDetails.​items[].​taxRatenumber

The tax rate percentage applied on the line item amount (quantity * unit amount).

invoiceDetails.​items[].​taxRateIdstring

Tax rate id for this line item. Use the Tax Rates API to manage your tax rates.

Example: "d4f1c2b3-4a5b-678c-9d0e-f1a2b3c4d5e6"
invoiceDetails.​items[].​accountCodeIdstring

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

invoiceDetails.​items[].​productIdstring

The base product id for this line item. Use the Items catalog API to manage your products.

Example: "d4f1c2b3-4a5b-678c-9d0e-f1a2b3c4d5e6"
invoiceDetails.​items[].​trackingItemIdsArray of strings(uuid)

Tracking item catalogue IDs for this line item.

invoiceDetails.​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/schedules/invoices \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "cadence": {
      "type": "INTERVAL",
      "timeUnit": "MONTH",
      "frequency": 1,
      "startDate": "2025-01-01T00:00:00.000Z"
    },
    "invoiceDetails": {
      "customer": {
        "id": "80349480-490b-4234-92e7-fad697e3d446"
      },
      "paymentTerm": {
        "timeUnit": "DAY",
        "value": 30
      },
      "distribution": {
        "collectionMethod": "AUTO_COLLECT",
        "customMessage": "Please find your invoice attached. Thank you for your business!",
        "approvedForSending": true
      },
      "description": "Monthly subscription for January",
      "currencyCode": "GBP",
      "itemsTaxType": "INCLUSIVE",
      "items": [
        {
          "description": "Pro Plan Subscription",
          "unitAmount": 5000,
          "quantity": 1
        }
      ]
    }
  }'

Responses

The request was successful and the recurring invoice was created

Bodyapplication/json
idstring

The Adfin ID of the recurring invoice.

Example: "1"
recurringInvoiceNostring

A system-generated, unique identifier for the recurring invoice. Automatically created using the prefix SCH followed by a numeric sequence (e.g., SCH-1, SCH-2, ...).

Example: "SCH-42"
nextIssueDatestring(date-time)

The next date a new invoice will be automatically generated.

Example: "2025-10-15T00:00:00Z"
statusstring

Indicates the current status of the recurring invoice. Possible values might include:

  • DRAFT – currently not generating new invoices
  • ACTIVE – currently generating new invoices
  • FINISHED – has finished all planned occurrences
  • CANCELLED – has been cancelled before finishing all planned occurrences
Example: "ACTIVE"
cadenceobject(IntervalCadence)
invoiceDetailsobject(RecurringInvoiceDetails)
creationTimestring(date-time)

The date and time when the recurring invoice was created.

Example: "2025-09-27T12:00:00Z"
lastUpdatedTimestring(date-time)

The date and time when the recurring invoice was last updated.

Example: "2025-10-01T08:30:00Z"
totalInvoicesinteger(int32)

The total number of invoices this recurring invoice is expected to generate based on cadence, start date, and end date.

Example: 10
amountnumber

The total amount of the recurring invoice. Calculated based on the sum of all invoice line items across all occurrences.

Example: 1234.5
nextInvoicesArray of objects(NextInvoiceResponse)

A list of upcoming invoices to be generated. Ordered by index and date, and limited to a maximum of 12 items.

Response
application/json
{
  "id": "1",
  "recurringInvoiceNo": "SCH-42",
  "nextIssueDate": "2025-10-15T00:00:00Z",
  "status": "ACTIVE",
  "cadence": {
    "timeUnit": "WEEK",
    "frequency": 2,
    "startDate": "2025-01-01T00:00:00.000Z",
    "endDate": "2025-12-31T23:59:59.000Z"
  },
  "invoiceDetails": {
    "customer": { … },
    "paymentTerm": { … },
    "distribution": { … },
    "description": "Monthly subscription for January",
    "currencyCode": "GBP",
    "itemsTaxType": "INCLUSIVE",
    "items": [ … ]
  },
  "creationTime": "2025-09-27T12:00:00Z",
  "lastUpdatedTime": "2025-10-01T08:30:00Z",
  "totalInvoices": 10,
  "amount": 1234.5,
  "nextInvoices": [
    { … }
  ]
}

Get the collection preferences for a recurring invoice

Request

Returns how collection is set up for the invoices this recurring invoice raises. The values in force, after the agent's settings and every override are resolved.

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Path
recurringInvoiceIdstring(uuid)required

The identifier of the recurring invoice.

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

Responses

The collection method and preferences in force.

Bodyapplication/json
collectionMethodstringrequired

The collection method in force.

Enum"AUTO_COLLECT""ON_DEMAND"
preferencesobject(CollectionPreferences)required
preferences.​paymentRemindersobject(PreferenceToggle)
preferences.​mandateRemindersobject(PreferenceToggle)
preferences.​cardRemindersobject(PreferenceToggle)
preferences.​directDebitEncouragementobject(PreferenceToggle)
preferences.​statementsobject(PreferenceToggle)
preferences.​lateFeesobject(LateFeesPreference)
preferences.​partialPaymentsobject(PartialPaymentsPreference)
preferences.​surchargingobject(PreferenceToggle)
Response
application/json
{
  "collectionMethod": "AUTO_COLLECT",
  "preferences": {
    "paymentReminders": { … },
    "mandateReminders": { … },
    "cardReminders": { … },
    "directDebitEncouragement": { … },
    "statements": { … },
    "lateFees": { … },
    "partialPayments": { … },
    "surcharging": { … }
  }
}

Reset the collection preferences for a recurring invoice

Request

Resets how collection is set up for the invoices this recurring invoice raises. Clears every override, not only these settings, including any set by Adfin or in the Adfin app. To turn a single setting off, PATCH it with an enabled of false instead; a pause set with :pause_collection survives.

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Path
recurringInvoiceIdstring(uuid)required

The identifier of the recurring invoice.

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

Responses

The overrides held against the recurring invoice are cleared. A recurring invoice that holds none is left as it is.

Response
No content

Change the collection preferences for a recurring invoice

Request

Changes how collection is set up for the invoices this recurring invoice raises. A field left out of the body is unchanged. partialPayments takes at most one of minimumAmount or minimumPercentage. statements, mandateReminders, cardReminders and directDebitEncouragement can only be set on the customer.

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Path
recurringInvoiceIdstring(uuid)required

The identifier of the recurring invoice.

Bodyapplication/jsonrequired
collectionMethodstring

The collection method to use.

Enum"AUTO_COLLECT""ON_DEMAND"
preferencesobject(CollectionPreferences)
curl -i -X PATCH \
  'https://developer.adfin.com/_mock/api-docs/prod/schedules/invoices/{recurringInvoiceId}/collection_preferences' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "collectionMethod": "AUTO_COLLECT",
    "preferences": {
      "paymentReminders": {
        "enabled": true
      },
      "mandateReminders": {
        "enabled": true
      },
      "cardReminders": {
        "enabled": true
      },
      "directDebitEncouragement": {
        "enabled": true
      },
      "statements": {
        "enabled": true
      },
      "lateFees": {
        "enabled": true,
        "gracePeriodDays": 0
      },
      "partialPayments": {
        "enabled": true,
        "minimumAmount": 0,
        "minimumPercentage": 0
      },
      "surcharging": {
        "enabled": true
      }
    }
  }'

Responses

The change was applied.

Response
No content

Payment requests

Operations

Recurring payment requests

Operations

Payments

Operations

Payouts

Operations

Tax rates

Operations

Items

Operations

Activities

What has happened to a customer, invoice, payment request or schedule.

Operations

Scheduled Activities

What is planned next for a customer or a payment request.

Operations

Webhooks

Operations

Referrals

Operations