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. To retrieve your available contracts, call:
```
GET https://app.open-cosmos.com/api/data/v1/dpap/organisations/{organisation_id}/policies
```
The response is an array of contract objects. Use the contract_id field from the appropriate entry. If your organisation has multiple contracts, use the one where default_contract is true unless you have a specific reason to choose another.

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, and contract ID.
Complete checkout — Call the checkout endpoint. If your organisation has sufficient credits, the order is completed automatically with no Stripe interaction. Otherwise, a Stripe payment URL is returned for card 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).

Credits at Checkout

If your organisation has a credit balance, credits are always used first when you call the checkout endpoint. The behaviour depends on whether credits cover the full order total:

Scenario	Result
Credits cover the full order total	Order completed immediately; `checkout_url` is empty; no Stripe session created.
Credits do not cover the full order total	Stripe checkout session created; `checkout_url` is a Stripe payment link.

For fully automated or M2M workflows, organisations with sufficient credits can purchase catalog images entirely via API calls — no browser redirect is required. See Purchasing Catalog Images for details and code examples.

Where to Next

End-to-End Quickstart | Pricing API | Purchasing Catalog Images | API Reference