Invoices: Creates a new draft invoice.

POST /api/invoicing/invoices deprecated

Requires: Invoicing.Invoices, Invoicing.Invoices.Create, merchant scope.

Requires API key scope: admin (Administration)

**Required permissions**: `Invoicing.Invoices`, `Invoicing.Invoices.Create` **Scope**: merchant

Signed in, you can send this request to your own sandbox merchant from the console and read the answer. Sign in to try it.

Example request

Each example below is one request, shown in every language. Choose an example and a language, then replace {{BASE_URL}} with the address of the API you are calling and {{API_KEY}} with your own key.

The request body is a InvoiceCreateDto. See the Request body section below for its fields.

cURL PowerShell TypeScript C# Python

Minimal invoice

Creates a draft invoice from the sample merchant to one customer with a single 450.00 line. The server computes every total, so the invoice totals 450.00, and the Net 30 terms set the due date when the invoice is issued. The recipient snapshot is where the invoice is emailed. A draft is not delivered: send it with POST /api/invoicing/invoices/{id}/send, which issues it, freezes the biller and recipient details, mints the pay link and emails the recipient. Replace billerId with your merchant's id and recipientId with the customer's id.

cURL

curl -X POST "{{BASE_URL}}/api/invoicing/invoices" \
  -H "api-key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
  "billerId": "00000000-0000-0000-0000-000000000001",
  "billerType": "Merchant",
  "recipientId": "00000000-0000-0000-0000-000000000201",
  "recipientType": "Customer",
  "currency": "USD",
  "paymentTermsValue": "Net30",
  "lineItems": [
    {
      "description": "Website maintenance, October 2026",
      "quantity": 1,
      "unitPrice": 450
    }
  ],
  "recipientSnapshot": {
    "name": "Jordan Rivera",
    "email": "jordan.rivera@example.com"
  }
}'

PowerShell

$headers = @{
    'api-key' = '{{API_KEY}}'
}

$body = @'
{
  "billerId": "00000000-0000-0000-0000-000000000001",
  "billerType": "Merchant",
  "recipientId": "00000000-0000-0000-0000-000000000201",
  "recipientType": "Customer",
  "currency": "USD",
  "paymentTermsValue": "Net30",
  "lineItems": [
    {
      "description": "Website maintenance, October 2026",
      "quantity": 1,
      "unitPrice": 450
    }
  ],
  "recipientSnapshot": {
    "name": "Jordan Rivera",
    "email": "jordan.rivera@example.com"
  }
}
'@

$response = Invoke-RestMethod -Method POST -Uri '{{BASE_URL}}/api/invoicing/invoices' `
    -Headers $headers -ContentType 'application/json' -Body $body

npm install @winkpg/winkpg-api

TypeScript (SDK)

import { Configuration, InvoicingApi } from '@winkpg/winkpg-api';

const api = new InvoicingApi(new Configuration({
  basePath: '{{BASE_URL}}',
  apiKey: '{{API_KEY}}',
}));

const { data } = await api.invoiceCrudCreate({
  "billerId": "00000000-0000-0000-0000-000000000001",
  "billerType": "Merchant",
  "recipientId": "00000000-0000-0000-0000-000000000201",
  "recipientType": "Customer",
  "currency": "USD",
  "paymentTermsValue": "Net30",
  "lineItems": [
    {
      "description": "Website maintenance, October 2026",
      "quantity": 1,
      "unitPrice": 450
    }
  ],
  "recipientSnapshot": {
    "name": "Jordan Rivera",
    "email": "jordan.rivera@example.com"
  }
});

TypeScript (raw HTTP)

const response = await fetch('{{BASE_URL}}/api/invoicing/invoices', {
  method: 'POST',
  headers: {
    "api-key": "{{API_KEY}}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "billerId": "00000000-0000-0000-0000-000000000001",
    "billerType": "Merchant",
    "recipientId": "00000000-0000-0000-0000-000000000201",
    "recipientType": "Customer",
    "currency": "USD",
    "paymentTermsValue": "Net30",
    "lineItems": [
      {
        "description": "Website maintenance, October 2026",
        "quantity": 1,
        "unitPrice": 450
      }
    ],
    "recipientSnapshot": {
      "name": "Jordan Rivera",
      "email": "jordan.rivera@example.com"
    }
  }),
});

const data = await response.json();

dotnet add package WinkPg.Api.Client

C# (SDK)

using WinkPg.Api.Client.Api;
using WinkPg.Api.Client.Client;
using System.Text.Json;

var config = new Configuration { BasePath = "{{BASE_URL}}" };
config.AddApiKey("api-key", "{{API_KEY}}");

var api = new InvoicingApi(config);
var body = JsonSerializer.Deserialize<InvoiceCreateDto>("""
    {
      "billerId": "00000000-0000-0000-0000-000000000001",
      "billerType": "Merchant",
      "recipientId": "00000000-0000-0000-0000-000000000201",
      "recipientType": "Customer",
      "currency": "USD",
      "paymentTermsValue": "Net30",
      "lineItems": [
        {
          "description": "Website maintenance, October 2026",
          "quantity": 1,
          "unitPrice": 450
        }
      ],
      "recipientSnapshot": {
        "name": "Jordan Rivera",
        "email": "jordan.rivera@example.com"
      }
    }
    """);

var result = await api.InvoiceCrudCreateAsync(body);

C# (raw HTTP)

using System.Text;

using var http = new HttpClient { BaseAddress = new Uri("{{BASE_URL}}") };

var request = new HttpRequestMessage(new HttpMethod("POST"), "/api/invoicing/invoices");
request.Headers.Add("api-key", "{{API_KEY}}");

request.Content = new StringContent("""
    {
      "billerId": "00000000-0000-0000-0000-000000000001",
      "billerType": "Merchant",
      "recipientId": "00000000-0000-0000-0000-000000000201",
      "recipientType": "Customer",
      "currency": "USD",
      "paymentTermsValue": "Net30",
      "lineItems": [
        {
          "description": "Website maintenance, October 2026",
          "quantity": 1,
          "unitPrice": 450
        }
      ],
      "recipientSnapshot": {
        "name": "Jordan Rivera",
        "email": "jordan.rivera@example.com"
      }
    }
    """, Encoding.UTF8, "application/json");

var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
var json = await response.Content.ReadAsStringAsync();

pip install winkpg-api

Python (SDK)

import winkpg_api

configuration = winkpg_api.Configuration(host="{{BASE_URL}}")
configuration.api_key["ApiKey"] = "{{API_KEY}}"

with winkpg_api.ApiClient(configuration) as client:
    api = winkpg_api.InvoicingApi(client)
    body = winkpg_api.InvoiceCreateDto.from_dict({
      "billerId": "00000000-0000-0000-0000-000000000001",
      "billerType": "Merchant",
      "recipientId": "00000000-0000-0000-0000-000000000201",
      "recipientType": "Customer",
      "currency": "USD",
      "paymentTermsValue": "Net30",
      "lineItems": [
        {
          "description": "Website maintenance, October 2026",
          "quantity": 1,
          "unitPrice": 450
        }
      ],
      "recipientSnapshot": {
        "name": "Jordan Rivera",
        "email": "jordan.rivera@example.com"
      }
    })
    result = api.invoice_crud_create(body)

pip install requests

Python (raw HTTP)

import requests

headers = {
    "api-key": "{{API_KEY}}",
    "Content-Type": "application/json",
}

body = {
  "billerId": "00000000-0000-0000-0000-000000000001",
  "billerType": "Merchant",
  "recipientId": "00000000-0000-0000-0000-000000000201",
  "recipientType": "Customer",
  "currency": "USD",
  "paymentTermsValue": "Net30",
  "lineItems": [
    {
      "description": "Website maintenance, October 2026",
      "quantity": 1,
      "unitPrice": 450
    }
  ],
  "recipientSnapshot": {
    "name": "Jordan Rivera",
    "email": "jordan.rivera@example.com"
  }
}

response = requests.request(
    "POST",
    "{{BASE_URL}}/api/invoicing/invoices",
    headers=headers,
    json=body,
)
response.raise_for_status()
data = response.json()

Invoice with taxed lines and partial payments

Creates a draft with three lines: two taxed at 8.25 percent and an hourly line marked not taxable. The server computes the money: a subtotal of 3,510.00, tax of 247.50 assessed once on the 3,000.00 taxable base and allocated back onto the two taxed lines, and a total of 3,757.50. Partial payments of at least 500.00 are accepted, the payer may use a card or a bank account, and reminders go out 7 and 1 days before the due date and 3 and 10 days after it. To split the balance into installments, issue the invoice and then create a payment plan with POST /api/invoicing/invoices/{id}/payment-plan: a plan divides an issued invoice's outstanding balance, so it is never part of the create payload. Replace billerId with your merchant's id and recipientId with the customer's id.

cURL

curl -X POST "{{BASE_URL}}/api/invoicing/invoices" \
  -H "api-key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
  "billerId": "00000000-0000-0000-0000-000000000001",
  "billerType": "Merchant",
  "recipientId": "00000000-0000-0000-0000-000000000201",
  "recipientType": "Customer",
  "currency": "USD",
  "paymentTermsValue": "Net30",
  "allowPartialPayment": true,
  "minimumPaymentAmount": 500,
  "allowedPaymentMethods": [
    "card",
    "ach"
  ],
  "reminderConfig": {
    "preDueDays": [
      7,
      1
    ],
    "dueDayReminder": true,
    "postDueDays": [
      3,
      10
    ]
  },
  "sourceReferenceId": "PO-48213",
  "recipientNote": "Thank you for choosing Northwind Design Studio.",
  "footerText": "Payment is due within 30 days of the invoice date.",
  "lineItems": [
    {
      "name": "Brand identity package",
      "description": "Logo, color palette and typography guide",
      "productCode": "BRAND-PKG",
      "quantity": 1,
      "unitPrice": 2400,
      "taxRatePercent": 8.25
    },
    {
      "name": "Logo usage license",
      "description": "Logo usage license, one seat each",
      "productCode": "LIC-SEAT",
      "unitOfMeasure": "seat",
      "quantity": 5,
      "unitPrice": 120,
      "taxRatePercent": 8.25
    },
    {
      "name": "Project management",
      "description": "Project management and client reviews",
      "unitOfMeasure": "hour",
      "quantity": 6,
      "unitPrice": 85,
      "isTaxable": false
    }
  ],
  "billerSnapshot": {
    "email": "billing@northwind-design.example.com",
    "phone": "512-555-0142",
    "addressLine1": "400 Congress Ave, Suite 210",
    "city": "Austin",
    "state": "TX",
    "postalCode": "78701",
    "country": "US",
    "companyName": "Northwind Design Studio"
  },
  "recipientSnapshot": {
    "name": "Jordan Rivera",
    "email": "jordan.rivera@example.com",
    "addressLine1": "2100 Ross Ave",
    "city": "Dallas",
    "state": "TX",
    "postalCode": "75201",
    "country": "US",
    "companyName": "Rivera Outdoor Supply"
  }
}'

PowerShell

$headers = @{
    'api-key' = '{{API_KEY}}'
}

$body = @'
{
  "billerId": "00000000-0000-0000-0000-000000000001",
  "billerType": "Merchant",
  "recipientId": "00000000-0000-0000-0000-000000000201",
  "recipientType": "Customer",
  "currency": "USD",
  "paymentTermsValue": "Net30",
  "allowPartialPayment": true,
  "minimumPaymentAmount": 500,
  "allowedPaymentMethods": [
    "card",
    "ach"
  ],
  "reminderConfig": {
    "preDueDays": [
      7,
      1
    ],
    "dueDayReminder": true,
    "postDueDays": [
      3,
      10
    ]
  },
  "sourceReferenceId": "PO-48213",
  "recipientNote": "Thank you for choosing Northwind Design Studio.",
  "footerText": "Payment is due within 30 days of the invoice date.",
  "lineItems": [
    {
      "name": "Brand identity package",
      "description": "Logo, color palette and typography guide",
      "productCode": "BRAND-PKG",
      "quantity": 1,
      "unitPrice": 2400,
      "taxRatePercent": 8.25
    },
    {
      "name": "Logo usage license",
      "description": "Logo usage license, one seat each",
      "productCode": "LIC-SEAT",
      "unitOfMeasure": "seat",
      "quantity": 5,
      "unitPrice": 120,
      "taxRatePercent": 8.25
    },
    {
      "name": "Project management",
      "description": "Project management and client reviews",
      "unitOfMeasure": "hour",
      "quantity": 6,
      "unitPrice": 85,
      "isTaxable": false
    }
  ],
  "billerSnapshot": {
    "email": "billing@northwind-design.example.com",
    "phone": "512-555-0142",
    "addressLine1": "400 Congress Ave, Suite 210",
    "city": "Austin",
    "state": "TX",
    "postalCode": "78701",
    "country": "US",
    "companyName": "Northwind Design Studio"
  },
  "recipientSnapshot": {
    "name": "Jordan Rivera",
    "email": "jordan.rivera@example.com",
    "addressLine1": "2100 Ross Ave",
    "city": "Dallas",
    "state": "TX",
    "postalCode": "75201",
    "country": "US",
    "companyName": "Rivera Outdoor Supply"
  }
}
'@

$response = Invoke-RestMethod -Method POST -Uri '{{BASE_URL}}/api/invoicing/invoices' `
    -Headers $headers -ContentType 'application/json' -Body $body

