Farmbrite Inventory API

openapi: 3.2.0
info:
  title: Farmbrite API Developers Documentation Inventory API
  description: '# Overview


    Welcome to the Farmbrite API. You can find out more about Farmbrite at

    www.farmbrite.com


    If you need help, check out our help center at help.farmbrite.com or email us at dev@farmbrite.com. ## API Reference


    The Farmbrite API allows authorized users programatic access to their account data in order to facilitate the integration of this data with other systems and service. The API is organized around REST standards. The API uses resource-oriented URLs and returns JSON-encoded responses. It uses standard HTTP response codes, authentication, and verbs. > Base URL


    ```

    https://api.farmbrite.com/v1


    ```


    # Authentication


    Farmbrite offers 2 authentication options for accessing the API both utilizing Personal Access Tokens (PATs) for enabling access to the API. Access Tokens (API Keys) are associated with an individual user in your account and inherit that user''s role and permissions. You can find the Access Token on the user profile page under API Key. When building an integration we recommend setting up a separate API user for the integration and changing the API KEY on a regular basis. Remember to keep your Access Tokens secret; treat them just like passwords! They act on your behalf when interacting with the API, with the same permissions and access as the user has. _Don''t hardcode them into your programs_. Instead, choose to store them as environment variables. ### Bearer Token


    To make a request to the API include the Authorization Bearer header with your request and include your Access Token (API KEY) as the value. Access Token and API KEY are used interchangeably through out the documentation. > Example cURL request authenticating with Bearer Token authentication


    ```

    curl https://api.farmbrite.com/v1/tasks \

    -H "Authorization: Bearer ACCESS_TOKEN"


    ```


    ### API Key


    Alternatively to using the Bearer Token authorization method, you can provide an API KEY as a header with your request. Use the header `api_key` with a value of your Access Token (API KEY). > Example cURL request authenticating with API Key header authentication


    ```

    curl https://api.farmbrite.com/v1/tasks \

    -H "api_key: ACCESS_TOKEN"


    ```


    # Errors


    Sadly, sometimes requests to the API fail. Failures can occur for a wide range of reasons. In all cases, the API should return an HTTP Status Code indicating the nature of the failure. | Code | Meaning | Description |

    | --- | --- | --- |

    | 200 | Success | The request was successful. If applicable the data it will be available in the data field at the top level of the response body. |

    | 400 | Bad Request | Typically caused by a missing or malformed parameter. Check the documentation and your request and try again. |

    | 401 | Unauthorized | No access token or an invalid access token was provided with the request. The error can also occur if the user or account is invalid or does not have access to this resource. |

    | 403 | Forbidden | The authentication and request syntax was valid but the server is refusing to complete the request. This can happen if you access resources that the user or account does not have access to. |

    | 404 | Not Found | Either the method and path supplied do not specify a known action or the object related to the request does not exist. |

    | 429 | Too Many Requests | You have exceeded one of the rate limits in the API. See the Rate Limits section for more information. |

    | 500 | Internal Server Error | There was a problem on Farmbrite''s side which was logged and reported to our technical team. You can retry, but if the problem continues please contact support. |


    Details about errors can sometimes also be found in the ''message'' property at the root level of the JSON response body. # Pagination


    In order to optimize performance, all list methods in the API will limit the total response data to a certain number of records and return the data in chunks (pages). API responses will include information about the total records available, the current page and total pages.'
  version: 1.0.0
  x-logo:
    url: https://static.farmbrite.com/assets/www/images/logo.png
    backgroundColor: '#FFFFFF'
    altText: Farmbrite
  termsOfService: https://www.farmbrite.com/terms
  contact:
    name: Farmbrite
    url: https://developers.farmbrite.com
    email: dev@farmbrite.com
servers:
- url: https://api.farmbrite.com/v1
security:
- bearerAuth: []
tags:
- name: Inventory
  description: Inventory types are the base objects for tracking inventory. They store the primary record that all inventory history, location details and tracking are associated with.
paths:
  /inventory_types:
    post:
      tags:
      - Inventory
      summary: Create an Inventory Type
      description: 'Create an inventory type


        ### Parameters


        **name** `REQUIRED`


        The name or primary label for this type of inventory


        ---


        **unit** `REQUIRED`


        The unit that inventory is stored in.


        > "Bales", "Barrels", "Bunches", "Bushels", "Dozen", "Fluid Ounces", "Gallons", "Grams", "Head", "Kilograms", "Kiloliter", "Liter", "Milliliter", "Ounces", "Pounds", "Quantity", "Quarts", "Tonnes", "Tons"


        Defaults to `Quantity`


        ---


        **alert_amount** `OPTIONAL`


        Numeric value that when inventory level goes below will trigger an inventory alert notices in app and to the `alert_email` specified.


        ---


        **alert_email** `OPTIONAL`


        The email address to send inventory alerts to.


        ---


        **days_expires** `OPTIONAL`


        Optional numeric value for the number of days that new inventory is valid for storage before triggering an expired inventory alert.


        ---


        **description** `OPTIONAL`


        Text description or summary of the inventory type


        ---


        **internal_id** `OPTIONAL`


        Custom identification number or SKU used to identify this inventory item


        ---


        **electronic_id** `OPTIONAL`


        Electronic ID - useful to set if using an RFID or barcode scanner to search for for sync data with Farmbrite.


        ---


        **product_id** `OPTIONAL`


        Optional Farmbrite product ID to allow you to link this inventory type to a product in your shop


        ---


        **track_lots** `OPTIONAL`


        Boolean value to indicate if new inventory added should create a new lot number. Defaults to `false`.


        ---


        **type** `OPTIONAL`


        Inventory type, variety or other attribute to specify details about this inventory type.


        ---


        **unit_value** `OPTIONAL`


        Numeric value used to indicate the approximate value (in your account currency) for each unit of inventory.


        ---


        **unit_weight** `OPTIONAL`


        Numeric value for the weight of each inventory item in pounds or kilograms (based on your account settings).'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                alert_amount: 10
                alert_email: user@email.com
                days_expires: 90
                description: ''
                internal_id: ''
                name: Cattle Feed
                product_id: ''
                track_lots: false
                type: Custom Blend
                unit: tons
                unit_value: 1000
                unit_weight: 100
      parameters:
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
      operationId: postInventoryTypes
      x-operation-id-source: derived
  /inventory_types/{inventory_type_id}/inventory/add:
    put:
      tags:
      - Inventory
      summary: Add Inventory
      description: 'Add inventory to a warehouse / inventory location. Response returns the details of the inventory adjustment, including lot ID and lot number (if applicable).


        The response provide a history record including details about the lot (if applicable) as well as total quantity remaining and the amount remaining for the inventory location (warehouse/bin).


        ### Parameters


        **warehouse_id** `REQUIRED`


        The Farmbrite `warehouse_id` for the warehouse where you are adjusting inventory amounts.


        ---


        **adjustment** `REQUIRED`


        A positive numeric value for the amount of inventory to add.


        ---


        **bin_id** `OPTIONAL`


        The Farmbrite warehouse_bin_id where you are adjusting inventory amounts (if applicable)


        ---


        **lot_number** `OPTIONAL`


        The lot number to add/remove inventory from. If this value is left blank and you are tracking lots for an inventory type a new lot number will be generated when inventory is added if this value is left blank.


        ---


        **description** `OPTIONAL`


        A summary of the reason for the inventory change.


        ---


        **date** `OPTIONAL`


        The date that the inventory adjustment occurred. Defaults to today.


        ---


        **source** `OPTIONAL`


        A string that includes the details about where new inventory was sourced from.


        ---


        **harvest_source_type** `OPTIONAL`


        If adding a harvest to inventory, use this property and `harvest_source_id` and `harvest_id` to link the harvest record to the inventory log. Available options are:


        > "animal", "crop"


        ---


        **harvest_source_id** `OPTIONAL`


        The Farmbrite record ID (livestock or planting) that the harvest is sourced from. If adding a harvest to inventory, use this property along with `harvest_source_type` and `harvest_id`to link the harvest record to the inventory log.


        ---


        **harvest_id** `OPTIONAL`


        The Farmbrite `harvest_id` to associate this change with. If adding a harvest to inventory, use this property and `harvest_source_id` and `harvest_source_type` to link the harvest record to the inventory log.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                warehouse_id: '{{warehouse_id}}'
                bin_id: null
                lot_number: null
                description: Api Adjustment
                adjustment: 100
                date: '2023-11-01'
                source: API
                harvest_source_type: null
                harvest_source_id: null
                harvest_id: null
      parameters:
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      - name: inventory_type_id
        in: path
        schema:
          type: string
        required: true
        example: '{{inventory_type_id}}'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
              example:
                id: GUID
                created_at: '2023-10-18 04:21:42'
                date_added: '2022-04-01'
                harvest_id: null
                harvest_source_id: null
                harvest_source_type: null
                lot_number: Lot1
                original_qty: 100
                qty_remaining: 200
                source: API
                updated_at: '2023-10-18 04:21:50'
                total_qty_remaining: 200
                location_qty_remaining: 200
      operationId: putInventoryTypesByInventoryTypeIdInventoryAdd
      x-operation-id-source: derived
  /inventory_types/{inventory_type_id}/inventory/remove:
    put:
      tags:
      - Inventory
      summary: Remove Inventory
      description: 'Remove inventory from a warehouse / inventory location. Response returns the details of the inventory adjustment, including lot ID and lot number (if applicable).


        The response will include quantity details about the lot (if applicable) as well as total quantity remaining and the amount remaining for the inventory location (warehouse/bin).


        ### Parameters


        **warehouse_id** `REQUIRED`


        The Farmbrite `warehouse_id` for the warehouse where you are adjusting inventory amounts.


        ---


        **adjustment** `REQUIRED`


        A positive numeric value for the amount of inventory to remove.


        ---


        **bin_id** `OPTIONAL`


        The Farmbrite warehouse_bin_id where you are adjusting inventory amounts (if applicable)


        ---


        **lot_number** `OPTIONAL`


        The lot number to remove inventory from. If this value is left blank and you are tracking lots for an inventory type a new lot number will be generated when inventory is added if this value is left blank.


        ---


        **description** `OPTIONAL`


        A summary of the reason for the inventory change.


        ---


        **date** `OPTIONAL`


        The date that the inventory adjustment occurred. Defaults to today.


        ---


        **order_id** `OPTIONAL`


        The Farmbrite `order_id` to associate the change in inventory to. Most often used when picking inventory for a specific order.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                warehouse_id: '{{warehouse_id}}'
                bin_id: null
                lot_number: null
                description: Api Adjustment
                adjustment: 50
                date: '2022-04-01'
                order_id: null
      parameters:
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      - name: inventory_type_id
        in: path
        schema:
          type: string
        required: true
        example: '{{inventory_type_id}}'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
              example:
                id: GUID
                created_at: '2023-10-18 04:21:42'
                date_added: '2022-04-01'
                lot_number: Lot1
                original_qty: 100
                qty_remaining: 150
                updated_at: '2023-10-18 04:27:47'
                total_qty_remaining: 150
                location_qty_remaining: 150
      operationId: putInventoryTypesByInventoryTypeIdInventoryRemove
      x-operation-id-source: derived
  /inventory_types/{inventory_type_id}:
    get:
      tags:
      - Inventory
      summary: Retrieve an Inventory Type
      parameters:
      - name: inventory_type_id
        in: path
        schema:
          type: string
        required: true
        example: '{{inventory_type_id}}'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
              example:
                id: GUID
                alert_amount: 10
                alert_email: user@email.com
                created_at: '2022-01-02 00:32:57'
                days_expires: 90
                description: ''
                internal_id: ''
                name: Cattle Feed
                product_id: ''
                projected_empty_date: '2025-06-06 00:00:00'
                track_lots: true
                type: Custom Blend
                unit: tons
                unit_value: 1000
                unit_weight: ''
                updated_at: '2022-02-17 15:55:59'
                qty_remaining: 50
      operationId: getInventoryTypesByInventoryTypeId
      x-operation-id-source: derived
    put:
      tags:
      - Inventory
      summary: Update an Inventory Type
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                internal_id: Inv99
      parameters:
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      - name: inventory_type_id
        in: path
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
      operationId: putInventoryTypesByInventoryTypeId
      x-operation-id-source: derived
    delete:
      tags:
      - Inventory
      summary: Delete an Inventory Type
      parameters:
      - name: inventory_type_id
        in: path
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
      operationId: deleteInventoryTypesByInventoryTypeId
      x-operation-id-source: derived
  /inventory_types/:
    get:
      tags:
      - Inventory
      summary: List Inventory Types
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
              example:
                data:
                - id: GUID
                  alert_amount: 10
                  alert_email: user@email.com
                  created_at: '2022-01-03 00:32:57'
                  days_expires: 90
                  description: ''
                  internal_id: ''
                  name: Cattle Feed
                  product_id: ''
                  track_lots: true
                  type: Custom Blend
                  unit: tons
                  unit_value: 1000
                  unit_weight: 50
                  updated_at: '2022-02-17 15:55:59'
                  qty_remaining: 50
      operationId: getInventoryTypes
      x-operation-id-source: derived
  /inventory_types/{inventory_type_id}/inventory:
    get:
      tags:
      - Inventory
      summary: List Inventory Type Inventory
      parameters:
      - name: inventory_type_id
        in: path
        schema:
          type: string
        required: true
        example: '{{inventory_type_id}}'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
              example:
                data:
                - location_id: Inventory Location ID
                  warehouse_id: Warehouse ID
                  warehouse_name: Area 51
                  bin_id: Bin ID
                  bin_internal_id: A-51
                  bin_name: Misc
                  bin_capacity: 1000
                  bin_unit: quantity
                  qty_remaining: 126
      operationId: getInventoryTypesByInventoryTypeIdInventory
      x-operation-id-source: derived
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer