List subscriptions

GET 
/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.

Operator	Attribute	Description
eq	account_id, name, email, external_ref	Equals. 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.

Resource	Required	Description
plans, products	Optional	Retrieves all plans and products associated with a subscription.
products	Optional	Retrieves all products associated with a subscription.
plans	Optional	Retrieves all plans associated with a subscription.

See Characteristics of Include Parameter.

Request

Query Parameters

page[offset] int64

Possible values: <= 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

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
filter string

Responses

200

Success. A list of subscriptions is returned.

application/json

Schema

Schema

data Subscription[]
Array [
id UUID (string)
The unique identifier.
type SubscriptionType (string)required
Possible values: [subscription]
attributes SubscriptionAttributesrequired
external_ref ExternalRef (string)
Possible values: <= 2048 characters
A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.
account_id UUID (string)required
The unique identifier.
address_id UUID (string)
The unique identifier.
offering Offeringrequired
id UUID (string)
The unique identifier.
type SubscriptionOfferingType (string)required
Possible values: [subscription_offering]
attributes OfferingAttributesrequired
external_ref ExternalRef (string)
Possible values: <= 2048 characters
A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.
name stringrequired
Possible values: >= 3 characters and <= 1024 characters
The name of the offering.
description string
Possible values: <= 1024 characters
The offering description to display to customers.
updated_at stringrequired
The date and time a resource was updated.
created_at stringrequired
The date and time a resource was created.
relationships Relationships
Relationships are established between different subscription entities. For example, a product and a plan are related to an offering, as both are attached to it.
anyOf
title
meta OfferingMetarequired
external_product_refs string[]required
owner stringrequired
The owner of a resource, either store or organization.
timestamps Timestampsrequired
updated_at stringrequired
The date and time a resource was updated.
created_at stringrequired
The date and time a resource was created.
plan_id UUID (string)required
The unique identifier.
currency CurrencyIdentifier (string)required
Possible values: <= 1024 characters
The three-letter ISO currency code in uppercase.
payment_authority object
oneOf
PaymentAuthorityStripe
type stringrequired
Possible values: [elastic_path_payments_stripe]
The name of the payment gateway facilitating the secure transmission of payment data.
customer_id string
Possible values: >= 3 characters and <= 1024 characters
The unique identifier for a customer.
card_id string
Possible values: >= 3 characters and <= 1024 characters
The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the card_id and customer_id attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See Card declines.
PaymentAuthorityAuthorizeNet
type stringrequired
Possible values: [authorize_net]
The name of the payment gateway facilitating the secure transmission of payment data.
payment_profile_id string
Possible values: >= 3 characters and <= 1024 characters
The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription.
customer_profile_id string
Possible values: >= 3 characters and <= 1024 characters
The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription.
relationships Relationships
Relationships are established between different subscription entities. For example, a product and a plan are related to an offering, as both are attached to it.
anyOf
title
meta SubscriptionMetarequired
owner stringrequired
The owner of a resource, either store or organization.
timestamps Timestampsrequired
updated_at stringrequired
The date and time a resource was updated.
created_at stringrequired
The date and time a resource was created.
canceled_at string
The date and time a subscription was cancelled.
paused_at string
The date and time a subscription was paused.
resumed_at string
The date and time a subscription was resumed.
end_date string
The date and time a subscription will end.
go_live_after string
The date and time a subscription will go live and become active.
go_live string
The date and time a subscription was released from the pending state and made active.
status Status (string)required
Possible values: [active, inactive]
The status of a subscription, either active or inactive.
state SubscriptionState
id UUID (string)
The unique identifier.
type SubscriptionStateType (string)required
Possible values: [subscription_state]
This represents the type of resource object being returned. Always subscription_state.
attributes SubscriptionStateAttributesrequired
action SubscriptionStateAction (string)required
Possible values: [cancel, pause, resume, pending]
The subscription lifecycle is the states that a subscription can go through when a customer subscribes to a service or a product.
A subscription can have the following states; canceled, paused, or resumed.
See Managing the subscription lifecycle.
meta StateMetarequired
created_at stringrequired
The date and time a resource was created.
manual_payments ManualPayments (boolean)required
When configured to true, no payment gateway is used and a pending payment is created. See External Payments.
canceled booleanrequired
Whether a subscription is canceled or not.
paused booleanrequired
Whether a subscription is paused or not.
closed booleanrequired
Whether a subscription is closed or not.
suspended booleanrequired
Whether a subscription is suspended or not.
pending booleanrequired
Whether a subscription is pending activation or not.
invoice_after stringrequired
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.
]
included SubscriptionIncludes
products OfferingProduct[]
Array [
id UUID (string)
The unique identifier.
type SubscriptionOfferingProductType (string)required
Possible values: [subscription_offering_product]
attributes ProductAttributesrequired
external_ref ExternalRef (string)
Possible values: <= 2048 characters
A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.
name stringrequired
Possible values: >= 3 characters and <= 1024 characters
The name of the product.
description string
Possible values: <= 1024 characters
The product or service description to display to customers.
sku string
Possible values: <= 1024 characters
A stock keeping unit for the product, if appropriate.
main_image uri
Possible values: <= 1024 characters
A URL from which an image or file for the product 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.
price Price
property name* object
The base price.
amount int64required
The value as a whole number of the currency's smallest subdivision.
includes_tax boolean
Indicates whether the amount includes any taxes.
price_units object
The timeframe during which the product 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 products that all have different prices. Rather than having to create separate plans for each product, you can specify the timeframe during which the product price is applicable and then create one plan that determines the billing frequency for those products.
unit stringrequired
Possible values: [day, month]
A unit of time.
amount integerrequired
Possible values: >= 1
The number of days or months the period covers.
updated_at stringrequired
The date and time a resource was updated.
created_at stringrequired
The date and time a resource was created.
relationships Relationships
Relationships are established between different subscription entities. For example, a product and a plan are related to an offering, as both are attached to it.
anyOf
title
meta ProductMetarequired
display_price DisplayPrice
without_tax PriceFormatting
amount int64required
The unformatted amount for the objects.
currency stringrequired
The three-letter ISO currency code in uppercase, associated with a price.
formatted stringrequired
The formatted amount for the objects.
with_tax PriceFormatting
amount int64required
The unformatted amount for the objects.
currency stringrequired
The three-letter ISO currency code in uppercase, associated with a price.
formatted stringrequired
The formatted amount for the objects.
owner stringrequired
The owner of a resource, either store or organization.
timestamps Timestampsrequired
updated_at stringrequired
The date and time a resource was updated.
created_at stringrequired
The date and time a resource was created.
]
plans OfferingPlan[]
Array [
id UUID (string)
The unique identifier.
type SubscriptionOfferingPlanType (string)required
Possible values: [subscription_offering_plan]
attributes PlanAttributesrequired
external_ref ExternalRef (string)
Possible values: <= 2048 characters
A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.
name stringrequired
Possible values: >= 3 characters and <= 1024 characters
A name for the plan.
description string
Possible values: <= 1024 characters
The plan description to display to customers.
billing_interval_type stringrequired
Possible values: [day, week, month, year]
The unit of time that billing intervals are measured.
billing_frequency integerrequired
Possible values: >= 1
The number of intervals between issuing bills.
trial_period integer
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.
plan_length integerrequired
Possible values: >= 1
The number of intervals that the subscription runs for.
end_behavior stringrequired
Possible values: [close, roll]
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.
can_pause booleanrequired
The subscriber can pause a subscription.
can_resume booleanrequired
The subscriber can resume a paused subscription.
can_cancel booleanrequired
The subscriber can cancel a subscription.
base_price_percentage double
Possible values: <= 100
A percentage discount on the total cost of any products within an offering. For example, you can configure a percentage that equates the cost of a plan to the total value of all products 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 products in an offering.
fixed_price Price
property name* object
The base price.
amount int64required
The value as a whole number of the currency's smallest subdivision.
includes_tax boolean
Indicates whether the amount includes any taxes.
updated_at stringrequired
The date and time a resource was updated.
created_at stringrequired
The date and time a resource was created.
relationships Relationships
Relationships are established between different subscription entities. For example, a product and a plan are related to an offering, as both are attached to it.
anyOf
title
meta OfferingPlanMetarequired
price Price
property name* object
The base price.
amount int64required
The value as a whole number of the currency's smallest subdivision.
includes_tax boolean
Indicates whether the amount includes any taxes.
display_price DisplayPrice
without_tax PriceFormatting
amount int64required
The unformatted amount for the objects.
currency stringrequired
The three-letter ISO currency code in uppercase, associated with a price.
formatted stringrequired
The formatted amount for the objects.
with_tax PriceFormatting
amount int64required
The unformatted amount for the objects.
currency stringrequired
The three-letter ISO currency code in uppercase, associated with a price.
formatted stringrequired
The formatted amount for the objects.
active_plan ActivePlan (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.
owner stringrequired
The owner of a resource, either store or organization.
timestamps Timestampsrequired
updated_at stringrequired
The date and time a resource was updated.
created_at stringrequired
The date and time a resource was created.
]
links object
anyOf
title

Example (from schema)

{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "type": "subscription",
      "attributes": {
        "external_ref": "abc123",
        "account_id": "00000000-0000-0000-0000-000000000000",
        "address_id": "00000000-0000-0000-0000-000000000000",
        "offering": {
          "id": "00000000-0000-0000-0000-000000000000",
          "type": "subscription_offering",
          "attributes": {
            "external_ref": "abc123",
            "name": "Magazine",
            "description": "A lovely magazine that is published every month.",
            "updated_at": "2017-01-10T11:41:19.244842Z",
            "created_at": "2017-01-10T11:41:19.244842Z"
          },
          "relationships": {
            "plans": {
              "links": {
                "related": "/offerings/:offering-id/plans",
                "self": "/offerings/:offering-id"
              },
              "data": {
                "type": "offering-plan",
                "id": "625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"
              }
            }
          },
          "meta": {
            "external_product_refs": [
              "97dddc65-eabd-45d8-b45b-2ece5cfc8c50"
            ],
            "owner": "store",
            "timestamps": {
              "updated_at": "2017-01-10T11:41:19.244842Z",
              "created_at": "2017-01-10T11:41:19.244842Z"
            }
          }
        },
        "plan_id": "00000000-0000-0000-0000-000000000000",
        "currency": "USD",
        "payment_authority": {}
      },
      "relationships": {
        "plans": {
          "links": {
            "related": "/offerings/:offering-id/plans",
            "self": "/offerings/:offering-id"
          },
          "data": {
            "type": "offering-plan",
            "id": "625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"
          }
        }
      },
      "meta": {
        "owner": "store",
        "timestamps": {
          "updated_at": "2017-01-10T11:41:19.244842Z",
          "created_at": "2017-01-10T11:41:19.244842Z",
          "canceled_at": "2017-01-10T11:41:19.244842Z",
          "paused_at": "2017-01-10T11:41:19.244842Z",
          "resumed_at": "2017-01-10T11:41:19.244842Z",
          "end_date": "2017-01-10T11:41:19.244842Z",
          "go_live_after": "2017-01-10T11:41:19.244842Z",
          "go_live": "2017-01-10T11:41:19.244842Z"
        },
        "status": "active",
        "state": {
          "id": "00000000-0000-0000-0000-000000000000",
          "type": "subscription_state",
          "attributes": {
            "action": "cancel"
          },
          "meta": {
            "created_at": "2017-01-10T11:41:19.244842Z"
          }
        },
        "manual_payments": false,
        "canceled": true,
        "paused": true,
        "closed": true,
        "suspended": false,
        "pending": false,
        "invoice_after": "2017-01-10T11:41:19.244842Z"
      }
    }
  ],
  "included": {
    "products": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "type": "subscription_offering_product",
        "attributes": {
          "external_ref": "abc123",
          "name": "Magazine",
          "description": "A lovely magazine that is published every month.",
          "sku": "MAGAZINE1",
          "main_image": "https://magazine.com/cover.jpg",
          "price": {
            "USD": {
              "amount": 100,
              "includes_tax": false
            },
            "GBP": {
              "amount": 90,
              "includes_tax": true
            }
          },
          "price_units": {
            "unit": "day",
            "amount": 7
          },
          "updated_at": "2017-01-10T11:41:19.244842Z",
          "created_at": "2017-01-10T11:41:19.244842Z"
        },
        "relationships": {
          "plans": {
            "links": {
              "related": "/offerings/:offering-id/plans",
              "self": "/offerings/:offering-id"
            },
            "data": {
              "type": "offering-plan",
              "id": "625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"
            }
          }
        },
        "meta": {
          "display_price": {
            "without_tax": {
              "amount": 100,
              "currency": "USD",
              "formatted": "$1.00"
            },
            "with_tax": {
              "amount": 110,
              "currency": "USD",
              "formatted": "$1.10"
            }
          },
          "owner": "store",
          "timestamps": {
            "updated_at": "2017-01-10T11:41:19.244842Z",
            "created_at": "2017-01-10T11:41:19.244842Z"
          }
        }
      }
    ],
    "plans": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "type": "subscription_offering_plan",
        "attributes": {
          "external_ref": "abc123",
          "name": "Monthly",
          "description": "A monthly subscription.",
          "billing_interval_type": "month",
          "billing_frequency": 1,
          "trial_period": 7,
          "plan_length": 12,
          "end_behavior": "close",
          "can_pause": false,
          "can_resume": false,
          "can_cancel": false,
          "base_price_percentage": 90,
          "fixed_price": {
            "USD": {
              "amount": 100,
              "includes_tax": false
            },
            "GBP": {
              "amount": 90,
              "includes_tax": true
            }
          },
          "updated_at": "2017-01-10T11:41:19.244842Z",
          "created_at": "2017-01-10T11:41:19.244842Z"
        },
        "relationships": {
          "plans": {
            "links": {
              "related": "/offerings/:offering-id/plans",
              "self": "/offerings/:offering-id"
            },
            "data": {
              "type": "offering-plan",
              "id": "625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"
            }
          }
        },
        "meta": {
          "price": {
            "USD": {
              "amount": 100,
              "includes_tax": false
            },
            "GBP": {
              "amount": 90,
              "includes_tax": true
            }
          },
          "display_price": {
            "without_tax": {
              "amount": 100,
              "currency": "USD",
              "formatted": "$1.00"
            },
            "with_tax": {
              "amount": 110,
              "currency": "USD",
              "formatted": "$1.10"
            }
          },
          "active_plan": true,
          "owner": "store",
          "timestamps": {
            "updated_at": "2017-01-10T11:41:19.244842Z",
            "created_at": "2017-01-10T11:41:19.244842Z"
          }
        }
      }
    ]
  },
  "links": {}
}

