Support

Subscription Methods

Methods for getting / modifying a Subscription from the Store API.

List all subscriptions, or get a subscription

GET http://yoursite.com/v1/store/api/subscriptions/
GET http://yoursite.com/v1/store/api/subscriptions/{subscription_id}/

Cancel, reactivate, or skip a subscription

Cancel an active subscription, reactivate an inactive subscription, or skip/unskip the next renewal.

PUT http://yoursite.com/v1/store/api/subscriptions/{subscription_id}/cancel/
PUT http://yoursite.com/v1/store/api/subscriptions/{subscription_id}/reactivate/
PUT http://yoursite.com/v1/store/api/subscriptions/{subscription_id}/skip/

Listing, applying, or removing coupons from subscriptions

GET http://yoursite.com/v1/store/api/subscriptions/{subscription_id}/coupons/
PUT http://yoursite.com/v1/store/api/subscriptions/{subscription_id}/coupons/
DELETE http://yoursite.com/v1/store/api/subscriptions/{subscription_id}/coupons/

Create, update, or delete subscription metadata

See documentation for Subscription Metadata for more details.

GET http://yoursite.com/v1/store/api/subscriptions/{sub_id}/metadata/
POST http://yoursite.com/v1/store/api/subscriptions/{sub_id}/metadata/
DELETE http://yoursite.com/v1/store/api/subscriptions/{sub_id}/metadata/

Get a subscription

$.get('/v1/store/api/subscriptions/75562148/');

{
    "autorenew": true, 
    "billing": {
      "id": 55065955, 
      "rebill_day": 1, 
      "rebill_months": 1, 
      "rebill_weeks": null, 
      "rebill_window": 10, 
      "store_id": 4848355, 
      "type": "product_billing"
    }, 
    "credit": null, 
    "customer": {
      "country": "US", 
      "email": "[email protected]", 
      "first_name": "Joey", 
      "id": 75561862, 
      "last_name": "Tallieu", 
      "location": "TX, US", 
      "name": "Joey Tallieu", 
      "num_orders": 21, 
      "num_subscriptions": 21, 
      "store_settings": null, 
      "subscription_status": "active", 
      "total_revenue": 26388, 
      "type": "customer"
    }, 
    "end_date": "2015-09-15T20:00:24Z", 
    "id": 75562148, 
    "is_test": true, 
    "note": null, 
    "product_billing_id": 55065955, 
    "revenue": 1200, 
    "skipped_date": null, 
    "start_date": "2015-09-15T20:00:24Z", 
    "status": "active", 
    "store_id": 4848355, 
    "term": {
      "description": "Charged every month", 
      "enabled": true, 
      "id": 55065958, 
      "name": "Month to Month", 
      "num_cycles": 1, 
      "type": "subscription_type_term"
    }, 
    "type": "subscription"
  }

Reactivate a subscription

$.ajax({
    url: '/v1/store/api/subscriptions/75562148/reactivate/',
    contentType: 'application/json',
    type: 'PUT',
    data: JSON.stringify({log_note: "Subscription reactivated using the Store API"}),
    success: function(data) {
        console.log(data);
    }
});

Cancel a subscription

$.ajax({
    url: '/v1/store/api/subscriptions/75562148/cancel/',
    contentType: 'application/json',
    type: 'PUT',
    data: JSON.stringify({
 	log_note: "Subscription canceled using the API",
  cancel_reason: 5
}),
    success: function(data) {
        console.log(data);
    }
});

Cancel Reasons

ReasonValue
Financial Reasons1
Just wanted to test it out2
Accidentally ordered more than once3
Planning on re-subscribing later4
Shipping issues5
Not worth the price6
Did not like the product7
Other service issues8
Trying another service9
Other10
Canceled by merchant11
I never wanted it to renew12
You billed me twice before I received anything13

Skip a subscription

$.ajax({
    url: '/v1/store/api/subscriptions/75562148/skip/',
    contentType: 'application/json',
    type: 'PUT',
    data: JSON.stringify({ skip: true }),
    success: function(data) {
        console.log(data);
    }
});

