Get subscription

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

Get subscription

Request

Path Parameters

subscription_uuid UUIDrequired

The unique identifier of the subscription.

Query Parameters

include string[]

Possible values: [products, plans]

Responses

200

Success. The details of a subscription are returned.

application/json

Schema

Schema

data Subscription
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 product and a plan are related to an offering, as both are attached to it.
property name* Relationship
anyOf
SingleRelationship
ManyRelationship
meta OfferingMetarequired
external_product_refsstring[]required
ownerstringrequired
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
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]
elastic_path_payments_stripe
authorize_net
payment_profile_idstring
The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription.
Possible values: >= 3 characters and <= 1024 characters
Example: 1511660856
customer_profile_idstring
The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription.
Possible values: >= 3 characters and <= 1024 characters
Example: 1511736979
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.
property name* Relationship
anyOf
SingleRelationship
ManyRelationship
meta SubscriptionMetarequired
ownerstringrequired
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 product.
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
products OfferingProduct[]
Array [
idUUID (string)
The unique identifier.
Example: 11111111-2222-3333-4444-555555555555
typeSubscriptionOfferingProductType (string)required
Possible values: [subscription_offering_product]
Example: subscription_offering_product
attributes OfferingProductResponseAttributes
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 product.
Possible values: >= 3 characters and <= 1024 characters
Example: Magazine
descriptionstring
The product 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 product, if appropriate.
Possible values: <= 1024 characters
Example: MAGAZINE1
main_imageuri
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.
Possible values: <= 1024 characters
Example: https://magazine.com/cover.jpg
price Price
property name* object
The base price.
amountint64required
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 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.
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 product
property name* FeatureProductConfiguration
typerequired
Possible values: [access, promotion, usage]
access
object
promotion
tagFeatureTag (string)required
A tag to add to the customer's account when entitled to the feature.
Possible values: non-empty and <= 64 characters, Value must match regular expression ^[0-9A-Za-z_-]+$
Example: digital_library_access
usage
default_valueintegerrequired
The default initial value
Example: 10
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.
property name* Relationship
anyOf
SingleRelationship
ManyRelationship
meta ProductMetarequired
display_price DisplayPrice
without_tax PriceFormatting
amountint64required
The unformatted amount for the objects.
Example: 100
currencystringrequired
The three-letter ISO currency code in uppercase, associated with a price.
Example: USD
formattedstringrequired
The formatted amount for the objects.
Example: $1.00
with_tax PriceFormatting
amountint64required
The unformatted amount for the objects.
Example: 100
currencystringrequired
The three-letter ISO currency code in uppercase, associated with a price.
Example: USD
formattedstringrequired
The formatted amount for the objects.
Example: $1.00
ownerstringrequired
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
]
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 PlanResponseAttributes
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 plan.
Possible values: >= 3 characters and <= 1024 characters
Example: Monthly
descriptionstring
The plan 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.
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_percentagedouble
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.
Possible values: <= 100
Example: 90
fixed_price Price
property name* object
The base price.
amountint64required
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 product and a plan are related to an offering, as both are attached to it.
property name* Relationship
anyOf
SingleRelationship
ManyRelationship
meta OfferingPlanMetarequired
price Price
property name* object
The base price.
amountint64required
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
amountint64required
The unformatted amount for the objects.
Example: 100
currencystringrequired
The three-letter ISO currency code in uppercase, associated with a price.
Example: USD
formattedstringrequired
The formatted amount for the objects.
Example: $1.00
with_tax PriceFormatting
amountint64required
The unformatted amount for the objects.
Example: 100
currencystringrequired
The three-letter ISO currency code in uppercase, associated with a price.
Example: USD
formattedstringrequired
The formatted amount for the objects.
Example: $1.00
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
ownerstringrequired
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
]

Example (auto)

{
  "data": {
    "id": "11111111-2222-3333-4444-555555555555",
    "type": "subscription",
    "attributes": {
      "external_ref": "abc123",
      "account_id": "11111111-2222-3333-4444-555555555555",
      "address_id": "11111111-2222-3333-4444-555555555555",
      "offering": {
        "id": "11111111-2222-3333-4444-555555555555",
        "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": "11111111-2222-3333-4444-555555555555",
      "currency": "USD",
      "payment_authority": {
        "type": "elastic_path_payments_stripe",
        "customer_id": "cus_OPfKlxWV3hp9h6",
        "card_id": "card_8Diw3FQPhxK27WADPVMeXieP"
      }
    },
    "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": "11111111-2222-3333-4444-555555555555",
        "type": "subscription_state",
        "attributes": {
          "action": "cancel"
        },
        "meta": {
          "created_at": "2017-01-10T11:41:19.244842Z"
        }
      },
      "manual_payments": false,
      "first_invoice_prepaid": false,
      "canceled": true,
      "paused": true,
      "closed": true,
      "suspended": false,
      "pending": false,
      "invoice_after": "2017-01-10T11:41:19.244842Z"
    }
  },
  "included": {
    "products": [
      {
        "id": "11111111-2222-3333-4444-555555555555",
        "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",
          "feature_configurations": {}
        },
        "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": "11111111-2222-3333-4444-555555555555",
        "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"
          }
        }
      }
    ]
  }
}

400

Bad request. The request failed validation.

application/json

Schema

Schema

errors Error[]required
Array [
statusstringrequired
The HTTP response code of the error.
Example: 500
titlestringrequired
A brief summary of the error.
Example: Internal server error
detailstring
Optional additional detail about the error.
Example: An internal error has occurred.
metaobject
Additional supporting meta data for the error.
Example: {"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}
]

Example (auto)

{
  "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"
    }
  ]
}

404

Not found. The requested entity does not exist.

application/json

Schema

Schema

errors Error[]required
Array [
statusstringrequired
The HTTP response code of the error.
Example: 500
titlestringrequired
A brief summary of the error.
Example: Internal server error
detailstring
Optional additional detail about the error.
Example: An internal error has occurred.
metaobject
Additional supporting meta data for the error.
Example: {"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}
]

Example (auto)

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

not-found

{
  "errors": [
    {
      "title": "Not Found",
      "status": "404",
      "detail": "No plan found"
    }
  ]
}

500

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

application/json

Schema

Schema

errors Error[]required
Array [
statusstringrequired
The HTTP response code of the error.
Example: 500
titlestringrequired
A brief summary of the error.
Example: Internal server error
detailstring
Optional additional detail about the error.
Example: An internal error has occurred.
metaobject
Additional supporting meta data for the error.
Example: {"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}
]

Example (auto)

{
  "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"
    }
  ]
}

Authorization: http

name: BearerTokentype: httpscheme: bearer

• csharp
• curl
• dart
• go
• http
• java
• javascript
• kotlin
• c
• nodejs
• objective-c
• ocaml
• php
• powershell
• python
• r
• ruby
• rust
• shell
• swift

• HTTPCLIENT
• RESTSHARP

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "https://euwest.api.elasticpath.com/v2/subscriptions/subscriptions/:subscription_uuid");
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

Bearer Token

Parameters

subscription_uuid — pathrequired

include — query

productsplans

ResponseClear

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