> ## Documentation Index
> Fetch the complete documentation index at: https://docs.salesive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a shipping label for an order

> Create a shipping label for an order. Requires the WRITE_SHIPPING scope.

Generates a courier shipping label for an order's automatic shipment via the carrier aggregator, then updates the shipment with the returned tracking number, tracking URL, courier contact details and status. Only valid for shipments whose shipping option is of type `auto`; cached rates must still be valid. Requires the `WRITE_SHIPPING` scope.


## OpenAPI

````yaml POST /shipping/labels
openapi: 3.1.0
info:
  title: Salesive Apps API — Shipping & Fulfillment
  version: 1.0.0
  description: >-
    Manage shipping options, live courier rates, shipments and labels, and the
    ShipDay delivery integration from an installed third-party app. Every
    endpoint authenticates with an installed-app access token (prefix `app_`)
    and requires a specific OAuth scope. The target store is bound to the token
    server-side from the installation — never send a shop id.
servers:
  - url: https://api.salesive.com/api/v1
    description: Production
security:
  - AppToken: []
paths:
  /shipping/labels:
    post:
      tags:
        - Shipping
      summary: Create a shipping label for an order
      description: >-
        Generates a courier shipping label for an order's automatic shipment via
        the carrier aggregator, then updates the shipment with the returned
        tracking number, tracking URL, courier contact details and status. Only
        valid for shipments whose shipping option is of type `auto`; cached
        rates must still be valid. Requires the `WRITE_SHIPPING` scope.
      operationId: createLabel
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                orderId:
                  type: string
                  description: >-
                    ObjectId of the order whose automatic shipment should get a
                    label.
              required:
                - orderId
            example:
              orderId: 6640c1b2d4e5f60102030406
      responses:
        '201':
          description: Create a shipping label for an order.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/EnvelopeBase'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/Shipment'
              example:
                status: 201
                success: true
                message: Create a shipping label for an order
                data:
                  _id: 6651b2c3d4e5f60102030405
                  orders:
                    - 6640c1b2d4e5f60102030406
                  carrier: DHL Express
                  courier:
                    id: dhl
                    name: DHL Express
                    phone: '+2348000000000'
                    email: courier@example.com
                  trackingNumber: SB12345678
                  trackingCode: SB12345678
                  trackingUrl: https://track.example.com/SB12345678
                  status: confirmed
                  metadata:
                    label_details:
                      order_id: SB12345678
                      status: confirmed
                      tracking_url: https://track.example.com/SB12345678
                  createdAt: '2026-06-28T09:00:00.000Z'
                  updatedAt: '2026-06-28T09:05:00.000Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    EnvelopeBase:
      type: object
      description: >-
        Standard Salesive response envelope. The operation-specific payload is
        carried in `data`.
      required:
        - status
        - success
        - message
      properties:
        status:
          type: integer
          description: HTTP status code, echoed in the body.
        success:
          type: boolean
          description: Whether the request succeeded.
        message:
          type: string
          description: Human-readable result message.
    Shipment:
      type: object
      description: >-
        A shipment record. Shapes vary slightly by how the shipment was created
        (manual, automatic label, or ShipDay dispatch); only the most common
        fields are listed and extra properties may be present.
      additionalProperties: true
      properties:
        _id:
          type: string
          description: ObjectId of the shipment.
        orders:
          type: array
          items:
            type: string
          description: Order ObjectIds attached to the shipment.
        carrier:
          type:
            - string
            - 'null'
          description: Carrier name.
        courier:
          type:
            - object
            - 'null'
          additionalProperties: true
          description: Courier contact details.
        shippingAddress:
          type:
            - string
            - 'null'
          description: Destination shipping address ObjectId.
        shippingOption:
          type:
            - string
            - 'null'
          description: Shipping option ObjectId, if any.
        metadata:
          type: object
          additionalProperties: true
          description: Carrier/aggregator metadata.
        trackingNumber:
          type:
            - string
            - 'null'
          description: Tracking number.
        trackingCode:
          type:
            - string
            - 'null'
          description: Tracking code.
        trackingUrl:
          type:
            - string
            - 'null'
          description: Tracking URL.
        shippingMethod:
          type:
            - string
            - 'null'
          description: Shipping method label.
        shippingCost:
          type:
            - number
            - 'null'
          description: Shipping cost.
        notes:
          type:
            - string
            - 'null'
          description: Free-text notes.
        status:
          type: string
          description: Shipment status.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Envelope:
      allOf:
        - $ref: '#/components/schemas/EnvelopeBase'
        - type: object
          properties:
            data:
              description: Operation-specific payload (object, array, or null).
  responses:
    Unauthorized:
      description: Missing or invalid app access token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Envelope'
          example:
            status: 401
            success: false
            message: Authentication required
            data: null
    Forbidden:
      description: The app token is missing the OAuth scope required for this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Envelope'
          example:
            status: 403
            success: false
            message: Insufficient scope
            data: null
  securitySchemes:
    AppToken:
      type: http
      scheme: bearer
      description: >-
        Installed-app access token (prefix app_), issued by the OAuth install
        flow. The store is bound to the token server-side — never send a shop
        id.

````