--- title: "Create a report" method: POST path: "/reports" tags: ["Reports"] --- # Create a report `POST /reports` ## Request - Base URL: `https://sandbox-api.paddle.com` - URL: `https://sandbox-api.paddle.com/reports` - Auth: HTTP bearer Creates a new report. Reports are created as `pending` initially while Paddle generates your report. They move to `ready` when they're ready to download. You can download a report when it's ready using the [get a CSV file for a report operation](https://developer.paddle.com/api-reference/reports/get-report-csv). If successful, your response includes a copy of the new report entity. ## Request body - union: Represents a report entity. - ReportAdjustmentsCreateModel: Entity when working with reports for adjustments or adjustment line items. - `type` 'adjustments' | 'adjustment_line_items', required: Type of report. - `filters` ReportFilterAdjustmentsCreate[]: Filter criteria for this report. If no `gte` filter for `updated_at` is passed, reports are filtered to include data updated in the last month. This means `updated_at` is greater than or equal to (`gte`) the same date and time one calendar month before the report was generated, so the window is between 28 and 31 days depending on the month. - `name` 'action' | 'currency_code' | 'status' | 'updated_at' - `operator` 'lt' | 'gte': Operator to use when filtering. - `value` union: Value to filter by. Check the allowed values descriptions for the `name` field to see valid values for a field. - AdjustmentStatus[] - AdjustmentAction[] - string, date-time: RFC 3339 datetime string. - string, date - string[] - string - ReportTransactionsCreateModel: Entity when working with reports for transaction or transaction line items. - `type` 'transactions' | 'transaction_line_items', required: Type of report. - `filters` ReportFilterTransactionsCreate[]: Filter criteria for this report. If no `gte` filter for `updated_at` is passed, reports are filtered to include data updated in the last month. This means `updated_at` is greater than or equal to (`gte`) the same date and time one calendar month before the report was generated, so the window is between 28 and 31 days depending on the month. - `name` 'collection_mode' | 'currency_code' | 'origin' | 'status' | 'updated_at': Field name to filter by. - `operator` 'lt' | 'gte': Operator to use when filtering. - `value` union: Value to filter by. Check the allowed values descriptions for the `name` field to see valid values for a field. - string[] - string - ReportProductsPricesCreateModel: Entity when working with a products and prices report. - `type` 'products_prices', required: Type of report. - `filters` ReportFilterProductsPricesCreate[]: Filter criteria for this report. `product_updated_at` and `price_updated_at` are defaulted independently: a field with no `gte` filter is filtered to include data updated in the last month, even when the other field has one. This means the field is set to greater than or equal to (`gte`) the same date and time one calendar month before the report was generated, so the window is between 28 and 31 days depending on the month. - `name` 'product_status' | 'price_status' | 'product_type' | 'price_type' | 'product_updated_at' | 'price_updated_at': Field name to filter by. - `operator` 'lt' | 'gte': Operator to use when filtering. - `value` union: Value to filter by. - string[] - string - ReportDiscountsCreateModel: Entity when working with a discounts report. - `type` 'discounts', required: Type of report. - `filters` ReportFilterDiscountsCreate[]: Filter criteria for this report. If no `gte` filter for `updated_at` is passed, reports are filtered to include data updated in the last month. This means `updated_at` is greater than or equal to (`gte`) the same date and time one calendar month before the report was generated, so the window is between 28 and 31 days depending on the month. - `name` 'type' | 'status' | 'updated_at': Field name to filter by. - `operator` 'lt' | 'gte': Operator to use when filtering. - `value` union: Value to filter by. Check the allowed values descriptions for the `name` field to see valid values for a field. - string[] - string - ReportBalanceCreateModel: Entity when working with a balance report. Deprecated. - `type` 'balance', required: Type of report. - `filters` ReportFilterBalanceCreate[]: Filter criteria for this report. If no `gte` filter for `updated_at` is passed, reports are filtered to include data updated in the last month. This means `updated_at` is greater than or equal to (`gte`) the same date and time one calendar month before the report was generated, so the window is between 28 and 31 days depending on the month. - `name` 'updated_at': Field name to filter by. - `operator` 'lt' | 'gte': Operator to use when filtering. - `value` union: Value to filter by. Check the allowed values descriptions for the `name` field to see valid values for a field. - string[] - string - ReportPayoutReconciliationCreateModel: Entity when working with a reconciliation report. - `type` 'payout_reconciliation', required: Type of report. - `filters` ReportFilterReconciliationCreate[]: Filter criteria for this report. If none of a `gte` filter for `transaction_updated_at`, a `remittance_reference` filter, or a `balance_movement_date` filter is passed, reports are filtered to include data updated in the last month. This means `transaction_updated_at` is greater than or equal to (`gte`) the same date and time one calendar month before the report was generated, so the window is between 28 and 31 days depending on the month. - `name` 'remittance_reference' | 'transaction_updated_at' | 'balance_movement_date' | 'balance_movement_type': Field name to filter by. - `operator` 'lt' | 'gte': Operator to use when filtering. - `value` union: Value to filter by. Check the allowed values descriptions for the `name` field to see valid values for a field. - string[] - string - BalanceMovementType[] - ReportCheckoutsCreateModel: Entity when working with a checkouts report. - `type` 'checkouts', required: Type of report. - `filters` ReportFilterCheckoutsCreate[]: Filter criteria for this report. If no `gte` filter for `checkout_created_at` is passed, reports are filtered to include checkouts created in the last month. This means `checkout_created_at` is greater than or equal to (`gte`) the same date and time one calendar month before the report was generated, so the window is between 28 and 31 days depending on the month. To filter by a specific date range, pass two `checkout_created_at` filters with `gte` and `lt` operators. - `name` 'checkout_created_at' | 'customer_country_code': Field name to filter by. - `operator` 'lt' | 'gte': Operator to use when filtering. - `value` union: Value to filter by. Check the allowed values descriptions for the `name` field to see valid values for a field. - string[] - string - ReportSubscriptionsCreateModel: Entity when working with a subscriptions report. - `type` 'subscriptions', required: Type of report. - `filters` ReportFilterSubscriptionsCreate[]: Filter criteria for this report. Subscriptions reports have no default date range. If you don't pass a `subscription_created_at` filter, reports include all your subscriptions. To filter by a specific date range, pass two `subscription_created_at` filters with `gte` and `lt` operators. - `name` 'subscription_status' | 'subscription_created_at' | 'customer_country_code' | 'subscription_scheduled_change_action': Field name to filter by. - `operator` 'lt' | 'gte': Operator to use when filtering. - `value` union: Value to filter by. Check the allowed values descriptions for the `name` field to see valid values for a field. - string[] - string - SubscriptionStatusFilter[] - SubscriptionScheduledChangeActionFilter[] ## Response `201` The request has succeeded and a new resource has been created as a result. - object - `data` union, required: Represents a report entity. - ReportAdjustmentsModel: Entity when working with reports for adjustments or adjustment line items. - `id` string, required: Unique Paddle ID for this entity. - `status` 'pending' | 'ready' | 'failed' | 'expired', required: Status of this report. Set automatically by Paddle. Reports are created as `pending` initially, then move to `ready` when they're available to download. - `rows` integer, nullable, required: Number of records in this report. `null` if the report is `pending`. - `expires_at` string, date-time, required: RFC 3339 datetime string. - `updated_at` string, date-time, required: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle. - `created_at` string, date-time, required: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle. - `type` 'adjustments' | 'adjustment_line_items', required: Type of report. - `filters` ReportFilterAdjustments[], required: Filter criteria for this report. If no `gte` filter for `updated_at` is passed, reports are filtered to include data updated in the last month. This means `updated_at` is greater than or equal to (`gte`) the same date and time one calendar month before the report was generated, so the window is between 28 and 31 days depending on the month. - `name` 'action' | 'currency_code' | 'status' | 'updated_at', required - `operator` 'lt' | 'gte', required: Operator to use when filtering. - `value` union, required: Value to filter by. Check the allowed values descriptions for the `name` field to see valid values for a field. - AdjustmentStatus[] - AdjustmentAction[] - string, date-time: RFC 3339 datetime string. - string, date - string[] - string - ReportTransactionsModel: Entity when working with reports for transaction or transaction line items. - `id` string, required: Unique Paddle ID for this entity. - `status` 'pending' | 'ready' | 'failed' | 'expired', required: Status of this report. Set automatically by Paddle. Reports are created as `pending` initially, then move to `ready` when they're available to download. - `rows` integer, nullable, required: Number of records in this report. `null` if the report is `pending`. - `expires_at` string, date-time, required: RFC 3339 datetime string. - `updated_at` string, date-time, required: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle. - `created_at` string, date-time, required: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle. - `type` 'transactions' | 'transaction_line_items', required: Type of report. - `filters` ReportFilterTransactions[], required: Filter criteria for this report. If no `gte` filter for `updated_at` is passed, reports are filtered to include data updated in the last month. This means `updated_at` is greater than or equal to (`gte`) the same date and time one calendar month before the report was generated, so the window is between 28 and 31 days depending on the month. - `name` 'collection_mode' | 'currency_code' | 'origin' | 'status' | 'updated_at', required: Field name to filter by. - `operator` 'lt' | 'gte', required: Operator to use when filtering. - `value` union, required: Value to filter by. Check the allowed values descriptions for the `name` field to see valid values for a field. - string[] - string - ReportProductsPricesModel: Entity when working with a products and prices report. - `id` string, required: Unique Paddle ID for this entity. - `status` 'pending' | 'ready' | 'failed' | 'expired', required: Status of this report. Set automatically by Paddle. Reports are created as `pending` initially, then move to `ready` when they're available to download. - `rows` integer, nullable, required: Number of records in this report. `null` if the report is `pending`. - `expires_at` string, date-time, required: RFC 3339 datetime string. - `updated_at` string, date-time, required: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle. - `created_at` string, date-time, required: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle. - `type` 'products_prices', required: Type of report. - `filters` ReportFilterProductsPrices[], required: Filter criteria for this report. `product_updated_at` and `price_updated_at` are defaulted independently: a field with no `gte` filter is filtered to include data updated in the last month, even when the other field has one. This means the field is set to greater than or equal to (`gte`) the same date and time one calendar month before the report was generated, so the window is between 28 and 31 days depending on the month. - `name` 'product_status' | 'price_status' | 'product_type' | 'price_type' | 'product_updated_at' | 'price_updated_at', required: Field name to filter by. - `operator` 'lt' | 'gte', required: Operator to use when filtering. - `value` union, required: Value to filter by. - string[] - string - ReportDiscountsModel: Entity when working with a discounts report. - `id` string, required: Unique Paddle ID for this entity. - `status` 'pending' | 'ready' | 'failed' | 'expired', required: Status of this report. Set automatically by Paddle. Reports are created as `pending` initially, then move to `ready` when they're available to download. - `rows` integer, nullable, required: Number of records in this report. `null` if the report is `pending`. - `expires_at` string, date-time, required: RFC 3339 datetime string. - `updated_at` string, date-time, required: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle. - `created_at` string, date-time, required: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle. - `type` 'discounts', required: Type of report. - `filters` ReportFilterDiscounts[], required: Filter criteria for this report. If no `gte` filter for `updated_at` is passed, reports are filtered to include data updated in the last month. This means `updated_at` is greater than or equal to (`gte`) the same date and time one calendar month before the report was generated, so the window is between 28 and 31 days depending on the month. - `name` 'type' | 'status' | 'updated_at', required: Field name to filter by. - `operator` 'lt' | 'gte', required: Operator to use when filtering. - `value` union, required: Value to filter by. Check the allowed values descriptions for the `name` field to see valid values for a field. - string[] - string - ReportBalanceModel: Entity when working with a balance report. Deprecated. - `id` string, required: Unique Paddle ID for this entity. - `status` 'pending' | 'ready' | 'failed' | 'expired', required: Status of this report. Set automatically by Paddle. Reports are created as `pending` initially, then move to `ready` when they're available to download. - `rows` integer, nullable, required: Number of records in this report. `null` if the report is `pending`. - `expires_at` string, date-time, required: RFC 3339 datetime string. - `updated_at` string, date-time, required: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle. - `created_at` string, date-time, required: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle. - `type` 'balance', required: Type of report. - `filters` ReportFilterBalance[], required: Filter criteria for this report. If no `gte` filter for `updated_at` is passed, reports are filtered to include data updated in the last month. This means `updated_at` is greater than or equal to (`gte`) the same date and time one calendar month before the report was generated, so the window is between 28 and 31 days depending on the month. - `name` 'updated_at', required: Field name to filter by. - `operator` 'lt' | 'gte', required: Operator to use when filtering. - `value` union, required: Value to filter by. Check the allowed values descriptions for the `name` field to see valid values for a field. - string[] - string - ReportPayoutReconciliationModel: Entity when working with a reconciliation report. - `id` string, required: Unique Paddle ID for this entity. - `status` 'pending' | 'ready' | 'failed' | 'expired', required: Status of this report. Set automatically by Paddle. Reports are created as `pending` initially, then move to `ready` when they're available to download. - `rows` integer, nullable, required: Number of records in this report. `null` if the report is `pending`. - `expires_at` string, date-time, required: RFC 3339 datetime string. - `updated_at` string, date-time, required: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle. - `created_at` string, date-time, required: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle. - `type` 'payout_reconciliation', required: Type of report. - `filters` ReportFilterReconciliation[], required: Filter criteria for this report. If none of a `gte` filter for `transaction_updated_at`, a `remittance_reference` filter, or a `balance_movement_date` filter is passed, reports are filtered to include data updated in the last month. This means `transaction_updated_at` is greater than or equal to (`gte`) the same date and time one calendar month before the report was generated, so the window is between 28 and 31 days depending on the month. - `name` 'remittance_reference' | 'transaction_updated_at' | 'balance_movement_date' | 'balance_movement_type', required: Field name to filter by. - `operator` 'lt' | 'gte', required: Operator to use when filtering. - `value` union, required: Value to filter by. Check the allowed values descriptions for the `name` field to see valid values for a field. - string[] - string - BalanceMovementType[] - ReportCheckoutsModel: Entity when working with a checkouts report. - `id` string, required: Unique Paddle ID for this entity. - `status` 'pending' | 'ready' | 'failed' | 'expired', required: Status of this report. Set automatically by Paddle. Reports are created as `pending` initially, then move to `ready` when they're available to download. - `rows` integer, nullable, required: Number of records in this report. `null` if the report is `pending`. - `expires_at` string, date-time, required: RFC 3339 datetime string. - `updated_at` string, date-time, required: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle. - `created_at` string, date-time, required: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle. - `type` 'checkouts', required: Type of report. - `filters` ReportFilterCheckouts[], required: Filter criteria for this report. If no `gte` filter for `checkout_created_at` is passed, reports are filtered to include checkouts created in the last month. This means `checkout_created_at` is greater than or equal to (`gte`) the same date and time one calendar month before the report was generated, so the window is between 28 and 31 days depending on the month. To filter by a specific date range, pass two `checkout_created_at` filters with `gte` and `lt` operators. - `name` 'checkout_created_at' | 'customer_country_code', required: Field name to filter by. - `operator` 'lt' | 'gte', required: Operator to use when filtering. - `value` union, required: Value to filter by. Check the allowed values descriptions for the `name` field to see valid values for a field. - string[] - string - ReportSubscriptionsModel: Entity when working with a subscriptions report. - `id` string, required: Unique Paddle ID for this entity. - `status` 'pending' | 'ready' | 'failed' | 'expired', required: Status of this report. Set automatically by Paddle. Reports are created as `pending` initially, then move to `ready` when they're available to download. - `rows` integer, nullable, required: Number of records in this report. `null` if the report is `pending`. - `expires_at` string, date-time, required: RFC 3339 datetime string. - `updated_at` string, date-time, required: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle. - `created_at` string, date-time, required: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle. - `type` 'subscriptions', required: Type of report. - `filters` ReportFilterSubscriptions[], required: Filter criteria for this report. Subscriptions reports have no default date range. If you don't pass a `subscription_created_at` filter, reports include all your subscriptions. To filter by a specific date range, pass two `subscription_created_at` filters with `gte` and `lt` operators. - `name` 'subscription_status' | 'subscription_created_at' | 'customer_country_code' | 'subscription_scheduled_change_action', required: Field name to filter by. - `operator` 'lt' | 'gte', required: Operator to use when filtering. - `value` union, required: Value to filter by. Check the allowed values descriptions for the `name` field to see valid values for a field. - string[] - string - SubscriptionStatusFilter[] - SubscriptionScheduledChangeActionFilter[] - `meta` Meta, required: Information about this response. - `request_id` string, required: Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request. ## Other responses - `default`: An unexpected error response. ## Changes - **2026-10-19** (v1) `4f35a8c6ea4d`: 1 breaking, 1 info - added `#/components/schemas/ReportSubscriptionsModel` to the `data` response property `oneOf` list for the response status `201` - added `#/components/schemas/ReportSubscriptionsCreateModel` to the request body `oneOf` list - **2026-07-09** (v1) `e1ac347eb3c5`: 1 breaking, 3 info - added `#/components/schemas/ReportCheckoutsModel` to the `data` response property `oneOf` list for the response status `201` - added `#/components/schemas/ReportCheckoutsCreateModel` to the request body `oneOf` list - added `#/components/schemas/Timestamp, subschema #1, subschema #2, subschema #4` to the `oneOf[subschema #1: Adjustments reports]/filters/items/value` request property `anyOf` list - added `#/components/schemas/Timestamp, subschema #1, subschema #2, subschema #4` to the `data/oneOf[subschema #1: Adjustments reports]/filters/items/value` response property `anyOf` list for the response status `201` - …earlier changes not shown [Operation history](https://skmtc.dev/paddlehq/apis/paddle-api/changes/reports/post.md) --- [API](https://skmtc.dev/paddlehq/apis/paddle-api.md) - [All operations](https://skmtc.dev/paddlehq/apis/paddle-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paddlehq/apis/paddle-api/revisions/bbc0c72039c8?raw)