Skip to main content

List subscriptions

GET 

https://euwest.api.elasticpath.com/v2/subscriptions/subscriptions

Retrieves a list of all subscriptions.

Filtering

This endpoint supports filtering. For the general syntax, see Filtering.

The following attributes and operators are supported.

OperatorAttributeDescription
eqaccount_id, name, email, external_refEquals. Checks if the values of two operands are equal. If they are, the condition is true.

Including Resources

You can use the include parameter to include the following resources with this endpoint.

ResourceRequiredDescription
pricing_options, plansOptionalRetrieves all pricing options and plans associated with a subscription.
plansOptionalRetrieves all plans associated with a subscription.
pricing_optionsOptionalRetrieves all pricing options associated with a subscription.

See Characteristics of Include Parameter.

Request

Query Parameters

    page[offset] int64

    Possible values: >= 0 and <= 10000

    The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the page length store setting is used.

    page[limit] int64

    Possible values: >= 0

    The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the page length store setting is used.

    include string[]

    Possible values: [plans, pricing_options]

    filter string

Responses

Success. A list of subscriptions is returned.

Schema
    data Subscription[]
  • Array [
  • idUUID (string)

    The unique identifier.

    Example: 11111111-2222-3333-4444-555555555555
    typeSubscriptionType (string)required

    Possible values: [subscription]

    Example: subscription
    attributes SubscriptionAttributesrequired
    external_refExternalRef (string)

    A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.

    Possible values: <= 2048 characters

    Example: abc123
    account_idUUID (string)required

    The unique identifier.

    Example: 11111111-2222-3333-4444-555555555555
    address_idUUID (string)

    The unique identifier.

    Example: 11111111-2222-3333-4444-555555555555
    offering Offeringrequired
    idUUID (string)

    The unique identifier.

    Example: 11111111-2222-3333-4444-555555555555
    typeSubscriptionOfferingType (string)required

    Possible values: [subscription_offering]

    Example: subscription_offering
    attributes OfferingResponseAttributes
    external_refExternalRef (string)

    A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.

    Possible values: <= 2048 characters

    Example: abc123
    namestringrequired

    The name of the offering.

    Possible values: >= 3 characters and <= 1024 characters

    Example: Magazine
    descriptionstring

    The offering description to display to customers.

    Possible values: <= 1024 characters

    Example: A lovely magazine that is published every month.
    updated_atstringrequired

    The date and time a resource was updated.

    Example: 2017-01-10T11:41:19.244842Z
    created_atstringrequired

    The date and time a resource was created.

    Example: 2017-01-10T11:41:19.244842Z
    relationships Relationships

    Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.

    property name* Relationship
    anyOf
    meta OfferingMetarequired
    external_plan_refsstring<string>[]required
    ownerstring<string>required

    The owner of a resource, either store or organization.

    Example: store
    timestamps Timestampsrequired
    updated_atstringrequired

    The date and time a resource was updated.

    Example: 2017-01-10T11:41:19.244842Z
    created_atstringrequired

    The date and time a resource was created.

    Example: 2017-01-10T11:41:19.244842Z
    pricing_option_idUUID (string)required

    The unique identifier.

    Example: 11111111-2222-3333-4444-555555555555
    plan_idUUID (string)required

    The unique identifier.

    Example: 11111111-2222-3333-4444-555555555555
    currencyCurrencyIdentifier (string)required

    The three-letter ISO currency code in uppercase.

    Possible values: <= 1024 characters

    Example: USD
    payment_authority object
    type stringrequired

    Possible values: [elastic_path_payments_stripe, authorize_net]

    relationships Relationships

    Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.

    property name* Relationship
    anyOf
    meta SubscriptionMetarequired
    ownerstring<string>required

    The owner of a resource, either store or organization.

    Example: store
    timestamps SubscriptionTimestamps
    updated_atstringrequired

    The date and time a resource was updated.

    Example: 2017-01-10T11:41:19.244842Z
    created_atstringrequired

    The date and time a resource was created.

    Example: 2017-01-10T11:41:19.244842Z
    canceled_atstring

    The date and time a subscription was cancelled.

    Example: 2017-01-10T11:41:19.244842Z
    paused_atstring

    The date and time a subscription was paused.

    Example: 2017-01-10T11:41:19.244842Z
    resumed_atstring

    The date and time a subscription was resumed.

    Example: 2017-01-10T11:41:19.244842Z
    end_datestring

    The date and time a subscription will end.

    Example: 2017-01-10T11:41:19.244842Z
    go_live_afterstring

    The date and time a subscription will go live and become active.

    Example: 2017-01-10T11:41:19.244842Z
    go_livestring

    The date and time a subscription was released from the pending state and made active.

    Example: 2017-01-10T11:41:19.244842Z
    statusStatus (string)required

    The status of a subscription, either active or inactive.

    Possible values: [active, inactive]

    Example: active
    state SubscriptionState
    idUUID (string)

    The unique identifier.

    Example: 11111111-2222-3333-4444-555555555555
    typeSubscriptionStateType (string)required

    This represents the type of resource object being returned. Always subscription_state.

    Possible values: [subscription_state]

    Example: subscription_state
    attributes SubscriptionStateAttributesrequired
    actionSubscriptionStateAction (string)required

    The subscription lifecycle is the states that a subscription can go through when a customer subscribes to a service or a plan.

    A subscription can have the following states; canceled, paused, or resumed.

    See Managing the subscription lifecycle.

    Possible values: [cancel, pause, resume, pending]

    Example: cancel
    meta StateMetarequired
    created_atstringrequired

    The date and time a resource was created.

    Example: 2017-01-10T11:41:19.244842Z
    manual_paymentsManualPayments (boolean)required

    When configured to true, no payment gateway is used and a pending payment is created. See External Payments.

    Default value: false
    Example: false
    first_invoice_prepaidbooleanrequired

    Indicates that the first billing period of this subscription was paid for outside of the subscriptions service.

    Example: false
    canceledbooleanrequired

    Whether a subscription is canceled or not.

    Example: true
    pausedbooleanrequired

    Whether a subscription is paused or not.

    Example: true
    closedbooleanrequired

    Whether a subscription is closed or not.

    Example: true
    suspendedbooleanrequired

    Whether a subscription is suspended or not.

    Example: false
    pendingbooleanrequired

    Whether a subscription is pending activation or not.

    Example: false
    invoice_afterstringrequired

    The time when the subscription becomes eligible for a new invoice. The next invoice will be generated at the next billing run after this point.

    Example: 2017-01-10T11:41:19.244842Z
  • ]
  • included SubscriptionIncludes
    plans OfferingPlan[]
  • Array [
  • idUUID (string)

    The unique identifier.

    Example: 11111111-2222-3333-4444-555555555555
    typeSubscriptionOfferingPlanType (string)required

    Possible values: [subscription_offering_plan]

    Example: subscription_offering_plan
    attributes OfferingPlanResponseAttributes
    external_refExternalRef (string)

    A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.

    Possible values: <= 2048 characters

    Example: abc123
    namestringrequired

    The name of the plan.

    Possible values: >= 3 characters and <= 1024 characters

    Example: Magazine
    descriptionstring

    The plan or service description to display to customers.

    Possible values: <= 1024 characters

    Example: A lovely magazine that is published every month.
    skustring

    A stock keeping unit for the plan, if appropriate.

    Possible values: <= 1024 characters

    Example: MAGAZINE1
    main_imagestring<uri>

    A URL from which an image or file for the plan can be fetched. You can either upload your images and files to Commerce using the Commerce Files API or you can use your own content delivery network. If you are using the Commerce Files API, use Create a File to upload your file and return an HREF link in the response. An extensive range of media and file extensions are supported.

    Possible values: <= 1024 characters

    Example: https://magazine.com/cover.jpg
    price Price
    property name* object

    The base price.

    amountinteger<int64>required

    The value as a whole number of the currency's smallest subdivision.

    Example: 100
    includes_taxboolean

    Indicates whether the amount includes any taxes.

    Example: true
    price_units object

    The timeframe during which the plan price is applicable. For example, for a streaming service, the price is $12.99 and the unit is months and the amount is 1. In other words, the streaming service is available for $12.99 a month. You may want to specify a unit price if you have many plans that all have different prices. Rather than having to create separate pricing options for each plan, you can specify the timeframe during which the plan price is applicable and then create one pricing option that determines the billing frequency for those plans.

    unitstringrequired

    A unit of time.

    Possible values: [day, month]

    Example: day
    amountintegerrequired

    The number of days or months the period covers.

    Possible values: >= 1

    Example: 7
    updated_atstringrequired

    The date and time a resource was updated.

    Example: 2017-01-10T11:41:19.244842Z
    created_atstringrequired

    The date and time a resource was created.

    Example: 2017-01-10T11:41:19.244842Z
    feature_configurations objectrequired

    A map of configurations indicating which features are available for the plan

    property name* FeaturePlanConfiguration
    typerequired

    Possible values: [access, promotion, usage]

    object
    relationships Relationships

    Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.

    property name* Relationship
    anyOf
    meta PlanMetarequired
    prices object

    A list of plan prices for each of its pricing options.

    property name* OfferingPlanPriceForPricingOption
    price Price
    property name* object

    The base price.

    amountinteger<int64>required

    The value as a whole number of the currency's smallest subdivision.

    Example: 100
    includes_taxboolean

    Indicates whether the amount includes any taxes.

    Example: true
    display_price DisplayPrice
    without_tax PriceFormatting
    amountinteger<int64>required

    The unformatted amount for the objects.

    Example: 100
    currencystring<string>required

    The three-letter ISO currency code in uppercase, associated with a price.

    Example: USD
    formattedstring<string>required

    The formatted amount for the objects.

    Example: $1.00
    with_tax PriceFormatting
    amountinteger<int64>required

    The unformatted amount for the objects.

    Example: 100
    currencystring<string>required

    The three-letter ISO currency code in uppercase, associated with a price.

    Example: USD
    formattedstring<string>required

    The formatted amount for the objects.

    Example: $1.00
    display_price DisplayPrice
    without_tax PriceFormatting
    amountinteger<int64>required

    The unformatted amount for the objects.

    Example: 100
    currencystring<string>required

    The three-letter ISO currency code in uppercase, associated with a price.

    Example: USD
    formattedstring<string>required

    The formatted amount for the objects.

    Example: $1.00
    with_tax PriceFormatting
    amountinteger<int64>required

    The unformatted amount for the objects.

    Example: 100
    currencystring<string>required

    The three-letter ISO currency code in uppercase, associated with a price.

    Example: USD
    formattedstring<string>required

    The formatted amount for the objects.

    Example: $1.00
    ownerstring<string>required

    The owner of a resource, either store or organization.

    Example: store
    timestamps Timestampsrequired
    updated_atstringrequired

    The date and time a resource was updated.

    Example: 2017-01-10T11:41:19.244842Z
    created_atstringrequired

    The date and time a resource was created.

    Example: 2017-01-10T11:41:19.244842Z
    active_planActivePlan (boolean)

    Whether a plan is active on a subscription using that offering. The active_plan attribute is null if a plan is not active in a subscription.

    Example: true
  • ]
  • pricing_options OfferingPricingOption[]
  • Array [
  • idUUID (string)

    The unique identifier.

    Example: 11111111-2222-3333-4444-555555555555
    typeSubscriptionOfferingPricingOptionType (string)required

    Possible values: [subscription_offering_pricing_option]

    Example: subscription_offering_pricing_option
    attributes PricingOptionResponseAttributes
    external_refExternalRef (string)

    A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.

    Possible values: <= 2048 characters

    Example: abc123
    namestringrequired

    A name for the pricing option.

    Possible values: >= 3 characters and <= 1024 characters

    Example: Monthly
    descriptionstring

    The pricing option description to display to customers.

    Possible values: <= 1024 characters

    Example: A monthly subscription.
    billing_interval_typestringrequired

    The unit of time that billing intervals are measured.

    Possible values: [day, week, month, year]

    Example: month
    billing_frequencyintegerrequired

    The number of intervals between issuing bills.

    Possible values: >= 1

    Example: 1
    trial_periodinteger

    The number of intervals from the start of the subscription before billing starts. Used with billing_interval_type. For example, if billing_interval_type is months, and trial_period is 1, the trial period is 1 month.

    Possible values: >= 0

    Example: 7
    plan_lengthintegerrequired

    The number of intervals that the subscription runs for.

    Possible values: >= 1

    Example: 12
    end_behaviorstringrequired

    Enables you to specify recurring payments. If end_behavior is roll, customers pay regularly and repeatedly. If end_behavior is close, customers pay a total amount in a limited number of partial payments.

    Possible values: [close, roll]

    Example: close
    can_pausebooleanrequired

    The subscriber can pause a subscription.

    Example: false
    can_resumebooleanrequired

    The subscriber can resume a paused subscription.

    Example: false
    can_cancelbooleanrequired

    The subscriber can cancel a subscription.

    Example: false
    base_price_percentagenumber<double>

    A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify 10, a 10% discount is applied to the total value of all repeat plans in an offering.

    Possible values: >= 0 and <= 100

    Example: 90
    fixed_price Price
    property name* object

    The base price.

    amountinteger<int64>required

    The value as a whole number of the currency's smallest subdivision.

    Example: 100
    includes_taxboolean

    Indicates whether the amount includes any taxes.

    Example: true
    updated_atstringrequired

    The date and time a resource was updated.

    Example: 2017-01-10T11:41:19.244842Z
    created_atstringrequired

    The date and time a resource was created.

    Example: 2017-01-10T11:41:19.244842Z
    relationships Relationships

    Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.

    property name* Relationship
    anyOf
    meta OfferingPricingOptionMetarequired
    prices object

    The price of each plan within the offering that this pricing option may be applied to.

    property name* OfferingPricingOptionPriceForPlan
    price Price
    property name* object

    The base price.

    amountinteger<int64>required

    The value as a whole number of the currency's smallest subdivision.

    Example: 100
    includes_taxboolean

    Indicates whether the amount includes any taxes.

    Example: true
    display_price DisplayPrice
    without_tax PriceFormatting
    amountinteger<int64>required

    The unformatted amount for the objects.

    Example: 100
    currencystring<string>required

    The three-letter ISO currency code in uppercase, associated with a price.

    Example: USD
    formattedstring<string>required

    The formatted amount for the objects.

    Example: $1.00
    with_tax PriceFormatting
    amountinteger<int64>required

    The unformatted amount for the objects.

    Example: 100
    currencystring<string>required

    The three-letter ISO currency code in uppercase, associated with a price.

    Example: USD
    formattedstring<string>required

    The formatted amount for the objects.

    Example: $1.00
    price Price
    property name* object

    The base price.

    amountinteger<int64>required

    The value as a whole number of the currency's smallest subdivision.

    Example: 100
    includes_taxboolean

    Indicates whether the amount includes any taxes.

    Example: true
    display_price DisplayPrice
    without_tax PriceFormatting
    amountinteger<int64>required

    The unformatted amount for the objects.

    Example: 100
    currencystring<string>required

    The three-letter ISO currency code in uppercase, associated with a price.

    Example: USD
    formattedstring<string>required

    The formatted amount for the objects.

    Example: $1.00
    with_tax PriceFormatting
    amountinteger<int64>required

    The unformatted amount for the objects.

    Example: 100
    currencystring<string>required

    The three-letter ISO currency code in uppercase, associated with a price.

    Example: USD
    formattedstring<string>required

    The formatted amount for the objects.

    Example: $1.00
    active_pricing_optionActivePricingOption (boolean)

    Whether a pricing option is active on a subscription using that offering. The active_pricing_option attribute is null if a pricing option is not active in a subscription.

    Example: true
    ownerstring<string>required

    The owner of a resource, either store or organization.

    Example: store
    timestamps Timestampsrequired
    updated_atstringrequired

    The date and time a resource was updated.

    Example: 2017-01-10T11:41:19.244842Z
    created_atstringrequired

    The date and time a resource was created.

    Example: 2017-01-10T11:41:19.244842Z
  • ]
  • links object
    property name* Link
    anyOf
    stringnullable
    Example: http://example.com/articles/1/comments

Authorization: http

name: BearerTokentype: httpscheme: bearer
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "https://euwest.api.elasticpath.com/v2/subscriptions/subscriptions");
request.Headers.Add("Accept", "application/json");
request.Headers.Add("Authorization", "Bearer <token>");
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
Request Collapse all
Base URL
https://euwest.api.elasticpath.com/v2
Auth
Parameters
— query
— query
— query
— query
ResponseClear

Click the Send API Request button above and see the response here!