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/V2/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/V2/store"
  -H "Authorization: Basic <auth string>"

The above command returns JSON structured like this:

{
  "name":"Brilliant Store",
  "inactive":false,
  "products":[
    {
      "id":24452,
      "name":"Top Tier Gift Set",
      "description":"Includes a MIIR wide-mouth water bottle, 2 La Newyorkina brownies, and a Fabrizio white soft cover notebook.",
      "inactive":false,
      "inventory_required":true,
      "variants":[
        {
          "id":72774,
          "product_id":24452,
          "inventory_count":-1,
          "size":null,
          "color":null,
          "flavor":null,
          "images": {
            "thumb": "https://assets.example.com/uploads/variant_photo/photo/152292/thumb_bri-deluxe-pack.jpg",
            "medium": "https://assets.example.com/uploads/variant_photo/photo/152292/medium_bri-deluxe-pack.jpg",
            "large": "https://assets.example.com/uploads/variant_photo/photo/152292/large_bri-deluxe-pack.jpg",
            "xlarge": "https://assets.example.com/uploads/variant_photo/photo/152292/xlarge_bri-deluxe-pack.jpg"
          }
        }
      ]
    },
    {
      "id":24454,
      "name":"Bottle + Notebook Gift Set",
      "description":"Includes a MIIR wide-mouth water bottle and a Fabrizio white soft cover notebook",
      "inactive":false,
      "inventory_required":true,
      "variants":[
        {
          "id":72776,
          "product_id":24454,
          "inventory_count":22,
          "size":null,
          "color":null,
          "flavor":null,
          "images": {
            "thumb": "https://assets.example.com/uploads/variant_photo/photo/152292/thumb_bri-deluxe-pack.jpg",
            "medium": "https://assets.example.com/uploads/variant_photo/photo/152292/medium_bri-deluxe-pack.jpg",
            "large": "https://assets.example.com/uploads/variant_photo/photo/152292/large_bri-deluxe-pack.jpg",
            "xlarge": "https://assets.example.com/uploads/variant_photo/photo/152292/xlarge_bri-deluxe-pack.jpg"
          }
        }
      ]
    },
    {
      "id":24453,
      "name":"Notebook + Two Brownies",
      "description":"Includes 2 La Newyorkina brownies, and a Fabrizio white soft cover notebook.",
      "inactive":false,
      "inventory_required":true,
      "variants":[
        {
          "id":72775,
          "product_id":24453,
          "inventory_count":-1,
          "size":null,
          "color":null,
          "flavor":null,
          "images": {
            "thumb": "https://assets.example.com/uploads/variant_photo/photo/152292/thumb_image.jpg",
            "medium": "https://assets.example.com/uploads/variant_photo/photo/152292/medium_image.jpg",
            "large": "https://assets.example.com/uploads/variant_photo/photo/152292/large_image.jpg",
            "xlarge": "https://assets.example.com/uploads/variant_photo/photo/152292/xlarge_image.jpg"
          }
        }
      ]
    },
    {
      "id":24455,
      "name":"Desk Essentials",
      "description":"A fun and colorful Maine Pouch, packed with some of our favorite goodies in a custom box. Contents include a slide-out gum pack, half-sticky note cube, two gel pens, a vanilla lip balm ball, and a set of pinback buttons that say \"Brilliant\", \"I (HEART) Marketing\" and \"Branding Geek\".",
      "inactive":false,
      "inventory_required":true,
      "variants":[
        {
          "id":72777,
          "product_id":24455,
          "inventory_count":70,
          "size":null,
          "color":null,
          "flavor":null,
          "images": {
            "thumb": "https://assets.example.com/uploads/variant_photo/photo/152292/thumb_image.jpg",
            "medium": "https://assets.example.com/uploads/variant_photo/photo/152292/medium_image.jpg",
            "large": "https://assets.example.com/uploads/variant_photo/photo/152292/large_image.jpg",
            "xlarge": "https://assets.example.com/uploads/variant_photo/photo/152292/xlarge_image.jpg"
          }
        }
      ]
    },
    {
      "id":24456,
      "name":"16 oz. Wide Mouth Bottle",
      "description":"16 oz. double wall vacuum insulated bottle stays cold for 24 hours, and hot for 12. Fits most standard cup holders. BPA free.",
      "inactive":false,
      "inventory_required":true,
      "variants":[
        {
          "id":72778,
          "product_id":24456,
          "inventory_count":20,
          "size":null,
          "color":null,
          "flavor":null,
          "images": {
            "thumb": "https://assets.example.com/uploads/variant_photo/photo/152292/thumb_image.jpg",
            "medium": "https://assets.example.com/uploads/variant_photo/photo/152292/medium_image.jpg",
            "large": "https://assets.example.com/uploads/variant_photo/photo/152292/large_image.jpg",
            "xlarge": "https://assets.example.com/uploads/variant_photo/photo/152292/xlarge_imge.jpg"
          }
        }
      ]
    }
  ]
}

