openapi: 3.0.3
info:
  title: Ally Invest Accounts Orders API
  description: The Ally Invest REST API (originally developed from the TradeKing acquisition) provides programmatic access to self-directed brokerage account management, order placement, real-time and delayed market data, watchlist management, and member profile information. Authentication uses OAuth 1.0 with consumer and token credentials. Responses are available in JSON and XML formats.
  version: v1
  contact:
    email: InvestAPI@ally.com
  termsOfService: https://www.ally.com/content/dam/pdf/invest/api-agreement.pdf
  x-logo:
    url: https://kinlane-images.s3.amazonaws.com/shared/apis-json/apis-json-logo.jpg
servers:
- url: https://api.ally.com/v1
  description: Ally Invest REST API
- url: https://stream.ally.com/v1
  description: Ally Invest Streaming API
tags:
- name: Orders
  description: Order placement, preview, retrieval, and cancellation
paths:
  /accounts/{id}/orders.json:
    get:
      operationId: getOrders
      summary: Get open orders for an account
      description: Returns a list of open orders for a specific account.
      tags:
      - Orders
      parameters:
      - $ref: '#/components/parameters/AccountId'
      responses:
        '200':
          description: Successful response with orders list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrdersResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
      - OAuth1: []
    post:
      operationId: postOrder
      summary: Place an order
      description: Places an equity or options order for a specific account. Orders are submitted in a FIXML-variant XML format. Requires OAuth 1.0 authentication.
      tags:
      - Orders
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/FIXMLOrderRequest'
            example: "<FIXML xmlns=\"http://www.fixprotocol.org/FIXML-5-0-SP2\">\n  <Order TmInForce=\"0\" Typ=\"1\" Side=\"1\" Acct=\"12345678\">\n    <Instrmt SecTyp=\"CS\" Sym=\"GE\"/>\n    <OrdQty Qty=\"1\"/>\n  </Order>\n</FIXML>"
      responses:
        '200':
          description: Order successfully placed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
      - OAuth1: []
  /accounts/{id}/orders/preview.json:
    post:
      operationId: previewOrder
      summary: Preview an order before placement
      description: Previews an order for a specific account to validate parameters and see estimated costs before actual execution. Uses the same FIXML-variant XML format as order placement.
      tags:
      - Orders
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/FIXMLOrderRequest'
      responses:
        '200':
          description: Order preview successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderPreviewResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
      - OAuth1: []
  /accounts/{id}/orders/{orderId}.json:
    delete:
      operationId: cancelOrder
      summary: Cancel a pending order
      description: Cancels a specific pending order for an account.
      tags:
      - Orders
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: orderId
        in: path
        required: true
        description: The order ID to cancel
        schema:
          type: string
      responses:
        '200':
          description: Order cancelled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelOrderResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
      - OAuth1: []
components:
  responses:
    Unauthorized:
      description: Authentication required or credentials invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Requested resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    FIXMLOrderRequest:
      type: object
      description: FIXML-variant XML order document. The root element is <FIXML> with a child <Order> element containing trade attributes and child elements for <Instrmt> (instrument), <OrdQty> (quantity), and optionally <CommInfo> (commission).
      xml:
        name: FIXML
        namespace: http://www.fixprotocol.org/FIXML-5-0-SP2
    ErrorResponse:
      type: object
      properties:
        response:
          type: object
          properties:
            error:
              type: string
              description: Error message
            elapsedtime:
              type: string
            id:
              type: string
    OrderPreviewResponse:
      type: object
      properties:
        response:
          type: object
          properties:
            order:
              $ref: '#/components/schemas/Order'
            cost:
              type: object
              properties:
                commission:
                  type: string
                estimatedcost:
                  type: string
                estimatednetamount:
                  type: string
                estimatedprice:
                  type: string
                estimatedpriceimpact:
                  type: string
                marginrequirement:
                  type: string
                tax:
                  type: string
            warnings:
              type: object
              properties:
                warning:
                  type: array
                  items:
                    type: string
            elapsedtime:
              type: string
            id:
              type: string
            error:
              type: string
    OrderResponse:
      type: object
      properties:
        response:
          type: object
          properties:
            order:
              $ref: '#/components/schemas/Order'
            elapsedtime:
              type: string
            id:
              type: string
            error:
              type: string
    OrdersResponse:
      type: object
      properties:
        response:
          type: object
          properties:
            orders:
              type: object
              properties:
                order:
                  type: array
                  items:
                    $ref: '#/components/schemas/Order'
            elapsedtime:
              type: string
            id:
              type: string
            error:
              type: string
    CancelOrderResponse:
      type: object
      properties:
        response:
          type: object
          properties:
            order:
              $ref: '#/components/schemas/Order'
            elapsedtime:
              type: string
            id:
              type: string
            error:
              type: string
    Order:
      type: object
      properties:
        accountid:
          type: string
        createtime:
          type: string
        displayqty:
          type: string
        duration:
          type: string
          description: Order duration (day, gtc, etc.)
        executedqty:
          type: string
        id:
          type: string
          description: Order ID
        img:
          type: string
        instrument:
          type: object
          properties:
            exch:
              type: string
            sectyp:
              type: string
            sym:
              type: string
        ordertype:
          type: string
          description: Order type (market, limit, stop, stop_limit)
        origclordid:
          type: string
        price:
          type: string
        qty:
          type: string
        side:
          type: string
          description: Order side (buy, sell, sell_short, buy_to_cover)
        stopprice:
          type: string
        statustext:
          type: string
        xref:
          type: string
  parameters:
    AccountId:
      name: id
      in: path
      required: true
      description: The account ID (account number)
      schema:
        type: string
  securitySchemes:
    OAuth1:
      type: apiKey
      in: header
      name: Authorization
      description: OAuth 1.0 authentication using consumer key/secret and OAuth token/secret pairs. The Authorization header must include oauth_consumer_key, oauth_token, oauth_signature_method (HMAC-SHA1), oauth_timestamp, oauth_nonce, oauth_version, and oauth_signature.
externalDocs:
  description: Ally Invest API Documentation
  url: https://www.ally.com/api/invest/documentation/getting-started/