Crystal-D API

The Crystal-D API is a RESTful API, that uses HTTP GET, POST, PUT and DELETE methods to interact with Crystal-D's internal software.

Authentication

Crystal-D uses HTTP basic authentication for API requests. You will need an API key issued by Crystal-D to interact with all endpoints in the API.

Keep your API key secret. Never upload your keys to any GIT repositories or use it in any client-side coding.

To authenticate use an Authorization header with key type X-API-KEY.
Authorization: X-API-KEY {API Key}

Authorization

Only certain API endpoints will be available to you depeding on our records. Please contact Crystal-D to change your authorized endpoints.

Crystal-D verifies your IP address everytime you connect to the API. If you are not using an IP address in the Crystal-D records, you will be denied access.

You are allowed multiple IP addresses, however only the first IP address used to connect is stored autmatically. If you need to specify multiple IP addresses, or to change your IP address on file, please contact crystal-D.

API Rate Limits

Calls are limited to 500 calls per hour.

API Server

All requests must be sent using HTTPS for your security to:
https://api.crystal-d.com

Response body

The API will respond with a JSON object in the body that contains the result.

Each response will always contain a status property that will result in true upon success or false upon a fail.

Each response will always contain a message property containing a string with additional information about the status.

See Endpoints below for more response information.

Endpoints

Orders

POST /orders Place an order with Crystal-D

Example Request Body:

{
    "order": {
        "line_items": [
            {
                "product_id": "6558",
                "quantity": 10,
                "options": [
                    {
                        "name": "image",
                        "value": "http://img.crystal-d.com/an-art-file-reference.jpg"
                    },
                    {
                        "name": "included",
                        "value": "6374BLOCKCLEAR"
                    }
                ]
            },
            {
                "product_id": "5648",
                "quantity": 11
            }
        ],
        "shipping_address": {
            "first_name": "Jane",
            "last_name": "Smith",
            "address1": "123 Fake Street",
            "phone": "777-777-7777",
            "city": "Fakecity",
            "state": "Ontario",
            "country": "Canada",
            "zip": "K2P 1L4"
        },
        "po_number": "4908234908348093",
        "notes": "I would like to get this order rush delivered if possible."
    }
}

Request Body Schema:

order* object = Root level object.
- line_items* array of objects = Array of item objects.
  - product_id* string = Item SKU.
  - quantity* integer = Quantity to be ordered.
  - options array of objects = Array of option objects.
    - name* string = Itentifier.
    -   Excepted values are:
        "run" = value will be url of a run file (.vmj)
        "image" = value will be url of a image file (.jpg, .png, etc)
        "included" = value will be the SKU of and included option
    - value* string = see above
- shipping_account object = Specify your own shipping account.
  - account_number* string
  - carrier_name string
  - company string
  - address1 string
  - address2 string
  - city string
  - state* string
  - country* string
  - zip* string
- shipping_address* object = Address for product shipment.
  - first_name* string
  - last_name* string
  - address1* string
  - address2 string
  - phone string
  - city* string
  - state* string
  - country* string
  - zip* string
- billing_address object = Billing Address.
  - first_name* string
  - last_name* string
  - address1* string
  - address2 string
  - phone string
  - city* string
  - state* string
  - country* string
  - zip* string
- return_address object = A return address for shipping label.
  - company_name* string
  - address1* string
  - address2 string
  - phone string
  - city* string
  - state* string
  - country* string
  - zip* string
- po_number object = Root level object.
- User defined order reference value. This value should be unique to this order.
- status object = Object for additional input. Please contact for details.
- notes string = Additional notes for the order.

Example 200 Response Body:

{
    "status": true,
    "message": "Order completed successfully!",
    "data": {
        "id": 1,
        "po_number": "4908234908348093",
        "status": "pending",
        "tracking_number": ""
    }
}

GET /orders Retrieve an order.

Example Requests:
https://api.crystal-d.com/orders?po=4908234908348093
https://api.crystal-d.com/orders?id=23
Either po or id is required to retrieve an order.

Example 200 Response Body:

{
    "status": true,
    "message": "Order retrieved successfully!",
    "data": {
        "id": "4",
        "po_number": "4908234908348093",
        "status": "shipped",
        "tracking_number": "92612999988295220984",
        "order": {
            "line_items": [
                {
                    "product_id": "6558",
                    "quantity": "10",
                    "options": [
                        {
                            "name": "art",
                            "value": "http://api.teelaunch/an-art-file-reference.jpg"
                        },
                        {
                            "name": "included",
                            "value": "6374BLOCKCLEAR"
                        }
                    ]
                },
                {
                    "product_id": "5648",
                    "quantity": "11"
                }
            ],
            "shipping_account": {
                "account_number": "309487df",
                "carrier_name": "Fedex",
                "company": "Crystal-D",
                "address1": "123 Fake Street",
                "address2": "Suite 102",
                "city": "St Paul",
                "state": "MN",
                "country": "USA",
                "zip": "55055"
            },
            "billing_address": {
                "first_name": "John",
                "last_name": "Smith",
                "address1": "123 Fake Street",
                "phone": "555-555-5555",
                "city": "Fakecity",
                "state": "Ontario",
                "country": "Canada",
                "zip": "K2P 1L4"
            },
            "shipping_address": {
                "first_name": "Jane",
                "last_name": "Smith",
                "address1": "123 Fake Street",
                "phone": "777-777-7777",
                "city": "Fakecity",
                "state": "Ontario",
                "country": "Canada",
                "zip": "K2P 1L4"
            },
            "po_number": "4908234908348093",
            "status": {
                "payment": "terms",
                "transaction_id": "1111232435546435"
            },
            "notes": "I would like to get this order rush delivered if possible."
        }
    }
}

Products

GET /products Get Crystal D Products

Rundown:
This endpoint is a pagination system of getting Crystal D products. A maximum count of products per page is 100. Use the page parameter to cycle through pages. Pages breaks are determined by the limit parameter.

Parameters:
- page [integer](optional) A page to view.
- limit [integer](optional) Number of products per page.

Example Requests:
https://api.crystal-d.com/products?page=3&limit=10
https://api.crystal-d.com/products?page=10

Example 200 Response Body:

{
    "status": true,
    "message": "1 products retrieved.",
    "data": {
        "count": 1,
        "page": 1,
        "products": [
            {
                "sku": "2010",
                "name": "Dome Paperweight 3-1/2\" Dia.",
                "description": "Magnify a logo or message by etching on the bottom of this optical crystal dome.",
                "material": "Optical Crystal",
                "dimensions": "3-1/2\" Dia. x 2\" H",
                "weight": 2,
                "catalog_page": 322,
                "msrp": [
                    {
                        "qty": 5,
                        "price": 44,
                        "code": "R"
                    },
                    {
                        "qty": 10,
                        "price": 41.75,
                        "code": "R"
                    },
                    {
                        "qty": 50,
                        "price": 40.5,
                        "code": "R"
                    }
                ],
                "images": [
                    {
                        "url": "https://image.crystal-d.com/images/proddb/current/tpl/Dome_Paperweight_2010.pdf",
                        "role": "template"
                    },
                    {
                        "url": "https://image.crystal-d.com/images/proddb/current/info/prd_2010_info_6515.tif",
                        "role": "info"
                    },
                    {
                        "url": "https://image.crystal-d.com/images/proddb/current/large/Dome_Paperweight_2010.jpg",
                        "role": "large"
                    }
                ]
            }
        ]
    }
}

Response body schema:

data object
- count integer = Number of products on this page.
- page integer = Current page displayed.
- products array of objects
  - sku string = Stock keeping unit.
  - name string = Formal product name.
  - description string = Brief product desciption.
  - material string
  - dimensions string = Product dimensions.
  - weight float = Product weight in lbs.
  - catalog_page integer = Page in the Crystal D catalog the product appears on.
  - msrp array of objects = MSRP columns.
    - qty integer = Qty break for price.
    - price float
    - code string = Discount code.
  - images array of objects = Product Images.
    - url string
    - role string = The role this file plays.

GET /products/avail/{sku} Retrieve inventory for a single product.

Rundown:
Queries the most recent inventory for a given SKU. If the product is assembled from optional parts (Feature) will be returned instead. The optional part has to be determined before inventory can be acurately calculated.

Parameters:
None

Example Requests:
https://api.crystal-d.com/products/avail/2010
https://api.crystal-d.com/products/avail/4061

Example 200 Response Body:

{
    "status": true,
    "message": "Inventory retrieved successfully.",
    "data": {
        "sku": "2010",
        "avail": 314
    }
}

Example 200 Response Body (Feature product):

{
    "status": true,
    "message": "4061 requires an option selection for accurate availability.",
    "data": {
        "sku": "4061",
        "avail": "(Feature)"
    }
}