Skip to content

Cookies, with your consent

Necessary cookies keep the site running. With your consent, Google Analytics measures visits and Google Ads measures our campaigns.Cookie policy

Resource · Billing

Invoices

An invoice is a sales invoice or a supplier bill of the workspace.

invoices:readinvoices:write
MethodPathSummary
GET…/invoicesList invoices in the workspace
GET…/invoices/searchSearch invoices by attributes
POST…/invoices/uploadGet an upload URL for a sales invoice or a bill document
POST…/invoices/upload-splitGet an upload URL for a document holding several sales invoices or bills
PATCH…/invoices/{invoiceId}Update an invoice
POST…/invoices/{invoiceId}/update-statusUpdate the status of an invoice
POST…/invoices/{invoiceId}/update-counterpartyUpdate the counterparty associated with an invoice
POST…/invoices/{invoiceId}/matches/addAdd a confirmed match between an invoice and a bank transaction
POST…/invoices/{invoiceId}/matches/confirmConfirm a candidate match between an invoice and a bank transaction
POST…/invoices/{invoiceId}/matches/removeRemove a confirmed match between an invoice and a bank transaction
POST…/invoices/{invoiceId}/matches/remove-candidateRemove a candidate match suggestion for an invoice
POST…/invoices/exportExport an invoice to a downloadable file

Paths start with /workspaces/{workspaceId}. GET endpoints need invoices:read, the others invoices:write.

The Invoice object

firestoreIdstringrequired

ID of the invoice.

workspaceIdstringrequired

ID of the workspace.

creationobjectrequired

When and by whom the resource was created.

Show 2 child fields
creationDateTimestringdate-timerequired

Date and time when the resource was created.

createdBystring

ID of the user who created the resource, when recorded.

invoiceStatusstringrequired

Status of the invoice in its lifecycle.

  • drafted

    Draft that may lack mandatory fields; an uploaded invoice starts here and moves to created once its data passes validation.

  • created

    Validated invoice, whose mandatory fields are all present and valid.

  • deleted

    Deleted invoice, which can no longer change status and is left out of transaction matching.

  • authorised

    Validated invoice that a user approved.

  • paid

    Validated invoice settled in full by matched bank transactions or marked as paid by a user; its mandatory fields can no longer change.

  • voided

    Cancelled invoice, left out of transaction matching.

processingStatusstringrequired

Progress of the data extraction from the invoice file.

  • uploaded

    The file is uploaded and its data is not extracted yet.

  • parsed

    The data is extracted from the file, or the invoice was imported without a file.

  • failed

    The data could not be extracted from the file, for example because the file is too large.

accountingTypestring

Direction of the invoice: a supplier bill to pay or a sales invoice to collect.

  • payable

    A bill received from a supplier, which the workspace pays.

  • receivable

    An invoice issued to a customer, which the workspace collects.

reconciledbooleanrequired
Show all 57 fields
processedbooleanrequired
paymentSubmittedbooleanrequired
sentDateTimestringdate-time
paymentMethodstring

Payment method of the invoice.

Show 13 values
  • creditCard

    Credit card.

  • debitCard

    Debit card.

  • directDebit

    Direct debit.

  • bankTransfer

    Bank transfer.

  • cash

    Cash.

  • voucher

    Voucher.

  • check

    Check.

  • paypal

    PayPal.

  • stripe

    Stripe.

  • applePay

    Apple Pay.

  • googlePay

    Google Pay.

  • samsungPay

    Samsung Pay.

  • unknown

    The payment method is not known.

supplierCounterpartyIdstring | null

ID of the counterparty.

receiverCounterpartyIdstring | null

ID of the counterparty.

storagePathstring
fileChecksumMd5string
fileChecksumCrc32cstring
amountDueMonetaryAmount | null
Show 2 child fields
amountnumberrequired

Amount in the main unit of the currency, such as francs.

currencystring | null

Currency of the amount, when known.

amountPaidSinceLastInvoiceMonetaryAmount | null
Show 2 child fields
amountnumberrequired

Amount in the main unit of the currency, such as francs.

currencystring | null

Currency of the amount, when known.

clientIdstring | null
currencystring | null

ISO 4217 currency code

dueDatestring | null
invoiceDatestring | null
invoiceIdstring | null
isUnpaidRemindernumber | null
netAmountMonetaryAmount | null
Show 2 child fields
amountnumberrequired

Amount in the main unit of the currency, such as francs.

currencystring | null

Currency of the amount, when known.

paymentTermsstring | null
purchaseOrderstring | null
receiverAddressAddressField | null

Postal address on a document, in which any part can be missing.

Show 12 child fields
countrystring | null

ISO 3166-1 alpha-2 country code

postCodestring | null

Post code of the address.

townNamestring | null

Name of the town or city.

streetNamestring | null

Name of the street.

buildingNumberstring | null

Number of the building in the street.

namestring | null

Name of the building or place.

sortingCodestring | null

Additional sorting code of the postal service, used in a few countries such as France.

postBoxstring | null

Post office box.

administrativeAreastring | null

Region of the country, such as a canton or a state.

recipientsstring[] | null

Names of the people the address is for.

organizationstring | null

Name of the organization at the address.

sourcestring[] | null

Text the address was read from, one item per line.

receiverBankAccountBankAccountField | null
Show 6 child fields
bankNamestring | null
bankAddressAddressField | null

Postal address on a document, in which any part can be missing.

Show 12 child fields
countrystring | null

ISO 3166-1 alpha-2 country code

postCodestring | null

Post code of the address.

townNamestring | null

Name of the town or city.

streetNamestring | null

Name of the street.

buildingNumberstring | null

Number of the building in the street.

namestring | null

Name of the building or place.

sortingCodestring | null

Additional sorting code of the postal service, used in a few countries such as France.

postBoxstring | null

Post office box.

administrativeAreastring | null

Region of the country, such as a canton or a state.

recipientsstring[] | null

Names of the people the address is for.

organizationstring | null

Name of the organization at the address.

sourcestring[] | null

Text the address was read from, one item per line.

bicstring | null
currencystring | null

ISO 4217 currency code

accountIdentificationstring | null
accountSecondaryIdentificationstring | null
receiverContactNamestring | null
receiverEmailstring | null
receiverNamestring | null
receiverPhonestring | null
receiverTaxIdstring | null
remitToAddressAddressField | null

Postal address on a document, in which any part can be missing.

Show 12 child fields
countrystring | null

ISO 3166-1 alpha-2 country code

postCodestring | null

Post code of the address.

townNamestring | null

Name of the town or city.

streetNamestring | null

Name of the street.

buildingNumberstring | null

Number of the building in the street.

namestring | null

Name of the building or place.

sortingCodestring | null

Additional sorting code of the postal service, used in a few countries such as France.

postBoxstring | null

Post office box.

administrativeAreastring | null

Region of the country, such as a canton or a state.

recipientsstring[] | null

Names of the people the address is for.

organizationstring | null

