eBay Fulfillment API — Order

naftiko: 1.0.0-alpha2
info:
  label: eBay Fulfillment API — Order
  description: 'eBay Fulfillment API — Order. 3 operations. Lead operation: eBay Issue Refund. Self-contained Naftiko capability
    covering one Ebay business surface.'
  tags:
  - Ebay
  - Order
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    EBAY_API_KEY: EBAY_API_KEY
capability:
  consumes:
  - type: http
    namespace: fulfillment-order
    baseUri: https://api.ebay.com{basePath}
    description: eBay Fulfillment API — Order business capability. Self-contained, no shared references.
    resources:
    - name: order
      path: /order
      operations:
      - name: getorders
        method: GET
        description: Use this method to search for and retrieve one or more orders based on their creation date, last modification
          date, or fulfillment status using the <b>filter</b> parameter. You can alternatively specify a list of orders using
          the <b>orderId
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: fieldGroups
          in: query
          type: string
          description: This parameter lets you control what is returned in the response.<br><br><span class="tablenote"><b>Note:</b>
            The only presently supported value is <code>TAX_BR
        - name: filter
          in: query
          type: string
          description: One or more comma-separated criteria for narrowing down the collection of orders returned by this call.
            These criteria correspond to specific fields in the resp
        - name: limit
          in: query
          type: string
          description: The number of orders to return per page of the result set. Use this parameter in conjunction with the
            <b>offset</b> parameter to control the pagination of the o
        - name: offset
          in: query
          type: string
          description: Specifies the number of orders to skip in the result set before returning the first order in the paginated
            response.  <p>Combine <b>offset</b> with the <b>limit
        - name: orderIds
          in: query
          type: string
          description: A comma-separated list of the unique identifiers of the orders to retrieve (maximum 50). If one or
            more order ID values are specified through the <b>orderIds</b
    - name: order-orderId
      path: /order/{orderId}
      operations:
      - name: getorder
        method: GET
        description: Use this call to retrieve the contents of an order based on its unique identifier, <i>orderId</i>. This
          value was returned in the <b> getOrders</b> call's <b>orders.orderId</b> field when you searched for orders by creation
          date, modificati
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: fieldGroups
          in: query
          type: string
          description: This parameter lets you control what is returned in the response.<br><br><span class="tablenote"><b>Note:</b>
            The only presently supported value is <code>TAX_BR
        - name: orderId
          in: path
          type: string
          description: This path parameter is used to specify the unique identifier of the order being retrieved.<br><br>
            Use the <a href="/api-docs/sell/fulfillment/resources/order/m
          required: true
    - name: order-order_id-issue_refund
      path: /order/{order_id}/issue_refund
      operations:
      - name: issuerefund
        method: POST
        description: eBay Issue Refund
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: order_id
          in: path
          type: string
          description: This path parameter is used to specify the unique identifier of the order associated with a refund.<br><br>Use
            the <a href="/api-docs/sell/fulfillment/resources
          required: true
        - name: Content-Type
          in: header
          type: string
          description: 'This header indicates the format of the request body provided by the client. Its value should be set
            to <b>application/json</b>. <br><br> For more information, '
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    authentication:
      type: bearer
      token: '{{env.EBAY_API_KEY}}'
  exposes:
  - type: rest
    namespace: fulfillment-order-rest
    port: 8080
    description: REST adapter for eBay Fulfillment API — Order. One Spectral-compliant resource per consumed operation, prefixed
      with /v1.
    resources:
    - path: /v1/order
      name: order
      description: REST surface for order.
      operations:
      - method: GET
        name: getorders
        description: Use this method to search for and retrieve one or more orders based on their creation date, last modification
          date, or fulfillment status using the <b>filter</b> parameter. You can alternatively specify a list of orders using
          the <b>orderId
        call: fulfillment-order.getorders
        with:
          fieldGroups: rest.fieldGroups
          filter: rest.filter
          limit: rest.limit
          offset: rest.offset
          orderIds: rest.orderIds
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/order/{orderid}
      name: order-orderid
      description: REST surface for order-orderId.
      operations:
      - method: GET
        name: getorder
        description: Use this call to retrieve the contents of an order based on its unique identifier, <i>orderId</i>. This
          value was returned in the <b> getOrders</b> call's <b>orders.orderId</b> field when you searched for orders by creation
          date, modificati
        call: fulfillment-order.getorder
        with:
          fieldGroups: rest.fieldGroups
          orderId: rest.orderId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/order/{order-id}/issue-refund
      name: order-order-id-issue-refund
      description: REST surface for order-order_id-issue_refund.
      operations:
      - method: POST
        name: issuerefund
        description: eBay Issue Refund
        call: fulfillment-order.issuerefund
        with:
          order_id: rest.order_id
          Content-Type: rest.Content-Type
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: fulfillment-order-mcp
    port: 9090
    transport: http
    description: MCP adapter for eBay Fulfillment API — Order. One tool per consumed operation, routed inline through this
      capability's consumes block.
    tools:
    - name: use-this-method-search-and
      description: Use this method to search for and retrieve one or more orders based on their creation date, last modification
        date, or fulfillment status using the <b>filter</b> parameter. You can alternatively specify a list of orders using
        the <b>orderId
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: fulfillment-order.getorders
      with:
        fieldGroups: tools.fieldGroups
        filter: tools.filter
        limit: tools.limit
        offset: tools.offset
        orderIds: tools.orderIds
      outputParameters:
      - type: object
        mapping: $.
    - name: use-this-call-retrieve-contents
      description: Use this call to retrieve the contents of an order based on its unique identifier, <i>orderId</i>. This
        value was returned in the <b> getOrders</b> call's <b>orders.orderId</b> field when you searched for orders by creation
        date, modificati
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: fulfillment-order.getorder
      with:
        fieldGroups: tools.fieldGroups
        orderId: tools.orderId
      outputParameters:
      - type: object
        mapping: $.
    - name: ebay-issue-refund
      description: eBay Issue Refund
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: fulfillment-order.issuerefund
      with:
        order_id: tools.order_id
        Content-Type: tools.Content-Type
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.