Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(warehouse_sources): add four more medusa endpoint tables (#123047)

Tom Owers14e2dcf32001
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md b/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md
index c352ab283d2a..db9c02320663 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md
@@ -7734,19 +7734,19 @@ Note: Read the vendor SDK's controller docs (32 controllers) and enumerated the
## Medusa — gaps
-Today (13): `Claims`, `CustomerGroups`, `Customers`, `DraftOrders`, `Exchanges`, `InventoryItems`, `Orders`, `PriceLists`, `Products`, `ProductVariants`, `Regions`, `Returns`, `StockLocations`
+Today (17): `Claims`, `CustomerGroups`, `Customers`, `DraftOrders`, `Exchanges`, `InventoryItems`, `Orders`, `Payments`, `PriceLists`, `ProductCategories`, `Products`, `ProductVariants`, `Promotions`, `Regions`, `Reservations`, `Returns`, `StockLocations`
Diffed against: <https://raw.githubusercontent.com/medusajs/medusa/develop/www/apps/api-reference/specs/admin/openapi.yaml>
- [x] `Stock locations (GET /admin/stock-locations)` — resolve location_id on returns and support stock analysis by warehouse (high). Added as `StockLocations`.
- [x] `Claims (GET /admin/claims)` — resolve claim_id on returns and analyze reasons for after-sale claims (high). Added as `Claims`.
- [x] `Exchanges (GET /admin/exchanges)` — resolve exchange_id on returns and measure replacement activity (high). Added as `Exchanges`.
-- [ ] `Payments (GET /admin/payments)` — track captured and refunded payments for revenue reconciliation (high)
+- [x] `Payments (GET /admin/payments)` — track captured and refunded payments for revenue reconciliation (high). Added as `Payments`.
- [x] `Inventory items (GET /admin/inventory-items)` — measure available, reserved, and stocked quantities, including nested location levels (high). Added as `InventoryItems` (full refresh: the list route has no timestamp filters).
-- [ ] `Reservations (GET /admin/reservations)` — analyze inventory commitments and their impact on available stock (medium)
-- [ ] `Promotions (GET /admin/promotions)` — compare discount rules with order revenue and promotional performance (medium)
+- [x] `Reservations (GET /admin/reservations)` — analyze inventory commitments and their impact on available stock (medium). Added as `Reservations`.
+- [x] `Promotions (GET /admin/promotions)` — compare discount rules with order revenue and promotional performance (medium). Added as `Promotions`.
- [ ] `Campaigns (GET /admin/campaigns)` — measure promotion budgets and campaign usage (medium)
-- [ ] `Product categories (GET /admin/product-categories)` — group catalog performance by category hierarchy (medium)
+- [x] `Product categories (GET /admin/product-categories)` — group catalog performance by category hierarchy (medium). Added as `ProductCategories`.
Note: Parsed the official v2 OpenAPI root and fetched referenced path files to verify GET methods. Checked official query defaults: products already embed types, collections, tags, and sales channels, so duplicate lookups are excluded. Inventory lists include location levels; no collection route exists for fulfillments. Excluded auth, keys, settings, and uploads; route availability depends on the deployed Medusa version.
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/medusa/canonical_descriptions.py b/products/warehouse_sources/backend/temporal/data_imports/sources/medusa/canonical_descriptions.py
index a844b91cd06e..cffae190cd52 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/medusa/canonical_descriptions.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/medusa/canonical_descriptions.py
@@ -187,4 +187,73 @@ CANONICAL_DESCRIPTIONS: CanonicalDescriptions = {
**_TIMESTAMPS,
},
},
+ "Reservations": {
+ "description": "A quantity of an inventory item held at a stock location, usually for an order line item.",
+ "docs_url": "https://docs.medusajs.com/api/admin#reservations",
+ "columns": {
+ "id": "Unique identifier of the reservation.",
+ "line_item_id": "ID of the line item the reservation is for.",
+ "location_id": "ID of the stock location the quantity is reserved from.",
+ "inventory_item_id": "ID of the reserved inventory item.",
+ "quantity": "Reserved quantity.",
+ "external_id": "ID of the reservation in an external system.",
+ "description": "Description of the reservation.",
+ "created_by": "ID of the user who created the reservation.",
+ "metadata": "Key-value pairs of custom data.",
+ **_TIMESTAMPS,
+ },
+ },
+ "Payments": {
+ "description": "A payment processed through a payment provider, with its authorized, captured, and refunded amounts.",
+ "docs_url": "https://docs.medusajs.com/api/admin#payments",
+ "columns": {
+ "id": "Unique identifier of the payment.",
+ "amount": "Amount of the payment.",
+ "currency_code": "Three-letter ISO currency code of the payment.",
+ "provider_id": "ID of the payment provider that processed the payment.",
+ "captured_at": "Date the payment was captured.",
+ "canceled_at": "Date the payment was canceled.",
+ "payment_collection_id": "ID of the payment collection the payment belongs to.",
+ "payment_session_id": "ID of the payment session the payment was created from.",
+ "metadata": "Key-value pairs of custom data.",
+ "captures": "Captures made against the payment.",
+ "refunds": "Refunds made against the payment.",
+ **_TIMESTAMPS,
+ },
+ },
+ "Promotions": {
+ "description": "A discount that applies to carts automatically or through a code, with its rules and usage.",
+ "docs_url": "https://docs.medusajs.com/api/admin#promotions",
+ "columns": {
+ "id": "Unique identifier of the promotion.",
+ "code": "Code customers enter to apply the promotion.",
+ "type": "Type of the promotion: standard or buyget.",
+ "status": "Status of the promotion.",
+ "is_automatic": "Whether the promotion applies to a cart automatically when it matches the rules.",
+ "is_tax_inclusive": "Whether the promotion applies after tax is calculated.",
+ "campaign_id": "ID of the campaign the promotion belongs to.",
+ "application_method": "How the discount is applied: its type, target, value, and allocation.",
+ "rules": "Conditions a cart must match for the promotion to apply.",
+ "limit": "Maximum number of times the promotion can be used.",
+ "used": "Number of times the promotion has been used.",
+ "metadata": "Key-value pairs of custom data.",
+ **_TIMESTAMPS,
+ },
+ },
+ "ProductCategories": {
+ "description": "A category in the product catalog, which can nest under a parent category.",
+ "docs_url": "https://docs.medusajs.com/api/admin#product-categories",
+ "columns": {
+ "id": "Unique identifier of the product category.",
+ "name": "Name of the category.",
+ "description": "Description of the category.",
+ "handle": "Unique handle of the category.",
+ "parent_category_id": "ID of the parent category.",
+ "rank": "Rank of the category among its sibling categories.",
+ "is_active": "Whether the category is active. Inactive categories are hidden in the storefront.",
+ "is_internal": "Whether the category is internal. Internal categories are only visible to admin users.",
+ "metadata": "Key-value pairs of custom data.",
+ **_TIMESTAMPS,
+ },
+ },
}
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/medusa/medusa.py b/products/warehouse_sources/backend/temporal/data_imports/sources/medusa/medusa.py
index 03eaf71c0ce0..e8f83ec14ddd 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/medusa/medusa.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/medusa/medusa.py
@@ -237,15 +237,19 @@ def get_resource(
raise ValueError(f"Medusa endpoint '{config.name}' has no incremental field '{incremental_field_name}'")
cursor_field = config.incremental_field_name
+ params: dict[str, Any] = {
+ # Explicit ascending sort: it keeps offset page boundaries stable while rows are
+ # inserted mid-sync, and on incremental runs it matches sort_mode="asc" so the
+ # watermark checkpoints correctly. `created_at` is immutable, so a full refresh
+ # sorts on it; incremental runs sort on the cursor field itself.
+ "order": cursor_field,
+ }
+ if config.extra_fields:
+ params["fields"] = ",".join(f"+{field}" for field in config.extra_fields)
+
endpoint: Endpoint = {
"path": f"/admin{config.path}",
- "params": {
- # Explicit ascending sort: it keeps offset page boundaries stable while rows are
- # inserted mid-sync, and on incremental runs it matches sort_mode="asc" so the
- # watermark checkpoints correctly. `created_at` is immutable, so a full refresh
- # sorts on it; incremental runs sort on the cursor field itself.
- "order": cursor_field,
- },
+ "params": params,
"paginator": MedusaPaginator(),
"data_selector": config.data_selector,
}
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/medusa/settings.py b/products/warehouse_sources/backend/temporal/data_imports/sources/medusa/settings.py
index 1a7681ab1faf..5897f2daf9fb 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/medusa/settings.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/medusa/settings.py
@@ -58,6 +58,9 @@ class MedusaEndpointConfig:
# incremental runs. None means the list route documents no timestamp filters, so the
# endpoint is full refresh only.
incremental_field_name: str | None = "updated_at"
+ # Columns to add to the route's default response fields via `fields=+a,+b`. Needed where the
+ # defaults omit the timestamps the cursor and the partition key read.
+ extra_fields: tuple[str, ...] = ()
@property
def incremental_fields(self) -> list[IncrementalField]:
@@ -92,6 +95,17 @@ MEDUSA_ENDPOINTS: dict[str, MedusaEndpointConfig] = {
"InventoryItems": MedusaEndpointConfig(
name="InventoryItems", path="/inventory-items", data_selector="inventory_items", incremental_field_name=None
),
+ "Reservations": MedusaEndpointConfig(name="Reservations", path="/reservations", data_selector="reservations"),
+ "Payments": MedusaEndpointConfig(
+ name="Payments",
+ path="/payments",
+ data_selector="payments",
+ extra_fields=("created_at", "updated_at", "canceled_at", "provider_id", "metadata"),
+ ),
+ "Promotions": MedusaEndpointConfig(name="Promotions", path="/promotions", data_selector="promotions"),
+ "ProductCategories": MedusaEndpointConfig(
+ name="ProductCategories", path="/product-categories", data_selector="product_categories"
+ ),
}
ENDPOINTS = tuple(MEDUSA_ENDPOINTS)
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/medusa/tests/test_medusa.py b/products/warehouse_sources/backend/temporal/data_imports/sources/medusa/tests/test_medusa.py
index 9c31e3c36179..5f9c3ee8f536 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/medusa/tests/test_medusa.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/medusa/tests/test_medusa.py
@@ -107,6 +107,22 @@ class TestMedusaTransport:
assert endpoint["incremental"]["start_param"] == "updated_at[$gte]"
assert endpoint["incremental"]["cursor_path"] == "updated_at"
+ @pytest.mark.parametrize(
+ ("endpoint", "expected_fields"),
+ [
+ ("Orders", None),
+ # The payments list route omits its timestamps by default; without them the cursor and
+ # the partition key have nothing to read.
+ ("Payments", "+created_at,+updated_at,+canceled_at,+provider_id,+metadata"),
+ ],
+ )
+ def test_requests_extra_fields_only_where_defaults_omit_them(
+ self, endpoint: str, expected_fields: str | None
+ ) -> None:
+ resource = cast(dict[str, Any], get_resource(MEDUSA_ENDPOINTS[endpoint], should_use_incremental_field=False))
+
+ assert resource["endpoint"]["params"].get("fields") == expected_fields
+
@pytest.mark.parametrize("endpoint", ["PriceLists", "InventoryItems"])
def test_incremental_rejected_for_endpoint_without_timestamp_filters(self, endpoint: str) -> None:
with pytest.raises(ValueError, match="does not support incremental"):