Index by title

• Main
• API References
• Authorization
• CatalogMethod
• CatalogResource
• CategoryMethod
• CategoryResource
• ColorMethod
• ColorResource
• Error Handling
• FeedbackMethod
• FeedbackResource
• General Notes
• Getting Started
• OrderMethod
• OrderResource
• PushNotificationMethod
• PushNotificationResource
• UserInventoryMethod
• UserInventoryResource

BrickLink API¶

Getting Started¶

API References¶

Getting Started¶

Getting a Consumer Key¶

• The consumer key publicly identifies your API account and will never be changed.
• The consumer secret is your confidential API password and can be changed.

Obtain Access Tokens¶

• You can access the BrickLink resources only from the registered location.
• Since the access token has no expiration date, token secret should be stored securely. (If it is exposed, you should reissue it)

Register Notification URLs¶

The BrickLink API provides push notifications that let you watch for changes to resources. To receive notifications, register callback URLs that will be used to send information of resources that have changed.

After a successful URL registration, the system will send an http POST request on the callback URL whenever one of following event is raised. The body will be a list of push notification resources

• Order
  • You received a new order.
  • Buyer updates an order status.
  • Items of an order are updated (added or deleted).
• Message
  • You received a new message.
• Feedback
  • You received a new feedback or reply

Please note: It does not guarantee delivery of all events.

Calling BrickLink API methods¶

Once you've finished the tasks listed above, you're ready to start.

API References¶

Overview¶

• General Notes
• Authentication & Authorization
• Error Handling

Order¶

• Resource Representations
• Method
  • Get Orders : Lists the orders you received or placed.
  • Get Order: Gets details of a specific order.
  • Get Order Items: Retrieves a list of items for the specified order.
  • Get Order Messages: Retrieves a list of messages for the specified order.
  • Get Order Feedback: Retrieves a list of feedback for the specified order.
  • Update Order: Updates properties of a specific order.
  • Update Order Status: Updates the status of a specific order.

User Inventory¶

• Resource Representations
• Method
  • Get Inventories: Lists your inventories.
  • Get Inventory: Gets the information about a specific inventory.
  • Create Inventory: Creates a new inventory with an item.
  • Create Inventories: Creates multiple inventories in a single request.
  • Update Inventory: Updates the specified inventory.
  • Delete Inventory: Deletes the specified inventory.

Catalog Item¶

• Resource Representations
• Method
  • Get Item: Gets information of the specified item in BrickLink catalog.
  • Get Supersets: Gets a list of items that include the specified item.
  • Get Subsets(Part Out): Gets a list of items that are included in the specified item.
  • Get Price Guide: Gets the price statistics of the specified item in BrickLink catalog.

Feedback¶

• Resource Representations
• Method
  • Get Feedback List: Gets a list of feedback you received or posted.
  • Get Feedback: Gets a specified feedback.
  • Post Feedback: Posts a new feedback about the transaction.
  • Reply Feedback: Replies to the feedback you received.

Color¶

• Resource Representations
• Method
  • Get Color List: Lists all of the colors defined within BrickLink catalog.
  • Get Color: Gets information about a specific color.

Category¶

• Resource Representations
• Method
  • Get Category List: Lists all of the categories defined within BrickLink catalog.
  • Get Category: Gets information about a specific category.

Push Notification¶

• Resource Representations
• Method
  • Get Notifications: Lists all unread push notifications.

General Notes¶

API Base URL¶

https://api.bricklink.com/api/store/v1

SSL only¶

We require that all requests are done over SSL.

UTF-8 encoding¶

Every string passed to and from the Bricklink API needs to be UTF-8 encoded.

Date format¶

All timestamps in the API are strings in ISO 8601 format:

yyyy-MM-dd'T'HH:mm:ss.SSSZ 
2013-12-01T18:05:46.123Z

Rounding policy¶

For all financial calculations, BrickLink API uses values with 4 decimal places. Any values that has greater precision will be rounded up to the 4 places.

Request¶

