Create a manual subscription

Overview

Create a manual subscription, like importing from another platform. You cannot create 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 in this 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.

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

How many issues have been purchased during the subscription.

notesstring

Optional internalnotes about the subscription.

is_recurringboolean

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

Object (IssueRef):

idstring

numbernumber

namestring

issue_listnumber[]

Issue numbers included in this subscription.

periodsSubscriptionPeriod[]

Array (SubscriptionPeriod):

idnumber

order_datedate

is_completeboolean

lengthnumber

How many issues this period contains.

issue_listnumber[]

Issue numbers included in this period.

subscriberSubscriberRef

Object (SubscriberRef):

idstring

full_namestring

emailstring

sourceSourceRef

Object (SourceRef):

idstring

namestring

Example

JSON

{
  "id": "<string>",
  "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>",
  "notes": "<string>",
  "is_recurring": "<boolean>",
  "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>",
      "issue_list": [
        "<number>"
      ]
    }
  ],
  "subscriber": {
    "id": "<string>",
    "full_name": "<string>",
    "email": "<string>"
  },
  "source": {
    "id": "<string>",
    "name": "<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