docs(reports): document the on-demand refund transactions export (#159069)

[gergesfikry-ottu]

What

Documents the refund transactions export — an on-demand endpoint that builds a refund-only CSV/XLSX report, filtered by date, state, order, currency, or gateway, with full timezone control. It was previously undocumented, so merchants had no way to discover it or to know that its date filters are timezone-sensitive.

The endpoint is the generation half of a flow whose other two halves (List Reports, Download Report) were already documented on this page, so this extends docs/developers/reports.mdx rather than adding a new page: request a report → poll until finished → download.

Docs ticket: https://orbit.ottu.com/issues/159069
Source ticket: https://orbit.ottu.com/issues/159067 (backend change this documents)
Source PR: https://github.com/ottuco/core_backend/pull/424

Pages

• docs/developers/reports.mdx — new Generating a Refund Export section (~290 lines): endpoint, auth matrix, four-language quick implementation, async-generation warning, full query-parameter tables, a Timezones section with a worked example, parent-transaction filtering, response-field table, error table. Also updates the page intro, use cases, workflow diagram, and report-sources list to account for the third endpoint, and adds 5 FAQ entries and 3 best practices.
• sidebars.ts — "Refund Export" anchor added to the Reports category.

Contract documented

Surface	Detail
Endpoint	GET /b/api/v1/dashboard/refund-transactions/export/
Auth	Authorization: Api-Key <key> · Basic · Keycloak JWT Bearer
New request header	X-Timezone: <IANA name> — takes priority over ?timezone=
New query param	timezone — IANA name; sets both filter interpretation and rendered dates
Output params	file_format (csv/xlsx), fields, language
Filters	created_*, modified_*, state (refunded/refund_queued), order_no, product_type, currency_code, gateway_code, initiator, q
Response 201	id, status, type, file, size, file_format, records_amount, period, created_at, exported_at, username, report_type
Errors	400 invalid timezone / invalid date / invalid state · 401 · 403

Also fixed on this page

The two existing samples used -H "Api-Key: your_private_api_key". HasPrivateAPIKey reads the standard Authorization header via rest_framework_api_key's KeyParser (keyword Api-Key), and no API_KEY_CUSTOM_HEADER is configured — so the correct form is Authorization: Api-Key <key>, which is what docs/developers/payments/wallet/index.mdx already uses. Corrected both.

Verification

Every claim in the new section was checked against the running endpoint, not inferred. Three drafted statements were wrong and were corrected before commit:

• an unparseable date does not fall through unfiltered — it returns 400 {"created": ["Enter a valid date/time."]}, keyed on the filter's base name rather than the bound you sent
• an unsupported file_format is not rejected with 404 — it returns 201 and the value is stored as-is
• available_until is absent from this response; it is a with_available_until() queryset annotation applied by List Reports, not a stored field

The 201 example body is a captured response, not a hand-written one.

• npm run typecheck — passes
• npm run build — passes, [SUCCESS] Generated static files in "build". The six broken-anchor warnings it prints are pre-existing on other pages (glossary terms, checkout-api, wallet); none originates from /developers/reports/.
• Anchors added this PR (#generating-a-refund-export, #timezones, #worked-example, #filtering-by-order) all resolve.

Source of truth

Field names, enum values, and error strings taken verbatim from ottuco/core_backend@e1e5db763:

• contrib/dashboard/views.py:361-374 — endpoint, auth, permissions, refunded/refund_queued queryset
• contrib/dashboard/urls.py:23-25 — path
• utils/rest/views.py:154-193 — get_report_timezone (header-over-query precedence, 400 on invalid), async export(), file_format/fields/language
• core/payment/filters.py:99-197,354-372,398-478 — filters, state choices, parent-matching order_no/product_type, TimezoneAwareExportFilterMixin
• contrib/report/serializers.py:13-66 — response fields
• contrib/report/models.py:128-131 — ReportStatus values
• contrib/report/export/export_builders.py:154-161 + export/formatters.py:118 — report_timezone drives rendered dates
• contrib/report/managers.py:7-9 — available_until is an annotation

[gergesfikry-ottu]

Closing this — wrong audience. The endpoint is not merchant-facing and does not belong in the public docs.

ExportRefundTransactionsView is registered as @Schema.register(namespace="dashboard"), not public. In this codebase the api_docs namespace is the audience boundary: contrib/api_docs/hooks.py::preprocessing_filter_spec filters the schema by namespace, public is the merchant surface, and dashboard is an internal back-office surface served at /schema/dashboard/redoc/. Consistent with that, static/Ottu_API.yaml here — fetched from /schema/public — contains no /api/v1/dashboard/** paths at all.

I over-weighted the fact that the view accepts HasPrivateAPIKey and read it as a merchant integration path. That was the wrong inference: the namespace registration is the deliberate signal, and it says internal dashboard.

The backend fix this documented is unaffected and still shipping: ottuco/core_backend#424 (#159067). Its OpenAPI description lives in contrib/dashboard/schema.py, which is the correct home — the dashboard namespace renders for internal developers, so the X-Timezone / timezone contract is still documented, just to the right audience.

No changes here are being carried forward. Docs ticket #159069 closed as well.

[gergesfikry-ottu]

What

Documents the refund transactions export — an on-demand endpoint that builds a refund-only CSV/XLSX report, filtered by date, state, order, currency, or gateway, with full timezone control. It was previously undocumented, so merchants had no way to discover it or to know that its date filters are timezone-sensitive.

The endpoint is the generation half of a flow whose other two halves (List Reports, Download Report) were already documented on this page, so this extends docs/developers/reports.mdx rather than adding a new page: request a report → poll until finished → download.

Docs ticket: https://orbit.ottu.com/issues/159069
Source ticket: https://orbit.ottu.com/issues/159067 (backend change this documents)
Source PR: https://github.com/ottuco/core_backend/pull/424

Pages

• docs/developers/reports.mdx — new Generating a Refund Export section (~290 lines): endpoint, auth matrix, four-language quick implementation, async-generation warning, full query-parameter tables, a Timezones section with a worked example, parent-transaction filtering, response-field table, error table. Also updates the page intro, use cases, workflow diagram, and report-sources list to account for the third endpoint, and adds 5 FAQ entries and 3 best practices.
• sidebars.ts — "Refund Export" anchor added to the Reports category.

Contract documented

Surface	Detail
Endpoint	GET /b/api/v1/dashboard/refund-transactions/export/
Auth	Authorization: Api-Key <key> · Basic · Keycloak JWT Bearer
New request header	X-Timezone: <IANA name> — takes priority over ?timezone=
New query param	timezone — IANA name; sets both filter interpretation and rendered dates
Output params	file_format (csv/xlsx), fields, language
Filters	created_*, modified_*, state (refunded/refund_queued), order_no, product_type, currency_code, gateway_code, initiator, q
Response 201	id, status, type, file, size, file_format, records_amount, period, created_at, exported_at, username, report_type
Errors	400 invalid timezone / invalid date / invalid state · 401 · 403

Also fixed on this page

The two existing samples used -H "Api-Key: your_private_api_key". HasPrivateAPIKey reads the standard Authorization header via rest_framework_api_key's KeyParser (keyword Api-Key), and no API_KEY_CUSTOM_HEADER is configured — so the correct form is Authorization: Api-Key <key>, which is what docs/developers/payments/wallet/index.mdx already uses. Corrected both.

Verification

Every claim in the new section was checked against the running endpoint, not inferred. Three drafted statements were wrong and were corrected before commit:

• an unparseable date does not fall through unfiltered — it returns 400 {"created": ["Enter a valid date/time."]}, keyed on the filter's base name rather than the bound you sent
• an unsupported file_format is not rejected with 404 — it returns 201 and the value is stored as-is
• available_until is absent from this response; it is a with_available_until() queryset annotation applied by List Reports, not a stored field

The 201 example body is a captured response, not a hand-written one.

• npm run typecheck — passes
• npm run build — passes, [SUCCESS] Generated static files in "build". The six broken-anchor warnings it prints are pre-existing on other pages (glossary terms, checkout-api, wallet); none originates from /developers/reports/.
• Anchors added this PR (#generating-a-refund-export, #timezones, #worked-example, #filtering-by-order) all resolve.

Source of truth

Field names, enum values, and error strings taken verbatim from ottuco/core_backend@e1e5db763:

• contrib/dashboard/views.py:361-374 — endpoint, auth, permissions, refunded/refund_queued queryset
• contrib/dashboard/urls.py:23-25 — path
• utils/rest/views.py:154-193 — get_report_timezone (header-over-query precedence, 400 on invalid), async export(), file_format/fields/language
• core/payment/filters.py:99-197,354-372,398-478 — filters, state choices, parent-matching order_no/product_type, TimezoneAwareExportFilterMixin
• contrib/report/serializers.py:13-66 — response fields
• contrib/report/models.py:128-131 — ReportStatus values
• contrib/report/export/export_builders.py:154-161 + export/formatters.py:118 — report_timezone drives rendered dates
• contrib/report/managers.py:7-9 — available_until is an annotation

[gergesfikry-ottu]

Closing this — wrong audience. The endpoint is not merchant-facing and does not belong in the public docs.

ExportRefundTransactionsView is registered as @Schema.register(namespace="dashboard"), not public. In this codebase the api_docs namespace is the audience boundary: contrib/api_docs/hooks.py::preprocessing_filter_spec filters the schema by namespace, public is the merchant surface, and dashboard is an internal back-office surface served at /schema/dashboard/redoc/. Consistent with that, static/Ottu_API.yaml here — fetched from /schema/public — contains no /api/v1/dashboard/** paths at all.

I over-weighted the fact that the view accepts HasPrivateAPIKey and read it as a merchant integration path. That was the wrong inference: the namespace registration is the deliberate signal, and it says internal dashboard.

The backend fix this documented is unaffected and still shipping: ottuco/core_backend#424 (#159067). Its OpenAPI description lives in contrib/dashboard/schema.py, which is the correct home — the dashboard namespace renders for internal developers, so the X-Timezone / timezone contract is still documented, just to the right audience.

No changes here are being carried forward. Docs ticket #159069 closed as well.

[gergesfikry-ottu]

What

Documents the refund transactions export — an on-demand endpoint that builds a refund-only CSV/XLSX report, filtered by date, state, order, currency, or gateway, with full timezone control. It was previously undocumented, so merchants had no way to discover it or to know that its date filters are timezone-sensitive.

The endpoint is the generation half of a flow whose other two halves (List Reports, Download Report) were already documented on this page, so this extends docs/developers/reports.mdx rather than adding a new page: request a report → poll until finished → download.

Docs ticket: https://orbit.ottu.com/issues/159069
Source ticket: https://orbit.ottu.com/issues/159067 (backend change this documents)
Source PR: https://github.com/ottuco/core_backend/pull/424

Pages

• docs/developers/reports.mdx — new Generating a Refund Export section (~290 lines): endpoint, auth matrix, four-language quick implementation, async-generation warning, full query-parameter tables, a Timezones section with a worked example, parent-transaction filtering, response-field table, error table. Also updates the page intro, use cases, workflow diagram, and report-sources list to account for the third endpoint, and adds 5 FAQ entries and 3 best practices.
• sidebars.ts — "Refund Export" anchor added to the Reports category.

Contract documented

Surface	Detail
Endpoint	GET /b/api/v1/dashboard/refund-transactions/export/
Auth	Authorization: Api-Key <key> · Basic · Keycloak JWT Bearer
New request header	X-Timezone: <IANA name> — takes priority over ?timezone=
New query param	timezone — IANA name; sets both filter interpretation and rendered dates
Output params	file_format (csv/xlsx), fields, language
Filters	created_*, modified_*, state (refunded/refund_queued), order_no, product_type, currency_code, gateway_code, initiator, q
Response 201	id, status, type, file, size, file_format, records_amount, period, created_at, exported_at, username, report_type
Errors	400 invalid timezone / invalid date / invalid state · 401 · 403

Also fixed on this page

The two existing samples used -H "Api-Key: your_private_api_key". HasPrivateAPIKey reads the standard Authorization header via rest_framework_api_key's KeyParser (keyword Api-Key), and no API_KEY_CUSTOM_HEADER is configured — so the correct form is Authorization: Api-Key <key>, which is what docs/developers/payments/wallet/index.mdx already uses. Corrected both.

Verification

Every claim in the new section was checked against the running endpoint, not inferred. Three drafted statements were wrong and were corrected before commit:

• an unparseable date does not fall through unfiltered — it returns 400 {"created": ["Enter a valid date/time."]}, keyed on the filter's base name rather than the bound you sent
• an unsupported file_format is not rejected with 404 — it returns 201 and the value is stored as-is
• available_until is absent from this response; it is a with_available_until() queryset annotation applied by List Reports, not a stored field

The 201 example body is a captured response, not a hand-written one.

• npm run typecheck — passes
• npm run build — passes, [SUCCESS] Generated static files in "build". The six broken-anchor warnings it prints are pre-existing on other pages (glossary terms, checkout-api, wallet); none originates from /developers/reports/.
• Anchors added this PR (#generating-a-refund-export, #timezones, #worked-example, #filtering-by-order) all resolve.

Source of truth

Field names, enum values, and error strings taken verbatim from ottuco/core_backend@e1e5db763:

• contrib/dashboard/views.py:361-374 — endpoint, auth, permissions, refunded/refund_queued queryset
• contrib/dashboard/urls.py:23-25 — path
• utils/rest/views.py:154-193 — get_report_timezone (header-over-query precedence, 400 on invalid), async export(), file_format/fields/language
• core/payment/filters.py:99-197,354-372,398-478 — filters, state choices, parent-matching order_no/product_type, TimezoneAwareExportFilterMixin
• contrib/report/serializers.py:13-66 — response fields
• contrib/report/models.py:128-131 — ReportStatus values
• contrib/report/export/export_builders.py:154-161 + export/formatters.py:118 — report_timezone drives rendered dates
• contrib/report/managers.py:7-9 — available_until is an annotation

[gergesfikry-ottu]

Closing this — wrong audience. The endpoint is not merchant-facing and does not belong in the public docs.

ExportRefundTransactionsView is registered as @Schema.register(namespace="dashboard"), not public. In this codebase the api_docs namespace is the audience boundary: contrib/api_docs/hooks.py::preprocessing_filter_spec filters the schema by namespace, public is the merchant surface, and dashboard is an internal back-office surface served at /schema/dashboard/redoc/. Consistent with that, static/Ottu_API.yaml here — fetched from /schema/public — contains no /api/v1/dashboard/** paths at all.

I over-weighted the fact that the view accepts HasPrivateAPIKey and read it as a merchant integration path. That was the wrong inference: the namespace registration is the deliberate signal, and it says internal dashboard.

The backend fix this documented is unaffected and still shipping: ottuco/core_backend#424 (#159067). Its OpenAPI description lives in contrib/dashboard/schema.py, which is the correct home — the dashboard namespace renders for internal developers, so the X-Timezone / timezone contract is still documented, just to the right audience.

No changes here are being carried forward. Docs ticket #159069 closed as well.

[gergesfikry-ottu]

What

Documents the refund transactions export — an on-demand endpoint that builds a refund-only CSV/XLSX report, filtered by date, state, order, currency, or gateway, with full timezone control. It was previously undocumented, so merchants had no way to discover it or to know that its date filters are timezone-sensitive.

The endpoint is the generation half of a flow whose other two halves (List Reports, Download Report) were already documented on this page, so this extends docs/developers/reports.mdx rather than adding a new page: request a report → poll until finished → download.

Docs ticket: https://orbit.ottu.com/issues/159069
Source ticket: https://orbit.ottu.com/issues/159067 (backend change this documents)
Source PR: https://github.com/ottuco/core_backend/pull/424

Pages

• docs/developers/reports.mdx — new Generating a Refund Export section (~290 lines): endpoint, auth matrix, four-language quick implementation, async-generation warning, full query-parameter tables, a Timezones section with a worked example, parent-transaction filtering, response-field table, error table. Also updates the page intro, use cases, workflow diagram, and report-sources list to account for the third endpoint, and adds 5 FAQ entries and 3 best practices.
• sidebars.ts — "Refund Export" anchor added to the Reports category.

Contract documented

Surface	Detail
Endpoint	GET /b/api/v1/dashboard/refund-transactions/export/
Auth	Authorization: Api-Key <key> · Basic · Keycloak JWT Bearer
New request header	X-Timezone: <IANA name> — takes priority over ?timezone=
New query param	timezone — IANA name; sets both filter interpretation and rendered dates
Output params	file_format (csv/xlsx), fields, language
Filters	created_*, modified_*, state (refunded/refund_queued), order_no, product_type, currency_code, gateway_code, initiator, q
Response 201	id, status, type, file, size, file_format, records_amount, period, created_at, exported_at, username, report_type
Errors	400 invalid timezone / invalid date / invalid state · 401 · 403

Also fixed on this page

The two existing samples used -H "Api-Key: your_private_api_key". HasPrivateAPIKey reads the standard Authorization header via rest_framework_api_key's KeyParser (keyword Api-Key), and no API_KEY_CUSTOM_HEADER is configured — so the correct form is Authorization: Api-Key <key>, which is what docs/developers/payments/wallet/index.mdx already uses. Corrected both.

Verification

Every claim in the new section was checked against the running endpoint, not inferred. Three drafted statements were wrong and were corrected before commit:

• an unparseable date does not fall through unfiltered — it returns 400 {"created": ["Enter a valid date/time."]}, keyed on the filter's base name rather than the bound you sent
• an unsupported file_format is not rejected with 404 — it returns 201 and the value is stored as-is
• available_until is absent from this response; it is a with_available_until() queryset annotation applied by List Reports, not a stored field

The 201 example body is a captured response, not a hand-written one.

• npm run typecheck — passes
• npm run build — passes, [SUCCESS] Generated static files in "build". The six broken-anchor warnings it prints are pre-existing on other pages (glossary terms, checkout-api, wallet); none originates from /developers/reports/.
• Anchors added this PR (#generating-a-refund-export, #timezones, #worked-example, #filtering-by-order) all resolve.

Source of truth

Field names, enum values, and error strings taken verbatim from ottuco/core_backend@e1e5db763:

• contrib/dashboard/views.py:361-374 — endpoint, auth, permissions, refunded/refund_queued queryset
• contrib/dashboard/urls.py:23-25 — path
• utils/rest/views.py:154-193 — get_report_timezone (header-over-query precedence, 400 on invalid), async export(), file_format/fields/language
• core/payment/filters.py:99-197,354-372,398-478 — filters, state choices, parent-matching order_no/product_type, TimezoneAwareExportFilterMixin
• contrib/report/serializers.py:13-66 — response fields
• contrib/report/models.py:128-131 — ReportStatus values
• contrib/report/export/export_builders.py:154-161 + export/formatters.py:118 — report_timezone drives rendered dates
• contrib/report/managers.py:7-9 — available_until is an annotation

[gergesfikry-ottu]

Closing this — wrong audience. The endpoint is not merchant-facing and does not belong in the public docs.

ExportRefundTransactionsView is registered as @Schema.register(namespace="dashboard"), not public. In this codebase the api_docs namespace is the audience boundary: contrib/api_docs/hooks.py::preprocessing_filter_spec filters the schema by namespace, public is the merchant surface, and dashboard is an internal back-office surface served at /schema/dashboard/redoc/. Consistent with that, static/Ottu_API.yaml here — fetched from /schema/public — contains no /api/v1/dashboard/** paths at all.

I over-weighted the fact that the view accepts HasPrivateAPIKey and read it as a merchant integration path. That was the wrong inference: the namespace registration is the deliberate signal, and it says internal dashboard.

The backend fix this documented is unaffected and still shipping: ottuco/core_backend#424 (#159067). Its OpenAPI description lives in contrib/dashboard/schema.py, which is the correct home — the dashboard namespace renders for internal developers, so the X-Timezone / timezone contract is still documented, just to the right audience.

No changes here are being carried forward. Docs ticket #159069 closed as well.

[gergesfikry-ottu]

What

Documents the refund transactions export — an on-demand endpoint that builds a refund-only CSV/XLSX report, filtered by date, state, order, currency, or gateway, with full timezone control. It was previously undocumented, so merchants had no way to discover it or to know that its date filters are timezone-sensitive.

The endpoint is the generation half of a flow whose other two halves (List Reports, Download Report) were already documented on this page, so this extends docs/developers/reports.mdx rather than adding a new page: request a report → poll until finished → download.

Docs ticket: https://orbit.ottu.com/issues/159069
Source ticket: https://orbit.ottu.com/issues/159067 (backend change this documents)
Source PR: https://github.com/ottuco/core_backend/pull/424

Pages

• docs/developers/reports.mdx — new Generating a Refund Export section (~290 lines): endpoint, auth matrix, four-language quick implementation, async-generation warning, full query-parameter tables, a Timezones section with a worked example, parent-transaction filtering, response-field table, error table. Also updates the page intro, use cases, workflow diagram, and report-sources list to account for the third endpoint, and adds 5 FAQ entries and 3 best practices.
• sidebars.ts — "Refund Export" anchor added to the Reports category.

Contract documented

Surface	Detail
Endpoint	GET /b/api/v1/dashboard/refund-transactions/export/
Auth	Authorization: Api-Key <key> · Basic · Keycloak JWT Bearer
New request header	X-Timezone: <IANA name> — takes priority over ?timezone=
New query param	timezone — IANA name; sets both filter interpretation and rendered dates
Output params	file_format (csv/xlsx), fields, language
Filters	created_*, modified_*, state (refunded/refund_queued), order_no, product_type, currency_code, gateway_code, initiator, q
Response 201	id, status, type, file, size, file_format, records_amount, period, created_at, exported_at, username, report_type
Errors	400 invalid timezone / invalid date / invalid state · 401 · 403

Also fixed on this page

The two existing samples used -H "Api-Key: your_private_api_key". HasPrivateAPIKey reads the standard Authorization header via rest_framework_api_key's KeyParser (keyword Api-Key), and no API_KEY_CUSTOM_HEADER is configured — so the correct form is Authorization: Api-Key <key>, which is what docs/developers/payments/wallet/index.mdx already uses. Corrected both.

Verification

Every claim in the new section was checked against the running endpoint, not inferred. Three drafted statements were wrong and were corrected before commit:

• an unparseable date does not fall through unfiltered — it returns 400 {"created": ["Enter a valid date/time."]}, keyed on the filter's base name rather than the bound you sent
• an unsupported file_format is not rejected with 404 — it returns 201 and the value is stored as-is
• available_until is absent from this response; it is a with_available_until() queryset annotation applied by List Reports, not a stored field

The 201 example body is a captured response, not a hand-written one.

• npm run typecheck — passes
• npm run build — passes, [SUCCESS] Generated static files in "build". The six broken-anchor warnings it prints are pre-existing on other pages (glossary terms, checkout-api, wallet); none originates from /developers/reports/.
• Anchors added this PR (#generating-a-refund-export, #timezones, #worked-example, #filtering-by-order) all resolve.

Source of truth

Field names, enum values, and error strings taken verbatim from ottuco/core_backend@e1e5db763:

• contrib/dashboard/views.py:361-374 — endpoint, auth, permissions, refunded/refund_queued queryset
• contrib/dashboard/urls.py:23-25 — path
• utils/rest/views.py:154-193 — get_report_timezone (header-over-query precedence, 400 on invalid), async export(), file_format/fields/language
• core/payment/filters.py:99-197,354-372,398-478 — filters, state choices, parent-matching order_no/product_type, TimezoneAwareExportFilterMixin
• contrib/report/serializers.py:13-66 — response fields
• contrib/report/models.py:128-131 — ReportStatus values
• contrib/report/export/export_builders.py:154-161 + export/formatters.py:118 — report_timezone drives rendered dates
• contrib/report/managers.py:7-9 — available_until is an annotation

[gergesfikry-ottu]

Closing this — wrong audience. The endpoint is not merchant-facing and does not belong in the public docs.

ExportRefundTransactionsView is registered as @Schema.register(namespace="dashboard"), not public. In this codebase the api_docs namespace is the audience boundary: contrib/api_docs/hooks.py::preprocessing_filter_spec filters the schema by namespace, public is the merchant surface, and dashboard is an internal back-office surface served at /schema/dashboard/redoc/. Consistent with that, static/Ottu_API.yaml here — fetched from /schema/public — contains no /api/v1/dashboard/** paths at all.

I over-weighted the fact that the view accepts HasPrivateAPIKey and read it as a merchant integration path. That was the wrong inference: the namespace registration is the deliberate signal, and it says internal dashboard.

The backend fix this documented is unaffected and still shipping: ottuco/core_backend#424 (#159067). Its OpenAPI description lives in contrib/dashboard/schema.py, which is the correct home — the dashboard namespace renders for internal developers, so the X-Timezone / timezone contract is still documented, just to the right audience.

No changes here are being carried forward. Docs ticket #159069 closed as well.

[gergesfikry-ottu]

What

Documents the refund transactions export — an on-demand endpoint that builds a refund-only CSV/XLSX report, filtered by date, state, order, currency, or gateway, with full timezone control. It was previously undocumented, so merchants had no way to discover it or to know that its date filters are timezone-sensitive.

The endpoint is the generation half of a flow whose other two halves (List Reports, Download Report) were already documented on this page, so this extends docs/developers/reports.mdx rather than adding a new page: request a report → poll until finished → download.

Docs ticket: https://orbit.ottu.com/issues/159069
Source ticket: https://orbit.ottu.com/issues/159067 (backend change this documents)
Source PR: https://github.com/ottuco/core_backend/pull/424

Pages

• docs/developers/reports.mdx — new Generating a Refund Export section (~290 lines): endpoint, auth matrix, four-language quick implementation, async-generation warning, full query-parameter tables, a Timezones section with a worked example, parent-transaction filtering, response-field table, error table. Also updates the page intro, use cases, workflow diagram, and report-sources list to account for the third endpoint, and adds 5 FAQ entries and 3 best practices.
• sidebars.ts — "Refund Export" anchor added to the Reports category.

Contract documented

Surface	Detail
Endpoint	GET /b/api/v1/dashboard/refund-transactions/export/
Auth	Authorization: Api-Key <key> · Basic · Keycloak JWT Bearer
New request header	X-Timezone: <IANA name> — takes priority over ?timezone=
New query param	timezone — IANA name; sets both filter interpretation and rendered dates
Output params	file_format (csv/xlsx), fields, language
Filters	created_*, modified_*, state (refunded/refund_queued), order_no, product_type, currency_code, gateway_code, initiator, q
Response 201	id, status, type, file, size, file_format, records_amount, period, created_at, exported_at, username, report_type
Errors	400 invalid timezone / invalid date / invalid state · 401 · 403

Also fixed on this page

The two existing samples used -H "Api-Key: your_private_api_key". HasPrivateAPIKey reads the standard Authorization header via rest_framework_api_key's KeyParser (keyword Api-Key), and no API_KEY_CUSTOM_HEADER is configured — so the correct form is Authorization: Api-Key <key>, which is what docs/developers/payments/wallet/index.mdx already uses. Corrected both.

Verification

Every claim in the new section was checked against the running endpoint, not inferred. Three drafted statements were wrong and were corrected before commit:

• an unparseable date does not fall through unfiltered — it returns 400 {"created": ["Enter a valid date/time."]}, keyed on the filter's base name rather than the bound you sent
• an unsupported file_format is not rejected with 404 — it returns 201 and the value is stored as-is
• available_until is absent from this response; it is a with_available_until() queryset annotation applied by List Reports, not a stored field

The 201 example body is a captured response, not a hand-written one.

• npm run typecheck — passes
• npm run build — passes, [SUCCESS] Generated static files in "build". The six broken-anchor warnings it prints are pre-existing on other pages (glossary terms, checkout-api, wallet); none originates from /developers/reports/.
• Anchors added this PR (#generating-a-refund-export, #timezones, #worked-example, #filtering-by-order) all resolve.

Source of truth

Field names, enum values, and error strings taken verbatim from ottuco/core_backend@e1e5db763:

• contrib/dashboard/views.py:361-374 — endpoint, auth, permissions, refunded/refund_queued queryset
• contrib/dashboard/urls.py:23-25 — path
• utils/rest/views.py:154-193 — get_report_timezone (header-over-query precedence, 400 on invalid), async export(), file_format/fields/language
• core/payment/filters.py:99-197,354-372,398-478 — filters, state choices, parent-matching order_no/product_type, TimezoneAwareExportFilterMixin
• contrib/report/serializers.py:13-66 — response fields
• contrib/report/models.py:128-131 — ReportStatus values
• contrib/report/export/export_builders.py:154-161 + export/formatters.py:118 — report_timezone drives rendered dates
• contrib/report/managers.py:7-9 — available_until is an annotation

[gergesfikry-ottu]

Closing this — wrong audience. The endpoint is not merchant-facing and does not belong in the public docs.

ExportRefundTransactionsView is registered as @Schema.register(namespace="dashboard"), not public. In this codebase the api_docs namespace is the audience boundary: contrib/api_docs/hooks.py::preprocessing_filter_spec filters the schema by namespace, public is the merchant surface, and dashboard is an internal back-office surface served at /schema/dashboard/redoc/. Consistent with that, static/Ottu_API.yaml here — fetched from /schema/public — contains no /api/v1/dashboard/** paths at all.

I over-weighted the fact that the view accepts HasPrivateAPIKey and read it as a merchant integration path. That was the wrong inference: the namespace registration is the deliberate signal, and it says internal dashboard.

The backend fix this documented is unaffected and still shipping: ottuco/core_backend#424 (#159067). Its OpenAPI description lives in contrib/dashboard/schema.py, which is the correct home — the dashboard namespace renders for internal developers, so the X-Timezone / timezone contract is still documented, just to the right audience.

No changes here are being carried forward. Docs ticket #159069 closed as well.

[gergesfikry-ottu]

What

Documents the refund transactions export — an on-demand endpoint that builds a refund-only CSV/XLSX report, filtered by date, state, order, currency, or gateway, with full timezone control. It was previously undocumented, so merchants had no way to discover it or to know that its date filters are timezone-sensitive.

The endpoint is the generation half of a flow whose other two halves (List Reports, Download Report) were already documented on this page, so this extends docs/developers/reports.mdx rather than adding a new page: request a report → poll until finished → download.

Docs ticket: https://orbit.ottu.com/issues/159069
Source ticket: https://orbit.ottu.com/issues/159067 (backend change this documents)
Source PR: https://github.com/ottuco/core_backend/pull/424

Pages

• docs/developers/reports.mdx — new Generating a Refund Export section (~290 lines): endpoint, auth matrix, four-language quick implementation, async-generation warning, full query-parameter tables, a Timezones section with a worked example, parent-transaction filtering, response-field table, error table. Also updates the page intro, use cases, workflow diagram, and report-sources list to account for the third endpoint, and adds 5 FAQ entries and 3 best practices.
• sidebars.ts — "Refund Export" anchor added to the Reports category.

Contract documented

Surface	Detail
Endpoint	GET /b/api/v1/dashboard/refund-transactions/export/
Auth	Authorization: Api-Key <key> · Basic · Keycloak JWT Bearer
New request header	X-Timezone: <IANA name> — takes priority over ?timezone=
New query param	timezone — IANA name; sets both filter interpretation and rendered dates
Output params	file_format (csv/xlsx), fields, language
Filters	created_*, modified_*, state (refunded/refund_queued), order_no, product_type, currency_code, gateway_code, initiator, q
Response 201	id, status, type, file, size, file_format, records_amount, period, created_at, exported_at, username, report_type
Errors	400 invalid timezone / invalid date / invalid state · 401 · 403

Also fixed on this page

The two existing samples used -H "Api-Key: your_private_api_key". HasPrivateAPIKey reads the standard Authorization header via rest_framework_api_key's KeyParser (keyword Api-Key), and no API_KEY_CUSTOM_HEADER is configured — so the correct form is Authorization: Api-Key <key>, which is what docs/developers/payments/wallet/index.mdx already uses. Corrected both.

Verification

Every claim in the new section was checked against the running endpoint, not inferred. Three drafted statements were wrong and were corrected before commit:

• an unparseable date does not fall through unfiltered — it returns 400 {"created": ["Enter a valid date/time."]}, keyed on the filter's base name rather than the bound you sent
• an unsupported file_format is not rejected with 404 — it returns 201 and the value is stored as-is
• available_until is absent from this response; it is a with_available_until() queryset annotation applied by List Reports, not a stored field

The 201 example body is a captured response, not a hand-written one.

• npm run typecheck — passes
• npm run build — passes, [SUCCESS] Generated static files in "build". The six broken-anchor warnings it prints are pre-existing on other pages (glossary terms, checkout-api, wallet); none originates from /developers/reports/.
• Anchors added this PR (#generating-a-refund-export, #timezones, #worked-example, #filtering-by-order) all resolve.

Source of truth

Field names, enum values, and error strings taken verbatim from ottuco/core_backend@e1e5db763:

• contrib/dashboard/views.py:361-374 — endpoint, auth, permissions, refunded/refund_queued queryset
• contrib/dashboard/urls.py:23-25 — path
• utils/rest/views.py:154-193 — get_report_timezone (header-over-query precedence, 400 on invalid), async export(), file_format/fields/language
• core/payment/filters.py:99-197,354-372,398-478 — filters, state choices, parent-matching order_no/product_type, TimezoneAwareExportFilterMixin
• contrib/report/serializers.py:13-66 — response fields
• contrib/report/models.py:128-131 — ReportStatus values
• contrib/report/export/export_builders.py:154-161 + export/formatters.py:118 — report_timezone drives rendered dates
• contrib/report/managers.py:7-9 — available_until is an annotation

[gergesfikry-ottu]

Closing this — wrong audience. The endpoint is not merchant-facing and does not belong in the public docs.

ExportRefundTransactionsView is registered as @Schema.register(namespace="dashboard"), not public. In this codebase the api_docs namespace is the audience boundary: contrib/api_docs/hooks.py::preprocessing_filter_spec filters the schema by namespace, public is the merchant surface, and dashboard is an internal back-office surface served at /schema/dashboard/redoc/. Consistent with that, static/Ottu_API.yaml here — fetched from /schema/public — contains no /api/v1/dashboard/** paths at all.

I over-weighted the fact that the view accepts HasPrivateAPIKey and read it as a merchant integration path. That was the wrong inference: the namespace registration is the deliberate signal, and it says internal dashboard.

The backend fix this documented is unaffected and still shipping: ottuco/core_backend#424 (#159067). Its OpenAPI description lives in contrib/dashboard/schema.py, which is the correct home — the dashboard namespace renders for internal developers, so the X-Timezone / timezone contract is still documented, just to the right audience.

No changes here are being carried forward. Docs ticket #159069 closed as well.

[gergesfikry-ottu]

What

Documents the refund transactions export — an on-demand endpoint that builds a refund-only CSV/XLSX report, filtered by date, state, order, currency, or gateway, with full timezone control. It was previously undocumented, so merchants had no way to discover it or to know that its date filters are timezone-sensitive.

The endpoint is the generation half of a flow whose other two halves (List Reports, Download Report) were already documented on this page, so this extends docs/developers/reports.mdx rather than adding a new page: request a report → poll until finished → download.

Docs ticket: https://orbit.ottu.com/issues/159069
Source ticket: https://orbit.ottu.com/issues/159067 (backend change this documents)
Source PR: https://github.com/ottuco/core_backend/pull/424

Pages

• docs/developers/reports.mdx — new Generating a Refund Export section (~290 lines): endpoint, auth matrix, four-language quick implementation, async-generation warning, full query-parameter tables, a Timezones section with a worked example, parent-transaction filtering, response-field table, error table. Also updates the page intro, use cases, workflow diagram, and report-sources list to account for the third endpoint, and adds 5 FAQ entries and 3 best practices.
• sidebars.ts — "Refund Export" anchor added to the Reports category.

Contract documented

Surface	Detail
Endpoint	GET /b/api/v1/dashboard/refund-transactions/export/
Auth	Authorization: Api-Key <key> · Basic · Keycloak JWT Bearer
New request header	X-Timezone: <IANA name> — takes priority over ?timezone=
New query param	timezone — IANA name; sets both filter interpretation and rendered dates
Output params	file_format (csv/xlsx), fields, language
Filters	created_*, modified_*, state (refunded/refund_queued), order_no, product_type, currency_code, gateway_code, initiator, q
Response 201	id, status, type, file, size, file_format, records_amount, period, created_at, exported_at, username, report_type
Errors	400 invalid timezone / invalid date / invalid state · 401 · 403

Also fixed on this page

The two existing samples used -H "Api-Key: your_private_api_key". HasPrivateAPIKey reads the standard Authorization header via rest_framework_api_key's KeyParser (keyword Api-Key), and no API_KEY_CUSTOM_HEADER is configured — so the correct form is Authorization: Api-Key <key>, which is what docs/developers/payments/wallet/index.mdx already uses. Corrected both.

Verification

Every claim in the new section was checked against the running endpoint, not inferred. Three drafted statements were wrong and were corrected before commit:

• an unparseable date does not fall through unfiltered — it returns 400 {"created": ["Enter a valid date/time."]}, keyed on the filter's base name rather than the bound you sent
• an unsupported file_format is not rejected with 404 — it returns 201 and the value is stored as-is
• available_until is absent from this response; it is a with_available_until() queryset annotation applied by List Reports, not a stored field

The 201 example body is a captured response, not a hand-written one.

• npm run typecheck — passes
• npm run build — passes, [SUCCESS] Generated static files in "build". The six broken-anchor warnings it prints are pre-existing on other pages (glossary terms, checkout-api, wallet); none originates from /developers/reports/.
• Anchors added this PR (#generating-a-refund-export, #timezones, #worked-example, #filtering-by-order) all resolve.

Source of truth

Field names, enum values, and error strings taken verbatim from ottuco/core_backend@e1e5db763:

• contrib/dashboard/views.py:361-374 — endpoint, auth, permissions, refunded/refund_queued queryset
• contrib/dashboard/urls.py:23-25 — path
• utils/rest/views.py:154-193 — get_report_timezone (header-over-query precedence, 400 on invalid), async export(), file_format/fields/language
• core/payment/filters.py:99-197,354-372,398-478 — filters, state choices, parent-matching order_no/product_type, TimezoneAwareExportFilterMixin
• contrib/report/serializers.py:13-66 — response fields
• contrib/report/models.py:128-131 — ReportStatus values
• contrib/report/export/export_builders.py:154-161 + export/formatters.py:118 — report_timezone drives rendered dates
• contrib/report/managers.py:7-9 — available_until is an annotation

[gergesfikry-ottu]

Closing this — wrong audience. The endpoint is not merchant-facing and does not belong in the public docs.

ExportRefundTransactionsView is registered as @Schema.register(namespace="dashboard"), not public. In this codebase the api_docs namespace is the audience boundary: contrib/api_docs/hooks.py::preprocessing_filter_spec filters the schema by namespace, public is the merchant surface, and dashboard is an internal back-office surface served at /schema/dashboard/redoc/. Consistent with that, static/Ottu_API.yaml here — fetched from /schema/public — contains no /api/v1/dashboard/** paths at all.

I over-weighted the fact that the view accepts HasPrivateAPIKey and read it as a merchant integration path. That was the wrong inference: the namespace registration is the deliberate signal, and it says internal dashboard.

The backend fix this documented is unaffected and still shipping: ottuco/core_backend#424 (#159067). Its OpenAPI description lives in contrib/dashboard/schema.py, which is the correct home — the dashboard namespace renders for internal developers, so the X-Timezone / timezone contract is still documented, just to the right audience.

No changes here are being carried forward. Docs ticket #159069 closed as well.