Structure

The structure of the JSON API is closely modeled on REST and JSON-API.org standards. All calls to the API go over HTTP using the appropriate method (GET for reading, POST for creating, PUT for updating, DELETE for destruction).

Endpoints

Authentication

Generally, the API is unauthenticated. POST/PUT/DELETE requests must contain the authenticity_token parameter with the supplied form authenticity token. This is used to prevent Cross-Site Request Forgery attacks. HTML GET requests will return this token for use in POST/PUT/DELETE requests.

You'll need to run the following snippet in your code before making requests to add the CSRF token to your ajax requests:

jQuery.ajaxPrefilter(function(options, originalOptions, xhr) {
  var token = jQuery('meta[name="csrf-token"]').attr('content');
  if (token) xhr.setRequestHeader('X-CSRF-Token', token);
});

Errors

If any errors are encountered while processing a create or update request, the errors key in the respond will contain the error. If multiple changes were requested, but only one change had an error, the successful changes will not be rolled back.

In some cases, the related record will be returned in a way that it can be referenced.

Example

{
  "errors": [
    {
      "field":   "qty",
      "message": "invalid for Air Elemental (20 in stock).",
      "code":    "reached_stock_limit",
      "line_item": {
        "id":         123,
        "variant_id": 63401
      }
    }
  ]
}

Getting the Cart

The current session's cart can be retreived by issuing a GET request to the cart resource endpoint /api/v1/cart. While you'll only ever receive one cart in response, the json-api standard specifies singleton resources should still be pluralized, so the root key is carts.

You can also render your liquid template with the current cart JSON with {{ site.cart_json }}.

Example Request

jQuery.ajax({
  url: "/api/v1/cart",
  type: "GET",
  dataType: "json",
  contentType: 'application/json; charset=utf-8'
});

Example Response:

{
  "carts": [
    {
      "id": 694,
      "type": "Order",
      "currency": "USD",
      "line_items_count": 1,
      "total_cents": 34,
      "links": {
        "checkout": "/checkout/index",
        "cart": "/checkout/cart"
      },
      "line_items": [
        {
          "id": 3315,
          "name": "Mirrodin Booster Pack",
          "qty": 1,
          "descriptors": "Condition: Brand New",
          "variant_id": 37172,
          "product_id": 12266,
          "category_name": "Booster Packs",
          "is_tax_exempt": false,
          "price_cents": 34,
          "msrp_cents": 350,
          "discount_cents": null,
          "links": {
            "product": "/catalog/magic_products-booster_packs/mirrodin_booster_pack/12266"
          },
          "thumbnail": "https://crystalcommerce-assets.s3.amazonaws.com/photos/30658/thumb/uZyvJDP3RZJ3ZQwE.jpg"
        }
      ]
    }
  ]
}

Adding Line Items

You can add one or many line items to a cart with a POST request to the cart's line items endpoint /api/v1/cart/line_items. The only two keys in a line item record that are respected are the variant_id and qty to buy.

You'll receive three root elements, the line_items successfully added, the existing carts, and any errors encountered while processing the request.

Example Request

var lineItems = {
  line_items: [
    {variant_id: 123, qty: 3},
    {variant_id: 456, qty: 2}
  ]
};
jQuery.ajax({
  url: '/api/v1/cart/line_items',
  type: 'POST',
  dataType: 'json',
  contentType: 'application/json; charset=utf-8',
  data: JSON.stringify(lineItems)
});

Example Response

{
  "line_items": [
    {
      "id": 4020,
      "variant_id": 123,
      "name": "Air Elemental",
      "qty": 3,
      "descriptors": "Condition: Near Mint | Language: English",
      "price_cents": 19
      // ...
    },
    {
      "id": 4021,
      "variant_id": 456,
      "name": "Adarkar Wastes",
      "qty": 2,
      "descriptors": "Condition: Near Mint | Language: English",
      "price_cents": 133
      // ...
    }
  ],
  "carts": [{
    "id": 702,
    "type": "Order",
    "currency": "USD",
    "line_items_count": 5,
    "total_cents": 323,
    "links": {
      "checkout": "/checkout/index",
      "cart": "/checkout/cart"
    },
    "line_items":[
      {
        "id": 4020,
        "variant_id": 123,
        "name": "Air Elemental",
        "qty": 3,
        "descriptors": "Condition: Near Mint | Language: English",
        "price_cents": 19
        // ...
      },
      {
        "id": 4021,
        "variant_id": 456,
        "name": "Adarkar Wastes",
        "qty": 2,
        "descriptors": "Condition: Near Mint | Language: English",
        "price_cents": 133
        // ...
      }
    ]
  }],
  "errors": []
}

