You are here:
    Home
  • >
    • API Documentation

API Documentation

The Brick Owl API can be used to access the website programmatically. It is mainly used for order management or inventory syncronisation. Usage of the API is dependent on adhering to the API section of the terms and conditions.

To access the API you first need to create an 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 API is rated limited to 600 requests per minute for most requests, or 100 requests per minute for bulk/batch.

For GET request the key and any parameters should be added as parameters onto the request, for example https://api.brickowl.com/v1/order/view?key=KEY&order_id=92
For POST requests, the key and any parameters should be in the body of the request and have a content type of application/x-www-form-urlencoded

Linking

If you are making a tool, you can provide a link to any item in the catalog with the URL format https://www.brickowl.com/boid/BOIDHERE

Or you you can link directly to our search:
Elements IDs: https://www.brickowl.com/search/catalog?query=6460836&utm_source=APPNAME&jump=1
Sets with Set ID: https://www.brickowl.com/search/catalog?query=40806-1&jump=1&cat=3&utm_source=APPNAME

Query is the search term. Utm_source is for tracking. jump=1 tells the system to go straight to the item page if there is only a single search result. Cat=3 filters to sets (rather than also showing instructions).

Add to cart / wishlist

If you want to add items to a cart, you can make a form in your website to do a POST submission to https://STORESUBDOMAIN.brickowl.com/addtocart with the POST parameter 'data' and a value with JSON in the format {"items":[{"lot_id":"36235","qty":"1"},{"lot_id":"212991","qty":"2"}]}

If you want to add items to a wishlist, you can make a form in your website to do a POST submission to https://www.brickowl.com/addtowishlist with the POST parameter 'data' and a value with JSON in the format {"items":[{"boid":"44980-38","qty":"2"},{"boid":"108285-41","qty":"5"}]}


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":"order/items","request_method":"GET","params":[{"order_id":"1"}]}, {"endpoint":"order/items","request_method":"GET","params":[{"order_id":"2"}]}]}. Or for POST {"requests": [{"endpoint":"inventory/update","request_method":"POST","params":[{"lot_id":"IDHERE","absolute_quantity":2}]}]}

Catalog

The catalog API allows for retrieval of information about items in the catalog. This API is primarily intended for stores to create order and inventory management tools. The API is not available for collection tracking tools. Access is only granted on a case by case basis. For access, please contact us. Please include the intended purpose, what data will be used, and where and how the data will be displayed.

List (Catalog Approval required)

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
    • Part
    • Set
    • Minifigure
    • Gear
    • Sticker
    • Minibuild
    • Instructions
    • Packaging
  • brand (Optional) - Filter by brand

Lookup (Catalog Approval required)

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

Retrieve details about an item in the catalog by BOID

Arguments
  • boid - A BOID

Color List

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

Retrieve a list of the colors

Condition List

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

Retrieve a list of the conditions a lot can have

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
    • Part
    • Set
    • Minifigure
    • Gear
    • Sticker
    • Minibuild
    • Instructions
    • Packaging
  • id_type (Optional) - Filter by ID type.
    • item_no - lego 7 digit item number
    • design_id - Part design ID
    • bl_item_no - BL ID
    • set_number - Set number

Price History (Catalog Approval required)

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

Retrieve summarised pricing information for an item in the catalog. All prices are in GBP

Arguments
  • boid - A BOID

Availability (Catalog Approval required)

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

Retrieve a list of lots for sale for an item in the catalog by BOID.

Arguments
  • boid - A BOID
  • quantity (Optional) - The minimum quantity required, greater than 0
  • country - iso2 country code for shipping destination
  • condition (Optional) - To specify a specific lot condition to be returned
    • new - New
    • news - New (Sealed)
    • newc - New (Complete)
    • newi - New (Incomplete)
    • usedc - Used (Complete)
    • usedi - Used (Incomplete)
    • usedn - Used (Like New)
    • usedg - Used (Good)
    • useda - Used (Acceptable)
    • other - Other
  • store_country (Optional) - Optional iso2 country code for store location
  • limit (Optional) - Range limit, limits the amount of results returned. Default 100. Limit 300.

