Versioning & changelog

Versioning policy

The version is in the path: /v1/. Within a version, changes are additive only:

• new endpoints, new optional request fields, new response fields, new event types and new enum values may appear at any time — write clients that ignore unknown fields and tolerate unknown enum values;
• existing fields never change meaning or type, and are never removed.

Breaking changes ship as a new version (/v2/). The previous version keeps working for at least 12 months, during which its responses carry Deprecation and Sunset headers with the retirement date.

Webhook payloads carry api_version so receivers can tell which shape they are getting.

Changelog

2026-09 — v1 launch

• Account (read-only): profile.
• Designs (read-only): list with retail_price (shop price) and purchase_price (what your account pays Merchable per unit, ex tax); detail adds the purchase_breakdown, the product's quantity_tiers, and every variant's option names, purchase price and stock status inline.
• Shops (read-only): list, detail, designs, collections.
• Orders: list with filters and cursor pagination, detail, events, shipments, quote, place (idempotent), cancel; per-order notification suppression.
• Shipping: cost estimate per method for a set of items and a destination.
• Webhooks: per-order webhook_url/webhook_secret, signed deliveries with retries.