GetCandy

The GetCandy API

This is the documentation for version 1.0 of the API. Last update on May 21, 2020.

Base URL
http://localhost:3000/api/v1

Channels

Store channels

Get all channels

Gets a paginated list of all channel

URL parameters
  • includes string

    Comma separated includes for the resource

  • per_page number

    How many results per page

Responses
  • 200

    OK

Definition
GET http://localhost:3000/api/v1/channels
cURL example
curl \ -X GET http://localhost:3000/api/v1/channels \ -H "Content-Type: application/json"
Response example (200)
No content

Create a new channel

Create a new channel resource

Responses
  • 200 object

    OK

    • id string
    • name string
    • handle string
    • url string(uri)
    • default boolean
Definition
POST http://localhost:3000/api/v1/channels
cURL example
curl \ -X POST http://localhost:3000/api/v1/channels \ -H "Content-Type: application/json"
Response example (200)
{ "id": "y3g6v91o", "name": "Webstore", "handle": "webstore", "url": "https:\\/\\/storefront.test", "default": true }

Get the channel resource

URL parameters
  • channelId Required / string
  • includes string
Responses
  • 200 object

    OK

    • data object

      Available includes

      • products
      • categories
      • collections
      • discounts
      • shippingMethods
      • data.id string
      • data.name string
      • data.handle string
      • data.url string(uri)
      • data.default boolean
  • 404 object

    Not Found

    • error object
      • error.http_code integer
      • error.message string
Definition
GET http://localhost:3000/api/v1/channels/{channelId}
cURL example
curl \ -X GET http://localhost:3000/api/v1/channels/{channelId} \ -H "Content-Type: application/json"
Response example (200)
{ "data": { "id": "y3g6v91o", "name": "Webstore", "handle": "webstore", "url": "http://webstore.test", "default": true, "published_at": null }, "meta": { "lang": "en" } }
Response example (404)
{ "error": { "http_code": 404, "message": "Resource not found" } }

Update the channel resource

URL parameters
  • channelId Required / string
Responses
  • 200 object

    OK

    • data object

      Available includes

      • products
      • categories
      • collections
      • discounts
      • shippingMethods
      • data.id string
      • data.name string
      • data.handle string
      • data.url string(uri)
      • data.default boolean
  • 422 object

    Unprocessable Entity

    • handle array[string]
    • name array[string]
Definition
PUT http://localhost:3000/api/v1/channels/{channelId}
cURL example
curl \ -X PUT http://localhost:3000/api/v1/channels/{channelId} \ -H "Content-Type: application/json"
Response example (200)
{ "data": { "default": true, "name": "Webstore", "handle": "webstore", "id": "y3g6v91o", "url": "https:\\/\\/storefront.test" } }
Response example (422)
{ "handle": [ "string" ], "name": [ "string" ] }

Delete the channel resource

URL parameters
  • channelId Required / string
Responses
  • 204

    No Content

Definition
DELETE http://localhost:3000/api/v1/channels/{channelId}
cURL example
curl \ -X DELETE http://localhost:3000/api/v1/channels/{channelId} \ -H "Content-Type: application/json"
Response example (204)
No content

Categories

Catalogue Management

Return a paged array of categories

Returns a paginated resource of categories

URL parameters
  • full_response boolean
  • include string
  • tree boolean

    Whether response should be a node tree

Responses
  • 200

    OK

Definition
GET http://localhost:3000/api/v1/categories
cURL example
curl \ -X GET http://localhost:3000/api/v1/categories \ -H "Content-Type: application/json"
Response example (200)
No content

Create a new category

Creates a new category and returns it's resource.

Body
  • url Required / string
  • path Required / string
  • name Required / object
    • name.en Required / string
Responses
  • 200 object

    OK

    • data object
      Available includes
      • children
      • data.id string
      • data.sort string
      • data.products_count integer
      • data.children_count integer
      • data.left_pos integer
      • data.right_pos integer
      • data.name string
      • data.attribute_data object
      • data.children
      • data.channels
      • data.ancestors
      • data.routes
      • data.layout object
        • data.layout.data object
          • data.layout.data.id Required / string
          • data.layout.data.name Required / string
          • data.layout.data.handle Required / string
          • data.layout.data.type Required / string
      • data.assets object
        • data.assets.data array[object]
          • data.assets.data.id string
          • data.assets.data.title string
          • data.assets.data.type string
          • data.assets.data.caption string
          • data.assets.data.kind string
          • data.assets.data.external boolean
          • data.assets.data.position integer
          • data.assets.data.primary boolean
          • data.assets.data.url string
          • data.assets.data.sub_kind string
          • data.assets.data.extension string
          • data.assets.data.original_filename string
          • data.assets.data.size string
          • data.assets.data.width string
          • data.assets.data.height string
          • data.assets.data.transforms
          • data.assets.data.tags
      • data.primary_asset object
        • data.primary_asset.data object
          • data.primary_asset.data.id string
          • data.primary_asset.data.title string
          • data.primary_asset.data.type string
          • data.primary_asset.data.caption string
          • data.primary_asset.data.kind string
          • data.primary_asset.data.external boolean
          • data.primary_asset.data.position integer
          • data.primary_asset.data.primary boolean
          • data.primary_asset.data.url string
          • data.primary_asset.data.sub_kind string
          • data.primary_asset.data.extension string
          • data.primary_asset.data.original_filename string
          • data.primary_asset.data.size string
          • data.primary_asset.data.width string
          • data.primary_asset.data.height string
          • data.primary_asset.data.transforms
          • data.primary_asset.data.tags
      • data.attributes
      • data.customer_groups
      • data.products
  • 422 object

    Unprocessable Entity

    • error object
      • error.http_code integer
      • error.message string
Definition
POST http://localhost:3000/api/v1/categories
cURL example
curl \ -X POST http://localhost:3000/api/v1/categories \ -H "Content-Type: application/json" \ -d '{"url":"string","path":"string","name":{"en":"en"}}'
Request payload example
{ "url": "string", "path": "string", "name": { "en": "en" } }
Response example (200)
{ "data": { "primary_asset": { "data": { "extension": "extension", "kind": "kind", "caption": "caption", "title": "title", "type": "type", "url": "url", "external": true, "original_filename": "original_filename", "size": "size", "width": "width", "id": "id", "position": 5, "sub_kind": "sub_kind", "primary": true, "height": "height" } }, "children_count": 6, "products_count": 0, "sort": "sort", "left_pos": 1, "right_pos": 5, "layout": { "data": { "name": "name", "handle": "handle", "id": "id", "type": "type" } }, "assets": { "data": [ { "extension": "extension", "kind": "kind", "caption": "caption", "title": "title", "type": "type", "url": "url", "external": true, "original_filename": "original_filename", "size": "size", "width": "width", "id": "id", "position": 5, "sub_kind": "sub_kind", "primary": true, "height": "height" }, { "extension": "extension", "kind": "kind", "caption": "caption", "title": "title", "type": "type", "url": "url", "external": true, "original_filename": "original_filename", "size": "size", "width": "width", "id": "id", "position": 5, "sub_kind": "sub_kind", "primary": true, "height": "height" } ] }, "name": "name", "id": "id", "attribute_data": "{}" } }
Response example (422)
{ "url": [ "The url field is required." ] }

Return a single category

Returns a single category from a given ID

URL parameters
  • categoryId Required / string
  • includes string
Responses
  • 200 object

    OK

    • data object
      Available includes
      • children
      • data.id string
      • data.sort string
      • data.products_count integer
      • data.children_count integer
      • data.left_pos integer
      • data.right_pos integer
      • data.name string
      • data.attribute_data object
      • data.children
      • data.channels
      • data.ancestors
      • data.routes
      • data.layout object
        • data.layout.data object
          • data.layout.data.id Required / string
          • data.layout.data.name Required / string
          • data.layout.data.handle Required / string
          • data.layout.data.type Required / string
      • data.assets object
        • data.assets.data array[object]
          • data.assets.data.id string
          • data.assets.data.title string
          • data.assets.data.type string
          • data.assets.data.caption string
          • data.assets.data.kind string
          • data.assets.data.external boolean
          • data.assets.data.position integer
          • data.assets.data.primary boolean
          • data.assets.data.url string
          • data.assets.data.sub_kind string
          • data.assets.data.extension string
          • data.assets.data.original_filename string
          • data.assets.data.size string
          • data.assets.data.width string
          • data.assets.data.height string
          • data.assets.data.transforms
          • data.assets.data.tags
      • data.primary_asset object
        • data.primary_asset.data object
          • data.primary_asset.data.id string
          • data.primary_asset.data.title string
          • data.primary_asset.data.type string
          • data.primary_asset.data.caption string
          • data.primary_asset.data.kind string
          • data.primary_asset.data.external boolean
          • data.primary_asset.data.position integer
          • data.primary_asset.data.primary boolean
          • data.primary_asset.data.url string
          • data.primary_asset.data.sub_kind string
          • data.primary_asset.data.extension string
          • data.primary_asset.data.original_filename string
          • data.primary_asset.data.size string
          • data.primary_asset.data.width string
          • data.primary_asset.data.height string
          • data.primary_asset.data.transforms
          • data.primary_asset.data.tags
      • data.attributes
      • data.customer_groups
      • data.products
Definition
GET http://localhost:3000/api/v1/categories/{categoryId}
cURL example
curl \ -X GET http://localhost:3000/api/v1/categories/{categoryId} \ -H "Content-Type: application/json"
Response example (200)
{ "data": { "primary_asset": { "data": { "extension": "extension", "kind": "kind", "caption": "caption", "title": "title", "type": "type", "url": "url", "external": true, "original_filename": "original_filename", "size": "size", "width": "width", "id": "id", "position": 5, "sub_kind": "sub_kind", "primary": true, "height": "height" } }, "children_count": 6, "products_count": 0, "sort": "sort", "left_pos": 1, "right_pos": 5, "layout": { "data": { "name": "name", "handle": "handle", "id": "id", "type": "type" } }, "assets": { "data": [ { "extension": "extension", "kind": "kind", "caption": "caption", "title": "title", "type": "type", "url": "url", "external": true, "original_filename": "original_filename", "size": "size", "width": "width", "id": "id", "position": 5, "sub_kind": "sub_kind", "primary": true, "height": "height" }, { "extension": "extension", "kind": "kind", "caption": "caption", "title": "title", "type": "type", "url": "url", "external": true, "original_filename": "original_filename", "size": "size", "width": "width", "id": "id", "position": 5, "sub_kind": "sub_kind", "primary": true, "height": "height" } ] }, "name": "name", "id": "id", "attribute_data": "{}" } }

Update a category

Update a category using a given ID.

URL parameters
  • categoryId Required / string
Body
  • attributes Required / object
Responses
  • 200 object

    OK

    • data object
      Available includes
      • children
      • data.id string
      • data.sort string
      • data.products_count integer
      • data.children_count integer
      • data.left_pos integer
      • data.right_pos integer
      • data.name string
      • data.attribute_data object
      • data.children
      • data.channels
      • data.ancestors
      • data.routes
      • data.layout object
        • data.layout.data object
          • data.layout.data.id Required / string
          • data.layout.data.name Required / string
          • data.layout.data.handle Required / string
          • data.layout.data.type Required / string
      • data.assets object
        • data.assets.data array[object]
          • data.assets.data.id string
          • data.assets.data.title string
          • data.assets.data.type string
          • data.assets.data.caption string
          • data.assets.data.kind string
          • data.assets.data.external boolean
          • data.assets.data.position integer
          • data.assets.data.primary boolean
          • data.assets.data.url string
          • data.assets.data.sub_kind string
          • data.assets.data.extension string
          • data.assets.data.original_filename string
          • data.assets.data.size string
          • data.assets.data.width string
          • data.assets.data.height string
          • data.assets.data.transforms
          • data.assets.data.tags
      • data.primary_asset object
        • data.primary_asset.data object
          • data.primary_asset.data.id string
          • data.primary_asset.data.title string
          • data.primary_asset.data.type string
          • data.primary_asset.data.caption string
          • data.primary_asset.data.kind string
          • data.primary_asset.data.external boolean
          • data.primary_asset.data.position integer
          • data.primary_asset.data.primary boolean
          • data.primary_asset.data.url string
          • data.primary_asset.data.sub_kind string
          • data.primary_asset.data.extension string
          • data.primary_asset.data.original_filename string
          • data.primary_asset.data.size string
          • data.primary_asset.data.width string
          • data.primary_asset.data.height string
          • data.primary_asset.data.transforms
          • data.primary_asset.data.tags
      • data.attributes
      • data.customer_groups
      • data.products
  • 404 object

    Not Found

    • error object
      • error.http_code integer
      • error.message string
  • 422

    Unprocessable Entity

Definition
PUT http://localhost:3000/api/v1/categories/{categoryId}
cURL example
curl \ -X PUT http://localhost:3000/api/v1/categories/{categoryId} \ -H "Content-Type: application/json" \ -d '{"attributes":{}}'
Request payload example
{ "attributes": { } }
Response example (200)
{ "data": { "primary_asset": { "data": { "extension": "extension", "kind": "kind", "caption": "caption", "title": "title", "type": "type", "url": "url", "external": true, "original_filename": "original_filename", "size": "size", "width": "width", "id": "id", "position": 5, "sub_kind": "sub_kind", "primary": true, "height": "height" } }, "children_count": 6, "products_count": 0, "sort": "sort", "left_pos": 1, "right_pos": 5, "layout": { "data": { "name": "name", "handle": "handle", "id": "id", "type": "type" } }, "assets": { "data": [ { "extension": "extension", "kind": "kind", "caption": "caption", "title": "title", "type": "type", "url": "url", "external": true, "original_filename": "original_filename", "size": "size", "width": "width", "id": "id", "position": 5, "sub_kind": "sub_kind", "primary": true, "height": "height" }, { "extension": "extension", "kind": "kind", "caption": "caption", "title": "title", "type": "type", "url": "url", "external": true, "original_filename": "original_filename", "size": "size", "width": "width", "id": "id", "position": 5, "sub_kind": "sub_kind", "primary": true, "height": "height" } ] }, "name": "name", "id": "id", "attribute_data": "{}" } }
Response example (404)
{ "error": { "http_code": 404, "message": "Resource not found" } }
Response example (422)
No content

Get categories by parent id

Returns categories by a given parent ID.

URL parameters
  • parentId Required / string

    If omitted will return top level catgories

  • include string
Responses
  • 200

    OK

Definition
GET http://localhost:3000/api/v1/categories/parent/{parentId}
cURL example
curl \ -X GET http://localhost:3000/api/v1/categories/parent/{parentId} \ -H "Content-Type: application/json"
Response example (200)
No content

Reorder a category

Body
  • action string

    before, after, over

  • moved_node Required / string

    The ID of the category which moved

  • node Required / string

    The id of the category affected

Responses
  • 200 object

    OK

    • message string
  • 404 object

    Not Found

    • error object
      • error.http_code integer
      • error.message string
Definition
POST http://localhost:3000/api/v1/categories/reorder
cURL example
curl \ -X POST http://localhost:3000/api/v1/categories/reorder \ -H "Content-Type: application/json" \ -d '{"action":"string","moved_node":"string","node":"string"}'
Request payload example
{ "action": "string", "moved_node": "string", "node": "string" }
Response example (200)
{ "status": "success" }
Response example (404)
{ "error": { "http_code": 404, "message": "Resource not found" } }

Attach products

Attaches products to a category resource.

URL parameters
  • categoryId Required / string
Body
  • products array[object]
    • products.id string
    • products.position integer(int32)
  • sort_type string

    custom, minprice:asc, minprice:desc, sku:asc, sku:desc

Responses
  • 200 object

    OK

    • data object
      Available includes
      • children
      • data.id string
      • data.sort string
      • data.products_count integer
      • data.children_count integer
      • data.left_pos integer
      • data.right_pos integer
      • data.name string
      • data.attribute_data object
      • data.children
      • data.channels
      • data.ancestors
      • data.routes
      • data.layout object
        • data.layout.data object
          • data.layout.data.id Required / string
          • data.layout.data.name Required / string
          • data.layout.data.handle Required / string
          • data.layout.data.type Required / string
      • data.assets object
        • data.assets.data array[object]
          • data.assets.data.id string
          • data.assets.data.title string
          • data.assets.data.type string
          • data.assets.data.caption string
          • data.assets.data.kind string
          • data.assets.data.external boolean
          • data.assets.data.position integer
          • data.assets.data.primary boolean
          • data.assets.data.url string
          • data.assets.data.sub_kind string
          • data.assets.data.extension string
          • data.assets.data.original_filename string
          • data.assets.data.size string
          • data.assets.data.width string
          • data.assets.data.height string
          • data.assets.data.transforms
          • data.assets.data.tags
      • data.primary_asset object
        • data.primary_asset.data object
          • data.primary_asset.data.id string
          • data.primary_asset.data.title string
          • data.primary_asset.data.type string
          • data.primary_asset.data.caption string
          • data.primary_asset.data.kind string
          • data.primary_asset.data.external boolean
          • data.primary_asset.data.position integer
          • data.primary_asset.data.primary boolean
          • data.primary_asset.data.url string
          • data.primary_asset.data.sub_kind string
          • data.primary_asset.data.extension string
          • data.primary_asset.data.original_filename string
          • data.primary_asset.data.size string
          • data.primary_asset.data.width string
          • data.primary_asset.data.height string
          • data.primary_asset.data.transforms
          • data.primary_asset.data.tags
      • data.attributes
      • data.customer_groups
      • data.products
Definition
PUT http://localhost:3000/api/v1/categories/{categoryId}/products
cURL example
curl \ -X PUT http://localhost:3000/api/v1/categories/{categoryId}/products \ -H "Content-Type: application/json" \ -d '{"products":[{"id":"id","position":1}],"sort_type":"string"}'
Request payload example
{ "products": [ { "id": "id", "position": 1 } ], "sort_type": "string" }
Response example (200)
{ "data": { "primary_asset": { "data": { "extension": "extension", "kind": "kind", "caption": "caption", "title": "title", "type": "type", "url": "url", "external": true, "original_filename": "original_filename", "size": "size", "width": "width", "id": "id", "position": 5, "sub_kind": "sub_kind", "primary": true, "height": "height" } }, "children_count": 6, "products_count": 0, "sort": "sort", "left_pos": 1, "right_pos": 5, "layout": { "data": { "name": "name", "handle": "handle", "id": "id", "type": "type" } }, "assets": { "data": [ { "extension": "extension", "kind": "kind", "caption": "caption", "title": "title", "type": "type", "url": "url", "external": true, "original_filename": "original_filename", "size": "size", "width": "width", "id": "id", "position": 5, "sub_kind": "sub_kind", "primary": true, "height": "height" }, { "extension": "extension", "kind": "kind", "caption": "caption", "title": "title", "type": "type", "url": "url", "external": true, "original_filename": "original_filename", "size": "size", "width": "width", "id": "id", "position": 5, "sub_kind": "sub_kind", "primary": true, "height": "height" } ] }, "name": "name", "id": "id", "attribute_data": "{}" } }

Attach channels to a category

Attaches channels to a catagory

URL parameters
  • categoryId Required / string
Body
  • channels array[object]
    • channels.id Required / string
    • channels.published_at Required / string
Responses
  • 200 object

    OK

    • data object
      Available includes
      • children
      • data.id string
      • data.sort string
      • data.products_count integer
      • data.children_count integer
      • data.left_pos integer
      • data.right_pos integer
      • data.name string
      • data.attribute_data object
      • data.children
      • data.channels
      • data.ancestors
      • data.routes
      • data.layout object
        • data.layout.data object
          • data.layout.data.id Required / string
          • data.layout.data.name Required / string
          • data.layout.data.handle Required / string
          • data.layout.data.type Required / string
      • data.assets object
        • data.assets.data array[object]
          • data.assets.data.id string
          • data.assets.data.title string
          • data.assets.data.type string
          • data.assets.data.caption string
          • data.assets.data.kind string
          • data.assets.data.external boolean
          • data.assets.data.position integer
          • data.assets.data.primary boolean
          • data.assets.data.url string
          • data.assets.data.sub_kind string
          • data.assets.data.extension string
          • data.assets.data.original_filename string
          • data.assets.data.size string
          • data.assets.data.width string
          • data.assets.data.height string
          • data.assets.data.transforms
          • data.assets.data.tags
      • data.primary_asset object
        • data.primary_asset.data object
          • data.primary_asset.data.id string
          • data.primary_asset.data.title string
          • data.primary_asset.data.type string
          • data.primary_asset.data.caption string
          • data.primary_asset.data.kind string
          • data.primary_asset.data.external boolean
          • data.primary_asset.data.position integer
          • data.primary_asset.data.primary boolean
          • data.primary_asset.data.url string
          • data.primary_asset.data.sub_kind string
          • data.primary_asset.data.extension string
          • data.primary_asset.data.original_filename string
          • data.primary_asset.data.size string
          • data.primary_asset.data.width string
          • data.primary_asset.data.height string
          • data.primary_asset.data.transforms
          • data.primary_asset.data.tags
      • data.attributes
      • data.customer_groups
      • data.products
  • 404 object

    Not Found

    • error object
      • error.http_code integer
      • error.message string
Definition
POST http://localhost:3000/api/v1/categories/{categoryId}/channels
cURL example
curl \ -X POST http://localhost:3000/api/v1/categories/{categoryId}/channels \ -H "Content-Type: application/json" \ -d '{"channels":[{"id":"id","published_at":"published_at"}]}'
Request payload example
{ "channels": [ { "id": "id", "published_at": "published_at" } ] }
Response example (200)
{ "data": { "primary_asset": { "data": { "extension": "extension", "kind": "kind", "caption": "caption", "title": "title", "type": "type", "url": "url", "external": true, "original_filename": "original_filename", "size": "size", "width": "width", "id": "id", "position": 5, "sub_kind": "sub_kind", "primary": true, "height": "height" } }, "children_count": 6, "products_count": 0, "sort": "sort", "left_pos": 1, "right_pos": 5, "layout": { "data": { "name": "name", "handle": "handle", "id": "id", "type": "type" } }, "assets": { "data": [ { "extension": "extension", "kind": "kind", "caption": "caption", "title": "title", "type": "type", "url": "url", "external": true, "original_filename": "original_filename", "size": "size", "width": "width", "id": "id", "position": 5, "sub_kind": "sub_kind", "primary": true, "height": "height" }, { "extension": "extension", "kind": "kind", "caption": "caption", "title": "title", "type": "type", "url": "url", "external": true, "original_filename": "original_filename", "size": "size", "width": "width", "id": "id", "position": 5, "sub_kind": "sub_kind", "primary": true, "height": "height" } ] }, "name": "name", "id": "id", "attribute_data": "{}" } }
Response example (404)
{ "error": { "http_code": 404, "message": "Resource not found" } }

Attach customer groups to a category

Attaches customer groups to a category resource.

URL parameters
  • categoryId Required / string
Body
  • groups array[object]
    • groups.id string
    • groups.visible boolean
    • groups.purchasable boolean
Responses
  • 200 object

    OK

    • data object
      Available includes
      • children
      • data.id string
      • data.sort string
      • data.products_count integer
      • data.children_count integer
      • data.left_pos integer
      • data.right_pos integer
      • data.name string
      • data.attribute_data object
      • data.children
      • data.channels
      • data.ancestors
      • data.routes
      • data.layout object
        • data.layout.data object
          • data.layout.data.id Required / string
          • data.layout.data.name Required / string
          • data.layout.data.handle Required / string
          • data.layout.data.type Required / string
      • data.assets object
        • data.assets.data array[object]
          • data.assets.data.id string
          • data.assets.data.title string
          • data.assets.data.type string
          • data.assets.data.caption string
          • data.assets.data.kind string
          • data.assets.data.external boolean
          • data.assets.data.position integer
          • data.assets.data.primary boolean
          • data.assets.data.url string
          • data.assets.data.sub_kind string
          • data.assets.data.extension string
          • data.assets.data.original_filename string
          • data.assets.data.size string
          • data.assets.data.width string
          • data.assets.data.height string
          • data.assets.data.transforms
          • data.assets.data.tags
      • data.primary_asset object
        • data.primary_asset.data object
          • data.primary_asset.data.id string
          • data.primary_asset.data.title string
          • data.primary_asset.data.type string
          • data.primary_asset.data.caption string
          • data.primary_asset.data.kind string
          • data.primary_asset.data.external boolean
          • data.primary_asset.data.position integer
          • data.primary_asset.data.primary boolean
          • data.primary_asset.data.url string
          • data.primary_asset.data.sub_kind string
          • data.primary_asset.data.extension string
          • data.primary_asset.data.original_filename string
          • data.primary_asset.data.size string
          • data.primary_asset.data.width string
          • data.primary_asset.data.height string
          • data.primary_asset.data.transforms
          • data.primary_asset.data.tags
      • data.attributes
      • data.customer_groups
      • data.products
  • 404 object

    Not Found

    • object
      • .error object
        • .error.http_code integer
        • .error.message string
Definition
POST http://localhost:3000/api/v1/categories/{categoryId}/customer-groups
cURL example
curl \ -X POST http://localhost:3000/api/v1/categories/{categoryId}/customer-groups \ -H "Content-Type: application/json" \ -d '{"groups":[{"purchasable":true,"visible":true,"id":"id"}]}'
Request payload example
{ "groups": [ { "purchasable": true, "visible": true, "id": "id" } ] }
Response example (200)
{ "data": { "primary_asset": { "data": { "extension": "extension", "kind": "kind", "caption": "caption", "title": "title", "type": "type", "url": "url", "external": true, "original_filename": "original_filename", "size": "size", "width": "width", "id": "id", "position": 5, "sub_kind": "sub_kind", "primary": true, "height": "height" } }, "children_count": 6, "products_count": 0, "sort": "sort", "left_pos": 1, "right_pos": 5, "layout": { "data": { "name": "name", "handle": "handle", "id": "id", "type": "type" } }, "assets": { "data": [ { "extension": "extension", "kind": "kind", "caption": "caption", "title": "title", "type": "type", "url": "url", "external": true, "original_filename": "original_filename", "size": "size", "width": "width", "id": "id", "position": 5, "sub_kind": "sub_kind", "primary": true, "height": "height" }, { "extension": "extension", "kind": "kind", "caption": "caption", "title": "title", "type": "type", "url": "url", "external": true, "original_filename": "original_filename", "size": "size", "width": "width", "id": "id", "position": 5, "sub_kind": "sub_kind", "primary": true, "height": "height" } ] }, "name": "name", "id": "id", "attribute_data": "{}" } }
Response example (404)
{ "": { "error": { "http_code": 404, "message": "Resource not found" } } }

Update a category layout

Attaches layouts to a category resource

URL parameters
  • categoryId Required / string
Body
  • layout_id string
Responses
  • 200 object

    OK

    • data object
      Available includes
      • children
      • data.id string
      • data.sort string
      • data.products_count integer
      • data.children_count integer
      • data.left_pos integer
      • data.right_pos integer
      • data.name string
      • data.attribute_data object
      • data.children
      • data.channels
      • data.ancestors
      • data.routes
      • data.layout object
        • data.layout.data object
          • data.layout.data.id Required / string
          • data.layout.data.name Required / string
          • data.layout.data.handle Required / string
          • data.layout.data.type Required / string
      • data.assets object
        • data.assets.data array[object]
          • data.assets.data.id string
          • data.assets.data.title string
          • data.assets.data.type string
          • data.assets.data.caption string
          • data.assets.data.kind string
          • data.assets.data.external boolean
          • data.assets.data.position integer
          • data.assets.data.primary boolean
          • data.assets.data.url string
          • data.assets.data.sub_kind string
          • data.assets.data.extension string
          • data.assets.data.original_filename string
          • data.assets.data.size string
          • data.assets.data.width string
          • data.assets.data.height string
          • data.assets.data.transforms
          • data.assets.data.tags
      • data.primary_asset object
        • data.primary_asset.data object
          • data.primary_asset.data.id string
          • data.primary_asset.data.title string
          • data.primary_asset.data.type string
          • data.primary_asset.data.caption string
          • data.primary_asset.data.kind string
          • data.primary_asset.data.external boolean
          • data.primary_asset.data.position integer
          • data.primary_asset.data.primary boolean
          • data.primary_asset.data.url string
          • data.primary_asset.data.sub_kind string
          • data.primary_asset.data.extension string
          • data.primary_asset.data.original_filename string
          • data.primary_asset.data.size string
          • data.primary_asset.data.width string
          • data.primary_asset.data.height string
          • data.primary_asset.data.transforms
          • data.primary_asset.data.tags
      • data.attributes
      • data.customer_groups
      • data.products
Definition
POST http://localhost:3000/api/v1/categories/{categoryId}/layouts
cURL example
curl \ -X POST http://localhost:3000/api/v1/categories/{categoryId}/layouts \ -H "Content-Type: application/json" \ -d '{"layout_id":"string"}'
Request payload example
{ "layout_id": "string" }
Response example (200)
{ "data": { "primary_asset": { "data": { "extension": "extension", "kind": "kind", "caption": "caption", "title": "title", "type": "type", "url": "url", "external": true, "original_filename": "original_filename", "size": "size", "width": "width", "id": "id", "position": 5, "sub_kind": "sub_kind", "primary": true, "height": "height" } }, "children_count": 6, "products_count": 0, "sort": "sort", "left_pos": 1, "right_pos": 5, "layout": { "data": { "name": "name", "handle": "handle", "id": "id", "type": "type" } }, "assets": { "data": [ { "extension": "extension", "kind": "kind", "caption": "caption", "title": "title", "type": "type", "url": "url", "external": true, "original_filename": "original_filename", "size": "size", "width": "width", "id": "id", "position": 5, "sub_kind": "sub_kind", "primary": true, "height": "height" }, { "extension": "extension", "kind": "kind", "caption": "caption", "title": "title", "type": "type", "url": "url", "external": true, "original_filename": "original_filename", "size": "size", "width": "width", "id": "id", "position": 5, "sub_kind": "sub_kind", "primary": true, "height": "height" } ] }, "name": "name", "id": "id", "attribute_data": "{}" } }

Update a category's routes

Attaches routes to a category resource.

URL parameters
  • categoryId Required / string
Body
  • redirect boolean
  • description string
  • slug string
  • locale string
Responses
  • 200 object

    OK

    • data object
      Available includes
      • children
      • data.id string
      • data.sort string
      • data.products_count integer
      • data.children_count integer
      • data.left_pos integer
      • data.right_pos integer
      • data.name string
      • data.attribute_data object
      • data.children
      • data.channels
      • data.ancestors
      • data.routes
      • data.layout object
        • data.layout.data object
          • data.layout.data.id Required / string
          • data.layout.data.name Required / string
          • data.layout.data.handle Required / string
          • data.layout.data.type Required / string
      • data.assets object
        • data.assets.data array[object]
          • data.assets.data.id string
          • data.assets.data.title string
          • data.assets.data.type string
          • data.assets.data.caption string
          • data.assets.data.kind string
          • data.assets.data.external boolean
          • data.assets.data.position integer
          • data.assets.data.primary boolean
          • data.assets.data.url string
          • data.assets.data.sub_kind string
          • data.assets.data.extension string
          • data.assets.data.original_filename string
          • data.assets.data.size string
          • data.assets.data.width string
          • data.assets.data.height string
          • data.assets.data.transforms
          • data.assets.data.tags
      • data.primary_asset object
        • data.primary_asset.data object
          • data.primary_asset.data.id string
          • data.primary_asset.data.title string
          • data.primary_asset.data.type string
          • data.primary_asset.data.caption string
          • data.primary_asset.data.kind string
          • data.primary_asset.data.external boolean
          • data.primary_asset.data.position integer
          • data.primary_asset.data.primary boolean
          • data.primary_asset.data.url string
          • data.primary_asset.data.sub_kind string
          • data.primary_asset.data.extension string
          • data.primary_asset.data.original_filename string
          • data.primary_asset.data.size string
          • data.primary_asset.data.width string
          • data.primary_asset.data.height string
          • data.primary_asset.data.transforms
          • data.primary_asset.data.tags
      • data.attributes
      • data.customer_groups
      • data.products
  • 404 object

    Not Found

    • error object
      • error.http_code integer
      • error.message string
Definition
POST http://localhost:3000/api/v1/categories/{categoryId}/routes
cURL example
curl \ -X POST http://localhost:3000/api/v1/categories/{categoryId}/routes \ -H "Content-Type: application/json" \ -d '{"redirect":true,"description":"string","slug":"string","locale":"string"}'
Request payload example
{ "redirect": true, "description": "string", "slug": "string", "locale": "string" }
Response example (200)
{ "data": { "primary_asset": { "data": { "extension": "extension", "kind": "kind", "caption": "caption", "title": "title", "type": "type", "url": "url", "external": true, "original_filename": "original_filename", "size": "size", "width": "width", "id": "id", "position": 5, "sub_kind": "sub_kind", "primary": true, "height": "height" } }, "children_count": 6, "products_count": 0, "sort": "sort", "left_pos": 1, "right_pos": 5, "layout": { "data": { "name": "name", "handle": "handle", "id": "id", "type": "type" } }, "assets": { "data": [ { "extension": "extension", "kind": "kind", "caption": "caption", "title": "title", "type": "type", "url": "url", "external": true, "original_filename": "original_filename", "size": "size", "width": "width", "id": "id", "position": 5, "sub_kind": "sub_kind", "primary": true, "height": "height" }, { "extension": "extension", "kind": "kind", "caption": "caption", "title": "title", "type": "type", "url": "url", "external": true, "original_filename": "original_filename", "size": "size", "width": "width", "id": "id", "position": 5, "sub_kind": "sub_kind", "primary": true, "height": "height" } ] }, "name": "name", "id": "id", "attribute_data": "{}" } }
Response example (404)
{ "error": { "http_code": 404, "message": "Resource not found" } }

Orders

Order Processing

Get orders

If you're an admin user you will be able to see all orders, otherwise only the current users orders will be returned.

URL parameters
  • include string
Responses
  • 200

    OK

Definition
GET http://localhost:3000/api/v1/orders
cURL example
curl \ -X GET http://localhost:3000/api/v1/orders \ -H "Content-Type: application/json"
Response example (200)
No content

Create Order

Create an Order from a Basket instance

Body
  • basket_id Required / string
Responses
  • 200 object

    OK

    • data
  • 403 object

    Forbidden

    • error object
      • error.http_code integer
      • error.message string
  • 422 object

    Unprocessable Entity

    • error object
      • error.http_code integer
      • error.message string
Definition
POST http://localhost:3000/api/v1/orders
cURL example
curl \ -X POST http://localhost:3000/api/v1/orders \ -H "Content-Type: application/json" \ -d '{"basket_id":"string"}'
Request payload example
{ "basket_id": "string" }
Response example (200)
{ "data": "string" }
Response example (403)
{ "http_code": 403, "message": "This basket already has an order that has been placed" }
Response example (422)
{ "basket_id": [ "The basket id field is required." ] }

Get Order

Get an Order by it's ID.

You must be an admin or owner to retrieve the order, otherwise you'll get a 404.

URL parameters
  • orderId Required / string
Responses
  • 200 object

    OK

    • data
  • 404 object

    Not Found

    • error object
      • error.http_code integer
      • error.message string
Definition
GET http://localhost:3000/api/v1/orders/{orderId}
cURL example
curl \ -X GET http://localhost:3000/api/v1/orders/{orderId} \ -H "Content-Type: application/json"
Response example (200)
{ "data": "string" }
Response example (404)
{ "error": { "http_code": 404, "message": "Resource not found" } }

Update Order

Update an Order

URL parameters
  • orderId Required / string
  • include string
Body
  • tracking_no string
  • status string

    Corresponds to status set in config

  • send_emails boolean
Responses
  • 200 object

    OK

    • data
  • 404 object

    Not Found

    • data object
      • data.id string
      • data.display_id string
      • data.sub_total integer(int32)
      • data.type string
      • data.delivery_total integer(int32)
      • data.discount_total integer
      • data.tax_total integer(int32)
      • data.shipping_preference string
      • data.shipping_method string
      • data.order_total integer(int32)
      • data.reference string
      • data.customer_reference string
      • data.invoice_reference string
      • data.vat_no string
      • data.tracking_no string
      • data.dispatched_at string
      • data.currency string
      • data.customer_name string
      • data.contact_details object
        • data.contact_details.phone string
        • data.contact_details.email string
      • data.billing_details object
        • data.billing_details.phone string
        • data.billing_details.email string
        • data.billing_details.firstname string
        • data.billing_details.lastname string
        • data.billing_details.address string
        • data.billing_details.address_two string
        • data.billing_details.address_three string
        • data.billing_details.city string
        • data.billing_details.county string
        • data.billing_details.state string
        • data.billing_details.country string
        • data.billing_details.zip string
      • data.shipping_details object
        • data.shipping_details.phone string
        • data.shipping_details.email string
        • data.shipping_details.firstname string
        • data.shipping_details.lastname string
        • data.shipping_details.address string
        • data.shipping_details.address_two string
        • data.shipping_details.address_three string
        • data.shipping_details.city string
        • data.shipping_details.county string
        • data.shipping_details.state string
        • data.shipping_details.country string
        • data.shipping_details.zip string
      • data.status string
      • data.created_at string
      • data.updated_at string
      • data.notes string
      • data.meta array[object]
      • data.basket object
        • data.basket.data object
          • data.basket.data.id string
          • data.basket.data.total number
          • data.basket.data.sub_total number
          • data.basket.data.tax_total number
          • data.basket.data.discount_total number(float)
          • data.basket.data.changed boolean
          • data.basket.data.has_exclusions boolean
          • data.basket.data.meta object
          • data.basket.data.lines
          • data.basket.data.order object
            • data.basket.data.order.data
      • data.discounts string
      • data.transactions
      • data.lines object
        • data.lines.data array[object]
          • data.lines.data.id string
          • data.lines.data.quantity integer
          • data.lines.data.line_total integer
          • data.lines.data.discount_total integer
          • data.lines.data.delivery_total integer
          • data.lines.data.unit_price integer
          • data.lines.data.unit_qty integer
          • data.lines.data.tax_total integer
          • data.lines.data.tax_rate integer
          • data.lines.data.description string
          • data.lines.data.option string
          • data.lines.data.sku string
          • data.lines.data.is_shipping boolean
          • data.lines.data.is_manual boolean
          • data.lines.data.meta object
      • data.shipping object
        • data.shipping.data object
          • data.shipping.data.id string
          • data.shipping.data.quantity integer
          • data.shipping.data.line_total integer
          • data.shipping.data.discount_total integer
          • data.shipping.data.delivery_total integer
          • data.shipping.data.unit_price integer
          • data.shipping.data.unit_qty integer
          • data.shipping.data.tax_total integer
          • data.shipping.data.tax_rate integer
          • data.shipping.data.description string
          • data.shipping.data.option string
          • data.shipping.data.sku string
          • data.shipping.data.is_shipping boolean
          • data.shipping.data.is_manual boolean
          • data.shipping.data.meta object
      • data.logs object
        • data.logs.data array[object]
          • data.logs.data.id string
          • data.logs.data.type string
          • data.logs.data.description string
          • data.logs.data.properties string
          • data.logs.data.created_at string
          • data.logs.data.user object
            • data.logs.data.user.data object
              • data.logs.data.user.data.id string
              • data.logs.data.user.data.name string
              • data.logs.data.user.data.email string
      • data.user object
        • data.user.data object
          • data.user.data.id string
          • data.user.data.name string
          • data.user.data.email string
Definition
PUT http://localhost:3000/api/v1/orders/{orderId}
cURL example
curl \ -X PUT http://localhost:3000/api/v1/orders/{orderId} \ -H "Content-Type: application/json" \ -d '{"tracking_no":"string","status":"string","send_emails":true}'
Request payload example
{ "tracking_no": "string", "status": "string", "send_emails": true }
Response example (200)
{ "data": "string" }
Response example (404)
{ "data": { "delivery_total": 1307, "basket": { "data": { "has_exclusions": true, "total": 6.027456183070403, "discount_total": 5.637377, "tax_total": 5.962133916683182, "meta": "{}", "sub_total": "1.4658129805029452", "id": "id", "changed": true } }, "discount_total": 0, "billing_details": { "zip": "zip", "country": "country", "firstname": "firstname", "address": "address", "address_three": "address_three", "phone": "phone", "city": "city", "county": "county", "state": "state", "address_two": "address_two", "email": "email", "lastname": "lastname" }, "tax_total": 1307, "notes": "notes", "display_id": "#ORD-123456", "dispatched_at": "dispatched_at", "shipping_details": { "zip": "zip", "country": "country", "firstname": "firstname", "address": "address", "address_three": "address_three", "phone": "phone", "city": "city", "county": "county", "state": "state", "address_two": "address_two", "email": "email", "lastname": "lastname" }, "created_at": "created_at", "type": "SagePay", "reference": "CUSTOM-REFERENCE", "updated_at": "updated_at", "discounts": "discounts", "shipping": { "data": { "delivery_total": 3, "discount_total": 9, "quantity": 2, "tax_total": 7, "unit_qty": 4, "is_shipping": true, "is_manual": true, "description": "description", "unit_price": 2, "line_total": 7, "tax_rate": 1, "meta": "{}", "id": "id", "sku": "sku", "option": "option" } }, "shipping_method": "Standard Delivery", "customer_reference": "customer_reference", "invoice_reference": "#INV-1234567", "currency": "GBP", "id": "123RFesfes356P", "lines": { "data": [ { "delivery_total": 3, "discount_total": 9, "quantity": 2, "tax_total": 7, "unit_qty": 4, "is_shipping": true, "is_manual": true, "description": "description", "unit_price": 2, "line_total": 7, "tax_rate": 1, "meta": "{}", "id": "id", "sku": "sku", "option": "option" }, { "delivery_total": 3, "discount_total": 9, "quantity": 2, "tax_total": 7, "unit_qty": 4, "is_shipping": true, "is_manual": true, "description": "description", "unit_price": 2, "line_total": 7, "tax_rate": 1, "meta": "{}", "id": "id", "sku": "sku", "option": "option" } ] }, "logs": { "data": [ { "description": "description", "created_at": "created_at", "id": "id", "type": "type", "user": { "data": { "name": "name", "id": "id", "email": "email" } }, "properties": "properties" }, { "description": "description", "created_at": "created_at", "id": "id", "type": "type", "user": { "data": { "name": "name", "id": "id", "email": "email" } }, "properties": "properties" } ] }, "contact_details": { "phone": "12345678910", "email": "example@example.com" }, "shipping_preference": "shipping_preference", "tracking_no": "tracking_no", "meta": [ "{}", "{}" ], "sub_total": 12345, "order_total": 7845, "customer_name": "Thanos", "user": { "data": { "name": "name", "id": "id", "email": "email" } }, "vat_no": "vat_no", "status": "payment-received" } }

Get order types

Returns all order types currently in the system

Responses
  • 200 object

    OK

    • data array[object]
      • data.label string
Definition
GET http://localhost:3000/api/v1/orders/types
cURL example
curl \ -X GET http://localhost:3000/api/v1/orders/types \ -H "Content-Type: application/json"
Response example (200)
{ "data": [ { "label": "Collection" }, { "label": "PayPal" }, { "label": "SagePay" } ] }

Processes an order on the API

Body
  • payment_type_id string
  • payment_type string
  • order_id Required / string
  • payment_token Required / string
  • customer_reference string
  • meta array[object]
    • meta. string
  • notes string
  • company_name string
  • data array[]
Responses
  • 200 object

    OK

    • data
  • 403 object

    Forbidden

    • error object
      • error.http_code integer
      • error.message string
  • 404 object

    Not Found

    • error object
      • error.http_code integer
      • error.message string
  • 422 object

    Unprocessable Entity

    • error object
      • error.http_code integer
      • error.message string
Definition
POST http://localhost:3000/api/v1/orders/process
cURL example
curl \ -X POST http://localhost:3000/api/v1/orders/process \ -H "Content-Type: application/json" \ -d '{"payment_type_id":"string","payment_type":"string","order_id":"string","payment_token":"string","customer_reference":"string","meta":[{"":"string"}],"notes":"string","company_name":"string","data":["string"]}'
Request payload example
{ "payment_type_id": "string", "payment_type": "string", "order_id": "string", "payment_token": "string", "customer_reference": "string", "meta": [ { "": "string" } ], "notes": "string", "company_name": "string", "data": [ "string" ] }
Response example (200)
{ "data": "string" }
Response example (403)
{ "error": { "http_code": 404, "message": "Resource not found" } }
Response example (404)
{ "error": { "http_code": 404, "message": "Resource not found" } }
Response example (422)
{ "error": { "http_code": 404, "message": "Resource not found" } }

Get order status preview email

This endpoint will get a HTML email preview for an order status, this is useful if you want to be able to see what email will be sent out for the corresponding Order status.

Mailers for each order status should be stored in the getcandy config under orders.mailers

URL parameters
  • status Required / string
  • id Required / string

    An order id to use for the template

Responses
  • 200 object

    OK

    • data object
      • data.subject string
      • data.content string
  • 422 object

    Unprocessable Entity

    This will happen if the passed order id cannot be found

    • id array[string]
Definition
GET http://localhost:3000/api/v1/orders/email-preview/{status}
cURL example
curl \ -X GET http://localhost:3000/api/v1/orders/email-preview/{status}?id=string \ -H "Content-Type: application/json"
Response example (200)
{ "data": { "subject": "subject", "content": "content" } }
Response example (422)
{ "id": [ "string" ] }

Get Order export

Export orders into a base64 encoded string

URL parameters
  • orders Required / string

    Colon seperated order IDs

    Values are 1sfe534r4ref:934redfk.

  • format Required / string

    The export format, must be present in config

Responses
  • 200 object

    OK

    • data object
      • data.format string
      • data.content string
Definition
GET http://localhost:3000/api/v1/orders/bulk
cURL example
curl \ -X GET http://localhost:3000/api/v1/orders/bulk?orders=1sfe534r4ref%3A934redfk&format=string \ -H "Content-Type: application/json"
Response example (200)
{ "data": { "format": "csv", "content": "ZW1haWwsZG..." } }

Bulk update orders

Allows you to bulk update a field across multiple Orders.

You must have the correct priviledges to perform this action.

Body
  • orders Required / array[string]
  • field Required / string
  • value string
  • send_emails boolean

    Whether to send any mailers when changing status

Responses
  • 204

    No Content

  • 400 object

    Bad Request

    • error object
      • error.http_code integer
      • error.message string
  • 422 object

    Unprocessable Entity

    • orders array[string]
    • field array[string]
    • value array[string]
Definition
POST http://localhost:3000/api/v1/orders/bulk
cURL example
curl \ -X POST http://localhost:3000/api/v1/orders/bulk \ -H "Content-Type: application/json" \ -d '{"orders":["string"],"field":"string","value":"string","send_emails":true}'
Request payload example
{ "orders": [ "string" ], "field": "string", "value": "string", "send_emails": true }
Response example (204)
No content
Response example (400)
{ "http_code": 400, "message": "Unable to update field" }
Response example (422)
{ "orders": [ "string" ], "field": [ "string" ], "value": [ "string" ] }

Expire an Order

Sets an order to be expired. You must have the correct priviledges to perform this action. Once an order is expired, it will no longer appear in results unless performed by an admin or in the hub.

URL parameters
  • orderId Required / string
Responses
  • 204

    No Content

  • 404 object

    Not Found

    • error object
      • error.http_code integer
      • error.message string
Definition
POST http://localhost:3000/api/v1/orders/{orderId}/expire
cURL example
curl \ -X POST http://localhost:3000/api/v1/orders/{orderId}/expire \ -H "Content-Type: application/json"
Response example (204)
No content
Response example (404)
{ "error": { "http_code": 404, "message": "Resource not found" } }

Update shipping address

Update an orders shipping address

URL parameters
  • orderId Required / string
Body
  • phone string
  • email string
  • firstname string
  • lastname string
  • address string
  • address_two string
  • address_three string
  • city string
  • county string
  • state string
  • country string
  • zip string
Responses
  • 200 object

    OK

    • data
  • 404 object

    Not Found

    • error object
      • error.http_code integer
      • error.message string
Definition
PUT http://localhost:3000/api/v1/orders/{orderId}/shipping/address
cURL example
curl \ -X PUT http://localhost:3000/api/v1/orders/{orderId}/shipping/address \ -H "Content-Type: application/json" \ -d '{"phone":"string","email":"string","firstname":"string","lastname":"string","address":"string","address_two":"string","address_three":"string","city":"string","county":"string","state":"string","country":"string","zip":"string"}'
Request payload example
{ "phone": "string", "email": "string", "firstname": "string", "lastname": "string", "address": "string", "address_two": "string", "address_three": "string", "city": "string", "county": "string", "state": "string", "country": "string", "zip": "string" }
Response example (200)
{ "data": "string" }
Response example (404)
{ "error": { "http_code": 404, "message": "Resource not found" } }

Get Order Shipping Methods

This will return a list of all ShippingMethod's that are available for this order.

URL parameters
  • orderId Required / string
Responses
  • 200

    OK

Definition
GET http://localhost:3000/api/v1/orders/{orderId}/shipping/methods
cURL example
curl \ -X GET http://localhost:3000/api/v1/orders/{orderId}/shipping/methods \ -H "Content-Type: application/json"
Response example (200)
{ "data": [ { "id": "awd2qwda0d", "rate": 795, "tax": 159, "fixed": true, "min_basket": 0, "min_basket_tax": 0, "min_weight": "0.00000", "weight_unit": "kg", "min_height": "0.00000", "height_unit": "cm", "min_width": "0.00000", "width_unit": "cm", "min_depth": "0.00000", "depth_unit": "cm", "min_volume": "0.00000", "volume_unit": "l", "method": { "data": { "id": "v8l4pl01", "type": "regional", "name": "Standard Delivery", "description": "Method Description", "code": "ND" } }, "zone": { "data": { "id": "p09prlrn", "name": "Region One" } } }, { "id": "92owerfd3", "rate": 3000, "tax": 600, "fixed": true, "min_basket": 0, "min_basket_tax": 0, "min_weight": "0.00000", "weight_unit": "kg", "min_height": "0.00000", "height_unit": "cm", "min_width": "0.00000", "width_unit": "cm", "min_depth": "0.00000", "depth_unit": "cm", "min_volume": "0.00000", "volume_unit": "l", "method": { "data": { "id": "awd2e15gtfd", "type": "regional", "name": "Next Working Day", "description": "Next day delivery - excluding weekends", "code": "ND1030" } }, "zone": { "data": { "id": "0o3wesde3", "name": "Region One" } } }, { "id": "eqdas9932", "rate": 2000, "tax": 400, "fixed": true, "min_basket": 0, "min_basket_tax": 0, "min_weight": "0.00000", "weight_unit": "kg", "min_height": "0.00000", "height_unit": "cm", "min_width": "0.00000", "width_unit": "cm", "min_depth": "0.00000", "depth_unit": "cm", "min_volume": "0.00000", "volume_unit": "l", "method": { "data": { "id": "wz6d39dj", "type": "regional", "name": "Next Working Day - Before 1pm", "description": "Next working day before 1pm", "code": "ND1230" } }, "zone": { "data": { "id": "12qewdfs4", "name": "Region One" } } } ] }

Add shipping cost

Adds a shipping cost to an Order

URL parameters
  • orderId Required / string
Body
  • price_id string

    The ShippingPrice id to associate

Responses
  • 200 object

    OK

    • data
  • 422 object

    Unprocessable Entity

    • price_id array[string]
Definition
PUT http://localhost:3000/api/v1/orders/{orderId}/shipping/cost
cURL example
curl \ -X PUT http://localhost:3000/api/v1/orders/{orderId}/shipping/cost \ -H "Content-Type: application/json" \ -d '{"price_id":"string"}'
Request payload example
{ "price_id": "string" }
Response example (200)
{ "data": "string" }
Response example (422)
{ "price_id": [ "Please choose a shipping option" ] }

Add contact details

Add contact details to an order

URL parameters
  • orderId Required / string
Body
  • email string
  • phone string
Responses
  • 200 object

    OK

    • data
Definition
PUT http://localhost:3000/api/v1/orders/{orderId}/contact
cURL example
curl \ -X PUT http://localhost:3000/api/v1/orders/{orderId}/contact \ -H "Content-Type: application/json" \ -d '{"email":"string","phone":"string"}'
Request payload example
{ "email": "string", "phone": "string" }
Response example (200)
{ "data": "string" }

Update billing address

Update an orders billing address

URL parameters
  • orderId Required / string
Body
  • phone string
  • email string
  • firstname string
  • lastname string
  • address string
  • address_two string
  • address_three string
  • city string
  • county string
  • state string
  • country string
  • zip string
Responses
  • 200 object

    OK

    • data
  • 404 object

    Not Found

    • error object
      • error.http_code integer
      • error.message string
Definition
PUT http://localhost:3000/api/v1/orders/{orderId}/billing/address
cURL example
curl \ -X PUT http://localhost:3000/api/v1/orders/{orderId}/billing/address \ -H "Content-Type: application/json" \ -d '{"phone":"string","email":"string","firstname":"string","lastname":"string","address":"string","address_two":"string","address_three":"string","city":"string","county":"string","state":"string","country":"string","zip":"string"}'
Request payload example
{ "phone": "string", "email": "string", "firstname": "string", "lastname": "string", "address": "string", "address_two": "string", "address_three": "string", "city": "string", "county": "string", "state": "string", "country": "string", "zip": "string" }
Response example (200)
{ "data": "string" }
Response example (404)
{ "error": { "http_code": 404, "message": "Resource not found" } }

Add order line

Adds an order line to an order

URL parameters
  • orderId Required / string
Body
  • quantity Required / integer
  • line_total Required / integer
  • unit_price Required / integer
  • tax_rate Required / number(double)

    The tax rate as a percentage

  • description Required / string

    Shows publicly on the order line

  • is_manual boolean

    Should this line be treated as a manual one

  • is_shipping boolean
  • option string

    If this is a variant, list the option name here

  • sku Required / string
  • discount_total integer
Responses
  • 200 object

    OK

    • data
  • 404 object

    Not Found

    • error object
      • error.http_code integer
      • error.message string
  • 422 object

    Unprocessable Entity

    • quantity array[string]
    • line_total array[string]
    • unit_price array[string]
    • tax_rate array[string]
    • description array[string]
Definition
PUT http://localhost:3000/api/v1/orders/{orderId}/lines
cURL example
curl \ -X PUT http://localhost:3000/api/v1/orders/{orderId}/lines \ -H "Content-Type: application/json" \ -d '{"quantity":42,"line_total":42,"unit_price":42,"tax_rate":20,"description":"string","is_manual":true,"is_shipping":true,"option":"string","sku":"string","discount_total":42}'
Request payload example
{ "quantity": 42, "line_total": 42, "unit_price": 42, "tax_rate": 20, "description": "string", "is_manual": true, "is_shipping": true, "option": "string", "sku": "string", "discount_total": 42 }
Response example (200)
{ "data": "string" }
Response example (404)
{ "error": { "http_code": 404, "message": "Resource not found" } }
Response example (422)
{ "quantity": [ "string" ], "line_total": [ "string" ], "unit_price": [ "string" ], "tax_rate": [ "string" ], "description": [ "string" ] }

Delete an order line

Deletes an order line from an order

URL parameters
  • orderLineId Required / string
Responses
  • 204

    No Content

Definition
DELETE http://localhost:3000/api/v1/orders/lines/{orderLineId}
cURL example
curl \ -X DELETE http://localhost:3000/api/v1/orders/lines/{orderLineId} \ -H "Content-Type: application/json"
Response example (204)
No content

Get order invoice

Get an orders invoice

URL parameters
  • orderId Required / string
Responses
  • 200 object

    OK

    • data object
      • data.encoding string
      • data.content string
  • 401

    Unauthorized

Definition
GET http://localhost:3000/api/v1/orders/{orderId}/invoice
cURL example
curl \ -X GET http://localhost:3000/api/v1/orders/{orderId}/invoice \ -H "Content-Type: application/json"
Response example (200)
{ "data": { "encoding": "encoding", "content": "content" } }
Response example (401)
No content

Attributes

Catalogue Management

Get Attributes

Return a paged array of attributes

Responses
  • 200

    OK

Definition
GET http://localhost:3000/api/v1/attributes
cURL example
curl \ -X GET http://localhost:3000/api/v1/attributes \ -H "Content-Type: application/json"
Response example (200)
{ "data": [ { "id": "dnj4zky5", "name": { "en": "Name", "sv": "Namn" }, "handle": "name", "position": "1", "filterable": false, "scopeable": true, "translatable": true, "variant": false, "searchable": true, "localised": true, "type": "text", "required": true, "lookups": null, "system": false, "group": { "data": { "id": "vokq5kmj", "name": { "en": "General" }, "handle": "general", "position": "1" } } } ], "links": { "first": "http://storefront.test/api/v1/attributes?page=1", "last": "http://storefront.test/api/v1/attributes?page=5", "prev": null, "next": "http://storefront.test/api/v1/attributes?page=2" }, "meta": { "current_page": 1, "from": 1, "last_page": 5, "path": "http://storefront.test/api/v1/attributes", "per_page": 15, "to": 15, "total": 70 } }

Create Attribute

Create a new attribute

Body
  • group_id Required / string
  • name array[object]
    • name.locale Required / string
  • handle Required / string
  • position integer(int32)
  • filterable boolean
  • scopeable integer(int32)
  • translatable boolean
  • variant boolean
  • searchable boolean
  • localised boolean
  • type string
  • required boolean
  • lookups array[object]
    • lookups.label string
    • lookups.value string
  • system boolean
Responses
  • 200 object

    OK

    • data object
      Available includes
      • group
      • data.id string
      • data.name object
      • data.handle string
      • data.position integer
      • data.filterable boolean
      • data.scopeable boolean
      • data.translatable boolean
      • data.variant boolean
      • data.searchable boolean
      • data.localised boolean
      • data.type string
      • data.required boolean
      • data.lookups array[object]
      • data.system boolean
      • data.group object
        • data.group.data object
          Available includes
          • attributes
          • data.group.data.id string
          • data.group.data.name object
          • data.group.data.handle string
          • data.group.data.position integer(int32)
          • data.group.data.attributes
  • 422 object

    Unprocessable Entity

    • group_id array[string]
    • name array[string]
    • handle array[string]
Definition
POST http://localhost:3000/api/v1/attributes
cURL example
curl \ -X POST http://localhost:3000/api/v1/attributes \ -H "Content-Type: application/json" \ -d '{"group_id":"q1jo3jm4","name":[{"locale":"string"}],"handle":"string","position":12,"filterable":true,"scopeable":42,"translatable":true,"variant":true,"searchable":true,"localised":true,"type":"string","required":true,"lookups":[{"label":"string","value":"string"}],"system":true}'
Request payload example
{ "group_id": "q1jo3jm4", "name": [ { "locale": "string" } ], "handle": "string", "position": 12, "filterable": true, "scopeable": 42, "translatable": true, "variant": true, "searchable": true, "localised": true, "type": "string", "required": true, "lookups": [ { "label": "string", "value": "string" } ], "system": true }
Response example (200)
{ "data": { "id": "w52log2p", "name": { "en": "New attribute" }, "handle": "new-attribute", "position": 2, "system": false, "lookups": null, "required": false, "type": "text", "localised": false, "searchable": false, "variant": false, "translatable": false, "scopeable": false, "filterable": false }, "meta": { "lang": "en" } }
Response example (422)
{ "group_id": [ "The group id field is required." ], "name": [ "The name field is required." ], "handle": [ "The handle field is required." ] }

Update request to reorder attributes

Allows you to reorder a target category in relation to another.

Body
  • groups array[object]
    • groups.groupId integer(int32)
Responses
  • 204

    No Content

Definition
PUT http://localhost:3000/api/v1/attributes/order
cURL example
curl \ -X PUT http://localhost:3000/api/v1/attributes/order \ -H "Content-Type: application/json" \ -d '{"groups":[{"groupId":0}]}'
Request payload example
{ "groups": [ { "groupId": 0 } ] }
Response example (204)
No content

Get an attribute

Returns an attribute from a given ID.

URL parameters
  • attributeId Required / string
  • include string
Responses
  • 200 object

    OK

    • data object
      Available includes
      • group
      • data.id string
      • data.name object
      • data.handle string
      • data.position integer
      • data.filterable boolean
      • data.scopeable boolean
      • data.translatable boolean
      • data.variant boolean
      • data.searchable boolean
      • data.localised boolean
      • data.type string
      • data.required boolean
      • data.lookups array[object]
      • data.system boolean
      • data.group object
        • data.group.data object
          Available includes
          • attributes
          • data.group.data.id string
          • data.group.data.name object
          • data.group.data.handle string
          • data.group.data.position integer(int32)
          • data.group.data.attributes
Definition
GET http://localhost:3000/api/v1/attributes/{attributeId}
cURL example
curl \ -X GET http://localhost:3000/api/v1/attributes/{attributeId} \ -H "Content-Type: application/json"
Response example (200)
{ "data": { "id": "dnj4zky5", "name": { "en": "Name", "sv": "Namn" }, "handle": "name", "position": "1", "filterable": false, "scopeable": true, "translatable": true, "variant": false, "searchable": true, "localised": true, "type": "text", "required": true, "lookups": null, "system": false } }

Update an attribute

Updates an attribute from a given ID.

URL parameters
  • attributeId Required / string
Body
  • id string
  • name object
  • handle string
  • position integer
  • filterable boolean
  • scopeable boolean
  • translatable boolean
  • variant boolean
  • searchable boolean
  • localised boolean
  • type string
  • required boolean
  • lookups array[object]
  • system boolean
  • group object
    • group.data object
      Available includes
      • attributes
      • group.data.id string
      • group.data.name object
      • group.data.handle string
      • group.data.position integer(int32)
      • group.data.attributes
Responses
  • 200 object

    OK

    • data object
      Available includes
      • group
      • data.id string
      • data.name object
      • data.handle string
      • data.position integer
      • data.filterable boolean
      • data.scopeable boolean
      • data.translatable boolean
      • data.variant boolean
      • data.searchable boolean
      • data.localised boolean
      • data.type string
      • data.required boolean
      • data.lookups array[object]
      • data.system boolean
      • data.group object
        • data.group.data object
          Available includes
          • attributes
          • data.group.data.id string
          • data.group.data.name object
          • data.group.data.handle string
          • data.group.data.position integer(int32)
          • data.group.data.attributes
  • 404 object

    Not Found

    • error object
      • error.http_code integer
      • error.message string
Definition
PUT http://localhost:3000/api/v1/attributes/{attributeId}
cURL example
curl \ -X PUT http://localhost:3000/api/v1/attributes/{attributeId} \ -H "Content-Type: application/json" \ -d '{"id":"dnj4zky5","name":{},"handle":"string","position":42,"filterable":true,"scopeable":true,"translatable":true,"variant":true,"searchable":true,"localised":true,"type":"string","required":true,"lookups":[{}],"system":true,"group":{"data":{"name":"{}","handle":"handle","id":"id","position":6}}}'
Request payload example
{ "id": "dnj4zky5", "name": { }, "handle": "string", "position": 42, "filterable": true, "scopeable": true, "translatable": true, "variant": true, "searchable": true, "localised": true, "type": "string", "required": true, "lookups": [ { } ], "system": true, "group": { "data": { "name": "{}", "handle": "handle", "id": "id", "position": 6 } } }
Response example (200)
{ "data": { "lookups": [ "{}", "{}" ], "filterable": true, "translatable": true, "localised": true, "handle": "handle", "type": "type", "searchable": true, "required": true, "scopeable": true, "system": true, "name": "{}", "variant": true, "id": "dnj4zky5", "position": 0, "group": { "data": { "name": "{}", "handle": "handle", "id": "id", "position": 6 } } } }
Response example (404)
{ "error": { "http_code": 404, "message": "Resource not found" } }

Delete an attribute

Delete an attribute.

URL parameters
  • attributeId Required / string
Responses
  • 204

    No Content

  • 404 object

    Not Found

    • error object
      • error.http_code integer
      • error.message string
Definition
DELETE http://localhost:3000/api/v1/attributes/{attributeId}
cURL example
curl \ -X DELETE http://localhost:3000/api/v1/attributes/{attributeId} \ -H "Content-Type: application/json"
Response example (204)
No content
Response example (404)
{ "error": { "http_code": 404, "message": "Resource not found" } }

Paginated list of Attribute Groups

Returns a paginated list of available attribute groups

URL parameters
  • all_records boolean

    Will skip pagination and return all records

  • include string
Responses
  • 200

    OK

Definition
GET http://localhost:3000/api/v1/attribute-groups
cURL example
curl \ -X GET http://localhost:3000/api/v1/attribute-groups \ -H "Content-Type: application/json"
Response example (200)
{ "data": [ { "id": "vokq5kmj", "name": { "en": "General" }, "handle": "general", "position": "1" }, { "id": "mqkj8wyj", "name": { "en": "Meta Information", "sv": "SEO" }, "handle": "seo", "position": "2" }, { "id": "96e7nk8r", "name": { "en": "Default" }, "handle": "default", "position": "4" } ] }

Create an Attribute Group

Responses
  • 200 object

    OK

    • data object
      Available includes
      • attributes
      • data.id string
      • data.name object
      • data.handle string
      • data.position integer(int32)
      • data.attributes
Definition
POST http://localhost:3000/api/v1/attribute-groups
cURL example
curl \ -X POST http://localhost:3000/api/v1/attribute-groups \ -H "Content-Type: application/json"
Response example (200)
{ "data": { "id": "m1wrpejy", "name": { "en": "New Group" }, "handle": "new-group", "position": "13" } }

Reorder attribute groups

Sends a request to reorder the attribute groups in the system

Body
  • groups array[object]
    • groups.groupId integer(int32)
Responses
  • 204

    No Content

  • 422 object

    Unprocessable Entity

    • attributes array[string]
Definition
PUT http://localhost:3000/api/v1/attribute-groups/reorder
cURL example
curl \ -X PUT http://localhost:3000/api/v1/attribute-groups/reorder \ -H "Content-Type: application/json" \ -d '{"groups":{"vokq5kmj":1,"mqkj8wyj":2}}'
Request payload example
{ "groups": { "vokq5kmj": 1, "mqkj8wyj": 2 } }
Response example (204)
No content
Response example (422)
{ "groups": [ "The groups field is required." ] }

Get a single attribute group

Gets a single attribute group

URL parameters
  • attributeGroupId Required / string
  • include integer
Responses
  • 200 object

    OK

    • data object
      Available includes
      • attributes
      • data.id string
      • data.name object
      • data.handle string
      • data.position integer(int32)
      • data.attributes
  • 404 object

    Not Found

    • error object
      • error.http_code integer
      • error.message string
Definition
GET http://localhost:3000/api/v1/attribute-groups/{attributeGroupId}
cURL example
curl \ -X GET http://localhost:3000/api/v1/attribute-groups/{attributeGroupId} \ -H "Content-Type: application/json"
Response example (200)
{ "data": { "id": "vokq5kmj", "name": { "en": "General" }, "handle": "general", "position": "1" } }
Response example (404)
{ "error": { "http_code": 404, "message": "Resource not found" } }

Update an attribute group

Updates an attribute group.

URL parameters
  • attributeGroupId Required / string
Body
  • id string
  • name object
  • handle string
  • position integer(int32)
  • attributes
Responses
  • 200 object

    OK

    • data object
      Available includes
      • attributes
      • data.id string
      • data.name object
      • data.handle string
      • data.position integer(int32)
      • data.attributes
Definition
PUT http://localhost:3000/api/v1/attribute-groups/{attributeGroupId}
cURL example
curl \ -X PUT http://localhost:3000/api/v1/attribute-groups/{attributeGroupId} \ -H "Content-Type: application/json" \ -d '{"id":"string","name":{},"handle":"string","position":42,"attributes":"string"}'
Request payload example
{ "id": "string", "name": { }, "handle": "string", "position": 42, "attributes": "string" }
Response example (200)
{ "data": { "name": "{}", "handle": "handle", "id": "id", "position": 6 } }

Delete an attribute group

Deletes an attribute group

URL parameters
  • attributeGroupId Required / string
Responses
  • 204

    No Content

  • 404 object

    Not Found

    • error object
      • error.http_code integer
      • error.message string
Definition
DELETE http://localhost:3000/api/v1/attribute-groups/{attributeGroupId}
cURL example
curl \ -X DELETE http://localhost:3000/api/v1/attribute-groups/{attributeGroupId} \ -H "Content-Type: application/json"
Response example (204)
No content
Response example (404)
{ "error": { "http_code": 404, "message": "Resource not found" } }

Assets

Catalogue Management

Update Assets

Update all assets in the given array of ids.

Body
  • assets array[object]
    • assets.id Required / string
    • assets.tags array[string]
Responses
  • 200 object

    OK

    • data object
      • data.id string
      • data.title string
      • data.type string
      • data.caption string
      • data.kind string
      • data.external boolean
      • data.position integer
      • data.primary boolean
      • data.url string
      • data.sub_kind string
      • data.extension string
      • data.original_filename string
      • data.size string
      • data.width string
      • data.height string
      • data.transforms
      • data.tags
Definition
PUT http://localhost:3000/api/v1/assets
cURL example
curl \ -X PUT http://localhost:3000/api/v1/assets \ -H "Content-Type: application/json" \ -d '{"assets":[{"id":"id","tags":["tags","tags"]}]}'
Request payload example
{ "assets": [ { "id": "id", "tags": [ "tags", "tags" ] } ] }
Response example (200)
{ "data": { "extension": "extension", "kind": "kind", "caption": "caption", "title": "title", "type": "type", "url": "url", "external": true, "original_filename": "original_filename", "size": "size", "width": "width", "id": "id", "position": 5, "sub_kind": "sub_kind", "primary": true, "height": "height" } }

Create Asset

Upload an asset to a model

Responses
  • 200 object

    OK

    • data object
      • data.id string
      • data.title string
      • data.type string
      • data.caption string
      • data.kind string
      • data.external boolean
      • data.position integer
      • data.primary boolean
      • data.url string
      • data.sub_kind string
      • data.extension string
      • data.original_filename string
      • data.size string
      • data.width string
      • data.height string
      • data.transforms
      • data.tags
Definition
POST http://localhost:3000/api/v1/assets
cURL example
curl \ -X POST http://localhost:3000/api/v1/assets \ -H "Content-Type: application/json"
Response example (200)
{ "data": { "extension": "extension", "kind": "kind", "caption": "caption", "title": "title", "type": "type", "url": "url", "external": true, "original_filename": "original_filename", "size": "size", "width": "width", "id": "id", "position": 5, "sub_kind": "sub_kind", "primary": true, "height": "height" } }

Simple asset upload

This endpoint allows you to upload an asset without having to attach it to a model. This is good for one time uploads where you just want to get back a URL

Responses
  • 200 object

    OK

    • thumbnail_url string
    • thumbnail string
    • url string
    • filename string
    • path string
Definition
POST http://localhost:3000/api/v1/assets/simple
cURL example
curl \ -X POST http://localhost:3000/api/v1/assets/simple \ -H "Content-Type: application/json"
Response example (200)
{ "path": "uploads/01/04/WGWVDkB2VXkDKx4UeeLnStBwnEJXGL2Vd6j5Le1P.png", "filename": "the-secret-recipe.png", "url": "http://storefront.test/storage/uploads/01/04/WGWVDkB2VXkDKx4UeeLnStBwnEJXGL2Vd6j5Le1P.png", "thumbnail": "uploads/01/04/thumbnails/WGWVDkB2VXkDKx4UeeLnStBwnEJXGL2Vd6j5Le1P.png", "thumbnail_url": "http://storefront.test/storage/uploads/01/04/thumbnails/WGWVDkB2VXkDKx4UeeLnStBwnEJXGL2Vd6j5Le1P.png" }

Detach an asset from it's model

Detaches any assets from a given model. Useful if you want to remove certain assets from a product (or another model) without deleting the asset itself.

URL parameters
  • assetId Required / string

    The hashed asset id

  • ownerId Required / string

    The hashed owner id

Body
  • attributes array[object]

    attributeId => position

Responses
  • 204

    No Content

Definition
POST http://localhost:3000/api/v1/assets/{assetId}/detach/{ownerId}
cURL example
curl \ -X POST http://localhost:3000/api/v1/assets/{assetId}/detach/{ownerId} \ -H "Content-Type: application/json" \ -d '{"attributes":[{}]}'
Request payload example
{ "attributes": [ { } ] }
Response example (204)
No content

Associations

Catalogue Management

Paginated array of association groups

Returns a paginated response of association groups available in the system

Responses
  • 200

    OK

Definition
GET http://localhost:3000/api/v1/associations/groups
cURL example
curl \ -X GET http://localhost:3000/api/v1/associations/groups \ -H "Content-Type: application/json"
Response example (200)
{ "data": [ { "id": "v8l4pl01", "name": "Upsell", "handle": "upsell" }, { "id": "p09prlrn", "name": "Cross-sell", "handle": "cross-sell" }, { "id": "wz6d39dj", "name": "Alternate", "handle": "alternate" } ], "meta": { "lang": "en", "pagination": { "total": 3, "count": 3, "per_page": 50, "current_page": 1, "total_pages": 1, "links": [ ] } } }

Baskets

Order Processing

Resolve a basket

This endpoint is for when you want to either merge a users basket with a guest basket and then assign that new basket or associate a user to a guest basket.

If you choose not to merge a basket, their current one will be overwritten with the guest basket.

Body
  • merge boolean
  • basket_id Required / string
Responses
  • 200 object

    OK

    • data object
      • data.id string
      • data.total number
      • data.sub_total number
      • data.tax_total number
      • data.discount_total number(float)
      • data.changed boolean
      • data.has_exclusions boolean
      • data.meta object
      • data.lines
      • data.order object
        • data.order.data
Definition
POST http://localhost:3000/api/v1/baskets/resolve
cURL example
curl \ -X POST http://localhost:3000/api/v1/baskets/resolve \ -H "Content-Type: application/json" \ -d '{"merge":true,"basket_id":"string"}'
Request payload example
{ "merge": true, "basket_id": "string" }
Response example (200)
{ "data": { "has_exclusions": true, "total": 6.027456183070403, "discount_total": 5.637377, "tax_total": 5.962133916683182, "meta": "{}", "sub_total": "1.4658129805029452", "id": "id", "changed": true } }

Get the current basket for a user

This request will get the current active basket for a user

Responses
  • 200 object

    OK

    • data object
      • data.id string
      • data.total number
      • data.sub_total number
      • data.tax_total number
      • data.discount_total number(float)
      • data.changed boolean
      • data.has_exclusions boolean
      • data.meta object
      • data.lines
      • data.order object
        • data.order.data
  • 404 object

    Not Found

    • error object
      • error.http_code integer
      • error.message string
Definition
GET http://localhost:3000/api/v1/baskets/current
cURL example
curl \ -X GET http://localhost:3000/api/v1/baskets/current \ -H "Content-Type: application/json"
Response example (200)
{ "data": { "has_exclusions": true, "total": 6.027456183070403, "discount_total": 5.637377, "tax_total": 5.962133916683182, "meta": "{}", "sub_total": "1.4658129805029452", "id": "id", "changed": true } }
Response example (404)
{ "error": { "http_code": 404, "message": "Resource not found" } }

Get a users saved baskets

Returns an authenticatd users saved baskets.

Responses
  • 200

    OK

  • 401 object

    Unauthorized

    • error string
Definition
GET http://localhost:3000/api/v1/baskets/saved
cURL example
curl \ -X GET http://localhost:3000/api/v1/baskets/saved \ -H "Content-Type: application/json"
Response example (200)
No content
Response example (401)
{ "error": "Unauthenticated." }

Save a basket for a user

Saves a basket to a users account.

URL parameters
  • basketId Required / string
Body
  • name Required / string
Responses
  • 200 object

    OK

    • data object
      • data.id string
      • data.total number
      • data.sub_total number
      • data.tax_total number
      • data.discount_total number(float)
      • data.changed boolean
      • data.has_exclusions boolean
      • data.meta object
      • data.lines
      • data.order object
        • data.order.data
  • 404 object

    Not Found

    • error object
      • error.http_code integer
      • error.message string
Definition
POST http://localhost:3000/api/v1/baskets/{basketId}/save
cURL example
curl \ -X POST http://localhost:3000/api/v1/baskets/{basketId}/save \ -H "Content-Type: application/json" \ -d '{"name":"string"}'
Request payload example
{ "name": "string" }
Response example (200)
{ "data": { "has_exclusions": true, "total": 6.027456183070403, "discount_total": 5.637377, "tax_total": 5.962133916683182, "meta": "{}", "sub_total": "1.4658129805029452", "id": "id", "changed": true } }
Response example (404)
{ "error": { "http_code": 404, "message": "Resource not found" } }

Allow a user to claim a basket

A user is able to "claim" a guest basket.

URL parameters
  • basketId Required / string
Responses
  • 200 object

    OK

    • data object
      • data.id string
      • data.total number
      • data.sub_total number
      • data.tax_total number
      • data.discount_total number(float)
      • data.changed boolean
      • data.has_exclusions boolean
      • data.meta object
      • data.lines
      • data.order object
        • data.order.data
  • 404 object

    Not Found

    • error object
      • error.http_code integer
      • error.message string
Definition
POST http://localhost:3000/api/v1/baskets/{basketId}/claim
cURL example
curl \ -X POST http://localhost:3000/api/v1/baskets/{basketId}/claim \ -H "Content-Type: application/json"
Response example (200)
{ "data": { "has_exclusions": true, "total": 6.027456183070403, "discount_total": 5.637377, "tax_total": 5.962133916683182, "meta": "{}", "sub_total": "1.4658129805029452", "id": "id", "changed": true } }
Response example (404)
{ "error": { "http_code": 404, "message": "Resource not found" } }

Get basket

Get a basket by it's ID

URL parameters
  • basketId Required / string
Responses
  • 200 object

    OK

    • data object
      • data.id string
      • data.total number
      • data.sub_total number
      • data.tax_total number
      • data.discount_total number(float)
      • data.changed boolean
      • data.has_exclusions boolean
      • data.meta object
      • data.lines
      • data.order object
        • data.order.data
  • 404 object

    Not Found

    • error object
      • error.http_code integer
      • error.message string
Definition
GET http://localhost:3000/api/v1/baskets/{basketId}
cURL example
curl \ -X GET http://localhost:3000/api/v1/baskets/{basketId} \ -H "Content-Type: application/json"
Response example (200)
{ "data": { "has_exclusions": true, "total": 6.027456183070403, "discount_total": 5.637377, "tax_total": 5.962133916683182, "meta": "{}", "sub_total": "1.4658129805029452", "id": "id", "changed": true } }
Response example (404)
{ "error": { "http_code": 404, "message": "Resource not found" } }

Update a basket by ID

Updates a basket

URL parameters
  • basketId Required / string
Responses
  • 200 object

    OK

    • data object
      • data.id string
      • data.total number
      • data.sub_total number
      • data.tax_total number
      • data.discount_total number(float)
      • data.changed boolean
      • data.has_exclusions boolean
      • data.meta object
      • data.lines
      • data.order object
        • data.order.data
  • 404 object

    Not Found

    • error object
      • error.http_code integer
      • error.message string
Definition
PUT http://localhost:3000/api/v1/baskets/{basketId}
cURL example
curl \ -X PUT http://localhost:3000/api/v1/baskets/{basketId} \ -H "Content-Type: application/json"
Response example (200)
{ "data": { "has_exclusions": true, "total": 6.027456183070403, "discount_total": 5.637377, "tax_total": 5.962133916683182, "meta": "{}", "sub_total": "1.4658129805029452", "id": "id", "changed": true } }
Response example (404)
{ "error": { "http_code": 404, "message": "Resource not found" } }

Delete a basket by ID

Deletes a basket

URL parameters
  • basketId Required / string
Responses
  • 204

    No Content

Definition
DELETE http://localhost:3000/api/v1/baskets/{basketId}
cURL example
curl \ -X DELETE http://localhost:3000/api/v1/baskets/{basketId} \ -H "Content-Type: application/json"
Response example (204)
No content

Update a saved basket

Updates a saved basket on the API

URL parameters
  • basketId Required / string
Body
  • name Required / string
Responses
  • 200 object

    OK

    • data object
      • data.id string
      • data.name string
      • data.basket object
        • data.basket.data object
          • data.basket.data.id string
          • data.basket.data.total number
          • data.basket.data.sub_total number
          • data.basket.data.tax_total number
          • data.basket.data.discount_total number(float)
          • data.basket.data.changed boolean
          • data.basket.data.has_exclusions boolean
          • data.basket.data.meta object
          • data.basket.data.lines
          • data.basket.data.order object
            • data.basket.data.order.data
  • 404 object

    Not Found

    • error object
      • error.http_code integer
      • error.message string