Availability (Basic) (Catalog Approval required)

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

Retrieve the cheapest lot price for an item in the catalog. All prices are in GBP.

Arguments
  • boid (Optional) - Brick Owl ID
  • minifigure_id (Optional) - Third party minifigure ID
  • item_no (Optional) - LEGO 7 digit part item number
  • country - iso2 country code for shipping destination

Bulk (Catalog Approval required)

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

Retrieve bulk catalog dumps. These are very large JSON objects. For example, 'full_catalog' contains the entire catalog. This should only be accessed infrequently, like once per day.

Arguments
  • type - Bulk type. Use 'full_catalog_sets' for all set data. Use 'full_catalog' for the entire catalog.

Lookup (Bulk) (Catalog Approval required)

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 (Catalog Approval required)

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

Retrieve an items inventory

Arguments
  • boid - BOID

Field Options List

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

Retrieve a list of the options a catalog field can have

Arguments
  • type - Field type
    • category_0 - Category 0
    • eye_color - Eye Color
    • eyebrow_color - Eyebrow Color
    • facial_expression - Facial Expression
    • facial_hair_color - Facial Hair Color
    • facial_hair_type - Facial Hair Type
    • gender - Gender
    • packaging_type - Packaging Type
    • remove_image - Remove Image
    • sides_printed - Sides Printed
    • sticker_sheet_color - Sticker Sheet Color
    • theme_0 - Theme 0
    • type - Type

Catalog Cart (Basic) (Catalog Approval required)

POST https://api.brickowl.com/v1/catalog/cart_basic

Create a catalog cart using Design IDs and Lego Color IDs and get a total price in the currency of the country. The cart ID can be passed to /catalog_cart_load/ID for a user to access it

Arguments
  • items - JSON structure in the format {"items":[{"design_id":"3034","color_id":21,"qty":"1"},{"design_id":"3004","color_id":23,"qty":"2"}]}
  • condition - A minimum condition code for the items.
    • new - New
    • news - New (Sealed)
    • newc - New (Complete)
    • newi - New (Incomplete)
    • usedc - Used (Complete)
    • usedi - Used (Incomplete)
    • usedn - Used (Like New)
    • usedg - Used (Good)
    • useda - Used (Acceptable)
    • other - Other
  • country - ISO2 country code for shipping destination

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. Some fields are item or user specific, all fields will return appropriate error information

Arguments
  • boid - BOID
  • type - Submission type
    • base_name - Base Name (string)
    • basic_decoration_description - Basic Decoration Description (string)
    • category_0 - Category 0 (option)
    • cleaned_lego_name - Cleaned Lego Name (string)
    • delete - Delete (binary)
    • delete_scheduled - Delete Scheduled (binary)
    • description - Description (string)
    • eye_color - Eye Color (option)
    • eyebrow_color - Eyebrow Color (option)
    • facial_expression - Facial Expression (option)
    • facial_hair_color - Facial Hair Color (option)
    • facial_hair_type - Facial Hair Type (option)
    • first_available - First Available (number)
    • gender - Gender (option)
    • height - Height (number)
    • our_asin - ID - ASIN (string)
    • our_bl_item_no - ID - BL ID (string)
    • our_set_number - ID - Brickset Set Number (string)
    • our_design_id - ID - Design ID (string)
    • our_ean - ID - EAN Barcode (string)
    • our_isbn - ID - ISBN (string)
    • our_ldraw - ID - LDraw Item ID (string)
    • our_cs_set_number - ID - Lego CS Set Number (string)
    • our_item_no - ID - Lego Item No (string)
    • our_obsolete_design_id - ID - Obsolete Design ID (string)
    • our_official_set_number - ID - Official Set Number (string)
    • our_other_design_id - ID - Other Design ID (string)
    • our_other - ID - Other ID (string)
    • our_peeron_id - ID - Peeron ID (string)
    • our_rebrickable_id - ID - Rebrickable ID (string)
    • our_upc - ID - UPC Barcode (string)
    • instructions_booklets - Instructions Booklets (number)
    • instructions_pages - Instructions Pages (number)
    • length - Length (number)
    • packaging_type - Packaging Type (option)
    • remove_image - Remove Image (option)
    • ship_height - Ship Height (number)
    • ship_length - Ship Length (number)
    • ship_width - Ship Width (number)
    • sides_printed - Sides Printed (option)
    • sticker_sheet_color - Sticker Sheet Color (option)
    • stud_height - Stud Height (number)
    • stud_length - Stud Length (number)
    • stud_width - Stud Width (number)
    • theme_0 - Theme 0 (option)
    • type - Type (option)
    • variant_child_assembly_mask - Variant Child Assembly Mask (string)
    • variant_child_decoration_mask - Variant Child Decoration Mask (string)
    • variant_desc - Variant Desc (string)
    • weight - Weight (number)
    • width - Width (number)
  • value - Submission value