• OAuth parameters should be included in every request.
• In the PUT or POST, you represent the resource object you wish to update as form of urlencoded JSON.
• Optional parameters (ex pagination info) should be provided as query string with urlencoded form.

Response¶

BrickLink API supports returning resource representations as JSON with the following structure:

{
    "code":"200",
    "message":"OK",
    "description":"OK",
    "data": {

    }
}

Authentication & Authorization¶

Make the request with OAuth protocol parameters¶

• The parameters are sent in either the HTTP Authorization header or query part of the URL with JSON format.
• All parameter names and values are escaped using the RFC3986 percent-encoding (%xx) mechanism.

Prameter Details¶

Example¶

The request for the orders you received is:

https://api.bricklink.com/api/store/v1/orders?direction=in

Authorization: OAuth realm="",
oauth_consumer_key="7CCDCEF257CF43D89A74A7E39BEAA1E1",
oauth_token="AC40C8C32A1748E0AE1EFA13CCCFAC3A",
oauth_signature_method="HMAC-SHA1",
oauth_signature="0IeNpR5N0kTEBURcuUMGTDPKU1c%3D",
oauth_timestamp="1191242096",
oauth_nonce="kllo9940pd9333jh",
oauth_version="1.0" 

And if using query parameters:

https://api.bricklink.com/api/store/v1/orders?direction=in&Authorization={"oauth_signature"%3A"0IeNpR5N0kTEBURcuUMGTDPKU1c%3D"%2C"oauth_nonce"%3A"kllo9940pd9333jh"%2C"oauth_version"%3A"1.0"%2C"oauth_consumer_key"%3A"7CCDCEF257CF43D89A74A7E39BEAA1E1"%2C"oauth_signature_method"%3A"HMAC-SHA1"%2C"oauth_token"%3A"AC40C8C32A1748E0AE1EFA13CCCFAC3A"%2C"oauth_timestamp"%3A"1191242096"}

Error Handling¶

Result Code¶

Errors are returned using standard HTTP error code syntax. Any additional info is included in the body of the return call, JSON-formatted.

• A value of 2xx indicates that no errors occurred and the transaction was successful.
• A value other than 2xx indicates a decline or an error.

Order¶

Order: Resource Representations¶

Order¶

Resource¶

Example¶

{
    "order_id":3986441,
    "date_ordered":"2013-12-17T07:00:15.087Z",
    "seller_name":"sklee",
    "store_name":"skleestore",
    "buyer_name":"covariance1",
    "buyer_email":"skleew@gmail.com",
    "require_insurance":true,
    "status":"PENDING",
    "is_invoiced":false,
    "total_count":10,
    "unique_count":1,
    "payment": {
        "method":"PayPal.com",
        "currency_code":"USD",
        "date_paid":"2013-12-17T09:20:02.000Z",
        "status":"Sent" 
    },
    "shipping": {
        "address": {
            "name": {
                "full":"Seulki Lee" 
            },
            "full":"Geumho-dong 2-ga, Seongdong-gu",
            "country_code":"KR" 
        },
        "date_shipped":"2013-12-17T03:00:15.087Z" 
    },
    "cost": {
        "currency_code":"USD",
        "subtotal":"139.9900",
        "grand_total":"157.8000",
        "disp_currency_code":"USD",
        "disp_subtotal":"139.9900",
        "disp_grand_total":"157.8000",
        "etc1":"0.0000",
        "etc2":"0.0000",
        "insurance":"3.0500",
        "shipping":"14.7600",
        "credit":"0.0000",
        "coupon":"0.0000" 
    }
}

Order Method¶

Get Orders¶

This method retrieves a list of orders you received or placed.

Request¶

* Parameters¶

* Request body¶

Do not supply a request body with this method.
 

Response¶

If successful, this method returns a list of the the summary of an order resource as "data" in the response body.
Each entry in the list includes followings:
- order_id
- date_ordered
- seller_name
- store_name
- buyer_name
- total_count
- unique_count
- status
- payment.payment_method
- payment.status
- payment.date_paid
- payment.currency_code
- cost.subtotal
- cost.grandtotal
- cost.currency_code
To retrieve additional properties, see the Get Order.

