Skip to main content

​
Introduction

The Movements API enables tracking of all inventory changes for products. Every stock change is recorded as a movement with complete audit information.

​
Movement Types

The system supports three types of inventory movements:

ENTRY

Stock received from suppliers or new inventory

EXIT

Stock sold or removed from inventory (uses FIFO costing)

ADJUSTMENT

Manual corrections or adjustments to inventory

​
Movement Object

All movements share the following structure: 
class Movement:
    id: str                    # Unique identifier
    product_id: str            # Product reference
    supplier_id: str | None    # Supplier reference (for ENTRY)
    customer_id: str | None    # Customer reference (for EXIT)
    type: str                  # ENTRY, EXIT, or ADJUSTMENT
    quantity: int              # Number of units
    unit_price: float | None   # Price per unit for this transaction
    total_price: float | None  # quantity * unit_price
    total_cost: float | None   # FIFO calculated cost (for EXIT)
    reference_id: str | None   # Batch ID, Order ID, etc.
    notes: str | None          # Additional information
    created_at: datetime       # Timestamp
    created_by: str            # User who created the movement

​
FIFO Costing

For EXIT movements, the system automatically calculates the cost of goods sold (COGS) using the First-In-First-Out (FIFO) method:
  1. Batch Tracking: Each ENTRY creates a batch with its unit cost
  2. Exit Processing: EXIT movements deduct from the oldest batches first
  3. Cost Calculation: The total_cost field contains the actual COGS
  4. Profit Analysis: Compare total_price (revenue) vs total_cost (COGS)

​
Role Requirements

​
create_sale
Role
Required roles: admin, gestor
​
list_movements
Role
Required roles: admin, gestor, consultor

​
Base URL

/api/v1/movements

Build docs developers (and LLMs) love

Get started for freeTalk to us