ShipBob subpackage_orders API

openapi: 3.1.0
info:
  title: API Reference subpackage_billing subpackage_orders API
  version: 1.0.0
servers:
- url: https://api.shipbob.com
- url: https://sandbox-api.shipbob.com
tags:
- name: subpackage_orders
paths:
  /2026-01/order:
    post:
      operationId: create-order
      summary: Create Order
      description: Creates a new order in ShipBob’s system that will be queued for fulfillment. Orders can be created using either product reference IDs (SKUs) or ShipBob product IDs, with reference IDs being the recommended approach.
      tags:
      - subpackage_orders
      parameters:
      - name: Authorization
        in: header
        description: Authentication using Personal Access Token (PAT) token or OAuth2
        required: true
        schema:
          type: string
      - name: shipbob_channel_id
        in: header
        description: Retrieve your channel ID from the [GET /channel](/api/channels/get-channels) endpoint. Use the channel ID that has write scopes.
        required: true
        schema:
          type: string
          format: int32
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.OrderViewModel'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.Post.Api.Order.Bad.Request.Object'
        '401':
          description: No access right at this time
          content:
            application/json:
              schema:
                description: Any type
        '403':
          description: No access
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: Client Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.Post.Api.Order.Unprocessable.Entity.Object'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Orders.CreateOrderModel'
    get:
      operationId: get-orders
      summary: Get Orders
      description: Retrieves a paginated list of orders from your ShipBob account with optional filters. All filter parameters use AND logic, meaning orders must match all provided criteria to be returned.
      tags:
      - subpackage_orders
      parameters:
      - name: Page
        in: query
        description: Page of orders to get
        required: false
        schema:
          type: integer
      - name: Limit
        in: query
        description: Amount of orders per page to request
        required: false
        schema:
          type: integer
      - name: IDs
        in: query
        description: order ids to filter by, comma separated <br /><strong>Example:</strong> ?IDs=1,2
        required: false
        schema:
          type: string
      - name: ReferenceIds
        in: query
        description: Reference ids to filter by, comma separated <br /><strong>Example:</strong> ?ReferenceIds=Ref1,Ref2
        required: false
        schema:
          type: string
      - name: StartDate
        in: query
        description: Start date to filter orders inserted later than
        required: false
        schema:
          type: string
          format: date-time
      - name: EndDate
        in: query
        description: End date to filter orders inserted earlier than
        required: false
        schema:
          type: string
          format: date-time
      - name: SortOrder
        in: query
        description: Order to sort results in
        required: false
        schema:
          type: string
      - name: HasTracking
        in: query
        description: Has any portion of this order been assigned a tracking number
        required: false
        schema:
          type: boolean
      - name: LastUpdateStartDate
        in: query
        description: Start date to filter orders updated later than
        required: false
        schema:
          type: string
          format: date-time
      - name: LastUpdateEndDate
        in: query
        description: End date to filter orders updated later than
        required: false
        schema:
          type: string
          format: date-time
      - name: IsTrackingUploaded
        in: query
        description: Filter orders that their tracking information was fully uploaded
        required: false
        schema:
          type: boolean
      - name: LastTrackingUpdateStartDate
        in: query
        description: Start date to filter orders with tracking updates later than the supplied date. Will only return orders that have tracking information
        required: false
        schema:
          type: string
          format: date-time
      - name: LastTrackingUpdateEndDate
        in: query
        description: End date to filter orders updated later than the supplied date. Will only return orders that have tracking information
        required: false
        schema:
          type: string
          format: date-time
      - name: Authorization
        in: header
        description: Authentication using Personal Access Token (PAT) token or OAuth2
        required: true
        schema:
          type: string
      - name: shipbob_channel_id
        in: header
        description: Retrieve your channel ID from the [GET /channel](/api/channels/get-channels) endpoint. Use the channel ID that has write scopes.
        required: false
        schema:
          type: string
          format: int32
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.OrderViewModelArray'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.Get.Api.Order.Bad.Request.Object'
        '401':
          description: No access right at this time
          content:
            application/json:
              schema:
                description: Any type
        '403':
          description: No access
          content:
            application/json:
              schema:
                description: Any type
  /2026-01/order/{orderId}:
    get:
      operationId: get-order
      summary: Get Order
      description: Retrieves detailed information about a specific order by its order ID, including order status, shipments, products, and recipient details.
      tags:
      - subpackage_orders
      parameters:
      - name: orderId
        in: path
        description: ''
        required: true
        schema:
          type: string
          format: int32
      - name: Authorization
        in: header
        description: Authentication using Personal Access Token (PAT) token or OAuth2
        required: true
        schema:
          type: string
      - name: shipbob_channel_id
        in: header
        description: Retrieve your channel ID from the [GET /channel](/api/channels/get-channels) endpoint. Use the channel ID that has write scopes.
        required: false
        schema:
          type: string
          format: int32
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.OrderViewModel'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.Get.Api.Order.OrderId.Bad.Request.Object'
        '401':
          description: No access right at this time
          content:
            application/json:
              schema:
                description: Any type
        '403':
          description: No access
          content:
            application/json:
              schema:
                description: Any type
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                description: Any type
  /2026-01/shipment/{shipmentId}:
    get:
      operationId: get-shipment
      summary: Get Shipment
      description: Retrieves detailed information about a specific shipment by shipment ID, including shipment status, tracking information, fulfillment center location, and contained products.
      tags:
      - subpackage_orders
      parameters:
      - name: shipmentId
        in: path
        description: The shipment id to get
        required: true
        schema:
          type: string
          format: int32
      - name: Authorization
        in: header
        description: Authentication using Personal Access Token (PAT) token or OAuth2
        required: true
        schema:
          type: string
      - name: shipbob_channel_id
        in: header
        description: Retrieve your channel ID from the [GET /channel](/api/channels/get-channels) endpoint. Use the channel ID that has write scopes.
        required: false
        schema:
          type: string
          format: int32
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.ShipmentViewModel'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.Get.Api.Shipment.ShipmentId.Bad.Request.Object'
        '401':
          description: No access right at this time
          content:
            application/json:
              schema:
                description: Any type
        '403':
          description: No access
          content:
            application/json:
              schema:
                description: Any type
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                description: Any type
  /2026-01/shipment/{shipmentId}/timeline:
    get:
      operationId: get-shipment-timeline
      summary: Get Shipment Timeline
      description: Retrieves a chronological timeline of shipment status updates by shipment ID, showing when each status change occurred and providing visibility into the fulfillment progress.
      tags:
      - subpackage_orders
      parameters:
      - name: shipmentId
        in: path
        description: The shipment id to get
        required: true
        schema:
          type: string
          format: int32
      - name: Authorization
        in: header
        description: Authentication using Personal Access Token (PAT) token or OAuth2
        required: true
        schema:
          type: string
      - name: shipbob_channel_id
        in: header
        description: Retrieve your channel ID from the [GET /channel](/api/channels/get-channels) endpoint. Use the channel ID that has write scopes.
        required: false
        schema:
          type: string
          format: int32
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.ShipmentLogViewModelArray'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.Get.Api.Shipment.ShipmentId.Timeline.Bad.Request.Object'
        '401':
          description: No access right at this time
          content:
            application/json:
              schema:
                description: Any type
        '403':
          description: No access
          content:
            application/json:
              schema:
                description: Any type
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                description: Any type
  /2026-01/shipment:batchCancel:
    post:
      operationId: batch-cancel-shipments
      summary: Batch Cancel Shipments
      description: Cancels multiple shipments in a single request. Shipments can only be cancelled if they are in a cancellable state (i.e. not picked, packed, or shipped yet).
      tags:
      - subpackage_orders
      parameters:
      - name: Authorization
        in: header
        description: Authentication using Personal Access Token (PAT) token or OAuth2
        required: true
        schema:
          type: string
      - name: shipbob_channel_id
        in: header
        description: Retrieve your channel ID from the [GET /channel](/api/channels/get-channels) endpoint. Use the channel ID that has write scopes.
        required: true
        schema:
          type: string
          format: int32
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.CanceledShipmentsViewModel'
        '401':
          description: No access right at this time
          content:
            application/json:
              schema:
                description: Any type
        '403':
          description: No access
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: Client Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.Post.Api.Shipment.Cancelbulk.Unprocessable.Entity.Object'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.Post.Api.Shipment.Cancelbulk.Internal.Server.Error.Object'
      requestBody:
        description: The shipment IDs to cancel
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Orders.CancelShipmentsModel'
  /2026-01/shipment:batchUpdateTrackingUpload:
    post:
      operationId: mark-tracking-uploaded
      summary: Mark Tracking Uploaded
      description: 'Mark tracking information as synced to your external system for multiple shipments. Use this endpoint after syncing tracking data to update the IsTrackingUploaded flag, preventing these shipments from appearing in future GET /order queries with IsTrackingUploaded=false.


        <Tip>Use this endpoint if you''re filtering orders by is_tracking_uploaded. This allows integrations to acknowledge that shipments have been successfully synced to their system.</Tip>'
      tags:
      - subpackage_orders
      parameters:
      - name: Authorization
        in: header
        description: Authentication using Personal Access Token (PAT) token or OAuth2
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.BulkUpdateResponseModel'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.Post.Api.Shipment.BulkUpdateTrackingUpload.Bad.Request.String'
        '401':
          description: No access right at this time
          content:
            application/json:
              schema:
                description: Any type
        '403':
          description: No access
          content:
            application/json:
              schema:
                description: Any type
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                description: Any type
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Orders.BulkUpdateTrackingUploadModel'
  /2026-01/shipment/{shipmentId}:updateAddress:
    put:
      operationId: update-shipment-address
      summary: 'Update Shipment Address

        '
      description: 'Updates the shipping address for a specific shipment.

        '
      tags:
      - subpackage_orders
      parameters:
      - name: shipmentId
        in: path
        description: Unique identifier of the shipment
        required: true
        schema:
          type: integer
      - name: Authorization
        in: header
        description: Authentication using Personal Access Token (PAT) token or OAuth2
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.ShipmentApiResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Orders.UpdateAddressRequest'
  /2026-01/shipment/{shipmentId}:getLineItems:
    get:
      operationId: get-shipment-line-items
      summary: 'Get Shipment Line Items

        '
      description: 'Retrieves the line items for a specific shipment.

        '
      tags:
      - subpackage_orders
      parameters:
      - name: shipmentId
        in: path
        description: Unique identifier of the shipment
        required: true
        schema:
          type: integer
      - name: Authorization
        in: header
        description: Authentication using Personal Access Token (PAT) token or OAuth2
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.ShipmentLineItemDetailArray'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.ErrorResponse'
  /2026-01/shipment/{shipmentId}:updateLineItems:
    post:
      operationId: update-shipment-line-items
      summary: 'Update Shipment Line Items

        '
      description: 'Updates the line items for a specific shipment. The request body must include the complete list of line items as returned by the GET /{shipmentId}:getLineItems endpoint — partial updates are not supported. Retrieve the current line items first, modify the desired fields, and submit the full payload.

        '
      tags:
      - subpackage_orders
      parameters:
      - name: shipmentId
        in: path
        description: Unique identifier of the shipment
        required: true
        schema:
          type: integer
      - name: Authorization
        in: header
        description: Authentication using Personal Access Token (PAT) token or OAuth2
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.ShipmentLineItemsApiResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Orders.UpdateLineItemsRequest'
  /2026-01/shipment:bulkUpdateShippingService:
    put:
      operationId: bulk-update-shipping-service
      summary: 'Bulk Update Shipping Service

        '
      description: 'Updates the shipping service for multiple shipments in a single request.

        '
      tags:
      - subpackage_orders
      parameters:
      - name: Authorization
        in: header
        description: Authentication using Personal Access Token (PAT) token or OAuth2
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.BulkActionApiResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Orders.BulkUpdateShippingServiceRequest'
  /2026-01/order/{orderId}:cancel:
    post:
      operationId: cancel-order
      summary: Cancel Order
      description: Cancels an order and all associated shipments. The order must be in a cancellable state to proceed with the cancellation.
      tags:
      - subpackage_orders
      parameters:
      - name: orderId
        in: path
        description: The order ID to cancel
        required: true
        schema:
          type: string
          format: int32
      - name: Authorization
        in: header
        description: Authentication using Personal Access Token (PAT) token or OAuth2
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.CanceledOrderViewModel'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.Post.Api.Order.OrderId.Cancel.Bad.Request.Object'
        '401':
          description: No access right at this time
          content:
            application/json:
              schema:
                description: Any type
        '403':
          description: No access
          content:
            application/json:
              schema:
                description: Any type
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: Client Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.Post.Api.Order.OrderId.Cancel.Unprocessable.Entity.Object'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.Post.Api.Order.OrderId.Cancel.Internal.Server.Error.Object'
  /2026-01/shipment/{shipmentId}:cancel:
    post:
      operationId: cancel-shipment
      summary: Cancel Shipment
      description: Cancels a specific shipment by shipment ID. The shipment must not be picked, packed, or shipped to proceed with the cancellation.
      tags:
      - subpackage_orders
      parameters:
      - name: shipmentId
        in: path
        description: The shipment id to get
        required: true
        schema:
          type: string
          format: int32
      - name: Authorization
        in: header
        description: Authentication using Personal Access Token (PAT) token or OAuth2
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.ShipmentViewModel'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.Post.Api.Shipment.ShipmentId.Cancel.Bad.Request.Object'
        '401':
          description: No access right at this time
          content:
            application/json:
              schema:
                description: Any type
        '403':
          description: No access
          content:
            application/json:
              schema:
                description: Any type
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: Client Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.Post.Api.Shipment.ShipmentId.Cancel.Unprocessable.Entity.Object'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.Post.Api.Shipment.ShipmentId.Cancel.Internal.Server.Error.Object'
  /2026-01/shipping-method:
    get:
      operationId: get-shipping-methods
      summary: Get Shipping Methods
      description: Retrieves all available shipping methods configured for your merchant account.
      tags:
      - subpackage_orders
      parameters:
      - name: Page
        in: query
        description: Page of orders to get
        required: false
        schema:
          type: integer
      - name: Limit
        in: query
        description: Amount of records per page to request
        required: false
        schema:
          type: integer
      - name: Authorization
        in: header
        description: Authentication using Personal Access Token (PAT) token or OAuth2
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.ShipMethodDetailViewModelArray'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.Get.Api.Shippingmethod.Bad.Request.Object'
        '401':
          description: No access right at this time
          content:
            application/json:
              schema:
                description: Any type
        '403':
          description: No access
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: Client Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.Get.Api.Shippingmethod.Unprocessable.Entity.Object'
  /2026-01/order/{orderId}/shipment/{shipmentId}/timeline:
    get:
      operationId: get-shipment-status-timeline-by-order-id-and-shipment-id
      summary: Get Shipment Status Timeline by Order ID and Shipment ID
      description: Retrieves a chronological timeline of shipment status updates by shipment ID, showing when each status change occurred and providing visibility into the fulfillment progress.
      tags:
      - subpackage_orders
      parameters:
      - name: orderId
        in: path
        description: The order id to get the shipment for
        required: true
        schema:
          type: string
          format: int32
      - name: shipmentId
        in: path
        description: The shipment id to get
        required: true
        schema:
          type: string
          format: int32
      - name: Authorization
        in: header
        description: Authentication using Personal Access Token (PAT) token or OAuth2
        required: true
        schema:
          type: string
      - name: shipbob_channel_id
        in: header
        description: Retrieve your channel ID from the [GET /channel](/api/channels/get-channels) endpoint. Use the channel ID that has write scopes.
        required: false
        schema:
          type: string
          format: int32
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.ShipmentLogViewModelArray'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.Get.Api.Order.OrderId.Shipment.ShipmentId.Timeline.Bad.Request.Object'
        '401':
          description: No access right at this time
          content:
            application/json:
              schema:
                description: Any type
        '403':
          description: No access
          content:
            application/json:
              schema:
                description: Any type
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                description: Any type
  /2026-01/order/{orderId}/shipment:
    get:
      operationId: get-all-shipments-for-order
      summary: Get All Shipments for Order
      description: Retrieves all shipments associated with a specific order, including shipment status, tracking information, and product details.
      tags:
      - subpackage_orders
      parameters:
      - name: orderId
        in: path
        description: The order id to get shipments for
        required: true
        schema:
          type: string
          format: int32
      - name: Authorization
        in: header
        description: Authentication using Personal Access Token (PAT) token or OAuth2
        required: true
        schema:
          type: string
      - name: shipbob_channel_id
        in: header
        description: Retrieve your channel ID from the [GET /channel](/api/channels/get-channels) endpoint. Use the channel ID that has write scopes.
        required: false
        schema:
          type: string
          format: int32
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.Get.Api.Order.OrderId.Shipment.OK.OneOfArray'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.Get.Api.Order.OrderId.Shipment.Bad.Request.Object'
        '401':
          description: No access right at this time
          content:
            application/json:
              schema:
                description: Any type
        '403':
          description: No access
          content:
            application/json:
              schema:
                description: Any type
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                description: Any type
  /2026-01/order/{orderId}/shipment/{shipmentId}/logs:
    get:
      operationId: get-shipment-logs-by-order-id-and-shipment-id
      summary: Get Shipment Logs by Order ID and Shipment ID
      description: Retrieves operational logs for a specific shipment by shipment ID, providing a detailed record of all events and status changes that have occurred.
      tags:
      - subpackage_orders
      parameters:
      - name: orderId
        in: path
        description: The order id to get the shipment for
        required: true
        schema:
          type: string
          format: int32
      - name: shipmentId
        in: path
        description: The shipment id to get
        required: true
        schema:
          type: string
          format: int32
      - name: Authorization
        in: header
        description: Authentication using Personal Access Token (PAT) token or OAuth2
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.ShipmentLogViewModelArray'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.Get.Api.Order.OrderId.Shipment.ShipmentId.Logs.Bad.Request.Object'
        '401':
          description: No access right at this time
          content:
            application/json:
              schema:
                description: Any type
        '403':
          description: No access
          content:
            application/json:
              schema:
         

# --- truncated at 32 KB (100 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/shipbob/refs/heads/main/openapi/shipbob-subpackage-orders-api-openapi.yml