Example¶

• GET /orders
  • Retrieves a list of received orders
• GET /orders?direction=out
  • Retrieves a list of placed orders
• GET /orders?status=pending,completed
  • Retrieves PENDING or COMPLETED received orders
• GET /orders?status=-purged
  • Retrieves a list of received orders not in PURGED status
• GET /orders?filed=true&status=completed
  • Retrieves a list of received and filed orders in COMPETED status

Get Order¶

This method retrieves the details of a specific order.

Request¶

* Parameters¶

* Request body¶

Do not supply a request body with this method.
 

Response¶

If successful, this method returns an order resource as "data" in the response body.

Example¶

• GET /orders/1234
  • Retrieves order #1234

Get Order Items¶

This method retrieves a list of items for the specified order.

Request¶

* Parameters¶

* Request body¶

Do not supply a request body with this method.
 

Response¶

If successful, this method returns a list of items batch list as "data" in the response body. An inner list indicates that items included in one batch of the order (order item batch).

Example¶

• GET /orders/1234/items
  • Retrieves a list of items for order #1234

Get Order Messages¶

This method retrieves a list of messages for the specified order.

Request¶

* Parameters¶

* Request body¶

Do not supply a request body with this method.
 

Response¶

If successful, this method returns a list of order message resource as "data" in the response body.

Example¶

• GET /orders/1234/messages
  • Retrieves a list of messages for order #1234

Get Order Feedback¶

This method retrieves a list of feedback for the specified order.

Request¶

* Parameters¶

* Request body¶

Do not supply a request body with this method.
 

Response¶

If successful, this method returns a list of feedback resource as "data" in the response body.

Example¶

• GET /orders/1234/feedback
  • Retrieves a list of feedback for order #1234

Update Order¶

This method updates properties of a specific order.

Request¶

* Parameters¶

* Request body¶

• cost.credit
• cost.insurance
• cost.etc1
• cost.etc2
• cost.shipping
• shipping.date_shipped
• shipping.tracking_no
• shipping.tracking_link

Any attempt to update other fields that are not listed above would be ignored.

{
    "shipping": {
        "date_shipped": "Timestamp",
        "tracking_no": "String",
        "tracking_link": "String",
    },
    "cost": {
        "shipping": "String",
        "insurance": "String",
        "credit": "String",
        "etc1": "String",
        "etc2": "String" 
    }
}

Response¶

If successful, this method returns an order resource as data in the response body.

Example¶

• PUT /orders/1234
  • Updates order #1234

Update Order Status¶

This method updates the status of a specific order.

Request¶

* Parameters¶

* Request body¶

In the request body, supply a patch object with the following structure:

{
    "field" : "status",
    "value" : "PENDING" 
}

Response¶

If successful, this method returns an empty "data".

Example¶

• PUT /orders/1234/status
  • Updates status of order #1234

User Inventory¶

User Inventory: Resource Representations¶

Inventory¶

Resource¶

Example¶

{
    "inventory_id":50592684,
    "item": {
        "no":"bel004",
        "name":"Belville Accessories - Complete Sprue - Perfume Bottles (same as 6932)",
        "type":"PART",
        "categoryID":48
    },
    "color_id":5,
    "quantity":12,
    "new_or_used":"U",
    "unit_price":"1.2000",
    "bind_id":0,
    "description":"",
    "remarks":"",
    "bulk":1,
    "is_retain":false,
    "is_stock_room":false,
    "date_created":"2013-12-18T05:00:00.000Z" 
}

User Inventory Method¶

Get Inventories¶

This method retrieves a list of inventories you have.

Request¶

* Parameters¶

* Request body¶

Do not supply a request body with this method.
 

Response¶

If successful, this method returns a list of the the summary of an inventory resource as "data" in the response body.

Example¶

• GET /inventories
  • Retrieves a list of inventories
• GET /inventories?item_type=part,set
  • Retrieves inventories of PART or SET
