openapi: 3.0.3
info:
  title: Dsco Platform Authentication Orders API
  description: The Dsco Platform API v3 provides dropship and marketplace commerce integration for retailers and suppliers. It supports order management, catalog synchronization, inventory updates, shipment tracking, returns processing, and invoice workflows via streaming and batch endpoints. Authentication uses OAuth2 bearer tokens obtained from the token endpoint.
  version: v3
  contact:
    name: Rithum Support
    url: https://knowledge.rithum.com
  termsOfService: https://www.rithum.com/terms-of-service/
  license:
    name: Proprietary
servers:
- url: https://api.dsco.io/api/v3
  description: Dsco Platform API v3
tags:
- name: Orders
  description: Retailer and supplier order operations
paths:
  /supplier/cancel-in:
    post:
      operationId: supplierCancelOrderItem
      summary: Cancel Order Item
      description: Supplier operation to cancel an order item. Supports small batch mode only.
      tags:
      - Orders
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelBatchRequest'
      responses:
        '200':
          description: Cancellation accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /supplier/acknowledge-order-in:
    post:
      operationId: supplierAcknowledgeOrder
      summary: Acknowledge Orders
      description: Supplier operation to acknowledge receipt of orders. Synchronous only.
      tags:
      - Orders
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcknowledgeOrderRequest'
      responses:
        '200':
          description: Order acknowledged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '401':
          description: Unauthorized
  /supplier/order-out/{orderId}:
    get:
      operationId: supplierGetOrder
      summary: Get Order by ID
      description: Supplier operation to retrieve a specific order by its identifier.
      tags:
      - Orders
      security:
      - BearerAuth: []
      parameters:
      - name: orderId
        in: path
        required: true
        schema:
          type: string
        description: The unique identifier of the order
      responses:
        '200':
          description: Order details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '401':
          description: Unauthorized
        '404':
          description: Order not found
  /supplier/order-out:
    get:
      operationId: supplierListOrders
      summary: List Orders
      description: Supplier operation to retrieve a collection of orders.
      tags:
      - Orders
      security:
      - BearerAuth: []
      parameters:
      - name: status
        in: query
        schema:
          type: string
        description: Filter orders by status
      - name: limit
        in: query
        schema:
          type: integer
        description: Maximum number of orders to return
      responses:
        '200':
          description: List of orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderList'
        '401':
          description: Unauthorized
  /retailer/order-in:
    post:
      operationId: retailerCreateOrder
      summary: Create Retailer Order
      description: Retailer operation to submit consumer orders to the Dsco platform. The orderType must be set to Dropship for dropship orders. Supports small batch and large batch modes.
      tags:
      - Orders
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetailerOrderRequest'
      responses:
        '200':
          description: Order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /retailer/cancel-in:
    post:
      operationId: retailerRequestCancel
      summary: Request Order Cancel
      description: Retailer operation to request cancellation of an order item. Synchronous only.
      tags:
      - Orders
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelBatchRequest'
      responses:
        '200':
          description: Cancellation requested
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '401':
          description: Unauthorized
components:
  schemas:
    Address:
      type: object
      properties:
        name:
          type: string
        street1:
          type: string
        street2:
          type: string
        city:
          type: string
        state:
          type: string
        postalCode:
          type: string
        country:
          type: string
        phone:
          type: string
    CancelRequest:
      type: object
      properties:
        orderId:
          type: string
        lineItemId:
          type: string
        reason:
          type: string
    AcknowledgeOrderRequest:
      type: object
      properties:
        orderIds:
          type: array
          items:
            type: string
    OrderItem:
      type: object
      properties:
        lineItemId:
          type: string
        sku:
          type: string
        quantity:
          type: integer
        cost:
          type: number
          format: float
          description: Cost charged by supplier to retailer
        price:
          type: number
          format: float
    Order:
      type: object
      properties:
        orderId:
          type: string
          description: Unique order identifier
        orderType:
          type: string
          enum:
          - Dropship
          - Marketplace
          description: Type of order
        status:
          type: string
          description: Current order status
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        shippingAddress:
          $ref: '#/components/schemas/Address'
    BatchResponse:
      type: object
      properties:
        batchId:
          type: string
          description: Unique identifier for the batch operation
        status:
          type: string
          enum:
          - accepted
          - processing
          - completed
          - failed
        errors:
          type: array
          items:
            $ref: '#/components/schemas/BatchError'
    BatchError:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        field:
          type: string
    OrderList:
      type: object
      properties:
        orders:
          type: array
          items:
            $ref: '#/components/schemas/Order'
        totalCount:
          type: integer
        hasMore:
          type: boolean
    CancelBatchRequest:
      type: object
      properties:
        cancellations:
          type: array
          items:
            $ref: '#/components/schemas/CancelRequest'
    RetailerOrderRequest:
      type: object
      properties:
        orders:
          type: array
          items:
            $ref: '#/components/schemas/Order'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer