openapi: 3.1.0
info:
  title: Merchbar Partner Orders 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: Orders
  description: Order previews, creation, tracking, address updates, and cancellation.
paths:
  /order_previews:
    post:
      operationId: createOrderPreview
      tags:
      - Orders
      summary: Preview an order
      description: 'Returns an order preview: a reiteration of the input line items plus a total shipping cost estimate and shipping options. Unavailable items are flagged with `available: false` and excluded from the shipping estimate. Returns an error for non-US countries where international shipping is not supported.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderInput'
      responses:
        '200':
          description: An order preview with shipping options.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/OrderPreview'
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
  /orders:
    post:
      operationId: createOrder
      tags:
      - Orders
      summary: Create an order
      description: Creates a new order. If any requested item is no longer available the entire order fails. Requires a `selected_shipping_option_id` from a prior preview.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/OrderInput'
              - type: object
                required:
                - selected_shipping_option_id
                properties:
                  selected_shipping_option_id:
                    type: string
                    description: The shipping option id chosen from an order preview.
      responses:
        '200':
          description: The created order.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/Order'
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
  /orders/{order_id}:
    get:
      operationId: getOrder
      tags:
      - Orders
      summary: Get order status
      description: Returns the current status of an order, including tracking number once shipped.
      parameters:
      - $ref: '#/components/parameters/OrderId'
      responses:
        '200':
          description: The order.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/Order'
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
    patch:
      operationId: updateOrderAddress
      tags:
      - Orders
      summary: Update order shipping address
      description: Updates the shipping address for an order. Merchbar sends only the `address` field. Returns an error if changing the address is not allowed or would change the shipping cost.
      parameters:
      - $ref: '#/components/parameters/OrderId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - address
              properties:
                address:
                  $ref: '#/components/schemas/Address'
      responses:
        '200':
          description: The updated order.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/Order'
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
  /orders/{order_id}/cancel:
    post:
      operationId: cancelOrder
      tags:
      - Orders
      summary: Cancel an order
      description: Cancels an order. The response body is ignored by Merchbar as long as it is not an error; by REST convention the (now CANCELLED) order object is returned.
      parameters:
      - $ref: '#/components/parameters/OrderId'
      responses:
        '200':
          description: The cancelled order.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/Order'
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
components:
  schemas:
    OrderInput:
      type: object
      required:
      - address
      - line_items
      properties:
        address:
          $ref: '#/components/schemas/Address'
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/LineItemInput'
    LineItem:
      allOf:
      - $ref: '#/components/schemas/LineItemInput'
      - type: object
        properties:
          available:
            type: boolean
    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
    OrderPreview:
      type: object
      properties:
        address:
          $ref: '#/components/schemas/Address'
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/LineItem'
        shipping_options:
          type: array
          items:
            $ref: '#/components/schemas/ShippingOption'
    Identifier:
      description: Object identifier; may be a string or integer (stored as string by Merchbar).
      oneOf:
      - type: string
      - type: integer
    Order:
      type: object
      required:
      - id
      - status
      properties:
        id:
          $ref: '#/components/schemas/Identifier'
        created:
          type: string
          format: date-time
        status:
          type: string
          enum:
          - RECEIVED
          - SHIPPED
          - CANCELLED
        tracking_number:
          type:
          - string
          - 'null'
          description: Provided only when status is SHIPPED.
        ship_date:
          type: string
          format: date
        address:
          $ref: '#/components/schemas/Address'
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/LineItem'
        shipping:
          $ref: '#/components/schemas/ShippingOption'
    LineItemInput:
      type: object
      required:
      - id
      - quantity
      properties:
        id:
          $ref: '#/components/schemas/Identifier'
        variant_id:
          $ref: '#/components/schemas/Identifier'
        quantity:
          type: integer
    ShippingOption:
      type: object
      required:
      - id
      - title
      - price
      - currency
      properties:
        id:
          type: string
        title:
          type: string
        ship_date:
          type: string
          format: date
        ship_time:
          type: string
          description: Human-readable delivery estimate
          e.g. "2-3 business days".: null
        price:
          type: string
        currency:
          type: string
    Address:
      type: object
      required:
      - first_name
      - last_name
      - line1
      - city
      - state
      - postal_code
      - country
      properties:
        first_name:
          type: string
        last_name:
          type: string
        line1:
          type: string
        line2:
          type:
          - string
          - 'null'
        city:
          type: string
        state:
          type: string
        postal_code:
          type: string
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code; defaults to US.
  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:
    OrderId:
      name: order_id
      in: path
      required: true
      description: Order identifier.
      schema:
        $ref: '#/components/schemas/Identifier'
  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.