openapi: 3.1.0
info:
  title: Toys R Us Commerce 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
externalDocs:
  description: Toys R Us LogicBroker API Documentation
  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
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.
  - name: Acknowledgements
    description: >-
      Create and retrieve order acknowledgements (EDI 855) to accept, cancel,
      or backorder order items. Sent after order receipt and before shipment
      or invoice creation.
  - name: Shipments
    description: >-
      Create and retrieve shipment notifications (EDI 856) containing
      containerized data, tracking numbers, and fulfillment details for
      shipped order items.
  - name: Invoices
    description: >-
      Create and retrieve invoices (EDI 810) providing billing details and
      item pricing for fulfilled goods.
  - name: Products
    description: >-
      Manage product catalog items including item creation, updates,
      and availability synchronization.
security:
  - apiKeyAuth: []
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'
  /api/v2/acknowledgements:
    get:
      operationId: getAcknowledgements
      summary: Get Acknowledgements
      description: >-
        Retrieves a list of order acknowledgements submitted by or available
        to the authenticated vendor.
      tags:
        - Acknowledgements
      parameters:
        - name: status
          in: query
          description: Filter acknowledgements 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
      responses:
        '200':
          description: Successfully retrieved acknowledgements
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcknowledgementsResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v2/acknowledgements/import:
    post:
      operationId: createAcknowledgement
      summary: Create Acknowledgement
      description: >-
        Submits a new order acknowledgement (EDI 855) to accept, cancel, or
        backorder order line items. Must be sent after receiving an order and
        before creating a shipment or invoice.
      tags:
        - Acknowledgements
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcknowledgementRequest'
      responses:
        '200':
          description: Acknowledgement successfully imported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportResponse'
        '400':
          description: Invalid acknowledgement data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v2/shipments:
    get:
      operationId: getShipments
      summary: Get Shipments
      description: >-
        Retrieves a list of shipment notifications (EDI 856) submitted by
        or available to the authenticated vendor.
      tags:
        - Shipments
      parameters:
        - name: status
          in: query
          description: Filter shipments 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
      responses:
        '200':
          description: Successfully retrieved shipments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShipmentsResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v2/shipments/import:
    post:
      operationId: createShipment
      summary: Create Shipment
      description: >-
        Submits a new shipment notification (EDI 856) to notify the retailer
        of shipped order items. Includes containerized data such as tracking
        numbers, carrier information, package dimensions, and item-level
        ship quantities.
      tags:
        - Shipments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShipmentRequest'
      responses:
        '200':
          description: Shipment successfully imported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportResponse'
        '400':
          description: Invalid shipment data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v2/invoices:
    get:
      operationId: getInvoices
      summary: Get Invoices
      description: >-
        Retrieves a list of invoices (EDI 810) submitted by or available
        to the authenticated vendor.
      tags:
        - Invoices
      parameters:
        - name: status
          in: query
          description: Filter invoices 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
      responses:
        '200':
          description: Successfully retrieved invoices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoicesResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v2/invoices/import:
    post:
      operationId: createInvoice
      summary: Create Invoice
      description: >-
        Submits a new invoice (EDI 810) providing billing details and item
        pricing for fulfilled goods. The invoice must reference the original
        order and include all line item pricing and payment information.
      tags:
        - Invoices
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceRequest'
      responses:
        '200':
          description: Invoice successfully imported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportResponse'
        '400':
          description: Invalid invoice data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v2/products:
    get:
      operationId: getProducts
      summary: Get Products
      description: >-
        Retrieves a list of product catalog items associated with the
        authenticated vendor account.
      tags:
        - Products
      parameters:
        - name: page
          in: query
          description: Page number for paginated results.
          required: false
          schema:
            type: integer
            minimum: 1
      responses:
        '200':
          description: Successfully retrieved products
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductsResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v2/products/import:
    post:
      operationId: createProduct
      summary: Create or Update Product
      description: >-
        Creates or updates a product catalog item. Used to synchronize
        product information including identifiers, descriptions, pricing,
        and availability between the vendor system and the Toys R Us catalog.
      tags:
        - Products
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductRequest'
      responses:
        '200':
          description: Product successfully imported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportResponse'
        '400':
          description: Invalid product data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  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/
  parameters:
    Key:
      name: key
      in: path
      required: true
      description: The unique LogicBroker document key identifier.
      schema:
        type: integer
        format: int64
  schemas:
    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.
    ImportResponse:
      type: object
      description: Response returned after a successful document import operation.
      properties:
        Body:
          type: object
          description: The imported document body.
        Errors:
          type: array
          description: List of validation errors if any occurred.
          items:
            type: object
            properties:
              Message:
                type: string
        StatusCode:
          type: integer
          description: HTTP status code of the import result.
    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.
    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'
    AcknowledgementRequest:
      type: object
      description: Request body for creating an order acknowledgement (EDI 855).
      required:
        - PartnerPO
        - Lines
      properties:
        PartnerPO:
          type: string
          description: The retailer's purchase order number being acknowledged.
        Lines:
          type: array
          description: Line item acknowledgements.
          items:
            type: object
            properties:
              LineNumber:
                type: integer
              AckCode:
                type: string
                description: >-
                  Acknowledgement code: IA (Accept), IQ (Quantity Changed),
                  IB (Item Backordered), IC (Item Cancelled).
                enum:
                  - IA
                  - IQ
                  - IB
                  - IC
              Quantity:
                type: number
              UnitPrice:
                type: number
                format: double
    AcknowledgementsResponse:
      type: object
      description: Paginated list of order acknowledgements.
      properties:
        TotalResults:
          type: integer
        Body:
          type: array
          items:
            type: object
    ShipmentRequest:
      type: object
      description: Request body for creating a shipment notification (EDI 856).
      required:
        - PartnerPO
        - Packages
      properties:
        PartnerPO:
          type: string
          description: The retailer's purchase order number for this shipment.
        ShipDate:
          type: string
          format: date
          description: Date the shipment was dispatched.
        Carrier:
          type: string
          description: Carrier name or SCAC code.
        ServiceLevel:
          type: string
          description: Shipping service level.
        Packages:
          type: array
          description: List of packages in the shipment.
          items:
            type: object
            properties:
              TrackingNumber:
                type: string
                description: Carrier tracking number.
              Weight:
                type: number
                format: double
              Length:
                type: number
                format: double
              Width:
                type: number
                format: double
              Height:
                type: number
                format: double
              Lines:
                type: array
                description: Line items included in this package.
                items:
                  type: object
                  properties:
                    LineNumber:
                      type: integer
                    Quantity:
                      type: number
    ShipmentsResponse:
      type: object
      description: Paginated list of shipment notifications.
      properties:
        TotalResults:
          type: integer
        Body:
          type: array
          items:
            type: object
    InvoiceRequest:
      type: object
      description: Request body for creating an invoice (EDI 810).
      required:
        - PartnerPO
        - InvoiceNumber
        - Lines
      properties:
        PartnerPO:
          type: string
          description: The retailer's purchase order number.
        InvoiceNumber:
          type: string
          description: The vendor's invoice number.
        InvoiceDate:
          type: string
          format: date
          description: Date of the invoice.
        Lines:
          type: array
          description: Invoiced line items with pricing details.
          items:
            type: object
            properties:
              LineNumber:
                type: integer
              Quantity:
                type: number
              UnitPrice:
                type: number
                format: double
              UOM:
                type: string
    InvoicesResponse:
      type: object
      description: Paginated list of invoices.
      properties:
        TotalResults:
          type: integer
        Body:
          type: array
          items:
            type: object
    ProductRequest:
      type: object
      description: Request body for creating or updating a product catalog item.
      required:
        - SupplierSKU
        - Description
      properties:
        SupplierSKU:
          type: string
          description: The vendor's unique product identifier.
        UPC:
          type: string
          description: Universal Product Code.
        Description:
          type: string
          description: Product title or description.
        UnitPrice:
          type: number
          format: double
          description: Wholesale unit price.
        MSRP:
          type: number
          format: double
          description: Manufacturer's suggested retail price.
        InStock:
          type: boolean
          description: Whether the product is currently in stock.
        Quantity:
          type: integer
          description: Available inventory quantity.
    ProductsResponse:
      type: object
      description: Paginated list of product catalog items.
      properties:
        TotalResults:
          type: integer
        Body:
          type: array
          items:
            type: object