openapi: 3.1.0
info:
  title: Merchbar Partner Orders Stores API
  version: '1.0'
  description: The Merchbar Partner API is the REST contract a merchandise partner implements so that Merchbar (operated by CopThis) can list a partner's stores and merchandise and place, track, update, and cancel orders on behalf of Merchbar customers. Partners host both a staging and a production implementation of this contract. Authentication is HTTP Basic over HTTPS; responses use a JSON envelope with a top-level `data` key (and `pagination` for collections), and errors return an `error` key with a 4xx/5xx status.
  contact:
    name: Merchbar (CopThis)
    url: https://github.com/CopThis/partner-api
  x-source: https://github.com/CopThis/partner-api/blob/master/partner_api.md
  x-note: Faithfully transcribed from the published Merchbar Partner API documentation (partner_api.md). This is a partner-implemented contract; each partner hosts the API at their own base host, so the server below is a template variable.
servers:
- url: https://{partnerHost}/v1
  description: Partner-hosted API base (staging or production); versioned via URI path.
  variables:
    partnerHost:
      default: api.partner.example.com
      description: The partner's own API host that implements this contract.
security:
- basicAuth: []
tags:
- name: Stores
  description: Partner stores (typically one per artist) and their merchandise.
paths:
  /stores:
    get:
      operationId: listStores
      tags:
      - Stores
      summary: List stores
      description: 'Returns a list of stores. Typically one store is assigned per artist. Stores can be hidden from Merchbar users with `visible: false`. Paginated unless the number of stores is small.'
      parameters:
      - $ref: '#/components/parameters/PerPage'
      - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: A paginated list of stores.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/StoreSummary'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
              example:
                data:
                - id: 1
                  title: Artist Name
                  visible: true
                - id: 2
                  title: Another Artist
                  visible: false
                pagination:
                  current_page: 1
                  per_page: 10
                  total_pages: 1
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
  /stores/{id}:
    get:
      operationId: getStore
      tags:
      - Stores
      summary: Get store metadata
      description: Returns extended store metadata. Merchbar polls this endpoint for every store at least once a day to keep store status up to date.
      parameters:
      - name: id
        in: path
        required: true
        description: Store identifier (string or integer).
        schema:
          $ref: '#/components/schemas/Identifier'
      responses:
        '200':
          description: Store metadata.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/Store'
              example:
                data:
                  id: 1
                  title: Artist Name
                  description: The official store of Artist Name!
                  photo: https://dt72k0ec4onep.cloudfront.net/JSNEMSDE92381733.JPG
                  visible: true
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
  /stores/{id}/merch:
    get:
      operationId: listStoreMerch
      tags:
      - Stores
      summary: List store merchandise
      description: Returns a paginated list of merchandise within a specific store. Merchbar polls this endpoint for every store at least once a day to keep item quantities up to date. Each merch item is a single design in a single color; sizes/fits are expressed as `variants`.
      parameters:
      - name: id
        in: path
        required: true
        description: Store identifier.
        schema:
          $ref: '#/components/schemas/Identifier'
      - $ref: '#/components/parameters/PerPage'
      - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: A paginated list of merchandise.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Merch'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
components:
  schemas:
    Error:
      type: object
      required:
      - error
      description: Error envelope. `error` may be a simple string or an object with details.
      properties:
        error:
          oneOf:
          - type: string
          - type: object
    Store:
      allOf:
      - $ref: '#/components/schemas/StoreSummary'
      - type: object
        properties:
          description:
            type: string
            description: Store description (basic HTML supported).
          photo:
            type: string
            format: uri
            description: Store image URL.
    StoreSummary:
      type: object
      required:
      - id
      - title
      - visible
      properties:
        id:
          $ref: '#/components/schemas/Identifier'
        title:
          type: string
        visible:
          type: boolean
          description: If false
          the store's merchandise is hidden from Merchbar users.: null
    Merch:
      type: object
      required:
      - id
      - title
      - price
      - currency
      - quantity
      - visible
      - status
      properties:
        id:
          $ref: '#/components/schemas/Identifier'
        title:
          type: string
        description:
          type: string
          description: Item description (basic HTML supported).
        color:
          type: string
        price:
          type: string
          description: Price as a string without a currency marker.
        currency:
          type: string
        quantity:
          type: integer
        sale_price:
          type:
          - string
          - 'null'
        visible:
          type: boolean
        status:
          type: string
          enum:
          - available
          - backorder
          - preorder
        available_date:
          type:
          - string
          - 'null'
          format: date
          description: Availability date for backorder/preorder items (ISO 8601 date), if known.
        photos:
          type: array
          items:
            type: string
            format: uri
          description: Product image URLs in preferred order.
        variants:
          type: array
          description: Size/fit variants; omitted entirely when the item has no variants.
          items:
            $ref: '#/components/schemas/Variant'
    Variant:
      type: object
      required:
      - id
      - title
      - quantity
      - price
      - currency
      properties:
        id:
          $ref: '#/components/schemas/Identifier'
        title:
          type: string
        quantity:
          type: integer
        price:
          type: string
          description: Price as a string without a currency marker
          e.g. "15.99".: null
        currency:
          type: string
          description: ISO 4217 currency code
          e.g. USD.: null
        sale_price:
          type:
          - string
          - 'null'
          description: Current sale price if the item is on sale, else null.
    Identifier:
      description: Object identifier; may be a string or integer (stored as string by Merchbar).
      oneOf:
      - type: string
      - type: integer
    Pagination:
      type: object
      properties:
        current_page:
          type: integer
          description: The current page (1-indexed).
        per_page:
          type: integer
          description: Page size.
        total_pages:
          type: integer
          description: Number of pages accessible.
  responses:
    Error:
      description: An error response with a 4xx or 5xx status.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            simple:
              value:
                error: Forbidden
            detailed:
              value:
                error:
                  code: item_unavailable
                  message: SKU123 is no longer available
  parameters:
    PerPage:
      name: per_page
      in: query
      required: false
      description: Number of items per page.
      schema:
        type: integer
    Page:
      name: page
      in: query
      required: false
      description: Current page number (1-indexed).
      schema:
        type: integer
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication over HTTPS. Merchbar recommends a randomly generated token as the username and a blank password. Non-TLS connections are rejected.