# POST /api/invoicing/invoices Invoices: Creates a new draft invoice. **Required permissions**: `Invoicing.Invoices`, `Invoicing.Invoices.Create` **Scope**: merchant **Operation ID:** `invoiceCrudCreate` ## Authorization Requires: Invoicing.Invoices, Invoicing.Invoices.Create, merchant scope. Required permissions: - `Invoicing.Invoices` - `Invoicing.Invoices.Create` ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | suppressNulls | query | no | boolean | If true, omit properties with null values. | ## Request Body **Content type:** `application/json` Schema: `InvoiceCreateDto` Properties: - `recipientId` (string(uuid)) required: Recipient entity ID. - `recipientType` (object): Recipient entity type. - `currency` (string) required: ISO 4217 currency code. - `paymentTermsValue` (object): Standard payment terms. - `customPaymentDays` (integer(int32)): Custom number of days when PaymentTerms is Custom. Conditional: When PaymentTermsValue == Custom. Must be > 0. - `dueDate` (string(date-time)): Manual due date override (used if PaymentTerms is null). - `allowPartialPayment` (boolean): Whether partial payments are allowed. - `minimumPaymentAmount` (number(double)): Minimum payment amount when partial payments are enabled. Conditional: When AllowPartialPayment is true and MinimumPaymentAmount is not null. Must be > 0. - `partialPaymentTolerance` (number(double)): Auto-close tolerance. - `depositType` (object): 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. - `depositValue` (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. - `depositDueDate` (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. - `allowedPaymentMethods` (array): Subset of biller's supported payment methods for this invoice. Conditional: When AllowedPaymentMethods is not null. - `vaultRestriction` (object): Controls whether new or saved payment methods are allowed. - `applyConvenienceFee` (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. - `hppPageId` (string(uuid)): Linked HPP configuration ID. - `templateId` (string(uuid)): Invoice style/template reference. - `invoiceLevelDiscount` (object): Invoice-level discount. - `reminderConfig` (object): Per-invoice reminder overrides. - `sourceType` (object): How this invoice was created. - `sourceReferenceId` (string): Caller-provided reference. Conditional: When SourceReferenceId is not empty. Max length: 200. - `notes` (array): Internal notes (not shown to recipient). - `recipientNote` (string): Shown on the invoice to the recipient. Conditional: When RecipientNote is not empty. Max length: 2000. - `footerText` (string): Terms and conditions text. Conditional: When FooterText is not empty. Max length: 5000. - `lineItems` (array): Line items to set on the invoice. - `customFields` (array): Custom field values. - `billerSnapshot` (object): 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). - `recipientSnapshot` (object): Optional recipient snapshot to freeze on this invoice at creation time. - `billerId` (string(uuid)) required: The billing entity ID. - `billerType` (object): The type of billing entity. **Content type:** `text/json` Schema: `InvoiceCreateDto` Properties: - `recipientId` (string(uuid)) required: Recipient entity ID. - `recipientType` (object): Recipient entity type. - `currency` (string) required: ISO 4217 currency code. - `paymentTermsValue` (object): Standard payment terms. - `customPaymentDays` (integer(int32)): Custom number of days when PaymentTerms is Custom. Conditional: When PaymentTermsValue == Custom. Must be > 0. - `dueDate` (string(date-time)): Manual due date override (used if PaymentTerms is null). - `allowPartialPayment` (boolean): Whether partial payments are allowed. - `minimumPaymentAmount` (number(double)): Minimum payment amount when partial payments are enabled. Conditional: When AllowPartialPayment is true and MinimumPaymentAmount is not null. Must be > 0. - `partialPaymentTolerance` (number(double)): Auto-close tolerance. - `depositType` (object): 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. - `depositValue` (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. - `depositDueDate` (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. - `allowedPaymentMethods` (array): Subset of biller's supported payment methods for this invoice. Conditional: When AllowedPaymentMethods is not null. - `vaultRestriction` (object): Controls whether new or saved payment methods are allowed. - `applyConvenienceFee` (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. - `hppPageId` (string(uuid)): Linked HPP configuration ID. - `templateId` (string(uuid)): Invoice style/template reference. - `invoiceLevelDiscount` (object): Invoice-level discount. - `reminderConfig` (object): Per-invoice reminder overrides. - `sourceType` (object): How this invoice was created. - `sourceReferenceId` (string): Caller-provided reference. Conditional: When SourceReferenceId is not empty. Max length: 200. - `notes` (array): Internal notes (not shown to recipient). - `recipientNote` (string): Shown on the invoice to the recipient. Conditional: When RecipientNote is not empty. Max length: 2000. - `footerText` (string): Terms and conditions text. Conditional: When FooterText is not empty. Max length: 5000. - `lineItems` (array): Line items to set on the invoice. - `customFields` (array): Custom field values. - `billerSnapshot` (object): 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). - `recipientSnapshot` (object): Optional recipient snapshot to freeze on this invoice at creation time. - `billerId` (string(uuid)) required: The billing entity ID. - `billerType` (object): The type of billing entity. **Content type:** `application/*+json` Schema: `InvoiceCreateDto` Properties: - `recipientId` (string(uuid)) required: Recipient entity ID. - `recipientType` (object): Recipient entity type. - `currency` (string) required: ISO 4217 currency code. - `paymentTermsValue` (object): Standard payment terms. - `customPaymentDays` (integer(int32)): Custom number of days when PaymentTerms is Custom. Conditional: When PaymentTermsValue == Custom. Must be > 0. - `dueDate` (string(date-time)): Manual due date override (used if PaymentTerms is null). - `allowPartialPayment` (boolean): Whether partial payments are allowed. - `minimumPaymentAmount` (number(double)): Minimum payment amount when partial payments are enabled. Conditional: When AllowPartialPayment is true and MinimumPaymentAmount is not null. Must be > 0. - `partialPaymentTolerance` (number(double)): Auto-close tolerance. - `depositType` (object): 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. - `depositValue` (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. - `depositDueDate` (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. - `allowedPaymentMethods` (array): Subset of biller's supported payment methods for this invoice. Conditional: When AllowedPaymentMethods is not null. - `vaultRestriction` (object): Controls whether new or saved payment methods are allowed. - `applyConvenienceFee` (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. - `hppPageId` (string(uuid)): Linked HPP configuration ID. - `templateId` (string(uuid)): Invoice style/template reference. - `invoiceLevelDiscount` (object): Invoice-level discount. - `reminderConfig` (object): Per-invoice reminder overrides. - `sourceType` (object): How this invoice was created. - `sourceReferenceId` (string): Caller-provided reference. Conditional: When SourceReferenceId is not empty. Max length: 200. - `notes` (array): Internal notes (not shown to recipient). - `recipientNote` (string): Shown on the invoice to the recipient. Conditional: When RecipientNote is not empty. Max length: 2000. - `footerText` (string): Terms and conditions text. Conditional: When FooterText is not empty. Max length: 5000. - `lineItems` (array): Line items to set on the invoice. - `customFields` (array): Custom field values. - `billerSnapshot` (object): 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). - `recipientSnapshot` (object): Optional recipient snapshot to freeze on this invoice at creation time. - `billerId` (string(uuid)) required: The billing entity ID. - `billerType` (object): The type of billing entity. ## Responses ### 200 OK **Content type:** `application/json` Schema: `InvoiceDto` Properties: - `extraProperties` (object) - `id` (string(uuid)) - `creationTime` (string(date-time)): The date and time when this entity was created. - `creatorId` (string(uuid)): The ID of the user who created this entity. - `lastModificationTime` (string(date-time)): The date and time when this entity was last modified. - `lastModifierId` (string(uuid)): The ID of the user who last modified this entity. - `isDeleted` (boolean): Indicates whether this entity has been deleted. - `deleterId` (string(uuid)): The ID of the user who deleted this entity, if it is deleted. - `deletionTime` (string(date-time)): The date and time when this entity was deleted, if it is deleted. - `tenantId` (string(uuid)) - `billerId` (string(uuid)) - `billerType` (InvoicePartyType): Identifies the type of entity acting as the biller or recipient on an invoice. - `recipientId` (string(uuid)) - `recipientType` (InvoicePartyType): Identifies the type of entity acting as the biller or recipient on an invoice. - `invoiceNumber` (string) - `status` (InvoiceStatus): Represents the lifecycle status of an invoice. - `isLocked` (boolean) - `billerSnapshot` (InvoicePartySnapshotDto): Read DTO for denormalized biller/recipient info frozen at invoice issuance. - `recipientSnapshot` (InvoicePartySnapshotDto): Read DTO for denormalized biller/recipient info frozen at invoice issuance. - `currency` (string) - `subtotal` (number(double)) - `taxTotal` (number(double)) - `discountTotal` (number(double)) - `grandTotal` (number(double)) - `amountPaid` (number(double)) - `balanceDue` (number(double)) - `invoiceLevelDiscount` (InvoiceDiscountDto): DTO for an invoice-level discount. - `issueDate` (string(date-time)) - `dueDate` (string(date-time)) - `sentAt` (string(date-time)) - `viewedAt` (string(date-time)) - `paidAt` (string(date-time)) - `paymentTermsValue` (object) - `customPaymentDays` (integer(int32)) - `allowPartialPayment` (boolean) - `minimumPaymentAmount` (number(double)) - `partialPaymentTolerance` (number(double)) - `allowedPaymentMethods` (array) - `vaultRestriction` (object) - `applyConvenienceFee` (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. - `depositRequest` (object): The deposit request on this invoice, if any. Null when no deposit was requested. - `hppPageId` (string(uuid)) - `templateId` (string(uuid)) - `sourceType` (object) - `sourceReferenceId` (string) - `notes` (array) - `recipientNote` (string) - `footerText` (string) - `reminderConfig` (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. - `lineItems` (array) - `payments` (array) - `activities` (array) - `customFields` (array) - `concurrencyStamp` (string) - `entityVersion` (integer(int32)) ### 403 Forbidden **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 401 Unauthorized **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 400 Bad Request **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 404 Not Found **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 501 Not Implemented **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 500 Internal Server Error **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 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. See the error-code reference in this document's description for the values `error.code` can take. **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 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. **Content type:** `application/problem+json` Schema: `RateLimitProblemDetails` Properties: - `type` (string) required: The problem type identifier. Always the same value: the failure is the status code itself, so there is no sub-type for a caller to branch on. - `title` (string) required: A short, human-readable summary of the problem type. - `status` (integer(int32)) required: The HTTP status code, repeated in the body as the problem-details format defines. - `detail` (string) required: A human-readable explanation of this occurrence of the problem. - `retryAfterSeconds` (integer(int32)) required: How long to wait before retrying, in whole seconds, carrying the same figure as the `Retry-After` header. Always at least one: a value of zero would invite an immediate retry that is certain to be rejected again. **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ## Example request Every block below sends the same request. 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 ```bash curl -X POST "{{BASE_URL}}/api/invoicing/invoices" \ -H "api-key: {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "recipientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "currency": "", "billerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }' ``` ### PowerShell ```powershell $headers = @{ 'api-key' = '{{API_KEY}}' } $body = @' { "recipientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "currency": "", "billerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } '@ $response = Invoke-RestMethod -Method POST -Uri '{{BASE_URL}}/api/invoicing/invoices' ` -Headers $headers -ContentType 'application/json' -Body $body ``` ### TypeScript (SDK) ```bash npm install @winkpg/winkpg-api ``` ```typescript import { Configuration, InvoicingApi } from '@winkpg/winkpg-api'; const api = new InvoicingApi(new Configuration({ basePath: '{{BASE_URL}}', apiKey: '{{API_KEY}}', })); const { data } = await api.invoiceCrudCreate({ "recipientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "currency": "", "billerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }); ``` ### TypeScript (raw HTTP) ```typescript const response = await fetch('{{BASE_URL}}/api/invoicing/invoices', { method: 'POST', headers: { "api-key": "{{API_KEY}}", "Content-Type": "application/json", }, body: JSON.stringify({ "recipientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "currency": "", "billerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }), }); const data = await response.json(); ``` ### C# (SDK) ```bash dotnet add package WinkPg.Api.Client ``` ```csharp 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(""" { "recipientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "currency": "", "billerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } """); var result = await api.InvoiceCrudCreateAsync(body); ``` ### C# (raw HTTP) ```csharp 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(""" { "recipientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "currency": "", "billerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } """, Encoding.UTF8, "application/json"); var response = await http.SendAsync(request); response.EnsureSuccessStatusCode(); var json = await response.Content.ReadAsStringAsync(); ``` ### Python (SDK) ```bash pip install winkpg-api ``` ```python 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({ "recipientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "currency": "", "billerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }) result = api.invoice_crud_create(body) ``` ### Python (raw HTTP) ```bash pip install requests ``` ```python import requests headers = { "api-key": "{{API_KEY}}", "Content-Type": "application/json", } body = { "recipientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "currency": "", "billerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } response = requests.request( "POST", "{{BASE_URL}}/api/invoicing/invoices", headers=headers, json=body, ) response.raise_for_status() data = response.json() ``` ## See also - [All documentation](https://devportal-simpay-sbx.winkpg.io/llms.txt): the machine-readable index of every public page on this site.