Support
API Reference

Subscription Methods

Methods for Subscription data objects

List all subscriptions, or get/modify a subscription

GET https://api.cratejoy.com/v1/subscriptions/
GET https://api.cratejoy.com/v1/subscriptions/{sub_id}
PUT https://api.cratejoy.com/v1/subscriptions/{sub_id}/

Cancel, reactivate, skip, or renew a subscription

PUT https://api.cratejoy.com/v1/subscriptions/{sub_id}/cancel/
PUT https://api.cratejoy.com/v1/subscriptions/{sub_id}/reactivate/
PUT https://api.cratejoy.com/v1/subscriptions/{sub_id}/skip/
PUT https://api.cratejoy.com/v1/subscriptions/{sub_id}/renew/

Listing, applying, or removing coupons from subscriptions

GET https://api.cratejoy.com/v1/subscriptions/{sub_id}/coupons/
POST https://api.cratejoy.com/v1/subscriptions/{sub_id}/coupons/
DELETE https://api.cratejoy.com/v1/subscriptions/{sub_id}/coupon/{coupon_id}/

Create, edit, get, or delete subscription metadata

These endpoints operate on the subscription metadata subresource.

PUT will add/replace specific fields in the JSON data. Other fields will be unaffected. POST will replace the entire metadata object.

GET https://api.cratejoy.com/v1/subscriptions/{sub_id}/metadata/
POST https://api.cratejoy.com/v1/subscriptions/{sub_id}/metadata/
PUT https://api.cratejoy.com/v1/subscriptions/{sub_id}/metadata/
DELETE https://api.cratejoy.com/v1/subscriptions/{sub_id}/metadata/

List subscriptions

GET https://api.cratejoy.com/v1/subscriptions/ 
$.ajax({
    url: 'https://api.cratejoy.com/v1/subscriptions/',
    method: 'GET'
});

$.get('https://api.cratejoy.com/v1/customers/',{
  "address.city": "Austin",
  "_md.shoe.size__gt": 10
});

{
  "count": 22, 
  "next": "?page=1", 
  "prev": null, 
  "results": [{
    "autorenew": true, 
    "billing": {...}, // Billing relation property
   	"billing_name": "Monthly",
    "credit": null, 
    "customer": {...}, // Customer relation property 
    "end_date": "2015-10-15T20:00:24Z", 
    "id": 75562148, 
    "is_test": true, 
    "note": null, 
    "product_billing_id": 55065955, 
    "skipped_date": null, 
    "start_date": "2015-09-15T20:00:24Z", 
    "status": "active", 
    "store_id": 4848355, 
    "term": {...}, // Term relation property 
    "type": "subscription",
    "url": "/v1/subscriptions/75562148"
  }]
}

Get subscription

GET https://api.cratejoy.com/v1/subscriptions/{sub_id} 
$.ajax({
    url: 'https://api.cratejoy.com/v1/subscriptions/75562148/',
    method: 'GET'
});

Update subscription

PUT https://api.cratejoy.com/v1/subscriptions/{sub_id}/ 
$.ajax({
    url: 'https://api.cratejoy.com/v1/subscriptions/75562148/',
    method: 'PUT',
    data: {
      note: "A new note"
    }
});

Cancel a subscription

PUT https://api.cratejoy.com/v1/subscriptions/{sub_id}/cancel 
$.ajax({
    url: 'https://api.cratejoy.com/v1/subscriptions/75562148/cancel/',
    method: 'PUT',
    data: {
      "log_note": "A new note"
    }
});

Reactivate a subscription

PUT https://api.cratejoy.com/v1/subscriptions/{sub_id}/reactivate/ 
$.ajax({
    url: 'https://api.cratejoy.com/v1/subscriptions/75562148/reactivate/',
    method: 'PUT',
    data: {
      log_note: "A new note"
    }
});

Skip a subscription's next renewal

PUT https://api.cratejoy.com/v1/subscriptions/{sub_id}/skip/ 
$.ajax({
    url: 'https://api.cratejoy.com/v1/subscriptions/75562148/skip/',
    method: 'PUT',
    data: {
      skip: "true"
    }
});

Unskip a subscription

$.ajax({
    url: 'https://api.cratejoy.com/v1/subscriptions/75562148/skip/',
    method: 'PUT',
    data: {
      unskip: "true"
    }
});

Renew a subscription

PUT https://api.cratejoy.com/v1/subscriptions/{sub_id}/renew/

📘

Only works with past due subscriptions that failed to renew in the past 30 days.

$.ajax({
    url: 'https://api.cratejoy.com/v1/subscriptions/75562148/renew/',
    method: 'PUT',
    data: {
      log_note: "A new note"
    }
});

Listing, adding, and removing subscription coupons

Subscription coupons are coupons that apply on a subscription's next renewal or a cancelled or expired subscription's reactivation. They can be added or even removed from a subscription, because they haven't yet been applied to an order. This makes them helpful for running reactivation campaigns. For more on subscription coupons, please refer to the Subscription Coupons subresource.

List coupons on a subscription

GET https://api.cratejoy.com/v1/subscriptions/{sub_id}/coupons/

This will only list coupons that apply on the subscription's next renewal (i.e., can be modified). 

{
  "count": 1,
  "next": null,
  "prev": null,
  "results": [
    {
      "code_used": "1234COUPON",
      "coupon_id": 713852368,
      "enabled": true,
      "id": 723378616,
      "num_renewals": 0, 
      "type": "subscription_coupon",
      "url": "/v1/subscriptions/723378616/"
    }
  ]
}

Add a coupon to a subscription

POST https://api.cratejoy.com/v1/subscriptions/{sub_id}/coupons/

Here, you can apply a subscription coupon to a subscription that will apply on the next renewal. The only required parameter is coupon_id.

$.ajax({
    url: 'https://api.cratejoy.com/v1/subscriptions/75562148/coupons/',
    method: 'POST',
    data: {
      coupon_id: 34526674
    }
});

{
  "code_used": "1234COUPON",
  "coupon_id": 756026933,
  "enabled": true,
  "id": 756027331,
  "num_renewals": 0,
  "type": "subscription_coupon",
  "url": "/v1/subscriptions/756027331/"
}

// If the subscription already has the coupon applied

{
  "errors": [
    "Subscription already has the coupon."
  ]
}

// If the coupon is unable to be applied to the subscription. Could be because the coupon isn't enabled, or doesn't apply to the subscription product.

{
  "errors": [
    "Unable to add coupon."
  ]
}

// If the coupon ID doesn't match a coupon in your store
{
  "errors": [
    "Coupon not found"
  ]
}

Delete a coupon from a subscription

DELETE https://api.cratejoy.com/v1/subscriptions/{sub_id}/coupon/{coupon_id}/