NAV Navbar
shell

Introduction

Welcome to the Brilliant Storefront API! You can use our API to access Storefront API endpoints as explained in this document. To gain access, please reach out to your company's Storefront Admin, or email us.

Authentication

To access every API entry point, you will need to supply an Authorization header. It can be generated like this:

# Ruby Example
# Generate your string by combinging the api key with your
# secret key. Notice the colon between them. 
str = "#{my_assigned_api_key}:#{my_assigned_secret_key}"

# Returns the Base64-encoded version of str. 
# This method complies with RFC 4648. No line feeds are added. 
my_enc_str = Base64.strict_encode64(str)
# With shell, you can just pass the correct header with each request
curl https://api.brilliantmade.com/v3/every/entrypoint
  -H "Authorization: Basic value_of_my_enc_str"

Brilliant uses API keys to allow access to the API. Store Administrators can create a new Brilliant API key in their dashboard.

Brilliant Store API expects a Basic Authorization Header containing a base64 encoded API Key and API Secret Key combined with a colon between them. Example:

API Key: f20e78a1d15cd2e976dddad7301d5c6a1137b2c49c67c382355a3775665047e1

API Secret Key: 8e02bf3ad43f9f0079850ea91510c4b6182e19480d963d3ddd73e2565ea5b279

Concatenate them delimited with a colon like so: f20e78a1d15cd2e976dddad7301d5c6a1137b2c49c67c382355a3775665047e1:8e02bf3ad43f9f0079850ea91510c4b6182e19480d963d3ddd73e2565ea5b279

Now, base64 encode this final value in RFC 4648 format. You should get the following without new lines and carriage returns:

ZjIwZTc4YTFkMTVjZDJlOTc2ZGRkYWQ3MzAxZDVjNmExMTM3YjJjNDljNjdjMzgyMzU1YTM3NzU2NjUwNDdlMTo4ZTAyYmYzYWQ0M2Y5ZjAwNzk4NTBlYTkxNTEwYzRiNjE4MmUxOTQ4MGQ5NjNkM2RkZDczZTI1NjVlYTViMjc5

Authorization: Basic ZjIwZTc4YTFkMTVjZDJlOTc2ZGRkYWQ3MzAxZDVjNmExMTM3YjJjNDljNjdjMzgyMzU1YTM3NzU2NjUwNDdlMTo4ZTAyYmYzYWQ0M2Y5ZjAwNzk4NTBlYTkxNTEwYzRiNjE4MmUxOTQ4MGQ5NjNkM2RkZDczZTI1NjVlYTViMjc5

Store

Get your store information

curl "https://api.brilliantmade.com/V3/store"
  -H "Authorization: Basic <auth string>"

The above command returns JSON structured like this:

{
    "name": "API Demo Store",
    "inactive": false,
    "product_groups": [
        {
            "id": 72,
            "name": "Apparel",
            "sort": 1,
            "hidden": false,
            "products": [
                {
                    "id": 2074,
                    "name": "Happy Hoodie",
                    "description": "Comfortable, cozy cotton hoodie!",
                    "sort": 1,
                    "max_quantity": 300,
                    "inactive": false,
                    "inventory_required": true,
                    "variants": [
                        {
                            "id": 79029,
                            "inventory_count": 200,
                            "size": "small",
                            "color": "black",
                            "flavor": null,
                            "color_hex_code": "000000",
                            "images": [
                                {
                                    "thumb": "https://cdn.example.com/uploads/variant_photo/photo/185427/thumb_black_hoodie.png",
                                    "medium": "https://cdn.example.com/uploads/variant_photo/photo/185427/medium_black_hoodie.png",
                                    "large": "https://cdn.example.com/uploads/variant_photo/photo/185427/large_black_hoodie.png",
                                    "xlarge": "https://cdn.example.com/uploads/variant_photo/photo/185427/black_hoodie.png"
                                }
                            ]
                        },
                        {
                            "id": 79030,
                            "inventory_count": 50,
                            "size": "medium",
                            "color": "black",
                            "flavor": null,
                            "color_hex_code": "000000",
                            "images": [
                                {
                                    "thumb": "https://cdn.example.com/uploads/variant_photo/photo/185427/thumb_black_hoodie.png",
                                    "medium": "https://cdn.example.com/uploads/variant_photo/photo/185427/medium_black_hoodie.png",
                                    "large": "https://cdn.example.com/uploads/variant_photo/photo/185427/large_black_hoodie.png",
                                    "xlarge": "https://cdn.example.com/uploads/variant_photo/photo/185427/black_hoodie.png"
                                }
                            ]
                        },
                        {
                            "id": 79031,
                            "inventory_count": 0,
                            "size": "large",
                            "color": "black",
                            "flavor": null,
                            "color_hex_code": "000000",
                            "images": [
                                {
                                    "thumb": "https://cdn.example.com/uploads/variant_photo/photo/185427/thumb_black_hoodie.png",
                                    "medium": "https://cdn.example.com/uploads/variant_photo/photo/185427/medium_black_hoodie.png",
                                    "large": "https://cdn.example.com/uploads/variant_photo/photo/185427/large_black_hoodie.png",
                                    "xlarge": "https://cdn.example.com/uploads/variant_photo/photo/185427/black_hoodie.png"
                                }
                            ]
                        }                        
                    ]
                }
            ]
        }
    ]
}

