openapi: 3.0.3
info:
  title: Bringg Delivery Hub API
  version: '1.0'
  description: |
    Bringg's Delivery Hub REST API provides programmatic access to last-mile delivery
    orchestration: orders (tasks), routes (runs), customers, teams, service areas,
    service plans, planned delivery windows (delivery slots), exclusion windows
    (blackouts), parking spots, packages, inventory, recurring orders, vehicles,
    delivery blocks, and analytics reports. All endpoints use OAuth 2.0 Client
    Credentials Grant. Base URLs are region-specific (US2/US3/US4, EU2/EU3) and
    follow the pattern https://{region}-admin-api.bringg.com.
  contact:
    name: Bringg Developer Support
    url: https://developers.bringg.com
  termsOfService: https://developers.bringg.com/reference/terms-of-service
  license:
    name: Bringg API Terms of Service
    url: https://developers.bringg.com/reference/terms-of-service
servers:
- url: https://us2-admin-api.bringg.com
  description: US2 region (GCP)
- url: https://us3-admin-api.bringg.com
  description: US3 region (GCP)
- url: https://us4-admin-api.bringg.com
  description: US4 region (GCP)
- url: https://eu2-admin-api.bringg.com
  description: EU2 region (GCP)
- url: https://eu3-admin-api.bringg.com
  description: EU3 region (GCP)