Updating Line Items

You can update the quantities of line items in your cart with PUT calls to the cart update endpoint /api/v1/cart/update The POST body of the request must contain a JSON PATCH (RFC 6902) document.

The only attribute available for update is qty. If the qty is set to a value less than 1, the line item will be removed from the cart.

Example Request

jQuery.ajax({
  url: "/api/v1/cart",
  type: "PUT",
  dataType: 'json',
  contentType: 'application/json; charset=utf-8',
  data: JSON.stringify([{
    op: "replace",
    path:  "/cart/0/line_items/124/qty",
    value: 4
  }])
});

Example Response

{
  "line_items": [
    {
      "id":              124,
      "name":            "Air Elemental",
      "qty":             4,
      "descriptors":     "Condition: Near Mint | Language: English",
      "price_cents":     19,
      "msrp_cents":      nil,
      "discount_cents":  nil,
      "variant_id":      9012,
      "product_id":      810,
      "is_tax_exempt":   false,
      "category_name":   "Tenth Edition"
      // ...
    }
  ],
  "carts": [
    {
      "id"               : 1,
      "type"             : "Order",
      "currency"         : "USD",
      "line_items_count" : 9,
      "total_cents"      : 4995,
      "links"            : {
        "checkout" : "/checkout/index",
        "cart"     : "/checkout/cart"
      },
      "line_items" : [
        {
          "id":              123,
          "name":            "Adarkar Wastes",
          "qty":             2,
          "descriptors":     "Condition: Near Mint | Language: English",
          "price_cents":     133,
          "msrp_cents":      499,
          "discount_cents":  nil,
          "variant_id":      9001,
          "product_id":      809,
          "is_tax_exempt":   false,
          "category_name":   "Tenth Edition"
          // ...
        },
        {
          "id":              124,
          "name":            "Air Elemental",
          "qty":             4,
          "descriptors":     "Condition: Near Mint | Language: English",
          "price_cents":     19,
          "msrp_cents":      nil,
          "discount_cents":  nil,
          "variant_id":      9012,
          "product_id":      810,
          "is_tax_exempt":   false,
          "category_name":   "Tenth Edition"
          // ...
        }
      ]
    }
  ],
  "errors": []
}

Removing Line Items

Following REST conventions, a DELETE call to /api/v1/cart/line_items/:id (where :id is the id of the line item) will remove the line item from the current cart.

Response will be a 204 No Content on success.

Example Request

jQuery.ajax({
  url: "/api/v1/cart/line_items/123",
  type: "DELETE",
  dataType: 'json',
  contentType: 'application/json; charset=utf-8'
});

Emptying the Cart

A POST request to /api/v1/cart/empty will clear the cart of items.

Response will be your cart, without any items.

Example Request

jQuery.ajax({
  url: "/api/v1/cart/empty",
  type: "POST",
  dataType: "json",
  contentType: 'application/json; charset=utf-8'
});

Getting the Buylist

The current session's buylist can be retreived by issuing a GET request to the buylist resource endpoint /api/v1/buylist. While you'll only ever receive one buylist in response, the json-api standard specifies singleton resources should still be pluralized, so the root key is buylists.

You can also render your liquid template with the current buylist JSON with {{ site.buylist_json }}.

Example Request

jQuery.ajax({
  url: "/api/v1/buylist",
  type: "GET",
  dataType: "json",
  contentType: 'application/json; charset=utf-8'
});

Example Response:

{
  "buylists": [{
    "id": 702,
    "type": "BuyOrder",
    "currency": "USD",
    "line_items_count": 1,
    "total_cents": 2800,
    "links": {
      "checkout": "/buy_orders/show",
    },
    "line_items": [
      {
        "id": 4019,
        "name": "Judgment Fat Pack",
        "qty": 1,
        "descriptors": "Condition: Brand New",
        "price_cents": 2800,
        "msrp_cents": 3500
      }
    ]
  }]
}

Adding Buylist Items

You can add one or many line items to a buylist with a POST request to the buylist's line items endpoint /api/v1/buylist/line_items. The only two keys in a line item record that are respected are the variant_id and qty to buy.

You'll receive three root elements, the line_items successfully added, the existing buylists, and any errors encountered while processing the request.

Example Request

var lineItems = {
  line_items: [
    {variant_id: 123, qty: 3},
    {variant_id: 456, qty: 2}
  ]
};
jQuery.ajax({
  url: '/api/v1/buylist/line_items',
  type: 'POST',
  dataType: 'json',
  contentType: 'application/json; charset=utf-8',
  data: JSON.stringify(lineItems)
});

Example Response

{
  "buylists": [
    {
      "id": 695,
      "type": "BuyOrder",
      "currency": "USD",
      "line_items_count": 1,
      "total_cents": 240,
      "links": {
        "checkout": "/buy_orders/show"
      },
      "line_items": [
        {
          "id": 3316,
          "name": "Abundant Growth",
          "qty": 1,
          "descriptors": "Condition: NM-Mint | Language: English",
          "variant_id": 38477,
          "product_id": 57114,
          "category_name": "Avacyn Restored",
          "is_tax_exempt": false,
          "price_cents": 240,
          "msrp_cents": 23,
          "discount_cents": null,
          "links": {
            "product": "/buylist/magic_singles-innistrad_block-avacyn_restored/abundant_growth/57114"
          },
          "thumbnail": "https://crystalcommerce-assets.s3.amazonaws.com/photos/857388/thumb/abundant.jpg"
        }
      ]
    }
  ]
}

Updating Buylist Items

You can update the quantities of line items in your buylist with PUT calls to the buylist update endpoint /api/v1/buylist/update The POST body of the request must contain a JSON PATCH (RFC 6902) document.

The only attribute available for update is qty. If the qty is set to a value less than 1, the line item will be removed from the buylist.

Example Request

jQuery.ajax({
  url: "/api/v1/buylist",
  type: "PUT",
  dataType: 'json',
  contentType: 'application/json; charset=utf-8',
  data: JSON.stringify([{
    op: "replace",
    path:  "/buylists/0/line_items/124/qty",
    value: 4
  }])
});

Example Response

{
  "line_items": [
    {
      "id":              124,
      "name":            "Air Elemental",
      "qty":             4,
      "descriptors":     "Condition: Near Mint | Language: English",
      "price_cents":     19,
      "msrp_cents":      nil,
      "discount_cents":  nil,
      "variant_id":      9012,
      "product_id":      810,
      "is_tax_exempt":   false,
      "category_name":   "Tenth Edition"
    }
  ],
  "buylists": [
    {
      "id"               : 1,
      "type"             : "BuyOrder",
      "currency"         : "USD",
      "line_items_count" : 9,
      "total_cents"      : 4995,
      "links"            : {
        "checkout" : "/checkout/index",
      },
      "line_items" : [
        {
          "id":              123,
          "name":            "Adarkar Wastes",
          "qty":             2,
          "descriptors":     "Condition: Near Mint | Language: English",
          "price_cents":     133,
          "msrp_cents":      499,
          "discount_cents":  nil,
          "variant_id":      9001,
          "product_id":      809,
          "is_tax_exempt":   false,
          "category_name":   "Tenth Edition"
        },
        {
          "id":              124,
          "name":            "Air Elemental",
          "qty":             4,
          "descriptors":     "Condition: Near Mint | Language: English",
          "price_cents":     19,
          "msrp_cents":      nil,
          "discount_cents":  nil,
          "variant_id":      9012,
          "product_id":      810,
          "is_tax_exempt":   false,
          "category_name":   "Tenth Edition"
        }
      ]
    }
  ],
  "errors": []
}

Removing Buylist Items

Following REST conventions, a DELETE call to /api/v1/buylist/line_items/:id (where :id is the id of the line item) will remove the line item from the current buylist.

Response will be a 204 No Content on success.

Example Request

jQuery.ajax({
  url: "/api/v1/buylist/line_items/123",
  type: "DELETE",
  dataType: 'json',
  contentType: 'application/json; charset=utf-8'
});

Emptying the Buylst

A POST request to /api/v1/buylist/empty will clear the buylist of items.

Response will be your buylist, without any items.

Example Request

jQuery.ajax({
  url: "/api/v1/buylist/empty",
  type: "POST",
  dataType: "json",
  contentType: 'application/json; charset=utf-8'
});

Getting current Server Time

A GET request to /api/v1/server_time will return the current server time, with time zone offset, in ISO 8601 format.

Example Request

jQuery.ajax({
  url: "/api/v1/server_time",
  type: "GET",
  dataType: "json",
  contentType: 'application/json; charset=utf-8'
});

Example Response

{
  "server_time": "2013-11-12T10:57:26-08:00"
}