Update a subscription

Overview

Partial update: include only the fields you want to change. Requires a read-write API key. Writable fields: first_name, last_name, company, address1, address2, city, state, postcode, country, phone, notes.

patchhttps://api.subsail.com/v1/subscriptions/{id}/

Request parameters

idstringRequired

path

Resource ID (alphanumeric).

Request body

first_namestring

last_namestring

companystring

address1string

address2string

citystring

statestring

postcodestring

countrystring

ISO country code.

phonestring

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

notesstring

Example

JSON

{
  "first_name": "<string>",
  "last_name": "<string>",
  "company": "<string>",
  "address1": "<string>",
  "address2": "<string>",
  "city": "<string>",
  "state": "<string>",
  "postcode": "<string>",
  "country": "<string>",
  "phone": "<string>",
  "notes": "<string>"
}

Request examples

curl -X PATCH https://api.subsail.com/v1/subscriptions/{id}/ \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
  "first_name": "<string>",
  "last_name": "<string>",
  "company": "<string>",
  "address1": "<string>",
  "address2": "<string>",
  "city": "<string>",
  "state": "<string>",
  "postcode": "<string>",
  "country": "<string>",
  "phone": "<string>",
  "notes": "<string>"
}'

const response = await fetch('https://api.subsail.com/v1/subscriptions/{id}/', {
  method: 'PATCH',
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
      "first_name": "<string>",
      "last_name": "<string>",
      "company": "<string>",
      "address1": "<string>",
      "address2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "postcode": "<string>",
      "country": "<string>",
      "phone": "<string>",
      "notes": "<string>"
    }),
});
const data = await response.json();

Responses

200Updated 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"
}

404Resource not found

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

Update a subscription

Overview

Request parameters

Request body

Request examples

Responses

On this page