npm install @winkpg/winkpg-api

TypeScript (SDK)

import { Configuration, InvoicingApi } from '@winkpg/winkpg-api';

const api = new InvoicingApi(new Configuration({
  basePath: '{{BASE_URL}}',
  apiKey: '{{API_KEY}}',
}));

const { data } = await api.invoiceCrudCreate({
  "billerId": "00000000-0000-0000-0000-000000000001",
  "billerType": "Merchant",
  "recipientId": "00000000-0000-0000-0000-000000000201",
  "recipientType": "Customer",
  "currency": "USD",
  "paymentTermsValue": "Net30",
  "allowPartialPayment": true,
  "minimumPaymentAmount": 500,
  "allowedPaymentMethods": [
    "card",
    "ach"
  ],
  "reminderConfig": {
    "preDueDays": [
      7,
      1
    ],
    "dueDayReminder": true,
    "postDueDays": [
      3,
      10
    ]
  },
  "sourceReferenceId": "PO-48213",
  "recipientNote": "Thank you for choosing Northwind Design Studio.",
  "footerText": "Payment is due within 30 days of the invoice date.",
  "lineItems": [
    {
      "name": "Brand identity package",
      "description": "Logo, color palette and typography guide",
      "productCode": "BRAND-PKG",
      "quantity": 1,
      "unitPrice": 2400,
      "taxRatePercent": 8.25
    },
    {
      "name": "Logo usage license",
      "description": "Logo usage license, one seat each",
      "productCode": "LIC-SEAT",
      "unitOfMeasure": "seat",
      "quantity": 5,
      "unitPrice": 120,
      "taxRatePercent": 8.25
    },
    {
      "name": "Project management",
      "description": "Project management and client reviews",
      "unitOfMeasure": "hour",
      "quantity": 6,
      "unitPrice": 85,
      "isTaxable": false
    }
  ],
  "billerSnapshot": {
    "email": "billing@northwind-design.example.com",
    "phone": "512-555-0142",
    "addressLine1": "400 Congress Ave, Suite 210",
    "city": "Austin",
    "state": "TX",
    "postalCode": "78701",
    "country": "US",
    "companyName": "Northwind Design Studio"
  },
  "recipientSnapshot": {
    "name": "Jordan Rivera",
    "email": "jordan.rivera@example.com",
    "addressLine1": "2100 Ross Ave",
    "city": "Dallas",
    "state": "TX",
    "postalCode": "75201",
    "country": "US",
    "companyName": "Rivera Outdoor Supply"
  }
});

TypeScript (raw HTTP)

