Newsletter
Orders Invoices
  • Home
  • Orders Invoices

Introduction

Finance.jpg

Last update :

Toolbox / Tips

This feature allows a seller to upload an order invoice so it can be attached to the corresponding order and made available to the final customer.

In the marketplace order lifecycle, this step happens after the order has been validated and fulfilled, when the seller is ready to provide the final invoice. The API does not generate invoices. It only lets the seller submit invoice files that have already been produced.

The feature supports two main usage patterns: uploading an invoice for a single order, or sending several invoices in bulk. In both cases, the platform validates the request, checks the order reference, verifies the file format, and processes the document asynchronously before attaching it to the order.

This API is therefore both an upload mechanism and a control point. It confirms whether an invoice can actually be linked to the expected order, and it also supports correction flows since a newly uploaded invoice can replace an existing one.

invoices.png

Key States & Attributes

Field / Term

Description

Business Rules

orderId

Identifier of the order that should receive the invoice

Required for the single-order upload endpoint. In bulk upload, the order is identified from the file name instead of a request field.

importId

Unique identifier of an invoice upload operation

Returned as soon as the upload request is accepted. Used to monitor asynchronous processing and investigate failures.

fileName

Name of the uploaded file

In bulk upload, the file name must be a valid order identifier. In ZIP uploads, inner file names must also match valid order identifiers.

status

Overall result of an import, or result of a single file

Main values are Running, Success, PartialSuccess, and Failure at import level; Running, Success, and Failure at file level.

integrationStatus

Technical step reached during invoice processing

Values include OrderCheck, FileCheck, FileExtract, FileUpload, Done, and Failure. Useful for understanding where processing is blocked or still running.

files

List of files attached to one import

The list can evolve during processing, especially when a ZIP archive is unpacked and inner files appear individually in the result.

PDF / XML / ZIP

Supported invoice file formats

Accepted formats are PDF, XML in UBL 2.1 format, and ZIP archives containing supported invoice files.

Invoice replacement

Behavior when an invoice already exists for the order

Uploading a new invoice replaces the existing invoice document for that order. This supports correction and resubmission scenarios.

Seller Workflow

invoice-workflow.png

Generate the Invoice File

Prerequisites

  • The order must already exist in the platform

  • The seller must be able to retrieve the related order and financial data

  • The seller must have a process to generate a PDF or UBL 2.1 XML invoice file

Before uploading an invoice, the seller must first generate the invoice document from marketplace data. This step consists in collecting the customer billing information, the ordered items, the quantities, the prices, and the taxes needed to build the final invoice.

GET /orders is the main source for invoice content. GET /operations can then be used to enrich or verify financial amounts and reconciliation data.

Functional Rules

  • GET /orders provides the main business data used to generate the customer invoice:

    • order identifier

    • purchase date

    • currency

    • billing address

    • product lines & quantities

    • unit prices

    • shipping costs

    • taxes

    • order total

  • Invoice line content should mainly be built from lines[] in GET /orders

  • Billing identity should be built from billingAddress

  • currencyCode should be used as the invoice currency

  • GET /operations provides complementary financial data such as:

    • product amount

    • shipping fees amount

    • processing fees amount

    • VAT amounts

    • total amount

    • currency

    • invoice identifier

  • GET /operations should be used as a reconciliation source, not as the primary source for customer invoice structure

  • Commission data and settlement-related amounts should be handled carefully, as they are useful for seller financial control but are not necessarily part of the customer-facing invoice

  • The invoice file must be generated by the seller system before being uploaded

  • The generated file must be in one of the supported formats:

    • PDF

    • XML in UBL 2.1 format

Endpoint to use

Important notes

Use GET /orders as the main invoice source. It contains the customer, address, line, and pricing data needed to build the document.

Use GET /operations for financial checks. It is useful to confirm totals, VAT-related figures, and invoice references, but it should not replace order data.

Keep customer invoice data and seller settlement data separate. Fields such as commissions or processing fees may be relevant for reconciliation without being displayed on the final customer invoice.

Upload Invoices for a Specific Order