Name of the organization at the address.

sourcestring[] | null

Text the address was read from, one item per line.

remitToNamestring | null
shipToAddressAddressField | null

Postal address on a document, in which any part can be missing.

Show 12 child fields
countrystring | null

ISO 3166-1 alpha-2 country code

postCodestring | null

Post code of the address.

townNamestring | null

Name of the town or city.

streetNamestring | null

Name of the street.

buildingNumberstring | null

Number of the building in the street.

namestring | null

Name of the building or place.

sortingCodestring | null

Additional sorting code of the postal service, used in a few countries such as France.

postBoxstring | null

Post office box.

administrativeAreastring | null

Region of the country, such as a canton or a state.

recipientsstring[] | null

Names of the people the address is for.

organizationstring | null

Name of the organization at the address.

sourcestring[] | null

Text the address was read from, one item per line.

shipToNamestring | null
supplierAddressAddressField | null

Postal address on a document, in which any part can be missing.

Show 12 child fields
countrystring | null

ISO 3166-1 alpha-2 country code

postCodestring | null

Post code of the address.

townNamestring | null

Name of the town or city.

streetNamestring | null

Name of the street.

buildingNumberstring | null

Number of the building in the street.

namestring | null

Name of the building or place.

sortingCodestring | null

Additional sorting code of the postal service, used in a few countries such as France.

postBoxstring | null

Post office box.

administrativeAreastring | null

Region of the country, such as a canton or a state.

recipientsstring[] | null

Names of the people the address is for.

organizationstring | null

Name of the organization at the address.

sourcestring[] | null

Text the address was read from, one item per line.

supplierBankAccountsBankAccountField[] | null
Show 6 child fields
bankNamestring | null
bankAddressAddressField | null

Postal address on a document, in which any part can be missing.

Show 12 child fields
countrystring | null

ISO 3166-1 alpha-2 country code

postCodestring | null

Post code of the address.

townNamestring | null

Name of the town or city.

streetNamestring | null

Name of the street.

buildingNumberstring | null

Number of the building in the street.

namestring | null

Name of the building or place.

sortingCodestring | null

Additional sorting code of the postal service, used in a few countries such as France.

postBoxstring | null

Post office box.

administrativeAreastring | null

Region of the country, such as a canton or a state.

recipientsstring[] | null

Names of the people the address is for.

organizationstring | null

Name of the organization at the address.

sourcestring[] | null

Text the address was read from, one item per line.

bicstring | null
currencystring | null

ISO 4217 currency code

accountIdentificationstring | null
accountSecondaryIdentificationstring | null
supplierContactNamestring | null
supplierEmailstring | null
supplierNamestring | null
supplierPaymentRefstring | null
supplierPhonestring | null
supplierTaxIdstring | null
supplierWebsitestring | null
totalAmountMonetaryAmount | null
Show 2 child fields
amountnumberrequired

Amount in the main unit of the currency, such as francs.

currencystring | null

Currency of the amount, when known.

totalTaxAmountMonetaryAmount | null
Show 2 child fields
amountnumberrequired

Amount in the main unit of the currency, such as francs.

currencystring | null

Currency of the amount, when known.

itemsobject[] | null
Show 12 child fields
amountMonetaryAmount | null
Show 2 child fields
amountnumberrequired

Amount in the main unit of the currency, such as francs.

currencystring | null

Currency of the amount, when known.

descriptionstring | null
discountAmountMonetaryAmount | null
Show 2 child fields
amountnumberrequired

Amount in the main unit of the currency, such as francs.

currencystring | null

Currency of the amount, when known.

discountRatenumber | null
productCodestring | null
productIdstring | null

ID of the product.

quantitynumber | null
taxAmountMonetaryAmount | null
Show 2 child fields
amountnumberrequired

Amount in the main unit of the currency, such as francs.

currencystring | null

Currency of the amount, when known.

taxRatenumber | null
taxTypeIdstring | null

ID of the tax type.

unitstring | null
unitPriceMonetaryAmount | null
Show 2 child fields
amountnumberrequired

Amount in the main unit of the currency, such as francs.

currencystring | null

Currency of the amount, when known.

taxesobject[] | null
Show 4 child fields
netAmountBeforeTaxMonetaryAmount | null
Show 2 child fields
amountnumberrequired

Amount in the main unit of the currency, such as francs.

currencystring | null

Currency of the amount, when known.

taxAmountMonetaryAmount | null
Show 2 child fields
amountnumberrequired

Amount in the main unit of the currency, such as francs.

currencystring | null

Currency of the amount, when known.