This endpoint retrieves your store information, including the 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/V2/store

Query Parameters

None

Fetch Store Orders

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

Example return value

{
  "orders": [
    {
      "id": 14002,
      "created_at": "2018-08-21T03:24:34.000Z",
      "updated_at": "2018-08-21T03:24:34.000Z",
      "status": "created",
      "ship_status": null,
      "order_item_count": 1
    },
    {
      "id": 14001,
      "created_at": "2018-08-21T02:17:17.000Z",
      "updated_at": "2018-08-21T02:17:17.000Z",
      "status": "created",
      "ship_status": null,
      "order_item_count": 1
    },
    {
      "id": 13986,
      "created_at": "2018-08-17T17:42:23.000Z",
      "updated_at": "2018-08-17T17:42:23.000Z",
      "status": "created",
      "ship_status": null,
      "order_item_count": 1
    },
    {
      "id": 13985,
      "created_at": "2018-08-17T16:45:30.000Z",
      "updated_at": "2018-08-17T16:45:30.000Z",
      "status": "created",
      "ship_status": null,
      "order_item_count": 1
    },
    {
      "id": 13982,
      "created_at": "2018-08-17T07:57:24.000Z",
      "updated_at": "2018-08-17T07:57:24.000Z",
      "status": "created",
      "ship_status": null,
      "order_item_count": 1
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 5,
    "total_pages": 2,
    "total_orders": 7
  }
}

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/V2/store/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/V2/store/order/123"
  -X GET
  -H "Authorization: my_auth_keys"

The return value should be structured like this:

{
  "id": 123,
  "created_at": "2018-08-21T03:24:34.000Z",
  "updated_at": "2018-08-21T03:24:34.000Z",
  "status": "created",
  "ship_status": null,
  "shipping_address": {
    "name": "Jill Gilgooley",
    "company": "Test Co.",
    "address_1": "123 Test Pl. W.",
    "address_2": null,
    "city": "Bothell",
    "state": "WA",
    "postal_code": "98021",
    "country": "US",
    "phone": "(555)555-5555"
  },
  "order_items": [
    {
      "variant_id": 79029,
      "quantity": 1,
      "notes": "Test Note"
    }
  ],
  "webhook_url": "https://example.com/order_listener",
  "custom_data": {
    "my": "data"
  }  
}

Using an order ID, fetch the current order data.

HTTP Request

GET https://api.brilliantmade.com/V2/store/order/{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/V2/store/order"
  -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": 1234,
      "quantity": 2,
      "note": "Some text"
    },
    {
      "variant_id": 5678,
      "quantity": 1,
      "note": "Some more text"
    }
  ],
  "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://api.example.com/brilliant/listener?hi=bye"
}

The above command returns JSON structured like this:

{
  "code": 1200,
  "message": "Success",
  "payload": {
    "order_items": [
      {
        "variant_id": 1234,
        "quantity": 2,
        "notes": "Some text"
      },
      {
        "variant_id": 1234,
        "quantity": 2,
        "notes": "Some more text"
      }
    ],
    "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"
    },
    "webhook_url": "https://api.example.com/brilliant/listener?hi=bye",
    "custom_data": {
      "something": "anything",
      "this": "that"
    }
  }
}

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

{
    "code": 2501,
    "invalid_records": [
        {
            "name": "Jan Wayward",
            "company": "Test Co.",
            "address_1": "22411 Test Pl. W.",
            "address_2": null,
            "city": "Bothell",
            "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 Wayward",
            "company": "Test Co.",
            "address_1": "22411 Test Pl. W.",
            "address_2": null,
            "city": "Bothell",
            "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/V2/store/order

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.

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

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.