Newsletter
Seller information
  • Home
  • Seller information

Introduction

Seller.jpg

Last update :

Toolbox / Tips

Octopia exposes a set of endpoints enabling a seller or integrator to retrieve all key information about their seller account, legal identity, operational preferences, and performance indicators.

This API is not used to update seller data — it is read-only and provides visibility into seller status, delivery setup, subscriptions, legal structure, and account health.

It is particularly relevant:

  • During onboarding audits and validations.

  • To feed internal seller dashboards.

  • For marketplaces wanting to cross-check seller eligibility or compliance.

  • To allow sellers to understand their current operational state and fulfilment configuration.

This API is typically used right after authentication, either to populate the seller home page or to run periodic compliance checks.

Key States & Attributes

Attribute

Description

seller_state

Overall status of the seller: Activated, Deactivated, PutOnNotice.

seller_sub_state

Operational mode: ActiveSeller, Holidays, BannedSeller.

subscription_step

Onboarding phase: FirstConnection, BankReferences, ValidatingSubscription, Finished.

auto_accept_order

Boolean flag: does the seller accept orders automatically?

fulfillment_profile_id

Associated logistics configuration.

seller_legal_information

Embedded object with SIRET, company name, legal form, share capital, etc.

indicators

SLA performance, order acceptance rate, claims, refunds, etc.

subscriptions

Historic and current subscriptions to sales channels.

Seller Workflow

seller.png

Data availability period

No expiration or date filtering is mentioned. The data returned is real-time and reflects the current state of the seller.

Retrieve Seller Full Profile

Prerequisites

  • SellerId must be passed as header.

This endpoint returns the complete seller profile including personal, legal, logistic, and configuration details. It is the primary endpoint to get the current state of a seller account.

Typical use cases:

  • Display seller info in back-office.

  • Audit legal and fiscal details.

  • Check onboarding status and current operational status.

Functional Rules

  • No query parameters required.

  • The object includes nested hyperlinks (href) to related data (addresses, delivery modes…).

  • Some fields may be null if not configured yet (e.g., logo_url).

  • The seller state and sub-state help determine whether the account is active or under restriction.

Endpoint to use

Important notes

  • Onboarding validation: Use subscription_step to check if the seller has completed the onboarding.

  • Legal verification: Use seller_legal_information to extract company registration data (SIRET, EORI, share capital).

  • Multi-channel linking: subscription and delivery_modes fields are links — call those endpoints separately if needed.

Retrieve Seller Addresses

This endpoint returns the full list of addresses associated with the seller: legal address, warehouse, return point, etc.

It is particularly used to:

  • Feed logistics or billing flows.

  • Display or cross-check delivery and legal address in seller profiles.

Functional Rules

  • Address list may include several types (e.g., billing, return).

  • Returned addresses contain standard fields: street, zip_code, city, country, civility, etc.

  • Does not support filters or pagination.

Endpoint to use

Important notes

  • Multiple addresses: Always iterate on the list; some sellers may have return warehouses distinct from their legal location.

  • Granularity: appartment_number, building, and instructions fields may be critical for home deliveries.

  • Civility compliance: Fields like first_name, last_name, and civility are needed for labeling and customs documentation.

Retrieve Seller Delivery Modes

This endpoint returns the list of delivery modes configured by the seller for their offers.

It supports frontend and logistics tooling by helping:

  • Build delivery method selectors.

  • Validate if express or heavy product delivery is enabled.

Functional Rules

  • Each delivery mode includes:

    • code: short code like THD, EHD, etc.

    • name: human-readable name.

    • delivery_delay: in business days.

    • is_express_delivery, more_than30_kg_product: boolean flags.

  • No query params or filtering options.

Endpoint to use

Important notes

  • Offer compatibility: These delivery modes are typically used in offer creation flows — verify they are reflected in product packages.

  • Heavy product flag: Some channels may block more_than30_kg_product = true if no compatible carrier is set.

  • Express options: Not all sellers enable express delivery — use is_express_delivery flag to inform UI or eligibility logic.

Retrieve Seller Subscriptions

This endpoint returns the list of subscriptions associated with the seller across sales channels.

Useful for:

  • Checking if seller is subscribed and actively selling.

  • Displaying past and current subscription states.

  • Troubleshooting subscription rejections.

Functional Rules

  • Response is a list of subscription objects with:

    • status, state, action, reason_action

    • acceptation_date, subscription_request_date, etc.

  • Supports multi-channel, multi-state scenarios.

  • Seller may have several historical subscriptions per sales channel.

Endpoint to use

Important notes

  • Sales channel onboarding: Use state and status fields to validate if the seller is active on each sales channel.

  • Audit purposes: reason_action_complement explains why a subscription was rejected or suspended.

  • Currency control: offer_submission_currency and seller_payment_currency may differ depending on the channel.

Retrieve Seller Performance Indicators

This endpoint retrieves SLA indicators used by Octopia to monitor seller performance.

These KPIs are essential to:

  • Monitor compliance with seller obligations.

  • Prevent suspension or penalties.

  • Display SLA metrics in back office dashboards.

Functional Rules

  • Returns five key SLA objects:

    • order_acceptation, product_shipping, deadline_compliance, order_claims, order_refunds

  • Each includes:

    • value_d30, value_d60, value_d365 (rolling periods)

    • compliant_d30, treshold, treshold_type

Endpoint to use

Important notes

  • Only available for Cdiscount sale channel

  • SLA compliance: compliant_d30 shows current risk of penalty; use it in seller dashboard alerts.

  • Value granularity: Compare short-term (30 days) vs long-term (365 days) metrics to evaluate trends.

  • Auto-check exclusion: Some sellers may be temporarily excluded from computation (auto_check_exclusion = true).

Retrieve List of Supported Carriers

This endpoint returns all supported carrier codes with strong tracking performance and the associated parameters required for integration.

Functional Rules

  • Carrier object includes:

    • code: internal reference.

    • label: display name.

    • additionalParametersRequired: e.g., tracking account number.

Endpoint to use

Important notes

  • Mandatory carrier code: When sending a tracking update, this carrier code must match.

  • Dynamic fields: Some carriers require additional parameters — always validate additionalParametersRequired before integration.

  • Scope of list: Only includes carriers with high reliability for tracking retrieval (not a full postal carrier list).

FAQ

 How can I verify if my seller account is active and allowed to sell?

You should check the values returned by seller_state and seller_sub_state in the /sellers endpoint:

  • seller_state = Activated means your account is enabled globally.

  • seller_sub_state = ActiveSeller confirms you’re in normal operating mode.
    If PutOnNotice or BannedSeller appear, your account is under restriction.

 I want to know if I have completed the onboarding process. How do I check this?

Use the subscription_step field from the /sellers response. If it’s set to Finished, your onboarding is fully complete. Any other value means your account is still under validation.

 How can I retrieve all my warehouse or return addresses?

Call /sellers/addresses. This will return all configured addresses, including optional fields like instructions, building, or relay_id.

 What are SLA indicators and how are they calculated?

SLA indicators are performance metrics used by Octopia to monitor your service quality:

  • order_acceptation, product_shipping, order_refunds, etc.
    Each indicator shows values over 30, 60, and 365 days. If compliant_d30 = false, you may be at risk of a warning or restriction.

 Can I retrieve which marketplaces I am subscribed to?

Yes. Use /sellers/subscriptions. It lists your historical and current subscriptions per sales channel, with status (Subscribed, Unsubscribed) and action history (Subscribe, Cancel, Suspend, etc.).

 What does auto_accept_order = false mean in my seller profile?

This means your system requires manual acceptance of new orders. You might miss SLA commitments if orders are not accepted quickly. Enabling auto-acceptance is often recommended.

 I changed my address or email but it doesn’t update — why?

This API is read-only. Any update to seller data must go through the Octopia Seller Portal or your onboarding contact. The /sellers API only reflects the current state in the system.