Sell and redeem gift vouchers through the Ecommerce API

A web store connected to the NaviPartner Ecommerce API can sell new gift vouchers and accept existing vouchers as payment. Both cases go through the same sales document, and Business Central creates and redeems the vouchers as part of the order.

This page covers the setup in Business Central. For request structure, fields, and examples, refer your developer to the Ecommerce API reference.

Set up the voucher type

Every voucher sold or accepted through the Ecommerce API needs a voucher type in Business Central. On the Retail Voucher Type Card, set Apply Payment Module to PARTIAL, so the voucher can be redeemed in several partial payments.

The voucher type code in Business Central must exactly match the code the web store sends. If the code is wrong or the type uses an unsupported setup, the API rejects the order.

Sell a gift voucher

To sell a new gift voucher, the web store adds a line with type voucher and the voucher type code to the sales document. Business Central issues the voucher when it processes the order and returns the voucher reference number in the response.

If the web store already has its own voucher code, it can send that code in barcodeNo on the same line, and Business Central uses it as the voucher reference.

See Create Sales Document in the API reference.

Pay with a gift voucher

To pay with an existing voucher, the web store adds a payment with payment method type voucher and the voucher reference number to the sales document. The amount is deducted from the voucher balance, and any remaining amount can be paid with another payment method.

See Create Sales Document in the API reference.

Not supported

• Voucher types with Apply Payment Module set to DEFAULT or LIMIT.
• Selling or redeeming vouchers on return orders.
• Selling or redeeming vouchers on orders in a foreign currency. The order must be in the local currency.
• Selling a gift voucher as a regular item line. Business Central doesn’t create a voucher from an item line.
• The voucher_created webhook only covers newly created vouchers, not later changes such as top-ups.
• The voucher_payment webhook can’t include the voucher reference number.