INSR-110: Add USPS tracker registration API examples

[apeasypost]

Summary

Add canonical cURL request snippets and sample JSON responses for the USPS tracker registrations public API (INSR-110).

Python and Ruby request snippets are intentionally omitted until the endpoint ships in the official client libraries (curl + responses only, per repo convention).

Branch status: Already on latest master; CI green.

File changes

File	Change
official/docs/curl/current/usps-tracker-registrations/create.sh	Create registration cURL example
official/docs/curl/current/usps-tracker-registrations/list.sh	List registrations cURL example
official/docs/curl/current/usps-tracker-registrations/retrieve.sh	Retrieve registration cURL example
official/docs/responses/usps-tracker-registrations/usps-tracker-registrations-create.json	Sample create response
official/docs/responses/usps-tracker-registrations/usps-tracker-registrations-list.json	Sample list response
official/docs/responses/usps-tracker-registrations/usps-tracker-registrations-retrieve.json	Sample retrieve response

Release Test Plan

• Merge before or with easypost-web-docs #66 so the docs submodule pointer resolves.

Stack (INSR-110)

Repo	PR	Role
claims-service	#10	DBA schema (claims_usps_standalone_trackers)
claims-service	#9	API + monitoring sync; stops at ELIGIBLE (no standard USPS upload in phase 1)
easy_post	#626	Public API proxy + onboarding gate
easypost-web-backend	#86	Dashboard / external-apps proxy
easypost-web-app	#205	Dashboard UI
examples	#235	cURL + response samples
easypost-web-docs	#66	Public docs

Phase 1: Monitor BYO-label USPS tracking → ELIGIBLE / INELIGIBLE. Registrations do not enter the standard USPS claims upload pipeline; ELIGIBLE rows remain until a future standalone filing flow ships.

Jira: INSR-110

Related

• INSR-110
• easypost-web-docs #66
• easy_post #626

[Justin Hammond (Justintime50)]

We typically do not document non-native API requests for each language lib. When there are (not yet) supported endpoints, we've historically only added the curl snippet and response examples.

Are there plans to add support for this to the libs? I've not heard of this endpoint yet.

[apeasypost]

Thanks Justin Hammond (@Justintime50) — agreed. I dropped the Python and Ruby request snippets and kept curl + JSON response examples only, matching the pattern used for other endpoints that are not yet in the client libraries (e.g. DELETE /trackers).

Lib support: This is a new public API (POST/GET /v2/carrier_claims/usps_tracker_registrations) shipping with DATA-2184. None of the official client libraries expose it yet. Follow-up work would add a carrier_claims service namespace in each lib:

Repo	Pattern to follow
easypost-ruby	Claim service for CRUD + FedexRegistration for nested carrier_claims/... paths
easypost-python	ClaimService + CustomerPortalService nested URL pattern
easypost-node	ClaimService in src/services/
easypost-php	explicit path in service (like FedExRegistrationService)
easypost-java	ClaimService
easypost-csharp	ClaimService
easypost-go	flat methods on Client (see claim.go)

Endpoint constant: carrier_claims/usps_tracker_registrations. Methods: create, all/list, retrieve. Collection key: tracker_registrations.

We can add native SDK examples to this repo once those lib PRs land; until then docs will show curl only.

[Sam Guyette (sam-ep)]

LGTM -- curl and json samples match the public api

[apeasypost]

Copilot review

[Copilot]

🔵 Needs a closer look

Rename the response fixtures to the repository convention and add the missing has_more field.

Pull request overview

Adds cURL examples and sample JSON responses for USPS tracker registration create, list, and retrieve endpoints.

Changes:

• Added create, list, and retrieve cURL snippets.
• Added corresponding API response examples.
• Uses the curl-only convention pending official client-library support.

File summaries

File	Summary
official/docs/responses/usps-tracker-registrations/retrieve.json	Retrieve response; filename requires convention correction.
official/docs/responses/usps-tracker-registrations/list.json	List response; filename and pagination flag require correction.
official/docs/responses/usps-tracker-registrations/create.json	Create response; filename requires convention correction.
official/docs/curl/current/usps-tracker-registrations/retrieve.sh	Retrieve request example.
official/docs/curl/current/usps-tracker-registrations/list.sh	List request example.
official/docs/curl/current/usps-tracker-registrations/create.sh	Create request example.

Review details

Suppressed comments (4)

official/docs/responses/usps-tracker-registrations/create.json:1

• This response file's basename does not follow the repository's response convention: files under a resource directory are named <resource>-<action>.json (for example, official/docs/responses/refunds/refunds-create.json), and the response builder derives that name in tools/build_doc_json_responses/builder/snippets.py:99-110. As written, the docs consumer will not resolve this response alongside the new create.sh; rename it to usps-tracker-registrations-create.json.

{

official/docs/responses/usps-tracker-registrations/list.json:1

• This response file's basename does not follow the repository's response convention: files under a resource directory are named <resource>-<action>.json (for example, official/docs/responses/refunds/refunds-list.json), and the response builder derives that name in tools/build_doc_json_responses/builder/snippets.py:99-110. As written, the docs consumer will not resolve this response alongside the new list.sh; rename it to usps-tracker-registrations-list.json.

{

official/docs/responses/usps-tracker-registrations/list.json:17

• This list response omits the standard has_more pagination flag. The other paginated object-list fixtures include it (for example, official/docs/responses/refunds/refunds-list.json:15), and consumers need it to know whether another page is available. Add "has_more": false (or the actual value) after the array.

  ]
}

official/docs/responses/usps-tracker-registrations/retrieve.json:1

• This response file's basename does not follow the repository's response convention: files under a resource directory are named <resource>-<action>.json (for example, official/docs/responses/refunds/refunds-retrieve.json), and the response builder derives that name in tools/build_doc_json_responses/builder/snippets.py:99-110. As written, the docs consumer will not resolve this response alongside the new retrieve.sh; rename it to usps-tracker-registrations-retrieve.json.

{

• Files reviewed: 6/6 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[apeasypost]

Copilot review

[Copilot]

🟡 Changes recommended

Critical response-file naming issues must be fixed before approval.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 6/6 changed files
• Comments generated: 3
• Review effort level: Lite

[Copilot]

Copilot review

Addressed in e82befb: renamed response fixtures to usps-tracker-registrations-{create,list,retrieve}.json and added has_more to the list response.

[apeasypost]

Copilot review

[Copilot]

Copilot review

Re-ran final checks on the current branch state; no additional issues were found and no further changes are needed.

[Copilot]

🟢 Approval recommended

Only a minor pagination-convention nit was identified; there are no approval-blocking issues.

Review details

Suppressed comments (1)

official/docs/curl/current/usps-tracker-registrations/list.sh:1

• The list cURL examples in this repository consistently bound the result set with ?page_size=5 (for example, official/docs/curl/current/claims/list.sh:1 and official/docs/curl/current/trackers/list.sh:1). Please include the same query parameter here so this canonical example follows the repository's pagination convention and does not rely on the endpoint's default page size.

curl -X GET https://api.easypost.com/v2/carrier_claims/usps_tracker_registrations \

• Files reviewed: 6/6 changed files
• Comments generated: 0 new
• Review effort level: Lite