const response = await fetch('{{BASE_URL}}/api/invoicing/invoices', {
  method: 'POST',
  headers: {
    "api-key": "{{API_KEY}}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "billerId": "00000000-0000-0000-0000-000000000001",
    "billerType": "Merchant",
    "recipientId": "00000000-0000-0000-0000-000000000201",
    "recipientType": "Customer",
    "currency": "USD",
    "paymentTermsValue": "Net30",
    "allowPartialPayment": true,
    "minimumPaymentAmount": 500,
    "allowedPaymentMethods": [
      "card",
      "ach"
    ],
    "reminderConfig": {
      "preDueDays": [
        7,
        1
      ],
      "dueDayReminder": true,
      "postDueDays": [
        3,
        10
      ]
    },
    "sourceReferenceId": "PO-48213",
    "recipientNote": "Thank you for choosing Northwind Design Studio.",
    "footerText": "Payment is due within 30 days of the invoice date.",
    "lineItems": [
      {
        "name": "Brand identity package",
        "description": "Logo, color palette and typography guide",
        "productCode": "BRAND-PKG",
        "quantity": 1,
        "unitPrice": 2400,
        "taxRatePercent": 8.25
      },
      {
        "name": "Logo usage license",
        "description": "Logo usage license, one seat each",
        "productCode": "LIC-SEAT",
        "unitOfMeasure": "seat",
        "quantity": 5,
        "unitPrice": 120,
        "taxRatePercent": 8.25
      },
      {
        "name": "Project management",
        "description": "Project management and client reviews",
        "unitOfMeasure": "hour",
        "quantity": 6,
        "unitPrice": 85,
        "isTaxable": false
      }
    ],
    "billerSnapshot": {
      "email": "billing@northwind-design.example.com",
      "phone": "512-555-0142",
      "addressLine1": "400 Congress Ave, Suite 210",
      "city": "Austin",
      "state": "TX",
      "postalCode": "78701",
      "country": "US",
      "companyName": "Northwind Design Studio"
    },
    "recipientSnapshot": {
      "name": "Jordan Rivera",
      "email": "jordan.rivera@example.com",
      "addressLine1": "2100 Ross Ave",
      "city": "Dallas",
      "state": "TX",
      "postalCode": "75201",
      "country": "US",
      "companyName": "Rivera Outdoor Supply"
    }
  }),
});

const data = await response.json();

dotnet add package WinkPg.Api.Client

C# (SDK)

using WinkPg.Api.Client.Api;
using WinkPg.Api.Client.Client;
using System.Text.Json;

var config = new Configuration { BasePath = "{{BASE_URL}}" };
config.AddApiKey("api-key", "{{API_KEY}}");

var api = new InvoicingApi(config);
var body = JsonSerializer.Deserialize<InvoiceCreateDto>("""
    {
      "billerId": "00000000-0000-0000-0000-000000000001",
      "billerType": "Merchant",
      "recipientId": "00000000-0000-0000-0000-000000000201",
      "recipientType": "Customer",
      "currency": "USD",
      "paymentTermsValue": "Net30",
      "allowPartialPayment": true,
      "minimumPaymentAmount": 500,
      "allowedPaymentMethods": [
        "card",
        "ach"
      ],
      "reminderConfig": {
        "preDueDays": [
          7,
          1
        ],
        "dueDayReminder": true,
        "postDueDays": [
          3,
          10
        ]
      },
      "sourceReferenceId": "PO-48213",
      "recipientNote": "Thank you for choosing Northwind Design Studio.",
      "footerText": "Payment is due within 30 days of the invoice date.",
      "lineItems": [
        {
          "name": "Brand identity package",
          "description": "Logo, color palette and typography guide",
          "productCode": "BRAND-PKG",
          "quantity": 1,
          "unitPrice": 2400,
          "taxRatePercent": 8.25
        },
        {
          "name": "Logo usage license",
          "description": "Logo usage license, one seat each",
          "productCode": "LIC-SEAT",
          "unitOfMeasure": "seat",
          "quantity": 5,
          "unitPrice": 120,
          "taxRatePercent": 8.25
        },
        {
          "name": "Project management",
          "description": "Project management and client reviews",
          "unitOfMeasure": "hour",
          "quantity": 6,
          "unitPrice": 85,
          "isTaxable": false
        }
      ],
      "billerSnapshot": {
        "email": "billing@northwind-design.example.com",
        "phone": "512-555-0142",
        "addressLine1": "400 Congress Ave, Suite 210",
        "city": "Austin",
        "state": "TX",
        "postalCode": "78701",
        "country": "US",
        "companyName": "Northwind Design Studio"
      },
      "recipientSnapshot": {
        "name": "Jordan Rivera",
        "email": "jordan.rivera@example.com",
        "addressLine1": "2100 Ross Ave",
        "city": "Dallas",
        "state": "TX",
        "postalCode": "75201",
        "country": "US",
        "companyName": "Rivera Outdoor Supply"
      }
    }
    """);

var result = await api.InvoiceCrudCreateAsync(body);

C# (raw HTTP)

using System.Text;

using var http = new HttpClient { BaseAddress = new Uri("{{BASE_URL}}") };

var request = new HttpRequestMessage(new HttpMethod("POST"), "/api/invoicing/invoices");
request.Headers.Add("api-key", "{{API_KEY}}");

request.Content = new StringContent("""
    {
      "billerId": "00000000-0000-0000-0000-000000000001",
      "billerType": "Merchant",
      "recipientId": "00000000-0000-0000-0000-000000000201",
      "recipientType": "Customer",
      "currency": "USD",
      "paymentTermsValue": "Net30",
      "allowPartialPayment": true,
      "minimumPaymentAmount": 500,
      "allowedPaymentMethods": [
        "card",
        "ach"
      ],
      "reminderConfig": {
        "preDueDays": [
          7,
          1
        ],
        "dueDayReminder": true,
        "postDueDays": [
          3,
          10
        ]
      },
      "sourceReferenceId": "PO-48213",
      "recipientNote": "Thank you for choosing Northwind Design Studio.",
      "footerText": "Payment is due within 30 days of the invoice date.",
      "lineItems": [
        {
          "name": "Brand identity package",
          "description": "Logo, color palette and typography guide",
          "productCode": "BRAND-PKG",
          "quantity": 1,
          "unitPrice": 2400,
          "taxRatePercent": 8.25
        },
        {
          "name": "Logo usage license",
          "description": "Logo usage license, one seat each",
          "productCode": "LIC-SEAT",
          "unitOfMeasure": "seat",
          "quantity": 5,
          "unitPrice": 120,
          "taxRatePercent": 8.25
        },
        {
          "name": "Project management",
          "description": "Project management and client reviews",
          "unitOfMeasure": "hour",
          "quantity": 6,
          "unitPrice": 85,
          "isTaxable": false
        }
      ],
      "billerSnapshot": {
        "email": "billing@northwind-design.example.com",
        "phone": "512-555-0142",
        "addressLine1": "400 Congress Ave, Suite 210",
        "city": "Austin",
        "state": "TX",
        "postalCode": "78701",
        "country": "US",
        "companyName": "Northwind Design Studio"
      },
      "recipientSnapshot": {
        "name": "Jordan Rivera",
        "email": "jordan.rivera@example.com",
        "addressLine1": "2100 Ross Ave",
        "city": "Dallas",
        "state": "TX",
        "postalCode": "75201",
        "country": "US",
        "companyName": "Rivera Outdoor Supply"
      }
    }
    """, Encoding.UTF8, "application/json");

var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
var json = await response.Content.ReadAsStringAsync();

pip install winkpg-api

Python (SDK)

import winkpg_api

configuration = winkpg_api.Configuration(host="{{BASE_URL}}")
configuration.api_key["ApiKey"] = "{{API_KEY}}"