This endpoint retrieves your store information, including the product groups, products and variants assigned to your store. The variant ID's are what you will submit within your orders.

Products contain general information, such as the product's name and description, whether or not the product is active and if inventory is required to accept an order or not.

The variants have unique properties, such as size and color. They also display inventory data, eg. number of variants in stock. Before submitting an order, ensure that the stock on hand is greater than or equal to the quantity you are ordering or the order will not be created. We advise checking inventory immediately before submitting your order to avoid unexpected errors.

HTTP Request

GET https://api.brilliantmade.com/v3/store

Query Parameters

None

Fetch Store Orders

curl "https://api.brilliantmade.com/v3/orders?page=1&per=5"
  -X GET
  -H "Authorization: my_auth_keys"

Example return value

{
    "orders": [
        {
            "id": 26336,
            "created_at": "2019-12-17T06:06:44.000Z",
            "updated_at": "2019-12-17T06:06:44.000Z",
            "status": "created",
            "ship_status": "all_delivered",
            "order_item_count": 1
        },
        {
            "id": 26335,
            "created_at": "2019-12-17T05:55:19.000Z",
            "updated_at": "2019-12-17T05:55:19.000Z",
            "status": "created",
            "ship_status": "all_shipped",
            "order_item_count": 1
        },
        {
            "id": 26334,
            "created_at": "2019-12-17T05:54:17.000Z",
            "updated_at": "2019-12-17T05:54:17.000Z",
            "status": "created",
            "ship_status": null,
            "order_item_count": 1
        },
        {
            "id": 26333,
            "created_at": "2019-12-17T04:40:49.000Z",
            "updated_at": "2019-12-17T04:40:49.000Z",
            "status": "created",
            "ship_status": "all_delivered",
            "order_item_count": 1
        },
        {
            "id": 26332,
            "created_at": "2019-12-17T04:36:06.000Z",
            "updated_at": "2019-12-17T04:36:06.000Z",
            "status": "created",
            "ship_status": "all_shipped",
            "order_item_count": 1
        }
    ],
    "pagination": {
        "page": 1,
        "per": 5,
        "total_pages": 4,
        "total_count": 20
    }
}

Paginate through all of your store orders. They are ordered by their creation date descending.

To paginate, include query parameters like so:

?page=2&per=20

Max number per page is 20. Contact us if you need something special.

HTTP Request

GET https://api.brilliantmade.com/v3/orders?page=<int>&per=<int>

Query Parameters

Parameter Description
page Page number. Default is 1
per Number of orders per page. Default and maximum is 20.

Fetch an Order

curl "https://api.brilliantmade.com/v3/orders/13981"
  -X GET
  -H "Authorization: my_auth_keys"

The return value should be structured like this:

