Live verification. Verified live on a test company (2026-11-11) with this release: selling gift certificates (including automatic numbering, required barcodes and expiry), redeeming them with cash change, forfeit and a credit-note change, marking certificates used, activating the change credit note, the recovery commands, and the refusals before any write; every test invoice ended fully settled. Not exercised live: the reference lookup after a failed invoice create, because no create failed.
client.Sales.Invoice.CreateWithGiftCertificatesAsync(request, options) creates a sales invoice paid with one or more
gift certificates and then marks every certificate used. Read Concepts and prerequisites
first: the invoice must be posted, needs a unique reference of at most 12 characters, every line needs an explicit price,
and you supply the payment ids.
Settings), and your payment ids are checked against the company'sSORUPM.Change.CreditNote, a credit note for the change is created first (inactive), because the invoice's payment must name it.Nothing is retried or rolled back. If the invoice exists and a later step fails, you get an exception that says which
steps are left (Failures and recovery); never create the invoice again.
Because the client computes the total itself, every line of the invoice must carry an explicit price, or a
DkPlusModelValidationException keyed by the line (Invoice.Lines[0].UnitPrice, .PricesIncludeTax, .Quantity,
.DiscountPercent, .DiscountAmount, .Total) is thrown before any request:
UnitPrice is set, with PricesIncludeTax = true: the unit price including VAT.Quantity is not 0.DiscountPercent and DiscountAmount are unset or 0. Put the discounted price in UnitPrice.Total is unset, or equal to quantity times unit price.Options.OriginalPrices is refused too: with it DK prices every line from the item instead of using your price. Certificates
you sell on the same invoice are lines that already follow these rules (quantity 1, the amount with tax); when you also
redeem, each sold Amount must be a whole number of cents.
The reason is how DK Plus behaves: its price calculation (PATCH /api/v1/sales/invoice/calculate) prices every line from the
item and ignores the price on the line, while the create keeps the price you supply and invoices a line without one at 0. A
total taken from the calculation would not be the total the invoice is created with.
The invoice total is 800 kr and certificate GB-1007 is worth 1000 kr, so 200 kr is left over. The three values of
Change handle the 200 kr differently. The payment ids are the company's own; keep them in your configuration (list them
once with GetSettingsAsync() or devop-dk sales gift-certificate settings).
using DevOp.DK.Plus;
using DevOp.DK.Plus.Models;
public sealed class GiftCertificateSale(IDkPlusClient dkPlus)
{
public async Task<GiftCertificateInvoiceResult> PayAsync(
GiftCertificateChange change,
CancellationToken cancellationToken)
{
var invoice = new SalesInvoiceCreateRequest
{
Customer = new DkPlusSalesDocumentParty { Number = "C-100" },
Reference = "SALE-1007",
Lines =
[
new SalesInvoiceLineRequest
{
ItemCode = "ITEM-1",
Quantity = 1,
UnitPrice = 800m, // explicit, including VAT
PricesIncludeTax = true
}
]
};
return await dkPlus.Sales.Invoice.CreateWithGiftCertificatesAsync(
invoice,
new GiftCertificateInvoiceOptions
{
Post = true,
Redeem = [new GiftCertificateRedemption { Number = "GB-1007" }],
GiftCertificatePaymentId = 1314, // an active payment type 9
Change = change,
ChangePaymentId = change switch
{
GiftCertificateChange.Cash => 6, // an active type 6 (exchange, "Til baka")
GiftCertificateChange.CreditNote => 8, // an active type 8
_ => null
}
},
cancellationToken);
}
}
Change |
What is paid and given back | ChangePaymentId |
|---|---|---|
Cash |
The certificate pays its whole 1000 kr; a change payment of 200 kr on the exchange payment method (type 6, "Til baka") records the cash you hand back. dkERP stores it as a positive exchange payment and subtracts it. | Required, an active type 6 |
CreditNote |
The certificate pays its whole 1000 kr; a new credit note worth 200 kr is created before the invoice and activated after it, and the invoice's change payment (type 8) names it. The customer can spend the credit note later. | Required, an active type 8 |
Forfeit |
The certificate payment is capped at the 800 kr due; no change payment is made. The certificate is still marked used, so the remaining 200 kr is forfeited. | Rejected |
With no change (the certificates are worth the amount due or less), Change is not used. The client never decides from
the company settings: if GiveChangeAsCreditNote is on and the change is at least MinimumCreditNoteChange, choose
CreditNote yourself, as the desktop would. Pass Settings = await dkPlus.Sales.GiftCertificate.GetSettingsAsync(...)
to skip the storage and settings reads for every invoice; the payment ids are still checked every time.
Redeem =
[
new GiftCertificateRedemption { Number = "GB-1007" },
new GiftCertificateRedemption { Number = "GB-1008", Amount = 300m } // uses 300 kr; Forfeit only
]
A certificate's amount defaults to its whole value. A smaller Amount forfeits the rest of that certificate, so it is
accepted only with Change = Forfeit; a larger one is rejected. With Forfeit the certificate payments are capped at the
amount due, in request order.
GiftCertificateInvoiceResult has:
| Member | Meaning |
|---|---|
Invoice, Posted |
The created invoice (a DkPlusSalesInvoice) and whether it is posted |
Redeemed |
The certificates as they are after being marked used. They are not read again, so their Modified is the value before the write |
ChangeCreditNote |
The activated change credit note, when Change = CreditNote |
Issued |
Certificates sold on the same invoice (Selling) |
Change |
The part of the certificates' value that the invoice did not use: with Cash and CreditNote it was given back, with Forfeit it is the forfeited amount, which is not paid back |
TotalUsed |
The part of the invoice the certificates paid |
ExpectedTotal |
The total computed from your lines (the payments and the change were computed from it); null when nothing is redeemed |
CreatedTotal |
The total with tax of the invoice DK Plus created; equal to ExpectedTotal to the cent whenever a certificate was redeemed |
After the create, the total DK Plus answers must equal the computed total to the cent. When it differs, or is missing, the
invoice's payments do not match its total, and that is a hard failure, never a warning. The certificates are marked used
(their payments are on the invoice), a change credit note is held inactive and every sold certificate is held uncreated,
both as pending steps with the reason AmountMismatch, and the call throws DkPlusGiftCertificateInvoiceException with
the outcome Created, the invoice, the completed and the pending steps, and a message that the invoice total differs. The
CLI exits with code 1 and a JSON partial result; PowerShell writes the error record. Correct the invoice in dkERP before you
complete a held step, and do not create the invoice again.
DK rounds every payment and every line total to the local currency's decimals when it stores it. The client does not know
those decimals, so it does not round: give line prices, Redeem.Amount and the invoice's own payment amounts with no more
decimals than the local currency has (for a currency with no decimals, whole amounts). A line total that DK rounds
differently makes the created total differ, which fails the call after the invoice is created.
Before any request, option and invoice problems are reported together in one DkPlusModelValidationException, by path
(for example Invoice.Reference, Redeem[0].Number) and never with a certificate number:
Redeem has at least one entry; each Number is required, unique ignoring case, and free of *, =, , and ;;Amount, when given, is greater than 0.GiftCertificatePaymentId is given and greater than 0; ChangePaymentId is greater than 0, required with Cash orCreditNote, and rejected with Forfeit or without Change.CurrencyCode or ExchangeRate, not a prescription, has a customer number andReference, and carries no gift-certificate or credit-note payment of its own.OriginalPrices is not set.Post is true.GiftCertificatePaymentId must be an active type 9, a cash ChangePaymentId an active type 6, a credit-noteChangePaymentId an active type 8.Problems that need the papers are InvalidOperationException, also before any write: a certificate that does not exist
or is not redeemable, an amount above the certificate's (or below it without Forfeit), or change without a Change
choice.
devop-dk sales invoice create -c C-100 -i ITEM-1 -p 800 --prices-include-tax --reference SALE-1007 \
--gift-certificate GB-1007 --gift-certificate-payment-id 1314 \
--change credit-note --change-payment-id 8 --post --yes
New-Invoice -Customer C-100 -Line @{ ItemCode = 'ITEM-1'; Quantity = 1; UnitPrice = 800; PricesIncludeTax = $true } `
-Reference SALE-1007 -GiftCertificate GB-1007 -GiftCertificatePaymentId 1314 -Change CreditNote -ChangePaymentId 8
The CLI options are --gift-certificate <number>[=<amount>] (repeatable), --gift-certificate-payment-id, --change
(cash, credit-note or forfeit), --change-payment-id, and --reference; they need --post --yes, because an
invoice with gift certificates is always posted. Every line needs an explicit unit price with tax (-p <price> --prices-include-tax, unit-price=...;prices-include-tax=true in a --line, or UnitPrice and PricesIncludeTax in the
--file lines), a quantity other than 0, and no discount; a line that breaks the rule exits with code 2 before any request,
and --original-prices is refused. The PowerShell parameters are -GiftCertificate, -GiftCertificatePaymentId, -Change
(Cash, CreditNote, Forfeit), -ChangePaymentId and -Reference, with the same line rule; -Post:$false is refused.
There is no option for the invoice total: the client computes it. More in the
cookbook.
Next: Selling and Failures and recovery.