with winkpg_api.ApiClient(configuration) as client:
    api = winkpg_api.InvoicingApi(client)
    body = winkpg_api.InvoiceCreateDto.from_dict({
      "billerId": "00000000-0000-0000-0000-000000000001",
      "billerType": "Merchant",
      "recipientId": "00000000-0000-0000-0000-000000000201",
      "recipientType": "Customer",
      "currency": "USD",
      "paymentTermsValue": "Net30",
      "allowPartialPayment": True,
      "minimumPaymentAmount": 500,
      "allowedPaymentMethods": [
        "card",
        "ach"
      ],
      "reminderConfig": {
        "preDueDays": [
          7,
          1
        ],
        "dueDayReminder": True,
        "postDueDays": [
          3,
          10
        ]
      },
      "sourceReferenceId": "PO-48213",
      "recipientNote": "Thank you for choosing Northwind Design Studio.",
      "footerText": "Payment is due within 30 days of the invoice date.",
      "lineItems": [
        {
          "name": "Brand identity package",
          "description": "Logo, color palette and typography guide",
          "productCode": "BRAND-PKG",
          "quantity": 1,
          "unitPrice": 2400,
          "taxRatePercent": 8.25
        },
        {
          "name": "Logo usage license",
          "description": "Logo usage license, one seat each",
          "productCode": "LIC-SEAT",
          "unitOfMeasure": "seat",
          "quantity": 5,
          "unitPrice": 120,
          "taxRatePercent": 8.25
        },
        {
          "name": "Project management",
          "description": "Project management and client reviews",
          "unitOfMeasure": "hour",
          "quantity": 6,
          "unitPrice": 85,
          "isTaxable": False
        }
      ],
      "billerSnapshot": {
        "email": "billing@northwind-design.example.com",
        "phone": "512-555-0142",
        "addressLine1": "400 Congress Ave, Suite 210",
        "city": "Austin",
        "state": "TX",
        "postalCode": "78701",
        "country": "US",
        "companyName": "Northwind Design Studio"
      },
      "recipientSnapshot": {
        "name": "Jordan Rivera",
        "email": "jordan.rivera@example.com",
        "addressLine1": "2100 Ross Ave",
        "city": "Dallas",
        "state": "TX",
        "postalCode": "75201",
        "country": "US",
        "companyName": "Rivera Outdoor Supply"
      }
    })
    result = api.invoice_crud_create(body)

pip install requests

Python (raw HTTP)

import requests

headers = {
    "api-key": "{{API_KEY}}",
    "Content-Type": "application/json",
}

body = {
  "billerId": "00000000-0000-0000-0000-000000000001",
  "billerType": "Merchant",
  "recipientId": "00000000-0000-0000-0000-000000000201",
  "recipientType": "Customer",
  "currency": "USD",
  "paymentTermsValue": "Net30",
  "allowPartialPayment": True,
  "minimumPaymentAmount": 500,
  "allowedPaymentMethods": [
    "card",
    "ach"
  ],
  "reminderConfig": {
    "preDueDays": [
      7,
      1
    ],
    "dueDayReminder": True,
    "postDueDays": [
      3,
      10
    ]
  },
  "sourceReferenceId": "PO-48213",
  "recipientNote": "Thank you for choosing Northwind Design Studio.",
  "footerText": "Payment is due within 30 days of the invoice date.",
  "lineItems": [
    {
      "name": "Brand identity package",
      "description": "Logo, color palette and typography guide",
      "productCode": "BRAND-PKG",
      "quantity": 1,
      "unitPrice": 2400,
      "taxRatePercent": 8.25
    },
    {
      "name": "Logo usage license",
      "description": "Logo usage license, one seat each",
      "productCode": "LIC-SEAT",
      "unitOfMeasure": "seat",
      "quantity": 5,
      "unitPrice": 120,
      "taxRatePercent": 8.25
    },
    {
      "name": "Project management",
      "description": "Project management and client reviews",
      "unitOfMeasure": "hour",
      "quantity": 6,
      "unitPrice": 85,
      "isTaxable": False
    }
  ],
  "billerSnapshot": {
    "email": "billing@northwind-design.example.com",
    "phone": "512-555-0142",
    "addressLine1": "400 Congress Ave, Suite 210",
    "city": "Austin",
    "state": "TX",
    "postalCode": "78701",
    "country": "US",
    "companyName": "Northwind Design Studio"
  },
  "recipientSnapshot": {
    "name": "Jordan Rivera",
    "email": "jordan.rivera@example.com",
    "addressLine1": "2100 Ross Ave",
    "city": "Dallas",
    "state": "TX",
    "postalCode": "75201",
    "country": "US",
    "companyName": "Rivera Outdoor Supply"
  }
}

response = requests.request(
    "POST",
    "{{BASE_URL}}/api/invoicing/invoices",
    headers=headers,
    json=body,
)
response.raise_for_status()
data = response.json()

Invoice that collects a deposit first

Creates a 12,800.00 draft that asks for a 25 percent deposit (3,200.00) by February 15, 2027, before the balance is due on March 31, 2027. While the deposit is outstanding a payment must equal it exactly; the remaining 9,600.00 is collected after. The deposit is a payment against the balance, never an amount added on top. It must be less than the invoice total, and its due date may not fall after the balance due date. Replace billerId with your merchant's id and recipientId with the customer's id.

cURL

curl -X POST "{{BASE_URL}}/api/invoicing/invoices" \
  -H "api-key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
  "billerId": "00000000-0000-0000-0000-000000000001",
  "billerType": "Merchant",
  "recipientId": "00000000-0000-0000-0000-000000000201",
  "recipientType": "Customer",
  "currency": "USD",
  "dueDate": "2027-03-31",
  "depositType": "Percentage",
  "depositValue": 25,
  "depositDueDate": "2027-02-15",
  "lineItems": [
    {
      "description": "Kitchen remodel: cabinets, counters and installation",
      "quantity": 1,
      "unitPrice": 12800
    }
  ],
  "recipientSnapshot": {
    "name": "Jordan Rivera",
    "email": "jordan.rivera@example.com"
  }
}'

PowerShell

$headers = @{
    'api-key' = '{{API_KEY}}'
}

$body = @'
{
  "billerId": "00000000-0000-0000-0000-000000000001",
  "billerType": "Merchant",
  "recipientId": "00000000-0000-0000-0000-000000000201",
  "recipientType": "Customer",
  "currency": "USD",
  "dueDate": "2027-03-31",
  "depositType": "Percentage",
  "depositValue": 25,
  "depositDueDate": "2027-02-15",
  "lineItems": [
    {
      "description": "Kitchen remodel: cabinets, counters and installation",
      "quantity": 1,
      "unitPrice": 12800
    }
  ],
  "recipientSnapshot": {
    "name": "Jordan Rivera",
    "email": "jordan.rivera@example.com"
  }
}
'@

