openapi: 3.0.3
info:
  title: Salla Shipping and Fulfillment API
  description: |
    REST surface for managing and tracking shipments, shipping zones, pickup
    branches, and courier integrations across Salla merchant stores. Shipping
    apps that implement this contract are listed in the Salla App Store and
    receive shipment lifecycle webhooks (`shipment.creating`,
    `shipment.created`, `shipment.cancelled`).
  version: '2'
  contact:
    name: Salla Developers
    url: https://docs.salla.dev/
    email: support@salla.dev
servers:
- url: https://api.salla.dev/admin/v2
  description: Salla Shipping API production
security:
- OAuth2: []
paths:
  /shipping/companies:
    get:
      summary: List Shipping Companies
      operationId: listShippingCompanies
      tags: [Shipping]
      responses:
        '200': { description: Shipping companies. }
    post:
      summary: Create Shipping Company
      operationId: createShippingCompany
      tags: [Shipping]
      requestBody:
        required: true
        content:
          application/json: { schema: { type: object } }
      responses:
        '201': { description: Shipping company created. }
  /shipping/companies/{company_id}:
    parameters:
    - name: company_id
      in: path
      required: true
      schema: { type: integer }
    get:
      summary: Get Shipping Company
      operationId: getShippingCompany
      tags: [Shipping]
      responses:
        '200': { description: Shipping company details. }
    put:
      summary: Update Shipping Company
      operationId: updateShippingCompany
      tags: [Shipping]
      requestBody:
        required: true
        content:
          application/json: { schema: { type: object } }
      responses:
        '200': { description: Shipping company updated. }
    delete:
      summary: Delete Shipping Company
      operationId: deleteShippingCompany
      tags: [Shipping]
      responses:
        '200': { description: Shipping company deleted. }
  /shipping/zones:
    get:
      summary: List Shipping Zones
      operationId: listShippingZones
      tags: [Zones]
      responses:
        '200': { description: Shipping zones. }
    post:
      summary: Create Shipping Zone
      operationId: createShippingZone
      tags: [Zones]
      requestBody:
        required: true
        content:
          application/json: { schema: { type: object } }
      responses:
        '201': { description: Shipping zone created. }
  /shipping/zones/{zone_id}:
    parameters:
    - name: zone_id
      in: path
      required: true
      schema: { type: integer }
    get:
      summary: Get Shipping Zone
      operationId: getShippingZone
      tags: [Zones]
      responses:
        '200':
          description: Shipping zone details.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ShippingZone' }
    put:
      summary: Update Shipping Zone
      operationId: updateShippingZone
      tags: [Zones]
      requestBody:
        required: true
        content:
          application/json: { schema: { type: object } }
      responses:
        '200': { description: Shipping zone updated. }
  /shipments:
    get:
      summary: List Shipments
      operationId: listShipments
      tags: [Shipments]
      responses:
        '200': { description: Shipments list. }
    post:
      summary: Create Shipment
      operationId: createShipment
      tags: [Shipments]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ShipmentCreate' }
      responses:
        '201':
          description: Shipment created.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Shipment' }
  /shipments/{shipment_id}:
    parameters:
    - name: shipment_id
      in: path
      required: true
      schema: { type: integer }
    get:
      summary: Get Shipment Details
      operationId: getShipment
      tags: [Shipments]
      responses:
        '200':
          description: Shipment details.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Shipment' }
    put:
      summary: Update Shipment
      operationId: updateShipment
      tags: [Shipments]
      requestBody:
        required: true
        content:
          application/json: { schema: { type: object } }
      responses:
        '200': { description: Shipment updated. }
  /shipments/{shipment_id}/cancel:
    parameters:
    - name: shipment_id
      in: path
      required: true
      schema: { type: integer }
    post:
      summary: Cancel Shipment
      operationId: cancelShipment
      tags: [Shipments]
      responses:
        '200': { description: Shipment cancelled. }
  /shipments/{shipment_id}/return:
    parameters:
    - name: shipment_id
      in: path
      required: true
      schema: { type: integer }
    post:
      summary: Create Shipment Return
      operationId: createShipmentReturn
      tags: [Shipments]
      requestBody:
        required: true
        content:
          application/json: { schema: { type: object } }
      responses:
        '201': { description: Shipment return created. }
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.salla.sa/oauth2/auth
          tokenUrl: https://accounts.salla.sa/oauth2/token
          refreshUrl: https://accounts.salla.sa/oauth2/token
          scopes:
            offline_access: Required to receive a refresh token.
            shipments.read: Read shipments.
            shipments.read_write: Read and write shipments.
  schemas:
    ShippingZone:
      type: object
      properties:
        id: { type: integer }
        name: { type: string }
        countries:
          type: array
          items: { type: string, description: ISO 3166-1 alpha-2 country code. }
        cities:
          type: array
          items: { type: string }
        cost: { type: number }
        currency: { type: string }
        free_above: { type: number, nullable: true }
    ShipmentCreate:
      type: object
      required: [order_id, courier_id]
      properties:
        order_id: { type: integer }
        courier_id: { type: integer }
        type: { type: string, enum: [shipment, return] }
        tracking_number: { type: string }
        tracking_link: { type: string, format: uri }
        cost: { type: number }
        pickup_address: { type: object }
        ship_to: { type: object }
        packages:
          type: array
          items: { type: object }
    Shipment:
      type: object
      properties:
        id: { type: integer }
        order_id: { type: integer }
        courier_id: { type: integer }
        courier_name: { type: string }
        tracking_number: { type: string }
        tracking_link: { type: string, format: uri }
        status: { type: string }
        type: { type: string, enum: [shipment, return] }
        total: { type: number }
        currency: { type: string }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }