{"openapi":"3.1.0","info":{"title":"BrickVillage Seller API","version":"1.0.0","description":"Sync listings, stock and orders between your own systems and BrickVillage. Access is on request via help@brickvillage.eu."},"servers":[{"url":"https://brickvillage.eu/api/v1"}],"security":[{"bearer":[]}],"paths":{"/listings":{"get":{"summary":"List own listings","parameters":[{"name":"status","in":"query","schema":{"enum":["active","sold","offline"]}},{"name":"external_ref","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Page of listings","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Listing"}},"next_cursor":{"type":["string","null"]}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"summary":"Create listing","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingInput"}}}},"responses":{"201":{"description":"Listing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Listing"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/listings/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"get":{"summary":"Get listing","responses":{"200":{"description":"Listing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Listing"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"patch":{"summary":"Partially update listing","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingInput"}}}},"responses":{"200":{"description":"Listing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Listing"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Take listing offline (not a hard delete)","responses":{"200":{"description":"Listing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Listing"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/listings/by-ref/{external_ref}":{"parameters":[{"name":"external_ref","in":"path","required":true,"schema":{"type":"string","maxLength":120}}],"get":{"summary":"Get listing by own reference","responses":{"200":{"description":"Listing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Listing"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"put":{"summary":"Upsert listing by own reference","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingInput"}}}},"responses":{"200":{"description":"Listing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Listing"}}}},"201":{"description":"Listing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Listing"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"patch":{"summary":"Partially update by reference","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingInput"}}}},"responses":{"200":{"description":"Listing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Listing"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Take offline by reference","responses":{"200":{"description":"Listing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Listing"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/listings/{id}/images":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"post":{"summary":"Add image (multipart field 'file' or JSON {url})","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}}}},"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"}},"required":["url"]}}}},"responses":{"201":{"description":"Listing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Listing"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/listings/{id}/images/{index}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"index","in":"path","required":true,"schema":{"type":"integer","minimum":0}}],"delete":{"summary":"Remove image","responses":{"200":{"description":"Listing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Listing"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/listings/{id}/images/order":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"put":{"summary":"Reorder images","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"array","items":{"type":"integer"}}}}}}},"responses":{"200":{"description":"Listing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Listing"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/orders":{"get":{"summary":"List own sales orders","parameters":[{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Only orders updated at or after"},{"name":"status","in":"query","schema":{"enum":["paid","shipped","delivered","refunded"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Page of orders","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"next_cursor":{"type":["string","null"]}}}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/orders/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get order","responses":{"200":{"description":"Order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"bv_live_… API key"}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"enum":["bad_request","unauthorized","forbidden","not_found","conflict","validation_failed","rate_limited","internal_error"]},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}}},"required":["code","message"]}}}}}}},"schemas":{"ListingInput":{"type":"object","additionalProperties":false,"properties":{"title":{"type":"string","minLength":3,"maxLength":120},"description":{"type":"string","maxLength":4000},"price_cents":{"type":"integer","minimum":50,"maximum":10000000},"quantity":{"type":"integer","minimum":0,"maximum":999},"condition":{"enum":["new","good","used_visible","incomplete","parts"]},"category":{"enum":["populair","onderdelen","setjes","minifigures","fantasie","films"]},"set_number":{"type":["string","null"],"maxLength":40},"piece_count":{"type":["integer","null"]},"year":{"type":["integer","null"]},"theme":{"enum":["halloween","dc","kerst","originals","marvel","fantasy","movies","overig",null]},"age_recommendation":{"enum":["1_5","4","6","9","13","18","overig",null]},"lego_category":{"enum":["city","classic","creator","duplo","friends","disney","technic","star_wars","architecture","marvel","overig",null]},"weight_grams":{"type":["integer","null"]},"color":{"type":["string","null"],"maxLength":40},"external_ref":{"type":["string","null"],"maxLength":120},"images":{"type":"array","maxItems":12,"items":{"type":"string","format":"uri"}}}},"Listing":{"type":"object","properties":{"id":{"type":"integer"},"slug":{"type":["string","null"]},"url":{"type":"string"},"status":{"enum":["active","sold","offline"]},"title":{"type":"string"},"description":{"type":"string"},"price_cents":{"type":"integer"},"quantity":{"type":"integer"},"condition":{"type":"string"},"category":{"type":["string","null"]},"images":{"type":"array","items":{"type":"string"}},"external_ref":{"type":["string","null"]},"source":{"enum":["web","api"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Order":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"enum":["paid","shipped","delivered","refunded"]},"currency":{"type":"string"},"amounts":{"type":"object"},"items":{"type":"array","items":{"type":"object","properties":{"listing_id":{"type":"integer"},"external_ref":{"type":["string","null"]},"title":{"type":"string"},"qty":{"type":"integer"},"price_cents":{"type":"integer"}}}},"shipping":{"type":"object"},"paid_at":{"type":["string","null"],"format":"date-time"}}}}}}