Unskip a subscription

$.ajax({
    url: '/v1/store/api/subscriptions/75562148/skip/',
    contentType: 'application/json',
    type: 'PUT',
    data: JSON.stringify({ unskip: true }),
    success: function(data) {
        console.log(data);
    }
});

Get subscription coupons

GET http://yoursite.com/v1/store/api/subscriptions/{subscription_id}/coupons/ 
$.get('/v1/store/api/subscriptions/2186430376/coupons/');

{
    "count": 1,
    "next": null,
    "prev": null,
    "results": [
    {
        "code_used": "100OFF",
        "coupon_id": 90278265,
        "enabled": true,
        "id": 2220703371,
        "num_renewals": 0,
        "type": "subscription_coupon",
        "url": "/v1/store/api/subscriptions/2220703371/"
    }]
}

Add a coupon to a subscription

PUT http://yoursite.com/v1/store/api/subscriptions/{subscription_id}/coupons/ 
$.ajax({
    url: '/v1/store/api/subscriptions/2184506927/coupons/',
    contentType: 'application/json',
    type: 'PUT',
    data: JSON.stringify({ "coupon_code": "100OFF" }),
    success: function(data) {
        console.log(data);
    }
});

{
    "code_used": "100OFF",
    "coupon_id": 90278265,
    "enabled": true,
    "id": 2220713562,
    "num_renewals": 0,
    "type": "subscription_coupon",
    "url": "/v1/store/api/subscriptions/2220713562/"
}

Remove a coupon from a subscription

DELETE http://yoursite.com/v1/store/api/subscriptions/{subscription_id}/coupons/ 
$.ajax({
    url: '/v1/store/api/subscriptions/2184506927/coupons/',
    contentType: 'application/json',
    type: 'DELETE',
    data: JSON.stringify({ "coupon_id": 90278265 }),
    success: function(data) {
        console.log(data);
    }
});

"No Content"

Get subscription metadata

GET http://yoursite.com/v1/store/api/subscriptions/{sub_id}/metadata/ 
$.get('/v1/store/api/subscriptions/623645/metadata/');

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

🚧

GET requests to the /subscriptions/{subscription_id}/metadata/ endpoint return 404 when the subscription does not already have a metadata record. POSTing data to the same route will create one.

{
  created_at: '2015-08-15T17:06:18Z',
  updated_at: '2015-08-15T17:06:18Z',
  subscription_id: 623645,
  id: 75572794,
  data: {
    "grate": "coarse",
    "flavor": "orange"
  }
}

Create or set subscription metadata

POST http://yoursite.com/v1/store/api/subscriptions/{sub_id}/metadata/ 
$.ajax({
    url: '/v1/store/api/subscriptions/623645/metadata/',
    contentType: 'application/json',
    type: 'POST',
    data: JSON.stringify({"grate": "coarse", "flavor": "orange"}),
    success: function(data) {
        console.log(data);
    }
});

🚧

Subscription records can only have one metadata record. POSTing to the subscription metadata endpoint will overwrite any existing records.

{
  created_at: '2015-08-15T17:06:18Z',
  updated_at: '2015-08-15T17:06:18Z',
  subscription_id: 623645,
  id: 75572794,
  data: {
    "grate": "coarse",
    "flavor": "orange"
  }
}

Delete subscription metadata

DELETE http://yoursite.com/v1/store/api/subscriptions/{sub_id}/metadata/ 
$.ajax({
    url: '/v1/store/api/subscriptions/623645/metadata/',
    contentType: 'application/json',
    type: 'DELETE',
    success: function(data) {
        console.log(data);
    }
});

"No Content"

Filtering by Status

If you want to filter by status, you have to use the integer value. For example: https://api.cratejoy.com/v1/subscriptions/?status__eq=2 rather than https://api.cratejoy.com/v1/subscriptions/?status__eq=active

The numeric values for each possible status are listed below.

idname
1unpaid
2active
3cancelled
4suspended
5expired
6past_due
7pending_renewal
8renewing
9unpaid_order_failed