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.
  • 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
    • Determines the applicable margin rule (via get_margin_rule_for_price)
    • Calls calculate_optimal_price_with_api (SP-API fee estimates + local costs) to compute min/max target prices per marketplace
    • 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; handles use_min_max_rules flag (profit-only recalculation) and robustly marks items with missing buy_price as errors.

  • 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.
  • The recalculation flow 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.