Collection

The collection API allows you to view and update your collection

Lots

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

Get a list of lots with details

Update Lot

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

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

Arguments
  • lot_id - Lot ID
  • quantity (Optional) - The minimum quantity required, greater than 0
  • 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
  • condition (Optional) - Condition ID
    • new - New
    • news - New (Sealed)
    • newc - New (Complete)
    • newi - New (Incomplete)
    • usedc - Used (Complete)
    • usedi - Used (Incomplete)
    • usedn - Used (Like New)
    • usedg - Used (Good)
    • useda - Used (Acceptable)
    • other - Other

Delete Lot

POST https://api.brickowl.com/v1/collection/delete_lot

Deletes a collection lot

Arguments
  • lot_id - Lot ID

Create Lot

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

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

Store Coupon

The coupon API allows viewing and creating coupons in a store.

List

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

Get a list of the store coupons. Limited to 100. Coupons can either have a coupon code, or a recipient_uid. Coupons can be enabled or disabled. Once a coupon redeem_count has met the redeem_limit, it can no longer be redeemed by a customer.

Arguments
  • offset (Optional) - Range offset start. Default 0. Limit 10,000,000.

Create

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

Create a new user specific coupon. If the recipient has notifications enabled, they will receive an email about the coupon. The coupon can only be redeemed a single time by the recipient. There is a limit on how many coupons a store can create per day.

Arguments
  • uid - The UID of the user to receive the coupon
  • free_shipping - Whether the coupon should include free shipping
    • 0 - no free shipping
    • 1 - free shipping
  • note - A description note to include for the customer
  • cart_discount_percent - A percentage discount amount. >0. <=100.
  • max_discount (Optional) - Optional maximum discount limit. This is in the stores local currency.

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
    • Part
    • Set
    • Minifigure
    • Gear
    • Sticker
    • Minibuild
    • Instructions
    • Packaging
  • active_only (Optional) - Include only items that are for sale and have a quantity > 0. 0 or 1. Default: 1
    • 0 - all
    • 1 - active lots only
  • 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 lot. You must pass only one identifier, and one or more update fields. Please note, if there are multiple lots with the same external_id, only 1 will be updated. external_id is not a unique 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
    • 0 - not for sale
    • 1 - for sale
  • price (Optional) - The price of the item. It must be a positive number, it will be rounded to 3 digits of precision
  • sale_percent (Optional) - The sale percentage of the item. It must be a whole number between -95 and 95
  • 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
  • lot_weight (Optional) - A custom lot weight, set in grams. 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) - Condition ID
    • new - New
    • news - New (Sealed)
    • newc - New (Complete)
    • newi - New (Incomplete)
    • usedc - Used (Complete)
    • usedi - Used (Incomplete)
    • usedn - Used (Like New)
    • usedg - Used (Good)
    • useda - Used (Acceptable)
    • other - Other
  • 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. Please note, if there are multiple lots with the same external_id, only 1 will be updated. This will remove the lot from customer carts and quotes. Stores must not delete large amounts of inventory on a regular basis.

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/Minibuild, 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 - Condition ID
    • new - New
    • news - New (Sealed)
    • newc - New (Complete)
    • newi - New (Incomplete)
    • usedc - Used (Complete)
    • usedi - Used (Incomplete)
    • usedn - Used (Like New)
    • usedg - Used (Good)
    • useda - Used (Acceptable)
    • other - Other
  • external_id (Optional) - An optional external ID for reference. This field is not unique.