taxCodestring | null
taxRatenumber | null
draftPaymentIdsstring[]
initiatedPaymentIdsstring[]
transactionCandidateMatchIdsstring[]
transactionConfirmedMatchIdsstring[]
transactionCandidateMatchesInvoiceMatch[]
Show 2 child fields
targetstringrequired
dataobjectrequired
Show 1 child field
confidencenumberrequired
transactionConfirmedMatchesInvoiceMatch[]
Show 2 child fields
targetstringrequired
dataobjectrequired
Show 1 child field
confidencenumberrequired
The Invoice object
{
  "firestoreId": "Iv5zP2nK7wRt3xMq9bLd",
  "workspaceId": "Wk7fQ2xR9bLm4tZp8sNv",
  "creation": {
    "creationDateTime": "2026-03-02T09:15:00.000Z",
    "createdBy": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj"
  },
  "invoiceStatus": "drafted",
  "processingStatus": "uploaded",
  "accountingType": "payable",
  "reconciled": true,
  "processed": true,
  "paymentSubmitted": true,
  "sentDateTime": "2026-03-02T09:30:00.000Z",
  "paymentMethod": "creditCard",
  "supplierCounterpartyId": "Cp2nG7vB4xLq9wRt5hMz",
  "receiverCounterpartyId": "Cp2nG7vB4xLq9wRt5hMz",
  "storagePath": "string",
  "fileChecksumMd5": "string",
  "fileChecksumCrc32c": "string",
  "amountDue": {
    "amount": 1250.5,
    "currency": "CHF"
  },
  "amountPaidSinceLastInvoice": {
    "amount": 1250.5,
    "currency": "CHF"
  },
  "clientId": "string",
  "currency": "CHF",
  "dueDate": "2026-03-02",
  "invoiceDate": "2026-03-02",
  "invoiceId": "string",
  "isUnpaidReminder": 0,
  "netAmount": {
    "amount": 1250.5,
    "currency": "CHF"
  },
  "paymentTerms": "string",
  "purchaseOrder": "string",
  "receiverAddress": {
    "country": "CH",
    "postCode": "8001",
    "townName": "Zürich",
    "streetName": "Bahnhofstrasse",
    "buildingNumber": "10",
    "name": "Haus zur Linde",
    "sortingCode": "string",
    "postBox": "Postfach 1234",
    "administrativeArea": "Zürich",
    "recipients": [
      "Anna Meier"
    ],
    "organization": "Muster AG",
    "source": [
      "Muster AG",
      "Bahnhofstrasse 10",
      "8001 Zürich"
    ]
  },
  "receiverBankAccount": {
    "bankName": "string",
    "bankAddress": {
      "country": "CH",
      "postCode": "8001",
      "townName": "Zürich",
      "streetName": "Bahnhofstrasse",
      "buildingNumber": "10",
      "name": "Haus zur Linde",
      "sortingCode": "string",
      "postBox": "Postfach 1234",
      "administrativeArea": "Zürich",
      "recipients": [
        "Anna Meier"
      ],
      "organization": "Muster AG",
      "source": [
        "Muster AG",
        "Bahnhofstrasse 10",
        "8001 Zürich"
      ]
    },
    "bic": "string",
    "currency": "CHF",
    "accountIdentification": "string",
    "accountSecondaryIdentification": "string"
  },
  "receiverContactName": "string",
  "receiverEmail": "string",
  "receiverName": "string",
  "receiverPhone": "string",
  "receiverTaxId": "string",
  "remitToAddress": {
    "country": "CH",
    "postCode": "8001",
    "townName": "Zürich",
    "streetName": "Bahnhofstrasse",
    "buildingNumber": "10",
    "name": "Haus zur Linde",
    "sortingCode": "string",
    "postBox": "Postfach 1234",
    "administrativeArea": "Zürich",
    "recipients": [
      "Anna Meier"
    ],
    "organization": "Muster AG",
    "source": [
      "Muster AG",
      "Bahnhofstrasse 10",
      "8001 Zürich"
    ]
  },
  "remitToName": "string",
  "shipToAddress": {
    "country": "CH",
    "postCode": "8001",
    "townName": "Zürich",
    "streetName": "Bahnhofstrasse",
    "buildingNumber": "10",
    "name": "Haus zur Linde",
    "sortingCode": "string",
    "postBox": "Postfach 1234",
    "administrativeArea": "Zürich",
    "recipients": [
      "Anna Meier"
    ],
    "organization": "Muster AG",
    "source": [
      "Muster AG",
      "Bahnhofstrasse 10",
      "8001 Zürich"
    ]
  },
  "shipToName": "string",
  "supplierAddress": {
    "country": "CH",
    "postCode": "8001",
    "townName": "Zürich",
    "streetName": "Bahnhofstrasse",
    "buildingNumber": "10",
    "name": "Haus zur Linde",
    "sortingCode": "string",
    "postBox": "Postfach 1234",
    "administrativeArea": "Zürich",
    "recipients": [
      "Anna Meier"
    ],
    "organization": "Muster AG",
    "source": [
      "Muster AG",
      "Bahnhofstrasse 10",
      "8001 Zürich"
    ]
  },
  "supplierBankAccounts": [
    {
      "bankName": "string",
      "bankAddress": {
        "country": "CH",
        "postCode": "8001",
        "townName": "Zürich",
        "streetName": "Bahnhofstrasse",
        "buildingNumber": "10",
        "name": "Haus zur Linde",
        "sortingCode": "string",
        "postBox": "Postfach 1234",
        "administrativeArea": "Zürich",
        "recipients": [
          "Anna Meier"
        ],
        "organization": "Muster AG",
        "source": [
          "Muster AG",
          "Bahnhofstrasse 10",
          "8001 Zürich"
        ]
      },
      "bic": "string",
      "currency": "CHF",
      "accountIdentification": "string",
      "accountSecondaryIdentification": "string"
    }
  ],
  "supplierContactName": "string",
  "supplierEmail": "string",
  "supplierName": "string",
  "supplierPaymentRef": "string",
  "supplierPhone": "string",
  "supplierTaxId": "string",
  "supplierWebsite": "string",
  "totalAmount": {
    "amount": 1250.5,
    "currency": "CHF"
  },
  "totalTaxAmount": {
    "amount": 1250.5,
    "currency": "CHF"
  },
  "items": [
    {
      "amount": {
        "amount": 1250.5,
        "currency": "CHF"
      },
      "description": "string",
      "discountAmount": {
        "amount": 1250.5,
        "currency": "CHF"
      },
      "discountRate": 0,
      "productCode": "string",
      "productId": "Pr4wJ8tM1xNq6zRb3vKf",
      "quantity": 0,
      "taxAmount": {
        "amount": 1250.5,
        "currency": "CHF"
      },
      "taxRate": 0,
      "taxTypeId": "Tt9mC5rL2wQz7nVb4kHp",
      "unit": "string",
      "unitPrice": {
        "amount": 1250.5,
        "currency": "CHF"
      }
    }
  ],
  "taxes": [
    {
      "netAmountBeforeTax": {
        "amount": 1250.5,
        "currency": "CHF"
      },
      "taxAmount": {
        "amount": 1250.5,
        "currency": "CHF"
      },
      "taxCode": "string",
      "taxRate": 0
    }
  ],
  "draftPaymentIds": [
    "string"
  ],
  "initiatedPaymentIds": [
    "string"
  ],
  "transactionCandidateMatchIds": [
    "string"
  ],
  "transactionConfirmedMatchIds": [
    "string"
  ],
  "transactionCandidateMatches": [
    {
      "target": "string",
      "data": {
        "confidence": 0
      }
    }
  ],
  "transactionConfirmedMatches": [
    {
      "target": "string",
      "data": {
        "confidence": 0
      }
    }
  ]
}
GET/workspaces/{workspaceId}/invoices

List invoices in the workspace

Scopeinvoices:read

Path parameters

workspaceIdstringrequired

ID of the workspace.

Query parameters

limitinteger

Maximum number of items to return, from 1 to 100. A missing, invalid or non-positive value falls back to 20, and a larger value to 100.

Default20

startAfterstring

Cursor of the page to return: the nextCursor of the previous page.

fieldsstring

Comma-separated property paths to include in the response, or in each item of a list. Use dots for nested paths.

idsstring[]

Comma-separated IDs of the items to return, up to 30. When set, limit, startAfter and the filters are ignored.

Returns

200

List of items

dataInvoice[]required

Items of the page, in list order.

limitintegerrequired

Page size of the request, or the number of requested ids.

nextCursorstring

Cursor of the next page, to pass as startAfter. Absent when the page holds fewer items than limit; a full last page still has one, and the page it points to is empty.