$response = Invoke-RestMethod -Method POST -Uri '{{BASE_URL}}/api/invoicing/invoices' `
    -Headers $headers -ContentType 'application/json' -Body $body

npm install @winkpg/winkpg-api

TypeScript (SDK)

import { Configuration, InvoicingApi } from '@winkpg/winkpg-api';

const api = new InvoicingApi(new Configuration({
  basePath: '{{BASE_URL}}',
  apiKey: '{{API_KEY}}',
}));

const { data } = await api.invoiceCrudCreate({
  "billerId": "00000000-0000-0000-0000-000000000001",
  "billerType": "Merchant",
  "recipientId": "00000000-0000-0000-0000-000000000201",
  "recipientType": "Customer",
  "currency": "USD",
  "dueDate": "2027-03-31",
  "depositType": "Percentage",
  "depositValue": 25,
  "depositDueDate": "2027-02-15",
  "lineItems": [
    {
      "description": "Kitchen remodel: cabinets, counters and installation",
      "quantity": 1,
      "unitPrice": 12800
    }
  ],
  "recipientSnapshot": {
    "name": "Jordan Rivera",
    "email": "jordan.rivera@example.com"
  }
});

TypeScript (raw HTTP)

const response = await fetch('{{BASE_URL}}/api/invoicing/invoices', {
  method: 'POST',
  headers: {
    "api-key": "{{API_KEY}}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "billerId": "00000000-0000-0000-0000-000000000001",
    "billerType": "Merchant",
    "recipientId": "00000000-0000-0000-0000-000000000201",
    "recipientType": "Customer",
    "currency": "USD",
    "dueDate": "2027-03-31",
    "depositType": "Percentage",
    "depositValue": 25,
    "depositDueDate": "2027-02-15",
    "lineItems": [
      {
        "description": "Kitchen remodel: cabinets, counters and installation",
        "quantity": 1,
        "unitPrice": 12800
      }
    ],
    "recipientSnapshot": {
      "name": "Jordan Rivera",
      "email": "jordan.rivera@example.com"
    }
  }),
});

const data = await response.json();

dotnet add package WinkPg.Api.Client

C# (SDK)

using WinkPg.Api.Client.Api;
using WinkPg.Api.Client.Client;
using System.Text.Json;

var config = new Configuration { BasePath = "{{BASE_URL}}" };
config.AddApiKey("api-key", "{{API_KEY}}");

var api = new InvoicingApi(config);
var body = JsonSerializer.Deserialize<InvoiceCreateDto>("""
    {
      "billerId": "00000000-0000-0000-0000-000000000001",
      "billerType": "Merchant",
      "recipientId": "00000000-0000-0000-0000-000000000201",
      "recipientType": "Customer",
      "currency": "USD",
      "dueDate": "2027-03-31",
      "depositType": "Percentage",
      "depositValue": 25,
      "depositDueDate": "2027-02-15",
      "lineItems": [
        {
          "description": "Kitchen remodel: cabinets, counters and installation",
          "quantity": 1,
          "unitPrice": 12800
        }
      ],
      "recipientSnapshot": {
        "name": "Jordan Rivera",
        "email": "jordan.rivera@example.com"
      }
    }
    """);

var result = await api.InvoiceCrudCreateAsync(body);

C# (raw HTTP)

using System.Text;

using var http = new HttpClient { BaseAddress = new Uri("{{BASE_URL}}") };

var request = new HttpRequestMessage(new HttpMethod("POST"), "/api/invoicing/invoices");
request.Headers.Add("api-key", "{{API_KEY}}");

request.Content = new StringContent("""
    {
      "billerId": "00000000-0000-0000-0000-000000000001",
      "billerType": "Merchant",
      "recipientId": "00000000-0000-0000-0000-000000000201",
      "recipientType": "Customer",
      "currency": "USD",
      "dueDate": "2027-03-31",
      "depositType": "Percentage",
      "depositValue": 25,
      "depositDueDate": "2027-02-15",
      "lineItems": [
        {
          "description": "Kitchen remodel: cabinets, counters and installation",
          "quantity": 1,
          "unitPrice": 12800
        }
      ],
      "recipientSnapshot": {
        "name": "Jordan Rivera",
        "email": "jordan.rivera@example.com"
      }
    }
    """, Encoding.UTF8, "application/json");

var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
var json = await response.Content.ReadAsStringAsync();

pip install winkpg-api

Python (SDK)

import winkpg_api

configuration = winkpg_api.Configuration(host="{{BASE_URL}}")
configuration.api_key["ApiKey"] = "{{API_KEY}}"

with winkpg_api.ApiClient(configuration) as client:
    api = winkpg_api.InvoicingApi(client)
    body = winkpg_api.InvoiceCreateDto.from_dict({
      "billerId": "00000000-0000-0000-0000-000000000001",
      "billerType": "Merchant",
      "recipientId": "00000000-0000-0000-0000-000000000201",
      "recipientType": "Customer",
      "currency": "USD",
      "dueDate": "2027-03-31",
      "depositType": "Percentage",
      "depositValue": 25,
      "depositDueDate": "2027-02-15",
      "lineItems": [
        {
          "description": "Kitchen remodel: cabinets, counters and installation",
          "quantity": 1,
          "unitPrice": 12800
        }
      ],
      "recipientSnapshot": {
        "name": "Jordan Rivera",
        "email": "jordan.rivera@example.com"
      }
    })
    result = api.invoice_crud_create(body)

pip install requests

Python (raw HTTP)

import requests

headers = {
    "api-key": "{{API_KEY}}",
    "Content-Type": "application/json",
}

body = {
  "billerId": "00000000-0000-0000-0000-000000000001",
  "billerType": "Merchant",
  "recipientId": "00000000-0000-0000-0000-000000000201",
  "recipientType": "Customer",
  "currency": "USD",
  "dueDate": "2027-03-31",
  "depositType": "Percentage",
  "depositValue": 25,
  "depositDueDate": "2027-02-15",
  "lineItems": [
    {
      "description": "Kitchen remodel: cabinets, counters and installation",
      "quantity": 1,
      "unitPrice": 12800
    }
  ],
  "recipientSnapshot": {
    "name": "Jordan Rivera",
    "email": "jordan.rivera@example.com"
  }
}

response = requests.request(
    "POST",
    "{{BASE_URL}}/api/invoicing/invoices",
    headers=headers,
    json=body,
)
response.raise_for_status()
data = response.json()

Parameters

Name In Type Description

suppressNulls required

query

boolean

If true, omit properties with null values.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Request body

application/json , required

Field Type Description

recipientId required

string (uuid)

Recipient entity ID.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

recipientType required

InvoicePartyType InvoicePartyType

Recipient entity type.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`GatewayOwner`	Platform-level gateway owner.
`Reseller`	Reseller entity.
`Merchant`	Merchant entity.
`Customer`	End customer.

currency required

string

ISO 4217 currency code. nullablemin length 3max length 3pattern ^[A-Za-z]{3}$

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

paymentTermsValue required

PaymentTerms PaymentTerms

Standard payment terms. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`DueOnReceipt`	Payment due immediately upon receipt.
`Net15`	Payment due within 15 days of issue.
`Net30`	Payment due within 30 days of issue.
`Net45`	Payment due within 45 days of issue.
`Net60`	Payment due within 60 days of issue.
`Net90`	Payment due within 90 days of issue.
`Custom`	Custom number of days specified via InvoiceConsts.

customPaymentDays required

integer (int32)

Custom number of days when PaymentTerms is Custom. Conditional: When PaymentTermsValue == Custom. Must be > 0. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

dueDate required

string (date-time)

Manual due date override (used if PaymentTerms is null). nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

allowPartialPayment required

boolean

Whether partial payments are allowed. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

minimumPaymentAmount required

number (double)

Minimum payment amount when partial payments are enabled. Conditional: When AllowPartialPayment is true and MinimumPaymentAmount is not null. Must be > 0. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

partialPaymentTolerance required

number (double)

Auto-close tolerance. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

depositType required

InvoiceDepositType InvoiceDepositType

When set, requests an up-front deposit on the invoice: the payer is charged exactly the deposit first, then the remaining balance. Null means no deposit is requested. When set, `depositValue` is required. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`Percentage`	Deposit is a percentage (0 < value < 100) of the invoice grand total.
`FixedAmount`	Deposit is a fixed currency amount (0 < value < grand total).

depositValue required

number (double)

The deposit percentage (e.g. 25 for 25%) when `depositType` is `Percentage`, or the fixed deposit amount when it is `FixedAmount`. Must be positive; the resolved amount must be strictly less than the invoice total. Required: When DepositType is not null. Must be > 0. Must be < 100. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

depositDueDate required

string (date-time)

Optional deposit due date, distinct from the balance `dueDate`. When set, it must not be after the balance due date. Conditional: When DepositType is not null. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

allowedPaymentMethods required

array of string array of

Subset of biller's supported payment methods for this invoice. Conditional: When AllowedPaymentMethods is not null. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

vaultRestriction required

VaultRestriction VaultRestriction

Controls whether new or saved payment methods are allowed. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`Any`	Allow any payment method (new or saved).
`AllowNewAndSaved`	Allow both new and saved payment methods.
`SavedOnly`	Only allow previously saved (vaulted) payment methods.

applyConvenienceFee required

boolean

Per-invoice override of the merchant's convenience fee on this invoice's payments: `true` applies it, `false` suppresses it, and `null` (the default, and the behaviour of any payload that omits the field) inherits the merchant and feature decision. An override can suppress a fee but can never create one: `true` applies the fee only when invoice convenience fees are enabled for the tenant and the merchant has a convenience-fee configuration, and the platform's compliance rules still govern whether the resulting transaction keeps the fee. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

hppPageId required

string (uuid)

Linked HPP configuration ID. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

templateId required

string (uuid)

Invoice style/template reference. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

invoiceLevelDiscount required

InvoiceDiscountDto InvoiceDiscountDto

Invoice-level discount.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of InvoiceDiscountDto:

Field Type Description

type required

DiscountType DiscountType

The type of discount applied to a line item or invoice.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`Percent`	Percentage discount (e.g., 10%).
`Flat`	Flat dollar amount discount (e.g., $5.00).

value required

number (double)

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

description required

string

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

reminderConfig required

InvoiceReminderConfigDto InvoiceReminderConfigDto

Per-invoice reminder overrides.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of InvoiceReminderConfigDto:

Field Type Description

preDueDays required

array of integer (int32) array of

Days before the due date to send a reminder (for example 7, 3, 1). Null or omitted inherits the tenant default; an empty list sends no pre-due reminders for this invoice. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

dueDayReminder required

boolean

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

postDueDays required

array of integer (int32) array of

Days after the due date to send a reminder (for example 1, 7, 14, 30). Null or omitted inherits the tenant default; an empty list sends no scheduled post-due reminders for this invoice. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

postDueRecurringDays required

integer (int32)

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

stopOnPaid required

boolean

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

maxReminders required

integer (int32)

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

dunningEndAction required

DunningEndAction DunningEndAction

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`None`	No automatic action taken.
`MarkUncollectible`	Transition the invoice to Uncollectible.
`Close`	Transition the invoice to Closed.

daysUntilUncollectible required

integer (int32)

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

sourceType required

InvoiceSourceType InvoiceSourceType

How this invoice was created. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`Manual`	Manually created by a user.
`UsageBilling`	Generated from usage billing data.
`RecurringBilling`	Generated from a recurring billing contract.
`Api`	Created via API by an external integration.

sourceReferenceId required

string

Caller-provided reference. Conditional: When SourceReferenceId is not empty. Max length: 200. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

notes required

array of EntityNote array of EntityNote

Internal notes (not shown to recipient). nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of each EntityNote:

Field Type Description

id required

string (uuid)

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

enteredBy required

string (uuid)

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

timestamp required

string (date-time)

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

enteredByName required

string

Denormalized display name of the user who created the note. Populated at creation time from `ICurrentUser` to avoid N+1 lookups when rendering. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

content required

string

nullablemin length 0max length 1000

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

recipientNote required

string

Shown on the invoice to the recipient. Conditional: When RecipientNote is not empty. Max length: 2000. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

footerText required

string

Terms and conditions text. Conditional: When FooterText is not empty. Max length: 5000. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

lineItems required

array of InvoiceLineItemInputDto array of InvoiceLineItemInputDto

Line items to set on the invoice. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of each InvoiceLineItemInputDto:

Field Type Description

parentLineItemId required

string (uuid)

Parent line item ID for bundle/discount/tax line hierarchies. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

name required

string

Product name snapshot (formal product name). nullablemax length 200

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

description required

string

Line item description shown on PDF and HPP. nullablemax length 500

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

notes required

string

Per-line notes visible to the biller only. nullablemax length 500

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

productId required

string (uuid)

Optional link to the product catalog. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

productCode required

string

SKU or product code. nullablemax length 50

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

unitOfMeasure required

string

Unit of measure (e.g., "each", "hour", "GB"). nullablemax length 50

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

commodityCode required

string

Commodity code sent as enhanced (Level 3) card data when the invoice is paid by card. At most 25 characters. nullablemax length 25

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

quantity required

number (double)

Quantity (default 1). greater than 0

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

unitPrice required

number (double)

Unit price. min 0

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

cost required

number (double)

Cost for margin tracking. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

pricingSource required

PricingSource PricingSource

How the unit price was determined. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`Catalog`	Price taken from the product catalog at time of invoicing.
`Override`	Price manually overridden by the user.
`Promotion`	Price determined by a promotion or coupon.
`Contract`	Price from a negotiated contract or quote.

discountType required

DiscountType DiscountType

Type of discount applied to this line item. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`Percent`	Percentage discount (e.g., 10%).
`Flat`	Flat dollar amount discount (e.g., $5.00).

discountValue required

number (double)

Discount value (percentage or flat amount). nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

taxRateId required

string (uuid)

Reference to a reusable tax rate definition. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

taxRatePercent required

number (double)

Snapshot of the tax rate percentage. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

taxJurisdiction required

string

Tax jurisdiction (state/country). nullablemax length 100

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

taxRateSource required

InvoiceTaxRateSource InvoiceTaxRateSource

Optional. Where `taxRatePercent` came from. Provider is stored only when `taxRateProviderName` is supplied and `taxRateId` is not; any other combination is stored as Catalog when a rate id is named, otherwise Manual. Provenance is recorded as supplied, like the percentage: the platform does not verify that a lookup ran. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`Manual`	The operator typed the percentage, or nothing recorded where it came from.
`Catalog`	The percentage was snapshotted from one of the biller's named tax rates.
`Provider`	The percentage was sourced from the merchant's bound tax provider.

taxRateProviderName required

string

Optional. The tax provider that sourced the percentage; meaningful only with a Provider source. nullablemax length 50

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

taxCode required

string

Tax code snapshotted from product or overridden. nullablemax length 50

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

isTaxable required

boolean

Whether tax applies to this line. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

isDiscountLine required

boolean

Indicates this is a discount adjustment line. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

isSystemGenerated required

boolean

Indicates this line was auto-generated. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

isOptional required

boolean

For quotes-to-invoices flow: whether this line is optional. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

revenueAccount required

string

GL account for revenue recognition. nullablemax length 100

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

recognitionStartDate required

string (date-time)

Revenue recognition start date. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

recognitionEndDate required

string (date-time)

Revenue recognition end date. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

attributes required

object

Extensibility metadata (key-value pairs). nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

customFields required

array of CustomFieldValueDto array of CustomFieldValueDto

Custom field values. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of each CustomFieldValueDto:

Field Type Description

id required

string (uuid)

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

key required

string

nullablemax length 100

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

label required

string

nullablemax length 200

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

value required

string

nullablemax length 2000

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

billerSnapshot required

InvoicePartySnapshotDto InvoicePartySnapshotDto

Optional biller snapshot to freeze on this invoice at creation time. When supplied, overrides the empty-placeholder default used by IssueAsync. Useful for programmatic/system-generated invoices where the caller already holds the party's display info (e.g., billing-run invoice generation).

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of InvoicePartySnapshotDto:

Field Type Description

name required

string

nullablemax length 200

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

email required

string

nullablemax length 256

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

phone required

string

nullablemax length 30

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

addressLine1 required

string

nullablemax length 200

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

addressLine2 required

string

nullablemax length 200

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

city required

string

nullablemax length 100

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

state required

string

nullablemax length 100

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

postalCode required

string

nullablemax length 20

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

country required

string

nullablemax length 100

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

companyName required

string

nullablemax length 200

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

taxId required

string

nullablemax length 50

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

logoUrl required

string

nullablemax length 2048

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

recipientSnapshot required

InvoicePartySnapshotDto InvoicePartySnapshotDto

Optional recipient snapshot to freeze on this invoice at creation time.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of InvoicePartySnapshotDto:

Field Type Description

name required

string

nullablemax length 200

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

email required

string

nullablemax length 256

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

phone required

string

nullablemax length 30

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

addressLine1 required

string

nullablemax length 200

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

addressLine2 required

string

nullablemax length 200

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

city required

string

nullablemax length 100

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

state required

string

nullablemax length 100

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

postalCode required

string

nullablemax length 20

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

country required

string

nullablemax length 100

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

companyName required

string

nullablemax length 200

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

taxId required

string

nullablemax length 50

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

logoUrl required

string

nullablemax length 2048

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

billerId required

string (uuid)

The billing entity ID.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

billerType required

InvoicePartyType InvoicePartyType

The type of billing entity.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`GatewayOwner`	Platform-level gateway owner.
`Reseller`	Reseller entity.
`Merchant`	Merchant entity.
`Customer`	End customer.

This request body has no documented fields.

Responses

200 OK

Body: InvoiceDto InvoiceDto Each item has these fields.

Field Type Description

extraProperties required

object

nullableread only

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

id required

string (uuid)

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

creationTime required

string (date-time)

The date and time when this entity was created.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

creatorId required

string (uuid)

The ID of the user who created this entity. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

lastModificationTime required

string (date-time)

The date and time when this entity was last modified. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

lastModifierId required

string (uuid)

The ID of the user who last modified this entity. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

isDeleted required

boolean

Indicates whether this entity has been deleted.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

deleterId required

string (uuid)

The ID of the user who deleted this entity, if it is deleted. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

deletionTime required

string (date-time)

The date and time when this entity was deleted, if it is deleted. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

tenantId required

string (uuid)

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

billerId required

string (uuid)

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

billerType required

InvoicePartyType InvoicePartyType

Identifies the type of entity acting as the biller or recipient on an invoice.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`GatewayOwner`	Platform-level gateway owner.
`Reseller`	Reseller entity.
`Merchant`	Merchant entity.
`Customer`	End customer.

recipientId required

string (uuid)

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

recipientType required

InvoicePartyType InvoicePartyType

Identifies the type of entity acting as the biller or recipient on an invoice.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`GatewayOwner`	Platform-level gateway owner.
`Reseller`	Reseller entity.
`Merchant`	Merchant entity.
`Customer`	End customer.

invoiceNumber required

string

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

status required

InvoiceStatus InvoiceStatus

Represents the lifecycle status of an invoice.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`Draft`	Created, editable, not yet issued.
`Issued`	Locked and immutable from this point forward.
`Sent`	Delivered to recipient via a notification channel.
`Viewed`	Recipient opened/viewed the invoice.
`PartiallyPaid`	Some payments applied, balance remaining.
`Paid`	Fully paid (balance = 0).
`PastDue`	Due date passed with outstanding balance.
`Closed`	Manually closed (write-off).
`Uncollectible`	Auto-marked after dunning period exhausted (configurable: 30/60/90 days past due).
`Cancelled`	Voided (only from Draft).
`Refunded`	Full refund issued.

isLocked required

boolean

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

billerSnapshot required

InvoicePartySnapshotDto InvoicePartySnapshotDto

Read DTO for denormalized biller/recipient info frozen at invoice issuance.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of InvoicePartySnapshotDto:

Field Type Description

name required

string

nullablemax length 200

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

email required

string

nullablemax length 256

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

phone required

string

nullablemax length 30

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

addressLine1 required

string

nullablemax length 200

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

addressLine2 required

string

nullablemax length 200

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

city required

string

nullablemax length 100

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

state required

string

nullablemax length 100

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

postalCode required

string

nullablemax length 20

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

country required

string

nullablemax length 100

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

companyName required

string

nullablemax length 200

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

taxId required

string

nullablemax length 50

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

logoUrl required

string

nullablemax length 2048

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

recipientSnapshot required

InvoicePartySnapshotDto InvoicePartySnapshotDto

Read DTO for denormalized biller/recipient info frozen at invoice issuance.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of InvoicePartySnapshotDto:

Field Type Description

name required

string

nullablemax length 200

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

email required

string

nullablemax length 256

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

phone required

string

nullablemax length 30

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

addressLine1 required

string

nullablemax length 200

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

addressLine2 required

string

nullablemax length 200

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

city required

string

nullablemax length 100

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

state required

string

nullablemax length 100

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

postalCode required

string

nullablemax length 20

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

country required

string

nullablemax length 100

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

companyName required

string

nullablemax length 200

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

taxId required

string

nullablemax length 50

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

logoUrl required

string

nullablemax length 2048

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

currency required

string

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

subtotal required

number (double)

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

taxTotal required

number (double)

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

discountTotal required

number (double)

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

grandTotal required

number (double)

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

amountPaid required

number (double)

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

balanceDue required

number (double)

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

invoiceLevelDiscount required

InvoiceDiscountDto InvoiceDiscountDto

DTO for an invoice-level discount.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of InvoiceDiscountDto:

Field Type Description

type required

DiscountType DiscountType

The type of discount applied to a line item or invoice.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`Percent`	Percentage discount (e.g., 10%).
`Flat`	Flat dollar amount discount (e.g., $5.00).

value required

number (double)

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

description required

string

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

issueDate required

string (date-time)

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

dueDate required

string (date-time)

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

sentAt required

string (date-time)

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

viewedAt required

string (date-time)

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

paidAt required

string (date-time)

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

paymentTermsValue required

PaymentTerms PaymentTerms

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`DueOnReceipt`	Payment due immediately upon receipt.
`Net15`	Payment due within 15 days of issue.
`Net30`	Payment due within 30 days of issue.
`Net45`	Payment due within 45 days of issue.
`Net60`	Payment due within 60 days of issue.
`Net90`	Payment due within 90 days of issue.
`Custom`	Custom number of days specified via InvoiceConsts.

customPaymentDays required

integer (int32)

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

allowPartialPayment required

boolean

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

minimumPaymentAmount required

number (double)

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

partialPaymentTolerance required

number (double)

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

allowedPaymentMethods required

array of string array of

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

vaultRestriction required

VaultRestriction VaultRestriction

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`Any`	Allow any payment method (new or saved).
`AllowNewAndSaved`	Allow both new and saved payment methods.
`SavedOnly`	Only allow previously saved (vaulted) payment methods.

applyConvenienceFee required

boolean

Per-invoice override of the merchant's convenience fee on this invoice's payments. `null` inherits the merchant and feature decision. `true` applies the fee only when invoice convenience fees are enabled for the tenant. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

depositRequest required

InvoiceDepositRequestInfoDto InvoiceDepositRequestInfoDto

The deposit request on this invoice, if any. Null when no deposit was requested.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of InvoiceDepositRequestInfoDto:

Field Type Description

depositType required

InvoiceDepositType InvoiceDepositType

Whether the deposit is a percentage of the total or a fixed amount.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`Percentage`	Deposit is a percentage (0 < value < 100) of the invoice grand total.
`FixedAmount`	Deposit is a fixed currency amount (0 < value < grand total).

depositValue required

number (double)

The configured percentage (e.g. 25 for 25%) or fixed amount.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

depositAmount required

number (double)

The resolved absolute deposit amount (rounded to the cent).

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

depositDueDate required

string (date-time)

When the deposit is due; null when due on receipt with the invoice. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

isSatisfied required

boolean

True once the deposit has been fully collected.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

hppPageId required

string (uuid)

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

templateId required

string (uuid)

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

sourceType required

InvoiceSourceType InvoiceSourceType

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`Manual`	Manually created by a user.
`UsageBilling`	Generated from usage billing data.
`RecurringBilling`	Generated from a recurring billing contract.
`Api`	Created via API by an external integration.

sourceReferenceId required

string

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

notes required

array of EntityNote array of EntityNote

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of each EntityNote:

Field Type Description

id required

string (uuid)

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

enteredBy required

string (uuid)

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

timestamp required

string (date-time)

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

enteredByName required

string

Denormalized display name of the user who created the note. Populated at creation time from `ICurrentUser` to avoid N+1 lookups when rendering. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

content required

string

nullablemin length 0max length 1000

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

recipientNote required

string

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

footerText required

string

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

reminderConfig required

InvoiceReminderConfigDto InvoiceReminderConfigDto

DTO for invoice reminder configuration. Each member overrides the tenant's reminder default on its own; a member that is null or omitted inherits that default.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of InvoiceReminderConfigDto:

Field Type Description

preDueDays required

array of integer (int32) array of

Days before the due date to send a reminder (for example 7, 3, 1). Null or omitted inherits the tenant default; an empty list sends no pre-due reminders for this invoice. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

dueDayReminder required

boolean

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

postDueDays required

array of integer (int32) array of

Days after the due date to send a reminder (for example 1, 7, 14, 30). Null or omitted inherits the tenant default; an empty list sends no scheduled post-due reminders for this invoice. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

postDueRecurringDays required

integer (int32)

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

stopOnPaid required

boolean

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

maxReminders required

integer (int32)

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

dunningEndAction required

DunningEndAction DunningEndAction

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`None`	No automatic action taken.
`MarkUncollectible`	Transition the invoice to Uncollectible.
`Close`	Transition the invoice to Closed.

daysUntilUncollectible required

integer (int32)

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

lineItems required

array of InvoiceLineItemDto array of InvoiceLineItemDto

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of each InvoiceLineItemDto:

Field Type Description

id required

string (uuid)

Stable identity for update/delete operations.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

sortOrder required

integer (int32)

Display order on the invoice.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

parentLineItemId required

string (uuid)

Parent line item ID for bundle/discount/tax line hierarchies. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

name required

string

Product name snapshot (formal product name). nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

description required

string

Line item description shown on PDF and HPP. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

notes required

string

Per-line notes visible to the biller only. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

productId required

string (uuid)

Optional link to the product catalog. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

productCode required

string

SKU or product code. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

unitOfMeasure required

string

Unit of measure (e.g., "each", "hour", "GB"). nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

commodityCode required

string

Commodity code sent as enhanced (Level 3) card data when the invoice is paid by card. At most 25 characters. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

quantity required

number (double)

Quantity.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

unitPrice required

number (double)

Unit price.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

grossAmount required

number (double)

Computed: Quantity * UnitPrice.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

cost required

number (double)

Cost for margin tracking. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

pricingSource required

PricingSource PricingSource

How the unit price was determined. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`Catalog`	Price taken from the product catalog at time of invoicing.
`Override`	Price manually overridden by the user.
`Promotion`	Price determined by a promotion or coupon.
`Contract`	Price from a negotiated contract or quote.

discountType required

DiscountType DiscountType

Type of discount applied to this line item. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`Percent`	Percentage discount (e.g., 10%).
`Flat`	Flat dollar amount discount (e.g., $5.00).

discountValue required

number (double)

Discount value (percentage or flat amount). nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

discountAmount required

number (double)

Resolved discount amount. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

netAmount required

number (double)

After discount, before tax.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

taxRateId required

string (uuid)

Reference to a reusable tax rate definition. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

taxRatePercent required

number (double)

Snapshot of the tax rate percentage. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

taxableAmount required

number (double)

Explicit taxable base amount. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

taxAmount required

number (double)

Computed tax amount.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

taxJurisdiction required

string

Tax jurisdiction (state/country). nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

taxRateSource required

InvoiceTaxRateSource InvoiceTaxRateSource

Where `taxRatePercent` came from. Always populated on read: a line stored before provenance existed reads as Catalog when it names a `taxRateId`, otherwise Manual. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`Manual`	The operator typed the percentage, or nothing recorded where it came from.
`Catalog`	The percentage was snapshotted from one of the biller's named tax rates.
`Provider`	The percentage was sourced from the merchant's bound tax provider.

taxRateProviderName required

string

The tax provider that sourced the percentage, when `taxRateSource` is Provider. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

taxCode required

string

Tax code snapshotted from product or overridden. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

isTaxable required

boolean

Whether tax applies to this line. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

lineTotal required

number (double)

Line total including tax.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

isDiscountLine required

boolean

Indicates this is a discount adjustment line. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

isSystemGenerated required

boolean

Indicates this line was auto-generated. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

isOptional required

boolean

For quotes-to-invoices flow: whether this line is optional. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

revenueAccount required

string

GL account for revenue recognition. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

recognitionStartDate required

string (date-time)

Revenue recognition start date. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

recognitionEndDate required

string (date-time)

Revenue recognition end date. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

attributes required

object

Extensibility metadata (key-value pairs). nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

payments required

array of InvoicePaymentDto array of InvoicePaymentDto

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of each InvoicePaymentDto:

Field Type Description

id required

string (uuid)

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

transactionId required

string (uuid)

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

amount required

number (double)

The amount applied against the invoice balance: the invoiced base, never a fee-inclusive total. Fees the payer was charged on top ride the members below.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

convenienceFeeAmount required

number (double)

The convenience fee charged on top of `amount`, in the invoice currency, when one was assessed. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

surchargeAmount required

number (double)

The credit-card surcharge charged on top of `amount`, in the invoice currency, when one was assessed. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

chargedTotal required

number (double)

The total the payer was actually charged, when known. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

paymentMethod required

string

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

status required

InvoicePaymentStatus InvoicePaymentStatus

Status of a payment attempt against an invoice.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`Pending`	Payment is pending processing.
`Succeeded`	Payment succeeded.
`Declined`	Payment was declined by the processor.
`Returned`	Payment was returned (e.g., ACH return).
`Refunded`	Payment was refunded.
`Indeterminate`	The attempt reached the processor but produced no answer the invoice can act on: a referral the merchant has to resolve by voice, a pending or submitted authorization, a partial approval whose approved base cannot be derived, or a status the platform does not recognize. Nothing is credited against the balance and the attempt is not a decline; the row exists so the invoice shows that someone tried and what came back.

declineReasonCode required

string

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

appliedAt required

string (date-time)

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

notes required

string

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

recordedBy required

string

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

activities required

array of InvoiceActivityDto array of InvoiceActivityDto

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of each InvoiceActivityDto:

Field Type Description

id required

string (uuid)

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

timestamp required

string (date-time)

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

type required

InvoiceActivityType InvoiceActivityType

Classifies entries in the invoice activity timeline.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`Created`	Invoice was created.
`Sent`	Invoice was sent to the recipient.
`Viewed`	Recipient viewed the invoice.
`PaymentReceived`	A payment was received.
`PaymentDeclined`	A payment attempt was declined.
`ReminderSent`	A reminder was sent.
`StatusChanged`	Invoice status changed.
`Edited`	Invoice was edited (Draft only).
`Closed`	Invoice was closed.
`Cancelled`	Invoice was cancelled.
`Refunded`	Invoice was refunded.
`CreditApplied`	A credit note was applied.
`NoteAdded`	An internal note was added.
`AutoChargeAttempted`	An automatic payment was attempted (auto-charge or smart-retry).
`PaymentRetryScheduled`	A soft-declined automatic payment was scheduled for a retry.
`PaymentRetriesExhausted`	Smart-retry attempts were exhausted (max attempts or retry window reached).
`PaymentRetriesStopped`	Smart-retry attempts were stopped (hard decline or manual intervention).
`PaymentPlanStarted`	A payment plan was set up against the invoice balance.
`InstallmentCollected`	An installment was collected (manually recorded or auto-charged).
`InstallmentCollectionFailed`	An automatic installment collection attempt failed (declined).
`PaymentPlanCancelled`	The payment plan was cancelled before all installments were collected.
`PaymentIndeterminate`	A payment attempt came back with a result the invoice cannot act on (a referral, a pending or submitted authorization, a partial approval, or an unrecognized status). Nothing was credited. Appended last: the numeric value is stored on the activity row and must never be renumbered.
`PaymentLinkReissued`	An operator replaced the payment link with a fresh one without notifying the recipient. The previous link stopped working. Appended last: the numeric value is stored on the activity row and must never be renumbered.

description required

string

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

userId required

string (uuid)

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

metadata required

string

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

customFields required

array of CustomFieldValueDto array of CustomFieldValueDto

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of each CustomFieldValueDto:

Field Type Description

id required

string (uuid)

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

key required

string

nullablemax length 100

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

label required

string

nullablemax length 200

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

value required

string

nullablemax length 2000

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

concurrencyStamp required

string

nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

entityVersion required

integer (int32)

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

403 Forbidden

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description

error required

RemoteServiceErrorInfo RemoteServiceErrorInfo

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

401 Unauthorized

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description

error required

RemoteServiceErrorInfo RemoteServiceErrorInfo

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

400 Bad Request

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description

error required

RemoteServiceErrorInfo RemoteServiceErrorInfo

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

404 Not Found

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description

error required

RemoteServiceErrorInfo RemoteServiceErrorInfo

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

501 Not Implemented

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description

error required

RemoteServiceErrorInfo RemoteServiceErrorInfo

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

500 Internal Server Error

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description

error required

RemoteServiceErrorInfo RemoteServiceErrorInfo

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

default The request failed. The body carries the standard error envelope: a machine-readable `error.code`, a human-readable `error.message`, and `error.validationErrors` when the failure was a validation rejection. The error reference lists the values `error.code` can take. The request failed. The body carries the standard error envelope: a machine-readable `error.code`, a human-readable `error.message`, and `error.validationErrors` when the failure was a validation rejection. The error reference lists the values `error.code` can take.

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description

error required

RemoteServiceErrorInfo RemoteServiceErrorInfo

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

429 The request was refused because a rate limit was exceeded, or because something a later retry can clear stopped it. A rate limit refusal carries an `application/problem+json` body: wait at least the interval `Retry-After` names before retrying, then back off. Limits are tuned per deployment, so read the allowance from the response headers rather than assuming a fixed ceiling. Any other refusal carries the standard error envelope as `application/json`, and its `error.code` names the cause.

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description

error required

RemoteServiceErrorInfo RemoteServiceErrorInfo

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

Errors

A failed request returns the platform error envelope. The error reference lists every value error.code can carry and shows the four response shapes.

Codes declared by Invoicing

The API reference isn't available right now

No such operation

This reference may be out of date

Invoices: Creates a new draft invoice.

Example request

Parameters

Request body

Responses

200 OK

403 Forbidden

401 Unauthorized

400 Bad Request

404 Not Found

501 Not Implemented

500 Internal Server Error

Errors

Authentication