Support trial-period pre-fill on subscription create

[sandervanhooft]

Problem

The SubscriptionEndpoint::create() payload accepts redirectUrlSuccess, redirectUrlCanceled, and optional billingAddress, but has no way to pre-fill a trial period when creating a subscription. Yet Subscription::\$trialUntil and SubscriptionStatus::TRIAL already exist on the read side — so the read shape models trials but the write shape can't initiate them.

This blocks fluent from offering trial helpers (see vatly/vatly-fluent-php#66). Consumers building SaaS pricing pages with "14-day free trial" CTAs have no way to wire it through.

Surface change

Add a trialUntil (ISO-8601 timestamp) or trialDays (int) field on the subscription-create endpoint request payload. The endpoint docblock currently reads:

Pre-fill data (redirectUrlSuccess, redirectUrlCanceled, optional billingAddress).

Extending to:

Pre-fill data (redirectUrlSuccess, redirectUrlCanceled, optional billingAddress, optional trialUntil).

Precedent

Subscription::\$trialUntil and Subscription::isTrial() already exist — the read shape exists, the write shape doesn't.

Open question

Does Vatly's HTTP API accept a trial parameter on POST /subscriptions today? If yes, this is purely an api-php DTO/endpoint addition. If no, this is upstream-blocked on the API itself.

[sandervanhooft]

End-to-end verification while wiring fluent's trial helpers (vatly-fluent-php#66):

The Vatly API already accepts a per-product trial on checkout create — CreateCheckoutRequest validates products.*.trialDays (integer) and the checkout controller computes trialUntil = now + trialDays for subscription products. api-php's CheckoutEndpoint::create() posts the products array through unchanged, so products[].trialDays flows end-to-end today with no client change required.

fluent now wraps this via SubscriptionBuilder::withTrialDays() / withTrialEndsAt() (vatly/vatly-fluent-php#73).

Remaining (optional) scope for this issue:

• Document/type the field on the api-php side — e.g. note trialDays in the ProductData/checkout-create docblock so it's discoverable, since it's currently only validated server-side.
• A native trialEndsAt timestamp input (vs. whole-day trialDays) would let callers express sub-day / exact-moment trials. fluent currently converts an end-date to whole days client-side (rounding up). Low priority — flagging for completeness.