curl 'https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/invoices' \
  -H "Authorization: Bearer $SWAY_API_KEY"
{
  "data": [
    {
      "firestoreId": "Iv5zP2nK7wRt3xMq9bLd",
      "workspaceId": "Wk7fQ2xR9bLm4tZp8sNv",
      "creation": {
        "creationDateTime": "2026-03-02T09:15:00.000Z",
        "createdBy": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj"
      },
      "invoiceStatus": "drafted",
      "processingStatus": "uploaded",
      "accountingType": "payable",
      "reconciled": true,
      "processed": true,
      "paymentSubmitted": true,
      "sentDateTime": "2026-03-02T09:30:00.000Z",
      "paymentMethod": "creditCard",
      "supplierCounterpartyId": "Cp2nG7vB4xLq9wRt5hMz",
      "receiverCounterpartyId": "Cp2nG7vB4xLq9wRt5hMz",
      "storagePath": "string",
      "fileChecksumMd5": "string",
      "fileChecksumCrc32c": "string",
      "amountDue": {
        "amount": 1250.5,
        "currency": "CHF"
      },
      "amountPaidSinceLastInvoice": {
        "amount": 1250.5,
        "currency": "CHF"
      },
      "clientId": "string",
      "currency": "CHF",
      "dueDate": "2026-03-02",
      "invoiceDate": "2026-03-02",
      "invoiceId": "string",
      "isUnpaidReminder": 0,
      "netAmount": {
        "amount": 1250.5,
        "currency": "CHF"
      },
      "paymentTerms": "string",
      "purchaseOrder": "string",
      "receiverAddress": {…},
      "receiverBankAccount": {…},
      "receiverContactName": "string",
      "receiverEmail": "string",
      "receiverName": "string",
      "receiverPhone": "string",
      "receiverTaxId": "string",
      "remitToAddress": {…},
      "remitToName": "string",
      "shipToAddress": {…},
      "shipToName": "string",
      "supplierAddress": {…},
      "supplierBankAccounts": […],
      "supplierContactName": "string",
      "supplierEmail": "string",
      "supplierName": "string",
      "supplierPaymentRef": "string",
      "supplierPhone": "string",
      "supplierTaxId": "string",
      "supplierWebsite": "string",
      "totalAmount": {
        "amount": 1250.5,
        "currency": "CHF"
      },
      "totalTaxAmount": {
        "amount": 1250.5,
        "currency": "CHF"
      },
      "items": […],
      "taxes": […],
      "draftPaymentIds": [
        "string"
      ],
      "initiatedPaymentIds": [
        "string"
      ],
      "transactionCandidateMatchIds": [
        "string"
      ],
      "transactionConfirmedMatchIds": [
        "string"
      ],
      "transactionCandidateMatches": […],
      "transactionConfirmedMatches": […]
    }
  ],
  "limit": 0,
  "nextCursor": "string"
}
POST/workspaces/{workspaceId}/invoices/upload

Get an upload URL for a sales invoice or a bill document

The document is a PDF or an image. The characters <>:"/\|?*#^ are removed from fileName, and a name left empty is rejected. PUT the file bytes to uploadUrl with the returned contentType. Once uploaded, the document is parsed in the background into a new invoice (receivable) or bill (payable). With bankAccountId and bankTransactionId, the new invoice is matched with that bank transaction.

Scopeinvoices:write

Path parameters

workspaceIdstringrequired

ID of the workspace.

Query parameters

fieldsstring

Comma-separated property paths to include in the response, or in each item of a list. Use dots for nested paths.

Request body

accountingTypestringrequired

Direction of the invoice: a supplier bill to pay or a sales invoice to collect.

  • payable

    A bill received from a supplier, which the workspace pays.

  • receivable

    An invoice issued to a customer, which the workspace collects.

fileNamestringrequired
contentTypestringrequired
sizeintegerrequired
bankAccountIdstring

ID of the bank account.

bankTransactionIdstring

ID of the bank transaction.

Returns

200

Successful response

dataFileUploadUrlrequired
Show 3 child fields
uploadUrlstringurirequired
contentTypestringrequired
sizeintegerrequired
curl -X POST 'https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/invoices/upload' \
  -H "Authorization: Bearer $SWAY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "accountingType": "payable",
  "fileName": "string",
  "contentType": "string",
  "size": 0,
  "bankAccountId": "bacc_Q0gzMTA4NzY1NDM",
  "bankTransactionId": "trx_MjAyNjAzMDJUMDk"
}'
{
  "data": {
    "uploadUrl": "https://example.com",
    "contentType": "string",
    "size": 0
  }
}
POST/workspaces/{workspaceId}/invoices/upload-split

Get an upload URL for a document holding several sales invoices or bills

The document is a PDF or an image. The characters <>:"/\|?*#^ are removed from fileName, and a name left empty is rejected. PUT the file bytes to uploadUrl with the returned contentType. Once uploaded, the document is split in the background into one document per invoice or receipt. Each invoice is parsed into a new invoice (receivable) or bill (payable), and each receipt into a new bill.

Scopeinvoices:write

Path parameters

workspaceIdstringrequired

ID of the workspace.

Query parameters

fieldsstring

Comma-separated property paths to include in the response, or in each item of a list. Use dots for nested paths.

Request body

accountingTypestringrequired

Direction of the invoice: a supplier bill to pay or a sales invoice to collect.

  • payable

    A bill received from a supplier, which the workspace pays.

  • receivable

    An invoice issued to a customer, which the workspace collects.

fileNamestringrequired
contentTypestringrequired
sizeintegerrequired

Returns

200

Successful response

dataFileUploadUrlrequired
Show 3 child fields
uploadUrlstringurirequired
contentTypestringrequired
sizeintegerrequired
curl -X POST 'https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/invoices/upload-split' \
  -H "Authorization: Bearer $SWAY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "accountingType": "payable",
  "fileName": "string",
  "contentType": "string",
  "size": 0
}'
{
  "data": {
    "uploadUrl": "https://example.com",
    "contentType": "string",
    "size": 0
  }
}
PATCH/workspaces/{workspaceId}/invoices/{invoiceId}

Update an invoice

Scopeinvoices:write

Path parameters

workspaceIdstringrequired

ID of the workspace.

invoiceIdstringrequired

ID of the invoice.

Query parameters

fieldsstring

Comma-separated property paths to include in the response, or in each item of a list. Use dots for nested paths.

Request body

fieldsobjectrequired
Show 38 child fields
amountDueMonetaryAmount | null
Show 2 child fields
amountnumberrequired

Amount in the main unit of the currency, such as francs.

currencystring | null

Currency of the amount, when known.

amountPaidSinceLastInvoiceMonetaryAmount | null
Show 2 child fields
amountnumberrequired

Amount in the main unit of the currency, such as francs.

currencystring | null

Currency of the amount, when known.

clientIdstring | null
currencystring | null

ISO 4217 currency code

dueDatestring | null
footerstring | null

Text printed at the bottom of the invoice.

headerstring | null

Text printed at the top of the invoice.

invoiceDatestring | null
invoiceIdstring | null
isUnpaidRemindernumber | null
netAmountMonetaryAmount | null
Show 2 child fields
amountnumberrequired

Amount in the main unit of the currency, such as francs.

currencystring | null

Currency of the amount, when known.

paymentTermsstring | null
purchaseOrderstring | null
receiverAddressAddressField | null

Postal address on a document, in which any part can be missing.

Show 12 child fields
countrystring | null

ISO 3166-1 alpha-2 country code

postCodestring | null

Post code of the address.

