openapi: 3.0.3
info:
  title: Urban Outfitters Affiliate API
  description: >-
    The Urban Outfitters affiliate program managed through Rakuten Advertising
    (formerly LinkShare). Provides affiliate tracking, product data feeds, and
    commission reporting for partners promoting Urban Outfitters products. Commission
    is approximately 2% per confirmed sale with a 30-day cookie window. Partners
    receive access to banner ads, deep linking, promotional materials, and weekly
    newsletters. Integration is done through the Rakuten Advertising platform APIs.
  version: '1.0.0'
  contact:
    name: Urban Outfitters Affiliate Support
    url: https://www.urbanoutfitters.com/help/affiliate
  x-generated-from: documentation
externalDocs:
  description: Urban Outfitters Affiliate Program
  url: https://www.urbanoutfitters.com/help/affiliate
servers:
  - url: https://api.rakutenadvertising.com
    description: Rakuten Advertising API (manages Urban Outfitters affiliate program)
tags:
  - name: Products
    description: Product catalog data for affiliate promotion
  - name: Links
    description: Affiliate tracking link generation and management
  - name: Reports
    description: Commission and performance reporting for affiliates
  - name: Creatives
    description: Banner ads and creative assets for affiliates
security:
  - apiKeyAuth: []
paths:
  /v1/products:
    get:
      operationId: searchProducts
      summary: Urban Outfitters Search Products
      description: >-
        Search the Urban Outfitters product catalog for affiliate promotion.
        Returns product listings with prices, images, and deep link URLs.
      tags:
        - Products
      parameters:
        - name: q
          in: query
          description: Search query string
          schema:
            type: string
          example: "graphic tee"
        - name: category
          in: query
          description: Product category filter
          schema:
            type: string
            enum:
              - womens
              - mens
              - home
              - accessories
              - beauty
          example: "womens"
        - name: limit
          in: query
          description: Maximum number of products to return
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          example: 20
        - name: offset
          in: query
          description: Pagination offset
          schema:
            type: integer
            minimum: 0
            default: 0
          example: 0
      responses:
        '200':
          description: Product search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductSearchResponse'
              examples:
                searchProducts200Example:
                  summary: Default searchProducts 200 response
                  x-microcks-default: true
                  value:
                    total: 450
                    products:
                      - id: "prod-12345"
                        name: "Graphic Tee - Earth Day"
                        price: 29.00
                        currency: "USD"
                        category: "womens"
                        imageUrl: "https://images.urbndata.com/is/image/UrbanOutfitters/prod-12345"
                        affiliateUrl: "https://click.linksynergy.com/link?id=affiliate_id&offerid=788395&type=2&murl=https%3A%2F%2Fwww.urbanoutfitters.com%2Fshop%2Fprod-12345"
        '401':
          description: Unauthorized - invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /v1/products/{product_id}:
    get:
      operationId: getProduct
      summary: Urban Outfitters Get Product Details
      description: >-
        Retrieve detailed information for a specific Urban Outfitters product
        including price, description, available sizes, and affiliate deep link.
      tags:
        - Products
      parameters:
        - name: product_id
          in: path
          required: true
          description: The unique product identifier
          schema:
            type: string
          example: "prod-12345"
      responses:
        '200':
          description: Product details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
              examples:
                getProduct200Example:
                  summary: Default getProduct 200 response
                  x-microcks-default: true
                  value:
                    id: "prod-12345"
                    name: "Graphic Tee - Earth Day"
                    description: "Relaxed-fit graphic tee in 100% cotton"
                    price: 29.00
                    currency: "USD"
                    category: "womens"
                    brand: "Urban Outfitters"
                    inStock: true
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /v1/links:
    post:
      operationId: createAffiliateLink
      summary: Urban Outfitters Create Affiliate Link
      description: >-
        Generate an affiliate tracking link for a specific Urban Outfitters product
        or page URL. The generated link includes affiliate tracking parameters.
      tags:
        - Links
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AffiliateLinkCreate'
            examples:
              createAffiliateLinkRequestExample:
                summary: Default createAffiliateLink request
                x-microcks-default: true
                value:
                  targetUrl: "https://www.urbanoutfitters.com/shop/prod-12345"
                  affiliateId: "aff-abc123"
      responses:
        '200':
          description: Generated affiliate link
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliateLink'
              examples:
                createAffiliateLink200Example:
                  summary: Default createAffiliateLink 200 response
                  x-microcks-default: true
                  value:
                    affiliateUrl: "https://click.linksynergy.com/link?id=aff-abc123&offerid=788395&type=2&murl=https%3A%2F%2Fwww.urbanoutfitters.com%2Fshop%2Fprod-12345"
                    trackingId: "track-xyz789"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /v1/reports/commissions:
    get:
      operationId: getCommissionReport
      summary: Urban Outfitters Get Commission Report
      description: >-
        Retrieve commission earnings and performance metrics for an affiliate
        account within a specified date range.
      tags:
        - Reports
      parameters:
        - name: start_date
          in: query
          description: Start date for the report period
          schema:
            type: string
            format: date
          example: "2025-01-01"
        - name: end_date
          in: query
          description: End date for the report period
          schema:
            type: string
            format: date
          example: "2025-03-31"
        - name: affiliate_id
          in: query
          description: Affiliate account identifier
          schema:
            type: string
          example: "aff-abc123"
      responses:
        '200':
          description: Commission report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommissionReport'
              examples:
                getCommissionReport200Example:
                  summary: Default getCommissionReport 200 response
                  x-microcks-default: true
                  value:
                    affiliateId: "aff-abc123"
                    period:
                      start: "2025-01-01"
                      end: "2025-03-31"
                    totalClicks: 1250
                    totalSales: 48
                    totalRevenue: 2400.00
                    totalCommission: 48.00
                    commissionRate: 0.02
                    currency: "USD"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /v1/creatives:
    get:
      operationId: listCreatives
      summary: Urban Outfitters List Creative Assets
      description: >-
        Retrieve available banner ads and creative assets for affiliate promotion.
      tags:
        - Creatives
      parameters:
        - name: size
          in: query
          description: Banner size filter
          schema:
            type: string
            enum:
              - 300x250
              - 728x90
              - 160x600
              - 300x600
          example: "300x250"
      responses:
        '200':
          description: List of creative assets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreativeListResponse'
              examples:
                listCreatives200Example:
                  summary: Default listCreatives 200 response
                  x-microcks-default: true
                  value:
                    creatives:
                      - id: "banner-abc123"
                        type: "banner"
                        size: "300x250"
                        imageUrl: "https://media.rakutenadvertising.com/uo-banner-300x250.jpg"
                        clickUrl: "https://click.linksynergy.com/fs-bin/click?id=aff-abc123&offerid=788395"
                        startDate: "2025-01-01"
                        endDate: "2025-06-30"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Rakuten Advertising API key provided upon affiliate program enrollment.
        Include as Bearer token in the Authorization header.

  schemas:
    Product:
      type: object
      description: A product available in the Urban Outfitters catalog
      properties:
        id:
          type: string
          description: Unique product identifier
          example: "prod-12345"
        name:
          type: string
          description: Product name
          example: "Graphic Tee - Earth Day"
        description:
          type: string
          description: Product description
          example: "Relaxed-fit graphic tee in 100% cotton"
        price:
          type: number
          description: Product price
          example: 29.00
        salePrice:
          type: number
          description: Sale price if on sale
          example: 19.99
        currency:
          type: string
          description: Price currency
          example: "USD"
        category:
          type: string
          description: Product category
          enum:
            - womens
            - mens
            - home
            - accessories
            - beauty
            - kids
          example: "womens"
        brand:
          type: string
          description: Brand name
          example: "Urban Outfitters"
        imageUrl:
          type: string
          description: Primary product image URL
          example: "https://images.urbndata.com/is/image/UrbanOutfitters/prod-12345"
        affiliateUrl:
          type: string
          description: Affiliate deep link for the product
          example: "https://click.linksynergy.com/link?id=aff-abc123&offerid=788395"
        inStock:
          type: boolean
          description: Whether the product is in stock
          example: true
        sizes:
          type: array
          description: Available sizes
          items:
            type: string
          example: ["XS", "S", "M", "L", "XL"]

    ProductSearchResponse:
      type: object
      description: Paginated product search results
      properties:
        total:
          type: integer
          description: Total matching products
          example: 450
        offset:
          type: integer
          description: Current offset
          example: 0
        limit:
          type: integer
          description: Items per page
          example: 20
        products:
          type: array
          description: List of products
          items:
            $ref: '#/components/schemas/Product'

    AffiliateLink:
      type: object
      description: A generated affiliate tracking link
      properties:
        affiliateUrl:
          type: string
          description: The affiliate tracking URL to use in promotions
          example: "https://click.linksynergy.com/link?id=aff-abc123&offerid=788395"
        trackingId:
          type: string
          description: Unique tracking identifier for this link
          example: "track-xyz789"
        targetUrl:
          type: string
          description: The original target URL being linked
          example: "https://www.urbanoutfitters.com/shop/prod-12345"

    AffiliateLinkCreate:
      type: object
      description: Request to create an affiliate link
      required:
        - targetUrl
        - affiliateId
      properties:
        targetUrl:
          type: string
          description: The Urban Outfitters URL to create an affiliate link for
          example: "https://www.urbanoutfitters.com/shop/prod-12345"
        affiliateId:
          type: string
          description: Affiliate account identifier
          example: "aff-abc123"

    CommissionReport:
      type: object
      description: Commission earnings report for an affiliate
      properties:
        affiliateId:
          type: string
          description: Affiliate account identifier
          example: "aff-abc123"
        period:
          type: object
          description: Reporting period
          properties:
            start:
              type: string
              format: date
              example: "2025-01-01"
            end:
              type: string
              format: date
              example: "2025-03-31"
        totalClicks:
          type: integer
          description: Total affiliate link clicks
          example: 1250
        totalSales:
          type: integer
          description: Total confirmed sales attributed to affiliate
          example: 48
        totalRevenue:
          type: number
          description: Total revenue generated from affiliate sales
          example: 2400.00
        totalCommission:
          type: number
          description: Total commission earned
          example: 48.00
        commissionRate:
          type: number
          description: Commission rate (decimal)
          example: 0.02
        currency:
          type: string
          description: Currency for monetary values
          example: "USD"

    Creative:
      type: object
      description: An affiliate creative asset (banner, text link, etc.)
      properties:
        id:
          type: string
          description: Creative identifier
          example: "banner-abc123"
        type:
          type: string
          description: Creative type
          enum:
            - banner
            - text_link
            - product_link
          example: "banner"
        size:
          type: string
          description: Banner dimensions
          example: "300x250"
        imageUrl:
          type: string
          description: Banner image URL
          example: "https://media.rakutenadvertising.com/uo-banner-300x250.jpg"
        clickUrl:
          type: string
          description: Click-through URL with tracking
          example: "https://click.linksynergy.com/fs-bin/click?id=aff-abc123&offerid=788395"
        startDate:
          type: string
          format: date
          description: Creative activation date
          example: "2025-01-01"
        endDate:
          type: string
          format: date
          description: Creative expiration date
          example: "2025-06-30"

    CreativeListResponse:
      type: object
      description: List of creative assets
      properties:
        creatives:
          type: array
          description: Available creative assets
          items:
            $ref: '#/components/schemas/Creative'

    APIError:
      type: object
      description: API error response
      properties:
        error:
          type: string
          description: Error code
          example: "unauthorized"
        message:
          type: string
          description: Human-readable error message
          example: "Invalid API key. Please check your credentials."
        code:
          type: integer
          description: HTTP status code
          example: 401