In this guide, we’ll explain the concepts of “Order” and “Order Item” in our API, and walk you through the endpoints that help you manage them. These APIs allow you to create, view, and track your orders, and dive into the granular details—like tasks and their statuses—at the order item level.

​
What is an Order?

An Order is a high-level grouping of one or more order items. It represents a complete request submitted through our system, which can include:
  • Tasking orders: Requests for new satellite imagery captures.
  • Archive orders: Requests for imagery from our archives.
  • Combined orders: Orders that may include both tasking and archive components.
Orders provide an overall summary of your request, including details like status, total amount, and the transaction ID. Key Points:
  • Orders are created via the POST /v0/orders endpoint.
  • High-level details such as order status, payment status, and creation timestamps are returned in the order summary.
  • For more granular details (like individual task statuses), you need to look at the order items.

​
What is an Order Item?

An Order Item is a single component within an order. It holds the detailed parameters of a specific request, whether it’s a tasking order for new imagery or an archive order for existing imagery. Each order item includes:
  • Specific configuration (e.g., AOI, bandset, imaging parameters).
  • Associated tasks (for tasking orders), which have their own status updates and processing details.
  • Detailed cost and payment information for that part of the order.
Key Points:
  • Granular details like individual task statuses and progress are tracked at the order item level.
  • Endpoints for listing and fetching order items provide detailed views of each component in your order.

​
Tasks

Tasks are the individual processing units within an order item, each representing a distinct step in the capture or processing workflow. They provide real-time status updates, error messages, and progress metrics, enabling you to monitor the execution of your imagery requests at a granular level. In case of recurring tasking orders, various tasks will be created corresponding to each occurrence.

​
API Endpoints Overview

Below are the key endpoints related to Orders and Order Items, along with a brief explanation of their purpose.

​
1. List Orders

  • Retrieve a paginated list of all orders associated with your service account. This gives you a high-level overview of your order history, including status and basic metadata.

​
2. Get Order Details

  • Fetch detailed information for a specific order using its unique order ID. This includes overall order details, as well as a summary of its order items.

​
3. List Order Items

  • Retrieve a paginated list of order items. This endpoint provides a more granular view of the individual requests within an order.

​
4. Get Order Item Details

  • This endpoint provides granular details, including associated tasks and their statuses. Use it to troubleshoot or monitor the progress of a specific component of your order.

​
How to Use These Endpoints

  1. Placing an Order:
    When you create an order via the POST /v0/orders endpoint, you receive an order ID. This ID gives you a high-level reference to the overall request. You will also receive the order item object for each order item.
  2. Drilling Down into Order Items:
    To track each order item (Tasking or Archive Order), use the “List Order Items” and “Get Order Item Details” endpoints. Here you’ll find detailed information like task status, error messages, and individual cost breakdowns.
  3. Monitoring Task Status:
    For tasking orders, the progress and status of individual tasks are only available at the order item level. Ensure you check the order item details to get the latest updates on your imagery capture or processing.