townNamestring | null

Name of the town or city.

streetNamestring | null

Name of the street.

buildingNumberstring | null

Number of the building in the street.

namestring | null

Name of the building or place.

sortingCodestring | null

Additional sorting code of the postal service, used in a few countries such as France.

postBoxstring | null

Post office box.

administrativeAreastring | null

Region of the country, such as a canton or a state.

recipientsstring[] | null

Names of the people the address is for.

organizationstring | null

Name of the organization at the address.

sourcestring[] | null

Text the address was read from, one item per line.

receiverBankAccountBankAccountField | null
Show 6 child fields
bankNamestring | null
bankAddressAddressField | null

Postal address on a document, in which any part can be missing.

Show 12 child fields
countrystring | null

ISO 3166-1 alpha-2 country code

postCodestring | null

Post code of the address.

townNamestring | null

Name of the town or city.

streetNamestring | null

Name of the street.

buildingNumberstring | null

Number of the building in the street.

namestring | null

Name of the building or place.

sortingCodestring | null

Additional sorting code of the postal service, used in a few countries such as France.

postBoxstring | null

Post office box.

administrativeAreastring | null

Region of the country, such as a canton or a state.

recipientsstring[] | null

Names of the people the address is for.

organizationstring | null

Name of the organization at the address.

sourcestring[] | null

Text the address was read from, one item per line.

bicstring | null
currencystring | null

ISO 4217 currency code

accountIdentificationstring | null
accountSecondaryIdentificationstring | null
receiverContactNamestring | null
receiverEmailstring | null
receiverNamestring | null
receiverPhonestring | null
receiverTaxIdstring | null
remitToAddressAddressField | null

Postal address on a document, in which any part can be missing.

Show 12 child fields
countrystring | null

ISO 3166-1 alpha-2 country code

postCodestring | null

Post code of the address.

townNamestring | null

Name of the town or city.

streetNamestring | null

Name of the street.

buildingNumberstring | null

Number of the building in the street.

namestring | null

Name of the building or place.

sortingCodestring | null

Additional sorting code of the postal service, used in a few countries such as France.

postBoxstring | null

Post office box.

administrativeAreastring | null

Region of the country, such as a canton or a state.

recipientsstring[] | null

Names of the people the address is for.

organizationstring | null

Name of the organization at the address.

sourcestring[] | null

Text the address was read from, one item per line.

remitToNamestring | null
shipToAddressAddressField | null

Postal address on a document, in which any part can be missing.

Show 12 child fields
countrystring | null

ISO 3166-1 alpha-2 country code

postCodestring | null

Post code of the address.

townNamestring | null

Name of the town or city.

streetNamestring | null

Name of the street.

buildingNumberstring | null

Number of the building in the street.

namestring | null

Name of the building or place.

sortingCodestring | null

Additional sorting code of the postal service, used in a few countries such as France.

postBoxstring | null

Post office box.

administrativeAreastring | null

Region of the country, such as a canton or a state.

recipientsstring[] | null

Names of the people the address is for.

organizationstring | null

Name of the organization at the address.

sourcestring[] | null

Text the address was read from, one item per line.

shipToNamestring | null
supplierAddressAddressField | null

Postal address on a document, in which any part can be missing.

Show 12 child fields
countrystring | null

ISO 3166-1 alpha-2 country code

postCodestring | null

Post code of the address.

townNamestring | null

Name of the town or city.

streetNamestring | null

Name of the street.

buildingNumberstring | null

Number of the building in the street.

namestring | null

Name of the building or place.

sortingCodestring | null

Additional sorting code of the postal service, used in a few countries such as France.

postBoxstring | null

Post office box.

administrativeAreastring | null

Region of the country, such as a canton or a state.

recipientsstring[] | null

Names of the people the address is for.

organizationstring | null

Name of the organization at the address.

sourcestring[] | null

Text the address was read from, one item per line.

supplierBankAccountsBankAccountField[] | null
Show 6 child fields
bankNamestring | null
bankAddressAddressField | null

Postal address on a document, in which any part can be missing.

Show 12 child fields
countrystring | null

ISO 3166-1 alpha-2 country code

postCodestring | null

Post code of the address.

townNamestring | null

Name of the town or city.

streetNamestring | null

Name of the street.

buildingNumberstring | null

Number of the building in the street.

namestring | null

Name of the building or place.

sortingCodestring | null

Additional sorting code of the postal service, used in a few countries such as France.

postBoxstring | null

Post office box.

administrativeAreastring | null

Region of the country, such as a canton or a state.

recipientsstring[] | null

Names of the people the address is for.

organizationstring | null

Name of the organization at the address.

sourcestring[] | null

Text the address was read from, one item per line.

bicstring | null
currencystring | null

ISO 4217 currency code

accountIdentificationstring | null
accountSecondaryIdentificationstring | null
supplierContactNamestring | null
supplierEmailstring | null
supplierNamestring | null
supplierPaymentRefstring | null
supplierPhonestring | null
supplierTaxIdstring | null
supplierWebsitestring | null
totalAmountMonetaryAmount | null
Show 2 child fields
amountnumberrequired

Amount in the main unit of the currency, such as francs.

currencystring | null

Currency of the amount, when known.

totalTaxAmountMonetaryAmount | null
Show 2 child fields
amountnumberrequired

Amount in the main unit of the currency, such as francs.

currencystring | null

Currency of the amount, when known.

itemsobject[] | null
Show 12 child fields
amountMonetaryAmount | null
Show 2 child fields
amountnumberrequired

Amount in the main unit of the currency, such as francs.

currencystring | null

Currency of the amount, when known.

descriptionstring | null
discountAmountMonetaryAmount | null
Show 2 child fields
amountnumberrequired

Amount in the main unit of the currency, such as francs.

currencystring | null

Currency of the amount, when known.

discountRatenumber | null
productCodestring | null
productIdstring | null

ID of the product.

quantitynumber | null
taxAmountMonetaryAmount | null
Show 2 child fields
amountnumberrequired

Amount in the main unit of the currency, such as francs.

currencystring | null

Currency of the amount, when known.

taxRatenumber | null
taxTypeIdstring | null

ID of the tax type.

unitstring | null
unitPriceMonetaryAmount | null
Show 2 child fields
amountnumberrequired

Amount in the main unit of the currency, such as francs.

currencystring | null

Currency of the amount, when known.

taxesobject[] | null
Show 4 child fields
netAmountBeforeTaxMonetaryAmount | null
Show 2 child fields
amountnumberrequired

Amount in the main unit of the currency, such as francs.

currencystring | null

Currency of the amount, when known.

taxAmountMonetaryAmount | null
Show 2 child fields
amountnumberrequired

Amount in the main unit of the currency, such as francs.

currencystring | null

Currency of the amount, when known.

taxCodestring | null
taxRatenumber | null
qrCodeDatastring[] | null

Returns

200

Successful response

