@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Billbee API
@base https://app.billbee.io
@version V1
@auth basic | ApiKey X-Billbee-Api-Key in header
@endpoints 87
@hint download_for_search
@toc api(87)

@endpoint GET /api/v1/apiusage
@desc Get summarised api usage statistics
@optional {request.date: any # Only year and month of this is relevant}
@returns(200) OK

@endpoint GET /api/v1/apiusage/detail
@desc Get detailed api usage statistics
@optional {request.date: any # Only year and month of this is relevant}
@returns(200) OK

@endpoint GET /api/v1/cloudstorages
@desc Gets a list of all connected cloud storage devices
@returns(200) OK

@endpoint GET /api/v1/customer-addresses
@desc Get a list of all customer addresses
@optional {page: any # The current page to request starting with 1 (default is 1), pageSize: any # The page size for the result list. Values between 1 and 250 are allowed. (default is 50)}
@returns(200) OK

@endpoint POST /api/v1/customer-addresses
@desc Creates a new customer address
@required {model: map}
@returns(200) OK

@endpoint GET /api/v1/customer-addresses/{id}
@desc Queries a single customer address by id
@required {id: any # The id of the address to query}
@returns(200) OK

@endpoint PUT /api/v1/customer-addresses/{id}
@desc Updates a customer address by id
@required {model: map, id: any # The id of the address}
@returns(200) OK

@endpoint GET /api/v1/customers
@desc Get a list of all customers
@optional {page: any # The current page to request starting with 1, pageSize: any # The pagesize for the result list. Values between 1 and 250 are allowed}
@returns(200) OK

@endpoint POST /api/v1/customers
@desc Creates a new customer
@required {model: map}
@returns(200) OK

@endpoint GET /api/v1/customers/{id}
@desc Queries a single customer by id
@required {id: any # The id of the customer to query}
@returns(200) OK

@endpoint PUT /api/v1/customers/{id}
@desc Updates a customer by id
@required {model: map, id: any # The id of the customer}
@returns(200) OK

@endpoint GET /api/v1/customers/{id}/orders
@desc Queries a list of orders from a customer
@required {id: any # The id of the customer}
@optional {page: any # The current page to request starting with 1, pageSize: any # The pagesize for the result list. Values between 1 and 250 are allowed}
@returns(200) OK

@endpoint GET /api/v1/customers/{id}/addresses
@desc Queries a list of addresses from a customer
@required {id: any # The id of the customer}
@optional {page: any # The current page to request starting with 1, pageSize: any # The pagesize for the result list. Values between 1 and 250 are allowed}
@returns(200) OK

@endpoint POST /api/v1/customers/{id}/addresses
@desc Adds a new address to a customer
@required {id: any # CustomerId to attach the new address to., model: map # Model containing the address, that should be attached.}
@returns(200) OK

@endpoint GET /api/v1/customers/addresses/{id}
@desc Queries a single address from a customer
@required {id: any # The id of the address}
@returns(200) OK

@endpoint PUT /api/v1/customers/addresses/{id}
@desc Updates all fields of an address
@required {model: map # The updated address. Please query an address via (todo) to see all fields. Note that Id and CustomerId cannot be changed., id: any # The id of the address}
@returns(200) OK

@endpoint PATCH /api/v1/customers/addresses/{id}
@desc Updates one or more fields of an address
@required {id: any # The id of the address, model: map # The address fields to be changed. Please query an address via (todo) to see all fields. Note that Id and CustomerId cannot be changed.}
@returns(200) OK

@endpoint GET /api/v1/enums/paymenttypes
@desc Returns a list with all defined paymenttypes
@returns(200) OK

@endpoint GET /api/v1/enums/shippingcarriers
@desc Returns a list with all defined shippingcarriers
@returns(200) OK

@endpoint GET /api/v1/enums/accountsyncstate
@desc Returns a list with all defined account sync states
@returns(200) OK

@endpoint GET /api/v1/enums/shopaccounttype
@desc Returns a list with all defined account types
@returns(200) OK

@endpoint GET /api/v1/enums/shipmenttypes
@desc Returns a list with all defined shipmenttypes
@returns(200) OK

@endpoint GET /api/v1/enums/orderstates
@desc Returns a list with all defined orderstates
@returns(200) OK

@endpoint GET /api/v1/events
@desc Get a list of all events optionally filtered by date. This request is extra throttled to 2 calls per page per hour.
@optional {minDate: any # Specifies the oldest date to include in the response, maxDate: any # Specifies the newest date to include in the response, page: any # Specifies the page to request, pageSize: any # Specifies the pagesize. Defaults to 50, max value is 250, typeId: any # Filter for specific event types, orderId: any # Filter for specific order id}
@returns(200) OK

@endpoint POST /api/v1/orders/createmultiple
@required {models: [map]}
@returns(200) OK

@endpoint GET /api/v1/orders
@desc Get a list of all orders optionally filtered by date
@optional {minOrderDate: any # Specifies the oldest order date to include in the response, maxOrderDate: any # Specifies the newest order date to include in the response, page: any # Specifies the page to request, pageSize: any # Specifies the pagesize. Defaults to 50, max value is 250, shopId: any # Specifies a list of shop ids for which invoices should be included, orderStateId: any # Specifies a list of state ids to include in the response, tag: any # Specifies a list of tags the order must have attached to be included in the response, minimumBillBeeOrderId: any # If given, all delivered orders have an Id greater than or equal to the given minimumOrderId, modifiedAtMin: any # If given, the last modification has to be newer than the given date, modifiedAtMax: any # If given, the last modification has to be older or equal than the given date., articleTitleSource: any # The source field for the article title. 0 = Order Position (default), 1 = Article Title, 2 = Article Invoice Text, excludeTags: any # If true the list of tags passed to the call are used to filter orders to not include these tags}
@returns(200) OK

@endpoint POST /api/v1/orders
@required {orderData: map}
@optional {shopId: any}
@returns(200) OK

@endpoint PUT /api/v1/orders/{id}/tags
@desc Sets the tags attached to an order
@required {tagData: map # Tags to attach, id: any # The internal id of the order}
@returns(200) OK

@endpoint POST /api/v1/orders/{id}/tags
@desc Attach one or more tags to an order
@required {tagData: map # Tags to attach, id: any # The internal id of the order}
@returns(200) OK

@endpoint POST /api/v1/orders/tags
@desc Add one or more tags to multiple orders
@required {model: map # Contains lists of orderids and tags}
@returns(200) OK

@endpoint GET /api/v1/orders/{id}
@desc Get a single order by its internal billbee id. This request is throttled to 6 calls per order in one minute
@required {id: any # The internal billbee id of the order}
@optional {articleTitleSource: any # The source field for the article title. 0 = Order Position (default), 1 = Article Title, 2 = Article Invoice Text}
@returns(200) OK

@endpoint PATCH /api/v1/orders/{id}
@desc Updates one or more fields of an order
@required {id: any, model: map}
@returns(200) OK

@endpoint GET /api/v1/orders/findbyextref/{extRef}
@desc Get a single order by its external order number
@required {extRef: any # The extern order number of the order}
@returns(200) OK

@endpoint PUT /api/v1/orders/{id}/orderstate
@desc Changes the main state of a single order
@required {id: any # The internal id of the order, model: map # The data used to change the state}
@returns(200) OK

@endpoint POST /api/v1/orders/{id}/shipment
@desc Add a shipment to a given order
@required {id: any # The internal billbee id of the order, model: map # The shipment data to create the shipment}
@returns(200) OK

@endpoint GET /api/v1/orders/invoices
@desc Get a list of all invoices optionally filtered by date. This request ist throttled to 1 per 1 minute for same page and minInvoiceDate
@optional {minInvoiceDate: any # Specifies the oldest invoice date to include, maxInvoiceDate: any # Specifies the newest invoice date to include, page: any # Specifies the page to request, pageSize: any # Specifies the pagesize. Defaults to 50, max value is 250, shopId: any # Specifies a list of shop ids for which invoices should be included, orderStateId: any # Specifies a list of state ids to include in the response, tag: any, minPayDate: any, maxPayDate: any, includePositions: any, excludeTags: any # If true the list of tags passed to the call are used to filter orders to not include these tags}
@returns(200) OK

@endpoint GET /api/v1/orders/find/{id}/{partner}
@desc Find a single order by its external id (order number)
@required {id: any # The order id from the external system, partner: any # Optional the name of the shop/marketplace the order was imported from}
@returns(200) OK

@endpoint POST /api/v1/orders/CreateDeliveryNote/{id}
@desc Create an delivery note for an existing order. This request is extra throttled by order and api key to a maximum of 1 per 5 minutes.
@required {id: any # The internal billbee id of the order}
@optional {includePdf: any # If true, the PDF is included in the response as base64 encoded string, sendToCloudId: any # Optionally specify the id of a billbee connected cloud device to send the pdf to}
@returns(200) OK

@endpoint POST /api/v1/orders/CreateInvoice/{id}
@desc Create an invoice for an existing order. This request is extra throttled by order and api key to a maximum of 1 per 5 minutes.
@required {id: any # The internal billbee id of the order}
@optional {includeInvoicePdf: any # If true, the PDF is included in the response as base64 encoded string, templateId: any # You can pass the id of an invoice template to overwrite the assigned template for invoice creation, sendToCloudId: any # You can pass the id of a connected cloud printer/storage to send the invoice to it}
@returns(200) OK

@endpoint GET /api/v1/orders/PatchableFields
@desc Returns a list of fields which can be updated with the orders/{id} patch call
@returns(200) OK

@endpoint POST /api/v1/orders/{id}/send-message
@desc Sends a message to the buyer
@required {id: any # The id of the order, model: map # The message model}
@returns(200) OK

@endpoint POST /api/v1/orders/{id}/trigger-event
@desc Triggers a rule event
@required {id: any # The id of the order, model: map}
@returns(200) OK

@endpoint POST /api/v1/orders/{id}/parse-placeholders
@desc Parses a text and replaces all placeholders
@required {id: any # The id of the order, container: map}
@returns(200) OK

@endpoint POST /api/v1/orders/{id}/message
@desc Adds a message to the order
@required {id: any # The id of the order, orderMessage: map}
@returns(200) OK

@endpoint GET /api/v1/layouts
@returns(200) OK

@endpoint POST /api/v1/search
@desc Search for products, customers and orders.
@required {model: map}
@returns(200) OK

@endpoint GET /api/v1/products
@desc Get a list of all products
@optional {page: any # The current page to request starting with 1, pageSize: any # The pagesize for the result list. Values between 1 and 250 are allowed, minCreatedAt: any # Optional the oldest create date of the articles to be returned, minimumBillBeeArticleId: any, maximumBillBeeArticleId: any}
@returns(200) OK

@endpoint POST /api/v1/products
@desc Creates a new product
@required {model: map}
@returns(200) OK

@endpoint GET /api/v1/products/{id}
@desc Queries a single article by id or by sku
@required {id: any # The id or the sku of the article to query}
@optional {lookupBy: any # Either the value id, ean or the value sku to specify the meaning of the id parameter.}
@returns(200) OK

@endpoint DELETE /api/v1/products/{id}
@desc Deletes a product
@required {id: any # The id of the Product}
@returns(200) OK

@endpoint PATCH /api/v1/products/{id}
@desc Updates one or more fields of a product
@required {id: any # The id of the Product, model: map}
@returns(200) OK

@endpoint GET /api/v1/products/stocks
@desc Query all defined stock locations
@returns(200) OK

@endpoint GET /api/v1/products/PatchableFields
@desc Returns a list of fields which can be updated with the patch call
@returns(200) OK

@endpoint GET /api/v1/products/category
@desc GEts a list of all defined categories
@returns(200) OK

@endpoint POST /api/v1/products/updatestock
@desc Update the stock qty of an article
@required {model: map}
@returns(200) OK

@endpoint POST /api/v1/products/stockmultiple
@desc Retrieve the stock qty for multiple articles at once
@required {request: map}
@optional {modifiedSince: any, page: any, pageSize: any}
@returns(200) OK

@endpoint POST /api/v1/products/updatestockmultiple
@desc Update the stock qty for multiple articles at once
@required {models: [map]}
@returns(200) OK

@endpoint GET /api/v1/products/reservedamount
@desc Queries the reserved amount for a single article by id or by sku
@required {id: any # The id or the sku of the article to query}
@optional {lookupBy: any # Either the value id or the value sku to specify the meaning of the id parameter, stockId: any # Optional the stock id if the multi stock feature is enabled}
@returns(200) OK

@endpoint POST /api/v1/products/updatestockcode
@desc Update the stock code of an article
@required {model: map}
@returns(200) OK

@endpoint GET /api/v1/products/custom-fields
@desc Queries a list of all custom fields
@optional {page: any, pageSize: any}
@returns(200) OK

@endpoint GET /api/v1/products/custom-fields/{id}
@desc Queries a single custom field
@required {id: any # The id of the custom field to query}
@returns(200) OK

@endpoint GET /api/v1/products/{productId}/images
@desc Returns a list of all images of the product
@required {productId: any # The Id of the product}
@returns(200) OK

@endpoint PUT /api/v1/products/{productId}/images
@desc Add multiple images to a product or replace the product images by the given images
@required {productId: any # The id of the product, models: [map] # An array of ArticleApiImageModel}
@optional {replace: any # If you pass true, the images will be replaced by the passed images. Otherwise the passed images will be appended to the product.}
@returns(200) OK

@endpoint GET /api/v1/products/{productId}/images/{imageId}
@desc Returns a single image by id
@required {productId: any # The Id of the product, imageId: any # The Id of the image}
@returns(200) OK

@endpoint PUT /api/v1/products/{productId}/images/{imageId}
@desc Add or update an existing image of a product
@required {productId: any # The product id, imageId: any # The image id. If you pass 0, the image will be added, model: map # The ArticleApiImageModel}
@returns(200) OK

@endpoint DELETE /api/v1/products/{productId}/images/{imageId}
@desc Deletes a single image from a product
@required {productId: any # The product id, imageId: any # The image id}
@returns(200) OK

@endpoint GET /api/v1/products/images/{imageId}
@desc Returns a single image by id
@required {imageId: any # The Id of the image}
@returns(200) OK

@endpoint DELETE /api/v1/products/images/{imageId}
@desc Deletes a single image by id
@required {imageId: any # The image id}
@returns(200) OK

@endpoint POST /api/v1/products/images/delete
@required {imageIds: [int(int64)]}
@returns(200) OK

@endpoint POST /api/v1/automaticprovision/createaccount
@desc Creates a new Billbee user account with the data passed
@required {model: map}
@returns(200) OK

@endpoint GET /api/v1/automaticprovision/termsinfo
@desc Returns infos about Billbee terms and conditions
@returns(200) OK

@endpoint POST /api/v1/shipment/shipmentmultiple
@desc Creates multiple shipments
@required {models: [map] # Data to specify shipment parameters}
@returns(200) OK

@endpoint POST /api/v1/shipment/shipment
@desc Creates a new shipment with the selected Shippingprovider
@required {model: map # Data to specify shipment parameters}
@returns(200) OK

@endpoint GET /api/v1/shipment/shippingproviders
@desc Query all defined shipping providers
@returns(200) OK

@endpoint POST /api/v1/shipment/shipwithlabel
@desc Creates a shipment for an order in billbee
@required {shipmentInformation: map # Details on the order and the shipping methods, that should be used.}
@returns(200) OK

@endpoint POST /api/v1/shipment/shipwithlabelmultiple
@desc Creates shipments for a list of orders in billbee
@required {models: [map]}
@returns(200) OK

@endpoint GET /api/v1/shipment/shippingcarriers
@desc Queries the currently available shipping carriers.
@returns(200) OK

@endpoint GET /api/v1/shipment/ping
@returns(200) OK

@endpoint GET /api/v1/shipment/shipments
@desc Get a list of all shipments optionally filtered by date. All parameters are optional.
@optional {page: any # Specifies the page to request., pageSize: any # Specifies the pagesize. Defaults to 50, max value is 250, createdAtMin: any # Specifies the oldest shipment date to include in the response, createdAtMax: any # Specifies the newest shipment date to include in the response, orderId: any # Get shipments for this order only., minimumShipmentId: any # Get Shipments with a shipment greater or equal than this id. New shipments have a greater id than older shipments., shippingProviderId: any # Get Shippings for the specified shipping provider only.}
@returns(200) OK

@endpoint GET /api/v1/shopaccounts
@desc Queries a list of avaible shop accounts
@optional {page: any # The current page to request starting with 1, pageSize: any # The pagesize for the result list. Values between 1 and 250 are allowed}
@returns(200) OK

@endpoint GET /api/v1/webhooks
@desc Gets all registered WebHooks for a given user.
@returns(200) OK

@endpoint POST /api/v1/webhooks
@desc Registers a new WebHook for a given user.
@required {webHook: map # The webhook to create. Attach ?noecho to the uri to prevent echo test.}
@returns(200) OK

@endpoint DELETE /api/v1/webhooks
@desc Deletes all existing WebHook registrations.
@returns(200) OK

@endpoint GET /api/v1/webhooks/{id}
@desc Looks up a registered WebHook with the given {id} for a given user.
@required {id: any}
@returns(200) OK

@endpoint PUT /api/v1/webhooks/{id}
@desc Updates an existing WebHook registration.
@required {id: any # The WebHook ID., webHook: map # The new webhook to use.}
@returns(200) OK

@endpoint DELETE /api/v1/webhooks/{id}
@desc Deletes an existing WebHook registration.
@required {id: any # The WebHook ID.}
@returns(200) OK

@endpoint GET /api/v1/webhooks/filters
@desc Returns a list of all known filters you can use to register webhooks
@returns(200) OK

@end