Orders Overview
The Orders API allows you to activate Planet Imagery and Basemaps directly on the platform or deliver the data to external cloud storage.
This API is designed for ordering items by catalog ID. For instructions on ordering items by query, please refer to our Subscriptions Documentation.
The Orders API is optimized for smaller-scale orders, with a limit of 500 items per request. If you need to deliver a larger volume of scenes, we recommend using the Subscriptions API for more efficient bulk management.
Orders API Components
Mechanics
Learn how to order scenes and basemaps from the Planet API with examples in curl, Python SDK, and the Planet CLI
Sources
Learn about how to order scenes and basemaps
Product Bundles
Choose a product bundle to order desired assets
Tools
Hosted raster operations to prepare data for your area of study
Notifications
Set email and webhook notifications to follow order progress
Delivery
Download scenes and basemaps or deliver to the cloud
API Reference
Service Contract
The following is a high-level overview of the Orders API service contract. The full spec for each endpoint can be found in the API Reference.
- name: The name of the order.
- source_type: The source imagery type for all orders. Options are
scenesandbasemaps. - products: The products from the Data API or Basemaps API to order.
- tools: The raster tools to apply to the ordered imagery.
- delivery: The cloud storage delivery location for the order.
- hosting: The hosting location for the order.
- notifications: The notifications to send for the order.
Rate Limits
Learn about rate limits in the Rate Limits Overview.
The following rate limits are currently in place by endpoint:
| Endpoint | Rate Limit (r/s, per API key) |
|---|---|
| Bulk Cancel | 5 |
| Cancel | 3 |
| Create | 3 |
| Download | 5 |
| Get | 3 |
| List | 3 |
| Spec | 10 |
| Stats | 5 |
Errors
Refer to the errors overview for information on conventional HTTP response codes.
States
Order state represents the state of the order in its lifecycle. The state of an order can be found in the state property of the GET order responses.
| State | Description |
|---|---|
| queued | The order is accepted and in the queue to run. |
| running | The order is running - processing, producing, and delivering assets. The time an order stays in running depends on: 1. The size of the order (assets per order). While orders with more assets take longer to run, the Orders API is designed to service a bulk ordering use case. As such, orders with more assets have a shorter per-asset running time. Wherever possible, Planet recommends creating fewer orders with more assets per order, to keep per-item running times low. 2. The raster processing tools included in the order. Read more about tools in the Tools & Toolchains page. 3. Some asset types coincide with longer running times. For example, scenes orders with a REOrthoTile or SkySatCollect item_type may experience longer runtimes. |
| success | The order is complete and was successful. All requested data were delivered. |
| partial | The order is complete and was partially successful. The state is valid for order_type partial orders.Generally, orders with a state of partial indicate that some requested items were not delivered because assets were not available, the requester lacked permission to download those assets, or for an indeterminant reason. |
| failed | The order failed. Orders may fail due to permissions issues, lack of availability of certain asset types (especially if the order_type is full), or other validation issues or internal errors. Any available details on order failure are supplied in the error_hints field. |
| cancelled | The order was cancelled and will not be completed. |