openapi: 3.1.0
info:
  title: Magento REST Authentication Shipments API
  description: 'The Adobe Commerce (Magento) REST API provides a comprehensive set of endpoints for interacting with all major aspects of an e-commerce store, including catalog management, orders, customers, inventory, shipping, and payments. It supports three authentication mechanisms: OAuth 1.0a for third-party integrations, token-based authentication for mobile apps and administrators, and guest access for select public endpoints. The API follows REST conventions and returns JSON responses, enabling developers to build integrations, automate store operations, and power headless commerce storefronts. All endpoints are versioned under the /V1 prefix and support searchCriteria query parameters for filtering, sorting, and paginating collection responses.'
  version: '2.4'
  contact:
    name: Adobe Commerce Developer Support
    url: https://developer.adobe.com/commerce/webapi/rest/
  termsOfService: https://www.adobe.com/legal/terms.html
servers:
- url: https://{store_domain}/rest/{store_code}
  description: Production Server
  variables:
    store_domain:
      default: your-store.example.com
      description: The hostname of your Adobe Commerce store
    store_code:
      default: V1
      description: Store code followed by API version. Use "all" as store code for admin-scope operations, or the specific store view code for store-scoped operations. The V1 version path segment follows.
security:
- bearerAuth: []
tags:
- name: Shipments
  description: Shipment management for orders including shipment creation, retrieval, tracking number management, and shipment comments.
paths:
  /V1/shipment:
    post:
      operationId: createShipment
      summary: Create a shipment
      description: Creates a new shipment record for an order. The request must include the order_id and the items being shipped with their quantities. Tracking information such as carrier code, title, and tracking number can be included at creation time. An optional shipment comment can also be provided.
      tags:
      - Shipments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShipmentRequest'
      responses:
        '200':
          description: Shipment entity ID
          content:
            application/json:
              schema:
                type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /V1/shipment/{shipmentId}:
    get:
      operationId: getShipment
      summary: Get shipment by ID
      description: Retrieves a single shipment by its numeric entity ID. Returns the full shipment object including shipment items, tracking information, comments, and the associated order reference. Admin authentication is required.
      tags:
      - Shipments
      parameters:
      - $ref: '#/components/parameters/shipmentId'
      responses:
        '200':
          description: Shipment object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shipment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    shipmentId:
      name: shipmentId
      in: path
      description: The numeric shipment entity ID.
      required: true
      schema:
        type: integer
  responses:
    Unauthorized:
      description: Unauthorized — missing or invalid authentication token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request — invalid input parameters or request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found — the requested resource does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Shipment:
      type: object
      description: A shipment record tracking the physical dispatch of order items.
      properties:
        entity_id:
          type: integer
          description: Numeric shipment entity ID.
        order_id:
          type: integer
          description: Numeric entity ID of the parent order.
        increment_id:
          type: string
          description: Human-readable shipment number.
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the shipment was created.
        tracks:
          type: array
          description: Tracking information for this shipment.
          items:
            type: object
            properties:
              carrier_code:
                type: string
                description: Carrier code (e.g. ups, fedex, usps).
              title:
                type: string
                description: Human-readable carrier name.
              track_number:
                type: string
                description: Tracking number provided by the carrier.
    ShipmentRequest:
      type: object
      description: Request body for creating a shipment record for an order.
      required:
      - entity
      properties:
        entity:
          $ref: '#/components/schemas/Shipment'
    Error:
      type: object
      description: Standard error response returned for 4xx and 5xx responses.
      properties:
        message:
          type: string
          description: Human-readable error message.
        parameters:
          type: array
          description: Additional error context parameters.
          items:
            type: object
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token obtained from the /V1/integration/admin/token or /V1/integration/customer/token endpoint. Include in the Authorization header as "Bearer {token}".
externalDocs:
  description: Adobe Commerce REST API Documentation
  url: https://developer.adobe.com/commerce/webapi/rest/