Invoice

The invoices API is to retieve information about invoices paid by a store

Transactions

GET https://api.brickowl.com/v1/invoice/transactions

Retrieve a list of the invoice transactions

Arguments
  • invoice_id - The invoice ID
  • id_type - Type of invoice ID
    • public_invoice_id
    • stripe_charge_id

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 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 created with a timestamp greater than or equal to the one provided.
  • update_time (Optional) - Unix Timestamp to limit the orders returned to those updated with a timestamp greater than or equal to the one provided.
  • limit (Optional) - Range limit, limits the amount of results returned. Default 500. Limit 5,000.
  • offset (Optional) - Range offset start. Default 0. Limit 10,000,000.
  • list_type (Optional) - Order list type
    • store - Store orders (default)
    • customer - Orders you have placed
  • sort_by (Optional) - Sorting
    • created - Sort by order creation time (default)
    • updated - Sort by order update time

View

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

Retrieve full order details

Arguments
  • order_id - The order ID

Items

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

Retrieve order items

Arguments
  • order_id - The order ID

Tracking

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

Attach a shipping tracking information to the order

Arguments
  • order_id - The order ID
  • tracking_id - Tracking ID / URL

Note

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

Edit the seller note on an order

Arguments
  • order_id - The order ID
  • note - Seller note

Tax Schemes

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

Get a list of possible tax schemes that can be applied to orders

Notify (Deprecated)

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. To remove the notification, submit an empty string for the ip parameter.

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 order ID
  • comment (Optional) - The feedback comment. Maximum of 120 characters long
  • rating - The feedback rating
    • 1 - Positive
    • 0 - Neutral
    • -1 - Negative

Set Status

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

Change the status of the order

Arguments
  • order_id - The order ID
  • status_id - Order Status ID
    • 1 - Payment Submitted
    • 2 - Payment Received
    • 3 - Processing
    • 4 - Processed
    • 5 - Shipped
    • 6 - Received
    • 7 - On Hold

Token (Deprecated)

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

User

This is for accessing information about the user associated with the API key.

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

Addresses

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

Retrieve the addresses associated with the user account

Webhook

Instead of frequently polling the order/list endpoint, you can register a webhook. Your chosen path will receive a POST request containing a JSON payload. The JSON will include information about the event.

Currently, the only events are order related. The payload will contain event name, store id, order id. This service is not 100% guaranteed, so you may also need to poll infrequently.

The webhook registration will expire after 7 days. We recommend that you register your webhook once per day to renew it. The webhook path is registered against the user account that the API key belongs to. You can register the same webhook path against many different users.

Register

POST https://api.brickowl.com/v1/webhook/register

Register a new webhook for a specific URL path

Arguments
  • webhook_path - URL path to receive webhook events

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 Lot

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) - Condition ID
    • new - New
    • news - New (Sealed)
    • newc - New (Complete)
    • newi - New (Incomplete)
    • usedc - Used (Complete)
    • usedi - Used (Incomplete)
    • usedn - Used (Like New)
    • usedg - Used (Good)
    • useda - Used (Acceptable)
    • other - Other

Delete Lot

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

Deletes a wishlist lot

Arguments
  • wishlist_id - The wishlists unique ID
  • lot_id - Wishlist lot ID

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
  • public (Optional) - Whether to make the wishlist public
    • 0 - private
    • 1 - public

Update List

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

Update a wishlist

Arguments
  • wishlist_id - The wishlists unique ID
  • name - A unique name for the wishlist

Delete List

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

Delete a wishlist

Arguments
  • wishlist_id - The wishlists unique ID

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