Ordering API
The Ordering API allows you to retrieve pricing information for catalog data products and complete purchases programmatically. This section describes the end-to-end workflow for purchasing catalog images through the DataCosmos API.
NOTE
This documentation covers purchasing existing catalog images only. For acquiring new imagery through satellite tasking, refer to the Tasking API.
Prerequisites
Before using the Ordering API, make sure you have:
- Authentication credentials — A valid bearer token obtained via the Authentication flow.
- STAC Collection and Item IDs — The identifiers for the catalog images you want to purchase. You can find these by searching the STAC catalog.
- Organisation ID — Your organisation's numeric identifier. This is associated with your account.
- Contract ID — The contract under which the purchase is made.
End-to-End Purchasing Workflow
The following steps describe the complete flow for purchasing catalog images via the API:
-
Search for data products — Use the STAC Search API to find catalog images that match your area of interest, time range, and other criteria.
-
Retrieve pricing — Call the Pricing API to get the price for one or more items before placing an order.
-
Create an order — Submit a purchase request with the selected items, your organisation ID, contract ID, and accepted licenses.
-
Complete checkout — Use the checkout endpoint to obtain a Stripe payment URL and complete the payment.
-
Verify order status — Poll the order details endpoint to confirm the order has been paid and the data is ready for download.
Base URL
All Ordering API endpoints are available at:
https://app.open-cosmos.com/api/data/v0/order/
Key Concepts
Order Types
- IMAGE — Used when purchasing existing catalog data products. This is the order type covered in this documentation.
Order Statuses
| Status | Description |
|---|---|
UNPAID | The order has been created but payment has not been completed. |
PAID | Payment has been received and the purchased data is available. |
CANCELLED | The order has been cancelled. |
Payment Methods
| Method | Description |
|---|---|
CARD | Payment via credit or debit card through the Stripe checkout flow. |
BANK_TRANSFER | Payment via bank transfer (available for enterprise customers). |
NOT_REQUIRED | No payment is required (e.g. when credits fully cover the order). |
Licenses
When creating an order, you must accept the applicable product licenses. Each license includes a link, name, version, and an accepted flag that must be set to true.
Where to Next