• GET /inventories?category_id=123
  • Retrieves inventories of category ID #123
• GET /inventories?status=-R
  • Retrieves a list of inventories not in RESERVED status
• GET /inventories?status=B
  • Retrieves a list of inventories in stockroom B
• GET /inventories?color_id=1&item_type=part
  • Retrieves inventories of color ID #123 and PART

Get Inventory¶

This method retrieves information about a specific inventory.

Request¶

* Parameters¶

* Request body¶

Do not supply a request body with this method.
 

Response¶

If successful, this method returns an inventory resource as "data" in the response body.

Example¶

• GET /inventories/1234
  • Retrieves a specific inventories with inventory ID #1234

Create Inventory¶

Creates a new inventory with an item.

Request¶

* Parameters¶

Do not supply a request parameter with this method.

* Request body¶

• item.no
• item.type
• color_id
• quantity
• unit_price
• new_or_used
• completeness (only when item.type is "set")
• description
• remarks
• bulk
• is_retain
• is_stock_room
• stock_room_id (only when is_sock_room is "true")
   

Response¶

If successful, this method returns an inventory resource as "data" in the response body.

Example¶

• POST /inventories
  • Creates a new inventory

Create Inventories¶

Creates multiple inventories in a single request.

Request¶

* Parameters¶

Do not supply a request parameter with this method.

* Request body¶

• item.no
• item.type
• color_id
• quantity
• unit_price
• new_or_used
• completeness (only when item.type is "set")
• description
• remarks
• bulk
• is_retain
• is_stock_room
• stock_room_id (only when is_sock_room is "true")
   

Response¶

If successful, this method returns an empty "data".

• POST /inventories
  • Creates new inventories

Update Inventory¶

This method updates properties of the specified inventory.

Request¶

* Parameters¶

* Request body¶

• color_id
• quantity (has to have a + (plus) or - (minus) sign in front of it. You can only add or subtract quantity, not set it to a new value because quantity can change when buyers submit orders in your store. )
• unit_price
• new_or_used
• completeness (only when item.type is "set")
• description
• remarks
• bulk
• is_retain
• is_stock_room
• stock_room_id (only when is_sock_room is "true")
   

Response¶

If successful, this method returns an inventory resource as "data" in the response body.

Example¶

• PUT /inventories/1234
  • Updates inventory #1234

Delete Inventory¶

This method deletes the specified inventory.

Request¶

* Parameters¶

* Request body¶

Do not supply a request body with this method.
 

Response¶

If successful, this method returns an empty "data".

Example¶

• DELETE /inventories/1234
  • Deletes inventory #1234

Catalog¶

Catalog: Resource Representations¶

Item¶

Resource¶

Example¶

{
    "no":"3305-1",
    "name":"World Team Player",
    "type":"SET",
    "image_url":"http://www.bricklink.com/SL/3305-1.jpg",
    "thumbnail_url":"http://www.bricklink.com/S/3305-1.gif",
    "weight":"3.92",
    "dim_x":"0.00",
    "dim_y":"0.00",
    "dim_z":"0.00",
    "year_released":1998,
    "is_obsolete":false,
    "categoryID":473
}

Superset Entry¶

Resource¶

Example¶

{
    "color_id":6,
    "entries": [ 
        {
            "item": {
                "no":"555-1",
                "name":"Hospital",
                "type":"SET",
                "categoryID":277
            },
            "quantity":1,
            "appears_as":"R" 
        },
        {
            "item": {
                "no":"363-1",
                "name":"Hospital with Figures",
                "type":"SET",
                "categoryID":277
            },
            "quantity":1,
            "appears_as":"R" 
        }
    ]
}

Subset Entry¶

Resource¶

Example¶

{
    "match_no":1,
    "entries": [
        { 
            "item": {
                "no":"3001old",
                "name":"Brick 2 x 4 without Cross Supports",
                "type":"PART",
                "categoryID":5
            },
            "color_id":5,
            "quantity":1,
            "extra_quantity":0,
            "is_alternate":false
        },
        {
            "item": {
                "no":"3001old",
                "name":"Brick 2 x 4 without Cross Supports",
                "type":"PART",
                "categoryID":5
            },
            "color_id":7,
            "quantity":1,
            "extra_quantity":0,
            "is_alternate":true
        }
    ]
}