400

Bad request. The request failed validation.

application/json

Schema

Schema

errors Error[]required
Array [
status stringrequired
The HTTP response code of the error.
title stringrequired
A brief summary of the error.
detail string
Optional additional detail about the error.
meta object
Additional supporting meta data for the error.
]

Example (from schema)

{
  "errors": [
    {
      "status": 500,
      "title": "Internal server error",
      "detail": "An internal error has occurred.",
      "meta": {
        "missing_ids": [
          "e7d50bd5-1833-43c0-9848-f9d325b08be8"
        ]
      }
    }
  ]
}

missing-name

{
  "errors": [
    {
      "title": "Validation Error",
      "status": "400",
      "detail": "data.attributes.name: \"name\" is required"
    }
  ]
}

500

Internal server error. There was a system failure in the platform.

application/json

Schema

Schema

errors Error[]required
Array [
status stringrequired
The HTTP response code of the error.
title stringrequired
A brief summary of the error.
detail string
Optional additional detail about the error.
meta object
Additional supporting meta data for the error.
]

Example (from schema)

{
  "errors": [
    {
      "status": 500,
      "title": "Internal server error",
      "detail": "An internal error has occurred.",
      "meta": {
        "missing_ids": [
          "e7d50bd5-1833-43c0-9848-f9d325b08be8"
        ]
      }
    }
  ]
}

internal-server-error

{
  "errors": [
    {
      "title": "Internal Server Error",
      "status": "500"
    }
  ]
}

Loading...