openapi: 3.1.0
info:
  title: Toys R Us Commerce Acknowledgements Orders API
  description: The Toys R Us Commerce API, powered by LogicBroker, enables supplier and dropship vendor integrations for the complete order lifecycle. The API supports order management, shipment notifications, invoice processing, acknowledgement workflows, and product catalog synchronization. Vendors authenticate using an API subscription key and interact with endpoints to exchange transactional documents compatible with EDI standards including EDI 850 (orders), EDI 855 (acknowledgements), EDI 856 (shipments), and EDI 810 (invoices).
  version: '1.0'
  contact:
    name: Toys R Us Supplier Support
    url: https://toysrus.logicbroker.com/hc/en-us/articles/9357008230164-API-Documentation
servers:
- url: https://commerceapi.io
  description: Production Server
- url: https://stage.commerceapi.io
  description: Stage / Testing Server
security:
- apiKeyAuth: []
tags:
- name: Orders
  description: Retrieve and manage purchase orders in the EDI 850 format. Orders initiate the order lifecycle and update until all items are fulfilled and invoiced.
paths:
  /api/v2/orders:
    get:
      operationId: getOrders
      summary: Get Orders
      description: Retrieves a list of purchase orders available for the authenticated vendor. Returns orders in their current state including new, in progress, and completed orders.
      tags:
      - Orders
      parameters:
      - name: status
        in: query
        description: Filter orders by status code.
        required: false
        schema:
          type: integer
      - name: page
        in: query
        description: Page number for paginated results.
        required: false
        schema:
          type: integer
          minimum: 1
      - name: pageSize
        in: query
        description: Number of records per page.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 200
      responses:
        '200':
          description: Successfully retrieved orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrdersResponse'
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v2/orders/{key}:
    get:
      operationId: getOrder
      summary: Get Order
      description: Retrieves a single purchase order by its unique key identifier. Returns the full order document including line items, ship-to information, and order status.
      tags:
      - Orders
      parameters:
      - $ref: '#/components/parameters/Key'
      responses:
        '200':
          description: Successfully retrieved order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    OrderLineItem:
      type: object
      description: A single line item in a purchase order.
      properties:
        LineNumber:
          type: integer
          description: The line item number within the order.
        SupplierSKU:
          type: string
          description: The vendor's product identifier (SKU).
        BuyerSKU:
          type: string
          description: The retailer's product identifier.
        UPC:
          type: string
          description: Universal Product Code for the item.
        Description:
          type: string
          description: Product description.
        Quantity:
          type: number
          description: Ordered quantity.
        UnitPrice:
          type: number
          format: double
          description: Unit price of the item.
        UOM:
          type: string
          description: Unit of measure.
    Error:
      type: object
      description: Standard error response from the LogicBroker Commerce API.
      properties:
        StatusCode:
          type: integer
          description: HTTP status code.
        Message:
          type: string
          description: Human-readable error description.
        Id:
          type: string
          description: Unique error trace identifier.
    Order:
      type: object
      description: A purchase order document in EDI 850 format.
      properties:
        Key:
          type: integer
          format: int64
          description: Unique document key.
        PartnerPO:
          type: string
          description: The retailer's purchase order number.
        OrderDate:
          type: string
          format: date
          description: Date the order was placed.
        Status:
          type: integer
          description: Current status code of the order.
        ShipToAddress:
          type: object
          description: Ship-to address for this order.
          properties:
            Name:
              type: string
            Address1:
              type: string
            Address2:
              type: string
            City:
              type: string
            State:
              type: string
            Zip:
              type: string
            Country:
              type: string
        LineItems:
          type: array
          description: List of line items in the order.
          items:
            $ref: '#/components/schemas/OrderLineItem'
    OrdersResponse:
      type: object
      description: Paginated list of purchase orders.
      properties:
        TotalResults:
          type: integer
        PageSize:
          type: integer
        PageNumber:
          type: integer
        Body:
          type: array
          items:
            $ref: '#/components/schemas/Order'
  parameters:
    Key:
      name: key
      in: path
      required: true
      description: The unique LogicBroker document key identifier.
      schema:
        type: integer
        format: int64
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: subscription-key
      description: API subscription key obtained from the Toys R Us LogicBroker supplier portal. Set up your key at https://stageportal.logicbroker.com/profile/api-authentication/
externalDocs:
  description: Toys R Us LogicBroker API Documentation
  url: https://toysrus.logicbroker.com/hc/en-us/articles/9357008230164-API-Documentation