security:
- OAuth2ClientCredentials: []
paths:
  /services/create_task:
    post:
      summary: Create Order
      description: Create a new order (task) in Bringg with one or more waypoints, customer, inventory, service plan, and team assignment.
      tags: [Orders]
      operationId: createTask
      responses:
        '200': {description: Order created.}
  /services/update_task:
    post:
      summary: Update Order
      description: Update an existing order's details, waypoints, inventory, or service plan.
      tags: [Orders]
      operationId: updateTask
      responses:
        '200': {description: Order updated.}
  /services/get_task:
    get:
      summary: Get Order
      description: Retrieve full details of an order by id or external_id.
      tags: [Orders]
      operationId: getTask
      responses:
        '200': {description: Order returned.}
  /services/get_open_tasks:
    get:
      summary: Get Open Orders
      description: List orders currently in an open state (not completed or cancelled).
      tags: [Orders]
      operationId: getOpenTasks
      responses:
        '200': {description: List of open orders.}
  /services/get_post_optimization_tasks:
    get:
      summary: Get Post-Optimization Orders
      description: Retrieve orders after route optimization has been applied.
      tags: [Orders]
      operationId: getPostOptimizationTasks
      responses:
        '200': {description: Post-optimization orders.}
  /services/get_open_orders_by_customer:
    get:
      summary: Get Open Orders by Customer
      description: List open orders for a specific customer.
      tags: [Orders]
      operationId: getOpenOrdersByCustomer
      responses:
        '200': {description: Orders for customer.}
  /services/start_task:
    post:
      summary: Start Order
      description: Mark an order as started (driver beginning execution).
      tags: [Orders]
      operationId: startTask
      responses:
        '200': {description: Order started.}
  /services/end_task:
    post:
      summary: End Order
      description: Mark an order as ended/completed.
      tags: [Orders]
      operationId: endTask
      responses:
        '200': {description: Order ended.}
  /services/cancel_task:
    post:
      summary: Cancel Order
      description: Cancel an order with optional cancellation reason.
      tags: [Orders]
      operationId: cancelTask
      responses:
        '200': {description: Order cancelled.}
  /services/update_task_external_id:
    post:
      summary: Update Order External ID
      description: Update an order's external_id without other changes.
      tags: [Orders]
      operationId: updateTaskExternalId
      responses:
        '200': {description: External id updated.}
  /services/create_task_refund:
    post:
      summary: Create Order Refund
      description: Create a refund record on a task.
      tags: [Orders]
      operationId: createTaskRefund
      responses:
        '200': {description: Refund created.}
  /services/create_task_payment_history:
    post:
      summary: Create Order Payment History
      description: Add a payment history entry to an order.
      tags: [Orders]
      operationId: createTaskPaymentHistory
      responses:
        '200': {description: Payment recorded.}
  /services/checkin:
    post:
      summary: Check-in (Arrived to Destination)
      description: Record driver arrival at an order waypoint.
      tags: [Orders, Waypoints]
      operationId: checkIn
      responses:
        '200': {description: Check-in recorded.}
  /services/checkout:
    post:
      summary: Check-out (Left Destination)
      description: Record driver leaving an order waypoint. Final checkout completes the order.
      tags: [Orders, Waypoints]
      operationId: checkOut
      responses:
        '200': {description: Check-out recorded.}
  /services/mass_checkout:
    post:
      summary: Multi-Order Checkout
      description: Trigger checkout for multiple orders sharing a checkout location.
      tags: [Orders, Waypoints]
      operationId: massCheckout
      responses:
        '200': {description: Bulk checkout accepted.}
  /services/release_tasks:
    post:
      summary: Release Orders
      description: Release orders from Planning to Dispatch, making them available to drivers.
      tags: [Orders]
      operationId: releaseTasks
      responses:
        '200': {description: Orders released.}
  /services/assign_task:
    post:
      summary: Assign Order To Driver
      description: Assign an order directly to a specific driver.
      tags: [Orders, Drivers]
      operationId: assignTask
      responses:
        '200': {description: Assigned.}
  /services/assign_run_driver:
    post:
      summary: Assign Driver To Route
      description: Assign a driver to a route (run) to fulfill its orders.
      tags: [Routes, Drivers]
      operationId: assignRunDriver
      responses:
        '200': {description: Driver assigned to run.}
  /services/assign_run_vehicle:
    post:
      summary: Assign Vehicle To Route
      description: Assign a vehicle to a route instance (run).
      tags: [Routes, Vehicles]
      operationId: assignRunVehicle
      responses:
        '200': {description: Vehicle assigned.}
  /services/unassign_run_driver:
    post:
      summary: Unassign Driver From Route
      description: Remove a driver from a route assignment.
      tags: [Routes, Drivers]
      operationId: unassignRunDriver
      responses:
        '200': {description: Driver unassigned.}
  /services/unassign_run_vehicle:
    post:
      summary: Unassign Vehicle From Route
      description: Remove a vehicle from a route assignment.
      tags: [Routes, Vehicles]
      operationId: unassignRunVehicle
      responses:
        '200': {description: Vehicle unassigned.}
  /services/create_note:
    post:
      summary: Create Note
      description: Create a note attached to a waypoint or order.
      tags: [Notes]
      operationId: createNote
      responses:
        '200': {description: Note created.}
  /services/update_note:
    post:
      summary: Update Note
      description: Update an existing note's text.
      tags: [Notes]
      operationId: updateNote
      responses:
        '200': {description: Note updated.}
  /services/create_customer:
    post:
      summary: Create Customer
      description: Create a new customer record.
      tags: [Customers]
      operationId: createCustomer
      responses:
        '200': {description: Customer created.}
  /services/update_customer:
    post:
      summary: Update Customer
      description: Update an existing customer record.
      tags: [Customers]
      operationId: updateCustomer
      responses:
        '200': {description: Customer updated.}
  /services/create_blacklisted_customer_user:
    post:
      summary: Create Blacklisted Customer Driver
      description: Block a driver from delivering to a specific customer.
      tags: [Customers, Drivers]
      operationId: createBlacklistedCustomerUser
      responses:
        '200': {description: Blacklist entry created.}
  /services/delete_blacklisted_customer_user:
    delete:
      summary: Delete Blacklisted Customer Driver
      description: Remove a blacklist entry between customer and driver.
      tags: [Customers, Drivers]
      operationId: deleteBlacklistedCustomerUser
      responses:
        '200': {description: Blacklist removed.}
  /services/get_blacklisted_customer_users:
    get:
      summary: Get Blacklisted Customer Drivers
      description: List blacklist entries between drivers and customers.
      tags: [Customers, Drivers]
      operationId: getBlacklistedCustomerUsers
      responses:
        '200': {description: Blacklist list.}
  /services/create_team:
    post:
      summary: Create Team
      description: Create a new team.
      tags: [Teams]
      operationId: createTeam
      responses:
        '200': {description: Team created.}
  /services/update_team:
    post:
      summary: Update Team
      description: Update an existing team.
      tags: [Teams]
      operationId: updateTeam
      responses:
        '200': {description: Team updated.}
  /services/delete_team:
    delete:
      summary: Delete Team
      description: Delete a team.
      tags: [Teams]
      operationId: deleteTeam
      responses:
        '200': {description: Team deleted.}
  /services/get_team:
    get:
      summary: Get Team
      description: Retrieve a team by id.
      tags: [Teams]
      operationId: getTeam
      responses:
        '200': {description: Team returned.}
  /services/team_index:
    get:
      summary: List Teams
      description: List all teams for the merchant.
      tags: [Teams]
      operationId: teamIndex
      responses:
        '200': {description: Teams returned.}
  /services/create_service_area:
    post:
      summary: Create Service Area
      description: Create a service area defined by a polygon.
      tags: [Service Areas]
      operationId: createServiceArea
      responses:
        '200': {description: Service area created.}
  /services/update_service_area:
    post:
      summary: Update Service Area
      description: Update an existing service area.
      tags: [Service Areas]
      operationId: updateServiceArea
      responses:
        '200': {description: Updated.}
  /services/get_service_area:
    get:
      summary: Get Service Area
      description: Get a service area by id.
      tags: [Service Areas]
      operationId: getServiceArea
      responses:
        '200': {description: Returned.}
  /services/get_service_areas:
    get:
      summary: Get Service Areas
      description: List all service areas.
      tags: [Service Areas]
      operationId: getServiceAreas
      responses:
        '200': {description: List returned.}
  /services/delete_service_area:
    delete:
      summary: Delete Service Area
      description: Delete a service area.
      tags: [Service Areas]
      operationId: deleteServiceArea
      responses:
        '200': {description: Deleted.}
  /services/create_team_service_area:
    post:
      summary: Assign Team To Service Area
      description: Assign one or more teams to a service area.
      tags: [Service Areas, Teams]
      operationId: createTeamServiceArea
      responses:
        '200': {description: Team assigned.}
  /services/get_teams_service_areas:
    get:
      summary: Get Team Service Areas
      description: Get the team-service-area coupling.
      tags: [Service Areas, Teams]
      operationId: getTeamsServiceAreas
      responses:
        '200': {description: Returned.}
  /services/update_team_service_area:
    post:
      summary: Update Team Service Area
      description: Update teams assigned to a service area.
      tags: [Service Areas, Teams]
      operationId: updateTeamServiceArea
      responses:
        '200': {description: Updated.}
  /services/create_service_plan:
    post:
      summary: Create Service Plan
      description: Create a service plan defining service level, time window, and requirements.
      tags: [Service Plans]
      operationId: createServicePlan
      responses:
        '200': {description: Created.}
  /services/update_service_plan:
    post:
      summary: Update Service Plan
      description: Update an existing service plan.
      tags: [Service Plans]
      operationId: updateServicePlan
      responses:
        '200': {description: Updated.}
  /services/get_service_plan:
    get:
      summary: Get Service Plan
      description: Retrieve a service plan by id or external_id.
      tags: [Service Plans]
      operationId: getServicePlan
      responses:
        '200': {description: Returned.}
  /services/get_service_plans:
    get:
      summary: Get Service Plans
      description: List all service plans.
      tags: [Service Plans]
      operationId: getServicePlans
      responses:
        '200': {description: List returned.}
  /services/create_planned_delivery_window:
    post:
      summary: Create Planned Delivery Window
      description: Create a delivery slot (planned delivery window).
      tags: [Delivery Slots]
      operationId: createPlannedDeliveryWindow
      responses:
        '200': {description: Slot created.}
  /services/update_planned_delivery_window:
    post:
      summary: Update Planned Delivery Window
      description: Update a delivery slot.
      tags: [Delivery Slots]
      operationId: updatePlannedDeliveryWindow
      responses:
        '200': {description: Slot updated.}
  /services/get_quotes:
    post:
      summary: Get Quotes
      description: Get delivery quotes and availability for a proposed order.
      tags: [Quotes]
      operationId: getQuotes
      responses:
        '200': {description: Quotes returned.}
  /services/async_operation_status:
    get:
      summary: Async Operation Status
      description: Check the status of an asynchronous operation.
      tags: [Operations]
      operationId: asyncOperationStatus
      responses:
        '200': {description: Status returned.}
  /services/create_exclusion_window:
    post:
      summary: Create Exclusion Window
      description: Create a blackout (exclusion window) for delivery availability.
      tags: [Blackouts]
      operationId: createExclusionWindow
      responses:
        '200': {description: Blackout created.}
  /services/update_exclusion_window:
    post:
      summary: Update Exclusion Window
      description: Update a blackout window.
      tags: [Blackouts]
      operationId: updateExclusionWindow
      responses:
        '200': {description: Blackout updated.}
  /services/delete_exclusion_window:
    delete:
      summary: Delete Exclusion Window
      description: Delete a blackout window.
      tags: [Blackouts]
      operationId: deleteExclusionWindow
      responses:
        '200': {description: Deleted.}
  /services/get_exclusion_windows:
    get:
      summary: Get Exclusion Windows
      description: List blackout windows.
      tags: [Blackouts]
      operationId: getExclusionWindows
      responses:
        '200': {description: List returned.}
  /services/create_planned_route:
    post:
      summary: Create Planned Route Identifier
      description: Create a named planned-route identifier.
      tags: [Planned Routes]
      operationId: createPlannedRoute
      responses:
        '200': {description: Created.}
  /services/update_planned_route:
    post:
      summary: Update Planned Route Identifier
      description: Update a planned route identifier.
      tags: [Planned Routes]
      operationId: updatePlannedRoute
      responses:
        '200': {description: Updated.}
  /services/create_recurrent_order_template:
    post:
      summary: Create Recurring Order Template
      description: Create a recurring order template.
      tags: [Recurring Orders]
      operationId: createRecurrentOrderTemplate
      responses:
        '200': {description: Created.}
  /services/delete_recurrent_order_template:
    delete:
      summary: Delete Recurring Order Template
      description: Delete a recurring order template.
      tags: [Recurring Orders]
      operationId: deleteRecurrentOrderTemplate
      responses:
        '200': {description: Deleted.}
  /services/get_recurrent_order_templates_by_customer:
    get:
      summary: Get Recurring Order Templates By Customer
      description: List recurring order templates for a customer.
      tags: [Recurring Orders]
      operationId: getRecurrentOrderTemplatesByCustomer
      responses:
        '200': {description: List returned.}
  /services/create_package:
    post:
      summary: Create Package
      description: Create a package associated with an order.
      tags: [Packages]
      operationId: createPackage
      responses:
        '200': {description: Created.}
  /services/update_package:
    post:
      summary: Update Package
      description: Update a package.
      tags: [Packages]
      operationId: updatePackage
      responses:
        '200': {description: Updated.}
  /services/upsert_package:
    post:
      summary: Upsert Package
      description: Create or update a package by external_id.
      tags: [Packages]
      operationId: upsertPackage
      responses:
        '200': {description: Upserted.}
  /services/delete_package:
    delete:
      summary: Delete Package
      description: Delete a package.
      tags: [Packages]
      operationId: deletePackage
      responses:
        '200': {description: Deleted.}
  /services/get_package:
    get:
      summary: Get Package
      description: Retrieve a package by id.
      tags: [Packages]
      operationId: getPackage
      responses:
        '200': {description: Returned.}
  /services/get_task_packages:
    get:
      summary: Get Task Packages
      description: List all packages for an order.
      tags: [Packages]
      operationId: getTaskPackages
      responses:
        '200': {description: Returned.}
  /services/create_inventory:
    post:
      summary: Create Inventory
      description: Create an inventory item associated with an order.
      tags: [Inventory]
      operationId: createInventory
      responses:
        '200': {description: Created.}
  /services/update_inventory:
    post:
      summary: Update Inventory
      description: Update an inventory item.
      tags: [Inventory]
      operationId: updateInventory
      responses:
        '200': {description: Updated.}
  /services/upsert_floating_inventory:
    post:
      summary: Upsert Floating Inventory
      description: Create or update a floating inventory item not associated with a specific order.
      tags: [Floating Inventory]
      operationId: upsertFloatingInventory
      responses:
        '200': {description: Upserted.}
  /services/soft_delete_floating_inventory:
    post:
      summary: Soft Delete Floating Inventory
      description: Soft delete floating inventory items while retaining DB record.
      tags: [Floating Inventory]
      operationId: softDeleteFloatingInventory
      responses:
        '200': {description: Soft deleted.}
  /services/mass_delete_floating_inventory:
    post:
      summary: Mass Delete Floating Inventory
      description: Delete multiple floating inventory items in bulk.
      tags: [Floating Inventory]
      operationId: massDeleteFloatingInventory
      responses:
        '200': {description: Deleted.}
  /services/mass_custody_change_floating_inventory:
    post:
      summary: Mass Custody Change To Vehicle
      description: Move multiple floating inventory items to vehicle custody.
      tags: [Floating Inventory, Vehicles]
      operationId: massCustodyChangeFloatingInventory
      responses:
        '200': {description: Custody changed.}
  /services/analytics_reports:
    get:
      summary: Get Analytics Report
      description: Retrieve an analytics report for a scheduled report.
      tags: [Analytics]
      operationId: analyticsReports
      responses:
        '200': {description: Report returned.}
  /services/get_report:
    get:
      summary: Get Report
      description: Get the latest version of a scheduled analytics report. Redirects to data file.
      tags: [Analytics]
      operationId: getReport
      responses:
        '302': {description: Redirect to data file.}
  /services/get_undelivered_webhooks:
    get:
      summary: Generate Undelivered Webhooks Report
      description: Retrieve a report of webhooks Bringg sent without receiving confirmation.
      tags: [Webhooks]
      operationId: getUndeliveredWebhooks
      responses:
        '200': {description: Report returned.}
  /services/create_parking_spot:
    post:
      summary: Create Parking Spot
      description: Create a parking spot for vehicles.
      tags: [Parking Spots]
      operationId: createParkingSpot
      responses:
        '200': {description: Created.}
  /services/update_parking_spot:
    post:
      summary: Update Parking Spot
      description: Update a parking spot.
      tags: [Parking Spots]
      operationId: updateParkingSpot
      responses:
        '200': {description: Updated.}
  /services/delete_parking_spot:
    delete:
      summary: Delete Parking Spot
      description: Delete a parking spot.
      tags: [Parking Spots]
      operationId: deleteParkingSpot
      responses:
        '200': {description: Deleted.}
  /services/get_parking_spot_by_id:
    get:
      summary: Get Parking Spot
      description: Get a parking spot by id.
      tags: [Parking Spots]
      operationId: getParkingSpotById
      responses:
        '200': {description: Returned.}
  /services/get_all_parking_spots:
    get:
      summary: Get All Parking Spots
      description: List all parking spots.
      tags: [Parking Spots]
      operationId: getAllParkingSpots
      responses:
        '200': {description: List returned.}
  /services/create_task_configuration:
    post:
      summary: Create Order Configuration
      description: Create a task configuration (set of driver actions and operational capabilities).
      tags: [Order Configurations]
      operationId: createTaskConfiguration
      responses:
        '200': {description: Created.}
  /services/update_task_configuration:
    post:
      summary: Update Order Configuration
      description: Update an order configuration.
      tags: [Order Configurations]
      operationId: updateTaskConfiguration
      responses:
        '200': {description: Updated.}
  /services/prepare_resource:
    post:
      summary: Prepare Bulk Resource
      description: Prepare a JSONL bulk upload resource (step 1 of bulk pipeline).
      tags: [Bulk]
      operationId: prepareResource
      responses:
        '200': {description: Resource prepared.}
  /services/process_resource:
    post:
      summary: Process Bulk Resource
      description: Process the uploaded bulk resource (step 4 of bulk pipeline).
      tags: [Bulk]
      operationId: processResource
      responses:
        '200': {description: Processing started.}
  /services/get_process_resource:
    get:
      summary: Get Bulk Resource Status
      description: Get bulk processing status and results.
      tags: [Bulk]
      operationId: getProcessResource
      responses:
        '200': {description: Status returned.}
  /services/get_companies:
    get:
      summary: Get Companies
      description: Get merchants/companies the caller has access to.
      tags: [Administration]
      operationId: getCompanies
      responses:
        '200': {description: Returned.}
components:
  securitySchemes:
    OAuth2ClientCredentials:
      type: oauth2
      description: |
        OAuth 2.0 Client Credentials Grant. Exchange your client_id and client_secret
        for an access token via POST https://admin-api.bringg.com/oauth/token (or the
        regional equivalent), then send Authorization: Bearer <access_token>.
      flows:
        clientCredentials:
          tokenUrl: https://admin-api.bringg.com/oauth/token
          scopes:
            create_task: Create orders
            update_task: Update orders
            get_task: Read orders
            cancel_task: Cancel orders
            assign_task: Assign orders to drivers
            checkin: Driver check-in
            checkout: Driver check-out
            create_customer: Create customers
            update_customer: Update customers
            create_team: Create teams
            create_service_area: Create service areas
            create_service_plan: Create service plans
            get_quotes: Get delivery quotes