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): add easypost usps_claims table (#119234)

Tom Owers63647c168bd8
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 e01773f8e3df..c5d36fba2071 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
@@ -4120,6 +4120,7 @@ Diffed against: <https://docs.easypost.com/docs/carrier-accounts>
- [x] `GET /v2/users/children` — child user roster for platforms that break spend and volume down by sub-account (medium)
- [x] `GET /v2/reports/{type}` — generated shipment/payment_log/tracker/refund report objects, useful for reconciling billing (low)
- [x] `GET /v2/carrier_types` — lookup of available carrier types and their credential fields (low)
+- [x] `GET /v2/carrier_claims/usps_claims` — USPS lost/damaged claims on EasyPost-purchased labels, separate from insurance `/claims` (medium) — added as `usps_claims`, full refresh only: the list takes no time filter and claims carry no `created_at`
Note: Diffed against the 45 /docs/\* pages in docs.easypost.com/sitemap.xml and read the endpoint tables on each candidate page. Orders, parcels, customs_infos and customs_items have create/retrieve only - no index endpoint - so they cannot back a warehouse table and were excluded rather than reported as gaps.
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/easypost/canonical_descriptions.py b/products/warehouse_sources/backend/temporal/data_imports/sources/easypost/canonical_descriptions.py
index 73dde5097899..cdcd0a97619f 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/easypost/canonical_descriptions.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/easypost/canonical_descriptions.py
@@ -112,6 +112,28 @@ CANONICAL_DESCRIPTIONS: CanonicalDescriptions = {
"updated_at": "When the claim was last updated.",
},
},
+ "usps_claims": {
+ "description": "A USPS lost or damaged claim on a USPS label bought through EasyPost, with its filing status and amounts. Separate from insurance claims.",
+ "docs_url": "https://docs.easypost.com/docs/carrier-claims/usps-claims",
+ "columns": {
+ "id": 'Unique identifier for the USPS claim, begins with "usc_".',
+ "object": 'The string "UspsClaim".',
+ "mode": 'Whether the claim is in "test" or "production" mode.',
+ "tracking_code": "USPS tracking code of the EasyPost-purchased label.",
+ "shipment_id": "Identifier of the EasyPost shipment the claim is for.",
+ "claim_type": "Type of claim: lost or damaged.",
+ "status": "Public status of the claim: action_required, ready_to_file, submitted, approved, denied, expired, or failed.",
+ "product_value": "Declared goods value in USD.",
+ "claimable_amount": "Amount EasyPost files with USPS.",
+ "description": "Merchandise description stored on the claim.",
+ "recipient": "Recipient name and company from the shipment.",
+ "shipment_date": "Ship date used to compute the claim expiry and the USPS filing window.",
+ "filing_window_closes_at": "Last day EasyPost can file the claim with USPS (60 days from the ship date).",
+ "missing": "Fields still required before the claim can be filed (e.g. product_value).",
+ "submitted_at": "When the claim was filed with USPS. Null until it is filed.",
+ "approved_at": "When USPS paid the claim. Null unless the status is approved.",
+ },
+ },
"carrier_accounts": {
"description": "A carrier account holding your credentials with a carrier. The carrier_account_id on shipments and rates resolves to a row here.",
"docs_url": "https://docs.easypost.com/docs/carrier-accounts",
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/easypost/settings.py b/products/warehouse_sources/backend/temporal/data_imports/sources/easypost/settings.py
index eb5de0302727..22d2e80e7024 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/easypost/settings.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/easypost/settings.py
@@ -182,6 +182,17 @@ EASYPOST_ENDPOINTS: dict[str, EasypostEndpointConfig] = {
path="/trackers",
incremental_fields=_created_at_fields(),
),
+ "usps_claims": EasypostEndpointConfig(
+ name="usps_claims",
+ path="/carrier_claims/usps_claims",
+ # USPS lost/damaged claims, separate from insurance /claims. A claim carries no
+ # `created_at` and the list takes no time filter, so full refresh only. Accounts not
+ # enrolled in USPS claims get a 422, so it stays unselected by default.
+ incremental_fields=[],
+ partition_key=None,
+ should_sync_default=False,
+ supports_start_datetime=False,
+ ),
}
ENDPOINTS = tuple(EASYPOST_ENDPOINTS.keys())
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/easypost/tests/test_easypost.py b/products/warehouse_sources/backend/temporal/data_imports/sources/easypost/tests/test_easypost.py
index 4ee20fbc2764..b3687c4e12f2 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/easypost/tests/test_easypost.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/easypost/tests/test_easypost.py
@@ -150,6 +150,22 @@ class TestChildUsers:
assert result.rows == [{"id": "user_1", "name": "Child", "children": [{"id": "user_2"}]}]
+class TestUspsClaims:
+ def test_paginates_the_nested_carrier_claims_path(self) -> None:
+ result = _driver().run(
+ "usps_claims",
+ [
+ ScriptedResponse(json={"usps_claims": [{"id": "usc_1"}, {"id": "usc_2"}], "has_more": True}),
+ ScriptedResponse(json={"usps_claims": [{"id": "usc_3"}], "has_more": False}),
+ ],
+ )
+ assert result.raised is None
+ assert [row["id"] for row in result.rows] == ["usc_1", "usc_2", "usc_3"]
+ assert result.paths == ["/v2/carrier_claims/usps_claims"] * 2
+ assert result.params("before_id") == [None, "usc_2"]
+ assert result.params("start_datetime") == [None, None]
+
+
REPORT_TYPES = EASYPOST_ENDPOINTS["reports"].path_values
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/easypost/tests/test_easypost_source.py b/products/warehouse_sources/backend/temporal/data_imports/sources/easypost/tests/test_easypost_source.py
index 56d07d452c67..6ce9c7110e85 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/easypost/tests/test_easypost_source.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/easypost/tests/test_easypost_source.py
@@ -28,7 +28,9 @@ class TestGetSchemas:
assert [f["field"] for f in schema.incremental_fields] == ["created_at"]
assert schema.supports_append is True
- @parameterized.expand([("carrier_accounts",), ("carriers",), ("carrier_types",), ("child_users",), ("reports",)])
+ @parameterized.expand(
+ [("carrier_accounts",), ("carriers",), ("carrier_types",), ("child_users",), ("reports",), ("usps_claims",)]
+ )
def test_lookup_schemas_are_full_refresh_only(self, endpoint: str) -> None:
# These endpoints expose no cursor at all, so offering incremental or append would let a
# user pick a sync type that silently re-reads the whole collection every run.
@@ -39,7 +41,7 @@ class TestGetSchemas:
assert schema.supports_append is False
@parameterized.expand(
- [("carrier_accounts",), ("end_shippers",), ("carrier_types",), ("child_users",), ("reports",)]
+ [("carrier_accounts",), ("end_shippers",), ("carrier_types",), ("child_users",), ("reports",), ("usps_claims",)]
)
def test_restricted_endpoints_are_not_selected_by_default(self, endpoint: str) -> None:
# EasyPost gates both endpoints: /carrier_accounts rejects test keys, and the EndShipper