API Documentation


The API can be used to access your account programmatically. You will be able to do things such as downloading and processing orders or synchronising your inventory with your own website.

To access the API you first need to create an account. Once you have an account, you can generate an API key from the page in your account. Once you have the API key you can make a request to any of the methods listed below that your key has permission for. The key and any arguments should be added as parameters onto the request, for example GET https://api.brickowl.com/v1/order/view?key=KEY&order_id=100

Order

The orders API allows you to download and process your stores orders and orders you have placed in stores.

List

GET https://api.brickowl.com/v1/order/list

Get a list of your orders

Arguments
  • status (Optional) - Order status filter, use the formatted name or the numeric ID
    • 0 - Pending
    • 1 - Payment Submitted
    • 2 - Payment Received
    • 3 - Processing
    • 4 - Processed
    • 5 - Shipped
    • 6 - Received
    • 7 - On Hold
    • 8 - Cancelled
  • order_time (Optional) - Unix Timestamp to limit the orders returned to those with a timestamp greater than or equal to the one provided.
  • limit (Optional) - Limit the amount of results returned, defaults to 500.
  • list_type (Optional) - Order list type
    • store - Store orders
    • customer - Orders you have placed

View

GET https://api.brickowl.com/v1/order/view

Retrieve full order details

Arguments
  • order_id - The orders unique ID

Items

GET https://api.brickowl.com/v1/order/items

Retrieve order items

Arguments
  • order_id - The orders unique ID

Tracking

POST https://api.brickowl.com/v1/order/tracking

Attach a Shipping Tracking ID number to the order

Arguments
  • order_id - The orders unique ID
  • tracking_id - Tracking ID

Notify

POST https://api.brickowl.com/v1/order/notify

You can set an IP address to be notified instantly when an order is placed via a HTTP request. The request will be placed to http://IP_ADDR:42500/brick_owl_order_notify. You will need to setup an appropriate webserver to receive the request. This service is not guaranteed, so you will also need to check at an interval. The request will not contain any data, and is to notify your software so that you can then check for orders in the usual way.

Arguments
  • ip - The IP address to be notified

Leave Feedback

POST https://api.brickowl.com/v1/order/feedback

Leave feedback for an order

Arguments
  • order_id - The orders unique ID
  • comment (Optional) - The feedback comment
  • rating - The feedback rating.
    • 1 - Positive
    • 0 - Neutral
    • -1 - Negative

(DEPRECIATED) Process

POST https://api.brickowl.com/v1/order/process

Mark the order as shipped and send the customer the shipment e-mail. This will also capture payment if appropriate.

Arguments
  • order_id - The orders unique ID

Set Status

POST https://api.brickowl.com/v1/order/set_status

Change the status of the order

Arguments
  • order_id - The orders unique ID
  • status_id - Order Status ID.
    • 1 - Payment Submitted
    • 2 - Payment Received
    • 3 - Processing
    • 4 - Processed
    • 5 - Shipped
    • 6 - Received

Store Inventory

The store inventory API allows you to download and update your store inventory.

List

GET https://api.brickowl.com/v1/inventory/list

Get a list of your lots with details

Arguments
  • type (Optional) - Filter by item type like Set/Part/Minifigure
  • active_only (Optional) - Include only items that are for sale and have a quantity > 0. 0 or 1. Default: 1
  • external_id_1 (Optional) - Optional external lot identifier to return one lot
  • lot_id (Optional) - Optional Brick Owl lot ID to return one lot

Update

POST https://api.brickowl.com/v1/inventory/update

Update a lots data. You must pass only one identifier and at least one update field.

Arguments
  • external_id (Optional) - External lot identifier
  • lot_id (Optional) - Brick Owl lot ID
  • absolute_quantity (Optional) - The absolute new quantity
  • relative_quantity (Optional) - A positive or negative amount to adjust the existing quantity by
  • for_sale (Optional) - 0 or 1 specifying if an item should be available for sale or not. This works independently of the quantity field, it is usually used for in stock items that you don't want to sell at the moment.
  • price (Optional) - The price of the item. It must be a positive number, it will be rounded to 3 digits of precision.
  • my_cost (Optional) - The price you paid for the item for your own records. It must be a positive number, it will be rounded to 3 digits of precision.
  • personal_note (Optional) - Personal note.
  • public_note (Optional) - Public note.
  • bulk_qty (Optional) - Bulk Quantity. A positive number greater than one.
  • tier_price (Optional) - Tier prices. Maximum of three tier prices, in the following format 'tier1quantity:tier1price,tier2quantity:tier2price,tier3quantity:tier3price'. For example '100:0.05,200:0.04'. To remove tier pricing, use the value 'remove'.
  • condition (Optional) - A Brick Owl condition ID, for example 'new' or 'useda'.
  • update_external_id_1 (Optional) - Change the first external ID associated with the lot

Delete

POST https://api.brickowl.com/v1/inventory/delete

Deletes a lot. Bear in mind this will remove it from customers carts/quotes

Arguments
  • external_id (Optional) - External lot identifier
  • lot_id (Optional) - Brick Owl lot ID

Create

POST https://api.brickowl.com/v1/inventory/create

Create a new lot. You must pass an item identifier. Parts need a color.

Arguments
  • boid - A BOID
  • color_id (Optional) - A Brick Owl color ID. This is required for Parts, optional for Gear and not allowed for other item types.
  • quantity - The quantity of the lot, a whole number greater than zero.
  • price - The price of the lot. It must be a positive number, it will be rounded to 3 digits of precision.
  • condition - A Brick Owl condition ID, for example 'new' or 'useda'.
  • external_id (Optional) - An optional external ID for reference

Wishlist

The wishlist API allows you to view and update your wishlists.

