Subscriptions

Query subscriptions

Changed on

Use when listing or searching subscriptions (e.g. admin view or customer subscription list). Returns a paginated list; supports filtering by customer, plan, status.

post/subscriptions/search

Request

  • Base URL
    https://us.api.flexprice.io/v1
  • URL
    https://us.api.flexprice.io/v1/subscriptions/search
  • Auth
    API key in header x-api-key

Request body

active_atstring date-time

ActiveAt filters subscriptions that are active at the given time

billing_cadenceTypesBillingCadence[]

BillingCadence filters by billing cadence

billing_periodTypesBillingPeriod[]

BillingPeriod filters by billing period

customer_idstring

CustomerID filters by customer ID

customer_idsstring[]

CustomerIDs filters by customer IDs

effective_date_for_updatestring

EffectiveDateForUpdate selects subscriptions that need a billing-period pass on or before this time: current_period_end <= date OR (cancel_at IS NOT NULL AND cancel_at <= date). When nil, period/cancel cutoff logic is not applied by this field (see TimeRangeFilter for legacy period-end filtering).

end_timestring date-time
expandstring
external_customer_idstring

ExternalCustomerID filters by external customer ID

invoicing_customer_idsstring[]

InvoicingCustomerIDs filters by invoicing customer ID

limitinteger
offsetinteger
order'asc' | 'desc'
parent_subscription_idsstring[]

ParentSubscriptionIDs filters by parent subscription IDs

plan_idstring

PlanID filters by plan ID

start_timestring date-time
status'published' | 'deleted' | 'archived'
subscription_idsstring[]
subscription_statusTypesSubscriptionStatus[]

SubscriptionStatus filters by subscription status

subscription_typeTypesSubscriptionType[]

SubscriptionType filters by subscription type

trial_end_due_ltestring date-time

TrialEndDueLTE, when set, restricts to subscriptions with trial_end not nil and trial_end <= trial_end_due_lte. Use with subscription_status trialing for trial-end cron processing.

with_coupon_associationsboolean

WithCouponAssociations eager-loads coupon associations and their coupons.

Kept separate from WithLineItems because the coupon_associations table has no index leading with subscription_id, so Ent's edge load degrades to a full table scan. Only set it when the response actually surfaces the associations; the service layer back-fills it from expand="coupon_associations".

with_line_itemsboolean

WithLineItems includes line items in the response.

Deprecated: use expand="subscription_line_items" instead. Retained for backwards compatibility and for internal callers that need to force-disable line item loading (set to false). The service layer ORs this with the expand check before invoking the repository.

Response

OK

Changes

  • 3798546cc4a3Revision changes
    • warning

      added the new END_OF_MONTH enum value to the // response property for the response status

    • warning

      added the new END_OF_NEXT_MONTH enum value to the // response property for the response status

  • 80eb0267435cRevision changes
    • info

      added the optional property /// to the response with the status