October 2022 SP-API Release Announcement
In October 2022 Amazon launched a schemas folder in the public selling‑partner‑api‑models GitHub repo, adding version‑tagged JSON schema files (e.g., v2022‑10‑01) for every SP‑API report such as GET_FLAT_FILE_ORDER_REPORT_ and GET_AMAZON_FULFILLED_SHIPMENTS_DATA_. The same announcement introduced Shipping API v2, with matching schemas to be added to the same repository.
Overview
In October 2022 Amazon added a complete set of JSON schema files for every Selling Partner API (SP‑API) report and placed them in the public selling‑partner‑api‑models GitHub repository. The schemas act as a machine‑readable contract that defines the exact structure of each report, making validation, testing, and future updates far more reliable. Sellers who automate report ingestion should track the repository to keep their data pipelines aligned with Amazon’s evolving specifications.
Key Points
- Schema repository launch — A new schemas directory was introduced in the selling‑partner‑api‑models GitHub repo, containing a JSON schema for each SP‑API report available as of October 2022.
- Live change notifications — By starring or watching the repository, developers receive GitHub alerts whenever a schema is added, altered, or deprecated, preventing unexpected breakages.
- Version‑controlled definitions — Every schema file carries a version tag such as v2022‑10‑01 and includes a $schema reference, enabling tools like ajv or jsonschema to enforce strict compliance during ingestion.
- Broad report coverage — The initial commit covers core reports such as GET_FLAT_FILE_ORDER_REPORT_, GET_AMAZON_FULFILLED_SHIPMENTS_DATA_, and GET_VENDOR_INVENTORY_REPORT_; future commits will extend coverage to newer reports like GET_SALES_AND_TRAFFIC_REPORT_.
- Shipping API v2 preview — At the same time Amazon announced Shipping API v2, which adds endpoints for rate quoting and label generation, and promised matching JSON schemas in the same repository.
How the JSON Schema System Works
- Repository sync — Developers clone or pull the selling‑partner‑api‑models repo; the schemas folder mirrors the exact hierarchy of the SP‑API report catalog. Example: A nightly Python job runs
git pulland copiesGET_FLAT_FILE_ORDER_REPORT_.jsoninto a local validation folder used by downstream services. - Schema selection — When a seller requests a report, the SP‑API response includes a reportDocumentId and a reportType value. The integration matches the reportType to the corresponding schema file in the repo. : A Node.js microservice receives a request and loads for subsequent checks.
Analysis & Recommendations
Why This Matters
The schemas give developers a machine‑readable contract, enabling automated validation with tools like ajv and preventing ETL crashes when Amazon adds or renames fields. Early GitHub alerts let sellers update mappings before data loss, reducing manual debugging and downtime.
Key Takeaways
- A new schemas directory was added to the selling‑partner‑api‑models GitHub repo in October 2022, providing a JSON schema for each SP‑API report.
- Each schema file carries a version tag such as v2022‑10‑01 and includes a $schema reference for strict validation with ajv or jsonschema.
- The initial commit covers core reports like GET_FLAT_FILE_ORDER_REPORT_, GET_AMAZON_FULFILLED_SHIPMENTS_DATA_, and GET_VENDOR_INVENTORY_REPORT_.
- Shipping API v2 was announced alongside the schema launch, with its endpoints (e.g., GET /shipping/v2/rates) slated to have matching JSON schemas i...
Recommended Actions
- →Watch or star the GitHub repository at https://github.com/amzn/selling-partner-api-models to receive real‑time change alerts.
- →Add a daily git pull or GitHub API fetch step in your CI/CD pipeline to pull the latest schema files before running validations.
- →Integrate an ajv (or jsonschema) validation step into your report ingestion workflow, loading the schema that matches the reportType returned by th...
Comments
Join the discussion
Log in or create an account to share your thoughts on this update.
No comments yet. Be the first to share your thoughts!