Prerequisites

  • The target order must exist in the platform

  • The seller must have generated the invoice file beforehand

  • The file must be provided in multipart/form-data format

This endpoint allows a seller to upload one or more invoice files for a specific order. It is typically used in operational flows where the order is already known, such as after shipment or during a customer service interaction.

It is also the preferred option for correcting an invoice, as uploading a new file replaces the existing invoice attached to the order.

Functional Rules

  • The upload is asynchronous: the response confirms acceptance, not final success

  • Supported formats are PDF, XML (UBL 2.1), and ZIP containing those formats

  • Multiple files can be uploaded in one request

  • Each file is processed independently and has its own status

  • The platform validates the order before attaching the invoice

  • A new upload replaces any existing invoice for the same order

  • Processing steps are visible through integrationStatus (e.g. order check, file validation, upload)

Endpoint to use

This endpoint uses multipart/form-data rather than JSON. A typical request looks like this:

POST /orders/SCID01210525142759UT8E/invoice-documents?sellerId=123
Content-Type: multipart/form-data
Authorization: Bearer

Form-data payload example:

file1 = SCID01210525142759UT8E.pdf
file2 = SCID01210525142759UT8E.xml

Important notes

Use for targeted corrections. This endpoint is ideal when only one order needs to be fixed without impacting other invoices.

Do not rely on immediate success. Always check the returned status before considering the invoice as available.

ZIP files may expand into multiple entries. Each inner file will appear separately in the processing result.

Upload Invoices in Bulk

Prerequisites

  • Invoice files must be named using valid order identifiers

  • For ZIP uploads, inner file names must also match valid order identifiers

  • Files must be provided in multipart/form-data

This endpoint allows a seller to upload multiple invoices in a single request. It is designed for batch processing from ERP or back-office systems, typically after a mass invoice generation.

The order is not provided explicitly. It is inferred from each file name, making naming conventions a key part of the integration.

Functional Rules

  • The upload is asynchronous and creates an import identified by importId

  • Supported formats are PDF, XML (UBL 2.1), and ZIP archives

  • Each file is matched to an order based on its file name

  • ZIP files are unpacked and processed file by file

  • Each file has its own result (success or failure)

  • The global import status can be Success, PartialSuccess, or Failure

  • Existing invoices are replaced if a new one is successfully processed

Endpoint to use

This endpoint uses multipart/form-data rather than JSON. A typical request looks like this:

POST /order-invoice-imports?sellerId=135
Content-Type: multipart/form-data
Authorization: Bearer

Form-data payload example:

file1 = MARJMA24031215601SELLER.pdf
file2 = BULK_INVOICES_20251212.zip

Important notes

File naming drives the integration. An incorrect file name means the invoice cannot be linked to an order.

Expect partial results. A valid batch can still contain failed files that must be corrected.

Monitor systematically. Bulk uploads require follow-up via the import status endpoints.

Monitor Bulk Import Results

Prerequisites

  • Used after a bulk upload to track processing results

This endpoint provides a list of invoice imports for a seller. It is mainly used to monitor batch processing and identify imports that are still running or require action.

It helps detect incomplete or failed batches and supports operational follow-up.

Functional Rules

  • Imports are returned from most recent to oldest

  • Each import includes global status and file-level results

  • Statuses indicate whether processing is ongoing, successful, or partially failed

  • File-level errors must be used to understand and fix issues

Endpoint to use

Important notes

Use it as a monitoring tool. This endpoint is essential to track asynchronous processing.

Always check file-level results. A successful import does not guarantee all files succeeded.

Drive recovery from this view. Identify failed files and trigger resubmission flows.

Check a Specific Import Result

Prerequisites

  • The importId must be known

This endpoint retrieves the detailed result of a single import. It is typically used after identifying an issue in a batch to understand exactly what failed.

It allows sellers to isolate problematic files and prepare targeted corrections.

Functional Rules

  • Returns one import with all associated file results

  • Each file includes its status, associated order (if resolved), and error details if any

  • Works for both bulk uploads and single-order uploads (both generate an import)

  • The response reflects the latest processing state

Endpoint to use

Important notes