Price Guide¶

Resource¶

Example¶

{
    "item": {
        "no":"7644-1",
        "type":"SET" 
    },
    "new_or_used":"N",
    "currency_code":"USD",
    "min_price":"96.0440",
    "max_price":"695.9884",
    "avg_price":"162.3401",
    "qty_avg_price":"155.3686",
    "unit_quantity":298,
    "total_quantity":359,
    "price_detail": [

    ]
}

Price Detail¶

Resource¶

• Current Items for Sale:

• Last 6 Months Sales:

Example¶

{
    "qunatity":2,
    "unit_price":"96.0440",
    "shipping_available":true
}

{
    "qunatity":1,
    "unit_price":"98.2618",
    "seller_country_code":"CZ",
    "buyer_country_code":"HK",
    "date_ordered":"2013-12-30T14:59:01.850Z" 
}

Catalog Method¶

Get Item¶

This method returns information about the specified item in BrickLink catalog.

Request¶

* Parameters¶

* Request body¶

Do not supply a request body with this method.
 

Response¶

If successful, this method returns a catalog item as "data" in the response body.

Example¶

• GET /items/part/1234
  • Retrieves PART #1234
• GET /items/set/1-1
  • Retrieves SET #1-1

Get Supersets¶

This method returns a list of items that include the specified item.

Request¶

* Parameters¶

* Request body¶

Do not supply a request body with this method.
 

Response¶

If successful, this method returns a list of superset entries as "data" in the response body.

Example¶

• GET /items/part/3001old
  • Retrieves a list of items that include the PART #3001old
• GET /items/part/3001old?color_id=1
  • Retrieves a list of items that include the PART #3001old with color #1

Get Subsets¶

This method returns a list of items that are included in the specified item.

Request¶

* Parameters¶

* Request body¶

Do not supply a request body with this method.
 

Response¶

If successful, this method returns a nested list of subset entries as "data" in the response body. Note that the result is grouped by matching. An inner list indicates one matching group of items.

Example¶

• GET /items/set/7644-1
  • Retrieves a list of items that are included in the SET #7644-1
• GET /items/set/7644-1?instruction=true&break_minifigs=false
  • Retrieves a list of items that are included in the SET #7644-1 including the instruction and breaking down minifigs as parts

Get Price Guide¶

This method returns the price statistics of the specified item in BrickLink catalog. Note that returned price does not include VAT

Request¶

* Parameters¶

* Request body¶

Do not supply a request body with this method.
 

Response¶

If successful, this method returns a price guide resource as "data" in the response body.

Example¶

• GET /items/part/3001old
  • Retrieves price statistics(currently for sale) of PART #3001old in new condition
• GET /items/part/3001old?new_or_used=U
  • Retrieves price statistics(currently for sale) of PART #3001old in used condition
• GET /items/part/3001old?guide_type=sold
  • Retrieves price statistics(last 6 months sales) of PART #3001old in new condition
• GET /items/part/3001old?guide_type=sold&country_code=US
  • Retrieves price statistics(last 6 months sales) of PART #3001old in new condition that are ordered from stores which are located in US.
• GET /items/part/3001old?region=asia
  • Retrieves price statistics(currently for sale) of PART #3001old in new condition that are currently for sale in stores which are located in Asia.
• GET /items/part/3001old?currency_code=USD
  • Retrieves price statistics(currently for sale in USD) of PART #3001old in new condition

Feedback¶

Feedback: Resource Representations¶

Feedback¶

Resource¶

Example¶

{
    "feedback_id":6628516,
    "order_id":3986441,
    "from":"covariance1",
    "to":"sklee",
    "date_rated":"2013-12-17T07:25:00.000Z",
    "rating":0,
    "rating_of_bs":"S",
    "comment":"Excellent! Thank you!" 
}

