Newsletter
Financial management
  • Home
  • Financial management

Introduction

Finance.jpg

Last update :

Toolbox / Tips

This documentation describes how to access your financial data as a seller on Octopia-powered marketplaces (Cdiscount, Bebeboutik, CDON SE, Wooday).
It presents the endpoints made available by the Octopia Financial Report API, and explains how to retrieve invoices, payment records, and financial operations in order to monitor, control, and reconcile your commercial activity.

Business Purpose

This API provides sellers with:

  • Financial visibility: Track income (sales, refunds, service fees) and their associated invoices.

  • Reconciliation support: Operations, and payments across dates, channels, and event types.

  • Access to documents: Download invoice PDFs individually or in bulk for accounting or tax reporting.

Data availability period

Financial information concerning orders is available the day after the acceptation of the order by the seller.

Sellers can therefore retrieve all the financial information of an order (or refund) at Day +1.

Commission statements are issued every 10 days on 9/19/29 of the month. It is a document of grouping of invoices.

The invoice documents (PDF files) are available at the same time as the invoice information.

Finally, payments are triggered automatically every 10 days on 1/11/21 of the month.

Sellers can retrieve the details of the payments made on each payment, as well as payment history.

Key States & Attributes

Attribute

Description

paymentState

Status of a financial operation: NotPayable, Estimated, Paid, Blocked, InProcess.

eventTypes

Nature of financial events: Sale, Commission, Refund, Subscription, LogisticFee, etc.

operationReference

Identifier of a financial transaction (can be an order or invoice).

releasePaymentDate

Date when the operation became eligible for payment.

commission, refund, sale

Sub-objects providing detailed amounts per operation type (gross, VAT, breakdowns).

totalAmount, vatTotalAmount

Aggregate gross and VAT amounts for a payment or operation.

salesChannel

Source marketplace or region associated with the transaction.

invoiceServiceFilePath

Link to service invoice document (e.g., subscription, logistics, etc.).

stateMotive

Reason why a payment is blocked (if applicable).

Seller Workflow

fincance_worflow.png

Channel-specific behaviors

Please note that financial operations may differ slightly from one sales channel to another, especially in terms of:

  • Commission structures

  • Invoice frequency

  • Tax and VAT rules

  • Payment delay and withholding

Always refer to the data returned by the API and the sales channel configuration for reconciliation.

Count Financial Operations

Prerequisites

  • At least one of: orderReference, invoiceId, or a full date range (paidAtMin + paidAtMax OR changedAtMin + changedAtMax).

To retrieve the number of financial operations matching a set of criteria, without returning the full operation list.

This lightweight endpoint returns a single integer: the number of financial operations matching the provided filters.

This helps:

  • Monitor the number of items generated on an invoice or payment

  • Control pagination behavior when calling /operations

  • Power visual KPI charts without full data retrieval

Functional Rules

  • Endpoint returns integer count.

  • If no filter provided, request rejected (400).

  • Date formats must be ISO 8601.

Endpoint to use

Retrieve Financial Operations

Prerequisites

  • At least one filter: orderReference, invoiceId, or valid date range; optional filters like eventTypes or states.

To retrieve a detailed list of financial operations (sales, refunds, commissions, service fees…) linked to your orders, invoices, or payments.
These operations are the foundation of the financial reconciliation process.

Each financial operation returned by this endpoint represents a transaction recorded by Octopia’s financial system. This includes:

  • Order sales

  • Commissions

  • Refunds

  • Logistic and subscription fees

  • Guarantee or service charges

  • VAT amounts when applicable

Each item includes metadata such as:

  • Related invoiceId

  • Event types

  • Currency and total amounts

  • Operation date and payment date

  • Current payment state (Paid, Estimated, Blocked…)

Functional Rules

  • Default pageSize: 20.

  • If filters missing or invalid, 400.

Endpoint to use

Important notes

  • Response includes common.totalAmount – total across all matching operations (not just current page).

  • Use filters (especially event types) to reduce noise.

  • Heavy use could have performance impact.

Count Invoice Details

Prerequisites

  • invoiceId must be known and valid.

Allow the seller to know how many detail lines a given invoice contains without fetching all line‑items.

Functional Rules

  • No pagination or query filters other than those inherent to the path.

  • Returns an integer count.

  • If invoiceId does not exist, returns 404.

  • Use sparingly to avoid overloading reporting tools.

Endpoint to use

Important notes

  • Best used to preview volume before performing full detail fetch.

  • Good to combine with UI indicators (e.g., “You have 120 lines in this invoice”).

Retrieve Invoice Details

Prerequisites

  • invoiceId must be known and valid.

This endpoint provides the detail of all operations included in a specific invoice.

Each item represents a sale, refund, service fee, or commission and includes detailed metadata.

Functional Rules

  • Default pageSize is 20 unless overridden.

  • Supports pageIndex, pageSize query params.

  • The response includes item metadata: product/order reference, amounts, VAT, dates.

  • If invalid pagination or bad invoice ID, returns 400 or 404.

Endpoint to use

Important notes

  • May impact performance for high pageIndex; consider filtering.

Download Invoice Document

Prerequisites

  • invoiceId must be known and valid.

This endpoint returns the official PDF version of a specific invoice.

Invoices are available for download after being generated on fixed dates (9th, 19th, 29th of each month).

Functional Rules

  • Returns PDF binary of the invoice document.

  • If document not present for that invoice ID, return 404.

  • Authorization via SellerId; verify that seller owns or is allowed to see that invoice.

