Sign in
invoice

Generate a monthly invoice PDF by buyer wallet vkey and month. (+PAY access required)

Changed on

Generates an invoice PDF aggregating all payment requests for a buyer wallet within a month, using the end-of-month conversion rate. (+PAY access required)

BETA: This invoice feature is in beta. Generated invoices should be reviewed manually or verified with a tax advisor before use. Use at your own discretion.

post/invoice/monthly

Request

  • Base URL: ./../api/v1/ (relative, and the document was published on a file host, not at the API’s origin)
  • URL: ./../api/v1/invoice/monthly
  • Auth: API key in header token

Request body

buyerWalletVkeystring required

The buyer wallet vkey to aggregate the month for

sellerWalletVkeystring

Optional seller wallet vkey to scope the invoice to a specific seller

monthstring required

Target month in format YYYY-MM (UTC calendar)

invoiceCurrency'usd' | 'eur' | 'gbp' | 'jpy' | 'chf' | 'aed' required

The currency of the invoice

CurrencyConversionobject

Currency conversion settings by unit for this invoice

vatRatenumber

The VAT rate as decimal (e.g., 0.19 for 19%)

reverseChargeboolean

Enable reverse charge (VAT = 0, notice on invoice)

forceRegenerateboolean

Force cancel existing invoice and generate a new revision, even if no data changes detected

signaturestring required

The signature to verify

keystring required

The key to verify the signature

walletAddressstring required

The wallet address that signed the message

validUntilnumber required

The valid until timestamp

action'RetrieveMonthlyInvoices' required

The action to perform for monthly invoices

Example request

{
  "signature": "ed25519_signature",
  "key": "ed25519_key",
  "walletAddress": "addr1xk2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer3n0d3vllmyqwsx5wktcd8cc3sq835lu7drv2xwl2wywfgse35a3x",
  "validUntil": 1736352000000,
  "action": "RetrieveMonthlyInvoices",
  "buyerWalletVkey": "buyer_wallet_vkey",
  "month": "2025-09",
  "invoiceCurrency": "usd",
  "CurrencyConversion": {
    "": 0.45,
    "policyIdAssetHex": 1.23
  },
  "Invoice": {
    "itemNamePrefix": "Agent: ",
    "title": "Monthly Invoice",
    "language": "en-us",
    "localizationFormat": "en-us"
  },
  "vatRate": 0.19,
  "reverseCharge": false,
  "forceRegenerate": false,
  "Seller": {
    "country": "DE",
    "city": "Berlin",
    "zipCode": "10115",
    "street": "Example Str.",
    "streetNumber": "1",
    "email": "seller@example.com",
    "phone": "+49 30 123456",
    "name": "Alice",
    "companyName": "Alice GmbH",
    "vatNumber": "DE123456789"
  },
  "Buyer": {
    "country": "DE",
    "city": "Berlin",
    "zipCode": "10115",
    "street": "Buyer Str.",
    "streetNumber": "2",
    "email": "buyer@example.com",
    "phone": "+49 30 987654",
    "name": "Bob",
    "companyName": null,
    "vatNumber": null
  }
}

Response

Monthly invoice generated

statusstring required

Example response

{
  "status": "Success",
  "data": {
    "invoice": "BASE64_PDF_STRING",
    "cancellationInvoice": "BASE64_CANCELLATION_PDF_STRING_OR_UNDEFINED"
  }
}

Changes

  • 315a2a763fb7Revision changes
    • breaking

      the request property's minLength was increased from 0 to 58

    • breaking

      added the pattern ^(addr1|addr_test1)[0-9a-z]+$ to the request property

  • b63a7da9c361Revision changes
    • info

      the request property's minLength was decreased from 58 to 0

    • info

      removed the pattern ^(addr1|addr_test1)[0-9a-z]+$ from the request property