Urban Outfitters Orders API

openapi: 3.2.0
info:
  title: Urban Outfitters Marketplace Orders API
  description: Integration API for the Urban Outfitters curated third-party marketplace (UO MRKT). Independent brands and sellers can list products, manage inventory, receive orders, and update shipment tracking through EDI or third-party integration platforms such as ConnectPointz, SellerCloud, and e-tailize. This spec represents the conceptual API surface for marketplace sellers.
  version: 1.0.0
  contact:
    name: Urban Outfitters Marketplace Support
    url: https://www.urbanoutfitters.com/mrkt-seller-form
  x-generated-from: documentation
servers:
- url: https://marketplace.urbanoutfitters.com/api
  description: Urban Outfitters Marketplace API
security:
- apiKeyAuth: []
tags:
- name: Orders
  description: Order retrieval and management
paths:
  /v1/orders:
    get:
      operationId: listOrders
      summary: Urban Outfitters List Marketplace Orders
      description: Retrieve orders from the Urban Outfitters marketplace for the authenticated seller.
      tags:
      - Orders
      parameters:
      - name: status
        in: query
        description: Filter by order status
        schema:
          type: string
          enum:
          - pending
          - acknowledged
          - shipped
          - delivered
          - cancelled
        example: pending
      - name: start_date
        in: query
        description: Filter orders from this date
        schema:
          type: string
          format: date
        example: '2025-01-01'
      - name: limit
        in: query
        description: Maximum orders to return
        schema:
          type: integer
          default: 20
        example: 20
      responses:
        '200':
          description: List of marketplace orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderListResponse'
              examples:
                listOrders200Example:
                  summary: Default listOrders 200 response
                  x-microcks-default: true
                  value:
                    total: 35
                    orders:
                    - id: order-xyz789
                      status: pending
                      createdAt: '2025-03-15T14:30:00Z'
                      items:
                      - sku: UO-BRAND-TEE-001
                        quantity: 2
                        price: 45.0
                      shippingAddress:
                        name: Jane Smith
                        city: New York
                        state: NY
                        country: US
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    OrderItem:
      type: object
      description: An item in a marketplace order
      properties:
        sku:
          type: string
          example: UO-BRAND-TEE-001
        quantity:
          type: integer
          example: 2
        price:
          type: number
          example: 45.0
    OrderListResponse:
      type: object
      description: Paginated list of marketplace orders
      properties:
        total:
          type: integer
          example: 35
        orders:
          type: array
          items:
            $ref: '#/components/schemas/Order'
    ShippingAddress:
      type: object
      description: A shipping destination address
      properties:
        name:
          type: string
          example: Jane Smith
        address1:
          type: string
          example: 123 Main St
        address2:
          type: string
          example: Apt 4B
        city:
          type: string
          example: New York
        state:
          type: string
          example: NY
        postalCode:
          type: string
          example: '10001'
        country:
          type: string
          example: US
    Order:
      type: object
      description: A marketplace order from Urban Outfitters
      properties:
        id:
          type: string
          description: Order identifier
          example: order-xyz789
        status:
          type: string
          description: Order status
          enum:
          - pending
          - acknowledged
          - shipped
          - delivered
          - cancelled
          example: pending
        createdAt:
          type: string
          format: date-time
          description: Order creation time
          example: '2025-03-15T14:30:00Z'
        items:
          type: array
          description: Ordered items
          items:
            $ref: '#/components/schemas/OrderItem'
        shippingAddress:
          $ref: '#/components/schemas/ShippingAddress'
        total:
          type: number
          description: Order total
          example: 90.0
        currency:
          type: string
          example: USD
    APIError:
      type: object
      description: API error response
      properties:
        error:
          type: string
          example: unauthorized
        message:
          type: string
          example: Invalid API key.
        code:
          type: integer
          example: 401
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-Seller-API-Key
      description: Seller API key provided by Urban Outfitters marketplace onboarding
externalDocs:
  description: Urban Outfitters Marketplace Seller Form
  url: https://www.urbanoutfitters.com/mrkt-seller-form