{
    "id": 26347,
    "created_at": "2019-12-17T08:59:07.000Z",
    "updated_at": "2019-12-17T08:59:07.000Z",
    "status": "created",
    "ship_status": null,
    "order_item_count": 1,
    "shipping_address": {
        "name": "John Smith",
        "company": "Test Co.",
        "address_1": "123 Test St.",
        "address_2": null,
        "city": "Seattle",
        "state": "WA",
        "zip": "98021",
        "country": "US",
        "phone": "(555)555-5555"
    },
    "custom_data": {
        "something": "anything",
        "this": "that"
    },
    "webhook_url": "https://api.example.com/test_webhook",
    "order_items": [
        {
            "variant_id": 79029,
            "quantity": 2,
            "notes": "Some Notes"
        }
    ],
    "shipments": []
}

Using an order ID, fetch the current order data.

HTTP Request

GET https://api.brilliantmade.com/v3/orders/{ID}

Query Parameters

ID of the order.

Create an Order

Orders are placed using variant ids, quantities, and a shipping address. You can also pass an optional webhook url that will be called whenever a status change happens on the order. The webhook entry point must accept a POST request with a JSON body.

You can also pass an optional object in your payload called "custom_data". Place anything you want into the custom data object. Brilliant does not modify it and we will send it to your webhook entry point as part of the post body for your convenience.

curl "https://api.brilliantmade.com/v3/orders"
  -X POST
  -H "Authorization: my_auth_keys"
  -d '{"order_items":[], "shipping_address":{}, "custom_data":{}, "webhook_url":""}'

The post body should be structured like so:

{
  "order_items": [
    {
      "variant_id": 79029,
      "quantity": 2,
      "notes": "Some Notes"
    }
  ],
  "shipping_address": {
    "name": "John Smith",
    "company": "Test Co.",
    "address_1": "123 Test St.",
    "address_2": null,
    "city": "Seattle",
    "state": "WA",
    "postal_code": "98021",
    "country": "US",
    "phone": "(555)555-5555"
  },
  "custom_data": {
    "something": "anything",
    "this": "that"
  },
  "webhook_url": "https://www.example.com/test_webhook"
}

The above command returns JSON structured like this:

{
    "code": 1200,
    "message": "Success",
    "payload": {
        "order_items": [
            {
                "variant_id": 79029,
                "quantity": 2,
                "notes": "Some Notes"
            }
        ],
        "shipping_address": {
            "name": "John Smith",
            "company": "Test Co.",
            "address_1": "123 Test St.",
            "address_2": null,
            "city": "Bothell",
            "state": "WA",
            "postal_code": "98021",
            "country": "US",
            "phone": "(555)555-5555"
        },
        "custom_data": {
            "something": "anything",
            "this": "that"
        },
        "webhook_url": "https://www.example.com/test_webhook"
    }
}

If the order is unsuccessful, the response will include some error information:

{
    "code": 2501,
    "invalid_records": [
        {
            "name": "Jan Smith",
            "company": "Test Co.",
            "address_1": "22411 Test Pl. W.",
            "address_2": null,
            "city": "Seattle",
            "state": "Washington",
            "postal_code": "98021",
            "country": "US",
            "phone": "(555)955-5555"
        }
    ],
    "message": "Address state State must be a valid 2 character state abbreviation",
    "body": {
        "order_items": [
            {
                "variant_id": 72799,
                "quantity": 1,
                "notes": "Test 2 Note"
            },
            {
                "variant_id": 72800,
                "quantity": 5,
                "notes": "Test 3 Note"
            }
        ],
        "shipping_address": {
            "name": "Jan Smith",
            "company": "Test Co.",
            "address_1": "22411 Test Pl. W.",
            "address_2": null,
            "city": "Seattle",
            "state": "Washington",
            "postal_code": "98021",
            "country": "US",
            "phone": "(555)955-5555"
        },
        "webhook_url": "https://example.com/order_listener",
        "custom_data": {
            "my": "context"
        }
    }
}

HTTP Request

POST https://api.brilliantmade.com/v3/orders

URL Parameters

None

POST Body Info

Addresses have some required fields:

Parameter Description
name Name of recipient
address_1 Required.
address_2 Optional.
city Required.
state Required. 2 characters.
postal_code Required.
country Required. 2 characters.
phone Optional. Phone number of recipient

Order items also have required fields:

Parameter Description
variant_id Required. The ID of the variant you wish to order.
quantity Required. The number of variants you wish to order.
note Optional.

Additional, Optional Post Data

Parameter Description
webhook_url Required if custom_data is set. This is a callback url that you expect us to call when your order status changes.
custom_data Optional. This is a JSON object holding data that you would like us to send back to you with every webhook call. Brilliant doesn't modify this data.

Fetch Store Users

curl "https://api.brilliantmade.com/v3/admin/store_users?page=1&per=5"
  -X GET
  -H "Authorization: my_auth_keys"

Example return value

{
    "store_users": [
        {
            "id": 26336,
            "crm_id": "U12341234123412345",
            "approver": false,
            "manager": false,
            "admin": false,
            "user": {
              "id": 1123,
              "name": "Ron Swanson",
              "email": "[email protected]"
            } 
        },
        {
            "id": 263344,
            "crm_id": "U12341234123412347",
            "approver": false,
            "manager": true,
            "admin": true,
            "user": {
              "id": 222,
              "name": "Sandra Dee",
              "email": "[email protected]"
            }
        }
    ],
    "pagination": {
        "page": 1,
        "per": 5,
        "total_pages": 1,
        "total_count": 20
    }
}

Paginate through all of your store users.

To paginate, include query parameters like so:

?page=2&per=20

Max number per page is 20. Contact us if you need something special.

HTTP Request

GET https://api.brilliantmade.com/v3/admin/store_users?page=<int>&per=<int>

Query Parameters

Parameter Description
page Page number. Default is 1
per Number of orders per page. Default and maximum is 20.

Add a store user

curl "https://api.brilliantmade.com/v3/admin/store_users"
  -X POST
  -H "Authorization: my_auth_keys"

The post body should be structured like so:

{
    "crm_id": "U123412341234554455",
    "approver": true,
    "manager": false,
    "admin": false,
    "user": {
      "name": "Ron Swanson",
      "email": "[email protected]"
    }
}

HTTP Request

GET https://api.brilliantmade.com/v3/admin/store_users

Query Parameters

Parameter Description
crm_id This is an optional field that is used by our Salesforce Touchpoint offering.
approver Whether or not this user will approve orders made by other store users. Boolean. Default false.
manager Whether or not this user will be a store manager. Boolean. Default false.
admin Whether or not this user will be a store administrator. Boolean. Default false.
user User attributes. Currently, email and name. Required.

Update a store user

curl "https://api.brilliantmade.com/v3/admin/store_user/:id"
  -X PATCH
  -H "Authorization: my_auth_keys"

The post body should be structured like so:

{
    "id": 12345,
    "crm_id": "U123412341234554455",
    "approver": true,
    "manager": false,
    "admin": false,
    "user": {
      "id": 4566,
      "name": "Ron Swanson",
      "email": "[email protected]"
    }
}

HTTP Request

PATCH https://api.brilliantmade.com/v3/admin/store_user/<integer id>

Query Parameters

Parameter Description
id Store user id
crm_id This is an optional field that is used by our Salesforce Touchpoint offering.
approver Whether or not this user will approve orders made by other store users. Boolean. Default false.
manager Whether or not this user will be a store manager. Boolean. Default false.
admin Whether or not this user will be a store administrator. Boolean. Default false.
user User attributes. Currently, id, email and name. Required.

Fulfillment

List Orders

curl "https://api.brilliantmade.com/fulfillment/v1/orders"
  -H "Authorization: Basic <auth string>"

The above command returns JSON structured like this:

{
    "orders": [
        {
            "id": 56789,
            "fulfillment_partner_id": 67890,
            "order_id": 23456,
            "company_id": 45678,
            "company_name": "Super Co.",
            "store_id": 12345,
            "store_name": "Super Inventory Storefront",
            "shipping_method": "UPS",
            "shipping_service": null,
            "order_items": [
                {
                    "order_item_id": 112233,
                    "product_id": 223344,
                    "sku": 334455,
                    "quantity": 1,
                    "unit_price": 0,
                    "line_total": 0,
                    "product_type": "",
                    "pdf": null
                }
            ],
            "subtotal": 0,
            "total": 0,
            "currency_code": "USD",
            "customs_info": null,
            "shipping_address": {
                "name": "Jan Tester",
                "company": "",
                "address_1": "123 Test Ln.",
                "address_2": "",
                "city": "Hastings on Hudson",
                "state": "NY",
                "zip_code": "10706",
                "country": "US",
                "phone": ""
            },
            "status": "shipped",
            "tracking_number": "TEST12345678"
        }
    ]
}