dataInvoicerequired
curl -X PATCH 'https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/invoices/Iv5zP2nK7wRt3xMq9bLd' \
  -H "Authorization: Bearer $SWAY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "fields": {
    "amountDue": {
      "amount": 1250.5,
      "currency": "CHF"
    },
    "amountPaidSinceLastInvoice": {
      "amount": 1250.5,
      "currency": "CHF"
    },
    "currency": "CHF",
    "dueDate": "2026-03-02",
    "invoiceDate": "2026-03-02",
    "netAmount": {
      "amount": 1250.5,
      "currency": "CHF"
    },
    "receiverAddress": {
      "country": "CH",
      "postCode": "8001",
      "townName": "Zürich",
      "streetName": "Bahnhofstrasse",
      "buildingNumber": "10",
      "name": "Haus zur Linde",
      "postBox": "Postfach 1234",
      "administrativeArea": "Zürich",
      "recipients": [
        "Anna Meier"
      ],
      "organization": "Muster AG",
      "source": [
        "Muster AG",
        "Bahnhofstrasse 10",
        "8001 Zürich"
      ]
    },
    "receiverBankAccount": {
      "bankAddress": {
        "country": "CH",
        "postCode": "8001",
        "townName": "Zürich",
        "streetName": "Bahnhofstrasse",
        "buildingNumber": "10",
        "name": "Haus zur Linde",
        "postBox": "Postfach 1234",
        "administrativeArea": "Zürich",
        "recipients": [
          "Anna Meier"
        ],
        "organization": "Muster AG",
        "source": [
          "Muster AG",
          "Bahnhofstrasse 10",
          "8001 Zürich"
        ]
      },
      "currency": "CHF"
    },
    "remitToAddress": {
      "country": "CH",
      "postCode": "8001",
      "townName": "Zürich",
      "streetName": "Bahnhofstrasse",
      "buildingNumber": "10",
      "name": "Haus zur Linde",
      "postBox": "Postfach 1234",
      "administrativeArea": "Zürich",
      "recipients": [
        "Anna Meier"
      ],
      "organization": "Muster AG",
      "source": [
        "Muster AG",
        "Bahnhofstrasse 10",
        "8001 Zürich"
      ]
    },
    "shipToAddress": {
      "country": "CH",
      "postCode": "8001",
      "townName": "Zürich",
      "streetName": "Bahnhofstrasse",
      "buildingNumber": "10",
      "name": "Haus zur Linde",
      "postBox": "Postfach 1234",
      "administrativeArea": "Zürich",
      "recipients": [
        "Anna Meier"
      ],
      "organization": "Muster AG",
      "source": [
        "Muster AG",
        "Bahnhofstrasse 10",
        "8001 Zürich"
      ]
    },
    "supplierAddress": {
      "country": "CH",
      "postCode": "8001",
      "townName": "Zürich",
      "streetName": "Bahnhofstrasse",
      "buildingNumber": "10",
      "name": "Haus zur Linde",
      "postBox": "Postfach 1234",
      "administrativeArea": "Zürich",
      "recipients": [
        "Anna Meier"
      ],
      "organization": "Muster AG",
      "source": [
        "Muster AG",
        "Bahnhofstrasse 10",
        "8001 Zürich"
      ]
    },
    "supplierBankAccounts": [
      {
        "bankAddress": {
          "country": "CH",
          "postCode": "8001",
          "townName": "Zürich",
          "streetName": "Bahnhofstrasse",
          "buildingNumber": "10",
          "name": "Haus zur Linde",
          "postBox": "Postfach 1234",
          "administrativeArea": "Zürich",
          "recipients": [
            "Anna Meier"
          ],
          "organization": "Muster AG",
          "source": [
            "Muster AG",
            "Bahnhofstrasse 10",
            "8001 Zürich"
          ]
        },
        "currency": "CHF"
      }
    ],
    "totalAmount": {
      "amount": 1250.5,
      "currency": "CHF"
    },
    "totalTaxAmount": {
      "amount": 1250.5,
      "currency": "CHF"
    },
    "items": [
      {
        "amount": {
          "amount": 1250.5,
          "currency": "CHF"
        },
        "discountAmount": {
          "amount": 1250.5,
          "currency": "CHF"
        },
        "productId": "Pr4wJ8tM1xNq6zRb3vKf",
        "taxAmount": {
          "amount": 1250.5,
          "currency": "CHF"
        },
        "taxTypeId": "Tt9mC5rL2wQz7nVb4kHp",
        "unitPrice": {
          "amount": 1250.5,
          "currency": "CHF"
        }
      }
    ],
    "taxes": [
      {
        "netAmountBeforeTax": {
          "amount": 1250.5,
          "currency": "CHF"
        },
        "taxAmount": {
          "amount": 1250.5,
          "currency": "CHF"
        }
      }
    ]
  }
}'
{
  "data": {
    "firestoreId": "Iv5zP2nK7wRt3xMq9bLd",
    "workspaceId": "Wk7fQ2xR9bLm4tZp8sNv",
    "creation": {
      "creationDateTime": "2026-03-02T09:15:00.000Z",
      "createdBy": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj"
    },
    "invoiceStatus": "drafted",
    "processingStatus": "uploaded",
    "accountingType": "payable",
    "reconciled": true,
    "processed": true,
    "paymentSubmitted": true,
    "sentDateTime": "2026-03-02T09:30:00.000Z",
    "paymentMethod": "creditCard",
    "supplierCounterpartyId": "Cp2nG7vB4xLq9wRt5hMz",
    "receiverCounterpartyId": "Cp2nG7vB4xLq9wRt5hMz",
    "storagePath": "string",
    "fileChecksumMd5": "string",
    "fileChecksumCrc32c": "string",
    "amountDue": {
      "amount": 1250.5,
      "currency": "CHF"
    },
    "amountPaidSinceLastInvoice": {
      "amount": 1250.5,
      "currency": "CHF"
    },
    "clientId": "string",
    "currency": "CHF",
    "dueDate": "2026-03-02",
    "invoiceDate": "2026-03-02",
    "invoiceId": "string",
    "isUnpaidReminder": 0,
    "netAmount": {
      "amount": 1250.5,
      "currency": "CHF"
    },
    "paymentTerms": "string",
    "purchaseOrder": "string",
    "receiverAddress": {…},
    "receiverBankAccount": {…},
    "receiverContactName": "string",
    "receiverEmail": "string",
    "receiverName": "string",
    "receiverPhone": "string",
    "receiverTaxId": "string",
    "remitToAddress": {…},
    "remitToName": "string",
    "shipToAddress": {…},
    "shipToName": "string",
    "supplierAddress": {…},
    "supplierBankAccounts": […],
    "supplierContactName": "string",
    "supplierEmail": "string",
    "supplierName": "string",
    "supplierPaymentRef": "string",
    "supplierPhone": "string",
    "supplierTaxId": "string",
    "supplierWebsite": "string",
    "totalAmount": {
      "amount": 1250.5,
      "currency": "CHF"
    },
    "totalTaxAmount": {
      "amount": 1250.5,
      "currency": "CHF"
    },
    "items": […],
    "taxes": […],
    "draftPaymentIds": [
      "string"
    ],
    "initiatedPaymentIds": [
      "string"
    ],
    "transactionCandidateMatchIds": [
      "string"
    ],
    "transactionConfirmedMatchIds": [
      "string"
    ],
    "transactionCandidateMatches": […],
    "transactionConfirmedMatches": […]
  }
}
POST/workspaces/{workspaceId}/invoices/{invoiceId}/update-status