Lists

GET https://api.brickowl.com/v1/wishlist/lists

Get a list of your wishlists

Lots

GET https://api.brickowl.com/v1/wishlist/lots

Get a list of a specific wishlists lots with details

Arguments
  • wishlist_id - The wishlists unique ID

Update

POST https://api.brickowl.com/v1/wishlist/update

Update a lots data. You must pass at least one update field.

Arguments
  • wishlist_id - The wishlists unique ID
  • lot_id - Wishlist lot ID
  • minimum_quantity (Optional) - The minimum quantity required, greater than 0
  • maximum_price (Optional) - The price of the item. It must be a positive number or blank, it will be rounded to 3 digits of precision.
  • note (Optional) - Note
  • minimum_condition (Optional) - A Brick Owl condition ID, for example 'new' or 'useda' or blank.

Create Lot

POST https://api.brickowl.com/v1/wishlist/create_lot

Create a new lot. You must pass an item identifier. Parts need a color.

Arguments
  • wishlist_id - The wishlists unique ID
  • boid - A BOID
  • color_id (Optional) - A Brick Owl color ID. This is required for Parts, optional for Gear and not allowed for other item types.

Create List

POST https://api.brickowl.com/v1/wishlist/create_list

Create a new wishlist.

Arguments
  • name - A unique name for the wishlist
  • description (Optional) - An optional description

Catalog

The catalog API allows you to retrieve information about items in the catalog. To access this API contact us.

List

GET https://api.brickowl.com/v1/catalog/list

Get a list of all the items in the catalog

Arguments
  • type (Optional) - Filter by item type. Set, Part, Minifigure, Gear, Sticker, Packaging
  • brand (Optional) - Filter by brand

Lookup

GET https://api.brickowl.com/v1/catalog/lookup

Retrieve details about an item in the catalog by BOID.

Arguments
  • boid - BOID

ID Lookup

GET https://api.brickowl.com/v1/catalog/id_lookup

Retrieve the possible BOIDs for another ID such as a set number or design ID.

Arguments
  • id - ID
  • type - Filter by item type. Set, Part, Minifigure, Gear, Sticker, Packaging
  • id_type (Optional) - Filter by ID type. For example, use item_no, design_id or set_number

Bulk

GET https://api.brickowl.com/v1/catalog/bulk

Retrieve bulk catalog dumps. This API should only be used when instructed to do so.

Arguments
  • type - Bulk type

Lookup (Bulk)

GET https://api.brickowl.com/v1/catalog/bulk_lookup

Retrieve details about multiple items in the catalog at once.

Arguments
  • boids - A comma separated list of boids. Maximum amount: 100

Inventory

GET https://api.brickowl.com/v1/catalog/inventory

Retrieve an items inventory.

Arguments
  • boid - BOID

Color List

GET https://api.brickowl.com/v1/catalog/color_list

Retrieve a list of the colors.

Data Type List

GET https://api.brickowl.com/v1/catalog/data_type_list

Retrieve a list of the various types of data an item can have submitted against it.

Condition List

GET https://api.brickowl.com/v1/catalog/condition_list

Retrieve a list of the condition a lot can have.

Bulk

Batch multiple requests together into one bulk request to save on request overhead.

Batch

POST https://api.brickowl.com/v1/bulk/batch

Batch up to 50 requests in one go.

Arguments
  • requests - JSON Array of endpoints with arguments in the format {"requests": [{"endpoint":"catalog/search","request_method":"GET","params":[{"query":"Vendor"}]}, {"endpoint":"catalog/search","request_method":"GET","params":[{"query":"Laser"}]}]}. Or for POST {"requests": [{"endpoint":"inventory/update","request_method":"POST","params":[{"lot_id":"IDHERE","absolute_quantity":2}]}]}

Catalog Edit

Submit changes to the catalog.

Edit (Basic)

POST https://api.brickowl.com/v1/catalog_edit/basic_edit

Submit a change request for an item

Arguments
  • boid - BOID
  • type - Submission type. Choose from: base_name, variant_desc, decoration_description, base_name, first_available, length, width, height, stud_length, stud_width, stud_height, weight, description
  • value - Submission value.

Edit (File)

POST https://api.brickowl.com/v1/catalog_edit/file

Submit a change request for an item that needs a file

Arguments
  • boid - BOID
  • type - Submission type. Choose from: primary_image
  • data - Base64 Encoded raw file data
  • content_type - Content type can be one of the following: image/png, image/x-png, image/jpeg, image/jpg, image/gif

User

This is for accessing users accounts.

Get Token

GET https://api.brickowl.com/v1/user/get_token

Get a users token

Arguments
  • username - Username
  • password - Password
  • application_name - Application Name

Details

GET https://api.brickowl.com/v1/user/details

Retrieve details about the user who the API key belongs to. This will include store details if they have one.

Token

This is for accessing details about a token.

Details

GET https://api.brickowl.com/v1/token/details

Retrieve details about the user who the API key belongs to. This will include store details if they have one.

Affiliate Stores

This API is for use by our affiliate partners, stores that have opted in can have their details retrieved through this API.

Stores

GET https://api.brickowl.com/v1/affiliate/stores

Get a list of all the stores that have opted in to your affiliate scheme

Lots

GET https://api.brickowl.com/v1/affiliate/lots

Retrieve the stores lots

Arguments
  • store_id - The stores unique ID
  • type (Optional) - Filter by item type like Set/Part/Minifigure

Lots by ID

GET https://api.brickowl.com/v1/affiliate/item_lots

Retrieve lots for an item identified by an id

Arguments
  • type - Filter by item type like Set/Part/Minifigure
  • id - ID
  • id_type - Specify the ID Type