Changelog & versioning

Versioning policy

The SDK follows strict SemVer: MAJOR.MINOR.PATCH. The git tag is the version — composer.json deliberately carries no version field.

• MAJOR — bumped on either trigger: the API's path version changes (/api/v1/ → /api/v2/), or the SDK makes its own breaking change with no API change at all (a renamed class or method, a changed return shape, a changed exception base class, a narrowed property type).
• MINOR — additive, backward-compatible: a new resource, a new optional named argument added after the existing ones, a new property on a model, a call that previously threw NotImplementedError starting to work.
• PATCH — fixes only, no contract change of any kind.

Two PHP-specific cases worth remembering: adding a named argument between existing ones is breaking (positional callers shift), and widening a property's type — even ?int → ?string — is breaking, however harmless it looks.

Anything to be removed is deprecated one minor ahead and documented here; nothing is ever removed in a minor or a patch.

Compatibility table

1.1.0 - 2026-10-05

Full parity with the current /api/v1 document. Every operation openapi declares is now exposed. All of it is additive: no existing class, method, property type or exception parent moves.

Added

• checkoutSessions->create() / ->read() — a checkout session collects one payment for up to ten billing periods, or for lines you price yourself. See Create checkout sessions. Adds CheckoutSession, CheckoutSessionDetail, CheckoutSeller, CreateCheckoutSessionParams and CheckoutItem, whose two named constructors — billingPeriod() and inline() — make the API's mutually exclusive item shapes unrepresentable rather than a 400 found at runtime. create is the SDK's one rate-limited endpoint (20/min); being a write, it is not retried for you.
• subscriptions->renew() — opens a checkout session for the next payment on an existing subscription, reusing its customer and billing period. See Manage subscriptions.
• subscriptions->read() and ->resume() — see Manage subscriptions.
• customers->create() and ->update(). create is an upsert: an email or phone already on the account is corrected and answered 200 rather than 201, which is what makes it safe to retry. Adds CustomerCreateParams and CustomerUpdateParams, which keep null (leave the field alone) distinct from '' (clear it). See Manage customers.
• $suqo->webhooks — the eight management operations: list, create, read, replace, update, delete, secret and testDelivery. See Handle webhooks. Adds WebhookEndpoint, WebhookEvent, SigningSecret, DetailResponse, WebhookParams and WebhookUpdateParams. Unrelated to Webhook::verify(), which still needs no client and no network — the two meet at secret(). list is the API's one unpaginated collection.
• Suqo\IntervalType — the day/week/month/year/one_time enum, with the same tolerant parse() as SubscriptionStatus. BillingPeriod::$intervalType stays a ?string: retyping a published property would be breaking.

Changed

• Documentation only: the "operations the SDK does not expose" gap on Not yet implemented is closed, and rate limiting there is updated to reflect the one real quota — checkoutSessions->create().

1.0.0 - 2026-09-14

The public surface is now stable. A commitment to hold it: from here, a breaking change requires a major version, and additions arrive as minors. Nothing in this release changes behaviour — 0.1.0 and 1.0.0 are the same code plus a documentation pass that closed four places where the reference had fallen behind the code, including Customer::$id (see Customers) and the auto-paging page cap (see Handle errors).

0.1.0 - 2026-09-14

Added

• SuqoClient — environment inferred from the API key prefix, with SuqoConfigError raised before any request on a malformed key or a conflicting environment.
• products->list() / ->autoPaging() — the seller's catalogue, including each plan's billing periods.
• subscriptions->list() / ->create() / ->cancel() / ->updateBillingCycle() / ->autoPaging().
• customers->list() / ->read() / ->autoPaging() — read-only at this point; create()/update() followed in 1.1.0.
• Webhook::verify() — HMAC-SHA256 signature verification with replay protection. No client, no API key, no network.
• Automatic retries for reads on a network failure, 429 or 5xx, with full-jitter backoff and Retry-After support. Writes are never retried, pending idempotency keys.
• Cancellation — an explicit token honoured before an attempt, mid-flight, during backoff and between pages.
• Pluggable HTTP layer: CurlHttpClient by default, Psr18HttpClient for any PSR-18 client, or your own HttpClientInterface.
• A full SuqoError hierarchy, a request id on every attempt, and configurable logging via $SUQO_LOG.

Security

• Transport::getAbsolute() refuses an absolute URL whose origin does not match the configured base URL — pagination follows server-supplied next links, and every request carries the API key, so an off-host link would have leaked it.
• A 3xx response is raised as a SuqoError carrying the redirect status, rather than being decoded as if its body were the payload — the SDK never follows redirects.
• autoPaging() stops after 10,000 pages rather than following a next chain forever.