{ "openapi": "3.0.3", "info": { "title": "Coritra API", "version": "1.0.0" }, "security": [ { "bearerAuth": [] } ], "paths": { "/api/v1/attributions": { "get": { "operationId": "getAttributions", "summary": "List attributions", "tags": [ "Attributions" ], "parameters": [ { "name": "ids", "in": "query", "description": "Filter by attribution IDs", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": true }, { "name": "partner_ids", "in": "query", "description": "Filter by partner IDs", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": true }, { "name": "workspace_ids", "in": "query", "description": "Filter by workspace IDs", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": true }, { "name": "page", "in": "query", "description": "Page number for pagination (default: 1)", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "description": "Number of items per page for pagination (default: 10)", "required": false, "schema": { "type": "integer", "default": 10 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_attributions_response" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } } } }, "post": { "operationId": "createAttribution", "summary": "Create an attribution", "tags": [ "Attributions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_attribution_request" } } } }, "responses": { "201": { "description": "Attribution created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_attribution_response" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "404": { "description": "Attribution schema or partner not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } } } } }, "/api/v1/attributions/stats": { "get": { "operationId": "getAttributionStats", "summary": "Get attribution statistics", "tags": [ "Attributions" ], "parameters": [ { "name": "from", "in": "query", "description": "Start of the period (inclusive), ISO 8601", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "description": "End of the period (exclusive), ISO 8601", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "granularity", "in": "query", "description": "Bucket size for the time series", "required": true, "schema": { "$ref": "#/components/schemas/attribution_stats_granularity" } }, { "name": "partner_ids", "in": "query", "description": "Filter by partner IDs", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": true }, { "name": "workspace_ids", "in": "query", "description": "Filter by workspace IDs", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_attribution_stats_response" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } } } } }, "/api/v1/attributions/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Attribution ID", "schema": { "type": "string", "format": "uuid" } } ], "delete": { "operationId": "cancelAttribution", "summary": "Cancel an attribution", "tags": [ "Attributions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cancel_attribution_request" } } } }, "responses": { "200": { "description": "Attribution cancelled successfully" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "404": { "description": "Attribution not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } } } } }, "/api/v1/attribution-schemas": { "get": { "operationId": "getAttributionSchemas", "summary": "List attribution schemas", "tags": [ "AttributionSchemas" ], "parameters": [ { "name": "ids", "in": "query", "description": "Filter by attribution schema IDs", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": true }, { "name": "customer_ids", "in": "query", "description": "Filter by customer IDs", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": true }, { "name": "workspace_ids", "in": "query", "description": "Filter by workspace IDs", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": true }, { "name": "name", "in": "query", "description": "Filter by schema name (case-insensitive substring match)", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number for pagination (default: 1)", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "description": "Number of items per page for pagination (default: 10)", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_attribution_schemas_response" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } } } }, "post": { "operationId": "createAttributionSchema", "summary": "Create an attribution schema", "tags": [ "AttributionSchemas" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_attribution_schema_request" } } } }, "responses": { "201": { "description": "Attribution schema created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_attribution_schema_response" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } } } } }, "/api/v1/partners": { "get": { "operationId": "getPartners", "summary": "List partners", "tags": [ "Partners" ], "parameters": [ { "name": "ids", "in": "query", "description": "Filter by partner IDs", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": true }, { "name": "customer_ids", "in": "query", "description": "Filter by customer IDs", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": true }, { "name": "workspace_ids", "in": "query", "description": "Filter by workspace IDs", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": true }, { "name": "name", "in": "query", "description": "Filter by partner name (case-insensitive substring match)", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number for pagination (default: 1)", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "description": "Number of items per page for pagination (default: 10)", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_partners_response" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } } } }, "post": { "operationId": "createPartner", "summary": "Create a partner", "tags": [ "Partners" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_partner_request" } } } }, "responses": { "201": { "description": "Partner created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_partner_response" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } } } } }, "/api/v1/partners/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Partner ID", "schema": { "type": "string", "format": "uuid" } } ], "patch": { "operationId": "updatePartner", "summary": "Update a partner", "tags": [ "Partners" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/update_partner_request" } } } }, "responses": { "200": { "description": "Partner updated successfully" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "404": { "description": "Partner not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } } } } }, "/api/v1/commission-formulas": { "get": { "operationId": "getCommissionFormulas", "summary": "List commission formulas", "tags": [ "CommissionFormulas" ], "parameters": [ { "name": "ids", "in": "query", "description": "Filter by commission formula IDs", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": true }, { "name": "customer_ids", "in": "query", "description": "Filter by customer IDs", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": true }, { "name": "partner_ids", "in": "query", "description": "Filter by partner IDs", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": true }, { "name": "workspace_ids", "in": "query", "description": "Filter by workspace IDs", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": true }, { "name": "active_at", "in": "query", "description": "Filter formulas active at the given ISO 8601 date-time", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "page", "in": "query", "description": "Page number for pagination (default: 1)", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "description": "Number of items per page for pagination (default: 10)", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_commission_formulas_response" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } } } }, "post": { "operationId": "createCommissionFormula", "summary": "Create a commission formula", "tags": [ "CommissionFormulas" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_commission_formula_request" } } } }, "responses": { "201": { "description": "Commission formula created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_commission_formula_response" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } } } } }, "/api/v1/commission-formulas/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Commission formula ID", "schema": { "type": "string", "format": "uuid" } } ], "patch": { "operationId": "updateCommissionFormula", "summary": "Update a commission formula", "tags": [ "CommissionFormulas" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/update_commission_formula_request" } } } }, "responses": { "200": { "description": "Commission formula updated successfully" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "404": { "description": "Commission formula not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } } } } }, "/api/v1/commissions": { "get": { "operationId": "getCommissions", "summary": "List commissions", "tags": [ "Commissions" ], "parameters": [ { "name": "ids", "in": "query", "description": "Filter by commission IDs", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": true }, { "name": "partner_ids", "in": "query", "description": "Filter by partner IDs", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": true }, { "name": "attribution_ids", "in": "query", "description": "Filter by attribution IDs", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": true }, { "name": "workspace_ids", "in": "query", "description": "Filter by workspace IDs", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": true }, { "name": "page", "in": "query", "description": "Page number for pagination (default: 1)", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "description": "Number of items per page for pagination (default: 10)", "required": false, "schema": { "type": "integer", "default": 10 } }, { "name": "settlement_status", "in": "query", "description": "Filter by settlement status", "required": false, "schema": { "type": "string", "enum": [ "unsettled", "pending_settlement", "settled" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_commissions_response" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/commissions/stats": { "get": { "operationId": "getCommissionStats", "summary": "Get commission statistics", "tags": [ "Commissions" ], "parameters": [ { "name": "from", "in": "query", "description": "Start of the period (inclusive), ISO 8601", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "description": "End of the period (exclusive), ISO 8601", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "granularity", "in": "query", "description": "Bucket size for the time series", "required": true, "schema": { "$ref": "#/components/schemas/commission_stats_granularity" } }, { "name": "partner_ids", "in": "query", "description": "Filter by partner IDs", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": true }, { "name": "workspace_ids", "in": "query", "description": "Filter by workspace IDs", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_commission_stats_response" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/settlements": { "get": { "operationId": "getSettlements", "summary": "List settlements", "tags": [ "Settlements" ], "parameters": [ { "name": "ids", "in": "query", "description": "Filter by settlement IDs", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": true }, { "name": "partner_ids", "in": "query", "description": "Filter by partner IDs", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": true }, { "name": "workspace_ids", "in": "query", "description": "Filter by workspace IDs", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": true }, { "name": "commission_ids", "in": "query", "description": "Filter by commission IDs included in the settlement", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": true }, { "name": "page", "in": "query", "description": "Page number for pagination (default: 1)", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "description": "Number of items per page for pagination (default: 10)", "required": false, "schema": { "type": "integer", "default": 10 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_settlements_response" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } } } }, "post": { "operationId": "createSettlement", "summary": "Create a settlement", "description": "Computes the settlement amount for the given commissions (actual amount minus already settled amount) and persists a draft settlement.", "tags": [ "Settlements" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_settlement_request" } } } }, "responses": { "201": { "description": "Settlement created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_settlement_response" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } } } } }, "/api/v1/settlements/{id}/approve": { "post": { "operationId": "approveSettlement", "summary": "Approve a settlement", "description": "Transitions a Draft settlement to AwaitingReport. The report must be linked before billing can proceed.", "tags": [ "Settlements" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the settlement to approve", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Settlement approved successfully" }, "400": { "description": "Settlement is not in draft state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "404": { "description": "Settlement not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } } } } }, "/api/v1/settlements/{id}/report": { "get": { "operationId": "getSettlementReport", "summary": "Download a settlement report", "description": "Streams the generated settlement report file for the given settlement. The response body is a binary stream; use the Content-Disposition header to determine the suggested filename.", "tags": [ "Settlements" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the settlement whose report to download", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Report file stream", "headers": { "Content-Disposition": { "description": "Suggested filename for the downloaded file", "schema": { "type": "string", "example": "attachment; filename=\"report-.pdf\"" } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "404": { "description": "Settlement or report not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/settlements/{id}/export": { "get": { "operationId": "exportSettlementCsv", "summary": "Export a settlement as CSV", "description": "Generates and streams a CSV export of the settlement's commission amounts, including commission IDs, amounts, attribution IDs and attribution dates. Available for any settlement regardless of status.", "tags": [ "Settlements" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the settlement to export", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "CSV export of the settlement", "headers": { "Content-Disposition": { "description": "Suggested filename for the downloaded file", "schema": { "type": "string", "example": "attachment; filename=\"settlement-.csv\"" } } }, "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "404": { "description": "Settlement not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/settlements/{id}/credit-note": { "get": { "operationId": "getSettlementCreditNote", "summary": "Download a settlement credit note", "description": "Streams the generated settlement credit note file for the given settlement. The response body is a binary stream; use the Content-Disposition header to determine the suggested filename.", "tags": [ "Settlements" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the settlement whose credit note to download", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Credit note file stream", "headers": { "Content-Disposition": { "description": "Suggested filename for the downloaded file", "schema": { "type": "string", "example": "attachment; filename=\"credit-note-.pdf\"" } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "404": { "description": "Settlement or credit note not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/settlements/{id}/invoice": { "get": { "operationId": "getSettlementInvoice", "summary": "Download a settlement invoice", "description": "Streams the generated settlement invoice file for the given settlement. The response body is a binary stream; use the Content-Disposition header to determine the suggested filename.", "tags": [ "Settlements" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the settlement whose invoice to download", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Invoice file stream", "headers": { "Content-Disposition": { "description": "Suggested filename for the downloaded file", "schema": { "type": "string", "example": "attachment; filename=\"invoice-.pdf\"" } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "404": { "description": "Settlement or invoice not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "operationId": "uploadSettlementInvoice", "summary": "Upload invoice for settlement", "tags": [ "Settlements" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the settlement whose invoice to upload", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "Invoice uploaded successfully" }, "400": { "description": "Invalid settlement state or billing mode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "404": { "description": "Settlement not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/settlements/{id}/review": { "post": { "operationId": "reviewSettlement", "summary": "Resolve a negative-review settlement", "description": "Transitions a NegativeReview settlement to one of: ReviewedAsCredit or ReviewedAsCarryForward, based on the chosen resolution. To write off a settlement use the dedicated write-off endpoint.", "tags": [ "Settlements" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the settlement to review", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/review_settlement_request" } } } }, "responses": { "200": { "description": "Settlement reviewed successfully" }, "400": { "description": "Settlement is not in negative_review state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "404": { "description": "Settlement not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/settlements/{id}": { "delete": { "operationId": "cancelSettlement", "summary": "Cancel a settlement", "description": "Cancels a draft settlement. Only settlements in Draft status can be cancelled. Once approved, use the dispute flow for post-approval corrections.", "tags": [ "Settlements" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the settlement to cancel", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Settlement successfully cancelled" }, "400": { "description": "Settlement is not cancellable (not in Draft status)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "404": { "description": "Settlement not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/settlements/{id}/write-off": { "post": { "operationId": "writeOffSettlement", "summary": "Write off a settlement", "description": "Writes off an approved settlement that has not yet reached a terminal state. The settlement transitions to WrittenOff, which is a terminal state.", "tags": [ "Settlements" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the settlement to write off", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Settlement successfully written off" }, "400": { "description": "Settlement is not eligible for write-off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "404": { "description": "Settlement not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/settlements/{id}/mark-as-paid": { "post": { "operationId": "markSettlementAsPaid", "summary": "Mark a settlement as paid", "description": "Confirms payment for a settlement that is in `AwaitingPayment` (ExternalPayout path — customer confirms they paid outside Coritra) or `PaymentInitiated` (SelfPayout path — manual confirmation or webhook fallback). Transitions the settlement to `Paid`.", "tags": [ "Settlements" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the settlement to mark as paid", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Settlement marked as paid successfully" }, "400": { "description": "Settlement is not in a payable state (must be AwaitingPayment or PaymentInitiated)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "404": { "description": "Settlement not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_error" } } } } }, "security": [ { "bearerAuth": [] } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "responses": {}, "schemas": { "jwt_claims": { "type": "object", "description": "JWT token claims, discriminated by token_use.", "discriminator": { "propertyName": "token_use", "mapping": { "access": "#/components/schemas/jwt_access_claims", "refresh": "#/components/schemas/jwt_refresh_claims" } }, "oneOf": [ { "$ref": "#/components/schemas/jwt_access_claims" }, { "$ref": "#/components/schemas/jwt_refresh_claims" } ] }, "jwt_access_claims": { "type": "object", "description": "Access token claims.", "required": [ "token_use", "sub", "email", "firstname", "lastname", "memberships", "exp" ], "properties": { "token_use": { "type": "string", "enum": [ "access" ], "example": "access" }, "sub": { "type": "string", "description": "User ID (UUID string).", "example": "3f7a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c" }, "email": { "type": "string", "format": "email", "description": "User email address.", "example": "user@example.com" }, "firstname": { "type": "string", "description": "User's first name.", "example": "John" }, "lastname": { "type": "string", "description": "User's last name.", "example": "Doe" }, "memberships": { "type": "array", "description": "List of memberships the user has.", "items": { "$ref": "#/components/schemas/jwt_access_claims_membership" } }, "exp": { "type": "integer", "description": "Expiration time as Unix timestamp (seconds since epoch).", "example": 1700000000 } } }, "jwt_refresh_claims": { "type": "object", "description": "Refresh token claims.", "required": [ "token_use", "sub", "exp" ], "properties": { "token_use": { "type": "string", "enum": [ "refresh" ], "example": "refresh" }, "sub": { "type": "string", "description": "User ID (UUID string).", "example": "3f7a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c" }, "exp": { "type": "integer", "description": "Expiration time as Unix timestamp (seconds since epoch).", "example": 1700000000 } } }, "jwt_access_claims_membership": { "type": "object", "description": "Membership inside an access token, discriminated by membership_type.", "discriminator": { "propertyName": "membership_type", "mapping": { "customer": "#/components/schemas/jwt_access_claims_membership_customer", "partner": "#/components/schemas/jwt_access_claims_membership_partner" } }, "oneOf": [ { "$ref": "#/components/schemas/jwt_access_claims_membership_customer" }, { "$ref": "#/components/schemas/jwt_access_claims_membership_partner" } ] }, "jwt_access_claims_membership_customer": { "type": "object", "description": "Customer membership inside an access token.", "required": [ "membership_type", "customer_id" ], "properties": { "membership_type": { "type": "string", "enum": [ "customer" ], "example": "customer" }, "customer_id": { "type": "string", "format": "uuid", "description": "Customer ID.", "example": "3f7a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c" } } }, "jwt_access_claims_membership_partner": { "type": "object", "description": "Partner membership inside an access token.", "required": [ "membership_type", "partner_id" ], "properties": { "membership_type": { "type": "string", "enum": [ "partner" ], "example": "partner" }, "partner_id": { "type": "string", "format": "uuid", "description": "Partner ID.", "example": "3f7a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c" } } }, "api_error_type": { "type": "string", "enum": [ "UNAUTHORIZED", "NOT_FOUND", "INTERNAL_ERROR", "BAD_REQUEST", "FORBIDDEN", "CONFLICT" ], "example": "UNAUTHORIZED" }, "api_error": { "type": "object", "required": [ "error_code", "message" ], "properties": { "error_code": { "$ref": "#/components/schemas/api_error_type" }, "message": { "type": "string", "example": "Authentication credentials were not provided or are invalid." } } }, "get_attributions_response_attribution_metadata": { "type": "object", "properties": { "agent_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Optional ID of the agent linked to this attribution" } } }, "get_attributions_response_attribution_event_create": { "type": "object", "required": [ "type", "properties" ], "properties": { "type": { "type": "string", "enum": [ "create_attribution" ] }, "properties": { "type": "object", "additionalProperties": true, "description": "Custom key-value properties attached to the attribution at creation" } } }, "get_attributions_response_attribution_event_cancel": { "type": "object", "required": [ "type", "reason" ], "properties": { "type": { "type": "string", "enum": [ "cancel_attribution" ] }, "reason": { "type": "string", "description": "Reason why the attribution was cancelled" } } }, "get_attributions_response_attribution_event_accrue_commission": { "type": "object", "required": [ "type", "commission_id" ], "properties": { "type": { "type": "string", "enum": [ "accrue_commission" ] }, "commission_id": { "type": "integer", "format": "int64", "minimum": 0, "description": "ID of the commission accrued from this attribution" } } }, "get_attributions_response_attribution_event": { "oneOf": [ { "$ref": "#/components/schemas/get_attributions_response_attribution_event_create" }, { "$ref": "#/components/schemas/get_attributions_response_attribution_event_cancel" }, { "$ref": "#/components/schemas/get_attributions_response_attribution_event_accrue_commission" } ], "discriminator": { "propertyName": "type", "mapping": { "create_attribution": "#/components/schemas/get_attributions_response_attribution_event_create", "cancel_attribution": "#/components/schemas/get_attributions_response_attribution_event_cancel", "accrue_commission": "#/components/schemas/get_attributions_response_attribution_event_accrue_commission" } } }, "get_attributions_response_attribution_event_envelope": { "type": "object", "required": [ "datetime", "event" ], "properties": { "datetime": { "type": "string", "format": "date-time", "description": "Timestamp when the event occurred" }, "event": { "$ref": "#/components/schemas/get_attributions_response_attribution_event" } } }, "get_attributions_response_attribution_view": { "type": "object", "required": [ "status", "properties" ], "properties": { "status": { "type": "string", "enum": [ "confirmed", "cancelled" ], "description": "Current lifecycle status of the attribution" }, "cancel_reason": { "type": "string", "nullable": true, "description": "Reason for cancellation, present only when status is 'cancelled'" }, "properties": { "type": "object", "additionalProperties": {}, "description": "Custom properties attached to this attribution at creation time" }, "created_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the attribution was created" } } }, "get_attributions_response_attribution": { "type": "object", "required": [ "id", "partner_id", "customer_id", "schema_id", "metadata", "events", "view" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the attribution" }, "partner_id": { "type": "string", "format": "uuid", "description": "ID of the partner associated with the attribution" }, "customer_id": { "type": "string", "format": "uuid", "description": "ID of the customer associated with the attribution" }, "schema_id": { "type": "string", "format": "uuid", "description": "ID of the attribution schema this attribution was validated against" }, "metadata": { "$ref": "#/components/schemas/get_attributions_response_attribution_metadata" }, "events": { "type": "array", "description": "Ordered list of events representing the lifecycle of this attribution", "items": { "$ref": "#/components/schemas/get_attributions_response_attribution_event_envelope" } }, "view": { "$ref": "#/components/schemas/get_attributions_response_attribution_view" } } }, "get_attributions_response": { "type": "object", "required": [ "attributions", "total", "page", "per_page" ], "properties": { "attributions": { "type": "array", "items": { "$ref": "#/components/schemas/get_attributions_response_attribution" } }, "total": { "type": "integer", "format": "int64", "description": "Total number of attributions matching the query" }, "page": { "type": "integer", "format": "int64", "description": "Current page number" }, "per_page": { "type": "integer", "format": "int64", "description": "Number of items per page" } } }, "create_attribution_request": { "type": "object", "required": [ "partner_id", "properties", "schema_id", "workspace_id" ], "properties": { "partner_id": { "type": "string", "format": "uuid", "description": "ID of the partner to associate with the attribution" }, "schema_id": { "type": "string", "format": "uuid", "description": "ID of the attribution schema to validate against" }, "workspace_id": { "type": "string", "format": "uuid", "description": "ID of the workspace to associate with the attribution" }, "properties": { "type": "object", "additionalProperties": {}, "description": "Key-value properties (string, number, or boolean) to attach to the attribution" } } }, "create_attribution_response": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the newly created attribution" } } }, "attribution_stats_granularity": { "type": "string", "enum": [ "day", "week", "month" ] }, "attribution_stats_summary": { "type": "object", "required": [ "total", "confirmed", "cancelled" ], "properties": { "total": { "type": "integer" }, "confirmed": { "type": "integer" }, "cancelled": { "type": "integer" } } }, "attribution_stats_bucket": { "type": "object", "required": [ "timestamp", "total", "confirmed", "cancelled" ], "properties": { "timestamp": { "type": "string", "format": "date-time" }, "total": { "type": "integer" }, "confirmed": { "type": "integer" }, "cancelled": { "type": "integer" } } }, "get_attribution_stats_response": { "type": "object", "required": [ "summary", "buckets" ], "properties": { "summary": { "$ref": "#/components/schemas/attribution_stats_summary" }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/attribution_stats_bucket" } } } }, "cancel_attribution_request": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string", "description": "Reason why the attribution is being cancelled" } } }, "get_attribution_schemas_response_attribution_schema_property_string": { "type": "object", "required": [ "name", "type", "required" ], "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "string" ] }, "required": { "type": "boolean" }, "default": { "type": "string", "nullable": true } } }, "get_attribution_schemas_response_attribution_schema_property_number": { "type": "object", "required": [ "name", "type", "required" ], "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "number" ] }, "required": { "type": "boolean" }, "default": { "type": "number", "nullable": true } } }, "get_attribution_schemas_response_attribution_schema_property_boolean": { "type": "object", "required": [ "name", "type", "required" ], "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "boolean" ] }, "required": { "type": "boolean" }, "default": { "type": "boolean", "nullable": true } } }, "get_attribution_schemas_response_attribution_schema_property": { "oneOf": [ { "$ref": "#/components/schemas/get_attribution_schemas_response_attribution_schema_property_string" }, { "$ref": "#/components/schemas/get_attribution_schemas_response_attribution_schema_property_number" }, { "$ref": "#/components/schemas/get_attribution_schemas_response_attribution_schema_property_boolean" } ], "discriminator": { "propertyName": "type", "mapping": { "string": "#/components/schemas/get_attribution_schemas_response_attribution_schema_property_string", "number": "#/components/schemas/get_attribution_schemas_response_attribution_schema_property_number", "boolean": "#/components/schemas/get_attribution_schemas_response_attribution_schema_property_boolean" } } }, "get_attribution_schemas_response_attribution_schema": { "type": "object", "required": [ "id", "customer_id", "workspace_id", "properties", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "customer_id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "properties": { "type": "array", "items": { "$ref": "#/components/schemas/get_attribution_schemas_response_attribution_schema_property" } } } }, "get_attribution_schemas_response": { "type": "object", "required": [ "attribution_schemas", "total", "page", "per_page" ], "properties": { "attribution_schemas": { "type": "array", "items": { "$ref": "#/components/schemas/get_attribution_schemas_response_attribution_schema" } }, "total": { "type": "integer", "description": "Total number of attribution schemas matching the query" }, "page": { "type": "integer", "description": "Current page number" }, "per_page": { "type": "integer", "description": "Number of attribution schemas returned per page" } } }, "create_attribution_schema_request_property_string": { "type": "object", "required": [ "name", "type", "required" ], "properties": { "name": { "type": "string", "description": "Name of the property" }, "type": { "type": "string", "enum": [ "string" ] }, "required": { "type": "boolean", "description": "Whether this property is required on attributions" }, "default": { "type": "string", "description": "Default value for this property", "nullable": true } } }, "create_attribution_schema_request_property_number": { "type": "object", "required": [ "name", "type", "required" ], "properties": { "name": { "type": "string", "description": "Name of the property" }, "type": { "type": "string", "enum": [ "number" ] }, "required": { "type": "boolean", "description": "Whether this property is required on attributions" }, "default": { "type": "number", "description": "Default value for this property", "nullable": true } } }, "create_attribution_schema_request_property_boolean": { "type": "object", "required": [ "name", "type", "required" ], "properties": { "name": { "type": "string", "description": "Name of the property" }, "type": { "type": "string", "enum": [ "boolean" ] }, "required": { "type": "boolean", "description": "Whether this property is required on attributions" }, "default": { "type": "boolean", "description": "Default value for this property", "nullable": true } } }, "create_attribution_schema_request_property": { "oneOf": [ { "$ref": "#/components/schemas/create_attribution_schema_request_property_string" }, { "$ref": "#/components/schemas/create_attribution_schema_request_property_number" }, { "$ref": "#/components/schemas/create_attribution_schema_request_property_boolean" } ], "discriminator": { "propertyName": "type", "mapping": { "string": "#/components/schemas/create_attribution_schema_request_property_string", "number": "#/components/schemas/create_attribution_schema_request_property_number", "boolean": "#/components/schemas/create_attribution_schema_request_property_boolean" } } }, "create_attribution_schema_request": { "type": "object", "required": [ "workspace_id", "properties", "name" ], "properties": { "workspace_id": { "type": "string", "format": "uuid", "description": "ID of the workspace this schema belongs to" }, "name": { "type": "string", "description": "Name of the attribution schema" }, "properties": { "type": "array", "items": { "$ref": "#/components/schemas/create_attribution_schema_request_property" }, "description": "List of property definitions for the attribution schema" } } }, "create_attribution_schema_response": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the newly created attribution schema" } } }, "customer_address": { "type": "object", "required": [ "street", "city", "postal_code", "region", "country" ], "properties": { "street": { "type": "string", "description": "Street address" }, "city": { "type": "string", "description": "City" }, "region": { "type": "string", "description": "State or region" }, "postal_code": { "type": "string", "description": "Postal code" }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code" } } }, "get_customers_response_customer": { "type": "object", "required": [ "id", "name", "trial_available" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the customer" }, "name": { "type": "string", "description": "Name of the customer" }, "legal_name": { "type": "string", "nullable": true, "description": "Legal / registered name used on invoices (null if not configured)" }, "address": { "$ref": "#/components/schemas/customer_address", "nullable": true, "description": "Registered business address (null if not configured)" }, "vat_number": { "type": "string", "nullable": true, "description": "VAT or tax registration number (null if not configured)" }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Free-form key-value metadata (arbitrary JSON)" }, "trial_available": { "type": "boolean", "description": "Whether this customer is eligible for a free trial. True when the customer has never started a subscription before." } } }, "get_customers_response": { "type": "object", "required": [ "customers", "total", "page", "per_page" ], "properties": { "customers": { "type": "array", "items": { "$ref": "#/components/schemas/get_customers_response_customer" } }, "total": { "type": "integer", "description": "Total number of customers matching the query" }, "page": { "type": "integer", "description": "Current page number" }, "per_page": { "type": "integer", "description": "Number of customers returned per page" } } }, "create_customer_request": { "type": "object", "required": [ "name", "email" ], "properties": { "name": { "type": "string", "description": "Name of the customer" }, "email": { "type": "string", "format": "email", "description": "Email address of the customer" }, "legal_name": { "type": "string", "nullable": true, "description": "Legal / registered name used on invoices (null if not configured)" }, "address": { "$ref": "#/components/schemas/customer_address", "nullable": true, "description": "Registered business address (null if not configured)" }, "vat_number": { "type": "string", "nullable": true, "description": "VAT or tax registration number (null if not configured)" }, "user_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Optional user ID to link as a customer membership to the new customer" }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Free-form key-value metadata (arbitrary JSON)" } } }, "create_customer_response": { "type": "object", "required": [ "customer_id" ], "properties": { "customer_id": { "type": "string", "format": "uuid", "description": "Unique identifier of the created customer" } } }, "update_customer_request": { "type": "object", "properties": { "legal_name": { "type": "string", "nullable": true, "description": "Updated legal entity name (used on invoices). Omit to leave unchanged." }, "address": { "$ref": "#/components/schemas/customer_address", "nullable": true, "description": "Updated billing address. Omit to leave unchanged." }, "vat_number": { "type": "string", "nullable": true, "description": "Updated VAT registration number. Omit to leave unchanged." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Updated free-form key-value metadata. Omit to leave unchanged." }, "clear_address": { "type": "boolean", "description": "When true, removes the billing address from the customer. Ignored when address is also provided." } } }, "customer_usage": { "type": "object", "required": [ "customer_id", "attribution_limit", "partners_count", "partners_limit", "workspaces_count", "workspaces_limit" ], "properties": { "customer_id": { "type": "string", "format": "uuid", "description": "Unique identifier of the customer" }, "attribution_current_period_count": { "type": "integer", "format": "int64", "minimum": 0, "nullable": true, "description": "Number of attributions created during the current billing cycle. Null when no cycle_anchor_day is configured." }, "attribution_period_start": { "type": "string", "format": "date-time", "nullable": true, "description": "UTC timestamp marking the start of the current billing cycle. Null when no cycle_anchor_day is configured." }, "attribution_limit": { "type": "integer", "format": "int64", "minimum": 0, "description": "Maximum number of attributions allowed per billing cycle." }, "attribution_cycle_anchor_day": { "type": "integer", "minimum": 1, "maximum": 28, "nullable": true, "description": "Day of the month on which the attribution counter resets (1–28). Null when not configured." }, "partners_count": { "type": "integer", "format": "int64", "minimum": 0, "description": "Current number of partners belonging to this customer." }, "partners_limit": { "type": "integer", "format": "int64", "minimum": 0, "description": "Maximum number of partners allowed." }, "workspaces_count": { "type": "integer", "format": "int64", "minimum": 0, "description": "Current number of workspaces belonging to this customer." }, "workspaces_limit": { "type": "integer", "format": "int64", "minimum": 0, "description": "Maximum number of workspaces allowed." } } }, "partner_address": { "type": "object", "required": [ "street", "city", "postal_code", "region", "country" ], "properties": { "street": { "type": "string", "description": "Street address including house number" }, "city": { "type": "string", "description": "City" }, "region": { "type": "string", "description": "State, province, or region" }, "postal_code": { "type": "string", "description": "Postal or ZIP code" }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code" } } }, "partner_bank_account": { "type": "object", "required": [ "beneficiary_name", "iban", "bic" ], "properties": { "beneficiary_name": { "type": "string", "description": "Name of the bank account beneficiary" }, "iban": { "type": "string", "description": "International Bank Account Number" }, "bic": { "type": "string", "description": "Bank Identifier Code (SWIFT/BIC)" } } }, "partner_tax_treatment": { "type": "string", "enum": [ "standard", "reverse_charge", "exempt" ], "description": "Tax treatment applied to commissions paid to this partner" }, "partner_tax_config": { "type": "object", "required": [ "treatment", "label" ], "properties": { "treatment": { "$ref": "#/components/schemas/partner_tax_treatment" }, "label": { "type": "string", "description": "Tax label printed on invoices (e.g. \"VAT\", \"TVA\", \"MwSt\")" }, "rate_bps": { "type": "integer", "nullable": true, "description": "Tax rate in basis points (e.g. 2000 = 20%). Required when treatment is standard." } } }, "partner_self_billing_data": { "type": "object", "required": [ "legal_name", "address", "vat_number", "payment_terms_days", "bank_account", "tax_config" ], "properties": { "legal_name": { "type": "string", "description": "Legal entity name of the partner (used on invoices)" }, "address": { "$ref": "#/components/schemas/partner_address", "description": "Registered business address shown on invoices" }, "vat_number": { "type": "string", "description": "VAT or tax registration number (e.g. \"FR12345678901\")" }, "payment_terms_days": { "type": "integer", "description": "Number of days after invoice issuance until payment is due" }, "bank_account": { "$ref": "#/components/schemas/partner_bank_account", "description": "Bank account to which the settlement amount should be transferred" }, "tax_config": { "$ref": "#/components/schemas/partner_tax_config", "description": "Tax treatment applied to this partner's invoices" } } }, "get_partners_response_partner": { "type": "object", "required": [ "id", "name", "customer_id", "workspace_id" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the partner" }, "name": { "type": "string", "description": "Name of the partner" }, "customer_id": { "type": "string", "format": "uuid", "description": "ID of the customer this partner belongs to" }, "workspace_id": { "type": "string", "format": "uuid", "description": "ID of the workspace this partner belongs to" }, "billing_mode": { "type": "string", "nullable": true, "enum": [ "self_billing", "partner_billing" ], "description": "Billing mode for this partner (null if not configured)" }, "self_billing_data": { "$ref": "#/components/schemas/partner_self_billing_data", "nullable": true, "description": "Present when billing_mode is self_billing. Contains all invoice generation data." } } }, "get_partners_response": { "type": "object", "required": [ "partners", "total", "page", "per_page" ], "properties": { "partners": { "type": "array", "items": { "$ref": "#/components/schemas/get_partners_response_partner" } }, "total": { "type": "integer", "description": "Total number of partners matching the query" }, "page": { "type": "integer", "description": "Current page number" }, "per_page": { "type": "integer", "description": "Number of partners returned per page" } } }, "create_partner_request": { "type": "object", "required": [ "name", "workspace_id" ], "properties": { "name": { "type": "string", "description": "Name of the partner to create" }, "workspace_id": { "type": "string", "format": "uuid", "description": "ID of the workspace this partner belongs to" }, "billing_mode": { "type": "string", "nullable": true, "enum": [ "self_billing", "partner_billing" ], "description": "Billing mode for the partner. Omit to use the default (partner_billing)." }, "self_billing_data": { "$ref": "#/components/schemas/partner_self_billing_data", "nullable": true, "description": "Required when billing_mode is self_billing. Contains all data needed to generate invoices on behalf of the partner." } } }, "create_partner_response": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the newly created partner" } } }, "update_partner_request": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "description": "Updated name for the partner (omit to leave unchanged)" }, "billing_mode": { "type": "string", "nullable": true, "enum": [ "self_billing", "partner_billing" ], "description": "Updated billing mode. Omit to leave unchanged." }, "self_billing_data": { "$ref": "#/components/schemas/partner_self_billing_data", "nullable": true, "description": "Required when billing_mode is self_billing. Replaces all self-billing data atomically. Omit to leave unchanged." } } }, "get_users_response_user": { "type": "object", "required": [ "id", "user_memberships", "email", "first_name", "last_name" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the user" }, "user_memberships": { "type": "array", "items": { "oneOf": [ { "type": "object", "required": [ "Customer" ], "properties": { "Customer": { "type": "object", "required": [ "customer_id", "role" ], "properties": { "customer_id": { "type": "string", "format": "uuid", "description": "ID of the customer" }, "role": { "type": "string", "enum": [ "owner", "user" ], "description": "Role within the customer organization" } } } } }, { "type": "object", "required": [ "Partner" ], "properties": { "Partner": { "type": "object", "required": [ "partner_id" ], "properties": { "partner_id": { "type": "string", "format": "uuid", "description": "ID of the partner" } } } } } ] }, "description": "List of user memberships" }, "email": { "type": "string", "description": "User email address" }, "first_name": { "type": "string", "description": "User first name" }, "last_name": { "type": "string", "description": "User last name" } } }, "get_users_response": { "type": "object", "required": [ "users", "total", "page", "per_page" ], "properties": { "users": { "type": "array", "items": { "$ref": "#/components/schemas/get_users_response_user" } }, "total": { "type": "integer", "description": "Total number of users matching the query" }, "page": { "type": "integer", "description": "Current page number" }, "per_page": { "type": "integer", "description": "Number of users returned per page" } } }, "invite_user_request": { "type": "object", "required": [ "email", "customer_id" ], "properties": { "email": { "type": "string", "format": "email", "description": "Email address of the user to invite" }, "customer_id": { "type": "string", "format": "uuid", "description": "ID of the customer associated with the user" } } }, "get_user_invitations_response_item": { "type": "object", "required": [ "id", "email", "customer_id", "by", "customer_name" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the invitation" }, "email": { "type": "string", "description": "Email address being invited" }, "customer_id": { "type": "string", "format": "uuid", "description": "Customer (organization) the user is invited to join" }, "by": { "type": "string", "format": "uuid", "description": "User who created this invitation" }, "customer_name": { "type": "string", "description": "Name of the customer (organization) the user is invited to join" } } }, "get_user_invitations_response": { "type": "object", "required": [ "invitations", "total", "page", "per_page" ], "properties": { "invitations": { "type": "array", "items": { "$ref": "#/components/schemas/get_user_invitations_response_item" }, "description": "List of user invitations" }, "total": { "type": "integer", "description": "Total number of invitations matching the query" }, "page": { "type": "integer", "description": "Current page number" }, "per_page": { "type": "integer", "description": "Number of invitations returned per page" } } }, "authenticate_user_request": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "description": "User email address" }, "password": { "type": "string", "description": "User password" } } }, "authenticate_user_response": { "type": "object", "required": [ "access_token", "refresh_token" ], "properties": { "access_token": { "type": "string", "description": "JWT access token" }, "refresh_token": { "type": "string", "description": "JWT refresh token" } } }, "refresh_token_request": { "type": "object", "required": [ "refresh_token" ], "properties": { "refresh_token": { "type": "string", "description": "JWT refresh token issued at login or a previous refresh" } } }, "ask_reset_password_request": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "description": "Email address of the user requesting a password reset" } } }, "verify_reset_password_token_response": { "type": "object", "required": [ "user_id", "email" ], "properties": { "user_id": { "type": "string", "format": "uuid", "description": "ID of the user who owns this reset token" }, "email": { "type": "string", "description": "Email address associated with the reset token" } } }, "reset_password_request": { "type": "object", "required": [ "token", "new_password" ], "properties": { "token": { "type": "string", "description": "The password-reset token from the reset link" }, "new_password": { "type": "string", "description": "The new password to set for the account" } } }, "initiate_registration_request": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "Email address of the initial admin user" }, "conversion_clics_id": { "type": "string", "description": "Ad platform click ID captured on landing (e.g. gclid, fbclid). Stored internally for conversion reporting — never returned by the API." } } }, "verify_registration_token_response": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "description": "The email address associated with the pending registration token" } } }, "validate_registration_request": { "type": "object", "required": [ "token", "first_name", "last_name", "password" ], "properties": { "token": { "type": "string", "description": "The registration token received by email" }, "first_name": { "type": "string", "description": "First name of the user" }, "last_name": { "type": "string", "description": "Last name of the user" }, "password": { "type": "string", "description": "Password for the user account", "minLength": 8 } } }, "get_workspaces_response_workspace": { "type": "object", "required": [ "id", "customer_id", "name", "sandbox" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Workspace ID" }, "customer_id": { "type": "string", "format": "uuid", "description": "ID of the customer that owns this workspace" }, "name": { "type": "string", "description": "Name of the workspace" }, "sandbox": { "type": "boolean", "description": "Whether this is a sandbox workspace" } } }, "get_workspaces_response": { "type": "object", "required": [ "workspaces", "total", "page", "per_page" ], "properties": { "workspaces": { "type": "array", "items": { "$ref": "#/components/schemas/get_workspaces_response_workspace" } }, "total": { "type": "integer", "description": "Total number of workspaces matching the query" }, "page": { "type": "integer", "description": "Current page number" }, "per_page": { "type": "integer", "description": "Number of workspaces returned per page" } } }, "create_workspace_request": { "type": "object", "required": [ "customer_id", "name", "sandbox" ], "properties": { "customer_id": { "type": "string", "format": "uuid", "description": "ID of the customer this workspace belongs to" }, "name": { "type": "string", "description": "Name of the workspace" }, "sandbox": { "type": "boolean", "description": "Whether this is a sandbox workspace" } } }, "create_workspace_response": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the newly created workspace" } } }, "value_number": { "title": "ValueNumber", "type": "object", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "enum": [ "number" ] }, "value": { "type": "number" } } }, "value_string": { "title": "ValueString", "type": "object", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "enum": [ "string" ] }, "value": { "type": "string" } } }, "value_bool": { "title": "ValueBool", "type": "object", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "enum": [ "bool" ] }, "value": { "type": "boolean" } } }, "value": { "title": "Value", "type": "object", "required": [ "type" ], "discriminator": { "propertyName": "type", "mapping": { "number": "#/components/schemas/value_number", "string": "#/components/schemas/value_string", "bool": "#/components/schemas/value_bool" } }, "oneOf": [ { "$ref": "#/components/schemas/value_number" }, { "$ref": "#/components/schemas/value_string" }, { "$ref": "#/components/schemas/value_bool" } ] }, "expression_literal": { "title": "ExpressionLiteral", "type": "object", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "enum": [ "literal" ] }, "value": { "$ref": "#/components/schemas/value" } } }, "expression_attribute": { "title": "ExpressionAttribute", "type": "object", "required": [ "type", "name" ], "properties": { "type": { "type": "string", "enum": [ "attribute" ] }, "name": { "type": "string", "enum": [ "id", "customer_id", "partner_id", "workspace_id", "created_at" ], "description": "Name of the attribution attribute" } } }, "expression_property": { "title": "ExpressionProperty", "type": "object", "required": [ "type", "name" ], "properties": { "type": { "type": "string", "enum": [ "property" ] }, "name": { "type": "string", "description": "Name of the property key in the attribution's dynamic property bag" } } }, "expression": { "title": "Expression", "type": "object", "required": [ "type" ], "discriminator": { "propertyName": "type", "mapping": { "literal": "#/components/schemas/expression_literal", "attribute": "#/components/schemas/expression_attribute", "property": "#/components/schemas/expression_property", "binary_op": "#/components/schemas/expression_binary_op", "unary_op": "#/components/schemas/expression_unary_op", "if": "#/components/schemas/expression_if" } }, "oneOf": [ { "$ref": "#/components/schemas/expression_literal" }, { "$ref": "#/components/schemas/expression_attribute" }, { "$ref": "#/components/schemas/expression_property" }, { "$ref": "#/components/schemas/expression_binary_op" }, { "$ref": "#/components/schemas/expression_unary_op" }, { "$ref": "#/components/schemas/expression_if" } ] }, "operator_add": { "title": "OperatorAdd", "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "operator_add" ] } } }, "operator_subtract": { "title": "OperatorSubtract", "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "operator_subtract" ] } } }, "operator_multiply": { "title": "OperatorMultiply", "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "operator_multiply" ] } } }, "operator_divide": { "title": "OperatorDivide", "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "operator_divide" ] } } }, "operator_equal": { "title": "OperatorEqual", "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "operator_equal" ] } } }, "operator_not_equal": { "title": "OperatorNotEqual", "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "operator_not_equal" ] } } }, "operator_greater_than": { "title": "OperatorGreaterThan", "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "operator_greater_than" ] } } }, "operator_less_than": { "title": "OperatorLessThan", "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "operator_less_than" ] } } }, "operator_and": { "title": "OperatorAnd", "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "operator_and" ] } } }, "operator_or": { "title": "OperatorOr", "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "operator_or" ] } } }, "operator": { "title": "Operator", "type": "object", "required": [ "type" ], "discriminator": { "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/operator_add" }, { "$ref": "#/components/schemas/operator_subtract" }, { "$ref": "#/components/schemas/operator_multiply" }, { "$ref": "#/components/schemas/operator_divide" }, { "$ref": "#/components/schemas/operator_equal" }, { "$ref": "#/components/schemas/operator_not_equal" }, { "$ref": "#/components/schemas/operator_greater_than" }, { "$ref": "#/components/schemas/operator_less_than" }, { "$ref": "#/components/schemas/operator_and" }, { "$ref": "#/components/schemas/operator_or" } ] }, "expression_binary_op": { "title": "ExpressionBinaryOp", "type": "object", "required": [ "type", "left", "op", "right" ], "properties": { "type": { "type": "string", "enum": [ "binary_op" ] }, "left": { "$ref": "#/components/schemas/expression" }, "op": { "$ref": "#/components/schemas/operator" }, "right": { "$ref": "#/components/schemas/expression" } } }, "unary_operator_not": { "title": "UnaryOperatorNot", "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "unary_operator_not" ] } } }, "unary_operator_negate": { "title": "UnaryOperatorNegate", "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "unary_operator_negate" ] } } }, "unary_operator": { "title": "UnaryOperator", "type": "object", "required": [ "type" ], "discriminator": { "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/unary_operator_not" }, { "$ref": "#/components/schemas/unary_operator_negate" } ] }, "expression_unary_op": { "title": "ExpressionUnaryOp", "type": "object", "required": [ "type", "op", "expr" ], "properties": { "type": { "type": "string", "enum": [ "unary_op" ] }, "op": { "$ref": "#/components/schemas/unary_operator" }, "expr": { "$ref": "#/components/schemas/expression" } } }, "expression_if": { "title": "ExpressionIf", "type": "object", "required": [ "type", "condition", "then_branch", "else_branch" ], "properties": { "type": { "type": "string", "enum": [ "if" ] }, "condition": { "$ref": "#/components/schemas/expression" }, "then_branch": { "$ref": "#/components/schemas/expression" }, "else_branch": { "$ref": "#/components/schemas/expression" } } }, "get_commission_formulas_response_commission_formula_event_create": { "type": "object", "required": [ "type", "currency", "name", "formula", "start_datetime" ], "properties": { "type": { "type": "string", "enum": [ "create_commission_formula" ] }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. EUR, USD)" }, "name": { "type": "string", "description": "Name of the commission formula" }, "description": { "type": "string", "nullable": true, "description": "Optional description of the commission formula" }, "formula": { "$ref": "#/components/schemas/expression", "description": "The AST expression defining the commission calculation" }, "start_datetime": { "type": "string", "format": "date-time", "description": "Date and time from which this formula is active" }, "end_datetime": { "type": "string", "format": "date-time", "nullable": true, "description": "Date and time until which this formula is active (null means no expiry)" } } }, "get_commission_formulas_response_commission_formula_event_cancel": { "type": "object", "required": [ "type", "reason" ], "properties": { "type": { "type": "string", "enum": [ "cancel_commission_formula" ] }, "reason": { "type": "string", "description": "Reason why the commission formula was cancelled" } } }, "get_commission_formulas_response_commission_formula_event_update": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "update_commission_formula" ] }, "name": { "type": "string", "nullable": true, "description": "Updated name of the commission formula (null means unchanged)" }, "start_datetime": { "type": "string", "format": "date-time", "nullable": true, "description": "Updated start date-time (null means unchanged)" }, "end_datetime": { "type": "string", "format": "date-time", "nullable": true, "description": "Updated end date-time (null means unchanged; omitted field means unchanged, explicit null means cleared)" } } }, "get_commission_formulas_response_commission_formula_event": { "oneOf": [ { "$ref": "#/components/schemas/get_commission_formulas_response_commission_formula_event_create" }, { "$ref": "#/components/schemas/get_commission_formulas_response_commission_formula_event_cancel" }, { "$ref": "#/components/schemas/get_commission_formulas_response_commission_formula_event_update" } ], "discriminator": { "propertyName": "type", "mapping": { "create_commission_formula": "#/components/schemas/get_commission_formulas_response_commission_formula_event_create", "cancel_commission_formula": "#/components/schemas/get_commission_formulas_response_commission_formula_event_cancel", "update_commission_formula": "#/components/schemas/get_commission_formulas_response_commission_formula_event_update" } } }, "get_commission_formulas_response_commission_formula_event_envelope": { "type": "object", "required": [ "datetime", "event" ], "properties": { "datetime": { "type": "string", "format": "date-time", "description": "Timestamp when the event occurred" }, "event": { "$ref": "#/components/schemas/get_commission_formulas_response_commission_formula_event" } } }, "get_commission_formulas_response_commission_formula_view": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "active", "cancelled" ], "description": "Current lifecycle status of the commission formula" }, "cancel_reason": { "type": "string", "nullable": true, "description": "Reason for cancellation, present only when status is 'cancelled'" }, "name": { "type": "string", "nullable": true, "description": "Name of the commission formula" }, "description": { "type": "string", "nullable": true, "description": "Optional description of the commission formula" }, "formula": { "$ref": "#/components/schemas/expression", "nullable": true, "description": "The AST expression defining the commission calculation" }, "start_datetime": { "type": "string", "format": "date-time", "nullable": true, "description": "Date and time from which this formula is active" }, "end_datetime": { "type": "string", "format": "date-time", "nullable": true, "description": "Date and time until which this formula is active (null means no expiry)" }, "created_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the commission formula was created" } } }, "get_commission_formulas_response_commission_formula": { "type": "object", "required": [ "id", "partner_id", "customer_id", "workspace_id", "schema_id", "events", "view" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the commission formula" }, "partner_id": { "type": "string", "format": "uuid", "description": "ID of the partner this formula belongs to" }, "customer_id": { "type": "string", "format": "uuid", "description": "ID of the customer this formula belongs to" }, "workspace_id": { "type": "string", "format": "uuid", "description": "ID of the workspace this formula belongs to" }, "schema_id": { "type": "string", "format": "uuid", "description": "ID of the attribution schema this formula is associated with" }, "events": { "type": "array", "description": "Ordered list of events representing the lifecycle of this commission formula", "items": { "$ref": "#/components/schemas/get_commission_formulas_response_commission_formula_event_envelope" } }, "view": { "$ref": "#/components/schemas/get_commission_formulas_response_commission_formula_view" } } }, "get_commission_formulas_response": { "type": "object", "required": [ "commission_formulas", "total", "page", "per_page" ], "properties": { "commission_formulas": { "type": "array", "items": { "$ref": "#/components/schemas/get_commission_formulas_response_commission_formula" } }, "total": { "type": "integer", "description": "Total number of commission formulas matching the query" }, "page": { "type": "integer", "description": "Current page number" }, "per_page": { "type": "integer", "description": "Number of commission formulas returned per page" } } }, "create_commission_formula_request": { "type": "object", "required": [ "partner_id", "workspace_id", "schema_id", "name", "start_datetime", "currency", "expression" ], "properties": { "partner_id": { "type": "string", "format": "uuid", "description": "ID of the partner this formula belongs to" }, "workspace_id": { "type": "string", "format": "uuid", "description": "ID of the workspace this formula belongs to" }, "schema_id": { "type": "string", "format": "uuid", "description": "ID of the attribution schema this formula is associated with" }, "name": { "type": "string", "description": "Name of the commission formula" }, "description": { "type": "string", "nullable": true, "description": "Optional description of the commission formula" }, "start_datetime": { "type": "string", "format": "date-time", "description": "Date and time from which this formula is active" }, "end_datetime": { "type": "string", "format": "date-time", "nullable": true, "description": "Date and time until which this formula is active" }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. EUR, USD)" }, "expression": { "$ref": "#/components/schemas/expression" } } }, "create_commission_formula_response": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the newly created commission formula" } } }, "update_commission_formula_request": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "description": "Updated name for the commission formula (omit to leave unchanged)" }, "start_datetime": { "type": "string", "format": "date-time", "nullable": true, "description": "Updated start date-time (omit to leave unchanged)" }, "end_datetime": { "type": "string", "format": "date-time", "nullable": true, "description": "Updated end date-time. Pass null to clear the expiry, omit to leave unchanged." }, "expression": { "$ref": "#/components/schemas/expression", "description": "Updated expression formula (omit to leave unchanged)" } } }, "get_commissions_response_commission_event_create": { "type": "object", "required": [ "type", "amount" ], "properties": { "type": { "type": "string", "enum": [ "create_commission" ] }, "amount": { "type": "number", "description": "Amount of the commission" } } }, "get_commissions_response_commission_event_cancel": { "type": "object", "required": [ "type", "reason" ], "properties": { "type": { "type": "string", "enum": [ "cancel_commission" ] }, "reason": { "type": "string", "description": "The reason the commission was cancelled" } } }, "get_commissions_response_commission_event_update_computed_amount": { "type": "object", "required": [ "type", "amount" ], "properties": { "type": { "type": "string", "enum": [ "update_computed_amount" ] }, "amount": { "type": "integer", "format": "int64", "description": "The new cached commission amount" } } }, "get_commissions_response_commission_event_update_settlement_status": { "type": "object", "required": [ "type", "settlement_status" ], "properties": { "type": { "type": "string", "enum": [ "update_settlement_status" ] }, "settlement_status": { "oneOf": [ { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "unsettled" ] } } }, { "type": "object", "required": [ "type", "settlement_id" ], "properties": { "type": { "type": "string", "enum": [ "pending_settlement" ] }, "settlement_id": { "type": "string", "format": "uuid", "description": "ID of the settlement that reserved this commission" } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "settled" ] } } } ], "discriminator": { "propertyName": "type" } } } }, "get_commissions_response_commission_event": { "oneOf": [ { "$ref": "#/components/schemas/get_commissions_response_commission_event_create" }, { "$ref": "#/components/schemas/get_commissions_response_commission_event_cancel" }, { "$ref": "#/components/schemas/get_commissions_response_commission_event_update_computed_amount" }, { "$ref": "#/components/schemas/get_commissions_response_commission_event_update_settlement_status" } ], "discriminator": { "propertyName": "type", "mapping": { "create_commission": "#/components/schemas/get_commissions_response_commission_event_create", "cancel_commission": "#/components/schemas/get_commissions_response_commission_event_cancel", "update_computed_amount": "#/components/schemas/get_commissions_response_commission_event_update_computed_amount", "update_settlement_status": "#/components/schemas/get_commissions_response_commission_event_update_settlement_status" } } }, "get_commissions_response_commission_event_envelope": { "type": "object", "required": [ "datetime", "event" ], "properties": { "datetime": { "type": "string", "format": "date-time", "description": "Timestamp when the event occurred" }, "event": { "$ref": "#/components/schemas/get_commissions_response_commission_event" } } }, "get_commissions_response_commission_view": { "type": "object", "required": [ "settlement_status" ], "properties": { "created_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the commission was created" }, "computed_amount": { "type": "integer", "format": "int64", "nullable": true, "description": "Cached total commission amount. Null until computed at least once." }, "settlement_status": { "type": "string", "enum": [ "unsettled", "pending_settlement", "settled" ], "description": "Settlement state of the commission" } } }, "get_commissions_response_commission": { "type": "object", "required": [ "id", "partner_id", "attribution_id", "customer_id", "commission_formula_id", "workspace_id", "currency", "events", "view" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the commission" }, "partner_id": { "type": "string", "format": "uuid", "description": "ID of the partner this commission belongs to" }, "attribution_id": { "type": "string", "format": "uuid", "description": "ID of the attribution that triggered this commission" }, "customer_id": { "type": "string", "format": "uuid", "description": "ID of the customer this commission belongs to" }, "commission_formula_id": { "type": "string", "format": "uuid", "description": "ID of the commission formula used to compute this commission" }, "workspace_id": { "type": "string", "format": "uuid", "description": "ID of the workspace this commission belongs to" }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. EUR, USD)" }, "events": { "type": "array", "description": "Ordered list of events representing the lifecycle of this commission", "items": { "$ref": "#/components/schemas/get_commissions_response_commission_event_envelope" } }, "view": { "$ref": "#/components/schemas/get_commissions_response_commission_view" } } }, "get_commissions_response": { "type": "object", "required": [ "commissions", "total", "page", "per_page" ], "properties": { "commissions": { "type": "array", "items": { "$ref": "#/components/schemas/get_commissions_response_commission" } }, "total": { "type": "integer", "format": "int64", "description": "Total number of commissions matching the query" }, "page": { "type": "integer", "format": "int64", "description": "Current page number" }, "per_page": { "type": "integer", "format": "int64", "description": "Number of items per page" } } }, "commission_stats_granularity": { "type": "string", "enum": [ "day", "week", "month" ] }, "commission_stats_amount": { "type": "object", "required": [ "currency", "amount" ], "properties": { "currency": { "type": "string", "description": "ISO 4217 currency code" }, "amount": { "type": "integer", "description": "Aggregated amount in the smallest unit for the given currency" } } }, "commission_stats_partition": { "type": "object", "required": [ "count", "amounts" ], "properties": { "count": { "type": "integer" }, "amounts": { "type": "array", "items": { "$ref": "#/components/schemas/commission_stats_amount" } } } }, "commission_stats_summary": { "type": "object", "required": [ "count", "settled", "unsettled" ], "properties": { "count": { "type": "integer" }, "settled": { "$ref": "#/components/schemas/commission_stats_partition" }, "unsettled": { "$ref": "#/components/schemas/commission_stats_partition" } } }, "commission_stats_bucket": { "type": "object", "required": [ "timestamp", "count", "settled", "unsettled" ], "properties": { "timestamp": { "type": "string", "format": "date-time" }, "count": { "type": "integer" }, "settled": { "$ref": "#/components/schemas/commission_stats_partition" }, "unsettled": { "$ref": "#/components/schemas/commission_stats_partition" } } }, "get_commission_stats_response": { "type": "object", "required": [ "summary", "buckets" ], "properties": { "summary": { "$ref": "#/components/schemas/commission_stats_summary" }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/commission_stats_bucket" } } } }, "get_settlements_response_settlement_status_draft": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "draft" ] } } }, "get_settlements_response_settlement_status_awaiting_report": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "awaiting_report" ] } } }, "get_settlements_response_settlement_status_negative_review": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "negative_review" ] } } }, "get_settlements_response_settlement_status_reviewed_as_credit": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "reviewed_as_credit" ] } } }, "get_settlements_response_settlement_status_reviewed_as_carry_forward": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "reviewed_as_carry_forward" ] } } }, "get_settlements_response_settlement_status_credit_note_issued": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "credit_note_issued" ] } } }, "get_settlements_response_settlement_status_written_off": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "written_off" ] } } }, "get_settlements_response_settlement_status_awaiting_invoice": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "awaiting_invoice" ] } } }, "get_settlements_response_settlement_status_payment_initiated": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "payment_initiated" ] } } }, "get_settlements_response_settlement_status_awaiting_payment": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "awaiting_payment" ] } } }, "get_settlements_response_settlement_status_paid": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "paid" ] } } }, "get_settlements_response_settlement_status_cancelled": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "cancelled" ] } } }, "get_settlements_response_settlement_status_disputed": { "type": "object", "required": [ "type", "reason" ], "properties": { "type": { "type": "string", "enum": [ "disputed" ] }, "reason": { "type": "string", "description": "Reason for the dispute" } } }, "get_settlements_response_settlement_status": { "oneOf": [ { "$ref": "#/components/schemas/get_settlements_response_settlement_status_draft" }, { "$ref": "#/components/schemas/get_settlements_response_settlement_status_awaiting_report" }, { "$ref": "#/components/schemas/get_settlements_response_settlement_status_negative_review" }, { "$ref": "#/components/schemas/get_settlements_response_settlement_status_reviewed_as_credit" }, { "$ref": "#/components/schemas/get_settlements_response_settlement_status_reviewed_as_carry_forward" }, { "$ref": "#/components/schemas/get_settlements_response_settlement_status_credit_note_issued" }, { "$ref": "#/components/schemas/get_settlements_response_settlement_status_written_off" }, { "$ref": "#/components/schemas/get_settlements_response_settlement_status_awaiting_invoice" }, { "$ref": "#/components/schemas/get_settlements_response_settlement_status_payment_initiated" }, { "$ref": "#/components/schemas/get_settlements_response_settlement_status_awaiting_payment" }, { "$ref": "#/components/schemas/get_settlements_response_settlement_status_paid" }, { "$ref": "#/components/schemas/get_settlements_response_settlement_status_cancelled" }, { "$ref": "#/components/schemas/get_settlements_response_settlement_status_disputed" } ], "discriminator": { "propertyName": "type", "mapping": { "draft": "#/components/schemas/get_settlements_response_settlement_status_draft", "awaiting_report": "#/components/schemas/get_settlements_response_settlement_status_awaiting_report", "negative_review": "#/components/schemas/get_settlements_response_settlement_status_negative_review", "reviewed_as_credit": "#/components/schemas/get_settlements_response_settlement_status_reviewed_as_credit", "reviewed_as_carry_forward": "#/components/schemas/get_settlements_response_settlement_status_reviewed_as_carry_forward", "credit_note_issued": "#/components/schemas/get_settlements_response_settlement_status_credit_note_issued", "written_off": "#/components/schemas/get_settlements_response_settlement_status_written_off", "awaiting_invoice": "#/components/schemas/get_settlements_response_settlement_status_awaiting_invoice", "payment_initiated": "#/components/schemas/get_settlements_response_settlement_status_payment_initiated", "awaiting_payment": "#/components/schemas/get_settlements_response_settlement_status_awaiting_payment", "paid": "#/components/schemas/get_settlements_response_settlement_status_paid", "cancelled": "#/components/schemas/get_settlements_response_settlement_status_cancelled", "disputed": "#/components/schemas/get_settlements_response_settlement_status_disputed" } } }, "get_settlements_response_commission_amount": { "type": "object", "required": [ "commission_id", "amount" ], "properties": { "commission_id": { "type": "string", "format": "uuid", "description": "ID of the commission" }, "amount": { "type": "integer", "format": "int64", "description": "Amount settled for this commission (in smallest currency unit)" } } }, "get_settlements_response_settlement_view": { "type": "object", "required": [ "status", "reconciliation_status", "total_amount", "commission_amounts" ], "properties": { "status": { "$ref": "#/components/schemas/get_settlements_response_settlement_status", "description": "Current status of the settlement as a typed object. Use the 'type' discriminator field to determine the variant; cancelled and disputed variants carry an additional 'reason' field." }, "reconciliation_status": { "type": "string", "description": "Reconciliation status of the settlement (reconciled, unreconciled)" }, "invoice_reference": { "type": "string", "nullable": true, "description": "Invoice reference set by link_invoice" }, "credit_note_reference": { "type": "string", "nullable": true, "description": "Credit note reference set by link_credit_note" }, "report_reference": { "type": "string", "nullable": true, "description": "Report reference set by link_report" }, "payment_reference": { "type": "string", "nullable": true, "description": "Payment reference set when payment is initiated (self-payout path only)" }, "paid_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the settlement was paid" }, "disputed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the settlement was disputed" }, "created_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the settlement was created" }, "total_amount": { "type": "integer", "format": "int64", "description": "Sum of all commission amounts in this settlement" }, "commission_amounts": { "type": "array", "description": "Per-commission amount lines", "items": { "$ref": "#/components/schemas/get_settlements_response_commission_amount" } } } }, "get_settlements_response_settlement": { "type": "object", "required": [ "id", "customer_id", "workspace_id", "partner_id", "currency", "view" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the settlement" }, "customer_id": { "type": "string", "format": "uuid", "description": "ID of the customer this settlement belongs to" }, "workspace_id": { "type": "string", "format": "uuid", "description": "ID of the workspace this settlement belongs to" }, "partner_id": { "type": "string", "format": "uuid", "description": "ID of the partner this settlement belongs to" }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. EUR, USD)" }, "view": { "$ref": "#/components/schemas/get_settlements_response_settlement_view" } } }, "get_settlements_response": { "type": "object", "required": [ "settlements", "total", "page", "per_page" ], "properties": { "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/get_settlements_response_settlement" } }, "total": { "type": "integer", "format": "int64", "description": "Total number of settlements matching the query" }, "page": { "type": "integer", "format": "int64", "description": "Current page number" }, "per_page": { "type": "integer", "format": "int64", "description": "Number of items per page" } } }, "create_settlement_request": { "type": "object", "required": [ "customer_id", "workspace_id", "partner_id", "commission_ids" ], "properties": { "customer_id": { "type": "string", "format": "uuid", "description": "ID of the customer this settlement belongs to" }, "workspace_id": { "type": "string", "format": "uuid", "description": "ID of the workspace this settlement belongs to" }, "partner_id": { "type": "string", "format": "uuid", "description": "ID of the partner to settle commissions for" }, "commission_ids": { "type": "array", "description": "IDs of the commissions to include in this settlement", "items": { "type": "string", "format": "uuid" } } } }, "create_settlement_response": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the created settlement" } } }, "review_settlement_request": { "type": "object", "required": [ "resolution" ], "properties": { "resolution": { "type": "string", "enum": [ "credit" ], "description": "How to resolve the negative-review settlement: credit = issue a credit note to the partner." } } }, "permission_create_api_key": { "type": "object", "description": "Permission to create API keys.", "properties": { "permission_type": { "type": "string", "enum": [ "create_api_key" ] } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_update_api_key": { "type": "object", "description": "Permission to update API keys.", "properties": { "permission_type": { "enum": [ "update_api_key" ] }, "key_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "nullable": true } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_delete_api_key": { "type": "object", "description": "Permission to delete API keys.", "properties": { "permission_type": { "enum": [ "delete_api_key" ] }, "key_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "nullable": true } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_view_api_keys": { "type": "object", "description": "Permission to view API keys.", "properties": { "permission_type": { "enum": [ "view_api_keys" ] } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_create_attribution": { "type": "object", "description": "Permission to create attributions.", "properties": { "permission_type": { "enum": [ "create_attribution" ] } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_update_attribution": { "type": "object", "description": "Permission to update attributions.", "properties": { "permission_type": { "enum": [ "update_attribution" ] }, "attribution_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "nullable": true } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_cancel_attribution": { "type": "object", "description": "Permission to cancel attributions.", "properties": { "permission_type": { "enum": [ "cancel_attribution" ] }, "attribution_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "nullable": true } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_view_attributions": { "type": "object", "description": "Permission to view attributions.", "properties": { "permission_type": { "enum": [ "view_attributions" ] } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_create_attribution_schema": { "type": "object", "description": "Permission to create attribution schemas.", "properties": { "permission_type": { "enum": [ "create_attribution_schema" ] } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_update_attribution_schema": { "type": "object", "description": "Permission to update attribution schemas.", "properties": { "permission_type": { "enum": [ "update_attribution_schema" ] }, "schema_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "nullable": true } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_delete_attribution_schema": { "type": "object", "description": "Permission to delete attribution schemas.", "properties": { "permission_type": { "enum": [ "delete_attribution_schema" ] }, "schema_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "nullable": true } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_view_attribution_schemas": { "type": "object", "description": "Permission to view attribution schemas.", "properties": { "permission_type": { "enum": [ "view_attribution_schemas" ] } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_create_partner": { "type": "object", "description": "Permission to create partners.", "properties": { "permission_type": { "enum": [ "create_partner" ] } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_update_partner": { "type": "object", "description": "Permission to update partners.", "properties": { "permission_type": { "enum": [ "update_partner" ] }, "partner_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "nullable": true } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_delete_partner": { "type": "object", "description": "Permission to delete partners.", "properties": { "permission_type": { "enum": [ "delete_partner" ] }, "partner_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "nullable": true } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_view_partners": { "type": "object", "description": "Permission to view partners.", "properties": { "permission_type": { "enum": [ "view_partners" ] } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_create_commission": { "type": "object", "description": "Permission to create commissions.", "properties": { "permission_type": { "enum": [ "create_commission" ] } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_update_commission": { "type": "object", "description": "Permission to update commissions.", "properties": { "permission_type": { "enum": [ "update_commission" ] }, "commission_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "nullable": true } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_delete_commission": { "type": "object", "description": "Permission to delete commissions.", "properties": { "permission_type": { "enum": [ "delete_commission" ] }, "commission_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "nullable": true } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_view_commissions": { "type": "object", "description": "Permission to view commissions.", "properties": { "permission_type": { "enum": [ "view_commissions" ] } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_create_commission_formula": { "type": "object", "description": "Permission to create commission formulas.", "properties": { "permission_type": { "enum": [ "create_commission_formula" ] } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_update_commission_formula": { "type": "object", "description": "Permission to update commission formulas.", "properties": { "permission_type": { "enum": [ "update_commission_formula" ] }, "commission_formula_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "nullable": true } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_delete_commission_formula": { "type": "object", "description": "Permission to delete commission formulas.", "properties": { "permission_type": { "enum": [ "delete_commission_formula" ] }, "commission_formula_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "nullable": true } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_view_commission_formulas": { "type": "object", "description": "Permission to view commission formulas.", "properties": { "permission_type": { "enum": [ "view_commission_formulas" ] } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_create_settlement": { "type": "object", "description": "Permission to create settlements.", "properties": { "permission_type": { "enum": [ "create_settlement" ] } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_update_settlement": { "type": "object", "description": "Permission to update settlements.", "properties": { "permission_type": { "enum": [ "update_settlement" ] }, "settlement_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "nullable": true } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_delete_settlement": { "type": "object", "description": "Permission to delete settlements.", "properties": { "permission_type": { "enum": [ "delete_settlement" ] }, "settlement_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "nullable": true } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_view_settlements": { "type": "object", "description": "Permission to view settlements.", "properties": { "permission_type": { "enum": [ "view_settlements" ] } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_create_workspace": { "type": "object", "description": "Permission to create workspaces.", "properties": { "permission_type": { "enum": [ "create_workspace" ] } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_view_workspaces": { "type": "object", "description": "Permission to view workspaces.", "properties": { "permission_type": { "enum": [ "view_workspaces" ] } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_delete_workspace": { "type": "object", "description": "Permission to delete workspaces.", "properties": { "permission_type": { "enum": [ "delete_workspace" ] }, "workspace_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "nullable": true } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_invite_member": { "type": "object", "description": "Permission to invite members to customers.", "properties": { "permission_type": { "enum": [ "invite_member" ] } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_remove_member": { "type": "object", "description": "Permission to remove members from customers.", "properties": { "permission_type": { "enum": [ "remove_member" ] } }, "required": [ "permission_type" ], "additionalProperties": false }, "permission_delete_invite": { "type": "object", "description": "Permission to delete invitations.", "properties": { "permission_type": { "enum": [ "delete_invite" ] } }, "required": [ "permission_type" ], "additionalProperties": false }, "permissions": { "type": "object", "description": "A permission covering various resource actions across the platform.", "discriminator": { "propertyName": "permission_type", "mapping": { "create_api_key": "#/components/schemas/permission_create_api_key", "update_api_key": "#/components/schemas/permission_update_api_key", "delete_api_key": "#/components/schemas/permission_delete_api_key", "view_api_keys": "#/components/schemas/permission_view_api_keys", "create_attribution": "#/components/schemas/permission_create_attribution", "update_attribution": "#/components/schemas/permission_update_attribution", "cancel_attribution": "#/components/schemas/permission_cancel_attribution", "view_attributions": "#/components/schemas/permission_view_attributions", "create_attribution_schema": "#/components/schemas/permission_create_attribution_schema", "update_attribution_schema": "#/components/schemas/permission_update_attribution_schema", "delete_attribution_schema": "#/components/schemas/permission_delete_attribution_schema", "view_attribution_schemas": "#/components/schemas/permission_view_attribution_schemas", "create_partner": "#/components/schemas/permission_create_partner", "update_partner": "#/components/schemas/permission_update_partner", "delete_partner": "#/components/schemas/permission_delete_partner", "view_partners": "#/components/schemas/permission_view_partners", "create_commission": "#/components/schemas/permission_create_commission", "update_commission": "#/components/schemas/permission_update_commission", "delete_commission": "#/components/schemas/permission_delete_commission", "view_commissions": "#/components/schemas/permission_view_commissions", "create_commission_formula": "#/components/schemas/permission_create_commission_formula", "update_commission_formula": "#/components/schemas/permission_update_commission_formula", "delete_commission_formula": "#/components/schemas/permission_delete_commission_formula", "view_commission_formulas": "#/components/schemas/permission_view_commission_formulas", "create_settlement": "#/components/schemas/permission_create_settlement", "update_settlement": "#/components/schemas/permission_update_settlement", "delete_settlement": "#/components/schemas/permission_delete_settlement", "view_settlements": "#/components/schemas/permission_view_settlements", "create_workspace": "#/components/schemas/permission_create_workspace", "view_workspaces": "#/components/schemas/permission_view_workspaces", "delete_workspace": "#/components/schemas/permission_delete_workspace", "invite_member": "#/components/schemas/permission_invite_member", "remove_member": "#/components/schemas/permission_remove_member", "delete_invite": "#/components/schemas/permission_delete_invite" } }, "oneOf": [ { "$ref": "#/components/schemas/permission_create_api_key" }, { "$ref": "#/components/schemas/permission_update_api_key" }, { "$ref": "#/components/schemas/permission_delete_api_key" }, { "$ref": "#/components/schemas/permission_view_api_keys" }, { "$ref": "#/components/schemas/permission_create_attribution" }, { "$ref": "#/components/schemas/permission_update_attribution" }, { "$ref": "#/components/schemas/permission_cancel_attribution" }, { "$ref": "#/components/schemas/permission_view_attributions" }, { "$ref": "#/components/schemas/permission_create_attribution_schema" }, { "$ref": "#/components/schemas/permission_update_attribution_schema" }, { "$ref": "#/components/schemas/permission_delete_attribution_schema" }, { "$ref": "#/components/schemas/permission_view_attribution_schemas" }, { "$ref": "#/components/schemas/permission_create_partner" }, { "$ref": "#/components/schemas/permission_update_partner" }, { "$ref": "#/components/schemas/permission_delete_partner" }, { "$ref": "#/components/schemas/permission_view_partners" }, { "$ref": "#/components/schemas/permission_create_commission" }, { "$ref": "#/components/schemas/permission_update_commission" }, { "$ref": "#/components/schemas/permission_delete_commission" }, { "$ref": "#/components/schemas/permission_view_commissions" }, { "$ref": "#/components/schemas/permission_create_commission_formula" }, { "$ref": "#/components/schemas/permission_update_commission_formula" }, { "$ref": "#/components/schemas/permission_delete_commission_formula" }, { "$ref": "#/components/schemas/permission_view_commission_formulas" }, { "$ref": "#/components/schemas/permission_create_settlement" }, { "$ref": "#/components/schemas/permission_update_settlement" }, { "$ref": "#/components/schemas/permission_delete_settlement" }, { "$ref": "#/components/schemas/permission_view_settlements" }, { "$ref": "#/components/schemas/permission_create_workspace" }, { "$ref": "#/components/schemas/permission_view_workspaces" }, { "$ref": "#/components/schemas/permission_delete_workspace" }, { "$ref": "#/components/schemas/permission_invite_member" }, { "$ref": "#/components/schemas/permission_remove_member" }, { "$ref": "#/components/schemas/permission_delete_invite" } ] }, "get_api_keys_response_api_key": { "type": "object", "required": [ "id", "customer_id", "name", "created_at", "permissions" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "API key ID" }, "customer_id": { "type": "string", "format": "uuid", "description": "ID of the customer that owns this API key" }, "name": { "type": "string", "description": "Human-readable name for the API key" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the API key was created" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Optional expiration datetime" }, "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/permissions" }, "description": "Permissions associated with this API key" } } }, "get_api_keys_response": { "type": "object", "required": [ "api_keys", "total", "page", "per_page" ], "properties": { "api_keys": { "type": "array", "items": { "$ref": "#/components/schemas/get_api_keys_response_api_key" } }, "total": { "type": "integer", "description": "Total number of API keys matching the query" }, "page": { "type": "integer", "description": "Current page number" }, "per_page": { "type": "integer", "description": "Number of API keys returned per page" } } }, "create_api_key_request": { "type": "object", "required": [ "customer_id", "name" ], "properties": { "customer_id": { "type": "string", "format": "uuid", "description": "ID of the customer this API key belongs to" }, "name": { "type": "string", "description": "Human-readable name for the API key" }, "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/permissions" }, "description": "Permissions associated with this API key" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Optional expiration datetime for the API key" } } }, "create_api_key_response": { "type": "object", "required": [ "api_key_id", "secret" ], "properties": { "api_key_id": { "type": "string", "format": "uuid", "description": "ID of the newly created API key" }, "secret": { "type": "string", "description": "The raw secret token. Store securely — shown only once." } } }, "subscription_plan": { "type": "object", "required": [ "id", "name", "description", "prices", "attribution_limit", "partner_limit", "workspace_limit" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "prices": { "type": "array", "items": { "type": "object", "required": [ "id", "interval", "frequency", "amount", "currencyCode", "has_trial" ], "properties": { "id": { "type": "string" }, "interval": { "enum": [ "monthly", "yearly" ], "type": "string" }, "frequency": { "type": "integer" }, "amount": { "type": "integer" }, "currencyCode": { "type": "string" }, "has_trial": { "type": "boolean", "description": "Whether this price has a trial period available. True when a trial price variant exists for this price." }, "trial_period_days": { "type": "integer", "nullable": true, "description": "Number of trial days available for this price. Null when has_trial is false." } } } }, "attribution_limit": { "type": "integer" }, "partner_limit": { "type": "integer" }, "workspace_limit": { "type": "integer" } } }, "get_plans_response": { "type": "array", "items": { "$ref": "#/components/schemas/subscription_plan" } }, "subscription": { "type": "object", "required": [ "plan", "customerId", "startDate", "status" ], "properties": { "plan": { "$ref": "#/components/schemas/subscription_plan" }, "customerId": { "type": "string", "format": "uuid" }, "startDate": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "trialing", "active", "paused", "past_due", "cancelled" ] }, "trialEndsAt": { "type": "string", "format": "date-time", "nullable": true }, "endsAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When a cancelled subscription's access expires (end of the paid billing period)." } } }, "invoice": { "type": "object", "required": [ "id", "customerId", "amount", "currencyCode", "date", "status" ], "properties": { "id": { "type": "string" }, "customerId": { "type": "string", "format": "uuid" }, "amount": { "type": "integer" }, "currencyCode": { "type": "string" }, "date": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "draft", "billed", "paid", "canceled", "past_due" ] }, "checkoutUrl": { "type": "string", "format": "uri", "description": "URL to view/pay the invoice online" } } }, "get_invoices_response": { "type": "object", "required": [ "invoices", "total", "page", "per_page" ], "properties": { "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/invoice" } }, "total": { "type": "integer", "description": "Total number of invoices matching the query" }, "page": { "type": "integer", "description": "Current page number" }, "per_page": { "type": "integer", "description": "Number of invoices returned per page" } } }, "get_invoice_file_url_response": { "type": "object", "required": [ "fileUrl" ], "properties": { "fileUrl": { "type": "string", "description": "URL to the invoice PDF file" } } }, "subscribe_response": { "title": "SubscribeResponse", "type": "object", "properties": { "checkout_url": { "type": "string", "nullable": true, "description": "A hosted checkout URL to present to the customer when a new subscription must be initiated through a payment flow (Lemon Squeezy). Null when an existing subscription was updated server-side and no further customer action is required." } } }, "search_response": { "type": "object", "required": [ "partners", "partners_total", "attribution_schemas", "attribution_schemas_total" ], "properties": { "partners": { "type": "array", "description": "Matching partners", "items": { "$ref": "#/components/schemas/get_partners_response_partner" } }, "partners_total": { "type": "integer", "description": "Total number of matching partners" }, "attribution_schemas": { "type": "array", "description": "Matching attribution schemas", "items": { "$ref": "#/components/schemas/get_attribution_schemas_response_attribution_schema" } }, "attribution_schemas_total": { "type": "integer", "description": "Total number of matching attribution schemas" } } } } } }