Order Desk

Order Desk Orders API

Create, retrieve, search, update, and delete orders in an Order Desk store. Filter orders by folder, status, source, date, and customer, add order history notes, and move orders between folders to drive fulfillment workflows.

GitHub OpenAPI

Documentation

📖
Documentation
https://apidocs.orderdesk.com/
📖
APIReference
https://apidocs.orderdesk.com/

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/orderdesk/refs/heads/main/openapi/orderdesk-openapi.yml

Other Resources

🔗
PostmanCollection
https://raw.githubusercontent.com/api-evangelist/orderdesk/refs/heads/main/collections/orderdesk.postman_collection.json
🔗
OpenCollection
https://raw.githubusercontent.com/api-evangelist/orderdesk/refs/heads/main/collections/orderdesk.opencollection.json
🔗
APIsJSON
https://raw.githubusercontent.com/api-evangelist/orderdesk/refs/heads/main/apis.yml

OpenAPI Specification

orderdesk-openapi.yml Raw ↑ 
openapi: 3.0.3
info:
  title: Order Desk API
  description: >-
    The Order Desk API is a JSON REST API for programmatically managing an Order
    Desk store - an ecommerce order management and fulfillment routing platform.
    It exposes Orders, Order Items, Shipments, Inventory Items, and Store
    settings, plus batch and utility endpoints. Every request must include two
    headers, ORDERDESK-STORE-ID and ORDERDESK-API-KEY, which are found in the
    Order Desk dashboard under Store Settings then API. List endpoints support
    limit (default 50, max 500) and offset pagination and return a status field
    with pagination metadata. The API is rate limited with a leaky-bucket
    limiter (~100 requests per rolling 30-second window).
  version: '2.0'
  contact:
    name: Order Desk
    url: https://www.orderdesk.com
  license:
    name: Proprietary
    url: https://www.orderdesk.com/terms/
servers:
  - url: https://app.orderdesk.me/api/v2
    description: Order Desk API v2
security:
  - storeId: []
    apiKey: []
tags:
  - name: Store
    description: Store settings, folder structure, and connectivity test.
  - name: Orders
    description: Create, retrieve, search, update, and delete orders.
  - name: Order Items
    description: Manage line items within an order.
  - name: Shipments
    description: Record and manage shipments and tracking against an order.
  - name: Inventory Items
    description: Maintain the store's inventory catalog.
paths:
  /test:
    get:
      operationId: testConnection
      tags:
        - Store
      summary: Test API connection
      description: Verifies that the store ID and API key are valid and the API is reachable.
      responses:
        '200':
          description: Connection succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /store:
    get:
      operationId: getStore
      tags:
        - Store
      summary: Retrieve store settings
      description: Returns the store's settings and folder structure.
      responses:
        '200':
          description: Store settings and folders.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  store:
                    $ref: '#/components/schemas/Store'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /orders:
    get:
      operationId: listOrders
      tags:
        - Orders
      summary: Search orders
      description: >-
        Retrieves multiple orders, optionally filtered by folder, status,
        source, date range, email, or search terms, with limit/offset pagination.
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - name: folder_id
          in: query
          schema:
            type: integer
          description: Restrict results to a specific folder.
        - name: source_name
          in: query
          schema:
            type: string
          description: Filter by the order source (e.g. Shopify, Amazon).
        - name: email
          in: query
          schema:
            type: string
          description: Filter by customer email address.
        - name: search_start_date
          in: query
          schema:
            type: string
          description: Start of a date range filter.
        - name: search_end_date
          in: query
          schema:
            type: string
          description: End of a date range filter.
      responses:
        '200':
          description: A list of orders.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  total_records:
                    type: integer
                  records_returned:
                    type: integer
                  offset:
                    type: integer
                  limit:
                    type: integer
                  orders:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      operationId: createOrder
      tags:
        - Orders
      summary: Create an order
      description: Creates a new order in the store.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
      responses:
        '200':
          description: The created order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /orders/{order_id}:
    parameters:
      - $ref: '#/components/parameters/OrderId'
    get:
      operationId: getOrder
      tags:
        - Orders
      summary: Get a single order
      description: Retrieves the details of a single order by its ID.
      responses:
        '200':
          description: The requested order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      operationId: updateOrder
      tags:
        - Orders
      summary: Update an order
      description: Updates an existing order. Only supplied fields are changed.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
      responses:
        '200':
          description: The updated order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteOrder
      tags:
        - Orders
      summary: Delete an order
      description: Permanently deletes an order.
      responses:
        '200':
          description: Deletion result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /orders/{order_id}/order-history:
    parameters:
      - $ref: '#/components/parameters/OrderId'
    post:
      operationId: addOrderHistory
      tags:
        - Orders
      summary: Add an order history note
      description: Appends a note to the order's history log.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                note:
                  type: string
      responses:
        '200':
          description: History note added.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /move-orders:
    post:
      operationId: moveOrders
      tags:
        - Orders
      summary: Move orders to a folder
      description: Moves one or more orders into a different folder.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                order_ids:
                  type: array
                  items:
                    type: string
                folder_id:
                  type: integer
      responses:
        '200':
          description: Move result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /orders/{order_id}/order-items:
    parameters:
      - $ref: '#/components/parameters/OrderId'
    get:
      operationId: listOrderItems
      tags:
        - Order Items
      summary: List order items
      description: Returns all line items for an order.
      responses:
        '200':
          description: A list of order items.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  order_items:
                    type: array
                    items:
                      $ref: '#/components/schemas/OrderItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: addOrderItem
      tags:
        - Order Items
      summary: Add an order item
      description: Adds a new line item to an order.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderItem'
      responses:
        '200':
          description: The added order item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /orders/{order_id}/order-items/{item_id}:
    parameters:
      - $ref: '#/components/parameters/OrderId'
      - $ref: '#/components/parameters/ItemId'
    get:
      operationId: getOrderItem
      tags:
        - Order Items
      summary: Get an order item
      description: Retrieves a single line item from an order.
      responses:
        '200':
          description: The requested order item.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  order_item:
                    $ref: '#/components/schemas/OrderItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      operationId: updateOrderItem
      tags:
        - Order Items
      summary: Update an order item
      description: Updates an existing line item.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderItem'
      responses:
        '200':
          description: The updated order item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteOrderItem
      tags:
        - Order Items
      summary: Remove an order item
      description: Removes a line item from an order.
      responses:
        '200':
          description: Deletion result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /orders/{order_id}/shipments:
    parameters:
      - $ref: '#/components/parameters/OrderId'
    get:
      operationId: listShipments
      tags:
        - Shipments
      summary: List shipments
      description: Returns all shipments recorded against an order.
      responses:
        '200':
          description: A list of shipments.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  shipments:
                    type: array
                    items:
                      $ref: '#/components/schemas/Shipment'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createShipment
      tags:
        - Shipments
      summary: Create a shipment
      description: Records a new shipment with carrier and tracking details.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Shipment'
      responses:
        '200':
          description: The created shipment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /orders/{order_id}/shipments/{shipment_id}:
    parameters:
      - $ref: '#/components/parameters/OrderId'
      - $ref: '#/components/parameters/ShipmentId'
    get:
      operationId: getShipment
      tags:
        - Shipments
      summary: Get a shipment
      description: Retrieves a single shipment from an order.
      responses:
        '200':
          description: The requested shipment.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  shipment:
                    $ref: '#/components/schemas/Shipment'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      operationId: updateShipment
      tags:
        - Shipments
      summary: Update a shipment
      description: Updates an existing shipment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Shipment'
      responses:
        '200':
          description: The updated shipment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteShipment
      tags:
        - Shipments
      summary: Delete a shipment
      description: Deletes a shipment from an order.
      responses:
        '200':
          description: Deletion result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /batch-shipments:
    post:
      operationId: batchShipments
      tags:
        - Shipments
      summary: Add multiple shipments
      description: Adds many shipments across orders in a single request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                shipments:
                  type: array
                  items:
                    $ref: '#/components/schemas/Shipment'
      responses:
        '200':
          description: Batch result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /inventory-items:
    get:
      operationId: listInventoryItems
      tags:
        - Inventory Items
      summary: List inventory items
      description: Returns inventory items with limit/offset pagination and optional search.
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - name: code
          in: query
          schema:
            type: string
          description: Filter by inventory item code.
        - name: search
          in: query
          schema:
            type: string
          description: Free-text search across inventory items.
      responses:
        '200':
          description: A list of inventory items.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  total_records:
                    type: integer
                  records_returned:
                    type: integer
                  offset:
                    type: integer
                  limit:
                    type: integer
                  inventory_items:
                    type: array
                    items:
                      $ref: '#/components/schemas/InventoryItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      operationId: createInventoryItem
      tags:
        - Inventory Items
      summary: Create an inventory item
      description: Adds a new item to the inventory catalog.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InventoryItem'
      responses:
        '200':
          description: The created inventory item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /inventory-items/{id}:
    parameters:
      - $ref: '#/components/parameters/InventoryId'
    get:
      operationId: getInventoryItem
      tags:
        - Inventory Items
      summary: Get an inventory item
      description: Retrieves a single inventory item by ID.
      responses:
        '200':
          description: The requested inventory item.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  inventory_item:
                    $ref: '#/components/schemas/InventoryItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      operationId: updateInventoryItem
      tags:
        - Inventory Items
      summary: Update an inventory item
      description: Updates an existing inventory item.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InventoryItem'
      responses:
        '200':
          description: The updated inventory item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteInventoryItem
      tags:
        - Inventory Items
      summary: Delete an inventory item
      description: Removes an item from the inventory catalog.
      responses:
        '200':
          description: Deletion result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /batch-inventory-items:
    put:
      operationId: batchInventoryItems
      tags:
        - Inventory Items
      summary: Update multiple inventory items
      description: Creates or updates many inventory items in a single request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                inventory_items:
                  type: array
                  items:
                    $ref: '#/components/schemas/InventoryItem'
      responses:
        '200':
          description: Batch result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    storeId:
      type: apiKey
      in: header
      name: ORDERDESK-STORE-ID
      description: The numeric ID of your Order Desk store.
    apiKey:
      type: apiKey
      in: header
      name: ORDERDESK-API-KEY
      description: The API key for your Order Desk store.
  parameters:
    Limit:
      name: limit
      in: query
      schema:
        type: integer
        default: 50
        maximum: 500
      description: Number of records to return (default 50, max 500).
    Offset:
      name: offset
      in: query
      schema:
        type: integer
        default: 0
      description: Number of records to skip.
    OrderId:
      name: order_id
      in: path
      required: true
      schema:
        type: string
      description: The ID of the order.
    ItemId:
      name: item_id
      in: path
      required: true
      schema:
        type: string
      description: The ID of the order item.
    ShipmentId:
      name: shipment_id
      in: path
      required: true
      schema:
        type: string
      description: The ID of the shipment.
    InventoryId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: The ID of the inventory item.
  responses:
    Unauthorized:
      description: Missing or invalid store ID / API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StatusResponse'
    RateLimited:
      description: Rate limit exceeded. Retry after the number of seconds in X-Retry-After.
      headers:
        X-Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying.
        X-Tokens-Remaining:
          schema:
            type: integer
          description: Remaining requests in the leaky-bucket window.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StatusResponse'
  schemas:
    StatusResponse:
      type: object
      properties:
        status:
          type: string
          description: success or error.
        message:
          type: string
        errors:
          type: array
          items:
            type: string
    Store:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        folders:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
    Order:
      type: object
      properties:
        id:
          type: string
        source_id:
          type: string
        source_name:
          type: string
        email:
          type: string
        order_total:
          type: number
        folder_id:
          type: integer
        customer_first_name:
          type: string
        customer_last_name:
          type: string
        shipping:
          type: object
          additionalProperties: true
        customer:
          type: object
          additionalProperties: true
        order_items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        shipments:
          type: array
          items:
            $ref: '#/components/schemas/Shipment'
        order_metadata:
          type: object
          additionalProperties: true
        date_added:
          type: string
        date_updated:
          type: string
    OrderResponse:
      type: object
      properties:
        status:
          type: string
        order:
          $ref: '#/components/schemas/Order'
    OrderItem:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        code:
          type: string
        price:
          type: number
        quantity:
          type: integer
        weight:
          type: number
        variation_list:
          type: object
          additionalProperties: true
        metadata:
          type: object
          additionalProperties: true
    Shipment:
      type: object
      properties:
        id:
          type: string
        tracking_number:
          type: string
        carrier_code:
          type: string
        shipment_method:
          type: string
        cost:
          type: number
        weight:
          type: number
        ship_date:
          type: string
    InventoryItem:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        code:
          type: string
        price:
          type: number
        cost:
          type: number
        weight:
          type: number
        stock:
          type: integer
        location:
          type: string
        metadata:
          type: object
          additionalProperties: true