List subscriptions
List subscriptions
Overview
Lists subscriptions. Use type to return only subscriptions or memberships.
Request parameters
cursorstringquery
Opaque cursor from the previous response. Omit for the first page.
limitnumberquery
Items per page. Default: 50. Maximum: 200.
subscriberstringquery
Filter by subscriber ID.
countrystringquery
Filter by subscription country code.
sourcestringquery
Filter by order source ID.
typesubscription | membershipquery
Filter by record type. membership for calendar memberships, subscription for issue subscriptions.
is_giftbooleanquery
Filter by gift status. Use true for gift subscriptions, false for non-gifts.
searchstringquery
Partial text search across subscription and subscriber fields.
Request body
No request body.
Request examples
No request body.
Responses
has_morebooleanRequiredTrue if more items are available after this page.
cursorstringRequiredPass this as cursor to fetch the next page. Null when has_more is false.
itemsSubscription[]RequiredArray (Subscription):
idstringSubscription ID.
typeSubscriptionTypesubscription is an issue-tied magazine subscription. membership is a calendar-billed membership.
values
- subscription
- membership
statusSubscriptionStatusvalues
- Active
- Active - Renewals stopped
- Complete
- Cancelled
- Past due
mediumPrint | Digital | Print + digitalfirst_namestringlast_namestringshipping_addressShippingAddressObject (ShippingAddress):
companystringaddress1stringaddress2stringcitystringstatestringpostcodestringcountrystringcountry_namestringphonestringlengthnumberNumber of issues per period. Null for memberships.
interval_monthsnumberMembership billing interval in months (e.g. 1 for monthly, 3 for quarterly). Null for subscriptions.
total_lengthnumberHow many issues have been included on this subscription/membership since purchase. This grows as magazine copies are granted.
notesstringOptional internal notes about the subscription.
is_recurringbooleancurrent_period_startdateFirst day of the current paid membership window. Null for subscriptions.
current_period_enddateLast day of the current paid membership window. Null for subscriptions.
next_charge_datedateNext renewal charge date. For memberships, the next scheduled billing period start date. For subscriptions, the next issue's recurring charge date, if set. Null if not recurring.
is_compbooleanTrue if the subscription is a complimentary subscription (no purchase made).
is_giftbooleangifterGifterRefDetails of the person who gifted the subscription (when is_gift is true).
Object (GifterRef):
full_namestringemailstringpromo_codestringdiscount_amountstringrefundedstringcurrencystringpricestringorder_datedatestart_issueIssueRefFirst issue of an issue subscription. Null for memberships.
Object (IssueRef):
idstringnumbernumbernamestringissue_listnumber[]Issue numbers included in this subscription.
periodsSubscriptionPeriod[]Array (SubscriptionPeriod):
idnumberorder_datedateis_completebooleanlengthnumberNumber of issues in this period.
interval_monthsnumberMembership billing interval in months for this period. Null for subscriptions.
period_startdateFirst day of the membership billing window. Null for subscriptions.
period_enddateLast day of the membership billing window. Null for subscriptions.
issue_listnumber[]Issue numbers included in this period.
subscriberSubscriberRefObject (SubscriberRef):
idstringfull_namestringemailstringsourceSourceRefObject (SourceRef):
idstringnamestringproductProductProduct purchased for this subscription or membership.
Object (Product):
idstringProduct ID.
namestringPublic product name.
benefitsstring[]Product benefits as a list. Empty list for imported products or when no benefits are set.
Example
{
"has_more": "<boolean>",
"cursor": "<string>",
"items": [
{
"id": "<string>",
"type": "subscription",
"status": "Active",
"medium": "<Print | Digital | Print + digital>",
"first_name": "<string>",
"last_name": "<string>",
"shipping_address": {
"company": "<string>",
"address1": "<string>",
"address2": "<string>",
"city": "<string>",
"state": "<string>",
"postcode": "<string>",
"country": "<string>",
"country_name": "<string>",
"phone": "<string>"
},
"length": "<number>",
"interval_months": "<number>",
"total_length": "<number>",
"notes": "<string>",
"is_recurring": "<boolean>",
"current_period_start": "<date>",
"current_period_end": "<date>",
"next_charge_date": "<date>",
"is_comp": "<boolean>",
"is_gift": "<boolean>",
"gifter": {
"full_name": "<string>",
"email": "<string>"
},
"promo_code": "<string>",
"discount_amount": "<string>",
"refunded": "<string>",
"currency": "<string>",
"price": "<string>",
"order_date": "<date>",
"start_issue": {
"id": "<string>",
"number": "<number>",
"name": "<string>"
},
"issue_list": [
"<number>"
],
"periods": [
{
"id": "<number>",
"order_date": "<date>",
"is_complete": "<boolean>",
"length": "<number>",
"interval_months": "<number>",
"period_start": "<date>",
"period_end": "<date>",
"issue_list": [
"<number>"
]
}
],
"subscriber": {
"id": "<string>",
"full_name": "<string>",
"email": "<string>"
},
"source": {
"id": "<string>",
"name": "<string>"
},
"product": {
"id": "<string>",
"name": "<string>",
"benefits": [
"<string>"
]
}
}
]
}