{ "openapi": "3.1.0", "info": { "title": "Refersion API", "version": "3.0.0", "description": "The Refersion REST API. Requests carry a Bearer token in the `Authorization` header — either a merchant JWT or an OAuth `client_credentials` access token obtained from the `/oauth/token` endpoint on the auth service. See the [Authentication tutorial](/docs/api-reference/authentication) for how to generate credentials, exchange them for an access token, and call the API." }, "servers": [ { "url": "https://api.refersion.com/v2026-08", "description": "main" } ], "tags": [ { "name": "/webhooks" }, { "name": "/session" }, { "name": "/clicks" }, { "name": "/offers" }, { "name": "/promotion-methods" }, { "name": "/affiliates" }, { "name": "/account/settings" }, { "name": "/prospects" }, { "name": "/conversions" }, { "name": "/orders" }, { "name": "/static" } ], "security": [ { "http": [] } ], "paths": { "/account/settings/exclusions": { "get": { "operationId": "settingsExclusions.get", "description": "Retrieves paginated active exclusions for the authenticated client account,\nfiltered by type (ip, coupon, or sku) with optional search.\n\n**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Get Exclusions", "tags": [ "/account/settings" ], "parameters": [ { "name": "type", "in": "query", "required": true, "description": "The exclusion type to retrieve", "schema": { "type": "string" }, "example": "ip" }, { "name": "page", "in": "query", "description": "Page number for pagination (1-indexed)", "schema": { "type": "integer" }, "example": 1 }, { "name": "limit", "in": "query", "description": "Number of items per page", "schema": { "type": "integer" }, "example": 50 }, { "name": "search", "in": "query", "description": "Search string to filter exclusions", "schema": { "type": "string" }, "example": "192.168" } ], "responses": { "200": { "description": "Exclusions retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetExclusionsResource" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "message": "The type parameter is required.", "errors": { "type": [ "The type parameter is required." ] } }, "summary": null, "description": null, "externalValue": null } ], "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "429": { "description": "**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 300 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Unexpected error occurred while retrieving exclusions" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Unexpected error occurred while retrieving exclusions" } }, "required": [ "error" ] } } } } } }, "post": { "operationId": "settingsExclusions.post", "description": "Creates a new exclusion of the given `type` (ip, coupon, or sku) for the\nauthenticated client. The fields required in the request body depend on\nthe type: `ip` for ip, `couponCode` (and optional `couponDescription`) for\ncoupon, `sku` (and optional `nameLabel`) for sku.\n\n**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Create Exclusion", "tags": [ "/account/settings" ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreateExclusionRequest" }, { "type": "object", "properties": { "couponCode": { "type": [ "string", "null" ], "description": "Coupon code to exclude. Required when type=coupon; omit otherwise.", "example": null, "default": null }, "couponDescription": { "type": [ "string", "null" ], "description": "Optional description for a coupon exclusion. Only valid when type=coupon.", "example": null, "default": null }, "sku": { "type": [ "string", "null" ], "description": "Product SKU to exclude. Required when type=sku; omit otherwise.", "example": null, "default": null }, "nameLabel": { "type": [ "string", "null" ], "description": "Optional user-friendly label for a SKU exclusion. Only valid when type=sku.", "example": null, "default": null } } } ] } } } }, "responses": { "201": { "description": "SKU exclusion created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SkuExclusionResource" } }, "required": [ "data" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "402": { "description": "Billing plan limit reached for SKU exclusions", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Your plan limit for exclusions has been reached." }, "summary": null, "description": null, "externalValue": null } ] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "message": "The exclusion type is required.", "errors": { "type": [ "The exclusion type is required." ] } }, "summary": null, "description": null, "externalValue": null } ], "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "429": { "description": "**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 60 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Failed to create exclusion" }, "summary": null, "description": null, "externalValue": null } ] } } } } } } }, "/account/settings/exclusions/{id}": { "delete": { "operationId": "settingsExclusions.delete", "description": "Soft-deletes an exclusion (ip, coupon, or sku) by setting its status to\nDISABLED. The `type` must be supplied as a query parameter to identify\nwhich exclusion table owns the given id.\n\n**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Delete Exclusion", "tags": [ "/account/settings" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "type", "in": "query", "required": true, "description": "The exclusion type to delete. Must be one of the supported types.", "schema": { "type": "string" }, "example": "ip" } ], "responses": { "204": { "description": "Exclusion deleted successfully" }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "404": { "description": "Exclusion not found", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Exclusion not found" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Exclusion not found" } }, "required": [ "error" ] } } } }, "422": { "description": "Invalid type", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "message": "The exclusion type must be one of: ip, coupon, sku.", "errors": { "type": [ "The exclusion type must be one of: ip, coupon, sku." ] } }, "summary": null, "description": null, "externalValue": null } ], "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "429": { "description": "**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 60 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Failed to delete exclusion" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Failed to delete exclusion" } }, "required": [ "error" ] } } } } } } }, "/affiliates/count": { "get": { "operationId": "affiliate.count", "description": "Returns the count of affiliates grouped by status (pending, approved, denied)\nfor the authenticated merchant. The deniedCount includes BANNED affiliates —\nbanned affiliates are counted within the denied bucket. When called without\nfilter parameters, results are cached for 1 minute.\n\nSupports the same filter parameters as GET /affiliates. When filters are supplied,\nthe cache is bypassed and counts reflect the filtered result set. Performance-specific\nfilters (the 34-parameter matrix across the pending, 30-day, and total buckets,\nplus hasPendingConversions and lastConversionDaysAgo) narrow only the approvedCount;\npendingCount and deniedCount are not affected by those filters.\n\n**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Get Affiliate Counts", "tags": [ "/affiliates" ], "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 255 } }, { "name": "hasPendingConversions", "in": "query", "schema": { "type": "boolean" } }, { "name": "lastConversionDaysAgo", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "pendingRevenueMin", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "pendingRevenueMax", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "pendingCommissionMin", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "pendingCommissionMax", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "pendingConversionsMin", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "pendingConversionsMax", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "pendingPayoutsMin", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "pendingPayoutsMax", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "pendingUniqueOrdersMin", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "pendingUniqueOrdersMax", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "last30DaysRevenueMin", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "last30DaysRevenueMax", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "last30DaysCommissionMin", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "last30DaysCommissionMax", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "last30DaysConversionsMin", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "last30DaysConversionsMax", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "last30DaysPayoutsMin", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "last30DaysPayoutsMax", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "last30DaysClicksMin", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "last30DaysClicksMax", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "last30DaysUniqueOrdersMin", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "last30DaysUniqueOrdersMax", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "totalRevenueMin", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "totalRevenueMax", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "totalCommissionMin", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "totalCommissionMax", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "totalConversionsMin", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "totalConversionsMax", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "totalPayoutsMin", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "totalPayoutsMax", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "totalClicksMin", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "totalClicksMax", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "totalUniqueOrdersMin", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "totalUniqueOrdersMax", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "offerIds[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 1 } } }, { "name": "revenueMin", "in": "query", "schema": { "type": "string" } }, { "name": "revenueMax", "in": "query", "schema": { "type": "string" } }, { "name": "conversionsLast30DaysMin", "in": "query", "schema": { "type": "string" } }, { "name": "conversionsLast30DaysMax", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Affiliate counts retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AffiliateCountResource" } }, "required": [ "data" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "422": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "The revenueMin parameter has been renamed to last30DaysRevenueMin." }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "The last30DaysRevenueMax must be greater than or equal to last30DaysRevenueMin." }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "The totalConversionsMin must be a valid integer." }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "The totalRevenueMin must be at least 0." }, "summary": null, "description": null, "externalValue": null } ], "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "429": { "description": "**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 300 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "An error occurred while retrieving affiliate counts" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "An error occurred while retrieving affiliate counts" } }, "required": [ "error" ] } } } } } } }, "/affiliates": { "get": { "operationId": "affiliate.index", "description": "Retrieves a paginated list of affiliates for the authenticated merchant.\nIncludes affiliate profile information, offer details, and performance metrics.\n\nSupports filtering by status, search term, performance metrics, and offer IDs.\nThe `status=approved` filter returns both regular APPROVED and locked-APPROVED\naffiliates; check the `locked` field on each record to distinguish them.\nThe `status=denied` filter returns both DENIED and BANNED affiliates; banned\nrecords expose `status: \"BANNED\"` so they can be distinguished per row.\n\n**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "List Affiliates", "tags": [ "/affiliates" ], "parameters": [ { "name": "status[]", "in": "query", "schema": { "type": "array", "enum": [ "pending", "approved", "denied" ], "items": { "type": "string", "enum": [ "pending", "approved", "denied" ] } } }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 255 } }, { "name": "hasPendingConversions", "in": "query", "schema": { "type": "boolean" } }, { "name": "lastConversionDaysAgo", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "pendingRevenueMin", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "pendingRevenueMax", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "pendingCommissionMin", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "pendingCommissionMax", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "pendingConversionsMin", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "pendingConversionsMax", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "pendingPayoutsMin", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "pendingPayoutsMax", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "pendingUniqueOrdersMin", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "pendingUniqueOrdersMax", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "last30DaysRevenueMin", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "last30DaysRevenueMax", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "last30DaysCommissionMin", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "last30DaysCommissionMax", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "last30DaysConversionsMin", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "last30DaysConversionsMax", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "last30DaysPayoutsMin", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "last30DaysPayoutsMax", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "last30DaysClicksMin", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "last30DaysClicksMax", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "last30DaysUniqueOrdersMin", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "last30DaysUniqueOrdersMax", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "totalRevenueMin", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "totalRevenueMax", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "totalCommissionMin", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "totalCommissionMax", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "totalConversionsMin", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "totalConversionsMax", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "totalPayoutsMin", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "totalPayoutsMax", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "totalClicksMin", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "totalClicksMax", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "totalUniqueOrdersMin", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "totalUniqueOrdersMax", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "offerIds[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 1 } } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "revenueMin", "in": "query", "schema": { "type": "string" } }, { "name": "revenueMax", "in": "query", "schema": { "type": "string" } }, { "name": "conversionsLast30DaysMin", "in": "query", "schema": { "type": "string" } }, { "name": "conversionsLast30DaysMax", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Affiliates retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AffiliateCollection" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "422": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "The revenueMin parameter has been renamed to last30DaysRevenueMin." }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "The last30DaysRevenueMax must be greater than or equal to last30DaysRevenueMin." }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "The totalConversionsMin must be a valid integer." }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "The totalRevenueMin must be at least 0." }, "summary": null, "description": null, "externalValue": null } ], "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "429": { "description": "**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 300 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "An error occurred while retrieving affiliates" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "An error occurred while retrieving affiliates" } }, "required": [ "error" ] } } } } } } }, "/affiliates/{id}/activity": { "get": { "operationId": "affiliate.activity", "description": "Retrieves weekly conversion, payment, and click activity for a specific affiliate\nmerged into a single timeline ordered by `date` descending and capped at 10 entries.\nEach source (conversion, payment, click) is independently bounded to the rolling\nlast 10 weeks and capped at 5 entries before the merge.\n\nThe response shape is polymorphic on `type`. Conversion entries include\n`conversionCount`, `total`, and `currency`; payment entries include\n`paidConversionCount`, `total`, and `currency`; click entries include `clickCount`\n(no `total` or `currency`).\n\n**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Get Affiliate Activity", "tags": [ "/affiliates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the affiliate", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Weekly conversion, payment, and click activity retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AffiliateActivityResource" } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "403": { "description": "Client does not own the affiliate", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "You do not have permission to access this affiliate" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "You do not have permission to access this affiliate" } }, "required": [ "error" ] } } } }, "404": { "description": "Affiliate not found", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Affiliate not found" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Affiliate not found" } }, "required": [ "error" ] } } } }, "429": { "description": "**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 300 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "An unexpected error occurred" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "An unexpected error occurred" } }, "required": [ "error" ] } } } } } } }, "/affiliates/{affiliateId}": { "patch": { "operationId": "affiliate.update", "description": "Updates an affiliate's details including status, lock state, offer assignment,\ncustom fields, URL configuration, merchant-assigned external identifier, and\nparent affiliate assignment. Supports partial updates - only the fields provided\nin the request body will be updated.\n\nAny transition between the valid public statuses (APPROVED, PENDING, DENIED) is permitted.\nTransitioning from APPROVED to DENIED is blocked if the affiliate has pending or unpaid conversions.\nSetting status to DELETED or DISABLED is not allowed via this endpoint — DISABLED is an\ninternal flag managed via the `locked` field, and deletion uses the DELETE endpoint.\n\nThe `locked` field abstracts the internal DISABLED state: `locked: true` locks an APPROVED\naffiliate, and `locked: false` unlocks it. `locked` is only accepted when the affiliate's\ncurrent status is APPROVED, and it cannot be combined with `status` in the same request.\n\nThe `parentAffiliateId` field accepts another affiliate ID owned by the authenticated\nclient. Passing `null` clears the existing parent relationship.\n\n**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Update Affiliate", "tags": [ "/affiliates" ], "parameters": [ { "name": "affiliateId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAffiliateRequest" } } } }, "responses": { "204": { "description": "Affiliate updated successfully" }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "At least one field must be provided" }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "Invalid custom field ID: 12345" }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "Invalid URL path format" }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "Cannot deny affiliate with pending or unpaid conversions" }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "locked and status cannot be updated in the same request" }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "locked can only be updated when the affiliate is approved" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "403": { "description": "Permission denied, or attempting to edit profile fields on a Plus or VIP affiliate", "content": { "application/json": { "schema": { "examples": [ { "value": { "error": "You do not have permission to modify this affiliate" }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "Plus affiliate profile fields cannot be changed" }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "VIP affiliate profile fields cannot be changed" }, "summary": null, "description": null, "externalValue": null } ], "anyOf": [ { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "string", "const": "You do not have permission to modify this affiliate" } }, "required": [ "error" ] } ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "examples": [ { "value": { "error": "Affiliate not found" }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "Offer not found" }, "summary": null, "description": null, "externalValue": null } ], "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "const": "Offer not found" } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "string", "const": "Affiliate not found" } }, "required": [ "error" ] } ] } } } }, "422": { "description": "Validation failure", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "message": "The email field must be a valid email address.", "errors": { "email": [ "The email field must be a valid email address." ] } }, "summary": null, "description": null, "externalValue": null }, { "value": { "message": "parentAffiliateId may not be set to the affiliate's own id.", "errors": { "parentAffiliateId": [ "parentAffiliateId may not be set to the affiliate's own id." ] } }, "summary": null, "description": null, "externalValue": null }, { "value": { "message": "parentAffiliateId must reference an existing, non-deleted affiliate that belongs to the authenticated client.", "errors": { "parentAffiliateId": [ "parentAffiliateId must reference an existing, non-deleted affiliate that belongs to the authenticated client." ] } }, "summary": null, "description": null, "externalValue": null }, { "value": { "message": "parentAffiliateId would create a circular parent relationship.", "errors": { "parentAffiliateId": [ "parentAffiliateId would create a circular parent relationship." ] } }, "summary": null, "description": null, "externalValue": null } ], "properties": { "message": { "type": "string" }, "errors": { "type": "string" } }, "required": [ "message", "errors" ] } } } }, "429": { "description": "**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 60 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Internal server error" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Internal server error" } }, "required": [ "error" ] } } } } } } }, "/affiliates/{affiliateId}/link": { "get": { "operationId": "affiliate.getLink", "description": "Generates an affiliate tracking link for the specified affiliate.\n\nWhen the affiliate ID is set to 0, the endpoint uses the default test affiliate for the account.\n\nOptional parameters allow for test link generation, custom URLs, and marketing asset association.\n\n**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Generate Affiliate Tracking Link", "tags": [ "/affiliates" ], "parameters": [ { "name": "affiliateId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "affiliateId", "in": "query", "required": true, "description": "The affiliate ID for link generation", "schema": { "type": "integer" }, "example": 12345 }, { "name": "test", "in": "query", "description": "Generate a test link for test orders", "schema": { "type": "boolean" }, "example": true }, { "name": "url", "in": "query", "description": "Custom URL to use for the tracking link", "schema": { "type": "string" }, "example": "https://www.example.com" }, { "name": "marketingAssetId", "in": "query", "description": "Marketing asset ID (creative ID) for the link", "schema": { "type": "integer" }, "example": 789 }, { "name": "amazonProductId", "in": "query", "description": "Amazon product ID. When provided, the endpoint generates a refer.as redirect\nlink bound to the (affiliate, Amazon product) pair instead of the affiliate's\ndefault referral URL. Only valid when the client has the Amazon integration enabled.", "schema": { "type": "integer" }, "example": 12345 } ], "responses": { "200": { "description": "Affiliate link generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GetAffiliateLinkResource" } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid parameter format", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Invalid parameter format" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "examples": [ { "value": { "error": "Resource not found" }, "summary": null, "description": null, "externalValue": null } ], "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "const": "Resource not found" } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "string", "const": "Marketing asset not found" } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "string", "const": "Affiliate not found" } }, "required": [ "error" ] } ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "429": { "description": "**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 300 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Internal server error" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Internal server error" } }, "required": [ "error" ] } } } } } } }, "/affiliates/{affiliateId}/custom-fields": { "get": { "operationId": "affiliate.getCustomFields", "description": "Retrieves all custom registration fields configured by the merchant for a given affiliate,\nalong with the affiliate's corresponding values.\n\n**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Get Affiliate Custom Fields", "tags": [ "/affiliates" ], "parameters": [ { "name": "affiliateId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Custom fields retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAffiliateCustomFieldCollection" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "404": { "description": "Affiliate not found", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Affiliate not found" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Affiliate not found" } }, "required": [ "error" ] } } } }, "429": { "description": "**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 300 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Internal server error" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Internal server error" } }, "required": [ "error" ] } } } } } } }, "/affiliates/{affiliateId}/amazon-products": { "get": { "operationId": "affiliate.getAmazonProducts", "description": "Retrieves a paginated list of the authenticated merchant's Amazon-marketplace-enabled\nproducts, scoped to a verified affiliate of the same client. Each product includes the\ncombined product/variant name, image URL, and Amazon product URL.\n\n**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Get Affiliate Amazon Products", "tags": [ "/affiliates" ], "parameters": [ { "name": "affiliateId", "in": "path", "required": true, "description": "The unique identifier of the affiliate", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "Page number for pagination.", "schema": { "type": "integer" }, "example": 1 }, { "name": "limit", "in": "query", "description": "Number of items per page (max: 100).", "schema": { "type": "integer" }, "example": 50 } ], "responses": { "200": { "description": "Amazon products retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AmazonProductCollection" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "404": { "description": "Affiliate not found", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Affiliate not found" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Affiliate not found" } }, "required": [ "error" ] } } } }, "422": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "message": "The page must be at least 1.", "errors": { "page": [ "The page must be at least 1." ] } }, "summary": null, "description": null, "externalValue": null } ], "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "429": { "description": "**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 300 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Internal server error" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Internal server error" } }, "required": [ "error" ] } } } } } } }, "/affiliates/{affiliateId}/custom-fields/{customFieldId}": { "patch": { "operationId": "affiliate.patchCustomField", "description": "Updates an affiliate's value for a specific custom registration field\nby modifying the affiliate's custom_fields JSON column.\n\n**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Update Affiliate Custom Field Value", "tags": [ "/affiliates" ], "parameters": [ { "name": "affiliateId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "customFieldId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchAffiliateCustomFieldRequest" } } } }, "responses": { "204": { "description": "Custom field value updated successfully" }, "400": { "description": "Invalid value for dropdown field", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "The provided value is not a valid option for this field" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "examples": [ { "value": { "error": "Affiliate not found" }, "summary": null, "description": null, "externalValue": null } ], "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "const": "Custom field not found" } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "string", "const": "Affiliate not found" } }, "required": [ "error" ] } ] } } } }, "422": { "description": "Validation failure", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "The value field is required" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "429": { "description": "**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 60 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Internal server error" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Internal server error" } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "affiliate.deleteCustomField", "description": "Clears an affiliate's value for a specific custom registration field by removing\nthe entry from the affiliate's custom_fields JSON data. The custom field definition\nitself is not modified or deleted. This operation is idempotent.\n\n**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Delete Affiliate Custom Field Value", "tags": [ "/affiliates" ], "parameters": [ { "name": "affiliateId", "in": "path", "required": true, "description": "The affiliate ID", "schema": { "type": "integer" } }, { "name": "customFieldId", "in": "path", "required": true, "description": "The custom field ID to clear", "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Custom field value cleared successfully" }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "404": { "description": "Affiliate or custom field not found", "content": { "application/json": { "schema": { "examples": [ { "value": { "error": "Affiliate not found" }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "Custom field not found" }, "summary": null, "description": null, "externalValue": null } ], "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "const": "Custom field not found" } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "string", "const": "Affiliate not found" } }, "required": [ "error" ] } ] } } } }, "429": { "description": "**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 60 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Internal server error" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Internal server error" } }, "required": [ "error" ] } } } } } } }, "/affiliates/{id}": { "delete": { "operationId": "affiliate.destroy", "description": "Soft-deletes an affiliate by setting its status to DELETED. The affiliate\nmust not have any pending or unpaid conversions. Already-deleted or hidden\naffiliates are treated as not found.\n\n**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Delete Affiliate", "tags": [ "/affiliates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the affiliate", "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Affiliate deleted successfully" }, "400": { "description": "Affiliate has pending or unpaid conversions", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Cannot delete affiliate with pending or unpaid conversions" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Cannot delete affiliate with pending or unpaid conversions" } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "You do not have permission to delete this affiliate" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "You do not have permission to delete this affiliate" } }, "required": [ "error" ] } } } }, "404": { "description": "Affiliate not found", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Affiliate not found" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Affiliate not found" } }, "required": [ "error" ] } } } }, "429": { "description": "**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 60 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Internal server error" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Internal server error" } }, "required": [ "error" ] } } } } } } }, "/affiliates/{affiliateId}/welcome-email": { "post": { "operationId": "affiliate.resendWelcomeEmail", "description": "Resends the welcome email to an affiliate. The email type is determined by the\naffiliate's current status (ACTIVE, PENDING, or DENIED). The endpoint enforces\na 15-minute throttle between resends, verifies the email channel is active,\nand checks marketplace notification opt-out settings.\n\n**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Resend Welcome Email", "tags": [ "/affiliates" ], "parameters": [ { "name": "affiliateId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendWelcomeEmailRequest" } } } }, "responses": { "202": { "description": "Welcome email queued successfully", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "message": "Welcome email queued successfully" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "message": { "type": "string", "const": "Welcome email queued successfully" } }, "required": [ "message" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "404": { "description": "Affiliate not found", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Affiliate not found" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Affiliate not found" } }, "required": [ "error" ] } } } }, "422": { "description": "Email channel disabled or affiliate opted out", "content": { "application/json": { "schema": { "examples": [ { "value": { "error": "Email channel is disabled" }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "Affiliate has opted out of notifications" }, "summary": null, "description": null, "externalValue": null } ], "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "const": "Affiliate has opted out of notifications" } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "string", "const": "Email channel is disabled" } }, "required": [ "error" ] } ] } } } }, "429": { "description": "Welcome email was sent recently", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Welcome email was sent recently. Please wait before resending." }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Internal server error" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Internal server error" } }, "required": [ "error" ] } } } } } } }, "/clicks": { "get": { "operationId": "click.get", "description": "Retrieves click tracking data based on supplied query parameters. Returns click information\nincluding affiliate details, timestamps, IP addresses, user agents, and referral data.\nSupports pagination and filtering by date range and affiliate ID.\n\n**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Get Click Data", "tags": [ "/clicks" ], "parameters": [ { "name": "createdAtMin", "in": "query", "required": true, "description": "Minimum creation timestamp (inclusive) in ISO 8601 format", "schema": { "type": "string" }, "example": "2025-09-25T00:00:00Z" }, { "name": "createdAtMax", "in": "query", "required": true, "description": "Maximum creation timestamp (inclusive) in ISO 8601 format", "schema": { "type": "string" }, "example": "2025-09-25T23:59:59Z" }, { "name": "affiliateId", "in": "query", "description": "Filter clicks by affiliate ID", "schema": { "type": "integer" }, "example": 456 }, { "name": "page", "in": "query", "description": "Page number for pagination", "schema": { "type": "integer" }, "example": 1 }, { "name": "limit", "in": "query", "description": "Items per page for pagination", "schema": { "type": "integer" }, "example": 50 } ], "responses": { "200": { "description": "Click data retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClickCollection" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "422": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Invalid query parameters" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "429": { "description": "**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 300 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "An error occurred while retrieving clicks" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "An error occurred while retrieving clicks" } }, "required": [ "error" ] } } } } } } }, "/conversions/manual-credit": { "post": { "operationId": "manualCredit.post", "description": "Creates a manual credit conversion for an affiliate. Supports PENDING, APPROVED, and DENIED\nstatuses. For APPROVED and DENIED statuses, a notification is dispatched and a conversion_info\nrecord is created.\n\n**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Create Manual Credit", "tags": [ "/conversions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateManualCreditRequest" } } } }, "responses": { "201": { "description": "Manual credit created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ManualCreditResource" } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "examples": [ { "value": { "error": "Invalid request" }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "Affiliate is not eligible to receive new conversions" }, "summary": null, "description": null, "externalValue": null } ], "anyOf": [ { "type": "object", "properties": { "error": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "Invalid request" ] } ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "404": { "description": "Affiliate not found", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Affiliate not found" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Affiliate not found" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "The affiliateId field is required." }, "summary": null, "description": null, "externalValue": null } ], "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "429": { "description": "**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 60 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Failed to create manual credit", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Failed to create manual credit" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Failed to create manual credit" } }, "required": [ "error" ] } } } } } } }, "/conversions/credit-order-id": { "post": { "operationId": "creditOrderId.post", "description": "Credits an existing order from the conversion queue to a specified affiliate.\nThe order is queued for processing and will be converted asynchronously.\n\n**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Credit Order to Affiliate", "tags": [ "/conversions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditOrderIdRequest" } } } }, "responses": { "202": { "description": "Order credit queued for processing", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "message": "Order credit queued for processing" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "message": { "type": "string", "const": "Order credit queued for processing" } }, "required": [ "message" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "examples": [ { "value": { "error": "Invalid request" }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "Affiliate is not eligible to receive new conversions" }, "summary": null, "description": null, "externalValue": null } ], "anyOf": [ { "type": "object", "properties": { "error": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "Invalid request" ] } ] } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "examples": [ { "value": { "error": "Order not found" }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "Affiliate not found" }, "summary": null, "description": null, "externalValue": null } ], "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "const": "Affiliate not found" } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "string", "const": "Order not found" } }, "required": [ "error" ] } ] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "The conversionQueueId field is required." }, "summary": null, "description": null, "externalValue": null } ], "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "429": { "description": "**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 60 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Failed to queue order credit", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Failed to queue order credit" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Failed to queue order credit" } }, "required": [ "error" ] } } } } } } }, "/conversions/count": { "get": { "operationId": "conversion.count", "description": "Returns counts of conversions grouped by status (pending, approved, paid, denied,\nunqualified) for the authenticated merchant. Supports the same filters as the\nconversions list endpoint, excluding status, page, limit, sortBy, and sortOrder.\nUnfiltered requests are cached for 1 minute per client; filtered requests bypass\nthe cache.\n\n**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Get Conversion Counts", "tags": [ "/conversions" ], "parameters": [ { "name": "search", "in": "query", "description": "Search by order ID, conversion ID, or subscription ID. Minimum 3\ncharacters — leading-wildcard LIKE on `merchant_unique_id` and\n`merchant_subscription_id` cannot use an index, so short prefixes\ntrigger a full per-client substring scan that is too costly to\nserve as a typeahead.", "schema": { "type": "string" }, "example": "ORD-9001" }, { "name": "orderId", "in": "query", "description": "Prefix filter against `merchant_unique_id` — returns counts for conversions whose order ID starts with this value. Mirrors the list endpoint's `orderId` filter exactly.", "schema": { "type": "string" }, "example": "ORD-9001" }, { "name": "affiliateIds[]", "in": "query", "description": "Individual affiliate ID.", "schema": { "type": "array", "items": { "type": "integer" } }, "example": 789 }, { "name": "offerIds[]", "in": "query", "description": "Individual offer ID.", "schema": { "type": "array", "items": { "type": "integer" } }, "example": 987 }, { "name": "payoutIds[]", "in": "query", "description": "Individual payout ID.", "schema": { "type": "array", "items": { "type": "integer" } }, "example": 456 }, { "name": "createdAtMin", "in": "query", "description": "Minimum creation timestamp in ISO 8601 format (inclusive). A date-only value expands to the start of that day in the client timezone.", "schema": { "type": "string" }, "example": "2026-03-01T00:00:00Z" }, { "name": "createdAtMax", "in": "query", "description": "Maximum creation timestamp in ISO 8601 format (inclusive). A date-only value expands to the end of that day in the client timezone, and must resolve to an instant after the normalized createdAtMin.", "schema": { "type": "string" }, "example": "2026-03-31T23:59:59Z" } ], "responses": { "200": { "description": "Conversion counts retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ConversionCountResource" } }, "required": [ "data" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "422": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Invalid query parameters" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "429": { "description": "**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 300 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "An error occurred while retrieving conversion counts" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "An error occurred while retrieving conversion counts" } }, "required": [ "error" ] } } } } } } }, "/conversions": { "get": { "operationId": "conversion.index", "description": "Retrieves a paginated list of conversions for the authenticated merchant.\nSupports filtering by status, order ID, affiliate, date range, offer, and platform.\nSupports sorting by order ID, affiliate, type, revenue, commission, date, source, and status.\n\n**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "List Conversions", "tags": [ "/conversions" ], "parameters": [ { "name": "status", "in": "query", "description": "Filter by conversion status tab", "schema": { "type": "string" }, "example": "PENDING" }, { "name": "page", "in": "query", "description": "Page number for pagination", "schema": { "type": "integer" }, "example": 1 }, { "name": "limit", "in": "query", "description": "Number of items per page", "schema": { "type": "integer" }, "example": 50 }, { "name": "sortBy", "in": "query", "description": "Column to sort by. The affiliate option orders by displayed affiliate name:\ncompany when present, otherwise first and last name.", "schema": { "type": "string" }, "example": "date" }, { "name": "sortOrder", "in": "query", "description": "Sort direction", "schema": { "type": "string" }, "example": "desc" }, { "name": "orderId", "in": "query", "description": "Filter by order ID prefix — returns conversions whose order ID starts with this value (prefix match, not substring)", "schema": { "type": "string" }, "example": "ORD-12345" }, { "name": "affiliateIds[]", "in": "query", "description": "Individual affiliate ID", "schema": { "type": "array", "items": { "type": "integer" } }, "example": 100 }, { "name": "createdAtMin", "in": "query", "description": "Filter by creation date minimum in ISO 8601 format (inclusive). A date-only value expands to the start of that day in the client timezone.", "schema": { "type": "string" }, "example": "2026-01-01" }, { "name": "createdAtMax", "in": "query", "description": "Filter by creation date maximum in ISO 8601 format (inclusive). A date-only value expands to the end of that day in the client timezone, and must resolve to an instant after the normalized createdAtMin.", "schema": { "type": "string" }, "example": "2026-12-31" }, { "name": "offerIds[]", "in": "query", "description": "Individual offer ID", "schema": { "type": "array", "items": { "type": "integer" } }, "example": 1 }, { "name": "platform[]", "in": "query", "description": "Individual platform name", "schema": { "type": "array", "items": { "type": "string" } }, "example": "Shopify" } ], "responses": { "200": { "description": "Conversions retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversionCollection" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "422": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Invalid query parameters" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "429": { "description": "**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 300 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "An error occurred while retrieving conversions" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "An error occurred while retrieving conversions" } }, "required": [ "error" ] } } } } } } }, "/conversions/{id}": { "patch": { "operationId": "updateConversionStatus.patch", "description": "Updates the status of a single conversion. Supports transitions between\nPENDING, APPROVED, DENIED, and UNQUALIFIED statuses based on a defined\ntransition matrix. Creates an audit trail and dispatches webhook notifications\nfor APPROVED and DENIED transitions.\n\n**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Update Conversion Status", "tags": [ "/conversions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateConversionStatusRequest" } } } }, "responses": { "204": { "description": "Conversion status updated successfully" }, "400": { "description": "Invalid status change", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Cannot change status of a paid conversion" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "404": { "description": "Conversion not found", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Conversion not found" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Conversion not found" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "message": "The status field is required.", "errors": { "status": [ "The status field is required." ] } }, "summary": null, "description": null, "externalValue": null }, { "value": { "message": "The status must be one of: APPROVED, DENIED, UNQUALIFIED, PENDING.", "errors": { "status": [ "The status must be one of: APPROVED, DENIED, UNQUALIFIED, PENDING." ] } }, "summary": null, "description": null, "externalValue": null } ], "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "429": { "description": "**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 60 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Failed to update conversion status", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Failed to update conversion status" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Failed to update conversion status" } }, "required": [ "error" ] } } } } } }, "get": { "operationId": "conversionDetail.get", "description": "Retrieves the full detail view for a single conversion owned by the authenticated\nclient. The response includes affiliate info, offer info, click details, payment\nmethod, autoPay status, VIP status, and Amazon approval eligibility. Returns 404\nfor conversions that do not exist, are not owned by the authenticated client, or\nhave HIDDEN status.\n\n**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Get Conversion Detail", "tags": [ "/conversions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the conversion", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Conversion detail retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ConversionDetailResource" } }, "required": [ "data" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "404": { "description": "Conversion not found", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Conversion not found" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Conversion not found" } }, "required": [ "error" ] } } } }, "429": { "description": "**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 300 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "An error occurred while retrieving the conversion" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "An error occurred while retrieving the conversion" } }, "required": [ "error" ] } } } } } } }, "/offers": { "get": { "operationId": "offer.get", "description": "Retrieves a paginated list of offers for the authenticated client. Returns offer information\nincluding commission settings, attribution window, and various configuration options.\nSupports pagination, optional search filtering by offer name or ID, filtering by offer\ntype (multi-value, OR semantics), and performance-range filtering across 17 metrics\n(Min/Max bounds for the pending, 30-day, and total buckets).\n\n**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "List Offers", "tags": [ "/offers" ], "parameters": [ { "name": "type[]", "in": "query", "description": "Individual type value within the type array.", "schema": { "type": "array", "items": { "type": "string" } }, "example": "FLAT_RATE" }, { "name": "search", "in": "query", "description": "Search string to filter offers by name or ID", "schema": { "type": "string" }, "example": "My Offer" }, { "name": "pendingRevenueMin", "in": "query", "description": "Minimum total pending revenue in the authenticated client's default currency.", "schema": { "type": "number" }, "example": 100 }, { "name": "pendingRevenueMax", "in": "query", "description": "Maximum total pending revenue in the authenticated client's default currency.", "schema": { "type": "number" }, "example": 10000 }, { "name": "pendingCommissionMin", "in": "query", "description": "Minimum total pending commission in the authenticated client's default currency.", "schema": { "type": "number" }, "example": 10 }, { "name": "pendingCommissionMax", "in": "query", "description": "Maximum total pending commission in the authenticated client's default currency.", "schema": { "type": "number" }, "example": 1000 }, { "name": "pendingConversionsMin", "in": "query", "description": "Minimum total pending conversions count.", "schema": { "type": "integer" }, "example": 1 }, { "name": "pendingConversionsMax", "in": "query", "description": "Maximum total pending conversions count.", "schema": { "type": "integer" }, "example": 100 }, { "name": "pendingPayoutsMin", "in": "query", "description": "Minimum total pending payouts in the authenticated client's default currency.", "schema": { "type": "number" }, "example": 10 }, { "name": "pendingPayoutsMax", "in": "query", "description": "Maximum total pending payouts in the authenticated client's default currency.", "schema": { "type": "number" }, "example": 1000 }, { "name": "pendingUniqueOrdersMin", "in": "query", "description": "Minimum total pending unique orders count.", "schema": { "type": "integer" }, "example": 1 }, { "name": "pendingUniqueOrdersMax", "in": "query", "description": "Maximum total pending unique orders count.", "schema": { "type": "integer" }, "example": 100 }, { "name": "last30DaysRevenueMin", "in": "query", "description": "Minimum 30-day approved revenue in the authenticated client's default currency.", "schema": { "type": "number" }, "example": 100 }, { "name": "last30DaysRevenueMax", "in": "query", "description": "Maximum 30-day approved revenue in the authenticated client's default currency.", "schema": { "type": "number" }, "example": 10000 }, { "name": "last30DaysCommissionMin", "in": "query", "description": "Minimum 30-day approved commission in the authenticated client's default currency.", "schema": { "type": "number" }, "example": 10 }, { "name": "last30DaysCommissionMax", "in": "query", "description": "Maximum 30-day approved commission in the authenticated client's default currency.", "schema": { "type": "number" }, "example": 1000 }, { "name": "last30DaysConversionsMin", "in": "query", "description": "Minimum 30-day approved conversions count.", "schema": { "type": "integer" }, "example": 5 }, { "name": "last30DaysConversionsMax", "in": "query", "description": "Maximum 30-day approved conversions count.", "schema": { "type": "integer" }, "example": 100 }, { "name": "last30DaysPayoutsMin", "in": "query", "description": "Minimum 30-day approved payouts in the authenticated client's default currency.", "schema": { "type": "number" }, "example": 10 }, { "name": "last30DaysPayoutsMax", "in": "query", "description": "Maximum 30-day approved payouts in the authenticated client's default currency.", "schema": { "type": "number" }, "example": 1000 }, { "name": "last30DaysClicksMin", "in": "query", "description": "Minimum 30-day clicks count.", "schema": { "type": "integer" }, "example": 10 }, { "name": "last30DaysClicksMax", "in": "query", "description": "Maximum 30-day clicks count.", "schema": { "type": "integer" }, "example": 1000 }, { "name": "last30DaysUniqueOrdersMin", "in": "query", "description": "Minimum 30-day unique orders count.", "schema": { "type": "integer" }, "example": 1 }, { "name": "last30DaysUniqueOrdersMax", "in": "query", "description": "Maximum 30-day unique orders count.", "schema": { "type": "integer" }, "example": 100 }, { "name": "totalRevenueMin", "in": "query", "description": "Minimum total approved revenue in the authenticated client's default currency.", "schema": { "type": "number" }, "example": 100 }, { "name": "totalRevenueMax", "in": "query", "description": "Maximum total approved revenue in the authenticated client's default currency.", "schema": { "type": "number" }, "example": 100000 }, { "name": "totalCommissionMin", "in": "query", "description": "Minimum total commission in the authenticated client's default currency.", "schema": { "type": "number" }, "example": 10 }, { "name": "totalCommissionMax", "in": "query", "description": "Maximum total commission in the authenticated client's default currency.", "schema": { "type": "number" }, "example": 10000 }, { "name": "totalConversionsMin", "in": "query", "description": "Minimum total conversions count.", "schema": { "type": "integer" }, "example": 1 }, { "name": "totalConversionsMax", "in": "query", "description": "Maximum total conversions count.", "schema": { "type": "integer" }, "example": 10000 }, { "name": "totalPayoutsMin", "in": "query", "description": "Minimum total payouts in the authenticated client's default currency.", "schema": { "type": "number" }, "example": 10 }, { "name": "totalPayoutsMax", "in": "query", "description": "Maximum total payouts in the authenticated client's default currency.", "schema": { "type": "number" }, "example": 10000 }, { "name": "totalClicksMin", "in": "query", "description": "Minimum total clicks count.", "schema": { "type": "integer" }, "example": 100 }, { "name": "totalClicksMax", "in": "query", "description": "Maximum total clicks count.", "schema": { "type": "integer" }, "example": 100000 }, { "name": "totalUniqueOrdersMin", "in": "query", "description": "Minimum total unique orders count.", "schema": { "type": "integer" }, "example": 1 }, { "name": "totalUniqueOrdersMax", "in": "query", "description": "Maximum total unique orders count.", "schema": { "type": "integer" }, "example": 10000 }, { "name": "page", "in": "query", "description": "Page number for pagination (1-indexed)", "schema": { "type": "integer" }, "example": 1 }, { "name": "limit", "in": "query", "description": "Number of items per page", "schema": { "type": "integer" }, "example": 50 } ], "responses": { "200": { "description": "Offers retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfferCollection" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "422": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Invalid type. Allowed values: PERCENT_OF_SALE, FLAT_RATE, TIERED_AFFILIATE_SALES, TIERED_CONVERSION_COUNT" }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "The limit may not be greater than 100." }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "The page must be at least 1." }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "The totalRevenueMax must be greater than or equal to totalRevenueMin." }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "The totalConversionsMin must be a valid integer." }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "The totalRevenueMin must be at least 0." }, "summary": null, "description": null, "externalValue": null } ], "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "429": { "description": "**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 300 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "An error occurred while retrieving offers" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "An error occurred while retrieving offers" } }, "required": [ "error" ] } } } } } } }, "/offers/{offerId}": { "patch": { "operationId": "offer.patch", "description": "Updates an existing offer. Allows partial updates of one or more fields including\nname, default status, attribution window, private status, and commission.\nIf offerId is 0, the client's default offer will be updated.\n\n**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Update Offer", "tags": [ "/offers" ], "parameters": [ { "name": "offerId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOfferRequest" } } } }, "responses": { "204": { "description": "Offer updated successfully" }, "400": { "description": "Invalid field values or business rule violation", "content": { "application/json": { "schema": { "examples": [ { "value": { "error": "Cannot set both isDefault and isPrivate to true" }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "Cannot make the default offer private" }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "No valid fields to update" }, "summary": null, "description": null, "externalValue": null } ], "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "const": "Cannot make the default offer private" } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "string", "const": "No valid fields to update" } }, "required": [ "error" ] } ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "404": { "description": "Offer not found", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Offer not found" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Offer not found" } }, "required": [ "error" ] } } } }, "422": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "The given data was invalid." }, "summary": null, "description": null, "externalValue": null } ], "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "429": { "description": "**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 60 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Failed to update offer" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Failed to update offer" } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "offer.delete", "description": "Soft-deletes an offer owned by the authenticated client. The default offer\nand offers with assigned affiliates cannot be deleted. Refersion attempts to move a\nMarketplace listing that uses the deleted offer to the active default offer; with no active\ndefault offer, it attempts to turn the listing off.\n\n**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Delete Offer", "tags": [ "/offers" ], "parameters": [ { "name": "offerId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Offer deleted successfully" }, "400": { "description": "Business rule violation — default offer or offer with assigned affiliates", "content": { "application/json": { "schema": { "examples": [ { "value": { "error": "Cannot delete the default offer" }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "Cannot delete offer with assigned affiliates" }, "summary": null, "description": null, "externalValue": null } ], "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "const": "Cannot delete offer with assigned affiliates" } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "string", "const": "Cannot delete the default offer" } }, "required": [ "error" ] } ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "404": { "description": "Offer not found", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Offer not found" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Offer not found" } }, "required": [ "error" ] } } } }, "429": { "description": "**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 60 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Failed to delete offer", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Failed to delete offer" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Failed to delete offer" } }, "required": [ "error" ] } } } } } } }, "/offers/{offerId}/duplicate": { "post": { "operationId": "offer.duplicate", "description": "Duplicates an offer owned by the authenticated client. Returns the new offer ID.\n\n**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Duplicate Offer", "tags": [ "/offers" ], "parameters": [ { "name": "offerId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "201": { "description": "Offer duplicated successfully", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "id": 12345 }, "summary": null, "description": null, "externalValue": null } ], "properties": { "id": { "type": "integer" } }, "required": [ "id" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "404": { "description": "Offer not found", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Offer not found" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Offer not found" } }, "required": [ "error" ] } } } }, "429": { "description": "**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 60 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Failed to duplicate offer", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Failed to duplicate offer" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Failed to duplicate offer" } }, "required": [ "error" ] } } } } } } }, "/orders": { "get": { "operationId": "orders.get", "description": "Searches for orders by order ID and determines if an affiliate can be credited.\nReturns available orders and any other affiliates that already have conversions\nfor the same order.\n\n**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Search Orders", "tags": [ "/orders" ], "parameters": [ { "name": "search", "in": "query", "required": true, "description": "The order ID to search for.", "schema": { "type": "string" }, "example": "ORD-12345" }, { "name": "affiliateId", "in": "query", "required": true, "description": "The affiliate ID to check conversions against.", "schema": { "type": "integer" }, "example": 123456 } ], "responses": { "200": { "description": "Orders retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SearchOrdersResource" } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Invalid request" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "Invalid request" ] } ] } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "404": { "description": "Affiliate not found", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Affiliate not found" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Affiliate not found" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "The search field is required." }, "summary": null, "description": null, "externalValue": null } ], "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "429": { "description": "**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 300 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Failed to search orders", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Failed to search orders" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Failed to search orders" } }, "required": [ "error" ] } } } } } } }, "/promotion-methods": { "get": { "operationId": "promotionMethod.index", "description": "Retrieves a paginated list of promotion methods for the authenticated client.\nReturns promotion method information including type, trigger value, status, affiliate details, and creation date.\nBy default returns ACTIVE, PENDING, and DISABLED records (excludes DELETED).\nSupports pagination, filtering by affiliate (multi-value), type (multi-value), status (multi-value), and search term.\n\n**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "List Promotion Methods", "tags": [ "/promotion-methods" ], "parameters": [ { "name": "affiliateId[]", "in": "query", "description": "Individual affiliate ID within the affiliateId array.", "schema": { "type": "array", "items": { "type": "integer" } }, "example": 12345 }, { "name": "type[]", "in": "query", "description": "Individual type value within the type array.", "schema": { "type": "array", "items": { "type": "string" } }, "example": "COUPON" }, { "name": "status[]", "in": "query", "description": "Individual status value within the status array.", "schema": { "type": "array", "items": { "type": "string" } }, "example": "ACTIVE" }, { "name": "search", "in": "query", "description": "Search by promotion method value (coupon code, SKU, or email)", "schema": { "type": "string" }, "example": "10off" }, { "name": "page", "in": "query", "description": "Page number for pagination (1-indexed)", "schema": { "type": "integer" }, "example": 1 }, { "name": "limit", "in": "query", "description": "Number of items per page (max 100)", "schema": { "type": "integer" }, "example": 50 } ], "responses": { "200": { "description": "Promotion methods retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionMethodCollection" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "403": { "description": "Access denied to affiliate", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "You do not have permission to access this affiliate" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "You do not have permission to access this affiliate" } }, "required": [ "error" ] } } } }, "404": { "description": "Affiliate not found", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Affiliate not found" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Affiliate not found" } }, "required": [ "error" ] } } } }, "422": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Invalid type. Allowed values: COUPON, SKU, EMAIL" }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "Invalid status. Allowed values: ACTIVE, PENDING, DISABLED" }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "The limit may not be greater than 100." }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "Page must be a positive integer" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "429": { "description": "**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 300 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "An unexpected error occurred" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "An unexpected error occurred" } }, "required": [ "error" ] } } } } } }, "post": { "operationId": "promotionMethod.post", "description": "Creates a new promotion method (coupon, email, or SKU) for an affiliate.\n\nPromotion method values are unique per client across all affiliates — duplicates by\n(type, trigger) under one client return 400 regardless of which affiliate already owns them.\n\nCreating a `sku` promotion method is not available to API access tokens; a `sku` request is always\nrefused with 403. Create SKU promotion methods in the Refersion dashboard.\n\n**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Create Promotion Method", "tags": [ "/promotion-methods" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePromotionMethodRequest" } } } }, "responses": { "201": { "description": "Promotion method created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PromotionMethodResource" } }, "required": [ "data" ] } } } }, "400": { "description": "Promotion method already exists for this client", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Promotion method already exists" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Promotion method already exists" } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "403": { "description": "Not permitted to create this promotion method type", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Insufficient permissions to create SKU promotion methods" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Insufficient permissions to create SKU promotion methods" } }, "required": [ "error" ] } } } }, "404": { "description": "Affiliate not found", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Affiliate not found" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Affiliate not found" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "examples": [ { "value": { "error": "Coupon code is excluded" }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "Affiliate is not eligible for promotion methods" }, "summary": null, "description": null, "externalValue": null } ], "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "const": "Coupon code is excluded" } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "string", "const": "Affiliate is not eligible for promotion methods" } }, "required": [ "error" ] } ] } } } }, "429": { "description": "**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 60 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Failed to create promotion method", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Failed to create promotion method" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Failed to create promotion method" } }, "required": [ "error" ] } } } } } } }, "/promotion-methods/{id}": { "patch": { "operationId": "promotionMethod.patch", "description": "Activates a promotion method that is currently in PENDING status.\nOnly promotion methods owned by the authenticated client can be activated.\n\n**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Activate Pending Promotion Method", "tags": [ "/promotion-methods" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePromotionMethodRequest" } } } }, "responses": { "204": { "description": "Promotion method activated successfully" }, "400": { "description": "Invalid status value or promotion method not in PENDING status", "content": { "application/json": { "schema": { "examples": [ { "value": { "error": "The status must be: active." }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "Promotion method is not in PENDING status" }, "summary": null, "description": null, "externalValue": null } ], "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "const": "Promotion method is not in PENDING status" } }, "required": [ "error" ] }, { "type": "object", "properties": { "error": { "type": "string", "const": "The status must be: active." } }, "required": [ "error" ] } ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "404": { "description": "Promotion method not found", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Promotion method not found" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Promotion method not found" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "The status field is required." }, "summary": null, "description": null, "externalValue": null } ], "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "429": { "description": "**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 60 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Failed to activate promotion method", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Failed to activate promotion method" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Failed to activate promotion method" } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "promotionMethod.delete", "description": "Deletes a promotion method (conversion trigger) by its ID. The promotion method\nmust belong to the authenticated client's account.\n\n**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Delete Promotion Method", "tags": [ "/promotion-methods" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Promotion method deleted successfully" }, "400": { "description": "Coupon creation dispatch is already in progress", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Coupon creation dispatch is already in progress" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Coupon creation dispatch is already in progress" } }, "required": [ "error" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "404": { "description": "Promotion method not found", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Promotion method not found" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Promotion method not found" } }, "required": [ "error" ] } } } }, "429": { "description": "**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 60 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Failed to delete promotion method", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Failed to delete promotion method" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Failed to delete promotion method" } }, "required": [ "error" ] } } } } } } }, "/prospects": { "get": { "operationId": "prospect.get", "description": "Retrieves affiliate partner prospects for the authenticated client. The endpoint provides\nan asynchronous prospect discovery mechanism where the system processes and returns\npotential affiliate partners based on the authenticated client's business profile.\n\nQuery Parameters:\n- more: Set to true to request a new prospect discovery job\n- customerDescription: Description of the client's business (max 255 chars, used when creating a new job)\n- productCategories: Product categories the client sells (max 255 chars, used when creating a new job)\n- page: Page number for pagination (default: 1)\n- limit: Items per page for pagination (default: 10, max: 100)\n\nResponse Scenarios:\n1. Job Processing (PENDING): Returns status \"in_progress\" with HTTP 200\n2. New Job Created: Returns status \"in_progress\" with HTTP 202\n3. Prospects Available (SUCCESS): Returns array of prospects with HTTP 200\n4. Previous Job Failed: Returns failure status with retry instructions, HTTP 200\n\n**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "List Affiliate Partner Prospects", "tags": [ "/prospects" ], "parameters": [ { "name": "more", "in": "query", "description": "Request a new prospect discovery job. When set to true, a new job will always be\ncreated regardless of whether a previous job exists or is still processing.", "schema": { "type": "boolean" }, "example": true }, { "name": "customerDescription", "in": "query", "description": "Description of the client's business and target customers. Used to customize\nthe prospect discovery process when creating a new job.", "schema": { "type": "string" }, "example": "Fashion retailer targeting young adults interested in sustainable clothing" }, { "name": "productCategories", "in": "query", "description": "Product categories the client sells. Used to find relevant affiliate prospects\nwhen creating a new job.", "schema": { "type": "string" }, "example": "Footwear, Accessories, Sustainable Fashion" }, { "name": "page", "in": "query", "description": "Page number for pagination", "schema": { "type": "integer" }, "example": 1 }, { "name": "limit", "in": "query", "description": "Items per page for pagination", "schema": { "type": "integer" }, "example": 50 } ], "responses": { "200": { "description": "Prospects available or job in progress", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "data": [ { "id": 12345, "profileName": "Acme Outdoors Blog", "profileType": null, "platform": "Website", "url": "https://www.example.com/blog", "status": 1, "createdAt": "2025-11-05T17:36:21+00:00", "updatedAt": "2025-11-05T17:36:21+00:00" } ] }, "summary": null, "description": null, "externalValue": null } ], "properties": { "data": { "$ref": "#/components/schemas/ProspectResource" } }, "required": [ "data" ] } } } }, "202": { "description": "Prospect discovery job has been queued", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "status": "in_progress", "message": "Prospect discovery job has been queued" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "data": { "$ref": "#/components/schemas/GetProspectsStatusResource" } }, "required": [ "data" ] } } } }, "422": { "description": "Invalid query parameter", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "message": "The given data was invalid.", "errors": { "more": [ "The more field must be true or false." ] } }, "summary": null, "description": null, "externalValue": null }, { "value": { "message": "The given data was invalid.", "errors": { "customerDescription": [ "The customerDescription may not be greater than 255 characters." ] } }, "summary": null, "description": null, "externalValue": null }, { "value": { "message": "The given data was invalid.", "errors": { "productCategories": [ "The productCategories may not be greater than 255 characters." ] } }, "summary": null, "description": null, "externalValue": null } ], "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "429": { "description": "**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 300 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Failed to process request" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "data": { "$ref": "#/components/schemas/GetProspectsStatusResource" } }, "required": [ "data" ] } } } } } } }, "/prospects/{prospectId}/feedback": { "post": { "operationId": "prospectFeedback.post", "description": "Allows users to provide thumbs up/down feedback on AI-recommended prospects.\nNegative feedback requires a reason to help improve future recommendations.\nFeedback can be updated by submitting new feedback for the same prospect.\n\n**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Submit Prospect Feedback", "tags": [ "/prospects" ], "parameters": [ { "name": "prospectId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitProspectFeedbackRequest" } } } }, "responses": { "200": { "description": "Feedback updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProspectFeedbackResource" } }, "required": [ "data" ] } } } }, "201": { "description": "Feedback submitted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProspectFeedbackResource" } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid type or missing required reason", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "message": "The given data was invalid.", "errors": { "type": [ "The type field must be either positive or negative." ] } }, "summary": null, "description": null, "externalValue": null }, { "value": { "message": "The given data was invalid.", "errors": { "reason": [ "The reason field is required when type is negative." ] } }, "summary": null, "description": null, "externalValue": null } ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "404": { "description": "Prospect not found", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Prospect not found" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Prospect not found" } }, "required": [ "error" ] } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "message": "The given data was invalid.", "errors": { "reason": [ "The reason may not be greater than 1000 characters." ] } }, "summary": null, "description": null, "externalValue": null } ], "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "429": { "description": "**Rate limit:** 60 requests per minute per account and credential type, shared across all write endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 60 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Failed to submit feedback" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Failed to submit feedback" } }, "required": [ "error" ] } } } } } } }, "/prospects/{prospectId}/pitch": { "get": { "operationId": "prospectPitch.get", "description": "Retrieves or generates a personalized pitch message for contacting a prospect (partner).\nThe endpoint first attempts to retrieve an existing pitch from the database. If no pitch\nexists, it generates one using AI and saves it for future retrieval.\n\n**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Get Prospect Pitch", "tags": [ "/prospects" ], "parameters": [ { "name": "prospectId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Pitch retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProspectPitchResource" } }, "required": [ "data" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Authentication required" } }, "required": [ "error" ] } } } }, "404": { "description": "Prospect not found", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Prospect not found" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "message": { "type": "string", "const": "Prospect not found" } }, "required": [ "message" ] } } } }, "429": { "description": "**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 300 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Failed to generate pitch", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Failed to generate pitch" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Failed to generate pitch" } }, "required": [ "error" ] } } } } } } }, "/session/accounts": { "get": { "operationId": "session.accounts", "description": "Lists the merchant accounts this connection can act on: the accounts chosen when access was granted that are\nstill available to the signed-in user, the current account first and the others in the order they were chosen.\nAvailable only to access tokens issued to a user through Refersion sign-in.\n\n**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "List Session Accounts", "tags": [ "/session" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Session accounts listed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionAccountResourceCollection" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Authentication required" } }, "required": [ "error" ] } } } }, "403": { "description": "Credential type not permitted", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Access not permitted." }, "summary": null, "description": null, "externalValue": null }, { "value": { "error": "Invalid user type" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Access not permitted." } }, "required": [ "error" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "429": { "description": "**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 300 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Failed to retrieve session accounts", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Failed to retrieve session accounts" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Failed to retrieve session accounts" } }, "required": [ "error" ] } } } } } } }, "/static/timezones": { "get": { "operationId": "timezone.index", "description": "Retrieves a list of all active timezones with their display labels and IANA identifiers.\nResults are cached for improved performance.\n\n**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Get Timezones", "tags": [ "/static" ], "responses": { "200": { "description": "Timezones retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimezoneResourceCollection" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "429": { "description": "**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 300 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } } } } }, "/static/business-categories": { "get": { "operationId": "businessCategories.index", "description": "Retrieves a list of all active business categories for classification purposes.\nResults are cached for improved performance.\n\n**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Get Business Categories", "tags": [ "/static" ], "responses": { "200": { "description": "Business categories retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessCategoryResourceCollection" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "429": { "description": "**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 300 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } } } } }, "/static/countries/{countryTwoLetterCode}/states": { "get": { "operationId": "countryStates.get", "description": "Retrieves a list of states/provinces/subdivisions for a given country code.\nThe country code must be a valid ISO 3166-1 alpha-2 format (e.g., \"US\", \"CA\", \"GB\").\nResults are sorted alphabetically by state name and cached for improved performance.\n\n**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Get States by Country", "tags": [ "/static" ], "parameters": [ { "name": "countryTwoLetterCode", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "countryTwoLetterCode", "in": "query", "required": true, "description": "The ISO 3166-1 alpha-2 country code", "schema": { "type": "string" }, "example": "US" } ], "responses": { "200": { "description": "States retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/StateResourceCollection" } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid country code format", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Invalid country code format. Must be ISO 3166-1 alpha-2 format." }, "summary": null, "description": null, "externalValue": null } ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "404": { "description": "No states found", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "No states found" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "No states found" } }, "required": [ "error" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "429": { "description": "**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 300 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Failed to retrieve states", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Failed to retrieve states" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Failed to retrieve states" } }, "required": [ "error" ] } } } } } } }, "/static/product-categories": { "get": { "operationId": "productCategories.get", "description": "Retrieves a hierarchical list of Google product taxonomy categories\nfor product categorization. Results are cached for optimal performance.\n\n**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Get Product Categories", "tags": [ "/static" ], "responses": { "200": { "description": "Product categories retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProductCategoriesResource" } }, "required": [ "data" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "429": { "description": "**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 300 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Failed to retrieve product categories", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Failed to retrieve product categories" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Failed to retrieve product categories" } }, "required": [ "error" ] } } } } } } }, "/static/countries": { "get": { "operationId": "staticCountries.index", "description": "Retrieves a list of all active countries with their ISO 3166-1 alpha-2 codes and names.\nResults are cacheable on the client side.\n\n**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Get Countries", "tags": [ "/static" ], "responses": { "200": { "description": "Countries retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryResourceCollection" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "429": { "description": "**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 300 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Failed to retrieve countries", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Failed to retrieve countries" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Failed to retrieve countries" } }, "required": [ "error" ] } } } } } } }, "/static/currencies": { "get": { "operationId": "currencies.get", "description": "Retrieves a list of supported currencies with their codes, symbols,\nand formatting information. Results are cached for optimal performance.\n\n**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Get Currencies", "tags": [ "/static" ], "responses": { "200": { "description": "Currencies retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CurrencyResource" } }, "required": [ "data" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "429": { "description": "**Rate limit:** 300 requests per minute per account and credential type, shared across all read endpoints. Exceeding it returns 429 with a Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "example": { "error": "Rate limit of 300 requests per minute exceeded for this account. Retry after 42 seconds.", "retryAfter": 42 }, "properties": { "error": { "type": "string" }, "retryAfter": { "type": "integer" } }, "required": [ "error", "retryAfter" ] } } } }, "500": { "description": "Failed to retrieve currencies", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Failed to retrieve currencies" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Failed to retrieve currencies" } }, "required": [ "error" ] } } } } } } }, "/webhooks/endpoints": { "get": { "operationId": "webhooksEndpoints.get", "description": "Lists the webhook endpoints for the authenticated Refersion user.\nCursor-paginated. Some users may receive a 402 if their plan doesn't\ninclude webhook access. The user's webhook configuration is\nauto-provisioned on first call — no endpoints yet just means an empty\nlist, not an error. Each row has the endpoint's id, url, subscribed\ntopics, and `isSubscribedToAllTopics` (true means `topics` is empty but\nevery event type is delivered).\n\n**Rate limit:** 30 requests per minute per account, shared across all webhook endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "List Webhook Endpoints", "tags": [ "/webhooks" ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of webhook endpoints to return (defaults to 100).", "schema": { "type": "integer" }, "example": 100 }, { "name": "cursor", "in": "query", "description": "Opaque cursor returned as `meta.nextCursor` by the previous page.", "schema": { "type": [ "string", "null" ] }, "example": "cursor_page_2" } ], "responses": { "200": { "description": "Webhook endpoints retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointCollection" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "402": { "description": "Billing plan does not include webhook access (merchant principals only)", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Your plan does not include webhook access." }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Your plan does not include webhook access." } }, "required": [ "error" ] } } } }, "403": { "description": "Token type is neither merchant nor marketplace", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Invalid user type" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "422": { "description": "Invalid pagination parameters", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "message": "The limit field must not be greater than 250.", "errors": { "limit": [ "The limit field must not be greater than 250." ] } }, "summary": null, "description": null, "externalValue": null } ], "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "429": { "description": "Rate limit exceeded (30 requests per minute per owner)", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "message": "Too Many Attempts." }, "summary": null, "description": null, "externalValue": null } ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Failed to list webhook endpoints" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Failed to list webhook endpoints" } }, "required": [ "error" ] } } } } } }, "post": { "operationId": "webhooksEndpoints.post", "description": "Registers a webhook endpoint for the authenticated Refersion user —\nlets an account subscribe programmatically instead of only through the\nwebhook settings portal. Some users can only subscribe to a limited set\nof event types — anything else returns 422. Some users may receive a\n402 if their plan doesn't include webhook access. The user's webhook\nconfiguration is auto-provisioned on first call. The 201 response's id\nis also what `DELETE /v3/webhooks/endpoints/{endpointId}` accepts.\n\n**Rate limit:** 30 requests per minute per account, shared across all webhook endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Create Webhook Endpoint", "tags": [ "/webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookEndpointRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "201": { "description": "Webhook endpoint created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpointResource" } }, "required": [ "data" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "402": { "description": "Billing plan does not include webhook access (merchant principals only)", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Your plan does not include webhook access." }, "summary": null, "description": null, "externalValue": null } ] } } } }, "403": { "description": "Token type is neither merchant nor marketplace", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Invalid user type" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "422": { "description": "Invalid URL, empty topics, unknown event type, or a marketplace member requesting a merchant-only event type", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "message": "The topics field is required.", "errors": { "topics": [ "The topics field is required." ] } }, "summary": null, "description": null, "externalValue": null } ], "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "429": { "description": "Rate limit exceeded (30 requests per minute per owner)", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "message": "Too Many Attempts." }, "summary": null, "description": null, "externalValue": null } ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Failed to create webhook endpoint" }, "summary": null, "description": null, "externalValue": null } ] } } } } } } }, "/webhooks/endpoints/{endpointId}": { "delete": { "operationId": "webhooksEndpoints.delete", "description": "Removes one webhook endpoint belonging to the authenticated Refersion\nuser. `endpointId` is always resolved within the user's own webhook\nconfiguration, so another user's id returns the same 404 as an unknown\none.\n\nDeleting the same endpoint twice returns 404 on the second call (not\nidempotent-204 by design), and this operation never auto-provisions a\nconfiguration — a user with none simply gets 404.\n\n**Rate limit:** 30 requests per minute per account, shared across all webhook endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Delete Webhook Endpoint", "tags": [ "/webhooks" ], "parameters": [ { "name": "endpointId", "in": "path", "required": true, "description": "The webhook endpoint id (`ep_…`) to delete", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Webhook endpoint deleted" }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "402": { "description": "Billing plan does not include webhook access (merchant principals only)", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Your plan does not include webhook access." }, "summary": null, "description": null, "externalValue": null } ] } } } }, "403": { "description": "Token type is neither merchant nor marketplace", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Invalid user type" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "404": { "description": "No such endpoint in the caller's own webhook configuration — also the response for another owner's endpoint id, for an already-deleted one, and for a slash-free id of a disallowed shape. An id containing a literal or percent-encoded `/` matches no route at all and yields 405", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Webhook endpoint not found." }, "summary": null, "description": null, "externalValue": null } ] } } } }, "405": { "description": "An endpoint id containing a literal or percent-encoded `/` matches no DELETE route", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "message": "The DELETE method is not supported for route api/v3/webhooks/endpoints/ep/other. Supported methods: GET, HEAD." }, "summary": null, "description": null, "externalValue": null } ] } } } }, "429": { "description": "Rate limit exceeded (30 requests per minute per owner)", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "message": "Too Many Attempts." }, "summary": null, "description": null, "externalValue": null } ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Failed to delete webhook endpoint" }, "summary": null, "description": null, "externalValue": null } ] } } } } } }, "patch": { "operationId": "webhooksEndpoints.patch", "description": "Updates the delivery URL, subscribed event types, or both, for one\nwebhook endpoint belonging to the authenticated Refersion user.\n`endpointId` is always resolved within the user's own webhook\nconfiguration, so another user's id returns the same 404 as an unknown\none.\n\nOmitted fields are left unchanged; `topics` REPLACES the subscription\nrather than merging into it. Some users can only use a limited set of\nevent types — anything else returns 422. Some users may receive a 402\nif their plan doesn't include webhook access. Like delete, this never\nauto-provisions a configuration — a user with none gets 404.\n\n**Rate limit:** 30 requests per minute per account, shared across all webhook endpoints. Exceeding it returns 429 with a Retry-After header.", "summary": "Update Webhook Endpoint", "tags": [ "/webhooks" ], "parameters": [ { "name": "endpointId", "in": "path", "required": true, "description": "The webhook endpoint id (`ep_…`) to update", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookEndpointRequest" } } } }, "responses": { "200": { "description": "Webhook endpoint updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpointResource" } }, "required": [ "data" ] } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Authentication required" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "402": { "description": "Billing plan does not include webhook access (merchant principals only)", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Your plan does not include webhook access." }, "summary": null, "description": null, "externalValue": null } ] } } } }, "403": { "description": "Token type is neither merchant nor marketplace", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Invalid user type" }, "summary": null, "description": null, "externalValue": null } ] } } } }, "404": { "description": "No such endpoint in the caller's own webhook configuration — also the response for another owner's endpoint id, for an already-deleted one, and for a slash-free id of a disallowed shape. An id containing a literal or percent-encoded `/` matches no route at all and yields 405", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Webhook endpoint not found." }, "summary": null, "description": null, "externalValue": null } ] } } } }, "405": { "description": "An endpoint id containing a literal or percent-encoded `/` matches no PATCH route", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "message": "The PATCH method is not supported for route api/v3/webhooks/endpoints/ep/other. Supported methods: GET, HEAD." }, "summary": null, "description": null, "externalValue": null } ] } } } }, "422": { "description": "Neither url nor topics supplied, an invalid URL, empty topics, an unknown event type, or a marketplace member requesting a merchant-only event type", "content": { "application/json": { "schema": { "type": "object", "examples": [ { "value": { "message": "At least one of url or topics must be provided.", "errors": { "url": [ "At least one of url or topics must be provided." ] } }, "summary": null, "description": null, "externalValue": null } ], "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "429": { "description": "Rate limit exceeded (30 requests per minute per owner)", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "message": "Too Many Attempts." }, "summary": null, "description": null, "externalValue": null } ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "string", "examples": [ { "value": { "error": "Failed to update webhook endpoint" }, "summary": null, "description": null, "externalValue": null } ] } } } } } } } }, "components": { "securitySchemes": { "http": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "AffiliateActivityResource": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "description": "The type of activity entry.", "examples": [ "conversion" ] }, "week": { "type": "integer", "description": "The week number within the year (MySQL `WEEK()` mode 0).", "examples": [ 17 ] }, "date": { "type": "string", "description": "The date of the activity entry in ISO 8601 format (YYYY-MM-DD).", "examples": [ "2026-04-25" ] }, "conversionCount": { "type": "integer", "description": "The number of approved conversions for that week.", "examples": [ 12 ] }, "total": { "type": "number", "description": "The total sale amount in the client's default currency, rounded to two decimal places.", "examples": [ 1250.5 ] }, "currency": { "type": "string", "description": "The ISO 4217 currency code for the total.", "examples": [ "USD" ] } }, "required": [ "type", "week", "date", "conversionCount", "total", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "The type of activity entry.", "examples": [ "payment" ] }, "week": { "type": "integer", "description": "The week number within the year (MySQL `WEEK()` mode 0).", "examples": [ 17 ] }, "date": { "type": "string", "description": "The date of the activity entry in ISO 8601 format (YYYY-MM-DD).", "examples": [ "2026-04-25" ] }, "paidConversionCount": { "type": "integer", "description": "The number of approved conversions paid out in that week.", "examples": [ 3 ] }, "total": { "type": "number", "description": "The total commission amount paid out in the client's default currency, rounded to two decimal places.", "examples": [ 412 ] }, "currency": { "type": "string", "description": "The ISO 4217 currency code for the total.", "examples": [ "USD" ] } }, "required": [ "type", "week", "date", "paidConversionCount", "total", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "The type of activity entry.", "examples": [ "click" ] }, "week": { "type": "integer", "description": "The week number within the year (MySQL `WEEK()` mode 0).", "examples": [ 17 ] }, "date": { "type": "string", "description": "The date of the activity entry in ISO 8601 format (YYYY-MM-DD).", "examples": [ "2026-04-25" ] }, "clickCount": { "type": "integer", "description": "The number of clicks recorded that week.", "examples": [ 84 ] } }, "required": [ "type", "week", "date", "clickCount" ] } ], "title": "AffiliateActivityResource" }, "AffiliateCollection": { "type": "object", "properties": { "data": { "type": "array", "description": "Array of affiliate resources.", "items": { "$ref": "#/components/schemas/AffiliateResource" } } }, "required": [ "data" ], "title": "AffiliateCollection" }, "AffiliateCountResource": { "type": "object", "properties": { "pendingCount": { "type": "integer", "description": "Number of affiliates with pending status.", "examples": [ 5 ] }, "approvedCount": { "type": "integer", "description": "Number of affiliates with approved status (DB status 'ACTIVE' maps to API status 'approved').", "examples": [ 12 ] }, "deniedCount": { "type": "integer", "description": "Number of affiliates with denied status. Includes BANNED affiliates —\nbanned affiliates are counted within the denied bucket.", "examples": [ 3 ] } }, "required": [ "pendingCount", "approvedCount", "deniedCount" ], "title": "AffiliateCountResource" }, "AffiliateResource": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique affiliate identifier.", "examples": [ 8963614 ] }, "code": { "type": "string", "description": "The affiliate's unique referral code.", "examples": [ "ab5n" ] }, "isTestAccount": { "type": "boolean", "description": "Whether this affiliate is a test account.", "examples": [ false ] }, "ableToEdit": { "type": "boolean", "description": "Whether the merchant is allowed to edit this affiliate's profile fields.", "examples": [ true ] }, "plus": { "type": "boolean", "description": "Whether this affiliate is a \"Plus\" affiliate.", "examples": [ false ] }, "uniqueMerchantId": { "type": [ "string", "null" ], "description": "The merchant-assigned external identifier for the affiliate.", "examples": [ "MERCH-12345" ] }, "parentAffiliateId": { "type": [ "integer", "null" ], "description": "The id of the parent affiliate in the MLM parent-child relationship.\nReturns null when this affiliate has no parent. The referenced parent\nrow may have any status (including DELETED or HIDDEN) — orphan\ncleanup is intentionally out of scope.", "examples": [ 12345 ] }, "status": { "type": "string", "description": "The affiliate status. Possible values: PENDING, APPROVED, DENIED, BANNED. The internal\nDISABLED status is reported as APPROVED — see the `locked` field for lock state.\nBANNED is returned verbatim; banned affiliates surface under the denied list filter.", "examples": [ "PENDING" ] }, "locked": { "type": "boolean", "description": "Whether the affiliate is locked. When true, the affiliate is APPROVED but\nunable to log in or generate clicks/conversions. Always false unless the\nunderlying DB status is DISABLED.", "examples": [ false ] }, "firstName": { "type": "string", "description": "The affiliate's first name.", "examples": [ "John" ] }, "lastName": { "type": "string", "description": "The affiliate's last name.", "examples": [ "Smith" ] }, "company": { "type": [ "string", "null" ], "description": "The affiliate's company name.", "examples": [ "Acme Inc" ] }, "email": { "type": "string", "description": "The affiliate's email address.", "examples": [ "example@gmail.com" ] }, "paypalEmail": { "type": [ "string", "null" ], "description": "The affiliate's PayPal email address for payments.", "examples": [ "paypal@example.com" ] }, "phone": { "type": "object", "description": "The affiliate's phone information.", "examples": [ { "number": "", "country": "", "verified": false } ], "properties": { "number": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" } }, "required": [ "number", "country", "verified" ] }, "offer": { "type": "object", "description": "The offer associated with this affiliate.", "examples": [ { "id": 65651, "name": "Default Offer", "type": "PERCENTAGE", "tierCalculationMode": null } ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" }, "tierCalculationMode": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "type", "tierCalculationMode" ] }, "address": { "type": "object", "description": "The affiliate's address information.", "examples": [ { "address1": null, "address2": null, "city": null, "state": null, "postalCode": null, "country": null } ], "properties": { "address1": { "type": [ "string", "null" ] }, "address2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "postalCode": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] } }, "required": [ "address1", "address2", "city", "state", "postalCode", "country" ] }, "url": { "type": "object", "description": "The affiliate's custom URL configuration.", "examples": [ { "path": "my-store", "additionalParameters": "ref=affiliate" } ], "properties": { "path": { "type": [ "string", "null" ] }, "additionalParameters": { "type": [ "string", "null" ] } }, "required": [ "path", "additionalParameters" ] }, "createdAt": { "type": "string", "description": "When the affiliate was created in ISO 8601 format.", "examples": [ "2025-09-25T15:07:33-04:00" ] }, "updatedAt": { "type": "string", "description": "When the affiliate was last updated in ISO 8601 format.", "examples": [ "2025-09-25T15:07:33-04:00" ] }, "timezone": { "type": "string", "description": "The affiliate's timezone.", "examples": [ "GMT" ] }, "source": { "type": "string", "description": "The source of the affiliate registration.", "examples": [ "MERCHANT_PROFILE" ] }, "vip": { "type": "boolean", "description": "Whether the affiliate is a VIP in the marketplace.", "examples": [ false ] }, "autoPay": { "type": "object", "description": "Auto-pay configuration for the affiliate.", "examples": [ { "setup": true } ], "properties": { "setup": { "type": "boolean" } }, "required": [ "setup" ] }, "trolley": { "type": "object", "description": "Trolley (Payment Rails) setup status for the affiliate.", "examples": [ { "setup": true } ], "properties": { "setup": { "type": [ "boolean", "null" ] } }, "required": [ "setup" ] }, "performance": { "type": "object", "description": "Performance metrics for the affiliate. Omitted entirely when the\nresource is built via withoutPerformance() (event payloads). The\nclosure defers every performance* property read so callers that\nopt out may supply rows without those columns.", "properties": { "pending": { "type": "object", "description": "Pending performance metrics.", "examples": [ { "revenue": 500, "commission": 75.25, "conversions": 12, "payouts": 150, "uniqueOrders": 8, "aov": 62.5 } ], "properties": { "revenue": { "type": "number" }, "commission": { "type": "number" }, "conversions": { "type": "integer" }, "payouts": { "type": "number" }, "uniqueOrders": { "type": "integer" }, "aov": { "type": "number" } }, "required": [ "revenue", "commission", "conversions", "payouts", "uniqueOrders", "aov" ] }, "30Days": { "type": "object", "description": "Last 30 days performance metrics.", "examples": [ { "revenue": 150, "commission": 120, "conversions": 15, "payouts": 200, "clicks": 300, "uniqueOrders": 12, "aov": 12.5 } ], "properties": { "revenue": { "type": [ "number", "null" ] }, "commission": { "type": "number" }, "conversions": { "type": "integer" }, "payouts": { "type": "number" }, "clicks": { "type": "integer" }, "uniqueOrders": { "type": "integer" }, "aov": { "type": "number" } }, "required": [ "revenue", "commission", "conversions", "payouts", "clicks", "uniqueOrders", "aov" ] }, "total": { "type": "object", "description": "Total lifetime performance metrics.", "examples": [ { "revenue": 423.45, "commission": 167.89, "conversions": 112, "payouts": 900, "clicks": 5000, "uniqueOrders": 50, "itemsSold": 230, "aov": 8.47 } ], "properties": { "revenue": { "type": "number" }, "commission": { "type": "number" }, "conversions": { "type": "integer" }, "payouts": { "type": "number" }, "clicks": { "type": "integer" }, "uniqueOrders": { "type": "integer" }, "itemsSold": { "type": "integer" }, "aov": { "type": "number" } }, "required": [ "revenue", "commission", "conversions", "payouts", "clicks", "uniqueOrders", "itemsSold", "aov" ] }, "lastConversion": { "type": [ "string", "null" ], "description": "When the affiliate's last conversion occurred in ISO 8601 format.", "examples": [ "2025-09-25T15:07:33-04:00" ] }, "lastLogin": { "type": [ "string", "null" ], "description": "When the affiliate last logged in, in ISO 8601 format.", "examples": [ "2025-09-25T15:07:33-04:00" ] } }, "required": [ "pending", "30Days", "total", "lastConversion", "lastLogin" ] } }, "required": [ "id", "code", "isTestAccount", "ableToEdit", "plus", "uniqueMerchantId", "parentAffiliateId", "status", "locked", "firstName", "lastName", "company", "email", "paypalEmail", "phone", "offer", "address", "url", "createdAt", "updatedAt", "timezone", "source", "vip", "autoPay", "trolley" ], "title": "AffiliateResource" }, "AmazonProductCollection": { "type": "object", "properties": { "data": { "type": "array", "description": "Array of Amazon product resources.", "items": { "$ref": "#/components/schemas/AmazonProductResource" } } }, "required": [ "data" ], "title": "AmazonProductCollection" }, "AmazonProductResource": { "type": "object", "properties": { "id": { "type": "integer", "description": "The product's unique identifier.", "examples": [ 123456 ] }, "fullName": { "type": "string", "description": "The product's name, optionally suffixed with the variant title when the variant title differs from the product name.", "examples": [ "Some Product - Large" ] }, "imageUrl": { "type": [ "string", "null" ], "description": "The product's image URL. May be null when no joined image exists.", "examples": [ "https://m.media-amazon.com/images/I/81YzSWqW1hL._SS60_.jpg" ] }, "productUrl": { "type": [ "string", "null" ], "description": "The product's public URL on the Amazon marketplace. May be null when no product URL is set.", "examples": [ "https://amazon.com/SUPER40KIT-FBM/dp/B0F9PBT781" ] } }, "required": [ "id", "fullName", "imageUrl", "productUrl" ], "title": "AmazonProductResource" }, "BusinessCategoryResource": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique identifier for the business category.", "examples": [ 1 ] }, "sortOrder": { "type": "integer", "description": "The display sort order for the category.", "examples": [ 1 ] }, "name": { "type": "string", "description": "The name of the business category.", "examples": [ "Arts, crafts, and collectibles" ] } }, "required": [ "id", "sortOrder", "name" ], "title": "BusinessCategoryResource" }, "BusinessCategoryResourceCollection": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessCategoryResource" } } }, "required": [ "data" ], "title": "BusinessCategoryResourceCollection" }, "ClickCollection": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ClickResource" } } }, "required": [ "data" ], "title": "ClickCollection" }, "ClickResource": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique click identifier across all of Refersion", "examples": [ 123 ] }, "affiliateId": { "type": "integer", "description": "The affiliate ID that the click belongs to", "examples": [ 456 ] }, "offerId": { "type": "integer", "description": "The offer ID that the click belongs to", "examples": [ 987 ] }, "creativeId": { "type": [ "integer", "null" ], "description": "The creative ID that the click belongs to", "examples": [ null ] }, "createdAt": { "type": "string", "description": "When the click took place in ISO 8601 format in the client's timezone.", "examples": [ "2025-09-25T15:07:33-04:00" ] }, "subId": { "type": [ "string", "null" ], "description": "The \"subid\" query parameter recorded with the click", "examples": [ null ] }, "ipAddress": { "type": [ "string", "null" ], "description": "The IP address of the person who made the click", "examples": [ "100.1.4.44" ] }, "userAgent": { "type": [ "string", "null" ], "description": "The user agent of the browser that made the click", "examples": [ "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36" ] }, "referer": { "type": [ "string", "null" ], "description": "The referring header from the user who made the click", "examples": [ null ] }, "landedUrl": { "type": [ "string", "null" ], "description": "The page the click was recorded on", "examples": [ "https://www.example.com/?rfsn=1234567.abcd123&utm_source=ambassador&utm_medium=referral&utm_campaign=1234567" ] }, "test": { "type": "boolean", "description": "Indicates if the click was a test or real", "examples": [ false ] } }, "required": [ "id", "affiliateId", "offerId", "creativeId", "createdAt", "subId", "ipAddress", "userAgent", "referer", "landedUrl", "test" ], "title": "ClickResource" }, "ConversionCollection": { "type": "object", "properties": { "data": { "type": "array", "description": "Array of conversion resources.", "items": { "$ref": "#/components/schemas/ConversionResource" } } }, "required": [ "data" ], "title": "ConversionCollection" }, "ConversionCountResource": { "type": "object", "properties": { "pendingCount": { "type": "integer", "description": "Number of conversions with PENDING status.", "examples": [ 5 ] }, "approvedCount": { "type": "integer", "description": "Number of conversions with APPROVED status (commission has not yet been paid out).", "examples": [ 12 ] }, "paidCount": { "type": "integer", "description": "Number of conversions with PAID status (APPROVED conversions whose commission has been paid out).", "examples": [ 8 ] }, "deniedCount": { "type": "integer", "description": "Number of conversions with DENIED status.", "examples": [ 2 ] }, "unqualifiedCount": { "type": "integer", "description": "Number of conversions with UNQUALIFIED status.", "examples": [ 1 ] } }, "required": [ "pendingCount", "approvedCount", "paidCount", "deniedCount", "unqualifiedCount" ], "title": "ConversionCountResource" }, "ConversionDetailResource": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique identifier of the conversion.", "examples": [ 12345 ] }, "merchantUniqueId": { "type": [ "string", "null" ], "description": "The merchant-provided unique order identifier.", "examples": [ "ORD-9001" ] }, "merchantSubscriptionId": { "type": [ "string", "null" ], "description": "The merchant-provided subscription identifier (if applicable).", "examples": [ "SUB-001" ] }, "currency": { "type": [ "string", "null" ], "description": "The ISO 4217 currency code associated with the conversion.", "examples": [ "USD" ] }, "type": { "type": [ "string", "null" ], "description": "The raw stored conversion type, returned verbatim (no label mapping).\nLANDING_SITE_RECOVERY_CONVERSION marks a conversion whose affiliate click was\nrecovered from the order's landing URL after standard cart tracking failed.", "examples": [ "AFFILIATE_SITE_CONVERSION" ] }, "customerName": { "type": [ "string", "null" ], "description": "The customer's name captured at order submission.", "examples": [ "John Doe" ] }, "customerEmail": { "type": [ "string", "null" ], "description": "The customer's email captured at order submission.", "examples": [ "john@example.com" ] }, "browserIp": { "type": [ "string", "null" ], "description": "The customer's IP address captured at order submission.", "examples": [ "192.168.1.1" ] }, "status": { "type": "string", "description": "The current status of the conversion (PENDING, APPROVED, PAID, DENIED, UNQUALIFIED).", "examples": [ "PENDING" ] }, "source": { "type": [ "string", "null" ], "description": "The source platform or integration that produced the conversion.", "examples": [ "Shopify" ] }, "couponCode": { "type": [ "string", "null" ], "description": "The coupon code used at checkout, if any.", "examples": [ "SAVE10" ] }, "commissionExplanation": { "type": [ "object", "null" ], "description": "An object describing how the commission was calculated.", "examples": [ { "items": [], "grand_total_items": 0, "grand_total_price": 0, "grand_total_commission": 19.99 } ] }, "paymentId": { "type": "integer", "description": "The associated payment identifier (0 when the conversion has not been paid out).", "examples": [ 0 ] }, "conversionNotes": { "type": [ "string", "null" ], "description": "Merchant-entered notes attached to the conversion.", "examples": [ "Customer notes" ] }, "reasonCode": { "type": [ "string", "null" ], "description": "The reason code associated with a status change (if any).", "examples": [ null ] }, "commissionTotal": { "type": "string", "description": "The commission amount earned for the conversion, formatted to two decimal places.", "examples": [ "19.99" ] }, "total": { "type": "string", "description": "The order total used for reporting. Uses commissionable_amount when order_total_adjustment is enabled, otherwise the order total. Formatted to two decimal places.", "examples": [ "199.95" ] }, "createdAt": { "type": [ "string", "null" ], "description": "When the conversion was created, in ISO 8601 format in the client's timezone.", "examples": [ "2026-03-25T15:07:33-04:00" ] }, "updatedAt": { "type": [ "string", "null" ], "description": "When the conversion was last updated, in ISO 8601 format in the client's timezone.\nNull when the conversion row has never been updated (e.g. a manual credit\ncreated directly in its terminal status).", "examples": [ "2026-03-26T09:12:45-04:00" ] }, "paymentMethod": { "type": [ "string", "null" ], "description": "The payment method used to pay out the conversion, if applicable.", "examples": [ "PayPal" ] }, "isOrderTotalAdjustment": { "type": "boolean", "description": "Whether the total field reflects the order_total_adjustment setting from offer_more_settings.", "examples": [ false ] }, "isAmazonCanBeApproved": { "type": "boolean", "description": "Whether this Amazon conversion is eligible to be approved (PENDING + AMAZON + created more than 30 days ago).", "examples": [ false ] }, "isLandingSiteRecoveryConversion": { "type": "boolean", "description": "Whether this conversion was recovered from the order's landing URL after standard\ncart tracking failed (e.g. browser privacy protections stripped the affiliate\ncookie). True for both LANDING_SITE_RECOVERY_CONVERSION and its cancellation\ncounterpart, since a reversal of a recovered conversion is still a recovered\nconversion for display purposes. When true, `click.landedUrl` is the landing URL\nthe recovery matched on.", "examples": [ false ] }, "isTest": { "type": "boolean", "description": "Whether this is a test conversion, such as one from a Stripe sandbox or test-mode payment.", "examples": [ false ] }, "affiliate": { "type": "object", "description": "The affiliate that earned the conversion.", "examples": [ { "id": 789, "firstName": "Jessica", "lastName": "Martinez", "email": "jessica@example.com", "company": "Acme Corp", "isVip": false, "isTestAccount": false } ], "properties": { "id": { "type": "integer" }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "isVip": { "type": "boolean" }, "isTestAccount": { "type": "boolean" } }, "required": [ "id", "firstName", "lastName", "email", "company", "isVip", "isTestAccount" ] }, "offer": { "type": "object", "description": "The offer associated with the conversion.", "examples": [ { "id": 987, "name": "My Offer", "type": "standard", "isPrivate": false, "isDefault": false } ], "properties": { "id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "isPrivate": { "type": "boolean" }, "isDefault": { "type": "boolean" } }, "required": [ "id", "name", "type", "isPrivate", "isDefault" ] }, "click": { "type": "object", "description": "The click that preceded the conversion (if tracked via link). For a landing-site\nrecovery conversion, `landedUrl` is the landing URL the recovery matched on.\n`subid` is null only when recovery fabricated a synthetic click; a recovery that\nmatched a real pre-existing click preserves that click's affiliate-supplied subid.", "examples": [ { "id": 123456789, "landedUrl": "https://example.com/product", "referer": "https://google.com", "subid": "campaign123", "clickedAt": "2026-03-23T12:56:14-04:00" } ], "properties": { "id": { "type": [ "integer", "null" ] }, "landedUrl": { "type": [ "string", "null" ] }, "referer": { "type": [ "string", "null" ] }, "subid": { "type": [ "string", "null" ] }, "clickedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "landedUrl", "referer", "subid", "clickedAt" ] }, "autoPay": { "type": "object", "description": "The Pantastic Pay (\"autoPay\") enrollment status for the conversion and its affiliate.", "examples": [ { "isEnabled": false, "isFunded": false, "isPaid": false, "hasAutoPay": false } ], "properties": { "isEnabled": { "type": "boolean" }, "isFunded": { "type": "boolean" }, "isPaid": { "type": "boolean" }, "hasAutoPay": { "type": "boolean" } }, "required": [ "isEnabled", "isFunded", "isPaid", "hasAutoPay" ] }, "childAffiliate": { "type": [ "object", "null" ], "description": "The child (descendant) affiliate whose activity triggered this MLM commission. Present only for PARENT_LEVEL, SIGNUP_BONUS, and SIGNUP_WITH_CONVERSION_BONUS conversions; null for all other types.", "examples": [ { "id": 456, "firstName": "Sam", "lastName": "Lee", "company": "Downline LLC" } ], "properties": { "id": { "type": "integer" }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] } }, "required": [ "id", "firstName", "lastName", "company" ] }, "parentLevel": { "type": [ "integer", "null" ], "description": "For a PARENT_LEVEL conversion, the number of levels above the child affiliate this commission was awarded for. Null for non-PARENT_LEVEL conversions.", "examples": [ 2 ] }, "originalAffiliate": { "type": [ "object", "null" ], "description": "The original (root) affiliate whose sale started a PARENT_LEVEL chain. Populated only when parentLevel > 1; null when parentLevel === 1 (it equals childAffiliate) or for non-PARENT_LEVEL conversions.", "examples": [ { "id": 123, "firstName": "Root", "lastName": "Affiliate", "company": "Top Co" } ], "properties": { "id": { "type": "integer" }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] } }, "required": [ "id", "firstName", "lastName", "company" ] }, "mayGenerateAdditionalConversions": { "type": "boolean", "description": "Whether approving this conversion may still generate additional MLM conversions (signup-bonus and/or direct-parent payout). Always false for non-pending conversions. Lets the detail drawer indicate pending generation.", "examples": [ false ] }, "generatedParentConversions": { "type": "array", "description": "Every PARENT_LEVEL conversion generated up the ancestor chain from this conversion, ordered by parentLevel ascending. One item per ancestor level paid out. Empty array when this conversion generated none.", "examples": [ [ { "conversionId": 555, "affiliate": { "id": 456, "firstName": "Sam", "lastName": "Lee", "company": "Downline LLC" }, "parentLevel": 1, "commissionTotal": "5.00", "currency": "USD", "status": "APPROVED", "createdAt": "2026-03-25T15:07:33-04:00" } ] ], "items": { "type": "object", "properties": { "conversionId": { "type": "integer" }, "affiliate": { "type": "object", "properties": { "id": { "type": "integer" }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] } }, "required": [ "id", "firstName", "lastName", "company" ] }, "parentLevel": { "type": "integer" }, "commissionTotal": { "type": "string" }, "currency": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "createdAt": { "type": [ "string", "null" ] } }, "required": [ "conversionId", "affiliate", "parentLevel", "commissionTotal", "currency", "status", "createdAt" ] } } }, "required": [ "id", "merchantUniqueId", "merchantSubscriptionId", "currency", "type", "customerName", "customerEmail", "browserIp", "status", "source", "couponCode", "commissionExplanation", "paymentId", "conversionNotes", "reasonCode", "commissionTotal", "total", "createdAt", "updatedAt", "paymentMethod", "isOrderTotalAdjustment", "isAmazonCanBeApproved", "isLandingSiteRecoveryConversion", "isTest", "affiliate", "offer", "click", "autoPay", "childAffiliate", "parentLevel", "originalAffiliate", "mayGenerateAdditionalConversions", "generatedParentConversions" ], "title": "ConversionDetailResource" }, "ConversionResource": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique conversion identifier.", "examples": [ 12345 ] }, "orderId": { "type": [ "string", "null" ], "description": "The merchant's order ID for this conversion. Null for conversions not\ntied to a merchant order (e.g. signup bonuses, manual credits); the\nclient derives a conversion-type label for display in that case.", "examples": [ "ORD-12345" ] }, "affiliate": { "type": "object", "description": "The affiliate associated with this conversion.", "examples": [ { "id": 100, "firstName": "Jane", "lastName": "Doe", "company": "Acme Co.", "isVip": false, "isTestAccount": false } ], "properties": { "id": { "type": "integer" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "company": { "type": "string" }, "isVip": { "type": "boolean" }, "isTestAccount": { "type": "boolean" } }, "required": [ "id", "firstName", "lastName", "company", "isVip", "isTestAccount" ] }, "type": { "type": "string", "description": "The raw stored conversion type, returned verbatim (no label mapping).\nLANDING_SITE_RECOVERY_CONVERSION marks a conversion whose affiliate click was\nrecovered from the order's landing URL after standard cart tracking failed.", "examples": [ "AFFILIATE_SITE_CONVERSION" ] }, "revenue": { "type": "number", "description": "The total revenue amount.", "examples": [ 150 ] }, "commission": { "type": "number", "description": "The commission amount.", "examples": [ 15 ] }, "currency": { "type": "string", "description": "The currency code for monetary values.", "examples": [ "USD" ] }, "createdAt": { "type": "string", "description": "When the conversion was created in ISO 8601 format.", "examples": [ "2026-01-15T10:30:00-05:00" ] }, "source": { "type": "string", "description": "The conversion source/platform.", "examples": [ "Shopify" ] }, "referral": { "type": [ "string", "null" ], "description": "Referral detail for the conversion — the click referrer URL for\nAFFILIATE_SITE_CONVERSION and LANDING_SITE_RECOVERY_CONVERSION (stripped of\nprotocol/www and any trailing slash), the coupon code for\nCONVERSION_TRIGGER_COUPON, or the first SKU for CONVERSION_TRIGGER_SKU.\nNull when not applicable, including when a recovered conversion's synthetic\nclick carries no referrer.", "examples": [ "example.com/landing" ] }, "status": { "type": "string", "description": "The computed conversion status.", "examples": [ "PENDING" ] }, "autoApproveAt": { "type": [ "string", "null" ], "description": "Projected auto-approval timestamp (ISO 8601) for PENDING conversions.\nNull when the status is not PENDING, the client has auto-approve disabled,\nor no delay is configured.", "examples": [ "2026-02-15T00:00:00-05:00" ] }, "isTest": { "type": "boolean", "description": "Whether this is a test conversion (recorded from a test order).", "examples": [ false ] }, "offerId": { "type": "integer", "description": "The offer ID associated with this conversion.", "examples": [ 1 ] }, "offerName": { "type": "string", "description": "The offer name.", "examples": [ "Default Offer" ] }, "mayGenerateAdditionalConversions": { "type": "boolean", "description": "Whether approving this PENDING conversion may generate additional\nMLM conversions — true only when the conversion is pending and its\naffiliate has an eligible parent affiliate whose offer carries a\nsignup bonus with conversion_count > 0 and/or a direct-parent\n(level 1) parent-affiliate payout. Always false for non-pending\nconversions.", "examples": [ false ] } }, "required": [ "id", "orderId", "affiliate", "type", "revenue", "commission", "currency", "createdAt", "source", "referral", "status", "autoApproveAt", "isTest", "offerId", "offerName", "mayGenerateAdditionalConversions" ], "title": "ConversionResource" }, "CountryResource": { "type": "object", "properties": { "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code", "examples": [ "US" ] }, "countryName": { "type": "string", "description": "Full country name", "examples": [ "United States" ] } }, "required": [ "countryCode", "countryName" ], "title": "CountryResource" }, "CountryResourceCollection": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CountryResource" } } }, "required": [ "data" ], "title": "CountryResourceCollection" }, "CouponExclusionResource": { "type": "object", "properties": { "id": { "type": "integer", "description": "The exclusion record ID.", "examples": [ 42 ] }, "couponCode": { "type": "string", "description": "The excluded coupon code.", "examples": [ "SUMMER2025" ] }, "couponDescription": { "type": [ "string", "null" ], "description": "An optional description of the excluded coupon.", "examples": [ "Summer sale discount code" ] }, "status": { "type": "string", "description": "The status of the exclusion. Always 'active' for this endpoint.", "examples": [ "active" ] }, "createdAt": { "type": "string", "description": "When the exclusion was created, in ISO 8601 format.", "examples": [ "2025-09-25T15:07:33+00:00" ] } }, "required": [ "id", "couponCode", "couponDescription", "status", "createdAt" ], "title": "CouponExclusionResource" }, "CreateExclusionRequest": { "type": "object", "description": "Create Exclusion Request\n\nValidates the request body for creating an exclusion of any supported type\n(IP, coupon, or SKU). The `type` field determines which additional fields\nare required and how uniqueness is validated.", "properties": { "type": { "type": "string", "description": "The exclusion type. Exactly one type-specific field must be supplied\non any single request: `ip` when type=ip, `couponCode` (with optional\n`couponDescription`) when type=coupon, `sku` (with optional `nameLabel`)\nwhen type=sku. Fields belonging to other types must be omitted.", "example": "ip" }, "ip": { "type": [ "string", "null" ], "description": "The IP address to exclude. Required when type=ip; omit for other types.", "example": "192.168.1.100" }, "couponCode": { "type": [ "string", "null" ], "description": "The coupon code to exclude. Required when type=coupon; omit for other types.", "example": "SUMMER2025" }, "couponDescription": { "type": [ "string", "null" ], "description": "Optional description for a coupon exclusion. Only valid when type=coupon.", "example": "Summer sale discount" }, "sku": { "type": [ "string", "null" ], "description": "The product SKU to exclude. Required when type=sku; omit for other types.", "example": "PROD-12345" }, "nameLabel": { "type": [ "string", "null" ], "description": "Optional user-friendly label for a SKU exclusion. Only valid when type=sku.", "example": "Premium Widget" } }, "required": [ "type" ], "title": "CreateExclusionRequest" }, "CreateManualCreditRequest": { "type": "object", "description": "Create Manual Credit Request\n\nValidates request body for creating a new manual credit conversion for an affiliate.", "properties": { "affiliateId": { "type": "integer", "description": "The affiliate ID receiving the manual credit.", "example": 123456 }, "commissionTotal": { "type": "number", "description": "The commission amount for the manual credit. Allows negative values.", "example": 19.99 }, "currency": { "type": "string", "description": "The ISO 4217 currency code for the commission.", "example": "USD" }, "approvalStatus": { "type": "string", "description": "The approval status for the manual credit.", "example": "APPROVED" }, "notes": { "type": [ "string", "null" ], "description": "Optional notes for the manual credit conversion.", "example": "Manual credit for Q4 bonus" } }, "required": [ "affiliateId", "commissionTotal", "currency", "approvalStatus" ], "title": "CreateManualCreditRequest" }, "CreatePromotionMethodRequest": { "type": "object", "description": "Create Promotion Method Request\n\nValidates request body for creating a new promotion method (conversion trigger).\nSupports coupon, email, and sku types with appropriate validation rules.", "properties": { "type": { "type": "string", "description": "The type of promotion method. API access tokens cannot create the `sku` type.", "example": "coupon" }, "value": { "type": "string", "description": "The promotion method value (coupon code, SKU, or email address).", "example": "10OFFJEFF" }, "affiliateId": { "type": "integer", "description": "The affiliate ID to associate with this promotion method.", "example": 123456 } }, "required": [ "type", "value", "affiliateId" ], "title": "CreatePromotionMethodRequest" }, "CreateWebhookEndpointRequest": { "type": "object", "description": "Create Webhook Endpoint Request\n\nValidates the request body for creating a webhook endpoint: an absolute HTTPS\ndelivery URL and a non-empty list of event types the authenticated principal\nis allowed to subscribe to.", "properties": { "url": { "type": "string", "description": "The absolute HTTPS URL webhook messages will be delivered to.", "example": "https://merchant.example.com/hooks/refersion" }, "topics": { "type": "array", "description": "The event types this endpoint subscribes to. Must be a JSON array\n(not an object) containing at least one type and no duplicates.", "example": [ "conversion.created", "payout.created" ], "items": { "type": "string", "description": "A single event type to subscribe to. Marketplace members may only\nuse conversion.created, conversion.approved, conversion.denied and\npayout.created; merchant clients may use any registered type.", "example": "conversion.created" } } }, "required": [ "url", "topics" ], "title": "CreateWebhookEndpointRequest" }, "CreditOrderIdRequest": { "type": "object", "description": "Credit Order ID Request\n\nValidates request body for crediting an existing order from the conversion queue to a specified affiliate.", "properties": { "conversionQueueId": { "type": "integer", "description": "The conversion queue record ID to credit.", "example": 456789 }, "affiliateId": { "type": "integer", "description": "The affiliate ID to credit the order to.", "example": 123456 }, "approvalStatus": { "type": "string", "description": "The approval status for the credited order.", "example": "APPROVED" }, "notes": { "type": [ "string", "null" ], "description": "Optional notes for the credited order.", "example": "Manual credit for order fulfillment" } }, "required": [ "conversionQueueId", "affiliateId", "approvalStatus" ], "title": "CreditOrderIdRequest" }, "CurrencyResource": { "type": "object", "additionalProperties": { "type": "object", "properties": { "symbol": { "type": "string" }, "format": { "type": "string" } }, "required": [ "symbol", "format" ] }, "title": "CurrencyResource" }, "GetAffiliateCustomFieldCollection": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GetAffiliateCustomFieldResource" } } }, "required": [ "data" ], "title": "GetAffiliateCustomFieldCollection" }, "GetAffiliateCustomFieldResource": { "type": "object", "properties": { "id": { "type": "integer", "description": "The custom field ID.", "examples": [ 123456 ] }, "label": { "type": "string", "description": "The display label of the custom field.", "examples": [ "What is your website URL?" ] }, "value": { "type": "string", "description": "The affiliate's answer for this custom field.", "examples": [ "https://example.com" ] }, "required": { "type": "boolean", "description": "Whether the merchant requires this field.", "examples": [ true ] }, "type": { "type": "string", "description": "The field type in camelCase format.", "examples": [ "text" ] }, "hidden": { "type": "boolean", "description": "Whether the field is hidden from the affiliate.", "examples": [ false ] }, "allowedValues": { "type": "string" } }, "required": [ "id", "label", "value", "required", "type", "hidden", "allowedValues" ], "title": "GetAffiliateCustomFieldResource" }, "GetAffiliateLinkResource": { "type": "object", "properties": { "link": { "type": "string", "description": "The generated affiliate tracking link.", "examples": [ "https://www.example.com?rfsn=123.4a5" ] } }, "required": [ "link" ], "title": "GetAffiliateLinkResource" }, "GetExclusionsResource": { "type": "object", "properties": { "data": { "type": "array", "description": "Array of exclusion records for the requested type.", "examples": [ [ { "id": 1, "ip": "192.168.1.1", "status": "active", "createdAt": "2025-01-01T00:00:00+00:00" } ] ], "items": { "type": "object", "properties": { "id": { "type": "integer" }, "ip": { "type": "string" }, "couponCode": { "type": "string" }, "couponDescription": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "nameLabel": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "status", "createdAt" ] } }, "hasNextPage": { "type": "boolean", "description": "Whether there is a next page of results.", "examples": [ true ] }, "hasPreviousPage": { "type": "boolean", "description": "Whether there is a previous page of results.", "examples": [ false ] }, "page": { "type": "integer", "description": "The current page number.", "examples": [ 1 ] }, "isAddAllowed": { "type": [ "boolean", "null" ], "description": "Whether the authenticated client may add more exclusions of this type.\nTrue/false only for type=sku (plan-gated); null for ip and coupon, which are ungated.", "examples": [ false ] } }, "required": [ "data", "hasNextPage", "hasPreviousPage", "page", "isAddAllowed" ], "title": "GetExclusionsResource" }, "GetProspectsStatusResource": { "type": "object", "properties": { "status": { "type": "string", "description": "The current status of the prospect discovery process", "examples": [ "processing" ] }, "message": { "type": [ "string", "null" ], "description": "A message describing the current state or any errors", "examples": [ "Prospect discovery job has been queued" ] } }, "required": [ "status", "message" ], "title": "GetProspectsStatusResource" }, "IpExclusionResource": { "type": "object", "properties": { "id": { "type": "integer", "description": "The exclusion record ID.", "examples": [ 42 ] }, "ip": { "type": "string", "description": "The excluded IP address (IPv4 or IPv6).", "examples": [ "192.168.1.100" ] }, "status": { "type": "string", "description": "The status of the exclusion. Always 'active' for this endpoint.", "examples": [ "active" ] }, "createdAt": { "type": "string", "description": "When the exclusion was created, in ISO 8601 format.", "examples": [ "2025-09-25T15:07:33+00:00" ] } }, "required": [ "id", "ip", "status", "createdAt" ], "title": "IpExclusionResource" }, "JsonResource": { "type": "string", "title": "JsonResource" }, "ManualCreditResource": { "type": "object", "properties": { "conversionId": { "type": "integer", "description": "The unique identifier of the created conversion.", "examples": [ 987654 ] } }, "required": [ "conversionId" ], "title": "ManualCreditResource" }, "OfferCollection": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OfferResource" } } }, "required": [ "data" ], "title": "OfferCollection" }, "OfferResource": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the offer", "examples": [ 123 ] }, "publicId": { "type": [ "string", "null" ], "description": "Public UUID identifier for the offer (used in public-facing URLs)", "examples": [ "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" ] }, "name": { "type": [ "string", "null" ], "description": "Name of the offer", "examples": [ "My First Offer" ] }, "commission": { "type": [ "string", "null" ], "description": "Base commission rate", "examples": [ "10.00" ] }, "returnCustomerCommission": { "type": [ "string", "null" ], "description": "Commission rate for returning customers", "examples": [ "5.00" ] }, "returningCustomerFlatRateCurrency": { "type": [ "string", "null" ], "description": "Currency code for returning customer flat rate (ISO 4217)", "examples": [ "USD" ] }, "flatRateCurrency": { "type": [ "string", "null" ], "description": "Currency code for flat rate (ISO 4217)", "examples": [ "USD" ] }, "commissionTerms": { "type": [ "string", "null" ], "description": "Description of commission terms", "examples": [ "Commission terms description text." ] }, "isRequireNewCustomer": { "type": "boolean", "description": "Whether the offer requires new customers only", "examples": [ false ] }, "isSubscriptionsDenyRenewals": { "type": "boolean", "description": "Whether subscription renewals are denied", "examples": [ false ] }, "attributionWindow": { "type": "integer", "description": "Attribution window in days (cookie days)", "examples": [ 90 ] }, "isDefault": { "type": "boolean", "description": "Whether this is the default offer", "examples": [ false ] }, "isAutoApproveConversions": { "type": "boolean", "description": "Whether conversions are auto-approved", "examples": [ false ] }, "isAutoDenyConversions": { "type": "boolean", "description": "Whether conversions are auto-denied", "examples": [ false ] }, "isAutoUnqualifyConversions": { "type": "boolean", "description": "Whether conversions are auto-unqualified", "examples": [ false ] }, "isAutoApproveAffiliates": { "type": "boolean", "description": "Whether affiliates are auto-approved", "examples": [ false ] }, "isPrivate": { "type": "boolean", "description": "Whether the offer is private", "examples": [ false ] }, "cs": { "type": [ "string", "null" ], "description": "Private offer registration checksum.", "examples": [ "e3b0c44298fc1c149afbf4c8996fb924" ] }, "type": { "type": "string", "description": "Offer type", "examples": [ "TIERED" ] }, "tierCalculationMode": { "type": [ "string", "null" ], "description": "Tier calculation mode", "examples": [ "AFFILIATE_SALES" ] }, "tierCount": { "type": "integer", "description": "Number of configured tier rows for tiered offers", "examples": [ 3 ] }, "quantityMultiply": { "type": [ "boolean", "null" ], "description": "Quantity multiplier setting", "examples": [ false ] }, "duration": { "type": [ "string", "null" ], "description": "Offer duration in days", "examples": [ "30" ] }, "maxRecurringPayable": { "type": "integer", "description": "Maximum recurring payable count", "examples": [ 1 ] }, "includeGiftCard": { "type": [ "boolean", "null" ], "description": "Whether gift cards are included", "examples": [ false ] }, "affiliateCounts": { "type": "object", "description": "Approved and pending affiliate counts for this offer.", "examples": [ { "approvedCount": 3, "pendingCount": 2 } ], "properties": { "approvedCount": { "type": "integer" }, "pendingCount": { "type": "integer" } }, "required": [ "approvedCount", "pendingCount" ] }, "updatedAt": { "type": "string", "description": "Last update timestamp in ISO 8601 format", "examples": [ "2025-09-25T19:07:33Z" ] }, "createdAt": { "type": "string", "description": "Creation timestamp in ISO 8601 format", "examples": [ "2025-09-25T19:07:33Z" ] }, "performance": { "type": "object", "description": "Performance metrics for the offer, aggregated from conversion data and currency-normalized to the client's default currency.", "properties": { "currency": { "type": "string", "description": "ISO 4217 currency code for all monetary values in this performance block.", "examples": [ "USD" ] }, "pending": { "type": "object", "description": "Pending performance metrics.", "properties": { "revenue": { "type": "number", "description": "Pending revenue.", "examples": [ 500 ] }, "commission": { "type": "number", "description": "Pending commission.", "examples": [ 75.25 ] }, "conversions": { "type": "integer", "description": "Total pending conversions count.", "examples": [ 12 ] }, "payouts": { "type": "number", "description": "Pending payouts amount.", "examples": [ 150 ] }, "uniqueOrders": { "type": "integer", "description": "Pending unique orders.", "examples": [ 8 ] } }, "required": [ "revenue", "commission", "conversions", "payouts", "uniqueOrders" ] }, "30Days": { "type": "object", "description": "Last 30 days performance metrics.", "properties": { "revenue": { "type": "number", "description": "Revenue in the last 30 days.", "examples": [ 150 ] }, "commission": { "type": "number", "description": "Commission in the last 30 days.", "examples": [ 120 ] }, "conversions": { "type": "integer", "description": "Conversions in the last 30 days.", "examples": [ 15 ] }, "payouts": { "type": "number", "description": "Payouts in the last 30 days.", "examples": [ 200 ] }, "clicks": { "type": "integer", "description": "Clicks in the last 30 days.", "examples": [ 300 ] }, "uniqueOrders": { "type": "integer", "description": "Unique orders in the last 30 days.", "examples": [ 12 ] } }, "required": [ "revenue", "commission", "conversions", "payouts", "clicks", "uniqueOrders" ] }, "total": { "type": "object", "description": "Total lifetime performance metrics.", "properties": { "revenue": { "type": "number", "description": "Total approved revenue.", "examples": [ 423.45 ] }, "commission": { "type": "number", "description": "Total commission.", "examples": [ 167.89 ] }, "conversions": { "type": "integer", "description": "Total conversions count.", "examples": [ 112 ] }, "payouts": { "type": "number", "description": "Total payouts.", "examples": [ 900 ] }, "clicks": { "type": "integer", "description": "Total clicks.", "examples": [ 5000 ] }, "uniqueOrders": { "type": "integer", "description": "Total unique orders.", "examples": [ 50 ] } }, "required": [ "revenue", "commission", "conversions", "payouts", "clicks", "uniqueOrders" ] } }, "required": [ "currency", "pending", "30Days", "total" ] } }, "required": [ "id", "publicId", "name", "commission", "returnCustomerCommission", "returningCustomerFlatRateCurrency", "flatRateCurrency", "commissionTerms", "isRequireNewCustomer", "isSubscriptionsDenyRenewals", "attributionWindow", "isDefault", "isAutoApproveConversions", "isAutoDenyConversions", "isAutoUnqualifyConversions", "isAutoApproveAffiliates", "isPrivate", "cs", "type", "tierCalculationMode", "tierCount", "quantityMultiply", "duration", "maxRecurringPayable", "includeGiftCard", "affiliateCounts", "updatedAt", "createdAt", "performance" ], "title": "OfferResource" }, "PatchAffiliateCustomFieldRequest": { "type": "object", "description": "Patch Affiliate Custom Field Request\n\nValidates the request to update an affiliate's custom field value.\nThe affiliate ID and custom field ID are extracted from the route parameters.", "properties": { "affiliateId": { "type": "integer", "description": "The affiliate ID to update the custom field for", "example": 12345 }, "customFieldId": { "type": "integer", "description": "The custom field ID to update", "example": 42 }, "value": { "type": "string", "description": "The new value for the custom field", "example": "My new answer" } }, "required": [ "affiliateId", "customFieldId", "value" ], "title": "PatchAffiliateCustomFieldRequest" }, "ProductCategoriesResource": { "type": "object", "additionalProperties": {}, "title": "ProductCategoriesResource" }, "PromotionMethodCollection": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PromotionMethodResource" } } }, "required": [ "data" ], "title": "PromotionMethodCollection" }, "PromotionMethodResource": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique identifier of the promotion method.", "examples": [ 123 ] }, "type": { "type": "string", "description": "The type of promotion method.", "examples": [ "COUPON" ] }, "value": { "type": "string", "description": "The trigger value (coupon code, SKU, or email).", "examples": [ "SAVE20" ] }, "status": { "type": "string", "description": "The status of the promotion method.", "examples": [ "active" ] }, "affiliate": { "type": "object", "description": "The affiliate who owns this promotion method.", "examples": [ { "id": 456, "firstName": "Sarah", "lastName": "Johnson", "status": "PENDING" } ], "properties": { "id": { "type": "integer" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "firstName", "lastName", "status" ] }, "createdAt": { "type": [ "string", "null" ], "description": "The timestamp when the promotion method was created.", "examples": [ "2026-03-12T14:30:00Z" ] } }, "required": [ "id", "type", "value", "status", "affiliate", "createdAt" ], "title": "PromotionMethodResource" }, "ProspectFeedbackResource": { "type": "object", "properties": { "prospectId": { "type": "integer", "description": "The prospect ID this feedback is for", "examples": [ 12345 ] }, "type": { "type": "string", "description": "The feedback type (positive or negative)", "examples": [ "negative" ] }, "reason": { "type": [ "string", "null" ], "description": "The reason for the feedback", "examples": [ "Not relevant to my target audience" ] }, "createdAt": { "type": "string", "description": "The timestamp when the feedback was created", "examples": [ "2025-12-17T14:30:00+00:00" ] }, "updatedAt": { "type": "string", "description": "The timestamp when the feedback was last updated", "examples": [ "2025-12-17T14:35:00+00:00" ] } }, "required": [ "prospectId", "type", "reason", "createdAt", "updatedAt" ], "title": "ProspectFeedbackResource" }, "ProspectPitchResource": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique pitch ID.", "examples": [ 123 ] }, "partnerId": { "type": "integer", "description": "The partner/prospect ID.", "examples": [ 456 ] }, "pitchMessage": { "type": "string", "description": "The pitch message content.", "examples": [ "Hi, I'd love to discuss a partnership opportunity with you." ] }, "createdAt": { "type": "string", "description": "When the pitch was created in ISO 8601 format in the client's timezone.", "examples": [ "2025-09-25T15:07:33-04:00" ] }, "updatedAt": { "type": "string", "description": "When the pitch was last updated in ISO 8601 format in the client's timezone.", "examples": [ "2025-09-25T15:07:33-04:00" ] } }, "required": [ "id", "partnerId", "pitchMessage", "createdAt", "updatedAt" ], "title": "ProspectPitchResource" }, "ProspectResource": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique identifier for the prospect", "examples": [ 12345 ] }, "profileName": { "type": "string", "description": "The name of the prospect's profile", "examples": [ "Acme Outdoors Blog" ] }, "profileType": { "type": [ "string", "null" ], "description": "The type of profile (e.g., blogger, influencer)", "examples": [ "blogger" ] }, "platform": { "type": "string", "description": "The platform where the prospect is active", "examples": [ "Website" ] }, "url": { "type": "string", "description": "The URL of the prospect's profile or website", "examples": [ "https://www.example.com/blog" ] }, "status": { "type": "integer", "description": "The status of the prospect", "examples": [ 1 ] }, "createdAt": { "type": "string", "description": "The timestamp when the prospect was created", "examples": [ "2025-11-05T17:36:21+00:00" ] }, "updatedAt": { "type": "string", "description": "The timestamp when the prospect was last updated", "examples": [ "2025-11-05T17:36:21+00:00" ] } }, "required": [ "id", "profileName", "profileType", "platform", "url", "status", "createdAt", "updatedAt" ], "title": "ProspectResource" }, "ResendWelcomeEmailRequest": { "type": "object", "description": "Resend Welcome Email Request\n\nValidates the request to resend a welcome email to an affiliate.\nThe affiliate ID is extracted from the route parameter.", "properties": { "affiliateId": { "type": "integer", "description": "The affiliate ID to resend the welcome email to", "example": 12345 } }, "required": [ "affiliateId" ], "title": "ResendWelcomeEmailRequest" }, "SearchOrdersResource": { "type": "object", "properties": { "isOrderFound": { "type": "boolean", "description": "Whether the searched order ID corresponds to any non-redacted conversion queue\nrecord for this client. Distinguishes \"order not found\" (false) from\n\"order exists but unavailable to this affiliate\" (true) when availableOrders is empty.", "examples": [ true ] }, "availableOrders": { "type": "array", "description": "Orders available to be credited to the affiliate.", "examples": [ [ { "id": 1, "orderId": "ORD-12345", "customerName": "John Smith" } ] ], "items": { "type": "object", "properties": { "id": { "type": "integer" }, "orderId": { "type": "string" }, "customerName": { "type": [ "string", "null" ] } }, "required": [ "id", "orderId", "customerName" ] } }, "otherAffiliatesWithConversions": { "type": "array", "description": "Other affiliates that already have conversions for the searched order.", "examples": [ [ { "affiliateId": 99, "firstName": "Jane", "lastName": "Smith" } ] ], "items": { "type": "object", "properties": { "affiliateId": { "type": "integer" }, "firstName": { "type": "string" }, "lastName": { "type": "string" } }, "required": [ "affiliateId", "firstName", "lastName" ] } } }, "required": [ "isOrderFound", "availableOrders", "otherAffiliatesWithConversions" ], "title": "SearchOrdersResource" }, "SessionAccountResource": { "type": "object", "properties": { "userType": { "type": "string", "description": "`client` for an account owner, or `client_user` for a sub-user seat on the account.", "examples": [ "client" ] }, "clientId": { "type": "integer", "description": "The merchant account.", "examples": [ 410 ] }, "clientUserId": { "type": [ "integer", "null" ], "description": "The sub-user seat, or null for the account owner.", "examples": [ 88 ] }, "name": { "type": "string", "description": "The account's store name, or the sign-in email for this entry when no store name is set.", "examples": [ "Acme Store" ] }, "domain": { "type": [ "string", "null" ], "description": "The account's main tracking domain, or null when none is set.", "examples": [ "acme.example.com" ] }, "isCurrent": { "type": "boolean", "description": "Whether the connection currently acts on this account; exactly one entry is true.", "examples": [ true ] } }, "required": [ "userType", "clientId", "clientUserId", "name", "domain", "isCurrent" ], "title": "SessionAccountResource" }, "SessionAccountResourceCollection": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SessionAccountResource" } }, "hasNextPage": { "type": "boolean" } }, "required": [ "data", "hasNextPage" ], "title": "SessionAccountResourceCollection" }, "SkuExclusionResource": { "type": "object", "properties": { "id": { "type": "integer", "description": "The exclusion record ID.", "examples": [ 42 ] }, "sku": { "type": [ "string", "null" ], "description": "The excluded product SKU.", "examples": [ "PROD-12345" ] }, "nameLabel": { "type": "string", "description": "A user-friendly label for the excluded product.", "examples": [ "Premium Widget" ] }, "status": { "type": "string", "description": "The status of the exclusion. Always 'active' for this endpoint.", "examples": [ "active" ] }, "createdAt": { "type": "string", "description": "When the exclusion was created, in ISO 8601 format.", "examples": [ "2025-09-25T15:07:33+00:00" ] } }, "required": [ "id", "sku", "nameLabel", "status", "createdAt" ], "title": "SkuExclusionResource" }, "StateResource": { "type": "object", "properties": { "stateName": { "type": "string", "description": "The name of the state or province", "examples": [ "Alabama" ] }, "stateSubdivisionCode": { "type": "string", "description": "The ISO 3166-2 subdivision code for the state or province", "examples": [ "AL" ] } }, "required": [ "stateName", "stateSubdivisionCode" ], "title": "StateResource" }, "StateResourceCollection": { "type": "array", "items": { "$ref": "#/components/schemas/StateResource" }, "title": "StateResourceCollection" }, "SubmitProspectFeedbackRequest": { "type": "object", "description": "Submit Prospect Feedback Request\n\nValidates feedback submission for AI-recommended prospects. Requires feedback type\n(positive or negative) and conditionally requires a reason when feedback is negative.", "properties": { "type": { "type": "string", "description": "The feedback type (positive or negative)", "example": "negative" }, "reason": { "type": [ "string", "null" ], "description": "The reason for the feedback (required for negative, optional for positive)", "example": "Not relevant to my target audience" } }, "required": [ "type" ], "title": "SubmitProspectFeedbackRequest" }, "TimezoneResource": { "type": "object", "properties": { "label": { "type": "string", "description": "Human-readable timezone label with UTC offset", "examples": [ "(UTC-05:00) Eastern Time (US & Canada)" ] }, "value": { "type": "string", "description": "IANA timezone identifier", "examples": [ "America/New_York" ] } }, "required": [ "label", "value" ], "title": "TimezoneResource" }, "TimezoneResourceCollection": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TimezoneResource" } } }, "required": [ "data" ], "title": "TimezoneResourceCollection" }, "UpdateAffiliateRequest": { "type": "object", "description": "Update Affiliate Request\n\nValidates the request to update an affiliate's details including status,\noffer assignment, custom fields, URL configuration, the merchant-assigned\nexternal identifier, and profile fields (email, first name, last name,\ncompany, address, phone, country).", "properties": { "id": { "type": "integer", "description": "The affiliate ID to update", "example": 12345 }, "status": { "type": "string", "description": "The new status for the affiliate (PENDING, APPROVED, or DENIED). To lock or\nunlock an APPROVED affiliate, use the `locked` field instead of this one.", "example": "APPROVED" }, "locked": { "type": "boolean", "description": "Whether to lock the affiliate. true sets the affiliate's lock state ON;\nfalse unlocks it. Only accepted when the affiliate's current status is\nAPPROVED. Cannot be combined with the `status` field in the same request.", "example": true }, "offerId": { "type": "integer", "description": "The offer ID to assign to the affiliate", "example": 42 }, "uniqueMerchantId": { "type": [ "string", "null" ], "description": "The merchant-assigned external identifier for the affiliate", "example": "MERCH-12345" }, "parentAffiliateId": { "type": [ "integer", "null" ], "description": "The id of another affiliate to set as this affiliate's MLM parent. Pass null to clear.", "example": 12345 }, "sendEmailNotifications": { "type": "boolean", "description": "Whether to send email notifications for the status change", "example": false }, "email": { "type": "string", "description": "The affiliate's email address. Must be unique within the merchant's affiliates,\nignoring the affiliate being updated.", "example": "affiliate@example.com" }, "firstName": { "type": "string", "description": "The affiliate's first name. Cannot be cleared.", "example": "Jane" }, "lastName": { "type": "string", "description": "The affiliate's last name. Cannot be cleared.", "example": "Doe" }, "company": { "type": [ "string", "null" ], "description": "The affiliate's company name. Pass null to clear.", "example": "Acme Inc" }, "address1": { "type": [ "string", "null" ], "description": "The affiliate's primary street address. Pass null to clear.", "example": "123 Main St" }, "address2": { "type": [ "string", "null" ], "description": "The affiliate's secondary street address (apartment, suite, etc). Pass null to clear.", "example": "Suite 100" }, "city": { "type": [ "string", "null" ], "description": "The affiliate's city. Pass null to clear.", "example": "New York" }, "state": { "type": [ "string", "null" ], "description": "The affiliate's state or subdivision code. Must belong to the country in scope\n(the new `country` value if provided, otherwise the affiliate's stored country).", "example": "NY" }, "zip": { "type": [ "string", "null" ], "description": "The affiliate's postal code. Pass null to clear.", "example": "10001" }, "phone": { "type": [ "string", "null" ], "description": "The affiliate's phone number in E.164 format. Pass null to clear.", "example": "+14155552671" }, "country": { "type": [ "string", "null" ], "description": "The affiliate's country as an active ISO 3166-1 alpha-2 code. Pass null to clear.", "example": "US" }, "url": { "type": "object", "description": "URL configuration object", "example": { "path": "my-custom-path", "additionalParameters": "utm_source=affiliate" }, "properties": { "path": { "type": "string", "description": "The custom URL path (default subfolder) for the affiliate. Accepts the\n{macro} tokens the referral-link Lambda resolves per affiliate at link\ngeneration time: {affiliate_id}, {affiliate_code}, {affiliate_first_name},\n{affiliate_last_name}, {company_name}, {offer_id}.", "example": "shop/{affiliate_code}" }, "additionalParameters": { "type": "string", "description": "Additional query parameters for the affiliate URL", "example": "utm_source=affiliate&utm_medium=link" } } }, "customFields": { "type": "array", "description": "Array of custom field updates with id and value pairs, up to 100 entries", "example": [ { "id": 1, "value": "My answer" }, { "id": 2, "value": "Another answer" } ], "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The custom field ID", "example": 1 }, "value": { "type": "string", "description": "The custom field value", "example": "My answer" } }, "required": [ "id", "value" ] } } }, "required": [ "id" ], "title": "UpdateAffiliateRequest" }, "UpdateConversionStatusRequest": { "type": "object", "description": "Update Conversion Status Request\n\nValidates request body for updating the status of a conversion.", "properties": { "status": { "type": "string", "description": "The new status for the conversion.", "example": "APPROVED" } }, "required": [ "status" ], "title": "UpdateConversionStatusRequest" }, "UpdateOfferRequest": { "type": "object", "description": "Update Offer Request\n\nValidates request body for updating an existing offer. All fields are optional\nand allow partial updates. Includes custom validation for business rules.", "properties": { "name": { "type": "string", "description": "The display name for the offer", "example": "Summer Sale Offer" }, "isDefault": { "type": "boolean", "description": "Whether this is the default offer for the client", "example": true }, "attributionWindow": { "type": "integer", "description": "Attribution window in days", "example": 30 }, "isPrivate": { "type": "boolean", "description": "Whether the offer is private", "example": false }, "commission": { "type": "integer", "description": "The commission percentage or flat rate amount", "example": 10 } }, "title": "UpdateOfferRequest" }, "UpdatePromotionMethodRequest": { "type": "object", "properties": { "status": { "type": "string", "description": "The target status for the promotion method. Only \"active\" is accepted (case-insensitive).\nInvalid values produce a 400 response; a missing field produces a 422 response.", "example": "active" } }, "required": [ "status" ], "title": "UpdatePromotionMethodRequest" }, "UpdateWebhookEndpointRequest": { "type": "object", "description": "Validates an edit to a webhook endpoint. Both fields are optional but at\nleast one is required; `topics` REPLACES the subscription rather than\nmerging, and an omitted field is left unchanged.", "properties": { "url": { "type": "string", "description": "HTTPS delivery URL. Omit to leave unchanged.", "example": "https://merchant.example.com/hooks/refersion" }, "topics": { "type": "array", "description": "Event types to subscribe to (JSON array, min 1, no duplicates).\nREPLACES the current subscription; omit to leave unchanged.", "example": [ "conversion.created", "payout.created" ], "items": { "type": "string", "description": "A single event type. Marketplace members: conversion.created/approved/denied\nand payout.created only; merchant clients may use any registered type.", "example": "conversion.created" } } }, "title": "UpdateWebhookEndpointRequest" }, "WebhookEndpointCollection": { "type": "object", "properties": { "data": { "type": "array", "description": "The webhook endpoints registered for the authenticated owner, in\nthe order the webhook delivery service returns them. Empty when the\nowner has configured none.", "examples": [ [ { "id": "ep_2ABc4defGHIjkl5MNop6qRsTU", "url": "https://merchant.example.com/hooks/refersion", "topics": [ "conversion.created" ], "isSubscribedToAllTopics": false } ] ], "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "topics": { "type": "array", "items": { "type": "string" } }, "isSubscribedToAllTopics": { "type": "boolean" } }, "required": [ "id", "url", "topics", "isSubscribedToAllTopics" ] } }, "meta": { "type": "object", "description": "Cursor pagination metadata for fetching the next bounded page.", "examples": [ { "limit": 100, "hasMore": true, "nextCursor": "cursor_page_2" } ], "properties": { "limit": { "type": "integer" }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "limit", "hasMore", "nextCursor" ] } }, "required": [ "data", "meta" ], "title": "WebhookEndpointCollection" }, "WebhookEndpointResource": { "type": "object", "properties": { "id": { "type": "string", "description": "The webhook endpoint's identifier. This is the value\nDELETE /v3/webhooks/endpoints/{endpointId} accepts, so a caller\ncan remove what it just created without opening the webhook settings\nportal.", "examples": [ "ep_2abcDEF456ghi" ] }, "url": { "type": "string", "description": "The URL webhook messages are delivered to.", "examples": [ "https://merchant.example.com/hooks/refersion" ] }, "topics": { "type": "array", "description": "The event types this endpoint is explicitly subscribed to. Empty\nonly when isSubscribedToAllTopics is true — read that flag rather\nthan inferring the subscription from an empty list.", "examples": [ [ "conversion.created", "payout.created" ] ], "items": { "type": "string" } }, "isSubscribedToAllTopics": { "type": "boolean", "description": "Whether the endpoint receives every event type. True means no\nevent-type filter is applied, so `topics` is empty and cannot be\nsent back to POST /v3/webhooks/endpoints, which requires at least\none type.", "examples": [ false ] } }, "required": [ "id", "url", "topics", "isSubscribedToAllTopics" ], "title": "WebhookEndpointResource" } }, "responses": { "ValidationException": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } } } } }