Skip to content

FBA Articles Endpoints

Base path: /api/v1/multi + router prefix /fba/articles → full base: /api/v1/multi/fba/articles

Summary: Endpoints to sync and manage FBA-specific article data, process Amazon ledger reports (inbound receipts), perform profit/price recalculations using SP-API fee estimates, and export updated price bounds to Sellerlogic.

Auth: All endpoints require a valid Bearer JWT (global auth middleware). Not public.

Rate limiting: Subject to global rate limiter (250 requests / 60s).

Primary models referenced: RepricerArticle, FBADetails, FBACountryPricing, FBABoundDetails (see implementation in backend/service_multi-repricer/app/models/repricer_articles.py and Pydantic schemas in schemas/repricer_articles.py).

External services used:

  • Sellerlogic helper functions: get_amazon_products, get_amazon_products_stock, get_amazon_products_package_dimensions, batch_reprice_items (from api.v1.endpoints.sellerlogic).
  • Amazon SP-API helpers: get_ledger_report, calculate_optimal_price_with_api, get_live_exchange_rates (from services.amazon.spapi_client).
  • WebSocket notifications via notifications.notify_clients().

Endpoints

  • POST /sync/{sku}
  • Path: POST /api/v1/multi/fba/articles/sync/{sku}
  • Path param: sku (string). Use all to sync all FBA records.
  • Description: Starts a background sync that fetches FBA product data from Sellerlogic (products, stock, package dimensions), merges into local FBADetails and RepricerArticle records, and triggers ledger processing when credentials are available. Multiple seller SKUs per ASIN: the first listing keeps repricer_articles.sku = ASIN; each additional merchant SKU gets a sibling article (sku = seller_sku) with its own fba_details row (asin set) so both can be recalculated and exported.
  • Response: 200 — { "message": "Syncing started in background." }

  • Notes: Executes heavy DB work in a threadpool; not blocking the ASGI loop. Emits websocket task status notifications (type=task_status, source=fba).

  • POST /sync-ledger

  • Path: POST /api/v1/multi/fba/articles/sync-ledger
  • Query params (optional): asin (string), start_time (ISO-8601), end_time (ISO-8601)
  • Description: Starts background processing to download the Amazon ledger report (Receipts) for the provided time window (defaults to previous day) and updates RepricerArticle.last_inbound_date for affected ASINs.
  • Response: 200 — { "message": "Ledger sync started in background." }

  • Notes: Requires active Amazon credentials for service multi-repricer or will log an error and abort.

  • GET /debug-ledger-report

  • Path: GET /api/v1/multi/fba/articles/debug-ledger-report
  • Query params: asin (optional)
  • Description: Debug-only endpoint that downloads the raw ledger report (tab-separated values) and returns it as a file attachment for inspection.

  • Response: 200 — text/tab-separated-values attachment

  • POST /recalculate/{sku}

  • Path: POST /api/v1/multi/fba/articles/recalculate/{sku}
  • Path param: sku (string). Use all to recalculate all FBA-backed articles.
  • Description: Starts a background recalculation job that:
    • Loads matching RepricerArticle and FBADetails rows
    • UVP: always profit-only — pins min/max from min_uvp / max_uvp, refreshes profit/margin
    • Penner/renner (article_type): profit-only even with force_min_max; heals targets from pricing_history
    • Wave/manual (use_min_max_rules == False) without force_min_max: profit-only on existing bounds
    • Rules-on, or untyped wave with force_min_max=True (buy-price after type clear): full SP-API via calculate_optimal_price_with_api for stored marketplaces
    • Applies rounding rules and populates FBACountryPricing entries with fee breakdowns, profit and margin
    • Updates FBADetails.status (e.g., ACTIVE, UPDATE_NEEDED, ERROR) and expected_profit
  • Response: 200 — { "message": "Recalculation started in background." }

  • Notes: Emits progress via websocket task_status messages. Missing brutto_buy_price → ERROR. force_min_max=True includes OOS rows and rewrites wave bounds; UVP stays profit-only.

  • POST /export-updates

  • Path: POST /api/v1/multi/fba/articles/export-updates
  • Query/body: optional sku (path used in code path), or call with no SKU to export all UPDATE_NEEDED items
  • Description: Collects articles marked UPDATE_NEEDED (or a single SKU) and batches repricing updates to Sellerlogic using batch_reprice_items per region (FBA flows).
  • Response: 200 — { "message": "Export task started in background." }
  • Notes: On success the FBA detail status is set to ACTIVE for exported SKUs.

Examples

  • Sync a single SKU (background):
curl -X POST "http://localhost:8000/api/v1/multi/fba/articles/sync/B07SKU123" \
    -H "Authorization: Bearer <TOKEN>"
  • Sync all FBA-backed SKUs:
curl -X POST "http://localhost:8000/api/v1/multi/fba/articles/sync/all" \
    -H "Authorization: Bearer <TOKEN>"
  • Recalculate profits/prices for all FBA-backed SKUs:
curl -X POST "http://localhost:8000/api/v1/multi/fba/articles/recalculate/all" \
    -H "Authorization: Bearer <TOKEN>"
  • Trigger ledger sync for a specific ASIN and time window:
curl -X POST "http://localhost:8000/api/v1/multi/fba/articles/sync-ledger?asin=B07SKU123&start_time=2026-05-20T00:00:00&end_time=2026-05-20T23:59:59" \
    -H "Authorization: Bearer <TOKEN>"
  • Download debug ledger report (write to file):
curl -X GET "http://localhost:8000/api/v1/multi/fba/articles/debug-ledger-report?asin=B07SKU123" \
    -H "Authorization: Bearer <TOKEN>" -o ledger_report.tsv

Implementation notes

  • File: backend/service_multi-repricer/app/api/v1/endpoints/fba_articles.py — key functions: sync_fba, process_sync_fba_skus, sync_ledger, process_ledger_report, recalculate, recalculate_articles, export_updates, process_export_updates.
  • Uses SessionLocal() for DB sessions in background threads; background work is executed in a threadpool via starlette.concurrency.run_in_threadpool to avoid blocking the ASGI event loop.
  • When new base articles are created during sync, the code calls repricer_articles.sync_buy_prices to keep buy prices synchronized.
  • Rules-on (since 1.10.4): every recalc runs full SP-API min/max — no profit-only shortcut when targets already exist.
  • Wave + force_min_max: buy-price / package force (incl. penner/renner) rewrites bounds via SP-API and includes OOS. Nightly main pass does not pass force.
  • UVP: always profit-only; never rewritten by force.
  • The rules-on / force path calls calculate_optimal_price_with_api (SP-API + local cost aggregator). Ensure active Amazon credentials exist for operations that require SP-API access; otherwise ledger sync and fee-based recalculations will fail or return errors.
  • Long-running batches periodically db.commit() per-article to release locks and allow other operations.

Caveats & operational guidance

  • These endpoints can be CPU and IO intensive — run during maintenance windows or staggered schedules for large catalogs.
  • Ensure that amazon_credentials and Sellerlogic credentials are configured and active in the DB before running ledger-based or export operations.
  • Monitor websocket notifications (type=task_status, source=fba) for real-time progress in the dashboard.
  • Endpoint implementation: backend/service_multi-repricer/app/api/v1/endpoints/fba_articles.py
  • Amazon SP-API helpers: backend/service_multi-repricer/app/services/amazon/spapi_client.py
  • Sellerlogic helpers: backend/service_multi-repricer/app/api/v1/endpoints/sellerlogic.py

Generated: detailed reference for fba_articles endpoints in service_multi-repricer.