To see the orders that are ready to be fulfilled, use a GET call as shown to the right.

The response will contain an array of orders along with their IDs which can be used to update shipping statuses and add tracking numbers (see the Update Order for more info).

HTTP Request

GET https://api.brilliantmade.com/fulfillment/v1/orders?status=<all, ready, in_fulfillment, or shipped>

Query Parameters

Parameter Possible values
status (optional) all, ready, in_fulfillment, shipped

List Products

curl "https://api.brilliantmade.com/fulfillment/v1/skus"
  -H "Authorization: Basic <auth string>"

The above command returns JSON structured like this:

{
    "skus": [
        {
            "company_id": 321,
            "company_name": "Brilliant",
            "store_id": 123,
            "store_name": "My Brilliant Store",
            "sku": 234,
            "product_id": 345,
            "name": "Organic Infant Triblend Tee",
            "full_name": "Organic Infant Triblend Tee (Size 3-6 Months (S))",
            "color": null,
            "size": "3-6 Months (S)",
            "description": "Sustainable and eco-friendly soft fabric (made from post consumer plastic bottles). Sizes 3-6 months, 6-12 months, 12-18 months, and 18-24 months.\r\n\r\n4.5 oz / yard with a rib collar, double needle hems, side seams and a tearaway label. Combed ring spun 50% recycled rpet poly / 37% organic cotton / 13% rayon.",
            "other_attributes": {
                "product_type": null
            },
            "weight": "0.0",
            "weight_units": "ounces",
            "customs_info": {
                "description": null,
                "origin_country": "US",
                "hs_tarrif_number": null
            }
        },
        {
            "company_id": 321,
            "company_name": "Brilliant",
            "store_id": 123,
            "store_name": "My Brilliant Store",
            "sku": 987,
            "product_id": 876,
            "name": "Organic Infant Triblend Tee",
            "full_name": "Organic Infant Triblend Tee (Size 6-9 Months (M))",
            "color": null,
            "size": "6-9 Months (M)",
            "description": "Sustainable and eco-friendly soft fabric (made from post consumer plastic bottles). Sizes 3-6 months, 6-12 months, 12-18 months, and 18-24 months.\r\n\r\n4.5 oz / yard with a rib collar, double needle hems, side seams and a tearaway label. Combed ring spun 50% recycled rpet poly / 37% organic cotton / 13% rayon.",
            "other_attributes": {
                "product_type": null
            },
            "weight": "0.0",
            "weight_units": "ounces",
            "customs_info": {
                "description": null,
                "origin_country": "US",
                "hs_tarrif_number": null
            }
        }
   ]
}

To see all of the skus that can be fulfilled, use a GET call as shown to the right.

The response will contain an array of skus along with their IDs which can be used to update inventory (see the Update Inventory for more info).

HTTP Request

GET https://api.brilliantmade.com/fulfillment/v1/skus

Query Parameters

None

Update Order

curl "https://api.brilliantmade.com/fulfillment/v1/orders/update"
  -X POST
  -H "Authorization: my_auth_keys"
  -d '{"id": 177777, "status": "shipped", "shipping_method": "UPS", "tracking_number": "TEST12345678"}'

The above command returns JSON structured like this:

{
    "id": 177777,
    "fulfillment_partner_id": 112233,
    "order_id": 223344,
    "company_id": 334455,
    "company_name": "StoreCo",
    "store_id": 123123,
    "store_name": "StoreCo Store Front",
    "shipping_method": "UPS",
    "shipping_service": null,
    "order_items": [
        {
            "order_item_id": 556677,
            "product_id": 776655,
            "sku": 112233,
            "quantity": 1,
            "unit_price": 0,
            "line_total": 0,
            "product_type": "",
            "pdf": null
        }
    ],
    "subtotal": 0,
    "total": 0,
    "currency_code": "USD",
    "customs_info": null,
    "shipping_address": {
        "name": "Amy Smith",
        "company": "",
        "address_1": "123 Test Ave.",
        "address_2": "",
        "city": "Hastings on Hudson",
        "state": "NY",
        "zip_code": "10706",
        "country": "US",
        "phone": ""
    },
    "status": "externally_shipped",
    "tracking_number": "TEST12345678"
}