Definition
PUT http://localhost:3000/api/v1/baskets/saved/{basketId}
cURL example
curl \ -X PUT http://localhost:3000/api/v1/baskets/saved/{basketId} \ -H "Content-Type: application/json" \ -d '{"name":"string"}'
Request payload example
{ "name": "string" }
Response example (200)
{ "data": { "basket": { "data": { "has_exclusions": true, "total": 6.027456183070403, "discount_total": 5.637377, "tax_total": 5.962133916683182, "meta": "{}", "sub_total": "1.4658129805029452", "id": "id", "changed": true } }, "name": "name", "id": "id" } }
Response example (404)
{ "error": { "http_code": 404, "message": "Resource not found" } }

Add meta information

Allows you to add custom meta information to a basket.

URL parameters
  • basketId Required / string
Body
  • value Required / string
  • key Required / string
Responses
  • 200 object

    OK

    • id string
    • total number
    • sub_total number
    • tax_total number
    • discount_total number(float)
    • changed boolean
    • has_exclusions boolean
    • meta object
    • lines
    • order object
      • order.data
  • 404 object

    Not Found

    • error object
      • error.http_code integer
      • error.message string
Definition
POST http://localhost:3000/api/v1/baskets/{basketId}/meta
cURL example
curl \ -X POST http://localhost:3000/api/v1/baskets/{basketId}/meta \ -H "Content-Type: application/json" \ -d '{"value":"string","key":"string"}'
Request payload example
{ "value": "string", "key": "string" }
Response example (200)
{ "id": "string", "total": 42.0, "sub_total": 42.0, "tax_total": 42.0, "discount_total": 42.0, "changed": true, "has_exclusions": true, "meta": { }, "lines": "string", "order": { "data": { "delivery_total": 1307, "basket": { "data": { "has_exclusions": true, "total": 6.027456183070403, "discount_total": 5.637377, "tax_total": 5.962133916683182, "meta": "{}", "sub_total": "1.4658129805029452", "id": "id", "changed": true } }, "discount_total": 0, "billing_details": { "zip": "zip", "country": "country", "firstname": "firstname", "address": "address", "address_three": "address_three", "phone": "phone", "city": "city", "county": "county", "state": "state", "address_two": "address_two", "email": "email", "lastname": "lastname" }, "tax_total": 1307, "notes": "notes", "display_id": "#ORD-123456", "dispatched_at": "dispatched_at", "shipping_details": { "zip": "zip", "country": "country", "firstname": "firstname", "address": "address", "address_three": "address_three", "phone": "phone", "city": "city", "county": "county", "state": "state", "address_two": "address_two", "email": "email", "lastname": "lastname" }, "created_at": "created_at", "type": "SagePay", "reference": "CUSTOM-REFERENCE", "updated_at": "updated_at", "discounts": "discounts", "shipping": { "data": { "delivery_total": 3, "discount_total": 9, "quantity": 2, "tax_total": 7, "unit_qty": 4, "is_shipping": true, "is_manual": true, "description": "description", "unit_price": 2, "line_total": 7, "tax_rate": 1, "meta": "{}", "id": "id", "sku": "sku", "option": "option" } }, "shipping_method": "Standard Delivery", "customer_reference": "customer_reference", "invoice_reference": "#INV-1234567", "currency": "GBP", "id": "123RFesfes356P", "lines": { "data": [ { "delivery_total": 3, "discount_total": 9, "quantity": 2, "tax_total": 7, "unit_qty": 4, "is_shipping": true, "is_manual": true, "description": "description", "unit_price": 2, "line_total": 7, "tax_rate": 1, "meta": "{}", "id": "id", "sku": "sku", "option": "option" }, { "delivery_total": 3, "discount_total": 9, "quantity": 2, "tax_total": 7, "unit_qty": 4, "is_shipping": true, "is_manual": true, "description": "description", "unit_price": 2, "line_total": 7, "tax_rate": 1, "meta": "{}", "id": "id", "sku": "sku", "option": "option" } ] }, "logs": { "data": [ { "description": "description", "created_at": "created_at", "id": "id", "type": "type", "user": { "data": { "name": "name", "id": "id", "email": "email" } }, "properties": "properties" }, { "description": "description", "created_at": "created_at", "id": "id", "type": "type", "user": { "data": { "name": "name", "id": "id", "email": "email" } }, "properties": "properties" } ] }, "contact_details": { "phone": "12345678910", "email": "example@example.com" }, "shipping_preference": "shipping_preference", "tracking_no": "tracking_no", "meta": [ "{}", "{}" ], "sub_total": 12345, "order_total": 7845, "customer_name": "Thanos", "user": { "data": { "name": "name", "id": "id", "email": "email" } }, "vat_no": "vat_no", "status": "payment-received" } } }
Response example (404)
{ "error": { "http_code": 404, "message": "Resource not found" } }

Remove discount

Allows a user/guest to remove a basket from their basket. Useful if you can only have one discount at a time and they wish to use a different one.

URL parameters
  • basketId Required / string
Responses
  • 204

    No Content

Definition
DELETE http://localhost:3000/api/v1/baskets/{basketId}/discounts
cURL example
curl \ -X DELETE http://localhost:3000/api/v1/baskets/{basketId}/discounts \ -H "Content-Type: application/json"
Response example (204)
No content

Add user

Attach a user to a basket.

This endpoint will be deprecated in version 0.3.0

URL parameters
  • basketId Required / string
Responses
  • 200 object

    OK

    • id string
    • total number
    • sub_total number
    • tax_total number
    • discount_total number(float)
    • changed boolean
    • has_exclusions boolean
    • meta object
    • lines
    • order object
      • order.data
Definition
PUT http://localhost:3000/api/v1/baskets/{basketId}/user
cURL example
curl \ -X PUT http://localhost:3000/api/v1/baskets/{basketId}/user \ -H "Content-Type: application/json"
Response example (200)
{ "id": "string", "total": 42.0, "sub_total": 42.0, "tax_total": 42.0, "discount_total": 42.0, "changed": true, "has_exclusions": true, "meta": { }, "lines": "string", "order": { "data": { "delivery_total": 1307, "basket": { "data": { "has_exclusions": true, "total": 6.027456183070403, "discount_total": 5.637377, "tax_total": 5.962133916683182, "meta": "{}", "sub_total": "1.4658129805029452", "id": "id", "changed": true } }, "discount_total": 0, "billing_details": { "zip": "zip", "country": "country", "firstname": "firstname", "address": "address", "address_three": "address_three", "phone": "phone", "city": "city", "county": "county", "state": "state", "address_two": "address_two", "email": "email", "lastname": "lastname" }, "tax_total": 1307, "notes": "notes", "display_id": "#ORD-123456", "dispatched_at": "dispatched_at", "shipping_details": { "zip": "zip", "country": "country", "firstname": "firstname", "address": "address", "address_three": "address_three", "phone": "phone", "city": "city", "county": "county", "state": "state", "address_two": "address_two", "email": "email", "lastname": "lastname" }, "created_at": "created_at", "type": "SagePay", "reference": "CUSTOM-REFERENCE", "updated_at": "updated_at", "discounts": "discounts", "shipping": { "data": { "delivery_total": 3, "discount_total": 9, "quantity": 2, "tax_total": 7, "unit_qty": 4, "is_shipping": true, "is_manual": true, "description": "description", "unit_price": 2, "line_total": 7, "tax_rate": 1, "meta": "{}", "id": "id", "sku": "sku", "option": "option" } }, "shipping_method": "Standard Delivery", "customer_reference": "customer_reference", "invoice_reference": "#INV-1234567", "currency": "GBP", "id": "123RFesfes356P", "lines": { "data": [ { "delivery_total": 3, "discount_total": 9, "quantity": 2, "tax_total": 7, "unit_qty": 4, "is_shipping": true, "is_manual": true, "description": "description", "unit_price": 2, "line_total": 7, "tax_rate": 1, "meta": "{}", "id": "id", "sku": "sku", "option": "option" }, { "delivery_total": 3, "discount_total": 9, "quantity": 2, "tax_total": 7, "unit_qty": 4, "is_shipping": true, "is_manual": true, "description": "description", "unit_price": 2, "line_total": 7, "tax_rate": 1, "meta": "{}", "id": "id", "sku": "sku", "option": "option" } ] }, "logs": { "data": [ { "description": "description", "created_at": "created_at", "id": "id", "type": "type", "user": { "data": { "name": "name", "id": "id", "email": "email" } }, "properties": "properties" }, { "description": "description", "created_at": "created_at", "id": "id", "type": "type", "user": { "data": { "name": "name", "id": "id", "email": "email" } }, "properties": "properties" } ] }, "contact_details": { "phone": "12345678910", "email": "example@example.com" }, "shipping_preference": "shipping_preference", "tracking_no": "tracking_no", "meta": [ "{}", "{}" ], "sub_total": 12345, "order_total": 7845, "customer_name": "Thanos", "user": { "data": { "name": "name", "id": "id", "email": "email" } }, "vat_no": "vat_no", "status": "payment-received" } } }

Remove user

Removes a user from a basket and turns it into a guest basket

This endpoint will be deprecated in 0.3.0

URL parameters
  • basketId Required / string
Responses
  • 200 object

    OK

    • data object
      • data.id string
      • data.total number
      • data.sub_total number
      • data.tax_total number
      • data.discount_total number(float)
      • data.changed boolean
      • data.has_exclusions boolean
      • data.meta object
      • data.lines
      • data.order object
        • data.order.data
Definition
DELETE http://localhost:3000/api/v1/baskets/{basketId}/user
cURL example
curl \ -X DELETE http://localhost:3000/api/v1/baskets/{basketId}/user \ -H "Content-Type: application/json"
Response example (200)
{ "data": { "has_exclusions": true, "total": 6.027456183070403, "discount_total": 5.637377, "tax_total": 5.962133916683182, "meta": "{}", "sub_total": "1.4658129805029452", "id": "id", "changed": true } }

Get baskets

Get a paginated list of baskets

Responses
  • 200

    OK

Definition
GET http://localhost:3000/api/v1/baskets
cURL example
curl \ -X GET http://localhost:3000/api/v1/baskets \ -H "Content-Type: application/json"
Response example (200)
No content

Create Basket

Body
  • variants array[object]
    • variants.id Required / string
    • variants.quantity Required / integer
  • basket_id string
Responses
  • 200 object

    OK

    • data object
      • data.id string
      • data.total number
      • data.sub_total number
      • data.tax_total number
      • data.discount_total number(float)
      • data.changed boolean
      • data.has_exclusions boolean
      • data.meta object
      • data.lines
      • data.order object
        • data.order.data
Definition
POST http://localhost:3000/api/v1/baskets
cURL example
curl \ -X POST http://localhost:3000/api/v1/baskets \ -H "Content-Type: application/json" \ -d '{"variants":[{"quantity":0,"id":"id"}],"basket_id":"string"}'
Request payload example
{ "variants": [ { "quantity": 0, "id": "id" } ], "basket_id": "string" }
Response example (200)
{ "data": { "has_exclusions": true, "total": 6.027456183070403, "discount_total": 5.637377, "tax_total": 5.962133916683182, "meta": "{}", "sub_total": "1.4658129805029452", "id": "id", "changed": true } }

Create basket lines

Add lines to a basket

Body
  • variants array[object]
    • variants.id string
    • variants.quantity integer
    • variants.meta object
  • basket_id string
Responses
  • 200 object

    OK

    • data object
      • data.id string
      • data.total number
      • data.sub_total number
      • data.tax_total number
      • data.discount_total number(float)
      • data.changed boolean
      • data.has_exclusions boolean
      • data.meta object