Best endpoint for troubleshooting. Use it to understand why a file failed.

Check all files, not just one. ZIP uploads often produce multiple entries.

Keep track of importId. It is required for any detailed investigation.

Detect Invoice Upload Errors

Prerequisites

  • The seller must have performed at least one invoice upload (single or bulk)

  • An importId or access to import history is available

This use case focuses on identifying issues after an invoice upload. Since processing is asynchronous, errors are not always visible at upload time and must be retrieved afterward.

It allows sellers to detect failed files, understand what went wrong, and decide whether corrective action is required.

Functional Rules

  • Upload requests may succeed technically but fail during processing

  • Errors are always returned at file level, not only at import level

  • Each file includes:

    • a status (Success or Failure)

    • an optional error object with code and detail

  • Import-level status (PartialSuccess, Failure) is only a summary

  • Typical error cases include:

    • invalid file format

    • order not found

    • duplicate invoice already provided

  • ZIP files may generate multiple file entries, each with its own result

Endpoint to use

Important notes

Always check file-level results. Import status alone is not sufficient to detect all issues.

Use import detail for investigation. It provides the most precise view of failures.

Do not assume immediate availability. A file marked as Running still requires follow-up.

Retry Failed Invoice Uploads

Prerequisites

  • Failed files must have been identified from a previous import

  • Corrected invoice files must be available

This use case describes how to correct and resubmit failed invoice uploads. Once an error is identified, the seller must fix the issue and resend only the impacted invoices.

It ensures that each order eventually receives a valid invoice without duplicating successful uploads.

Functional Rules

  • Only files with Failure status should be retried

  • The root cause must be fixed before resubmission:

    • regenerate the file if the format is invalid

    • correct the order identifier if it does not match an existing order

    • validate business intent in case of duplicate uploads

  • Resubmission can be done:

    • per order (single upload)

    • or in batch (bulk upload)

  • A successful retry replaces any previously attached invoice

  • Retried files go through the same asynchronous processing lifecycle

Endpoint to use

Important notes

Retry selectively. Do not resend the entire batch if only a few files failed.

Fix before retrying. Re-sending the same invalid file will lead to the same error.

Track retries via new importId. Each retry creates a new processing cycle that must be monitored.

FAQ

 When should I upload an invoice for an order?

You should upload the invoice once the order is confirmed and the invoice has been generated in your system. This typically happens after shipment or when the invoice becomes legally available.

 Can I upload multiple invoices at once?

Yes. You can use the bulk upload endpoint to send multiple invoices in a single request, including ZIP files containing several invoice documents.

 What file formats are supported?

The API supports:

  • PDF

  • XML (UBL 2.1 format)

  • ZIP archives containing PDF and/or XML files

 How is the order linked to the invoice in bulk upload?

In bulk uploads, the order is identified from the file name. Each file name must match a valid order identifier. The same rule applies to files inside ZIP archives.

 What happens if I upload an invoice for an order that already has one?

The new invoice replaces the existing one. This allows you to correct or update a previously submitted invoice.

 Is the invoice immediately available after upload?

No. The upload is asynchronous. A successful API response only confirms that the request was accepted. You must check the import status to confirm that the invoice was successfully processed.

 How can I check if my invoice upload succeeded?

You can retrieve the import status using the import endpoints. Always check file-level results to confirm whether each invoice was successfully attached to its order.

 What does “PartialSuccess” mean?

It means that some files in your upload were successfully processed, while others failed. You should review the failed files and resubmit only those.

 What are the most common reasons for invoice upload failure?

Common causes include:

  • invalid file format

  • incorrect file naming (especially in bulk uploads)

  • order not found

  • duplicate invoice already submitted

 Should I resend the entire batch if one file fails?

No. You should only correct and resend the failed files. Resubmitting successful invoices is unnecessary and may lead to duplicates.

 Do I need to generate the invoice through this API?

No. The API does not generate invoices. You must create the invoice document in your system and then upload it using this API.

© Octopia 2021 - 2026  —  Legal · API T&C · Octopia T&C · Illegal Content  —  Privacy Policy · Cookie management