Update the status of an invoice

Scopeinvoices:write

Path parameters

workspaceIdstringrequired

ID of the workspace.

invoiceIdstringrequired

ID of the invoice.

Query parameters

fieldsstring

Comma-separated property paths to include in the response, or in each item of a list. Use dots for nested paths.

Request body

statusstring

Status of the invoice in its lifecycle.

  • drafted

    Draft that may lack mandatory fields; an uploaded invoice starts here and moves to created once its data passes validation.

  • created

    Validated invoice, whose mandatory fields are all present and valid.

  • deleted

    Deleted invoice, which can no longer change status and is left out of transaction matching.

  • authorised

    Validated invoice that a user approved.

  • paid

    Validated invoice settled in full by matched bank transactions or marked as paid by a user; its mandatory fields can no longer change.

  • voided

    Cancelled invoice, left out of transaction matching.

processedboolean
paymentSubmittedboolean

Returns

200

Successful response

dataInvoicerequired
curl -X POST 'https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/invoices/Iv5zP2nK7wRt3xMq9bLd/update-status' \
  -H "Authorization: Bearer $SWAY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "status": "drafted"
}'
{
  "data": {
    "firestoreId": "Iv5zP2nK7wRt3xMq9bLd",
    "workspaceId": "Wk7fQ2xR9bLm4tZp8sNv",
    "creation": {
      "creationDateTime": "2026-03-02T09:15:00.000Z",
      "createdBy": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj"
    },
    "invoiceStatus": "drafted",
    "processingStatus": "uploaded",
    "accountingType": "payable",
    "reconciled": true,
    "processed": true,
    "paymentSubmitted": true,
    "sentDateTime": "2026-03-02T09:30:00.000Z",
    "paymentMethod": "creditCard",
    "supplierCounterpartyId": "Cp2nG7vB4xLq9wRt5hMz",
    "receiverCounterpartyId": "Cp2nG7vB4xLq9wRt5hMz",
    "storagePath": "string",
    "fileChecksumMd5": "string",
    "fileChecksumCrc32c": "string",
    "amountDue": {
      "amount": 1250.5,
      "currency": "CHF"
    },
    "amountPaidSinceLastInvoice": {
      "amount": 1250.5,
      "currency": "CHF"
    },
    "clientId": "string",
    "currency": "CHF",
    "dueDate": "2026-03-02",
    "invoiceDate": "2026-03-02",
    "invoiceId": "string",
    "isUnpaidReminder": 0,
    "netAmount": {
      "amount": 1250.5,
      "currency": "CHF"
    },
    "paymentTerms": "string",
    "purchaseOrder": "string",
    "receiverAddress": {…},
    "receiverBankAccount": {…},
    "receiverContactName": "string",
    "receiverEmail": "string",
    "receiverName": "string",
    "receiverPhone": "string",
    "receiverTaxId": "string",
    "remitToAddress": {…},
    "remitToName": "string",
    "shipToAddress": {…},
    "shipToName": "string",
    "supplierAddress": {…},
    "supplierBankAccounts": […],
    "supplierContactName": "string",
    "supplierEmail": "string",
    "supplierName": "string",
    "supplierPaymentRef": "string",
    "supplierPhone": "string",
    "supplierTaxId": "string",
    "supplierWebsite": "string",
    "totalAmount": {
      "amount": 1250.5,
      "currency": "CHF"
    },
    "totalTaxAmount": {
      "amount": 1250.5,
      "currency": "CHF"
    },
    "items": […],
    "taxes": […],
    "draftPaymentIds": [
      "string"
    ],
    "initiatedPaymentIds": [
      "string"
    ],
    "transactionCandidateMatchIds": [
      "string"
    ],
    "transactionConfirmedMatchIds": [
      "string"
    ],
    "transactionCandidateMatches": […],
    "transactionConfirmedMatches": […]
  }
}
POST/workspaces/{workspaceId}/invoices/{invoiceId}/update-counterparty

Update the counterparty associated with an invoice

Scopeinvoices:write

Path parameters

workspaceIdstringrequired

ID of the workspace.

invoiceIdstringrequired

ID of the invoice.

Query parameters

fieldsstring

Comma-separated property paths to include in the response, or in each item of a list. Use dots for nested paths.

Request body

counterpartyIdstring | nullrequired

ID of the counterparty.

Returns

200

Successful response

dataInvoicerequired
curl -X POST 'https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/invoices/Iv5zP2nK7wRt3xMq9bLd/update-counterparty' \
  -H "Authorization: Bearer $SWAY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "counterpartyId": "Cp2nG7vB4xLq9wRt5hMz"
}'
{
  "data": {
    "firestoreId": "Iv5zP2nK7wRt3xMq9bLd",
    "workspaceId": "Wk7fQ2xR9bLm4tZp8sNv",
    "creation": {
      "creationDateTime": "2026-03-02T09:15:00.000Z",
      "createdBy": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj"
    },
    "invoiceStatus": "drafted",
    "processingStatus": "uploaded",
    "accountingType": "payable",
    "reconciled": true,
    "processed": true,
    "paymentSubmitted": true,
    "sentDateTime": "2026-03-02T09:30:00.000Z",
    "paymentMethod": "creditCard",
    "supplierCounterpartyId": "Cp2nG7vB4xLq9wRt5hMz",
    "receiverCounterpartyId": "Cp2nG7vB4xLq9wRt5hMz",
    "storagePath": "string",
    "fileChecksumMd5": "string",
    "fileChecksumCrc32c": "string",
    "amountDue": {
      "amount": 1250.5,
      "currency": "CHF"
    },
    "amountPaidSinceLastInvoice": {
      "amount": 1250.5,
      "currency": "CHF"
    },
    "clientId": "string",
    "currency": "CHF",
    "dueDate": "2026-03-02",
    "invoiceDate": "2026-03-02",
    "invoiceId": "string",
    "isUnpaidReminder": 0,
    "netAmount": {
      "amount": 1250.5,
      "currency": "CHF"
    },
    "paymentTerms": "string",
    "purchaseOrder": "string",
    "receiverAddress": {…},
    "receiverBankAccount": {…},
    "receiverContactName": "string",
    "receiverEmail": "string",
    "receiverName": "string",
    "receiverPhone": "string",
    "receiverTaxId": "string",
    "remitToAddress": {…},
    "remitToName": "string",
    "shipToAddress": {…},
    "shipToName": "string",
    "supplierAddress": {…},
    "supplierBankAccounts": […],
    "supplierContactName": "string",
    "supplierEmail": "string",
    "supplierName": "string",
    "supplierPaymentRef": "string",
    "supplierPhone": "string",
    "supplierTaxId": "string",
    "supplierWebsite": "string",
    "totalAmount": {
      "amount": 1250.5,
      "currency": "CHF"
    },
    "totalTaxAmount": {
      "amount": 1250.5,
      "currency": "CHF"
    },
    "items": […],
    "taxes": […],
    "draftPaymentIds": [
      "string"
    ],
    "initiatedPaymentIds": [
      "string"
    ],
    "transactionCandidateMatchIds": [
      "string"
    ],
    "transactionConfirmedMatchIds": [
      "string"
    ],
    "transactionCandidateMatches": […],
    "transactionConfirmedMatches": […]
  }
}
POST/workspaces/{workspaceId}/invoices/{invoiceId}/matches/add