Endpoint to use

Important notes

  • Cache documents locally once downloaded.

  • PDF size / rendering time might vary with number of line items.

Download Multiple Invoice Documents

Prerequisites

  • invoiceIds query parameter list (min 2, max 10).

This endpoint allows sellers to download several invoice documents in one call, grouped inside a compressed (ZIP) archive.

It is intended to:

  • Speed up the retrieval of a batch of PDF invoices (e.g. for monthly exports)

  • Reduce manual effort compared to downloading each file individually

  • Integrate with accounting automation tools

Each file in the archive corresponds to a invoice PDF previously issued for the seller.

Functional Rules

  • `invoiceIds` array is mandatory (min 2, max 10)

  • Result is application/zip containing multiple PDFs

  • If some invoiceIds are invalid or missing docs, behavior may vary (error vs partial)

Endpoint to use

Important notes

  • Archive size may be large; network performance matters.

  • Use only when needed, not for every invoice.

Count Payments

This endpoint allows sellers to retrieve the number of payment records that match a given set of filters, without fetching all payment data.

It can be used to:

  • Power UI counters, pagination indicators or business dashboards

  • Monitor historical payment volume

  • Validate if a full payment request is necessary

Each payment counted may correspond to:

  • A paid transfer

  • An upcoming (Estimated) payment

  • A blocked or unpayable amount

Endpoint to use

List Payments

This endpoint allows sellers to retrieve a list of payments received or expected based on aggregated financial operations grouped by sales channel and payment date.

Each payment returned by this endpoint corresponds to a transfer (or forecasted transfer) to the seller’s bank account and consolidates multiple operations into a single payment record. This includes:

  • Sales revenue

  • Refund adjustments

  • Commissions deducted

  • Service and logistic fees

  • Guarantee or reserve charges

Each payment item includes metadata such as:

  • Total gross amount (including VAT)

  • Breakdown by operation type (sales, refunds, services)

  • Associated payment state (Estimated, Paid, Blocked, NotPayable)

  • Payment date

  • Sales channel

This API is essential for sellers to reconcile their payments with operations and bank statements.

Endpoint to use

Important notes

  • Default pageSize: 20

FAQ

 When are invoices generated?

Invoices are issued every 10 days: on the 9th, 19th, and 29th of each month. They consolidate all operations since the last billing cycle.

 How often do payments happen?

Payouts are executed every 10 days (on the 1st, 11th, and 21st), or on demand once funds are cleared.

 What is the difference between a payment and an invoice?

  • Invoices summarize what is billed (sales, commissions, services).

  • Payments represent what is actually paid out to the seller, based on cleared funds and due dates.

 What is a financial operation?

It is a transaction that impacts your account: sale, refund, commission, guarantee, logistics fee, etc.

 What’s the difference between paidAt and changedAt filters?

  • paidAt: when the transaction was paid.

  • changedAt: when the transaction was last updated — useful for tracking changes (refunds, corrections).

 Are the amounts returned tax-included?

Yes — all amounts are gross (including VAT), with VAT fields provided separately when applicable.

 What’s the recommended integration strategy for high-volume sellers?

  • Retrieve GET /payments once per payout to reconcile balances.

  • Use GET /operations with changedAtMin/Max daily for incremental accounting sync.

  • Retrieve invoice details only when needed, using GET /invoices/{id}/details.

 EU/non-EU seller: how VAT is presented

The VAT presentation depends on the order’s shipping country.

For shipments outside the EU:
VAT is always included in all grossAmount fields (sales, refunds, commissions).
The VAT rate and amount are explicitly broken down under vatSale or vatRefund blocks.
You can see:

  • salesVatAmount: VAT on the product sale

  • salesShippingCostVatAmount: VAT on the shipping cost

  • salesTotalVatAmount: total VAT for the transaction

In all other cases, VAT is 0 and the gross amount equals the net amount.

 Concrete example: reconstruction of operations on an order

Let’s say you want to reconcile all financial operations linked to order 1601302358PGI56.

Here’s how to proceed:

1. Search for operations

GET /operations?orderReference=1601302358PGI56

2. API returns something like:

{
  "items": [
    {
      "operationReference": "1601302358PGI56",
      "orderStatus": "Accepted",
      "paidAt": "2025-09-11",
      "eventTypes": ["Sale", "Commission", "VAT"],
      "sale": {
        "productAmount": 100.00,
        "shippingFeesAmount": 5.00,
        "processingFeesAmount": 1.00,
        "total": 106.00
      },
      "vatSale": {
        "salesVatAmount": 20.00,
        "salesShippingCostVatAmount": 1.00,
        "salesTotalVatAmount": 21.00
      },
      "commission": 10.00,
      "commissionDetail": [
        {"type": "product", "amount": 7.00},
        {"type": "paymentFees", "amount": 3.00}
      ],
      "totalAmount": 96.00
    }
  ]
}

3. Interpretation

Component

Value

Product Sale (gross)

€100.00

Shipping (gross)

€5.00

Processing Fees (gross)

€1.00

Total Sale (gross)

€106.00

VAT on Product

€20.00

VAT on Shipping

€1.00

Total VAT

€21.00

Commission (gross)

€10.00

Payout to seller (gross)

€96.00

📌 So, the seller will receive €96.00 on this order, and the operation includes a full breakdown of revenue, fees, and taxes.