Create a manual subscription

Overview

Create a manual subscription, like importing from another platform. You cannot create a manual membership or a recurring subscription with this endpoint, or save payment information. Creates the subscriber (or matches an existing one by email), and full subscription record, including copies. Requires a read-write API key.

posthttps://api.subsail.com/v1/subscriptions/

Request parameters

No parameters.

Request body

sourcestringRequired

Source ID from GET /v1/sources/. Must be an active connected shop or import source (not Subsail checkout).

start_issuenumberRequired

The issue number of the first issue in this subscription.

lengthnumberRequired

Number of issues per period for this imported subscription.

emailstring

Subscriber email. If omitted, a placeholder address is created. Matching an existing email attaches this subscription to that subscriber.

first_namestring

last_namestring

companystring

Company name. Required if first_name is omitted.

address1string

First line of the shipping address.

address2string

Second line of the shipping address.

citystring

City of the shipping address.

statestring

State of the shipping address.

postcodestring

Postcode of the shipping address.

countrystringRequired

ISO country code of the shipping address (e.g. 'GB', 'US').

phonestring

Phone number with country code, e.g. +44 7700 900123.

notesstring

order_idstringRequired

Unique order ID from the original platform. If the order was not from a shop, any unique value is fine.

order_datedateRequired

Order date in YYYY-MM-DD format.

transaction_idstring

Optional payment-system transaction ID.

pricestringRequired

Amount paid. Use 0 for complimentary subscriptions.

currencystring

ISO currency code. Defaults to the account selling currency.

is_recurringboolean

True if this imported subscription has a recurring payment.

is_compboolean

True if this is a complimentary subscription.

mediumPrint | Digital | Print + digital

promo_codestring

Optional promo code applied to this order.

discount_amountstring

Discount amount applied to this order.

send_welcome_emailboolean

Send the account's default welcome email to the subscriber after creation.

Example

JSON

{
  "source": "<string>",
  "start_issue": "<number>",
  "length": "<number>",
  "email": "<string>",
  "first_name": "<string>",
  "last_name": "<string>",
  "company": "<string>",
  "address1": "<string>",
  "address2": "<string>",
  "city": "<string>",
  "state": "<string>",
  "postcode": "<string>",
  "country": "<string>",
  "phone": "<string>",
  "notes": "<string>",
  "order_id": "<string>",
  "order_date": "<date>",
  "transaction_id": "<string>",
  "price": "<string>",
  "currency": "<string>",
  "is_recurring": "<boolean>",
  "is_comp": "<boolean>",
  "medium": "<Print | Digital | Print + digital>",
  "promo_code": "<string>",
  "discount_amount": "<string>",
  "send_welcome_email": "<boolean>"
}

Request examples

curl -X POST https://api.subsail.com/v1/subscriptions/ \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
  "source": "<string>",
  "start_issue": "<number>",
  "length": "<number>",
  "email": "<string>",
  "first_name": "<string>",
  "last_name": "<string>",
  "company": "<string>",
  "address1": "<string>",
  "address2": "<string>",
  "city": "<string>",
  "state": "<string>",
  "postcode": "<string>",
  "country": "<string>",
  "phone": "<string>",
  "notes": "<string>",
  "order_id": "<string>",
  "order_date": "<date>",
  "transaction_id": "<string>",
  "price": "<string>",
  "currency": "<string>",
  "is_recurring": "<boolean>",
  "is_comp": "<boolean>",
  "medium": "<Print | Digital | Print + digital>",
  "promo_code": "<string>",
  "discount_amount": "<string>",
  "send_welcome_email": "<boolean>"
}'

const response = await fetch('https://api.subsail.com/v1/subscriptions/', {
  method: 'POST',
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
      "source": "<string>",
      "start_issue": "<number>",
      "length": "<number>",
      "email": "<string>",
      "first_name": "<string>",
      "last_name": "<string>",
      "company": "<string>",
      "address1": "<string>",
      "address2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "postcode": "<string>",
      "country": "<string>",
      "phone": "<string>",
      "notes": "<string>",
      "order_id": "<string>",
      "order_date": "<date>",
      "transaction_id": "<string>",
      "price": "<string>",
      "currency": "<string>",
      "is_recurring": "<boolean>",
      "is_comp": "<boolean>",
      "medium": "<Print | Digital | Print + digital>",
      "promo_code": "<string>",
      "discount_amount": "<string>",
      "send_welcome_email": "<boolean>"
    }),
});
const data = await response.json();

Responses

201Created subscription

idstring

Subscription ID.

typeSubscriptionType

subscription is an issue-tied magazine subscription. membership is a calendar-billed membership.

values

subscription
membership

statusSubscriptionStatus

values

Active
Active - Renewals stopped
Complete
Cancelled
Past due

mediumPrint | Digital | Print + digital

first_namestring

last_namestring

shipping_addressShippingAddress

Object (ShippingAddress):

companystring

address1string

address2string

citystring

statestring

postcodestring

countrystring

country_namestring

phonestring

lengthnumber

Number of issues per period. Null for memberships.

interval_monthsnumber

Membership billing interval in months (e.g. 1 for monthly, 3 for quarterly). Null for subscriptions.

total_lengthnumber

How many issues have been included on this subscription/membership since purchase. This grows as magazine copies are granted.

notesstring

Optional internal notes about the subscription.

is_recurringboolean

current_period_startdate

First day of the current paid membership window. Null for subscriptions.

current_period_enddate

Last day of the current paid membership window. Null for subscriptions.

next_charge_datedate

Next 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_compboolean

True if the subscription is a complimentary subscription (no purchase made).

is_giftboolean

gifterGifterRef

Details of the person who gifted the subscription (when is_gift is true).

Object (GifterRef):

full_namestring

emailstring

promo_codestring

discount_amountstring

refundedstring

currencystring

pricestring

order_datedate

start_issueIssueRef

First issue of an issue subscription. Null for memberships.

Object (IssueRef):

idstring

numbernumber

namestring

issue_listnumber[]

Issue numbers included in this subscription.

periodsSubscriptionPeriod[]

Array (SubscriptionPeriod):

idnumber

order_datedate

is_completeboolean

lengthnumber

Number of issues in this period.

interval_monthsnumber

Membership billing interval in months for this period. Null for subscriptions.

period_startdate

First day of the membership billing window. Null for subscriptions.

period_enddate

Last day of the membership billing window. Null for subscriptions.

issue_listnumber[]

Issue numbers included in this period.

subscriberSubscriberRef

Object (SubscriberRef):

idstring

full_namestring

emailstring

sourceSourceRef

Object (SourceRef):

idstring

namestring

productProduct

Product purchased for this subscription or membership.

Object (Product):

idstring

Product ID.

namestring

Public product name.

benefitsstring[]

Product benefits as a list. Empty list for imported products or when no benefits are set.

Example

JSON

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

400Invalid request

errorbooleanRequired

messagestringRequired

codestring

Machine-readable code, e.g. read_only_key for read-only key write attempts.

Example

JSON

{
  "error": "<boolean>",
  "message": "<string>",
  "code": "<string>"
}

401Missing or invalid API key (empty response body).

403Write request rejected. Inactive account returns an empty body. Read-only API key returns JSON with `code: read_only_key`.

errorbooleanRequired

messagestringRequired

codestring

Machine-readable code, e.g. read_only_key for read-only key write attempts.

Example

JSON

{
  "error": true,
  "message": "This API key is read-only. Create a read-write key in Subsail settings to perform write operations.",
  "code": "read_only_key"
}

Create a manual subscription

Overview

Request parameters

Request body

Request examples

Responses

On this page