StripeKit - Find Subscription By Metadata

`$kit->subscriptions->findByMetadata()`

Finds a single active-ish subscription by matching a metadata key/value pair. Useful when you've tagged a subscription with your own identifier (for example a team_id) and want to look it up later without storing the Stripe subscription ID yourself.

Signature

Parameters

Field	Type	Description
`key`	`string`	The metadata key to match, for example `'team_id'`.
`value`	`string`	The metadata value to match.

Example request

Example response

Same shape as retrieve() if a match is found, otherwise null.

Errors

This method does not throw for a missing match, it returns null instead. It can still throw StripeOperationError for a genuine Stripe-side failure while searching.

Notes

Backed by Stripe's search API, which indexes with a short delay after a subscription's metadata changes. Don't rely on this method finding a subscription immediately after you write the matching metadata; if you need a strict read-after-write guarantee, look the subscription up through your own storage adapter instead.

Returns only the first match. If more than one subscription could share the same key/value pair, use a more specific value, or a combination you control uniquely, such as prefixing with your own namespace.

Find By Metadata

$kit->subscriptions->findByMetadata()#

Signature#

Parameters#

Example request#

Example response#

Errors#