Add a confirmed match between an invoice and a bank transaction

Scopeinvoices:write

Path parameters

workspaceIdstringrequired

ID of the workspace.

invoiceIdstringrequired

ID of the invoice.

Request body

bankAccountIdstringrequired

ID of the bank account.

bankTransactionIdstringrequired

ID of the bank transaction.

Returns

204

No content

curl -X POST 'https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/invoices/Iv5zP2nK7wRt3xMq9bLd/matches/add' \
  -H "Authorization: Bearer $SWAY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "bankAccountId": "bacc_Q0gzMTA4NzY1NDM",
  "bankTransactionId": "trx_MjAyNjAzMDJUMDk"
}'
{
  "error": {
    "code": "invalid-argument",
    "message": "Invalid request"
  }
}
POST/workspaces/{workspaceId}/invoices/{invoiceId}/matches/confirm

Confirm a candidate match between an invoice and a bank transaction

Scopeinvoices:write

Path parameters

workspaceIdstringrequired

ID of the workspace.

invoiceIdstringrequired

ID of the invoice.

Query parameters

fieldsstring

Comma-separated property paths to include in the response, or in each item of a list. Use dots for nested paths.

Request body

matchReferencestringrequired

Returns

200

Successful response

dataInvoiceMatchrequired
Show 2 child fields
targetstringrequired
dataobjectrequired
Show 1 child field
confidencenumberrequired
curl -X POST 'https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/invoices/Iv5zP2nK7wRt3xMq9bLd/matches/confirm' \
  -H "Authorization: Bearer $SWAY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "matchReference": "string"
}'
{
  "data": {
    "target": "string",
    "data": {
      "confidence": 0
    }
  }
}
POST/workspaces/{workspaceId}/invoices/{invoiceId}/matches/remove

Remove a confirmed match between an invoice and a bank transaction

Scopeinvoices:write

Path parameters

workspaceIdstringrequired

ID of the workspace.

invoiceIdstringrequired

ID of the invoice.

Request body

matchReferencestringrequired

Returns

204

No content

curl -X POST 'https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/invoices/Iv5zP2nK7wRt3xMq9bLd/matches/remove' \
  -H "Authorization: Bearer $SWAY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "matchReference": "string"
}'
{
  "error": {
    "code": "invalid-argument",
    "message": "Invalid request"
  }
}
POST/workspaces/{workspaceId}/invoices/{invoiceId}/matches/remove-candidate

Remove a candidate match suggestion for an invoice

Scopeinvoices:write

Path parameters

workspaceIdstringrequired

ID of the workspace.

invoiceIdstringrequired

ID of the invoice.

Request body

matchReferencestringrequired

Returns

204

No content

curl -X POST 'https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/invoices/Iv5zP2nK7wRt3xMq9bLd/matches/remove-candidate' \
  -H "Authorization: Bearer $SWAY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "matchReference": "string"
}'
{
  "error": {
    "code": "invalid-argument",
    "message": "Invalid request"
  }
}
POST/workspaces/{workspaceId}/invoices/export

Export an invoice to a downloadable file

Scopeinvoices:write

Path parameters

workspaceIdstringrequired

ID of the workspace.

Query parameters

fieldsstring

Comma-separated property paths to include in the response, or in each item of a list. Use dots for nested paths.

Request body

exportTypestringrequired

Format of the invoice export.

  • csv

    CSV file of the invoices, with the columns in fields.

  • pain.001

    ISO 20022 pain.001 payment file that pays the invoices from the bank account bankAccountId.

invoiceIdsstring[]required

ID of the invoice.

bankAccountIdstring

ID of the bank account.

counterpartyCashAccountIdsRecord<string, string>
requestedExecutionDatestring
requestedExecutionDateModestring

ValuesdueDatecommonDate

localTimeZonestring
markAsPaymentSubmittedboolean
fieldsobject[]
Show 4 child fields
fieldstringrequired
Show 40 values

invoice_idinvoice_datedue_datenet_amounttax_amounttotal_amountamount_duecurrencystatusprocessing_statusaccounting_typepurchase_orderpayment_termsclient_idsupplier_namesupplier_addresssupplier_contactsupplier_emailsupplier_phonesupplier_tax_idsupplier_bank_accountsreceiver_namereceiver_addressreceiver_contactreceiver_emailreceiver_phonereceiver_tax_idreceiver_bank_accountship_to_nameship_to_addressremit_to_nameremit_to_addresspayment_referenceline_itemstaxescreation_dateis_unpaid_reminderreconciledprocessedpayment_submitted

namestring
defaultValuestring
formatstring

Returns

200

Successful response

dataInvoiceExportrequired
Show 3 child fields
startedbooleanrequired
workspaceIdstringrequired
filesobject[]required
Show 4 child fields
exportIdstringrequired
targetFileNamestringrequired
downloadUrlstringurirequired

Time-limited URL to download the file. The file may not be ready the moment the export call returns: poll this URL and retry while it responds with 404 until the download succeeds.

expiresAtstringrequired

Instant after which downloadUrl stops working.

curl -X POST 'https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/invoices/export' \
  -H "Authorization: Bearer $SWAY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "exportType": "csv",
  "invoiceIds": [
    "Iv5zP2nK7wRt3xMq9bLd"
  ],
  "bankAccountId": "bacc_Q0gzMTA4NzY1NDM",
  "requestedExecutionDate": "2026-03-02",
  "requestedExecutionDateMode": "dueDate",
  "fields": [
    {
      "field": "invoice_id"
    }
  ]
}'
{
  "data": {
    "started": true,
    "workspaceId": "string",
    "files": [
      {
        "exportId": "string",
        "targetFileName": "string",
        "downloadUrl": "https://example.com",
        "expiresAt": "2026-03-02T09:30:00.000Z"
      }
    ]
  }
}

Start building on your own data.

Create an account, open Profile › Developer and create a key scoped to the resources you need. Questions about an integration? The team answers them on a call.

Create an API key in SwaySchedule a call