{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://api.wikiup.app/affiliate-management.schema.json",
  "title": "Wikiup affiliate management API",
  "description": "Select the named response definition matching the operation. Examples use synthetic records. Ratings are pending deployment.",
  "$defs": {
    "Account": {
      "type": "object",
      "description": "Affiliate profile; this does not grant hosting access.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Affiliate account UID, derived from the authenticated account."
        },
        "name": {
          "type": "string",
          "description": "Affiliate display name."
        },
        "website": {
          "type": "string",
          "description": "HTTPS affiliate website or social profile URL."
        },
        "active": {
          "type": "boolean",
          "description": "Whether the platform permits affiliate activity. Self-service cannot reactivate a suspended account."
        },
        "createdAt": {
          "type": "string",
          "description": "Account creation time. ISO 8601 instant; format displayed times in the relevant property timezone.",
          "format": "date-time"
        },
        "imageUrl": {
          "type": [
            "string",
            "null"
          ],
          "description": "Affiliate card image path under /api/web-assets/affilate-profile-pics/{uid}/, separate from user profile photos. Null means no image."
        },
        "description": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 500,
          "description": "Affiliate card description, plain text; null when absent."
        },
        "region": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 120,
          "description": "Affiliate card region, plain text; null when absent."
        }
      },
      "required": [
        "id",
        "name",
        "website",
        "active",
        "createdAt"
      ],
      "additionalProperties": false
    },
    "Terms": {
      "type": "object",
      "description": "Read-only Wikiup-wide commission policy. Legacy per-affiliate terms no longer control commission.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Affiliate account UID."
        },
        "commissionBps": {
          "type": "integer",
          "const": 75,
          "description": "Fixed 75 basis points (0.75%) of accommodation after discounts only; excludes add-ons, fees and taxes."
        }
      },
      "required": [
        "id",
        "commissionBps"
      ],
      "additionalProperties": false
    },
    "AccountResponse": {
      "type": "object",
      "description": "Affiliate account response.",
      "properties": {
        "account": {
          "description": "Null until the profile is created.",
          "anyOf": [
            {
              "$ref": "#/$defs/Account"
            },
            {
              "type": "null"
            }
          ]
        },
        "terms": {
          "description": "Read-only fixed Wikiup commission policy, including before affiliate onboarding.",
          "anyOf": [
            {
              "$ref": "#/$defs/Terms"
            },
            {
              "type": "null"
            }
          ]
        },
        "email": {
          "type": "string",
          "description": "Verified email of the authenticated session."
        },
        "platformAdmin": {
          "type": "boolean",
          "description": "Whether this session has the platform administration claim."
        }
      },
      "required": [
        "account",
        "terms",
        "email",
        "platformAdmin"
      ],
      "additionalProperties": false
    },
    "Selection": {
      "type": "object",
      "description": "Affiliate visibility selection.",
      "properties": {
        "propertyId": {
          "type": "string",
          "description": "Raw Wikiup property ID; not a prefixed listing ID."
        },
        "visible": {
          "type": "boolean",
          "description": "True includes this property; false blacklists it for this affiliate only."
        }
      },
      "required": [
        "propertyId",
        "visible"
      ],
      "additionalProperties": false
    },
    "Listing": {
      "type": "object",
      "description": "Private affiliate management listing; status=all includes every request state. Only the newest request per property is returned.",
      "properties": {
        "propertyId": {
          "type": "string",
          "description": "Raw Wikiup property ID; not a hotel/rental listing ID."
        },
        "name": {
          "type": "string",
          "description": "Public listing title, falling back to property name."
        },
        "destination": {
          "type": [
            "string",
            "null"
          ],
          "description": "Display destination name, falling back to saved city/state. Null when geography is unavailable. Not a destination search ID."
        },
        "visible": {
          "type": "boolean",
          "description": "Compatibility field derived from status: true only for approved. Inventory eligibility is checked separately for public reads."
        },
        "requestId": {
          "type": "string",
          "description": "Newest request ID used to retrieve private review details and change listing status."
        },
        "status": {
          "type": "string",
          "enum": [
            "pending",
            "approved",
            "denied",
            "owner_suspended",
            "affiliate_suspended",
            "both_suspended",
            "withdrawn",
            "removed"
          ],
          "description": "Current listing lifecycle state, including both parties\u2019 suspensions."
        },
        "listingId": {
          "type": [
            "string",
            "null"
          ],
          "description": "Stable public hotel/rental listing ID when approved with eligible inventory and a single public listing target. Null for other request states, unavailable inventory, or a property with multiple rental targets. Use requestId for private management regardless."
        },
        "coverImage": {
          "description": "First saved listing photo using the public image contract; null when no photo is available. No slideshow fallback.",
          "anyOf": [
            {
              "$ref": "#/$defs/PublicImage"
            },
            {
              "type": "null"
            }
          ]
        },
        "tagLine": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 100,
          "description": "Owner-supplied property tagline; null when unset."
        }
      },
      "required": [
        "propertyId",
        "name",
        "destination",
        "visible",
        "requestId",
        "status",
        "listingId",
        "coverImage",
        "tagLine"
      ],
      "additionalProperties": false
    },
    "ListingsResponse": {
      "type": "object",
      "description": "Property management page, not date availability.",
      "properties": {
        "listings": {
          "type": "array",
          "description": "Up to 12 matching properties, ordered by propertyId. Search and status filtering happen before pagination.",
          "items": {
            "$ref": "#/$defs/Listing"
          }
        },
        "meta": {
          "type": "object",
          "description": "Pagination for this management catalog.",
          "properties": {
            "page": {
              "type": "integer",
              "description": "Requested one-based page."
            },
            "nextPage": {
              "type": [
                "integer",
                "null"
              ],
              "description": "Next page number, or null at the end."
            }
          },
          "required": [
            "page",
            "nextPage"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "listings",
        "meta"
      ],
      "additionalProperties": false
    },
    "Ratings": {
      "type": "object",
      "description": "Current affiliate editorial ratings for one property.",
      "properties": {
        "propertyId": {
          "type": "string",
          "description": "Raw property ID."
        },
        "starRating": {
          "type": [
            "number",
            "null"
          ],
          "description": "Affiliate editorial classification; not guest reviews. Null is unset.",
          "minimum": 1,
          "maximum": 5,
          "multipleOf": 0.5
        },
        "priceTier": {
          "type": [
            "integer",
            "null"
          ],
          "description": "1 Budget, 2 Value, 3 Mid-range, 4 Upscale, 5 Luxury; null is unset. Not a price quote.",
          "minimum": 1,
          "maximum": 5
        }
      },
      "required": [
        "propertyId",
        "starRating",
        "priceTier"
      ],
      "additionalProperties": false
    },
    "Booking": {
      "type": "object",
      "description": "Attributed booking projection without guest or access details.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Reservation ID for report correlation."
        },
        "propertyName": {
          "type": "string",
          "description": "Current public property title/name, or Unavailable property if no longer readable."
        },
        "bookedAt": {
          "type": "string",
          "description": "Booking creation instant. ISO 8601 instant; format displayed times in the relevant property timezone.",
          "format": "date-time"
        },
        "checkIn": {
          "type": "string",
          "description": "Property-local arrival date, YYYY-MM-DD."
        },
        "checkOut": {
          "type": "string",
          "description": "Property-local departure date, YYYY-MM-DD; checkout is not an occupied night."
        },
        "reservationStatus": {
          "type": "string",
          "description": "Stored reservation lifecycle status, such as upcoming, checkedin, checkedout or canceled."
        },
        "currency": {
          "type": "string",
          "description": "Three-letter currency code. Money is in major currency units."
        },
        "accommodationSubtotal": {
          "type": "number",
          "description": "Accommodation subtotal after discounts captured at attribution; excludes taxes and fees."
        },
        "refunds": {
          "type": "number",
          "description": "Successful completed ledger refunds for this reservation; conservatively reduce commission base dollar-for-dollar."
        },
        "commissionBps": {
          "type": "integer",
          "const": 75,
          "description": "Fixed 75 basis points (0.75%) of accommodation after discounts only; excludes add-ons, fees and taxes."
        },
        "pendingCommission": {
          "type": "number",
          "description": "Fixed-rate estimated commission before checkout; zero after checkout/cancellation."
        },
        "earnedCommission": {
          "type": "number",
          "description": "Fixed-rate commission after checkedout status, reduced by refunds and limited to collected funds; not a payout."
        },
        "commissionStatus": {
          "enum": [
            "canceled",
            "earned",
            "pending"
          ],
          "description": "Commission calculation state. Legacy missing rates use the fixed policy."
        }
      },
      "required": [
        "id",
        "propertyName",
        "bookedAt",
        "checkIn",
        "checkOut",
        "reservationStatus",
        "currency",
        "accommodationSubtotal",
        "refunds",
        "commissionBps",
        "pendingCommission",
        "earnedCommission",
        "commissionStatus"
      ],
      "additionalProperties": false
    },
    "ReportsResponse": {
      "type": "object",
      "description": "One page of attributed bookings.",
      "properties": {
        "bookings": {
          "type": "array",
          "description": "Up to 25 attributed bookings, newest creation first.",
          "items": {
            "$ref": "#/$defs/Booking"
          }
        },
        "meta": {
          "type": "object",
          "description": "Report pagination and accounting scope.",
          "properties": {
            "nextCursor": {
              "type": [
                "string",
                "null"
              ],
              "description": "Opaque cursor for the next request; null when finished."
            },
            "totalsScope": {
              "const": "page",
              "description": "Values apply to the returned page, not an account-wide aggregate."
            },
            "payoutsTracked": {
              "const": false,
              "description": "Payouts are not tracked here. Never label earned commission as paid."
            }
          },
          "required": [
            "nextCursor",
            "totalsScope",
            "payoutsTracked"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "bookings",
        "meta"
      ],
      "additionalProperties": false
    },
    "AdminAccount": {
      "type": "object",
      "description": "Affiliate profile; this does not grant hosting access.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Affiliate account UID, derived from the authenticated account."
        },
        "name": {
          "type": "string",
          "description": "Affiliate display name."
        },
        "website": {
          "type": "string",
          "description": "HTTPS affiliate website or social profile URL."
        },
        "active": {
          "type": "boolean",
          "description": "Whether the platform permits affiliate activity. Self-service cannot reactivate a suspended account."
        },
        "createdAt": {
          "type": "string",
          "description": "Account creation time. ISO 8601 instant; format displayed times in the relevant property timezone.",
          "format": "date-time"
        },
        "terms": {
          "description": "Current platform terms, or null.",
          "anyOf": [
            {
              "$ref": "#/$defs/Terms"
            },
            {
              "type": "null"
            }
          ]
        },
        "imageUrl": {
          "type": [
            "string",
            "null"
          ],
          "description": "Affiliate card image path under /api/web-assets/affilate-profile-pics/{uid}/, separate from user profile photos. Null means no image."
        },
        "description": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 500,
          "description": "Affiliate card description, plain text; null when absent."
        },
        "region": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 120,
          "description": "Affiliate card region, plain text; null when absent."
        }
      },
      "required": [
        "id",
        "name",
        "website",
        "active",
        "createdAt",
        "terms"
      ],
      "additionalProperties": false
    },
    "AdminResponse": {
      "type": "object",
      "description": "Platform-only affiliate account page.",
      "properties": {
        "accounts": {
          "type": "array",
          "description": "Up to 25 profiles with their current terms.",
          "items": {
            "$ref": "#/$defs/AdminAccount"
          }
        },
        "nextCursor": {
          "type": [
            "string",
            "null"
          ],
          "description": "Opaque cursor for the next page; null when finished."
        }
      },
      "required": [
        "accounts",
        "nextCursor"
      ],
      "additionalProperties": false
    },
    "AdminUpdateResponse": {
      "type": "object",
      "description": "Readback of platform changes.",
      "properties": {
        "account": {
          "description": "Updated affiliate profile.",
          "$ref": "#/$defs/Account"
        },
        "terms": {
          "description": "Updated commission terms.",
          "$ref": "#/$defs/Terms"
        }
      },
      "required": [
        "account",
        "terms"
      ],
      "additionalProperties": false
    },
    "ErrorResponse": {
      "type": "object",
      "description": "Affiliate error response.",
      "properties": {
        "error": {
          "type": "string",
          "description": "Human-readable error message."
        },
        "details": {
          "type": "array",
          "description": "Present for validation errors (422).",
          "items": {
            "type": "object",
            "description": "Invalid field.",
            "properties": {
              "field": {
                "type": "string",
                "description": "Dotted field path."
              },
              "message": {
                "type": "string",
                "description": "Validation explanation."
              }
            },
            "required": [
              "field",
              "message"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "error"
      ],
      "additionalProperties": false
    },
    "ReportsQuery": {
      "type": "object",
      "description": "Optional filters for GET /api/affiliates/reports, applied before pagination. Omit dates for all time. Keep filters fixed while following a cursor.",
      "properties": {
        "search": {
          "type": "string",
          "maxLength": 120,
          "description": "Case-insensitive property name or listing title substring."
        },
        "from": {
          "type": "string",
          "format": "date",
          "description": "Inclusive check-in date, YYYY-MM-DD."
        },
        "to": {
          "type": "string",
          "format": "date",
          "description": "Inclusive check-in date, YYYY-MM-DD; must not precede from."
        },
        "cursor": {
          "type": "string",
          "maxLength": 4096,
          "description": "Previous meta.nextCursor; omit when filters change."
        }
      },
      "additionalProperties": false
    },
    "PublicImage": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable identifier of this resource; preserve it unchanged."
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "Public versioned photo URL. Use the returned URL unchanged; it contains no API key."
        },
        "alt": {
          "type": "string",
          "description": "Image alternative text for accessible presentation."
        },
        "width": {
          "type": "integer",
          "minimum": 1,
          "description": "Actual image width in pixels; do not assume the nominal thumbnail width."
        },
        "height": {
          "type": "integer",
          "minimum": 1,
          "description": "Actual image height in pixels; preserve its aspect ratio."
        },
        "variants": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ImageVariant"
          },
          "description": "Prepared image sizes; choose by displayed width and pixel density. Original image remains available at url."
        },
        "group": {
          "anyOf": [
            {
              "$ref": "#/$defs/PhotoGroup"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional owner-defined photo group; null means ungrouped."
        }
      },
      "required": [
        "id",
        "url",
        "alt",
        "width",
        "height",
        "variants",
        "group"
      ],
      "additionalProperties": false,
      "description": "Response structure: PublicImage."
    },
    "ImageVariant": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "format": "uri",
          "description": "Public versioned photo URL. Use the returned URL unchanged; it contains no API key."
        },
        "width": {
          "type": "integer",
          "minimum": 1,
          "description": "Actual image width in pixels; do not assume the nominal thumbnail width."
        },
        "height": {
          "type": "integer",
          "minimum": 1,
          "description": "Actual image height in pixels; preserve its aspect ratio."
        },
        "format": {
          "enum": [
            "avif",
            "webp",
            "jpeg",
            "png"
          ],
          "description": "Encoded thumbnail image format."
        }
      },
      "required": [
        "url",
        "width",
        "height",
        "format"
      ],
      "additionalProperties": false,
      "description": "Response structure: ImageVariant."
    },
    "PhotoGroup": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable identifier of this resource; preserve it unchanged."
        },
        "title": {
          "type": "string",
          "maxLength": 160,
          "description": "Display title supplied by Wikiup; group titles are Title Case."
        }
      },
      "required": [
        "id",
        "title"
      ],
      "additionalProperties": false,
      "description": "Response structure: PhotoGroup."
    },
    "ListingsQuery": {
      "type": "object",
      "description": "Private GET /api/affiliates/listings query. Keep filters unchanged while following nextPage; restart at page 1 after changing filters.",
      "properties": {
        "page": {
          "type": "integer",
          "minimum": 1,
          "maximum": 1000,
          "default": 1,
          "description": "One-based page; fixed 12 properties per page."
        },
        "search": {
          "type": "string",
          "maxLength": 200,
          "description": "Trimmed, case-insensitive substring of property name, listing title or town."
        },
        "status": {
          "type": "string",
          "enum": [
            "all",
            "pending",
            "approved",
            "denied",
            "owner_suspended",
            "affiliate_suspended",
            "both_suspended",
            "withdrawn",
            "removed"
          ],
          "description": "all includes every latest request state. Omit for approved and suspended states only."
        }
      },
      "additionalProperties": false
    }
  }
}
