<!--
{
  "availability" : [
    "Apple Ads Platform API: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Apple-Ads-Platform-API",
  "identifier" : "/documentation/Apple-Ads-Platform-API/POST-shared-budgets-query",
  "metadataVersion" : "0.1.0",
  "role" : "Web Service Endpoint",
  "symbol" : {
    "kind" : "Web Service Endpoint",
    "modules" : [
      "Apple Ads Platform API"
    ],
    "preciseIdentifier" : "rest:apple-ads-platform-api:post:shared-budgets-query"
  },
  "title" : "Query Budget Orders"
}
-->

# Query Budget Orders

Returns a filtered, sorted, and paginated list of budget orders.

## Discussion

This endpoint finds budget orders by name, status, or date range, or retrieves them across an ad account. Narrow and order the result set with `filters`, `sorting`, and `pagination`.

See [`QueryFilterOperator`](/documentation/Apple-Ads-Platform-API/QueryFilterOperator) for the full set of supported comparison operators.

### Filterable Fields

|Field                |Type                   |Operators                                                                                               |Sortable|Description                                                                                                                                                    |
|---------------------|:---------------------:|:------------------------------------------------------------------------------------------------------:|:------:|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
|`deleted`            |boolean                |`EQUALS`, `IN`                                                                                          |        |Whether the budget order has been soft-deleted.                                                                                                                |
|`id`                 |integer                |`EQUALS`, `IN`                                                                                          |        |System-assigned unique identifier for the budget order.                                                                                                        |
|`name`               |string                 |`EQUALS`, `IN`, `LIKE`, `STARTS_WITH`, `ENDS_WITH`                                                      |Yes     |The budget order’s display name.                                                                                                                               |
|`orgId`              |integer                |`EQUALS`                                                                                                |        |The organization that owns the budget order.                                                                                                                   |
|`adAccountIds`       |array of integers      |`EQUALS`, `IN`                                                                                          |        |The ad accounts the budget order is assigned to.                                                                                                               |
|`systemStatus`       |string (enum)          |`EQUALS`, `IN`                                                                                          |        |The budget order’s current status. See <doc://com.apple.apple-ads-platform-api/documentation/Apple-Ads-Platform-API/BudgetSystemStatus>.                       |
|`systemStatusReasons`|array of strings (enum)|`CONTAINS_ANY`, `CONTAINS_ALL`, `NOT_CONTAINS_ANY`, `NOT_CONTAINS_ALL`, `IS_NULL`, `IS_NOT_NULL`        |        |Reasons contributing to the current `systemStatus`. See <doc://com.apple.apple-ads-platform-api/documentation/Apple-Ads-Platform-API/BudgetSystemStatusReason>.|
|`startTime`          |string (date-time)     |`EQUALS`, `NOT_EQUALS`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL_TO`, `LESS_THAN`, `LESS_THAN_OR_EQUAL_TO`|        |The budget order’s scheduled start date and time.                                                                                                              |
|`endTime`            |string (date-time)     |`EQUALS`, `NOT_EQUALS`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL_TO`, `LESS_THAN`, `LESS_THAN_OR_EQUAL_TO`|        |The budget order’s scheduled end date and time.                                                                                                                |
|`creationTime`       |string (date-time)     |`EQUALS`, `NOT_EQUALS`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL_TO`, `LESS_THAN`, `LESS_THAN_OR_EQUAL_TO`|        |Timestamp when the budget order was created.                                                                                                                   |
|`modificationTime`   |string (date-time)     |`EQUALS`, `NOT_EQUALS`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL_TO`, `LESS_THAN`, `LESS_THAN_OR_EQUAL_TO`|        |Timestamp of the last modification to the budget order.                                                                                                        |

The `value` and `invoiceDetail` fields aren’t filterable. The request body is a [`QueryRequest`](/documentation/Apple-Ads-Platform-API/QueryRequest) composed of [`QueryFilter`](/documentation/Apple-Ads-Platform-API/QueryFilter) conditions and [`QuerySort`](/documentation/Apple-Ads-Platform-API/QuerySort) directives ([`QuerySortOrder`](/documentation/Apple-Ads-Platform-API/QuerySortOrder)), controlled by [`QueryPagination`](/documentation/Apple-Ads-Platform-API/QueryPagination).

## Payload Examples

**Query Budget Orders:**

### Request

Query all active budget orders for an ad account, sorted by name.

```json
{
 "filters": [
   {
     "field": "deleted",
     "operator": "EQUALS",
     "value": false
   }
 ],
 "sorting": [
   {
     "field": "name",
     "order": "ASC"
   }
 ],
 "pagination": {
   "offset": 0,
   "pageSize": 20,
   "fetchTotalCount": true
 }
}
```

### Response

```json
{
 "result": [
   {
     "id": 777890001,
     "name": "AwayFinder - Q3 2025 Budget",
     "orgId": 555666777,
     "startTime": "2025-07-01T00:00:00.000",
     "endTime": "2025-09-30T23:59:59.000",
     "value": {
       "amount": "20000.00",
       "currency": "USD"
     },
     "adAccountIds": [
       123456789
     ],
     "systemStatus": "ACTIVE",
     "systemStatusReasons": [],
     "invoiceDetail": {
       "orderNumber": "PO-2025-Q3",
       "clientName": "AwayFinder Inc.",
       "billingEmail": "billing@awayfinder.com"
     },
     "deleted": false,
     "creationTime": "2025-06-01T10:00:00.000",
     "modificationTime": "2025-06-01T10:00:00.000"
   },
   {
     "id": 777890002,
     "name": "AwayFinder - Q4 2025 Budget",
     "orgId": 555666777,
     "startTime": "2025-10-01T00:00:00.000",
     "endTime": "2025-12-31T23:59:59.000",
     "value": {
       "amount": "25000.00",
       "currency": "USD"
     },
     "adAccountIds": [
       123456789
     ],
     "systemStatus": "INACTIVE",
     "systemStatusReasons": [
       "SCHEDULE_PENDING"
     ],
     "invoiceDetail": {
       "orderNumber": "PO-2025-Q4",
       "clientName": "AwayFinder Inc.",
       "billingEmail": "billing@awayfinder.com"
     },
     "deleted": false,
     "creationTime": "2025-06-01T10:30:00.000",
     "modificationTime": "2025-06-01T10:30:00.000"
   }
 ],
 "pagination": {
   "totalCount": 2,
   "offset": 0,
   "pageSize": 20
 }
}
```

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)