With this API call, you can update an order's status, shipping method, and/or tracking number.

HTTP Request

POST|PUT|PATCH https://api.brilliantmade.com/fulfillment/v1/orders/update

JSON Request Body Parameters

Parameter Possible values
id (required) This is order ID found in the List Orders call
status When an order has shipped, set the status to 'shipped'. Possible values are "canceled", "created", "creation_in_process", "failed", "new", "on_hold", "purchased", "purchase_in_process", "in_fulfillment", "shipped"

(optional but required if shipped)

shipping_method Examples, "UPS", "USPS", "GSO", "FedEx", "Wholesaler", "Courier", nil, "DHL", "UPSMailInnovations", "DHLExpress", "FedExSmartPost", "OnTrac", "RoyalMail", "AustraliaPost", "fedex", "FedexSmartPost"

(optional but required if value is available)

tracking_number Tracking number assigned by the shipper

(optional but required if value is available)

Update Inventory

curl "https://api.brilliantmade.com/fulfillment/v1/skus/update_inventory_count"
  -X POST
  -H "Authorization: my_auth_keys"
  -d '{"sku": 12345, "reason": "Decrementing Inventory", "inventory_adjustment": -1, "tracking_number": "TEST1122334455"}'

The above command returns JSON structured like this:

{
    "message": "OK",
    "original_payload": {
        "sku": 12345,
        "reason": "Decrementing Inventory",
        "inventory_adjustment": -1,
        "tracking_number": "TEST1122334455"
    }
}

With this API call, you can update a SKU's inventory, and/or provide a tracking number for an inbound shipment.

HTTP Request

POST|PUT|PATCH https://api.brilliantmade.com/fulfillment/v1/skus/update_inventory_count

JSON Request Body Parameters

Parameter Possible values
sku (required) This is SKU found in the List Products call
reason (optional) Tell us the purpose of the adjustment
inventory_adjustment (required) Examples: 1, 20, -2
tracking_number (optional) If this is an inbound shipment to your location, provide the tracking number

Errors

The Storefront API uses the following HTTP error codes:

Error Code Meaning
401 Unauthorized -- Your API key is wrong or disabled.
404 Not Found.
429 Too Many Requests -- You've hit your throttling limit. Please lower the frequency of your requests.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Response codes (Non-fulfillment API requests)

The response code portions of the response body:

{
  "code": 1200,
  "message": "Looks good.",
  ...
}
{
  "code": 2501,
  "message": "Address state State must be a valid 2 character state abbreviation",
  "invalid_records": [
    {
      "name": "John Smith",
      "company": "Test Co.",
      "address_1": "123 Test St.",
      "address_2": null,
      "city": "Bothell",
      "state": "Washington",
      "postal_code": "98021",
      "country": "US",
      "phone": "(555)555-5555"
    }
  ],
  ...
}

There are various response codes that the API will return to give you a programmatic answer:

Code Meaning
1200 Everything was OK.
1404 Not found. If the call expected an ID as a url parameter, please ensure that it is correct.
1500 There was an unexpected error and engineers are taking a look. Please resubmit your request later.
2501 There was a problem with an address. The order has not been submitted.
2502 There was a problem with one or more of the variant ID's you submitted. Please review them and make sure that they belong to your store. The order has not been submitted.
2503 Stock was too low for one or more of the variants you are trying to order. Please contact Brilliant to increase stock levels. The order has not been submitted.
2504 One or more of the order item entries is specifying the same variant id. Please make the order item entries unique and adjust the quantity instead. The order has not been submitted.
2505 The payload you submitted for an order is missing an order_items section or it is empty. The order has not been submitted.
2506 One or more of the variants you are trying to order are inactive. Check into the possibility of re-activating them, or remove these variants from your payload.
3501 Validation passed, however, we could not insert your order because we ran into some internal issues. The engineers have been notified and will work on the issue. Please resubmit your payload later.
3502 An unexpected issue occurred and engineers have been notified. Please resubmit your payload later.
3503 There was an issue with the payload and the API couldn't handle it appropriately. Engineers have been notified. Please resubmit your payload later.