Feedback Method¶

Get Feedback List¶

This method gets a list of feedback you received or posted.

Request¶

* Parameters¶

* Request body¶

Do not supply a request body with this method.
 

Response¶

If successful, this method returns a list of feedback resource as "data" in the response body.

Example¶

• GET /feedback
  • Retrieves a list of feedback you received
• GET /feedback?direction=out
  • Retrieves a list of feedback you posted

Get Feedback¶

This method gets a specified feedback.

Request¶

* Parameters¶

* Request body¶

Do not supply a request body with this method.
 

Response¶

If successful, this method returns feedback resource as "data" in the response body.

Example¶

• GET /feedback/1234
  • Retrieves a specific feedback with feedback ID #1234

Post Feedback¶

This method posts a new feedback about the transaction.

Request¶

* Parameters¶

Do not supply a request parameter with this method.

* Request body¶

• order_id
• rating
• comment
   

Response¶

If successful, this method returns feedback resource as "data" in the response body.

Example¶

• POST /feedback
  • Creates a new feedback

Reply Feedback¶

This method creates a reply to the specified feedback you received.

Request¶

* Parameters¶

* Request body¶

• reply
   

Response¶

If successful, this method returns an empty "data".

Example¶

• POST /feedback/1234/reply
  • Creates a new reply for feedback #1234

Color¶

Color: Resource Representations¶

Color¶

Resource¶

Example¶

{
    "color_id":10,
    "color_name":"Dark Gray",
    "color_code":"6b5a5a",
    "color_type":"Solid" 
}

Color Method¶

Get Color List¶

This method retrieves a list of the colors defined within BrickLink catalog.

Request¶

* Parameters¶

Do not supply a request parameter with this method.

* Request body¶

Do not supply a request body with this method.
 

Response¶

If successful, this method returns a list of color resource as "data" in the response body.

Example¶

• GET /colors
  • Retrieves a list of colors defined within BrickLink catalog

Get Color¶

This method retrieves information about a specific color.

Request¶

* Parameters¶

* Request body¶

Do not supply a request body with this method.
 

Response¶

If successful, this method returns color resource as "data" in the response body.

Example¶

• GET /colors/123
  • Retrieves color #123

Category¶

Category: Resource Representations¶

Category¶

Resource¶

Example¶

{
    "category_id":10,
    "category_name":"Container",
    "parent_id":0
}

Category Method¶

Get Category List¶

This method retrieves a list of the categories defined within BrickLink catalog.

Request¶

* Parameters¶

Do not supply a request parameter with this method.

* Request body¶

Do not supply a request body with this method.
 

Response¶

If successful, this method returns a list of category resource as "data" in the response body.

Example¶

• GET /categories
  • Retrieves a list of categories defined within BrickLink catalog

Get Category¶

This method retrieves information about a specific category.

Request¶

* Parameters¶

* Request body¶

Do not supply a request body with this method.
 

Response¶

If successful, this method returns category resource as "data" in the response body.

Example¶

• GET /categories/123
  • Retrieves category #123

Push Notification¶

Push Notification: Resource Representations¶

Notification¶

Resource¶

Example¶

{
    "event_type":"Order",
    "resource_id":3986441,
    "timestamp":"2013-12-17T08:20:02.177Z" 
}

Push Notification Method¶

Get Notifications¶

This method returns a list of unread push notifications. If you provided callback URLs to get notifications, you don't need to call this method.
A notification to be created when:

• Order
  • You received a new order.
  • Buyer updates an order status.
  • Items of an order are updated (added or deleted).
• Message
  • You received a new message.
• Feedback
  • You received a new feedback or reply

However, assure that it does not guarantee delivery of all events.

Request¶

* Parameters¶

Do not supply a request parameter with this method.

* Request body¶

Do not supply a request body with this method.
 

Response¶

If successful, this method returns a list of push notification resources as "data" in the response body.

Example¶

• GET /notifications
  • Retrieves a list of unread push notifications