Merchant API: financial totals on orders

About this article

This article explains how to read financial totals from order responses via the Merchant API, covering the difference between base-currency and original-currency fields, and how to use each set correctly for accounting, reconciliation, and customer-facing invoicing.

Table of contents

Introduction

Retrieve orders

Financial totals

Introduction

When you retrieve orders via GET /v2/orders or GET /v2/orders/new, each order response includes a full set of financial fields covering order line totals, shipping costs, VAT breakdowns, and channel fees. These fields come in two parallel sets that serve different purposes and should not be used interchangeably.

Fields without the Original prefix — such as TotalInclVat and ShippingCostsInclVat — are expressed in your shop's base currency as configured in ChannelEngine. When a customer pays in a different currency, ChannelEngine converts the amounts at the exchange rate applicable at the time of ordering. Use these fields for your own accounting, reporting, and payout reconciliation.

Fields with the Original prefix — such as OriginalTotalInclVat and OriginalShippingCostsInclVat — are expressed in the currency the customer actually paid in, identified by the CurrencyCode field on the order. Use these fields when generating customer-facing invoices, displaying the original price to the customer, or when the channel requires amounts in the transaction currency.

This article describes each financial field, explains which set to use for common integration scenarios, and provides guidance on currency conversion behavior.

Retrieve orders

Inspect the responses of your orders for fields relating to financial totals.

• Retrieve orders: GET /v2/orders
  Returns a paginated list of orders matching your filters. Use this endpoint when you need fine-grained control — for example, filtering by status, date range, channel, or acknowledgement state.
• Retrieve new orders: GET /v2/orders/new
  Returns only orders with status NEW that have not yet been acknowledged. The recommended starting point for most polling-based integrations.

Financial totals

Financial fields come in two sets that are easy to confuse. Understanding the difference is important for correct invoicing and reconciliation:

• Fields without the Original prefix (for example, TotalInclVat, ShippingCostsInclVat) — amounts in your shop's base currency, as configured in ChannelEngine. When the customer paid in a different currency, ChannelEngine converts the amounts using the exchange rate at the time of ordering. These are the amounts you should use for your own accounting, reporting, and payout reconciliation.
• Fields with the Original prefix (for example, OriginalTotalInclVat, OriginalShippingCostsInclVat) — amounts in the currency the customer actually paid in, before any conversion. The currency is identified by CurrencyCode on the order. Use these amounts when you need to show the customer their original price, generate an invoice in the transaction currency, or when the channel itself requires amounts in the original currency.