> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Create AceDataCloud Platform Top-Up Orders

> Platform integration guide - Ace Data Cloud

Create pending payment orders for one or more Applications. Creation writes the order, but does not automatically complete payment; before payment, verify the `price`, package, and Application in the response.

## Preparation

* Create an [Account Token](https://platform.acedata.cloud/documents/platform-token).
* Obtain the `application_id` from the [Application list](https://platform.acedata.cloud/documents/platform-application-list).
* Select a purchasable `package_id` matching the Application type from `packages` in the [service details](https://platform.acedata.cloud/documents/platform-service-detail).

```shell theme={null}
export PLATFORM_TOKEN='your account token'
export APPLICATION_ID='your Application ID'
export PACKAGE_ID='your Package ID'
```

## API Overview

| Item | Content |
| - | - |
| Method | `POST` |
| URL | `https://platform.acedata.cloud/api/v1/orders/` |
| Auth | Account Token; OAuth token requires `orders:write` |
| Body | JSON |

## Request Body

Single-Application orders use `application_id` + `package_id`; batch orders use corresponding-length `application_ids` + `package_ids`. Regular orders select a payment method in the subsequent `/pay/` request. For iOS in-app purchase orders, pass `pay_way: "AppleIAP"` when creating them, and only one Usage package with `metadata.apple_product_id` and `metadata.apple_price` can be selected. Apple in-app purchases use independent preset USD prices and do not stack membership discounts, payment method discounts, or site markups; the amount charged in local currency in other regions is subject to the Apple payment confirmation page.

```shell theme={null}
curl -X POST 'https://platform.acedata.cloud/api/v1/orders/' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d "{\"application_id\":\"${APPLICATION_ID}\",\"package_id\":\"${PACKAGE_ID}\"}"
```

## Response Description

On success, returns `201` and the newly created Order object. Key fields include `id`, `price`, `discount`, `state`, `application_id/application_ids`, `package_id/package_ids`, `expired_at`, and time fields. New orders are usually `Pending`, followed by calling [Pay Order](https://platform.acedata.cloud/documents/platform-order-pay).

* `price` is the payable amount calculated by the server based on the package, site markup, and discounts; do not calculate it on the client.
* Returns `400` when the Package does not match the Application service or type.
* Free and system-managed Packages cannot be claimed independently through the public order API.
* Creating an order for an Application that does not belong to the current account will be rejected.

## Related APIs

* [Get Order List](https://platform.acedata.cloud/documents/platform-order-list)
* [Get Order Details](https://platform.acedata.cloud/documents/platform-order-detail)
* [Pay Order](https://platform.acedata.cloud/documents/platform-order-pay)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.