{ "version": "1.0", "modules": [ { "name": "User Management", "prefix": "/users", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create User", "description": "Creates a new user account with email and password. Email must be unique. Password must be at least 8 characters with uppercase, lowercase, and number. Returns 409 if email already exists.", "request_body": { "schema_name": "UserCreate", "fields": [ { "name": "email", "type": "EmailStr", "required": true }, { "name": "role", "type": "UserRole", "required": true, "enum_values": [ "GUEST", "BUYER", "SELLER", "MODERATOR", "ADMIN" ] }, { "name": "is_active", "type": "bool", "required": false, "default": true }, { "name": "is_verified", "type": "bool", "required": false, "default": false }, { "name": "password", "type": "str", "required": true } ] }, "response": { "schema_name": "UserResponse", "fields": [ { "name": "email", "type": "str", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/", "summary": "List Users", "description": "Returns a paginated list of users. Supports optional filters for role, is_active, and is_verified status.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "role", "type": "UserRole", "required": false }, { "name": "is_active", "type": "bool", "required": false }, { "name": "is_verified", "type": "bool", "required": false } ], "response": { "schema_name": "UserResponse", "fields": [ { "name": "email", "type": "str", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/{id}", "summary": "Get User", "description": "Returns a single user by ID. Returns 404 if user not found.", "path_params": [ { "name": "id", "type": "str" } ], "response": { "schema_name": "UserResponse", "fields": [ { "name": "email", "type": "str", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{id}", "summary": "Update User", "description": "Updates user information. Email must remain unique. Returns 404 if user not found, 409 if email already in use.", "path_params": [ { "name": "id", "type": "str" } ], "request_body": { "schema_name": "UserUpdate", "fields": [ { "name": "email", "type": "EmailStr", "required": false, "nullable": true }, { "name": "role", "type": "UserRole", "required": false, "nullable": true, "enum_values": [ "GUEST", "BUYER", "SELLER", "MODERATOR", "ADMIN" ] }, { "name": "is_active", "type": "bool", "required": false, "nullable": true }, { "name": "is_verified", "type": "bool", "required": false, "nullable": true }, { "name": "last_login_at", "type": "datetime", "required": false, "nullable": true } ] }, "response": { "schema_name": "UserResponse", "fields": [ { "name": "email", "type": "str", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{id}", "summary": "Delete User", "description": "Permanently deletes a user and all associated data. Returns 404 if user not found.", "path_params": [ { "name": "id", "type": "str" } ], "status_code": 200 }, { "method": "GET", "path": "/{id}/profile", "summary": "Get User Profile Details", "description": "Returns detailed user information including user profile and seller profile if available. Returns 404 if user not found.", "path_params": [ { "name": "id", "type": "str" } ], "response": { "schema_name": "UserProfileDetailsResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "email", "type": "EmailStr", "required": true }, { "name": "role", "type": "UserRole", "required": true, "enum_values": [ "GUEST", "BUYER", "SELLER", "MODERATOR", "ADMIN" ] }, { "name": "is_active", "type": "bool", "required": true }, { "name": "is_verified", "type": "bool", "required": true }, { "name": "last_login_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "user_profile", "type": "UserprofileResponse", "required": false, "nullable": true, "fields": [ { "name": "first_name", "type": "str", "required": false, "nullable": true }, { "name": "last_name", "type": "str", "required": false, "nullable": true }, { "name": "display_name", "type": "str", "required": false, "nullable": true }, { "name": "bio", "type": "str", "required": false, "nullable": true }, { "name": "avatar_url", "type": "str", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "location", "type": "str", "required": false, "nullable": true }, { "name": "timezone", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] }, { "name": "seller_profile", "type": "SellerprofileResponse", "required": false, "nullable": true, "fields": [ { "name": "store_name", "type": "str", "required": true }, { "name": "store_description", "type": "str", "required": false, "nullable": true }, { "name": "store_logo_url", "type": "str", "required": false, "nullable": true }, { "name": "average_rating", "type": "str", "required": false, "nullable": true }, { "name": "total_sales", "type": "str", "required": false, "default": "0" }, { "name": "total_reviews", "type": "str", "required": false, "default": "0" }, { "name": "response_time_hours", "type": "str", "required": false, "nullable": true }, { "name": "is_verified_seller", "type": "bool", "required": false, "default": false }, { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/register", "summary": "Register New User", "description": "Registers a new user account. Email must be unique and valid. Password must meet security requirements. User is created with is_verified=False. Returns 409 if email already registered.", "request_body": { "schema_name": "UserCreate", "fields": [ { "name": "email", "type": "EmailStr", "required": true }, { "name": "role", "type": "UserRole", "required": true, "enum_values": [ "GUEST", "BUYER", "SELLER", "MODERATOR", "ADMIN" ] }, { "name": "is_active", "type": "bool", "required": false, "default": true }, { "name": "is_verified", "type": "bool", "required": false, "default": false }, { "name": "password", "type": "str", "required": true } ] }, "response": { "schema_name": "UserResponse", "fields": [ { "name": "email", "type": "str", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "POST", "path": "/login", "summary": "Login User", "description": "Authenticates user with email and password. Updates last_login_at timestamp. Returns 404 if credentials invalid, 400 if account inactive.", "response": { "schema_name": "UserResponse", "fields": [ { "name": "email", "type": "str", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/{id}/verify-email", "summary": "Verify Email Address", "description": "Marks user email as verified. Required before making purchases or becoming a seller. Returns 400 if already verified, 404 if user not found.", "path_params": [ { "name": "id", "type": "str" } ], "response": { "schema_name": "UserResponse", "fields": [ { "name": "email", "type": "str", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/{id}/become-seller", "summary": "Apply To Become Seller", "description": "Creates seller profile for user and changes role to SELLER. User must have verified email. Returns 400 if email not verified, 409 if seller profile already exists.", "path_params": [ { "name": "id", "type": "str" } ], "query_params": [ { "name": "store_description", "type": "str", "required": false } ], "response": { "schema_name": "SellerprofileResponse", "fields": [ { "name": "store_name", "type": "str", "required": true }, { "name": "store_description", "type": "str", "required": false, "nullable": true }, { "name": "store_logo_url", "type": "str", "required": false, "nullable": true }, { "name": "average_rating", "type": "str", "required": false, "nullable": true }, { "name": "total_sales", "type": "str", "required": false, "default": "0" }, { "name": "total_reviews", "type": "str", "required": false, "default": "0" }, { "name": "response_time_hours", "type": "str", "required": false, "nullable": true }, { "name": "is_verified_seller", "type": "bool", "required": false, "default": false }, { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "POST", "path": "/profiles", "summary": "Create User Profile", "description": "Creates extended profile information for a user. User must exist. Returns 404 if user not found, 409 if profile already exists.", "request_body": { "schema_name": "UserprofileCreate", "fields": [ { "name": "first_name", "type": "str", "required": false, "nullable": true }, { "name": "last_name", "type": "str", "required": false, "nullable": true }, { "name": "display_name", "type": "str", "required": false, "nullable": true }, { "name": "bio", "type": "str", "required": false, "nullable": true }, { "name": "avatar_url", "type": "str", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "location", "type": "str", "required": false, "nullable": true }, { "name": "timezone", "type": "str", "required": false, "nullable": true }, { "name": "user_id", "type": "str", "required": true } ] }, "response": { "schema_name": "UserprofileResponse", "fields": [ { "name": "first_name", "type": "str", "required": false, "nullable": true }, { "name": "last_name", "type": "str", "required": false, "nullable": true }, { "name": "display_name", "type": "str", "required": false, "nullable": true }, { "name": "bio", "type": "str", "required": false, "nullable": true }, { "name": "avatar_url", "type": "str", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "location", "type": "str", "required": false, "nullable": true }, { "name": "timezone", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/profiles", "summary": "List User Profiles", "description": "Returns a paginated list of user profiles. Supports optional filter by user_id.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "user_id", "type": "str", "required": false } ], "response": { "schema_name": "UserprofileResponse", "fields": [ { "name": "first_name", "type": "str", "required": false, "nullable": true }, { "name": "last_name", "type": "str", "required": false, "nullable": true }, { "name": "display_name", "type": "str", "required": false, "nullable": true }, { "name": "bio", "type": "str", "required": false, "nullable": true }, { "name": "avatar_url", "type": "str", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "location", "type": "str", "required": false, "nullable": true }, { "name": "timezone", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/profiles/{id}", "summary": "Get User Profile", "description": "Returns a single user profile by ID. Returns 404 if profile not found.", "path_params": [ { "name": "id", "type": "str" } ], "response": { "schema_name": "UserprofileResponse", "fields": [ { "name": "first_name", "type": "str", "required": false, "nullable": true }, { "name": "last_name", "type": "str", "required": false, "nullable": true }, { "name": "display_name", "type": "str", "required": false, "nullable": true }, { "name": "bio", "type": "str", "required": false, "nullable": true }, { "name": "avatar_url", "type": "str", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "location", "type": "str", "required": false, "nullable": true }, { "name": "timezone", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/profiles/{id}", "summary": "Update User Profile", "description": "Updates user profile information. Returns 404 if profile not found.", "path_params": [ { "name": "id", "type": "str" } ], "request_body": { "schema_name": "UserprofileUpdate", "fields": [ { "name": "first_name", "type": "str", "required": false, "nullable": true }, { "name": "last_name", "type": "str", "required": false, "nullable": true }, { "name": "display_name", "type": "str", "required": false, "nullable": true }, { "name": "bio", "type": "str", "required": false, "nullable": true }, { "name": "avatar_url", "type": "str", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "location", "type": "str", "required": false, "nullable": true }, { "name": "timezone", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "UserprofileResponse", "fields": [ { "name": "first_name", "type": "str", "required": false, "nullable": true }, { "name": "last_name", "type": "str", "required": false, "nullable": true }, { "name": "display_name", "type": "str", "required": false, "nullable": true }, { "name": "bio", "type": "str", "required": false, "nullable": true }, { "name": "avatar_url", "type": "str", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "location", "type": "str", "required": false, "nullable": true }, { "name": "timezone", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/profiles/{id}", "summary": "Delete User Profile", "description": "Permanently deletes a user profile. Returns 404 if profile not found.", "path_params": [ { "name": "id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/seller-profiles", "summary": "Create Seller Profile", "description": "Creates seller profile for a user. User must exist. Returns 404 if user not found, 409 if seller profile already exists.", "request_body": { "schema_name": "SellerprofileCreate", "fields": [ { "name": "store_name", "type": "str", "required": true }, { "name": "store_description", "type": "str", "required": false, "nullable": true }, { "name": "store_logo_url", "type": "str", "required": false, "nullable": true }, { "name": "average_rating", "type": "str", "required": false, "nullable": true }, { "name": "total_sales", "type": "str", "required": false, "default": "0" }, { "name": "total_reviews", "type": "str", "required": false, "default": "0" }, { "name": "response_time_hours", "type": "str", "required": false, "nullable": true }, { "name": "is_verified_seller", "type": "bool", "required": false, "default": false }, { "name": "user_id", "type": "str", "required": true } ] }, "response": { "schema_name": "SellerprofileResponse", "fields": [ { "name": "store_name", "type": "str", "required": true }, { "name": "store_description", "type": "str", "required": false, "nullable": true }, { "name": "store_logo_url", "type": "str", "required": false, "nullable": true }, { "name": "average_rating", "type": "str", "required": false, "nullable": true }, { "name": "total_sales", "type": "str", "required": false, "default": "0" }, { "name": "total_reviews", "type": "str", "required": false, "default": "0" }, { "name": "response_time_hours", "type": "str", "required": false, "nullable": true }, { "name": "is_verified_seller", "type": "bool", "required": false, "default": false }, { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/seller-profiles", "summary": "List Seller Profiles", "description": "Returns a paginated list of seller profiles. Supports optional filters for user_id and is_verified_seller status.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "user_id", "type": "str", "required": false }, { "name": "is_verified_seller", "type": "bool", "required": false } ], "response": { "schema_name": "SellerprofileResponse", "fields": [ { "name": "store_name", "type": "str", "required": true }, { "name": "store_description", "type": "str", "required": false, "nullable": true }, { "name": "store_logo_url", "type": "str", "required": false, "nullable": true }, { "name": "average_rating", "type": "str", "required": false, "nullable": true }, { "name": "total_sales", "type": "str", "required": false, "default": "0" }, { "name": "total_reviews", "type": "str", "required": false, "default": "0" }, { "name": "response_time_hours", "type": "str", "required": false, "nullable": true }, { "name": "is_verified_seller", "type": "bool", "required": false, "default": false }, { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/seller-profiles/{id}", "summary": "Get Seller Profile", "description": "Returns a single seller profile by ID. Returns 404 if profile not found.", "path_params": [ { "name": "id", "type": "str" } ], "response": { "schema_name": "SellerprofileResponse", "fields": [ { "name": "store_name", "type": "str", "required": true }, { "name": "store_description", "type": "str", "required": false, "nullable": true }, { "name": "store_logo_url", "type": "str", "required": false, "nullable": true }, { "name": "average_rating", "type": "str", "required": false, "nullable": true }, { "name": "total_sales", "type": "str", "required": false, "default": "0" }, { "name": "total_reviews", "type": "str", "required": false, "default": "0" }, { "name": "response_time_hours", "type": "str", "required": false, "nullable": true }, { "name": "is_verified_seller", "type": "bool", "required": false, "default": false }, { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/seller-profiles/{id}", "summary": "Update Seller Profile", "description": "Updates seller profile information including store details and statistics. Returns 404 if profile not found.", "path_params": [ { "name": "id", "type": "str" } ], "request_body": { "schema_name": "SellerprofileUpdate", "fields": [ { "name": "store_name", "type": "str", "required": false, "nullable": true }, { "name": "store_description", "type": "str", "required": false, "nullable": true }, { "name": "store_logo_url", "type": "str", "required": false, "nullable": true }, { "name": "average_rating", "type": "str", "required": false, "nullable": true }, { "name": "total_sales", "type": "str", "required": false, "nullable": true }, { "name": "total_reviews", "type": "str", "required": false, "nullable": true }, { "name": "response_time_hours", "type": "str", "required": false, "nullable": true }, { "name": "is_verified_seller", "type": "bool", "required": false, "nullable": true } ] }, "response": { "schema_name": "SellerprofileResponse", "fields": [ { "name": "store_name", "type": "str", "required": true }, { "name": "store_description", "type": "str", "required": false, "nullable": true }, { "name": "store_logo_url", "type": "str", "required": false, "nullable": true }, { "name": "average_rating", "type": "str", "required": false, "nullable": true }, { "name": "total_sales", "type": "str", "required": false, "default": "0" }, { "name": "total_reviews", "type": "str", "required": false, "default": "0" }, { "name": "response_time_hours", "type": "str", "required": false, "nullable": true }, { "name": "is_verified_seller", "type": "bool", "required": false, "default": false }, { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/seller-profiles/{id}", "summary": "Delete Seller Profile", "description": "Permanently deletes a seller profile. Returns 404 if profile not found.", "path_params": [ { "name": "id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/addresses", "summary": "Create Address", "description": "Creates a new shipping or billing address for a user. If is_default is true, unsets default flag on other addresses of same type. All required fields must be provided. Returns 404 if user not found.", "request_body": { "schema_name": "AddressCreate", "fields": [ { "name": "address_type", "type": "AddressType", "required": true, "enum_values": [ "SHIPPING", "BILLING" ] }, { "name": "is_default", "type": "bool", "required": false, "default": false }, { "name": "recipient_name", "type": "str", "required": true }, { "name": "address_line1", "type": "str", "required": true }, { "name": "address_line2", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": true }, { "name": "state", "type": "str", "required": true }, { "name": "postal_code", "type": "str", "required": true }, { "name": "country", "type": "str", "required": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "user_id", "type": "str", "required": true } ] }, "response": { "schema_name": "AddressResponse", "fields": [ { "name": "address_type", "type": "AddressType", "required": true, "enum_values": [ "SHIPPING", "BILLING" ] }, { "name": "is_default", "type": "bool", "required": false, "default": false }, { "name": "recipient_name", "type": "str", "required": true }, { "name": "address_line1", "type": "str", "required": true }, { "name": "address_line2", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": true }, { "name": "state", "type": "str", "required": true }, { "name": "postal_code", "type": "str", "required": true }, { "name": "country", "type": "str", "required": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/addresses", "summary": "List Addresses", "description": "Returns a paginated list of addresses. Supports optional filters for user_id, address_type, and is_default status.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "user_id", "type": "str", "required": false }, { "name": "address_type", "type": "AddressType", "required": false }, { "name": "is_default", "type": "bool", "required": false } ], "response": { "schema_name": "AddressResponse", "fields": [ { "name": "address_type", "type": "AddressType", "required": true, "enum_values": [ "SHIPPING", "BILLING" ] }, { "name": "is_default", "type": "bool", "required": false, "default": false }, { "name": "recipient_name", "type": "str", "required": true }, { "name": "address_line1", "type": "str", "required": true }, { "name": "address_line2", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": true }, { "name": "state", "type": "str", "required": true }, { "name": "postal_code", "type": "str", "required": true }, { "name": "country", "type": "str", "required": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/addresses/{id}", "summary": "Get Address", "description": "Returns a single address by ID. Returns 404 if address not found.", "path_params": [ { "name": "id", "type": "str" } ], "response": { "schema_name": "AddressResponse", "fields": [ { "name": "address_type", "type": "AddressType", "required": true, "enum_values": [ "SHIPPING", "BILLING" ] }, { "name": "is_default", "type": "bool", "required": false, "default": false }, { "name": "recipient_name", "type": "str", "required": true }, { "name": "address_line1", "type": "str", "required": true }, { "name": "address_line2", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": true }, { "name": "state", "type": "str", "required": true }, { "name": "postal_code", "type": "str", "required": true }, { "name": "country", "type": "str", "required": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/addresses/{id}", "summary": "Update Address", "description": "Updates address information. If is_default is set to true, unsets default flag on other addresses of same type. Returns 404 if address not found.", "path_params": [ { "name": "id", "type": "str" } ], "request_body": { "schema_name": "AddressUpdate", "fields": [ { "name": "address_type", "type": "AddressType", "required": false, "nullable": true, "enum_values": [ "SHIPPING", "BILLING" ] }, { "name": "is_default", "type": "bool", "required": false, "nullable": true }, { "name": "recipient_name", "type": "str", "required": false, "nullable": true }, { "name": "address_line1", "type": "str", "required": false, "nullable": true }, { "name": "address_line2", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "postal_code", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "AddressResponse", "fields": [ { "name": "address_type", "type": "AddressType", "required": true, "enum_values": [ "SHIPPING", "BILLING" ] }, { "name": "is_default", "type": "bool", "required": false, "default": false }, { "name": "recipient_name", "type": "str", "required": true }, { "name": "address_line1", "type": "str", "required": true }, { "name": "address_line2", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": true }, { "name": "state", "type": "str", "required": true }, { "name": "postal_code", "type": "str", "required": true }, { "name": "country", "type": "str", "required": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/addresses/{id}", "summary": "Delete Address", "description": "Permanently deletes an address. Returns 404 if address not found.", "path_params": [ { "name": "id", "type": "str" } ], "status_code": 200 } ] }, { "name": "Card Catalog", "prefix": "/card-catalog", "endpoints": [ { "method": "POST", "path": "/card-sets", "summary": "Create Card Set", "description": "Creates a new Pokemon TCG card set. Returns 409 if a set with the same set_code already exists.", "request_body": { "schema_name": "CardsetCreate", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "series", "type": "str", "required": false, "nullable": true }, { "name": "release_date", "type": "date", "required": false, "nullable": true }, { "name": "total_cards", "type": "int", "required": false, "nullable": true }, { "name": "set_code", "type": "str", "required": false, "nullable": true }, { "name": "symbol_url", "type": "str", "required": false, "nullable": true }, { "name": "logo_url", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "CardsetResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "series", "type": "str", "required": false, "nullable": true }, { "name": "release_date", "type": "date", "required": false, "nullable": true }, { "name": "total_cards", "type": "int", "required": false, "nullable": true }, { "name": "set_code", "type": "str", "required": false, "nullable": true }, { "name": "symbol_url", "type": "str", "required": false, "nullable": true }, { "name": "logo_url", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "str", "required": true }, { "name": "updated_at", "type": "str", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/card-sets/{cardset_id}", "summary": "Get Card Set", "description": "Retrieves a single card set by ID. Returns 404 if the card set does not exist.", "path_params": [ { "name": "cardset_id", "type": "str" } ], "response": { "schema_name": "CardsetResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "series", "type": "str", "required": false, "nullable": true }, { "name": "release_date", "type": "date", "required": false, "nullable": true }, { "name": "total_cards", "type": "int", "required": false, "nullable": true }, { "name": "set_code", "type": "str", "required": false, "nullable": true }, { "name": "symbol_url", "type": "str", "required": false, "nullable": true }, { "name": "logo_url", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "str", "required": true }, { "name": "updated_at", "type": "str", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/card-sets", "summary": "List Card Sets", "description": "Returns a paginated list of card sets. Supports optional filtering by series.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "series", "type": "str", "required": false } ], "response": { "schema_name": "CardsetResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "series", "type": "str", "required": false, "nullable": true }, { "name": "release_date", "type": "date", "required": false, "nullable": true }, { "name": "total_cards", "type": "int", "required": false, "nullable": true }, { "name": "set_code", "type": "str", "required": false, "nullable": true }, { "name": "symbol_url", "type": "str", "required": false, "nullable": true }, { "name": "logo_url", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "str", "required": true }, { "name": "updated_at", "type": "str", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/card-sets/{cardset_id}", "summary": "Update Card Set", "description": "Updates an existing card set. Returns 404 if the card set does not exist. Returns 409 if the updated set_code conflicts with another set.", "path_params": [ { "name": "cardset_id", "type": "str" } ], "request_body": { "schema_name": "CardsetUpdate", "fields": [ { "name": "name", "type": "str", "required": false, "nullable": true }, { "name": "series", "type": "str", "required": false, "nullable": true }, { "name": "release_date", "type": "date", "required": false, "nullable": true }, { "name": "total_cards", "type": "int", "required": false, "nullable": true }, { "name": "set_code", "type": "str", "required": false, "nullable": true }, { "name": "symbol_url", "type": "str", "required": false, "nullable": true }, { "name": "logo_url", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "CardsetResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "series", "type": "str", "required": false, "nullable": true }, { "name": "release_date", "type": "date", "required": false, "nullable": true }, { "name": "total_cards", "type": "int", "required": false, "nullable": true }, { "name": "set_code", "type": "str", "required": false, "nullable": true }, { "name": "symbol_url", "type": "str", "required": false, "nullable": true }, { "name": "logo_url", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "str", "required": true }, { "name": "updated_at", "type": "str", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/card-sets/{cardset_id}", "summary": "Delete Card Set", "description": "Deletes a card set by ID. Returns 404 if the card set does not exist.", "path_params": [ { "name": "cardset_id", "type": "str" } ], "status_code": 204 }, { "method": "GET", "path": "/card-sets/{cardset_id}/details", "summary": "Get Card Set With Cards", "description": "Retrieves a card set with all its cards pre-loaded. Returns 404 if the card set does not exist.", "path_params": [ { "name": "cardset_id", "type": "str" } ], "response": { "schema_name": "CardsetWithCardsResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "series", "type": "str", "required": false, "nullable": true }, { "name": "release_date", "type": "date", "required": false, "nullable": true }, { "name": "total_cards", "type": "int", "required": false, "nullable": true }, { "name": "set_code", "type": "str", "required": false, "nullable": true }, { "name": "symbol_url", "type": "str", "required": false, "nullable": true }, { "name": "logo_url", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "str", "required": true }, { "name": "updated_at", "type": "str", "required": true }, { "name": "cards", "type": "List[CardResponse]", "required": false, "is_list": true, "item_fields": [ { "name": "id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "pokemon_name", "type": "str", "required": false, "nullable": true }, { "name": "card_number", "type": "str", "required": true }, { "name": "rarity", "type": "str", "required": false, "nullable": true }, { "name": "card_set", "type": "CardSetResponse", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "series", "type": "str", "required": false, "nullable": true } ] } ] } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/cards", "summary": "Create Card", "description": "Creates a new card in the catalog. Validates that the card_set_id exists and that the card_number is unique within the set. Returns 404 if the card set does not exist. Returns 409 if a card with the same card_number already exists in the set.", "request_body": { "schema_name": "CardCreate", "fields": [ { "name": "card_set_id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": false }, { "name": "pokemon_name", "type": "str", "required": false, "nullable": true }, { "name": "card_number", "type": "str", "required": false }, { "name": "rarity", "type": "str", "required": false, "nullable": true }, { "name": "card_type", "type": "str", "required": false, "nullable": true }, { "name": "pokemon_type", "type": "str", "required": false, "nullable": true }, { "name": "hp", "type": "int", "required": false, "nullable": true }, { "name": "artist", "type": "str", "required": false, "nullable": true }, { "name": "image_url", "type": "str", "required": false, "nullable": true }, { "name": "image_url_hires", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "CardResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "pokemon_name", "type": "str", "required": false, "nullable": true }, { "name": "card_number", "type": "str", "required": true }, { "name": "rarity", "type": "str", "required": false, "nullable": true }, { "name": "card_set", "type": "CardSetResponse", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "series", "type": "str", "required": false, "nullable": true } ] } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/cards/{card_id}", "summary": "Get Card", "description": "Retrieves a single card by ID. Returns 404 if the card does not exist.", "path_params": [ { "name": "card_id", "type": "str" } ], "response": { "schema_name": "CardResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "pokemon_name", "type": "str", "required": false, "nullable": true }, { "name": "card_number", "type": "str", "required": true }, { "name": "rarity", "type": "str", "required": false, "nullable": true }, { "name": "card_set", "type": "CardSetResponse", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "series", "type": "str", "required": false, "nullable": true } ] } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/cards", "summary": "List Cards", "description": "Returns a paginated list of cards. Supports optional filtering by card_set_id.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "card_set_id", "type": "str", "required": false } ], "response": { "schema_name": "CardResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "pokemon_name", "type": "str", "required": false, "nullable": true }, { "name": "card_number", "type": "str", "required": true }, { "name": "rarity", "type": "str", "required": false, "nullable": true }, { "name": "card_set", "type": "CardSetResponse", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "series", "type": "str", "required": false, "nullable": true } ] } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/cards/{card_id}", "summary": "Update Card", "description": "Updates an existing card. Validates that the card_set_id exists if changed and that the card_number remains unique within the set. Returns 404 if the card or card set does not exist. Returns 409 if the updated card_number conflicts with another card in the set.", "path_params": [ { "name": "card_id", "type": "str" } ], "request_body": { "schema_name": "CardUpdate", "fields": [ { "name": "card_set_id", "type": "str", "required": false, "nullable": true }, { "name": "name", "type": "str", "required": false, "nullable": true }, { "name": "pokemon_name", "type": "str", "required": false, "nullable": true }, { "name": "card_number", "type": "str", "required": false, "nullable": true }, { "name": "rarity", "type": "str", "required": false, "nullable": true }, { "name": "card_type", "type": "str", "required": false, "nullable": true }, { "name": "pokemon_type", "type": "str", "required": false, "nullable": true }, { "name": "hp", "type": "int", "required": false, "nullable": true }, { "name": "artist", "type": "str", "required": false, "nullable": true }, { "name": "image_url", "type": "str", "required": false, "nullable": true }, { "name": "image_url_hires", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "CardResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "pokemon_name", "type": "str", "required": false, "nullable": true }, { "name": "card_number", "type": "str", "required": true }, { "name": "rarity", "type": "str", "required": false, "nullable": true }, { "name": "card_set", "type": "CardSetResponse", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "series", "type": "str", "required": false, "nullable": true } ] } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/cards/{card_id}", "summary": "Delete Card", "description": "Deletes a card by ID. Returns 404 if the card does not exist.", "path_params": [ { "name": "card_id", "type": "str" } ], "status_code": 204 }, { "method": "GET", "path": "/cards/{card_id}/details", "summary": "Get Card With Details", "description": "Retrieves a card with its card set and categories pre-loaded. Returns 404 if the card does not exist.", "path_params": [ { "name": "card_id", "type": "str" } ], "response": { "schema_name": "CardDetailResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "pokemon_name", "type": "str", "required": false, "nullable": true }, { "name": "card_number", "type": "str", "required": true }, { "name": "rarity", "type": "str", "required": false, "nullable": true }, { "name": "card_set", "type": "CardsetResponse", "required": true, "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "series", "type": "str", "required": false, "nullable": true }, { "name": "release_date", "type": "date", "required": false, "nullable": true }, { "name": "total_cards", "type": "int", "required": false, "nullable": true }, { "name": "set_code", "type": "str", "required": false, "nullable": true }, { "name": "symbol_url", "type": "str", "required": false, "nullable": true }, { "name": "logo_url", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "str", "required": true }, { "name": "updated_at", "type": "str", "required": true } ] } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/cards/search", "summary": "Search Cards", "description": "Searches cards by name, pokemon_name, card_set_id, rarity, and card_type. Returns a paginated list of matching cards.", "query_params": [ { "name": "search_term", "type": "str", "required": false }, { "name": "card_set_id", "type": "str", "required": false }, { "name": "rarity", "type": "str", "required": false }, { "name": "card_type", "type": "str", "required": false }, { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 } ], "response": { "schema_name": "CardResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "pokemon_name", "type": "str", "required": false, "nullable": true }, { "name": "card_number", "type": "str", "required": true }, { "name": "rarity", "type": "str", "required": false, "nullable": true }, { "name": "card_set", "type": "CardSetResponse", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "series", "type": "str", "required": false, "nullable": true } ] } ], "is_list": true }, "status_code": 200 }, { "method": "POST", "path": "/categories", "summary": "Create Category", "description": "Creates a new category for organizing cards. Validates that the slug is unique and that the parent_category_id exists if provided. Returns 404 if the parent category does not exist. Returns 409 if a category with the same slug already exists.", "request_body": { "schema_name": "CategoryCreate", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "slug", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "parent_category_id", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "CategoryResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "slug", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "parent_category_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "str", "required": true }, { "name": "updated_at", "type": "str", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/categories/{category_id}", "summary": "Get Category", "description": "Retrieves a single category by ID. Returns 404 if the category does not exist.", "path_params": [ { "name": "category_id", "type": "str" } ], "response": { "schema_name": "CategoryResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "slug", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "parent_category_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "str", "required": true }, { "name": "updated_at", "type": "str", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/categories", "summary": "List Categories", "description": "Returns a paginated list of categories. Supports optional filtering by parent_category_id to retrieve subcategories.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "parent_category_id", "type": "str", "required": false } ], "response": { "schema_name": "CategoryResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "slug", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "parent_category_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "str", "required": true }, { "name": "updated_at", "type": "str", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/categories/{category_id}", "summary": "Update Category", "description": "Updates an existing category. Validates that the slug remains unique, that the parent_category_id exists if changed, and that a category cannot be its own parent. Returns 400 if the category is set as its own parent. Returns 404 if the category or parent category does not exist. Returns 409 if the updated slug conflicts with another category.", "path_params": [ { "name": "category_id", "type": "str" } ], "request_body": { "schema_name": "CategoryUpdate", "fields": [ { "name": "name", "type": "str", "required": false, "nullable": true }, { "name": "slug", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "parent_category_id", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "CategoryResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "slug", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "parent_category_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "str", "required": true }, { "name": "updated_at", "type": "str", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/categories/{category_id}", "summary": "Delete Category", "description": "Deletes a category by ID. Returns 404 if the category does not exist.", "path_params": [ { "name": "category_id", "type": "str" } ], "status_code": 204 }, { "method": "GET", "path": "/categories/{category_id}/details", "summary": "Get Category With Subcategories", "description": "Retrieves a category with all its subcategories pre-loaded. Returns 404 if the category does not exist.", "path_params": [ { "name": "category_id", "type": "str" } ], "response": { "schema_name": "CategoryWithSubcategoriesResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "slug", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "parent_category_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "str", "required": true }, { "name": "updated_at", "type": "str", "required": true }, { "name": "subcategories", "type": "List[CategoryResponse]", "required": false, "is_list": true, "item_fields": [ { "name": "name", "type": "str", "required": false }, { "name": "slug", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "parent_category_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "str", "required": true }, { "name": "updated_at", "type": "str", "required": true } ] } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/card-categories", "summary": "Create Card Category Assignment", "description": "Assigns a card to a category. Validates that both the card and category exist and that the assignment is unique. Returns 404 if the card or category does not exist. Returns 409 if the card is already assigned to the category.", "request_body": { "schema_name": "CardcategoryCreate", "fields": [ { "name": "card_id", "type": "str", "required": true }, { "name": "category_id", "type": "str", "required": true } ] }, "response": { "schema_name": "CardcategoryResponse", "fields": [ { "name": "card_id", "type": "str", "required": true }, { "name": "category_id", "type": "str", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "str", "required": true }, { "name": "updated_at", "type": "str", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/card-categories/{cardcategory_id}", "summary": "Get Card Category Assignment", "description": "Retrieves a single card-category assignment by ID. Returns 404 if the assignment does not exist.", "path_params": [ { "name": "cardcategory_id", "type": "str" } ], "response": { "schema_name": "CardcategoryResponse", "fields": [ { "name": "card_id", "type": "str", "required": true }, { "name": "category_id", "type": "str", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "str", "required": true }, { "name": "updated_at", "type": "str", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/card-categories", "summary": "List Card Category Assignments", "description": "Returns a paginated list of card-category assignments. Supports optional filtering by card_id or category_id.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "card_id", "type": "str", "required": false }, { "name": "category_id", "type": "str", "required": false } ], "response": { "schema_name": "CardcategoryResponse", "fields": [ { "name": "card_id", "type": "str", "required": true }, { "name": "category_id", "type": "str", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "str", "required": true }, { "name": "updated_at", "type": "str", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/card-categories/{cardcategory_id}", "summary": "Update Card Category Assignment", "description": "Updates an existing card-category assignment. Validates that the card and category exist if changed and that the assignment remains unique. Returns 404 if the assignment, card, or category does not exist. Returns 409 if the updated assignment conflicts with an existing one.", "path_params": [ { "name": "cardcategory_id", "type": "str" } ], "request_body": { "schema_name": "CardcategoryUpdate", "fields": [ { "name": "card_id", "type": "str", "required": false, "nullable": true }, { "name": "category_id", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "CardcategoryResponse", "fields": [ { "name": "card_id", "type": "str", "required": true }, { "name": "category_id", "type": "str", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "str", "required": true }, { "name": "updated_at", "type": "str", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/card-categories/{cardcategory_id}", "summary": "Delete Card Category Assignment", "description": "Deletes a card-category assignment by ID. Returns 404 if the assignment does not exist.", "path_params": [ { "name": "cardcategory_id", "type": "str" } ], "status_code": 204 } ] }, { "name": "Grading", "prefix": "/grading", "endpoints": [ { "method": "POST", "path": "/services", "summary": "Create Grading Service", "description": "Creates a new grading service record. Returns 409 if a service with the same name or abbreviation already exists.", "request_body": { "schema_name": "GradingserviceCreate", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "abbreviation", "type": "str", "required": false }, { "name": "website_url", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "GradingserviceResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "abbreviation", "type": "str", "required": false }, { "name": "website_url", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/services/{gradingservice_id}", "summary": "Get Grading Service", "description": "Retrieves a single grading service by ID. Returns 404 if not found.", "path_params": [ { "name": "gradingservice_id", "type": "str" } ], "response": { "schema_name": "GradingserviceResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "abbreviation", "type": "str", "required": false }, { "name": "website_url", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/services", "summary": "List Grading Services", "description": "Returns a paginated list of grading services. Supports optional filtering by name and abbreviation.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "name", "type": "str", "required": false }, { "name": "abbreviation", "type": "str", "required": false } ], "response": { "schema_name": "GradingserviceResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "abbreviation", "type": "str", "required": false }, { "name": "website_url", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/services/{gradingservice_id}", "summary": "Update Grading Service", "description": "Updates an existing grading service. Returns 404 if not found, 409 if name or abbreviation conflicts with another service.", "path_params": [ { "name": "gradingservice_id", "type": "str" } ], "request_body": { "schema_name": "GradingserviceUpdate", "fields": [ { "name": "name", "type": "str", "required": false, "nullable": true }, { "name": "abbreviation", "type": "str", "required": false, "nullable": true }, { "name": "website_url", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "GradingserviceResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "abbreviation", "type": "str", "required": false }, { "name": "website_url", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/services/{gradingservice_id}", "summary": "Delete Grading Service", "description": "Deletes a grading service by ID. Returns 404 if not found. Fails if graded cards reference this service.", "path_params": [ { "name": "gradingservice_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/graded-cards", "summary": "Create Graded Card", "description": "Creates a new graded card record for a listing. Returns 404 if listing or grading service not found, 409 if listing already has a graded card or certification number is duplicate.", "request_body": { "schema_name": "GradedcardCreate", "fields": [ { "name": "listing_id", "type": "str", "required": false }, { "name": "grading_service_id", "type": "str", "required": false }, { "name": "grade", "type": "str", "required": false }, { "name": "certification_number", "type": "str", "required": false, "nullable": true }, { "name": "grading_date", "type": "date", "required": false, "nullable": true }, { "name": "population_count", "type": "int", "required": false, "nullable": true } ] }, "response": { "schema_name": "GradedcardResponse", "fields": [ { "name": "listing_id", "type": "str", "required": false }, { "name": "grading_service_id", "type": "str", "required": false }, { "name": "grade", "type": "str", "required": false }, { "name": "certification_number", "type": "str", "required": false, "nullable": true }, { "name": "grading_date", "type": "date", "required": false, "nullable": true }, { "name": "population_count", "type": "int", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/graded-cards/{gradedcard_id}", "summary": "Get Graded Card", "description": "Retrieves a single graded card by ID. Returns 404 if not found.", "path_params": [ { "name": "gradedcard_id", "type": "str" } ], "response": { "schema_name": "GradedcardResponse", "fields": [ { "name": "listing_id", "type": "str", "required": false }, { "name": "grading_service_id", "type": "str", "required": false }, { "name": "grade", "type": "str", "required": false }, { "name": "certification_number", "type": "str", "required": false, "nullable": true }, { "name": "grading_date", "type": "date", "required": false, "nullable": true }, { "name": "population_count", "type": "int", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/graded-cards/{gradedcard_id}/details", "summary": "Get Graded Card Details", "description": "Retrieves a graded card with full grading service details. Returns 404 if not found.", "path_params": [ { "name": "gradedcard_id", "type": "str" } ], "response": { "schema_name": "GradedcardDetailResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "listing_id", "type": "str", "required": true }, { "name": "grading_service_id", "type": "str", "required": true }, { "name": "grade", "type": "str", "required": true }, { "name": "certification_number", "type": "str", "required": false, "nullable": true }, { "name": "grading_date", "type": "date", "required": false, "nullable": true }, { "name": "population_count", "type": "int", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "grading_service", "type": "GradingserviceResponse", "required": true, "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "abbreviation", "type": "str", "required": false }, { "name": "website_url", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/graded-cards", "summary": "List Graded Cards", "description": "Returns a paginated list of graded cards. Supports optional filtering by listing, grading service, grade, and certification number.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "listing_id", "type": "str", "required": false }, { "name": "grading_service_id", "type": "str", "required": false }, { "name": "grade", "type": "str", "required": false }, { "name": "certification_number", "type": "str", "required": false } ], "response": { "schema_name": "GradedcardResponse", "fields": [ { "name": "listing_id", "type": "str", "required": false }, { "name": "grading_service_id", "type": "str", "required": false }, { "name": "grade", "type": "str", "required": false }, { "name": "certification_number", "type": "str", "required": false, "nullable": true }, { "name": "grading_date", "type": "date", "required": false, "nullable": true }, { "name": "population_count", "type": "int", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/graded-cards/{gradedcard_id}", "summary": "Update Graded Card", "description": "Updates an existing graded card. Returns 404 if not found or referenced entities not found, 409 if listing already has another graded card or certification number conflicts.", "path_params": [ { "name": "gradedcard_id", "type": "str" } ], "request_body": { "schema_name": "GradedcardUpdate", "fields": [ { "name": "listing_id", "type": "str", "required": false, "nullable": true }, { "name": "grading_service_id", "type": "str", "required": false, "nullable": true }, { "name": "grade", "type": "str", "required": false, "nullable": true }, { "name": "certification_number", "type": "str", "required": false, "nullable": true }, { "name": "grading_date", "type": "date", "required": false, "nullable": true }, { "name": "population_count", "type": "int", "required": false, "nullable": true } ] }, "response": { "schema_name": "GradedcardResponse", "fields": [ { "name": "listing_id", "type": "str", "required": false }, { "name": "grading_service_id", "type": "str", "required": false }, { "name": "grade", "type": "str", "required": false }, { "name": "certification_number", "type": "str", "required": false, "nullable": true }, { "name": "grading_date", "type": "date", "required": false, "nullable": true }, { "name": "population_count", "type": "int", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/graded-cards/{gradedcard_id}", "summary": "Delete Graded Card", "description": "Deletes a graded card by ID. Returns 404 if not found.", "path_params": [ { "name": "gradedcard_id", "type": "str" } ], "status_code": 200 } ] }, { "name": "Listings", "prefix": "/listings", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Listing", "description": "Creates a new listing for a card. Validates that the seller exists, has a completed seller profile, and the card exists. Returns 404 if seller or card not found, 400 if seller profile is incomplete.", "request_body": { "schema_name": "ListingCreate", "fields": [ { "name": "seller_id", "type": "str", "required": true }, { "name": "card_id", "type": "str", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "price", "type": "Decimal", "required": true }, { "name": "quantity", "type": "int", "required": true }, { "name": "condition", "type": "CardCondition", "required": true, "enum_values": [ "MINT", "NEAR_MINT", "LIGHTLY_PLAYED", "MODERATELY_PLAYED", "HEAVILY_PLAYED", "DAMAGED" ] }, { "name": "language", "type": "str", "required": true }, { "name": "is_first_edition", "type": "bool", "required": false, "default": false }, { "name": "is_shadowless", "type": "bool", "required": false, "default": false }, { "name": "is_reverse_holo", "type": "bool", "required": false, "default": false }, { "name": "accepts_offers", "type": "bool", "required": false, "default": false }, { "name": "status", "type": "ListingStatus", "required": true, "enum_values": [ "DRAFT", "ACTIVE", "SOLD", "RESERVED", "INACTIVE", "REMOVED" ] } ] }, "response": { "schema_name": "ListingResponse", "fields": [ { "name": "seller_id", "type": "str", "required": true }, { "name": "card_id", "type": "str", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "price", "type": "Decimal", "required": true }, { "name": "quantity", "type": "int", "required": true }, { "name": "condition", "type": "CardCondition", "required": true, "enum_values": [ "MINT", "NEAR_MINT", "LIGHTLY_PLAYED", "MODERATELY_PLAYED", "HEAVILY_PLAYED", "DAMAGED" ] }, { "name": "language", "type": "str", "required": true }, { "name": "is_first_edition", "type": "bool", "required": false, "default": false }, { "name": "is_shadowless", "type": "bool", "required": false, "default": false }, { "name": "is_reverse_holo", "type": "bool", "required": false, "default": false }, { "name": "accepts_offers", "type": "bool", "required": false, "default": false }, { "name": "status", "type": "ListingStatus", "required": true, "enum_values": [ "DRAFT", "ACTIVE", "SOLD", "RESERVED", "INACTIVE", "REMOVED" ] }, { "name": "id", "type": "str", "required": true }, { "name": "views_count", "type": "int", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/", "summary": "List Listings", "description": "Returns a paginated list of listings. Supports filtering by seller, card, status, condition, price range, and text search on title. Results are ordered by creation date descending.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "seller_id", "type": "str", "required": false }, { "name": "card_id", "type": "str", "required": false }, { "name": "status", "type": "ListingStatus", "required": false }, { "name": "condition", "type": "CardCondition", "required": false }, { "name": "min_price", "type": "float", "required": false }, { "name": "max_price", "type": "float", "required": false }, { "name": "search", "type": "str", "required": false } ], "response": { "schema_name": "ListingResponse", "fields": [ { "name": "seller_id", "type": "str", "required": true }, { "name": "card_id", "type": "str", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "price", "type": "Decimal", "required": true }, { "name": "quantity", "type": "int", "required": true }, { "name": "condition", "type": "CardCondition", "required": true, "enum_values": [ "MINT", "NEAR_MINT", "LIGHTLY_PLAYED", "MODERATELY_PLAYED", "HEAVILY_PLAYED", "DAMAGED" ] }, { "name": "language", "type": "str", "required": true }, { "name": "is_first_edition", "type": "bool", "required": false, "default": false }, { "name": "is_shadowless", "type": "bool", "required": false, "default": false }, { "name": "is_reverse_holo", "type": "bool", "required": false, "default": false }, { "name": "accepts_offers", "type": "bool", "required": false, "default": false }, { "name": "status", "type": "ListingStatus", "required": true, "enum_values": [ "DRAFT", "ACTIVE", "SOLD", "RESERVED", "INACTIVE", "REMOVED" ] }, { "name": "id", "type": "str", "required": true }, { "name": "views_count", "type": "int", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/{id}", "summary": "Get Listing", "description": "Returns a single listing by ID. Returns 404 if listing not found.", "path_params": [ { "name": "id", "type": "str" } ], "response": { "schema_name": "ListingResponse", "fields": [ { "name": "seller_id", "type": "str", "required": true }, { "name": "card_id", "type": "str", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "price", "type": "Decimal", "required": true }, { "name": "quantity", "type": "int", "required": true }, { "name": "condition", "type": "CardCondition", "required": true, "enum_values": [ "MINT", "NEAR_MINT", "LIGHTLY_PLAYED", "MODERATELY_PLAYED", "HEAVILY_PLAYED", "DAMAGED" ] }, { "name": "language", "type": "str", "required": true }, { "name": "is_first_edition", "type": "bool", "required": false, "default": false }, { "name": "is_shadowless", "type": "bool", "required": false, "default": false }, { "name": "is_reverse_holo", "type": "bool", "required": false, "default": false }, { "name": "accepts_offers", "type": "bool", "required": false, "default": false }, { "name": "status", "type": "ListingStatus", "required": true, "enum_values": [ "DRAFT", "ACTIVE", "SOLD", "RESERVED", "INACTIVE", "REMOVED" ] }, { "name": "id", "type": "str", "required": true }, { "name": "views_count", "type": "int", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{id}", "summary": "Update Listing", "description": "Updates an existing listing. Only provided fields are updated. Validates seller and card references if changed. Returns 404 if listing, seller, or card not found.", "path_params": [ { "name": "id", "type": "str" } ], "request_body": { "schema_name": "ListingUpdate", "fields": [ { "name": "seller_id", "type": "str", "required": false, "nullable": true }, { "name": "card_id", "type": "str", "required": false, "nullable": true }, { "name": "title", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "price", "type": "Decimal", "required": false, "nullable": true }, { "name": "quantity", "type": "int", "required": false, "nullable": true }, { "name": "condition", "type": "CardCondition", "required": false, "nullable": true, "enum_values": [ "MINT", "NEAR_MINT", "LIGHTLY_PLAYED", "MODERATELY_PLAYED", "HEAVILY_PLAYED", "DAMAGED" ] }, { "name": "language", "type": "str", "required": false, "nullable": true }, { "name": "is_first_edition", "type": "bool", "required": false, "nullable": true }, { "name": "is_shadowless", "type": "bool", "required": false, "nullable": true }, { "name": "is_reverse_holo", "type": "bool", "required": false, "nullable": true }, { "name": "accepts_offers", "type": "bool", "required": false, "nullable": true }, { "name": "status", "type": "ListingStatus", "required": false, "nullable": true, "enum_values": [ "DRAFT", "ACTIVE", "SOLD", "RESERVED", "INACTIVE", "REMOVED" ] } ] }, "response": { "schema_name": "ListingResponse", "fields": [ { "name": "seller_id", "type": "str", "required": true }, { "name": "card_id", "type": "str", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "price", "type": "Decimal", "required": true }, { "name": "quantity", "type": "int", "required": true }, { "name": "condition", "type": "CardCondition", "required": true, "enum_values": [ "MINT", "NEAR_MINT", "LIGHTLY_PLAYED", "MODERATELY_PLAYED", "HEAVILY_PLAYED", "DAMAGED" ] }, { "name": "language", "type": "str", "required": true }, { "name": "is_first_edition", "type": "bool", "required": false, "default": false }, { "name": "is_shadowless", "type": "bool", "required": false, "default": false }, { "name": "is_reverse_holo", "type": "bool", "required": false, "default": false }, { "name": "accepts_offers", "type": "bool", "required": false, "default": false }, { "name": "status", "type": "ListingStatus", "required": true, "enum_values": [ "DRAFT", "ACTIVE", "SOLD", "RESERVED", "INACTIVE", "REMOVED" ] }, { "name": "id", "type": "str", "required": true }, { "name": "views_count", "type": "int", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{id}", "summary": "Delete Listing", "description": "Permanently deletes a listing and all associated images. Returns 404 if listing not found.", "path_params": [ { "name": "id", "type": "str" } ], "status_code": 200 }, { "method": "GET", "path": "/{id}/details", "summary": "Get Listing Details", "description": "Returns comprehensive listing details including card information, seller profile, all images, and grading details if applicable. Increments view count. Returns 404 if listing not found.", "path_params": [ { "name": "id", "type": "str" } ], "response": { "schema_name": "ListingDetailResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "seller_id", "type": "str", "required": true }, { "name": "card_id", "type": "str", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "price", "type": "Decimal", "required": true }, { "name": "quantity", "type": "int", "required": true }, { "name": "condition", "type": "str", "required": true }, { "name": "language", "type": "str", "required": true }, { "name": "is_first_edition", "type": "bool", "required": true }, { "name": "is_shadowless", "type": "bool", "required": true }, { "name": "is_reverse_holo", "type": "bool", "required": true }, { "name": "accepts_offers", "type": "bool", "required": true }, { "name": "status", "type": "str", "required": true }, { "name": "views_count", "type": "int", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "card", "type": "CardResponse", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "pokemon_name", "type": "str", "required": false, "nullable": true }, { "name": "card_number", "type": "str", "required": true }, { "name": "rarity", "type": "str", "required": false, "nullable": true }, { "name": "card_set", "type": "CardSetResponse", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "series", "type": "str", "required": false, "nullable": true } ] } ] }, { "name": "seller", "type": "SellerResponse", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "seller_profile", "type": "SellerProfileResponse", "required": false, "nullable": true, "fields": [ { "name": "store_name", "type": "str", "required": true }, { "name": "average_rating", "type": "float", "required": false, "nullable": true }, { "name": "total_sales", "type": "int", "required": true }, { "name": "is_verified_seller", "type": "bool", "required": true } ] } ] }, { "name": "listing_images", "type": "List[ListingimageResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "listing_id", "type": "str", "required": true }, { "name": "image_url", "type": "str", "required": true }, { "name": "display_order", "type": "int", "required": true }, { "name": "is_primary", "type": "bool", "required": false, "default": false }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] }, { "name": "graded_card", "type": "GradedCardResponse", "required": false, "nullable": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "grade", "type": "str", "required": true }, { "name": "certification_number", "type": "str", "required": false, "nullable": true }, { "name": "grading_service", "type": "GradingServiceResponse", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "abbreviation", "type": "str", "required": true } ] } ] } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/{id}/publish", "summary": "Publish Listing", "description": "Publishes a draft listing, making it active and visible to buyers. Validates that listing has minimum 2 photos. Returns 400 if listing is not in draft status or lacks required photos, 404 if listing not found.", "path_params": [ { "name": "id", "type": "str" } ], "response": { "schema_name": "ListingResponse", "fields": [ { "name": "seller_id", "type": "str", "required": true }, { "name": "card_id", "type": "str", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "price", "type": "Decimal", "required": true }, { "name": "quantity", "type": "int", "required": true }, { "name": "condition", "type": "CardCondition", "required": true, "enum_values": [ "MINT", "NEAR_MINT", "LIGHTLY_PLAYED", "MODERATELY_PLAYED", "HEAVILY_PLAYED", "DAMAGED" ] }, { "name": "language", "type": "str", "required": true }, { "name": "is_first_edition", "type": "bool", "required": false, "default": false }, { "name": "is_shadowless", "type": "bool", "required": false, "default": false }, { "name": "is_reverse_holo", "type": "bool", "required": false, "default": false }, { "name": "accepts_offers", "type": "bool", "required": false, "default": false }, { "name": "status", "type": "ListingStatus", "required": true, "enum_values": [ "DRAFT", "ACTIVE", "SOLD", "RESERVED", "INACTIVE", "REMOVED" ] }, { "name": "id", "type": "str", "required": true }, { "name": "views_count", "type": "int", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/{id}/deactivate", "summary": "Deactivate Listing", "description": "Deactivates an active or reserved listing, making it invisible to buyers. Returns 400 if listing is not active or reserved, 404 if listing not found.", "path_params": [ { "name": "id", "type": "str" } ], "response": { "schema_name": "ListingResponse", "fields": [ { "name": "seller_id", "type": "str", "required": true }, { "name": "card_id", "type": "str", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "price", "type": "Decimal", "required": true }, { "name": "quantity", "type": "int", "required": true }, { "name": "condition", "type": "CardCondition", "required": true, "enum_values": [ "MINT", "NEAR_MINT", "LIGHTLY_PLAYED", "MODERATELY_PLAYED", "HEAVILY_PLAYED", "DAMAGED" ] }, { "name": "language", "type": "str", "required": true }, { "name": "is_first_edition", "type": "bool", "required": false, "default": false }, { "name": "is_shadowless", "type": "bool", "required": false, "default": false }, { "name": "is_reverse_holo", "type": "bool", "required": false, "default": false }, { "name": "accepts_offers", "type": "bool", "required": false, "default": false }, { "name": "status", "type": "ListingStatus", "required": true, "enum_values": [ "DRAFT", "ACTIVE", "SOLD", "RESERVED", "INACTIVE", "REMOVED" ] }, { "name": "id", "type": "str", "required": true }, { "name": "views_count", "type": "int", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/images", "summary": "Create Listing Image", "description": "Adds a new image to a listing. Returns 404 if listing not found.", "request_body": { "schema_name": "ListingimageCreate", "fields": [ { "name": "listing_id", "type": "str", "required": true }, { "name": "image_url", "type": "str", "required": true }, { "name": "display_order", "type": "int", "required": true }, { "name": "is_primary", "type": "bool", "required": false, "default": false } ] }, "response": { "schema_name": "ListingimageResponse", "fields": [ { "name": "listing_id", "type": "str", "required": true }, { "name": "image_url", "type": "str", "required": true }, { "name": "display_order", "type": "int", "required": true }, { "name": "is_primary", "type": "bool", "required": false, "default": false }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/images/{id}", "summary": "Get Listing Image", "description": "Returns a single listing image by ID. Returns 404 if image not found.", "path_params": [ { "name": "id", "type": "str" } ], "response": { "schema_name": "ListingimageResponse", "fields": [ { "name": "listing_id", "type": "str", "required": true }, { "name": "image_url", "type": "str", "required": true }, { "name": "display_order", "type": "int", "required": true }, { "name": "is_primary", "type": "bool", "required": false, "default": false }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{listing_id}/images", "summary": "List Listing Images", "description": "Returns all images for a specific listing, ordered by display order. Returns 404 if listing not found.", "path_params": [ { "name": "listing_id", "type": "str" } ], "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 } ], "response": { "schema_name": "ListingimageResponse", "fields": [ { "name": "listing_id", "type": "str", "required": true }, { "name": "image_url", "type": "str", "required": true }, { "name": "display_order", "type": "int", "required": true }, { "name": "is_primary", "type": "bool", "required": false, "default": false }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/images/{id}", "summary": "Update Listing Image", "description": "Updates an existing listing image. Only provided fields are updated. Returns 404 if image or listing not found.", "path_params": [ { "name": "id", "type": "str" } ], "request_body": { "schema_name": "ListingimageUpdate", "fields": [ { "name": "listing_id", "type": "str", "required": false, "nullable": true }, { "name": "image_url", "type": "str", "required": false, "nullable": true }, { "name": "display_order", "type": "int", "required": false, "nullable": true }, { "name": "is_primary", "type": "bool", "required": false, "nullable": true } ] }, "response": { "schema_name": "ListingimageResponse", "fields": [ { "name": "listing_id", "type": "str", "required": true }, { "name": "image_url", "type": "str", "required": true }, { "name": "display_order", "type": "int", "required": true }, { "name": "is_primary", "type": "bool", "required": false, "default": false }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/images/{id}", "summary": "Delete Listing Image", "description": "Permanently deletes a listing image. Returns 404 if image not found.", "path_params": [ { "name": "id", "type": "str" } ], "status_code": 200 } ] }, { "name": "Shopping", "prefix": "/shopping", "endpoints": [ { "method": "POST", "path": "/carts", "summary": "Create Cart", "description": "Creates a new shopping cart for a user. Returns 400 if the user does not exist or 409 if the user already has a cart.", "request_body": { "schema_name": "CartCreate", "fields": [ { "name": "user_id", "type": "str", "required": true } ] }, "response": { "schema_name": "CartResponse", "fields": [ { "name": "user_id", "type": "str", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/carts/{cart_id}", "summary": "Get Cart", "description": "Retrieves a cart by ID. Returns 404 if the cart does not exist.", "path_params": [ { "name": "cart_id", "type": "str" } ], "response": { "schema_name": "CartResponse", "fields": [ { "name": "user_id", "type": "str", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/carts", "summary": "List Carts", "description": "Returns a paginated list of carts. Supports optional filtering by user_id.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "user_id", "type": "str", "required": false } ], "response": { "schema_name": "CartResponse", "fields": [ { "name": "user_id", "type": "str", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/carts/{cart_id}", "summary": "Update Cart", "description": "Updates a cart by ID. Returns 404 if the cart does not exist or 400 if the user does not exist.", "path_params": [ { "name": "cart_id", "type": "str" } ], "request_body": { "schema_name": "CartUpdate", "fields": [ { "name": "user_id", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "CartResponse", "fields": [ { "name": "user_id", "type": "str", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/carts/{cart_id}", "summary": "Delete Cart", "description": "Deletes a cart by ID. Returns 404 if the cart does not exist.", "path_params": [ { "name": "cart_id", "type": "str" } ], "status_code": 200 }, { "method": "GET", "path": "/carts/{cart_id}/details", "summary": "Get Cart Details", "description": "Retrieves detailed cart information including all cart items with their associated listings, cards, and sellers. Returns 404 if the cart does not exist.", "path_params": [ { "name": "cart_id", "type": "str" } ], "response": { "schema_name": "CartDetailResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "cart_items", "type": "list[CartDetailItemResponse]", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/cart-items", "summary": "Create Cart Item", "description": "Adds a listing to a cart. Validates that the cart and listing exist and that sufficient quantity is available. Returns 400 if validation fails.", "request_body": { "schema_name": "CartitemCreate", "fields": [ { "name": "cart_id", "type": "str", "required": true }, { "name": "listing_id", "type": "str", "required": true }, { "name": "quantity", "type": "int", "required": true }, { "name": "price_snapshot", "type": "Decimal", "required": true } ] }, "response": { "schema_name": "CartitemResponse", "fields": [ { "name": "cart_id", "type": "str", "required": true }, { "name": "listing_id", "type": "str", "required": true }, { "name": "quantity", "type": "int", "required": true }, { "name": "price_snapshot", "type": "Decimal", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/cart-items/{cartitem_id}", "summary": "Get Cart Item", "description": "Retrieves a cart item by ID. Returns 404 if the cart item does not exist.", "path_params": [ { "name": "cartitem_id", "type": "str" } ], "response": { "schema_name": "CartitemResponse", "fields": [ { "name": "cart_id", "type": "str", "required": true }, { "name": "listing_id", "type": "str", "required": true }, { "name": "quantity", "type": "int", "required": true }, { "name": "price_snapshot", "type": "Decimal", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/cart-items", "summary": "List Cart Items", "description": "Returns a paginated list of cart items. Supports optional filtering by cart_id and listing_id.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "cart_id", "type": "str", "required": false }, { "name": "listing_id", "type": "str", "required": false } ], "response": { "schema_name": "CartitemResponse", "fields": [ { "name": "cart_id", "type": "str", "required": true }, { "name": "listing_id", "type": "str", "required": true }, { "name": "quantity", "type": "int", "required": true }, { "name": "price_snapshot", "type": "Decimal", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/cart-items/{cartitem_id}", "summary": "Update Cart Item", "description": "Updates a cart item by ID. Validates that the cart and listing exist and that sufficient quantity is available. Returns 404 if the cart item does not exist or 400 if validation fails.", "path_params": [ { "name": "cartitem_id", "type": "str" } ], "request_body": { "schema_name": "CartitemUpdate", "fields": [ { "name": "cart_id", "type": "str", "required": false, "nullable": true }, { "name": "listing_id", "type": "str", "required": false, "nullable": true }, { "name": "quantity", "type": "int", "required": false, "nullable": true }, { "name": "price_snapshot", "type": "Decimal", "required": false, "nullable": true } ] }, "response": { "schema_name": "CartitemResponse", "fields": [ { "name": "cart_id", "type": "str", "required": true }, { "name": "listing_id", "type": "str", "required": true }, { "name": "quantity", "type": "int", "required": true }, { "name": "price_snapshot", "type": "Decimal", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/cart-items/{cartitem_id}", "summary": "Delete Cart Item", "description": "Removes a cart item by ID. Returns 404 if the cart item does not exist.", "path_params": [ { "name": "cartitem_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/wishlists", "summary": "Create Wishlist", "description": "Creates a new wishlist for a user. Returns 400 if the user does not exist.", "request_body": { "schema_name": "WishlistCreate", "fields": [ { "name": "user_id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "is_public", "type": "bool", "required": false, "default": false } ] }, "response": { "schema_name": "WishlistResponse", "fields": [ { "name": "user_id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "is_public", "type": "bool", "required": false, "default": false }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/wishlists/{wishlist_id}", "summary": "Get Wishlist", "description": "Retrieves a wishlist by ID. Returns 404 if the wishlist does not exist.", "path_params": [ { "name": "wishlist_id", "type": "str" } ], "response": { "schema_name": "WishlistResponse", "fields": [ { "name": "user_id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "is_public", "type": "bool", "required": false, "default": false }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/wishlists", "summary": "List Wishlists", "description": "Returns a paginated list of wishlists. Supports optional filtering by user_id and is_public.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "user_id", "type": "str", "required": false }, { "name": "is_public", "type": "bool", "required": false } ], "response": { "schema_name": "WishlistResponse", "fields": [ { "name": "user_id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "is_public", "type": "bool", "required": false, "default": false }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/wishlists/{wishlist_id}", "summary": "Update Wishlist", "description": "Updates a wishlist by ID. Returns 404 if the wishlist does not exist or 400 if the user does not exist.", "path_params": [ { "name": "wishlist_id", "type": "str" } ], "request_body": { "schema_name": "WishlistUpdate", "fields": [ { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "name", "type": "str", "required": false, "nullable": true }, { "name": "is_public", "type": "bool", "required": false, "nullable": true } ] }, "response": { "schema_name": "WishlistResponse", "fields": [ { "name": "user_id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "is_public", "type": "bool", "required": false, "default": false }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/wishlists/{wishlist_id}", "summary": "Delete Wishlist", "description": "Deletes a wishlist by ID. Returns 404 if the wishlist does not exist.", "path_params": [ { "name": "wishlist_id", "type": "str" } ], "status_code": 200 }, { "method": "GET", "path": "/wishlists/{wishlist_id}/details", "summary": "Get Wishlist Details", "description": "Retrieves detailed wishlist information including all wishlist items with their associated cards and card sets. Returns 404 if the wishlist does not exist.", "path_params": [ { "name": "wishlist_id", "type": "str" } ], "response": { "schema_name": "WishlistDetailResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true }, { "name": "is_public", "type": "bool", "required": true }, { "name": "wishlist_items", "type": "list[WishlistDetailItemResponse]", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/wishlist-items", "summary": "Create Wishlist Item", "description": "Adds a card to a wishlist. Validates that the wishlist and card exist. Returns 400 if validation fails.", "request_body": { "schema_name": "WishlistitemCreate", "fields": [ { "name": "wishlist_id", "type": "str", "required": true }, { "name": "card_id", "type": "str", "required": true }, { "name": "price_alert_threshold", "type": "Decimal", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "WishlistitemResponse", "fields": [ { "name": "wishlist_id", "type": "str", "required": true }, { "name": "card_id", "type": "str", "required": true }, { "name": "price_alert_threshold", "type": "Decimal", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/wishlist-items/{wishlistitem_id}", "summary": "Get Wishlist Item", "description": "Retrieves a wishlist item by ID. Returns 404 if the wishlist item does not exist.", "path_params": [ { "name": "wishlistitem_id", "type": "str" } ], "response": { "schema_name": "WishlistitemResponse", "fields": [ { "name": "wishlist_id", "type": "str", "required": true }, { "name": "card_id", "type": "str", "required": true }, { "name": "price_alert_threshold", "type": "Decimal", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/wishlist-items", "summary": "List Wishlist Items", "description": "Returns a paginated list of wishlist items. Supports optional filtering by wishlist_id and card_id.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "wishlist_id", "type": "str", "required": false }, { "name": "card_id", "type": "str", "required": false } ], "response": { "schema_name": "WishlistitemResponse", "fields": [ { "name": "wishlist_id", "type": "str", "required": true }, { "name": "card_id", "type": "str", "required": true }, { "name": "price_alert_threshold", "type": "Decimal", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/wishlist-items/{wishlistitem_id}", "summary": "Update Wishlist Item", "description": "Updates a wishlist item by ID. Validates that the wishlist and card exist. Returns 404 if the wishlist item does not exist or 400 if validation fails.", "path_params": [ { "name": "wishlistitem_id", "type": "str" } ], "request_body": { "schema_name": "WishlistitemUpdate", "fields": [ { "name": "wishlist_id", "type": "str", "required": false, "nullable": true }, { "name": "card_id", "type": "str", "required": false, "nullable": true }, { "name": "price_alert_threshold", "type": "Decimal", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "WishlistitemResponse", "fields": [ { "name": "wishlist_id", "type": "str", "required": true }, { "name": "card_id", "type": "str", "required": true }, { "name": "price_alert_threshold", "type": "Decimal", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/wishlist-items/{wishlistitem_id}", "summary": "Delete Wishlist Item", "description": "Removes a wishlist item by ID. Returns 404 if the wishlist item does not exist.", "path_params": [ { "name": "wishlistitem_id", "type": "str" } ], "status_code": 200 } ] }, { "name": "Orders", "prefix": "/orders", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Order", "description": "Creates a new order record. Validates that buyer, seller, and addresses exist. Returns 409 if order number already exists. Returns 404 if any referenced entity is not found.", "request_body": { "schema_name": "OrderCreate", "fields": [ { "name": "order_number", "type": "str", "required": false }, { "name": "buyer_id", "type": "str", "required": false }, { "name": "seller_id", "type": "str", "required": false }, { "name": "status", "type": "OrderStatus", "required": true, "enum_values": [ "PENDING", "PAID", "PROCESSING", "SHIPPED", "DELIVERED", "CANCELLED", "REFUNDED", "DISPUTED" ] }, { "name": "subtotal", "type": "Decimal", "required": false }, { "name": "shipping_cost", "type": "Decimal", "required": false }, { "name": "tax_amount", "type": "Decimal", "required": false }, { "name": "platform_fee", "type": "Decimal", "required": false }, { "name": "total_amount", "type": "Decimal", "required": false }, { "name": "shipping_address_id", "type": "str", "required": false }, { "name": "billing_address_id", "type": "str", "required": false }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "cancelled_at", "type": "datetime", "required": false, "nullable": true }, { "name": "cancellation_reason", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "OrderResponse", "fields": [ { "name": "order_number", "type": "str", "required": true }, { "name": "order_items", "type": "list[OrderItemResponse]", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/", "summary": "List Orders", "description": "Returns a paginated list of orders. Supports optional filters for buyer_id, seller_id, status, and order_number.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "buyer_id", "type": "str", "required": false }, { "name": "seller_id", "type": "str", "required": false }, { "name": "status", "type": "OrderStatus", "required": false }, { "name": "order_number", "type": "str", "required": false } ], "response": { "schema_name": "OrderResponse", "fields": [ { "name": "order_number", "type": "str", "required": true }, { "name": "order_items", "type": "list[OrderItemResponse]", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/{order_id}", "summary": "Get Order", "description": "Returns a single order by ID. Returns 404 if order not found.", "path_params": [ { "name": "order_id", "type": "str" } ], "response": { "schema_name": "OrderResponse", "fields": [ { "name": "order_number", "type": "str", "required": true }, { "name": "order_items", "type": "list[OrderItemResponse]", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{order_id}/details", "summary": "Get Order Details", "description": "Returns detailed order information including buyer, seller, order items with listing and card details, payment status, shipment tracking, and addresses. Uses eager loading to prevent N+1 queries. Returns 404 if order not found.", "path_params": [ { "name": "order_id", "type": "str" } ], "response": { "schema_name": "OrderDetailResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "order_number", "type": "str", "required": true }, { "name": "buyer_id", "type": "str", "required": true }, { "name": "seller_id", "type": "str", "required": true }, { "name": "status", "type": "OrderStatus", "required": true, "enum_values": [ "PENDING", "PAID", "PROCESSING", "SHIPPED", "DELIVERED", "CANCELLED", "REFUNDED", "DISPUTED" ] }, { "name": "subtotal", "type": "Decimal", "required": true }, { "name": "shipping_cost", "type": "Decimal", "required": true }, { "name": "tax_amount", "type": "Decimal", "required": true }, { "name": "platform_fee", "type": "Decimal", "required": true }, { "name": "total_amount", "type": "Decimal", "required": true }, { "name": "shipping_address_id", "type": "str", "required": true }, { "name": "billing_address_id", "type": "str", "required": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "cancelled_at", "type": "datetime", "required": false, "nullable": true }, { "name": "cancellation_reason", "type": "str", "required": false, "nullable": true }, { "name": "buyer_email", "type": "str", "required": true }, { "name": "seller_email", "type": "str", "required": true }, { "name": "seller_store_name", "type": "str", "required": false, "nullable": true }, { "name": "order_items", "type": "List[OrderitemDetailResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "id", "type": "str", "required": true }, { "name": "order_id", "type": "str", "required": true }, { "name": "listing_id", "type": "str", "required": true }, { "name": "card_id", "type": "str", "required": true }, { "name": "quantity", "type": "int", "required": true }, { "name": "price", "type": "Decimal", "required": true }, { "name": "condition", "type": "str", "required": true }, { "name": "listing_title", "type": "str", "required": true }, { "name": "card_name", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] }, { "name": "payment_status", "type": "PaymentStatus", "required": false, "nullable": true, "enum_values": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "REFUNDED", "CANCELLED" ] }, { "name": "shipment_tracking_number", "type": "str", "required": false, "nullable": true }, { "name": "shipping_address_line1", "type": "str", "required": true }, { "name": "billing_address_line1", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{order_id}", "summary": "Update Order", "description": "Updates an existing order. Validates that any updated buyer, seller, or addresses exist. Returns 404 if order or referenced entity not found. Returns 409 if updated order number conflicts with existing order.", "path_params": [ { "name": "order_id", "type": "str" } ], "request_body": { "schema_name": "OrderUpdate", "fields": [ { "name": "order_number", "type": "str", "required": false, "nullable": true }, { "name": "buyer_id", "type": "str", "required": false, "nullable": true }, { "name": "seller_id", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "OrderStatus", "required": false, "nullable": true, "enum_values": [ "PENDING", "PAID", "PROCESSING", "SHIPPED", "DELIVERED", "CANCELLED", "REFUNDED", "DISPUTED" ] }, { "name": "subtotal", "type": "Decimal", "required": false, "nullable": true }, { "name": "shipping_cost", "type": "Decimal", "required": false, "nullable": true }, { "name": "tax_amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "platform_fee", "type": "Decimal", "required": false, "nullable": true }, { "name": "total_amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "shipping_address_id", "type": "str", "required": false, "nullable": true }, { "name": "billing_address_id", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "cancelled_at", "type": "datetime", "required": false, "nullable": true }, { "name": "cancellation_reason", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "OrderResponse", "fields": [ { "name": "order_number", "type": "str", "required": true }, { "name": "order_items", "type": "list[OrderItemResponse]", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{order_id}", "summary": "Delete Order", "description": "Deletes an order and all related order items, payment, and shipment records via cascade. Returns 404 if order not found.", "path_params": [ { "name": "order_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/{order_id}/ship", "summary": "Ship Order", "description": "Marks an order as shipped and updates shipment status to IN_TRANSIT. Order must be in PROCESSING status. Returns 400 if order is not in correct status or shipment record not found. Returns 404 if order not found.", "path_params": [ { "name": "order_id", "type": "str" } ], "response": { "schema_name": "OrderResponse", "fields": [ { "name": "order_number", "type": "str", "required": true }, { "name": "order_items", "type": "list[OrderItemResponse]", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/{order_id}/cancel", "summary": "Cancel Order", "description": "Cancels an order with a reason. Cannot cancel orders after shipment or orders already cancelled/refunded. Returns 400 if order cannot be cancelled. Returns 404 if order not found.", "path_params": [ { "name": "order_id", "type": "str" } ], "query_params": [ { "name": "cancellation_reason", "type": "str", "required": false, "default": null } ], "response": { "schema_name": "OrderResponse", "fields": [ { "name": "order_number", "type": "str", "required": true }, { "name": "order_items", "type": "list[OrderItemResponse]", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/{order_id}/confirm-delivery", "summary": "Confirm Order Delivery", "description": "Confirms order delivery and updates order status to DELIVERED and shipment status to DELIVERED. Order must be in SHIPPED status. Returns 400 if order is not in correct status or shipment record not found. Returns 404 if order not found.", "path_params": [ { "name": "order_id", "type": "str" } ], "response": { "schema_name": "OrderResponse", "fields": [ { "name": "order_number", "type": "str", "required": true }, { "name": "order_items", "type": "list[OrderItemResponse]", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{order_id}/tracking", "summary": "Get Order Tracking", "description": "Returns tracking information for an order including carrier, tracking number, shipment status, and delivery dates. Returns 404 if order or shipment not found.", "path_params": [ { "name": "order_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/items", "summary": "Create Order Item", "description": "Creates a new order item record. Validates that order, listing, and card exist. Returns 404 if any referenced entity not found.", "request_body": { "schema_name": "OrderitemCreate", "fields": [ { "name": "order_id", "type": "str", "required": false }, { "name": "listing_id", "type": "str", "required": false }, { "name": "card_id", "type": "str", "required": false }, { "name": "quantity", "type": "int", "required": false }, { "name": "price", "type": "Decimal", "required": false }, { "name": "condition", "type": "str", "required": false } ] }, "response": { "schema_name": "OrderitemResponse", "fields": [ { "name": "order_id", "type": "str", "required": false }, { "name": "listing_id", "type": "str", "required": false }, { "name": "card_id", "type": "str", "required": false }, { "name": "quantity", "type": "int", "required": false }, { "name": "price", "type": "Decimal", "required": false }, { "name": "condition", "type": "str", "required": false }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/items", "summary": "List Order Items", "description": "Returns a paginated list of order items. Supports optional filters for order_id, listing_id, and card_id.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "order_id", "type": "str", "required": false }, { "name": "listing_id", "type": "str", "required": false }, { "name": "card_id", "type": "str", "required": false } ], "response": { "schema_name": "OrderitemResponse", "fields": [ { "name": "order_id", "type": "str", "required": false }, { "name": "listing_id", "type": "str", "required": false }, { "name": "card_id", "type": "str", "required": false }, { "name": "quantity", "type": "int", "required": false }, { "name": "price", "type": "Decimal", "required": false }, { "name": "condition", "type": "str", "required": false }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/items/{orderitem_id}", "summary": "Get Order Item", "description": "Returns a single order item by ID. Returns 404 if order item not found.", "path_params": [ { "name": "orderitem_id", "type": "str" } ], "response": { "schema_name": "OrderitemResponse", "fields": [ { "name": "order_id", "type": "str", "required": false }, { "name": "listing_id", "type": "str", "required": false }, { "name": "card_id", "type": "str", "required": false }, { "name": "quantity", "type": "int", "required": false }, { "name": "price", "type": "Decimal", "required": false }, { "name": "condition", "type": "str", "required": false }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/items/{orderitem_id}", "summary": "Update Order Item", "description": "Updates an existing order item. Validates that any updated order, listing, or card exists. Returns 404 if order item or referenced entity not found.", "path_params": [ { "name": "orderitem_id", "type": "str" } ], "request_body": { "schema_name": "OrderitemUpdate", "fields": [ { "name": "order_id", "type": "str", "required": false, "nullable": true }, { "name": "listing_id", "type": "str", "required": false, "nullable": true }, { "name": "card_id", "type": "str", "required": false, "nullable": true }, { "name": "quantity", "type": "int", "required": false, "nullable": true }, { "name": "price", "type": "Decimal", "required": false, "nullable": true }, { "name": "condition", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "OrderitemResponse", "fields": [ { "name": "order_id", "type": "str", "required": false }, { "name": "listing_id", "type": "str", "required": false }, { "name": "card_id", "type": "str", "required": false }, { "name": "quantity", "type": "int", "required": false }, { "name": "price", "type": "Decimal", "required": false }, { "name": "condition", "type": "str", "required": false }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/items/{orderitem_id}", "summary": "Delete Order Item", "description": "Deletes an order item. Returns 404 if order item not found.", "path_params": [ { "name": "orderitem_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/payments", "summary": "Create Payment", "description": "Creates a new payment record for an order. Validates that order exists and payment amount matches order total. Returns 409 if payment already exists for the order. Returns 400 if payment amount does not match order total. Returns 404 if order not found.", "request_body": { "schema_name": "PaymentCreate", "fields": [ { "name": "order_id", "type": "str", "required": false }, { "name": "payment_method", "type": "PaymentMethod", "required": true, "enum_values": [ "CREDIT_CARD", "DEBIT_CARD", "PAYPAL", "STRIPE", "BANK_TRANSFER" ] }, { "name": "amount", "type": "Decimal", "required": false }, { "name": "currency", "type": "str", "required": false }, { "name": "status", "type": "PaymentStatus", "required": true, "enum_values": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "REFUNDED", "CANCELLED" ] }, { "name": "transaction_id", "type": "str", "required": false, "nullable": true }, { "name": "payment_gateway", "type": "str", "required": false, "nullable": true }, { "name": "payment_details", "type": "str", "required": false, "nullable": true }, { "name": "processed_at", "type": "datetime", "required": false, "nullable": true } ] }, "response": { "schema_name": "PaymentResponse", "fields": [ { "name": "order_id", "type": "str", "required": false }, { "name": "payment_method", "type": "PaymentMethod", "required": true, "enum_values": [ "CREDIT_CARD", "DEBIT_CARD", "PAYPAL", "STRIPE", "BANK_TRANSFER" ] }, { "name": "amount", "type": "Decimal", "required": false }, { "name": "currency", "type": "str", "required": false }, { "name": "status", "type": "PaymentStatus", "required": true, "enum_values": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "REFUNDED", "CANCELLED" ] }, { "name": "transaction_id", "type": "str", "required": false, "nullable": true }, { "name": "payment_gateway", "type": "str", "required": false, "nullable": true }, { "name": "payment_details", "type": "str", "required": false, "nullable": true }, { "name": "processed_at", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/payments", "summary": "List Payments", "description": "Returns a paginated list of payments. Supports optional filters for order_id, status, and payment_method.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "order_id", "type": "str", "required": false }, { "name": "status", "type": "PaymentStatus", "required": false }, { "name": "payment_method", "type": "str", "required": false } ], "response": { "schema_name": "PaymentResponse", "fields": [ { "name": "order_id", "type": "str", "required": false }, { "name": "payment_method", "type": "PaymentMethod", "required": true, "enum_values": [ "CREDIT_CARD", "DEBIT_CARD", "PAYPAL", "STRIPE", "BANK_TRANSFER" ] }, { "name": "amount", "type": "Decimal", "required": false }, { "name": "currency", "type": "str", "required": false }, { "name": "status", "type": "PaymentStatus", "required": true, "enum_values": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "REFUNDED", "CANCELLED" ] }, { "name": "transaction_id", "type": "str", "required": false, "nullable": true }, { "name": "payment_gateway", "type": "str", "required": false, "nullable": true }, { "name": "payment_details", "type": "str", "required": false, "nullable": true }, { "name": "processed_at", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/payments/{payment_id}", "summary": "Get Payment", "description": "Returns a single payment by ID. Returns 404 if payment not found.", "path_params": [ { "name": "payment_id", "type": "str" } ], "response": { "schema_name": "PaymentResponse", "fields": [ { "name": "order_id", "type": "str", "required": false }, { "name": "payment_method", "type": "PaymentMethod", "required": true, "enum_values": [ "CREDIT_CARD", "DEBIT_CARD", "PAYPAL", "STRIPE", "BANK_TRANSFER" ] }, { "name": "amount", "type": "Decimal", "required": false }, { "name": "currency", "type": "str", "required": false }, { "name": "status", "type": "PaymentStatus", "required": true, "enum_values": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "REFUNDED", "CANCELLED" ] }, { "name": "transaction_id", "type": "str", "required": false, "nullable": true }, { "name": "payment_gateway", "type": "str", "required": false, "nullable": true }, { "name": "payment_details", "type": "str", "required": false, "nullable": true }, { "name": "processed_at", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/payments/{payment_id}", "summary": "Update Payment", "description": "Updates an existing payment. Validates that any updated order exists and no duplicate payment exists for the order. Returns 404 if payment or order not found. Returns 409 if another payment exists for the updated order.", "path_params": [ { "name": "payment_id", "type": "str" } ], "request_body": { "schema_name": "PaymentUpdate", "fields": [ { "name": "order_id", "type": "str", "required": false, "nullable": true }, { "name": "payment_method", "type": "PaymentMethod", "required": false, "nullable": true, "enum_values": [ "CREDIT_CARD", "DEBIT_CARD", "PAYPAL", "STRIPE", "BANK_TRANSFER" ] }, { "name": "amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "currency", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "PaymentStatus", "required": false, "nullable": true, "enum_values": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "REFUNDED", "CANCELLED" ] }, { "name": "transaction_id", "type": "str", "required": false, "nullable": true }, { "name": "payment_gateway", "type": "str", "required": false, "nullable": true }, { "name": "payment_details", "type": "str", "required": false, "nullable": true }, { "name": "processed_at", "type": "datetime", "required": false, "nullable": true } ] }, "response": { "schema_name": "PaymentResponse", "fields": [ { "name": "order_id", "type": "str", "required": false }, { "name": "payment_method", "type": "PaymentMethod", "required": true, "enum_values": [ "CREDIT_CARD", "DEBIT_CARD", "PAYPAL", "STRIPE", "BANK_TRANSFER" ] }, { "name": "amount", "type": "Decimal", "required": false }, { "name": "currency", "type": "str", "required": false }, { "name": "status", "type": "PaymentStatus", "required": true, "enum_values": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "REFUNDED", "CANCELLED" ] }, { "name": "transaction_id", "type": "str", "required": false, "nullable": true }, { "name": "payment_gateway", "type": "str", "required": false, "nullable": true }, { "name": "payment_details", "type": "str", "required": false, "nullable": true }, { "name": "processed_at", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/payments/{payment_id}", "summary": "Delete Payment", "description": "Deletes a payment record. Returns 404 if payment not found.", "path_params": [ { "name": "payment_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/shipments", "summary": "Create Shipment", "description": "Creates a new shipment record for an order. Validates that order exists. Returns 409 if shipment already exists for the order. Returns 404 if order not found.", "request_body": { "schema_name": "ShipmentCreate", "fields": [ { "name": "order_id", "type": "str", "required": false }, { "name": "carrier", "type": "str", "required": false }, { "name": "tracking_number", "type": "str", "required": false, "nullable": true }, { "name": "shipping_method", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "ShipmentStatus", "required": true, "enum_values": [ "PENDING", "LABEL_CREATED", "IN_TRANSIT", "OUT_FOR_DELIVERY", "DELIVERED", "FAILED", "RETURNED" ] }, { "name": "shipped_at", "type": "datetime", "required": false, "nullable": true }, { "name": "estimated_delivery_date", "type": "datetime", "required": false, "nullable": true }, { "name": "delivered_at", "type": "datetime", "required": false, "nullable": true } ] }, "response": { "schema_name": "ShipmentResponse", "fields": [ { "name": "order_id", "type": "str", "required": false }, { "name": "carrier", "type": "str", "required": false }, { "name": "tracking_number", "type": "str", "required": false, "nullable": true }, { "name": "shipping_method", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "ShipmentStatus", "required": true, "enum_values": [ "PENDING", "LABEL_CREATED", "IN_TRANSIT", "OUT_FOR_DELIVERY", "DELIVERED", "FAILED", "RETURNED" ] }, { "name": "shipped_at", "type": "datetime", "required": false, "nullable": true }, { "name": "estimated_delivery_date", "type": "datetime", "required": false, "nullable": true }, { "name": "delivered_at", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/shipments", "summary": "List Shipments", "description": "Returns a paginated list of shipments. Supports optional filters for order_id, status, carrier, and tracking_number.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "order_id", "type": "str", "required": false }, { "name": "status", "type": "ShipmentStatus", "required": false }, { "name": "carrier", "type": "str", "required": false }, { "name": "tracking_number", "type": "str", "required": false } ], "response": { "schema_name": "ShipmentResponse", "fields": [ { "name": "order_id", "type": "str", "required": false }, { "name": "carrier", "type": "str", "required": false }, { "name": "tracking_number", "type": "str", "required": false, "nullable": true }, { "name": "shipping_method", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "ShipmentStatus", "required": true, "enum_values": [ "PENDING", "LABEL_CREATED", "IN_TRANSIT", "OUT_FOR_DELIVERY", "DELIVERED", "FAILED", "RETURNED" ] }, { "name": "shipped_at", "type": "datetime", "required": false, "nullable": true }, { "name": "estimated_delivery_date", "type": "datetime", "required": false, "nullable": true }, { "name": "delivered_at", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/shipments/{shipment_id}", "summary": "Get Shipment", "description": "Returns a single shipment by ID. Returns 404 if shipment not found.", "path_params": [ { "name": "shipment_id", "type": "str" } ], "response": { "schema_name": "ShipmentResponse", "fields": [ { "name": "order_id", "type": "str", "required": false }, { "name": "carrier", "type": "str", "required": false }, { "name": "tracking_number", "type": "str", "required": false, "nullable": true }, { "name": "shipping_method", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "ShipmentStatus", "required": true, "enum_values": [ "PENDING", "LABEL_CREATED", "IN_TRANSIT", "OUT_FOR_DELIVERY", "DELIVERED", "FAILED", "RETURNED" ] }, { "name": "shipped_at", "type": "datetime", "required": false, "nullable": true }, { "name": "estimated_delivery_date", "type": "datetime", "required": false, "nullable": true }, { "name": "delivered_at", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/shipments/{shipment_id}", "summary": "Update Shipment", "description": "Updates an existing shipment. Validates that any updated order exists and no duplicate shipment exists for the order. Returns 404 if shipment or order not found. Returns 409 if another shipment exists for the updated order.", "path_params": [ { "name": "shipment_id", "type": "str" } ], "request_body": { "schema_name": "ShipmentUpdate", "fields": [ { "name": "order_id", "type": "str", "required": false, "nullable": true }, { "name": "carrier", "type": "str", "required": false, "nullable": true }, { "name": "tracking_number", "type": "str", "required": false, "nullable": true }, { "name": "shipping_method", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "ShipmentStatus", "required": false, "nullable": true, "enum_values": [ "PENDING", "LABEL_CREATED", "IN_TRANSIT", "OUT_FOR_DELIVERY", "DELIVERED", "FAILED", "RETURNED" ] }, { "name": "shipped_at", "type": "datetime", "required": false, "nullable": true }, { "name": "estimated_delivery_date", "type": "datetime", "required": false, "nullable": true }, { "name": "delivered_at", "type": "datetime", "required": false, "nullable": true } ] }, "response": { "schema_name": "ShipmentResponse", "fields": [ { "name": "order_id", "type": "str", "required": false }, { "name": "carrier", "type": "str", "required": false }, { "name": "tracking_number", "type": "str", "required": false, "nullable": true }, { "name": "shipping_method", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "ShipmentStatus", "required": true, "enum_values": [ "PENDING", "LABEL_CREATED", "IN_TRANSIT", "OUT_FOR_DELIVERY", "DELIVERED", "FAILED", "RETURNED" ] }, { "name": "shipped_at", "type": "datetime", "required": false, "nullable": true }, { "name": "estimated_delivery_date", "type": "datetime", "required": false, "nullable": true }, { "name": "delivered_at", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/shipments/{shipment_id}", "summary": "Delete Shipment", "description": "Deletes a shipment record. Returns 404 if shipment not found.", "path_params": [ { "name": "shipment_id", "type": "str" } ], "status_code": 200 } ] }, { "name": "Offers", "prefix": "/offers", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Offer", "description": "Creates a new offer for a listing. Validates that the offer amount is at least 50% of asking price and does not exceed the listing price. Returns 400 if listing does not accept offers or is not active. Returns 404 if buyer or listing not found.", "request_body": { "schema_name": "OfferCreate", "fields": [ { "name": "listing_id", "type": "str", "required": false }, { "name": "buyer_id", "type": "str", "required": false }, { "name": "offer_amount", "type": "Decimal", "required": false }, { "name": "message", "type": "str", "required": false, "nullable": true }, { "name": "expires_at", "type": "datetime", "required": true } ] }, "response": { "schema_name": "OfferResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "listing_id", "type": "str", "required": true }, { "name": "buyer_id", "type": "str", "required": true }, { "name": "offer_amount", "type": "Decimal", "required": true }, { "name": "message", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "str", "required": true }, { "name": "expires_at", "type": "datetime", "required": true }, { "name": "responded_at", "type": "datetime", "required": false, "nullable": true }, { "name": "response_message", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/{offer_id}", "summary": "Get Offer", "description": "Returns a single offer by ID. Returns 404 if offer not found.", "path_params": [ { "name": "offer_id", "type": "str" } ], "response": { "schema_name": "OfferResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "listing_id", "type": "str", "required": true }, { "name": "buyer_id", "type": "str", "required": true }, { "name": "offer_amount", "type": "Decimal", "required": true }, { "name": "message", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "str", "required": true }, { "name": "expires_at", "type": "datetime", "required": true }, { "name": "responded_at", "type": "datetime", "required": false, "nullable": true }, { "name": "response_message", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/", "summary": "List Offers", "description": "Returns a paginated list of offers. Supports optional filters for listing_id, buyer_id, and status.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "listing_id", "type": "str", "required": false }, { "name": "buyer_id", "type": "str", "required": false }, { "name": "status", "type": "str", "required": false } ], "response": { "schema_name": "OfferResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "listing_id", "type": "str", "required": true }, { "name": "buyer_id", "type": "str", "required": true }, { "name": "offer_amount", "type": "Decimal", "required": true }, { "name": "message", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "str", "required": true }, { "name": "expires_at", "type": "datetime", "required": true }, { "name": "responded_at", "type": "datetime", "required": false, "nullable": true }, { "name": "response_message", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/{offer_id}", "summary": "Update Offer", "description": "Updates an existing offer. Returns 404 if offer, buyer, or listing not found.", "path_params": [ { "name": "offer_id", "type": "str" } ], "request_body": { "schema_name": "OfferUpdate", "fields": [ { "name": "listing_id", "type": "str", "required": false, "nullable": true }, { "name": "buyer_id", "type": "str", "required": false, "nullable": true }, { "name": "offer_amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "message", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "str", "required": false, "nullable": true }, { "name": "expires_at", "type": "datetime", "required": false, "nullable": true }, { "name": "responded_at", "type": "datetime", "required": false, "nullable": true }, { "name": "response_message", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "OfferResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "listing_id", "type": "str", "required": true }, { "name": "buyer_id", "type": "str", "required": true }, { "name": "offer_amount", "type": "Decimal", "required": true }, { "name": "message", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "str", "required": true }, { "name": "expires_at", "type": "datetime", "required": true }, { "name": "responded_at", "type": "datetime", "required": false, "nullable": true }, { "name": "response_message", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{offer_id}", "summary": "Delete Offer", "description": "Deletes an offer by ID. Returns 404 if offer not found.", "path_params": [ { "name": "offer_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/{offer_id}/accept", "summary": "Accept Offer", "description": "Accepts a pending offer and reserves the listing. Returns 400 if offer is not pending, has expired, or listing is not active. Returns 404 if offer or listing not found.", "path_params": [ { "name": "offer_id", "type": "str" } ], "response": { "schema_name": "OfferResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "listing_id", "type": "str", "required": true }, { "name": "buyer_id", "type": "str", "required": true }, { "name": "offer_amount", "type": "Decimal", "required": true }, { "name": "message", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "str", "required": true }, { "name": "expires_at", "type": "datetime", "required": true }, { "name": "responded_at", "type": "datetime", "required": false, "nullable": true }, { "name": "response_message", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/{offer_id}/reject", "summary": "Reject Offer", "description": "Rejects a pending offer with optional response message. Returns 400 if offer is not pending. Returns 404 if offer not found.", "path_params": [ { "name": "offer_id", "type": "str" } ], "query_params": [ { "name": "response_message", "type": "str", "required": false } ], "response": { "schema_name": "OfferResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "listing_id", "type": "str", "required": true }, { "name": "buyer_id", "type": "str", "required": true }, { "name": "offer_amount", "type": "Decimal", "required": true }, { "name": "message", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "str", "required": true }, { "name": "expires_at", "type": "datetime", "required": true }, { "name": "responded_at", "type": "datetime", "required": false, "nullable": true }, { "name": "response_message", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/{offer_id}/counter", "summary": "Counter Offer", "description": "Rejects the current offer and creates a new counter offer with a different amount. Returns 400 if offer is not pending, counter amount is invalid, or exceeds asking price. Returns 404 if offer or listing not found.", "path_params": [ { "name": "offer_id", "type": "str" } ], "query_params": [ { "name": "counter_amount", "type": "float", "required": false, "default": null }, { "name": "response_message", "type": "str", "required": false } ], "response": { "schema_name": "OfferResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "listing_id", "type": "str", "required": true }, { "name": "buyer_id", "type": "str", "required": true }, { "name": "offer_amount", "type": "Decimal", "required": true }, { "name": "message", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "str", "required": true }, { "name": "expires_at", "type": "datetime", "required": true }, { "name": "responded_at", "type": "datetime", "required": false, "nullable": true }, { "name": "response_message", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/{offer_id}/cancel", "summary": "Cancel Offer", "description": "Cancels a pending offer. Returns 400 if offer is not pending. Returns 404 if offer not found.", "path_params": [ { "name": "offer_id", "type": "str" } ], "response": { "schema_name": "OfferResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "listing_id", "type": "str", "required": true }, { "name": "buyer_id", "type": "str", "required": true }, { "name": "offer_amount", "type": "Decimal", "required": true }, { "name": "message", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "str", "required": true }, { "name": "expires_at", "type": "datetime", "required": true }, { "name": "responded_at", "type": "datetime", "required": false, "nullable": true }, { "name": "response_message", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 } ] }, { "name": "Communication", "prefix": "/conversations", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Conversation", "description": "Creates a new conversation between two users. Validates that both participants exist and are different users. Optionally links the conversation to a listing or order context.", "request_body": { "schema_name": "ConversationCreate", "fields": [ { "name": "participant1_id", "type": "str", "required": false }, { "name": "participant2_id", "type": "str", "required": false }, { "name": "listing_id", "type": "str", "required": false, "nullable": true }, { "name": "order_id", "type": "str", "required": false, "nullable": true }, { "name": "last_message_at", "type": "datetime", "required": false, "nullable": true } ] }, "response": { "schema_name": "ConversationResponse", "fields": [ { "name": "participant1_id", "type": "str", "required": false }, { "name": "participant2_id", "type": "str", "required": false }, { "name": "listing_id", "type": "str", "required": false, "nullable": true }, { "name": "order_id", "type": "str", "required": false, "nullable": true }, { "name": "last_message_at", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/", "summary": "List Conversations", "description": "Returns a paginated list of conversations. Supports optional filtering by participant IDs, listing ID, or order ID. Results are ordered by last message timestamp descending.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "participant1_id", "type": "str", "required": false }, { "name": "participant2_id", "type": "str", "required": false }, { "name": "listing_id", "type": "str", "required": false }, { "name": "order_id", "type": "str", "required": false } ], "response": { "schema_name": "ConversationResponse", "fields": [ { "name": "participant1_id", "type": "str", "required": false }, { "name": "participant2_id", "type": "str", "required": false }, { "name": "listing_id", "type": "str", "required": false, "nullable": true }, { "name": "order_id", "type": "str", "required": false, "nullable": true }, { "name": "last_message_at", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/{conversation_id}", "summary": "Get Conversation", "description": "Returns a single conversation by ID. Returns 404 if the conversation does not exist.", "path_params": [ { "name": "conversation_id", "type": "str" } ], "response": { "schema_name": "ConversationResponse", "fields": [ { "name": "participant1_id", "type": "str", "required": false }, { "name": "participant2_id", "type": "str", "required": false }, { "name": "listing_id", "type": "str", "required": false, "nullable": true }, { "name": "order_id", "type": "str", "required": false, "nullable": true }, { "name": "last_message_at", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{conversation_id}/details", "summary": "Get Conversation Details", "description": "Returns detailed conversation information including both participants, all messages with sender details, and optional listing or order context. All related data is eagerly loaded to avoid N+1 queries.", "path_params": [ { "name": "conversation_id", "type": "str" } ], "response": { "schema_name": "ConversationDetailResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "participant1", "type": "UserBasicInfo", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true } ] }, { "name": "participant2", "type": "UserBasicInfo", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true } ] }, { "name": "listing", "type": "ListingBasicInfo", "required": false, "nullable": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "title", "type": "str", "required": true } ] }, { "name": "order", "type": "OrderBasicInfo", "required": false, "nullable": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "order_number", "type": "str", "required": true } ] }, { "name": "messages", "type": "List[MessageDetailResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "id", "type": "str", "required": true }, { "name": "conversation_id", "type": "str", "required": true }, { "name": "sender", "type": "UserBasicInfo", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true } ] }, { "name": "message_text", "type": "str", "required": true }, { "name": "is_read", "type": "bool", "required": true }, { "name": "read_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] }, { "name": "last_message_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{conversation_id}", "summary": "Update Conversation", "description": "Updates conversation details. Validates that any new participant IDs, listing ID, or order ID exist in the database. Returns 404 if the conversation does not exist.", "path_params": [ { "name": "conversation_id", "type": "str" } ], "request_body": { "schema_name": "ConversationUpdate", "fields": [ { "name": "participant1_id", "type": "str", "required": false, "nullable": true }, { "name": "participant2_id", "type": "str", "required": false, "nullable": true }, { "name": "listing_id", "type": "str", "required": false, "nullable": true }, { "name": "order_id", "type": "str", "required": false, "nullable": true }, { "name": "last_message_at", "type": "datetime", "required": false, "nullable": true } ] }, "response": { "schema_name": "ConversationResponse", "fields": [ { "name": "participant1_id", "type": "str", "required": false }, { "name": "participant2_id", "type": "str", "required": false }, { "name": "listing_id", "type": "str", "required": false, "nullable": true }, { "name": "order_id", "type": "str", "required": false, "nullable": true }, { "name": "last_message_at", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{conversation_id}", "summary": "Delete Conversation", "description": "Deletes a conversation and all associated messages. Returns 404 if the conversation does not exist.", "path_params": [ { "name": "conversation_id", "type": "str" } ], "status_code": 200 }, { "method": "GET", "path": "/users/{user_id}/conversations", "summary": "Get User Conversations", "description": "Returns all conversations where the specified user is a participant (either participant1 or participant2). Results are ordered by last message timestamp descending.", "path_params": [ { "name": "user_id", "type": "str" } ], "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 } ], "response": { "schema_name": "ConversationResponse", "fields": [ { "name": "participant1_id", "type": "str", "required": false }, { "name": "participant2_id", "type": "str", "required": false }, { "name": "listing_id", "type": "str", "required": false, "nullable": true }, { "name": "order_id", "type": "str", "required": false, "nullable": true }, { "name": "last_message_at", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 } ] }, { "name": "Reviews", "prefix": "/reviews", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Review", "description": "Creates a new review for a completed order. Validates that the order exists, the reviewer and seller are valid users, and enforces the business rule of one review per order. Returns 404 if order or users not found, 409 if a review already exists for the order.", "request_body": { "schema_name": "ReviewCreate", "fields": [ { "name": "order_id", "type": "str", "required": false }, { "name": "reviewer_id", "type": "str", "required": false }, { "name": "seller_id", "type": "str", "required": false }, { "name": "rating", "type": "int", "required": false }, { "name": "title", "type": "str", "required": false, "nullable": true }, { "name": "comment", "type": "str", "required": false, "nullable": true }, { "name": "is_verified_purchase", "type": "bool", "required": false, "default": true } ] }, "response": { "schema_name": "ReviewResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "order_id", "type": "str", "required": true }, { "name": "reviewer_id", "type": "str", "required": true }, { "name": "seller_id", "type": "str", "required": true }, { "name": "rating", "type": "int", "required": true }, { "name": "title", "type": "str", "required": false, "nullable": true }, { "name": "comment", "type": "str", "required": false, "nullable": true }, { "name": "seller_response", "type": "str", "required": false, "nullable": true }, { "name": "seller_response_at", "type": "datetime", "required": false, "nullable": true }, { "name": "is_verified_purchase", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/", "summary": "List Reviews", "description": "Returns a paginated list of reviews. Supports optional filtering by order_id, reviewer_id, seller_id, rating, and is_verified_purchase. Results are ordered by creation date descending.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "order_id", "type": "str", "required": false }, { "name": "reviewer_id", "type": "str", "required": false }, { "name": "seller_id", "type": "str", "required": false }, { "name": "rating", "type": "int", "required": false }, { "name": "is_verified_purchase", "type": "bool", "required": false } ], "response": { "schema_name": "ReviewResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "order_id", "type": "str", "required": true }, { "name": "reviewer_id", "type": "str", "required": true }, { "name": "seller_id", "type": "str", "required": true }, { "name": "rating", "type": "int", "required": true }, { "name": "title", "type": "str", "required": false, "nullable": true }, { "name": "comment", "type": "str", "required": false, "nullable": true }, { "name": "seller_response", "type": "str", "required": false, "nullable": true }, { "name": "seller_response_at", "type": "datetime", "required": false, "nullable": true }, { "name": "is_verified_purchase", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/{review_id}", "summary": "Get Review", "description": "Retrieves a single review by ID. Returns 404 if the review does not exist.", "path_params": [ { "name": "review_id", "type": "str" } ], "response": { "schema_name": "ReviewResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "order_id", "type": "str", "required": true }, { "name": "reviewer_id", "type": "str", "required": true }, { "name": "seller_id", "type": "str", "required": true }, { "name": "rating", "type": "int", "required": true }, { "name": "title", "type": "str", "required": false, "nullable": true }, { "name": "comment", "type": "str", "required": false, "nullable": true }, { "name": "seller_response", "type": "str", "required": false, "nullable": true }, { "name": "seller_response_at", "type": "datetime", "required": false, "nullable": true }, { "name": "is_verified_purchase", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{review_id}/details", "summary": "Get Review Details", "description": "Retrieves detailed review information including order details, reviewer profile, and seller profile. Uses eager loading to prevent N+1 queries. Returns 404 if the review does not exist.", "path_params": [ { "name": "review_id", "type": "str" } ], "response": { "schema_name": "ReviewDetailsResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "order_id", "type": "str", "required": true }, { "name": "reviewer_id", "type": "str", "required": true }, { "name": "seller_id", "type": "str", "required": true }, { "name": "rating", "type": "int", "required": true }, { "name": "title", "type": "str", "required": false, "nullable": true }, { "name": "comment", "type": "str", "required": false, "nullable": true }, { "name": "seller_response", "type": "str", "required": false, "nullable": true }, { "name": "seller_response_at", "type": "datetime", "required": false, "nullable": true }, { "name": "is_verified_purchase", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "order", "type": "OrderSummary", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "order_number", "type": "str", "required": true } ] }, { "name": "reviewer", "type": "UserSummary", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true } ] }, { "name": "seller", "type": "UserSummary", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true } ] } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{review_id}", "summary": "Update Review", "description": "Updates an existing review. Validates foreign key references if order_id, reviewer_id, or seller_id are changed. Returns 404 if the review or referenced entities do not exist.", "path_params": [ { "name": "review_id", "type": "str" } ], "request_body": { "schema_name": "ReviewUpdate", "fields": [ { "name": "order_id", "type": "str", "required": false, "nullable": true }, { "name": "reviewer_id", "type": "str", "required": false, "nullable": true }, { "name": "seller_id", "type": "str", "required": false, "nullable": true }, { "name": "rating", "type": "int", "required": false, "nullable": true }, { "name": "title", "type": "str", "required": false, "nullable": true }, { "name": "comment", "type": "str", "required": false, "nullable": true }, { "name": "seller_response", "type": "str", "required": false, "nullable": true }, { "name": "seller_response_at", "type": "datetime", "required": false, "nullable": true }, { "name": "is_verified_purchase", "type": "bool", "required": false, "nullable": true } ] }, "response": { "schema_name": "ReviewResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "order_id", "type": "str", "required": true }, { "name": "reviewer_id", "type": "str", "required": true }, { "name": "seller_id", "type": "str", "required": true }, { "name": "rating", "type": "int", "required": true }, { "name": "title", "type": "str", "required": false, "nullable": true }, { "name": "comment", "type": "str", "required": false, "nullable": true }, { "name": "seller_response", "type": "str", "required": false, "nullable": true }, { "name": "seller_response_at", "type": "datetime", "required": false, "nullable": true }, { "name": "is_verified_purchase", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{review_id}", "summary": "Delete Review", "description": "Permanently deletes a review. Returns 404 if the review does not exist.", "path_params": [ { "name": "review_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/{review_id}/respond", "summary": "Seller Responds to Review", "description": "Allows a seller to respond to a review. Validates that the seller_id matches the review's seller_id. Updates seller_response and seller_response_at fields. Returns 403 if the seller is not authorized, 404 if the review does not exist.", "path_params": [ { "name": "review_id", "type": "str" } ], "response": { "schema_name": "ReviewResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "order_id", "type": "str", "required": true }, { "name": "reviewer_id", "type": "str", "required": true }, { "name": "seller_id", "type": "str", "required": true }, { "name": "rating", "type": "int", "required": true }, { "name": "title", "type": "str", "required": false, "nullable": true }, { "name": "comment", "type": "str", "required": false, "nullable": true }, { "name": "seller_response", "type": "str", "required": false, "nullable": true }, { "name": "seller_response_at", "type": "datetime", "required": false, "nullable": true }, { "name": "is_verified_purchase", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 } ] }, { "name": "Disputes", "prefix": "/disputes", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Dispute", "description": "Creates a new dispute for an order. Validates that the order exists, is delivered or completed, and that the complainant is either the buyer or seller. Returns 400 if the order status is invalid or complainant is not authorized. Returns 404 if order or users not found. Returns 409 if an active dispute already exists for the order.", "request_body": { "schema_name": "DisputeCreate", "fields": [ { "name": "order_id", "type": "str", "required": true }, { "name": "complainant_id", "type": "str", "required": true }, { "name": "respondent_id", "type": "str", "required": true }, { "name": "reason", "type": "DisputeReason", "required": true, "enum_values": [ "ITEM_NOT_RECEIVED", "ITEM_NOT_AS_DESCRIBED", "DAMAGED_ITEM", "COUNTERFEIT", "OTHER" ] }, { "name": "description", "type": "str", "required": true } ] }, "response": { "schema_name": "DisputeResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "order_id", "type": "str", "required": true }, { "name": "complainant_id", "type": "str", "required": true }, { "name": "respondent_id", "type": "str", "required": true }, { "name": "reason", "type": "str", "required": true }, { "name": "description", "type": "str", "required": true }, { "name": "status", "type": "str", "required": true }, { "name": "resolution", "type": "str", "required": false, "nullable": true }, { "name": "resolved_by_id", "type": "str", "required": false, "nullable": true }, { "name": "resolved_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/{dispute_id}", "summary": "Get Dispute", "description": "Returns a single dispute by ID. Returns 404 if the dispute does not exist.", "path_params": [ { "name": "dispute_id", "type": "str" } ], "response": { "schema_name": "DisputeResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "order_id", "type": "str", "required": true }, { "name": "complainant_id", "type": "str", "required": true }, { "name": "respondent_id", "type": "str", "required": true }, { "name": "reason", "type": "str", "required": true }, { "name": "description", "type": "str", "required": true }, { "name": "status", "type": "str", "required": true }, { "name": "resolution", "type": "str", "required": false, "nullable": true }, { "name": "resolved_by_id", "type": "str", "required": false, "nullable": true }, { "name": "resolved_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/", "summary": "List Disputes", "description": "Returns a paginated list of disputes. Supports optional filters for status, complainant_id, respondent_id, and order_id. Results are ordered by creation date descending.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "status", "type": "str", "required": false }, { "name": "complainant_id", "type": "str", "required": false }, { "name": "respondent_id", "type": "str", "required": false }, { "name": "order_id", "type": "str", "required": false } ], "response": { "schema_name": "DisputeResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "order_id", "type": "str", "required": true }, { "name": "complainant_id", "type": "str", "required": true }, { "name": "respondent_id", "type": "str", "required": true }, { "name": "reason", "type": "str", "required": true }, { "name": "description", "type": "str", "required": true }, { "name": "status", "type": "str", "required": true }, { "name": "resolution", "type": "str", "required": false, "nullable": true }, { "name": "resolved_by_id", "type": "str", "required": false, "nullable": true }, { "name": "resolved_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/{dispute_id}", "summary": "Update Dispute", "description": "Updates an existing dispute. Validates that referenced order and users exist. Returns 404 if dispute, order, or users not found.", "path_params": [ { "name": "dispute_id", "type": "str" } ], "request_body": { "schema_name": "DisputeUpdate", "fields": [ { "name": "order_id", "type": "str", "required": false, "nullable": true }, { "name": "complainant_id", "type": "str", "required": false, "nullable": true }, { "name": "respondent_id", "type": "str", "required": false, "nullable": true }, { "name": "reason", "type": "DisputeReason", "required": false, "nullable": true, "enum_values": [ "ITEM_NOT_RECEIVED", "ITEM_NOT_AS_DESCRIBED", "DAMAGED_ITEM", "COUNTERFEIT", "OTHER" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "DisputeStatus", "required": false, "nullable": true, "enum_values": [ "OPEN", "UNDER_REVIEW", "RESOLVED", "CLOSED", "ESCALATED" ] }, { "name": "resolution", "type": "str", "required": false, "nullable": true }, { "name": "resolved_by_id", "type": "str", "required": false, "nullable": true }, { "name": "resolved_at", "type": "datetime", "required": false, "nullable": true } ] }, "response": { "schema_name": "DisputeResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "order_id", "type": "str", "required": true }, { "name": "complainant_id", "type": "str", "required": true }, { "name": "respondent_id", "type": "str", "required": true }, { "name": "reason", "type": "str", "required": true }, { "name": "description", "type": "str", "required": true }, { "name": "status", "type": "str", "required": true }, { "name": "resolution", "type": "str", "required": false, "nullable": true }, { "name": "resolved_by_id", "type": "str", "required": false, "nullable": true }, { "name": "resolved_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{dispute_id}", "summary": "Delete Dispute", "description": "Deletes a dispute by ID. Returns 404 if the dispute does not exist.", "path_params": [ { "name": "dispute_id", "type": "str" } ], "status_code": 200 }, { "method": "GET", "path": "/{dispute_id}/details", "summary": "Get Dispute Details", "description": "Returns detailed dispute information including order details with order items and card names, complainant and respondent user emails, and resolver user email if resolved. Uses eager loading to prevent N+1 queries. Returns 404 if dispute not found.", "path_params": [ { "name": "dispute_id", "type": "str" } ], "response": { "schema_name": "DisputeDetailResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "order_id", "type": "str", "required": true }, { "name": "complainant_id", "type": "str", "required": true }, { "name": "respondent_id", "type": "str", "required": true }, { "name": "reason", "type": "str", "required": true }, { "name": "description", "type": "str", "required": true }, { "name": "status", "type": "str", "required": true }, { "name": "resolution", "type": "str", "required": false, "nullable": true }, { "name": "resolved_by_id", "type": "str", "required": false, "nullable": true }, { "name": "resolved_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "order", "type": "OrderResponse", "required": true, "fields": [ { "name": "order_number", "type": "str", "required": true }, { "name": "order_items", "type": "list[OrderItemResponse]", "required": true } ] }, { "name": "complainant", "type": "UserResponse", "required": true, "fields": [ { "name": "email", "type": "str", "required": true } ] }, { "name": "respondent", "type": "UserResponse", "required": true, "fields": [ { "name": "email", "type": "str", "required": true } ] }, { "name": "resolved_by", "type": "UserResponse", "required": false, "nullable": true, "fields": [ { "name": "email", "type": "str", "required": true } ] } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/{dispute_id}/resolve", "summary": "Resolve Dispute", "description": "Resolves an open, under review, or escalated dispute by recording the resolution details and marking it as resolved. Updates status to RESOLVED, sets resolution text, resolved_by_id, and resolved_at timestamp. Returns 400 if dispute is not in a resolvable state. Returns 404 if dispute or resolver user not found.", "path_params": [ { "name": "dispute_id", "type": "str" } ], "query_params": [ { "name": "resolution", "type": "str", "required": false, "default": null }, { "name": "resolved_by_id", "type": "str", "required": false, "default": null } ], "response": { "schema_name": "DisputeResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "order_id", "type": "str", "required": true }, { "name": "complainant_id", "type": "str", "required": true }, { "name": "respondent_id", "type": "str", "required": true }, { "name": "reason", "type": "str", "required": true }, { "name": "description", "type": "str", "required": true }, { "name": "status", "type": "str", "required": true }, { "name": "resolution", "type": "str", "required": false, "nullable": true }, { "name": "resolved_by_id", "type": "str", "required": false, "nullable": true }, { "name": "resolved_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 } ] }, { "name": "Transactions", "prefix": "/transactions", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Transaction", "description": "Creates a new transaction record for platform fees, seller payouts, refunds, or other financial activities. Validates that the referenced user and optional order exist. Returns 400 if user or order is not found.", "request_body": { "schema_name": "TransactionCreate", "fields": [ { "name": "user_id", "type": "str", "required": true }, { "name": "order_id", "type": "str", "required": false, "nullable": true }, { "name": "transaction_type", "type": "TransactionTypeEnum", "required": true, "enum_values": [ "SALE", "PURCHASE", "REFUND", "PAYOUT", "PLATFORM_FEE", "ADJUSTMENT" ] }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "currency", "type": "str", "required": false, "default": "USD" }, { "name": "status", "type": "TransactionStatusEnum", "required": true, "enum_values": [ "PENDING", "COMPLETED", "FAILED", "CANCELLED" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "reference_id", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "TransactionResponse", "fields": [ { "name": "user_id", "type": "str", "required": true }, { "name": "order_id", "type": "str", "required": false, "nullable": true }, { "name": "transaction_type", "type": "TransactionTypeEnum", "required": true, "enum_values": [ "SALE", "PURCHASE", "REFUND", "PAYOUT", "PLATFORM_FEE", "ADJUSTMENT" ] }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "currency", "type": "str", "required": false, "default": "USD" }, { "name": "status", "type": "TransactionStatusEnum", "required": true, "enum_values": [ "PENDING", "COMPLETED", "FAILED", "CANCELLED" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "reference_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/{id}", "summary": "Get Transaction By ID", "description": "Retrieves a single transaction by its unique identifier. Returns 404 if the transaction does not exist.", "path_params": [ { "name": "id", "type": "str" } ], "response": { "schema_name": "TransactionResponse", "fields": [ { "name": "user_id", "type": "str", "required": true }, { "name": "order_id", "type": "str", "required": false, "nullable": true }, { "name": "transaction_type", "type": "TransactionTypeEnum", "required": true, "enum_values": [ "SALE", "PURCHASE", "REFUND", "PAYOUT", "PLATFORM_FEE", "ADJUSTMENT" ] }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "currency", "type": "str", "required": false, "default": "USD" }, { "name": "status", "type": "TransactionStatusEnum", "required": true, "enum_values": [ "PENDING", "COMPLETED", "FAILED", "CANCELLED" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "reference_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/", "summary": "List Transactions", "description": "Returns a paginated list of transactions. Supports optional filtering by user_id, order_id, transaction_type, and status. Results are ordered by creation date descending.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "user_id", "type": "str", "required": false }, { "name": "order_id", "type": "str", "required": false }, { "name": "transaction_type", "type": "TransactionTypeEnum", "required": false }, { "name": "status", "type": "TransactionStatusEnum", "required": false } ], "response": { "schema_name": "TransactionResponse", "fields": [ { "name": "user_id", "type": "str", "required": true }, { "name": "order_id", "type": "str", "required": false, "nullable": true }, { "name": "transaction_type", "type": "TransactionTypeEnum", "required": true, "enum_values": [ "SALE", "PURCHASE", "REFUND", "PAYOUT", "PLATFORM_FEE", "ADJUSTMENT" ] }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "currency", "type": "str", "required": false, "default": "USD" }, { "name": "status", "type": "TransactionStatusEnum", "required": true, "enum_values": [ "PENDING", "COMPLETED", "FAILED", "CANCELLED" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "reference_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/{id}", "summary": "Update Transaction", "description": "Updates an existing transaction. Only provided fields are updated; unset fields remain unchanged. Validates that any new user_id or order_id references exist. Returns 404 if transaction not found, 400 if referenced entities are invalid.", "path_params": [ { "name": "id", "type": "str" } ], "request_body": { "schema_name": "TransactionUpdate", "fields": [ { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "order_id", "type": "str", "required": false, "nullable": true }, { "name": "transaction_type", "type": "TransactionTypeEnum", "required": false, "nullable": true, "enum_values": [ "SALE", "PURCHASE", "REFUND", "PAYOUT", "PLATFORM_FEE", "ADJUSTMENT" ] }, { "name": "amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "currency", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "TransactionStatusEnum", "required": false, "nullable": true, "enum_values": [ "PENDING", "COMPLETED", "FAILED", "CANCELLED" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "reference_id", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "TransactionResponse", "fields": [ { "name": "user_id", "type": "str", "required": true }, { "name": "order_id", "type": "str", "required": false, "nullable": true }, { "name": "transaction_type", "type": "TransactionTypeEnum", "required": true, "enum_values": [ "SALE", "PURCHASE", "REFUND", "PAYOUT", "PLATFORM_FEE", "ADJUSTMENT" ] }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "currency", "type": "str", "required": false, "default": "USD" }, { "name": "status", "type": "TransactionStatusEnum", "required": true, "enum_values": [ "PENDING", "COMPLETED", "FAILED", "CANCELLED" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "reference_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{id}", "summary": "Delete Transaction", "description": "Permanently deletes a transaction record. Returns 404 if the transaction does not exist.", "path_params": [ { "name": "id", "type": "str" } ], "status_code": 200 } ] }, { "name": "Notifications", "prefix": "/notifications", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Notification", "description": "Creates a new notification for a user. Validates that the user exists before creating the notification.", "request_body": { "schema_name": "NotificationCreate", "fields": [ { "name": "user_id", "type": "str", "required": false }, { "name": "notification_type", "type": "str", "required": false }, { "name": "title", "type": "str", "required": false }, { "name": "message", "type": "str", "required": false }, { "name": "action_url", "type": "str", "required": false, "nullable": true }, { "name": "related_entity_type", "type": "str", "required": false, "nullable": true }, { "name": "related_entity_id", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "NotificationResponse", "fields": [ { "name": "user_id", "type": "str", "required": false }, { "name": "notification_type", "type": "str", "required": false }, { "name": "title", "type": "str", "required": false }, { "name": "message", "type": "str", "required": false }, { "name": "action_url", "type": "str", "required": false, "nullable": true }, { "name": "related_entity_type", "type": "str", "required": false, "nullable": true }, { "name": "related_entity_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "is_read", "type": "bool", "required": true }, { "name": "read_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/", "summary": "List Notifications", "description": "Returns a paginated list of notifications. Supports filtering by user_id, is_read status, and notification_type. Results are ordered by creation date descending.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "user_id", "type": "str", "required": false }, { "name": "is_read", "type": "bool", "required": false }, { "name": "notification_type", "type": "str", "required": false } ], "response": { "schema_name": "NotificationResponse", "fields": [ { "name": "user_id", "type": "str", "required": false }, { "name": "notification_type", "type": "str", "required": false }, { "name": "title", "type": "str", "required": false }, { "name": "message", "type": "str", "required": false }, { "name": "action_url", "type": "str", "required": false, "nullable": true }, { "name": "related_entity_type", "type": "str", "required": false, "nullable": true }, { "name": "related_entity_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "is_read", "type": "bool", "required": true }, { "name": "read_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/{notification_id}", "summary": "Get Notification", "description": "Retrieves a single notification by ID. Returns 404 if the notification does not exist.", "path_params": [ { "name": "notification_id", "type": "str" } ], "response": { "schema_name": "NotificationResponse", "fields": [ { "name": "user_id", "type": "str", "required": false }, { "name": "notification_type", "type": "str", "required": false }, { "name": "title", "type": "str", "required": false }, { "name": "message", "type": "str", "required": false }, { "name": "action_url", "type": "str", "required": false, "nullable": true }, { "name": "related_entity_type", "type": "str", "required": false, "nullable": true }, { "name": "related_entity_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "is_read", "type": "bool", "required": true }, { "name": "read_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{notification_id}", "summary": "Update Notification", "description": "Updates an existing notification. All fields are optional. Returns 404 if the notification does not exist.", "path_params": [ { "name": "notification_id", "type": "str" } ], "request_body": { "schema_name": "NotificationUpdate", "fields": [ { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "notification_type", "type": "str", "required": false, "nullable": true }, { "name": "title", "type": "str", "required": false, "nullable": true }, { "name": "message", "type": "str", "required": false, "nullable": true }, { "name": "is_read", "type": "bool", "required": false, "nullable": true }, { "name": "read_at", "type": "datetime", "required": false, "nullable": true }, { "name": "action_url", "type": "str", "required": false, "nullable": true }, { "name": "related_entity_type", "type": "str", "required": false, "nullable": true }, { "name": "related_entity_id", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "NotificationResponse", "fields": [ { "name": "user_id", "type": "str", "required": false }, { "name": "notification_type", "type": "str", "required": false }, { "name": "title", "type": "str", "required": false }, { "name": "message", "type": "str", "required": false }, { "name": "action_url", "type": "str", "required": false, "nullable": true }, { "name": "related_entity_type", "type": "str", "required": false, "nullable": true }, { "name": "related_entity_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "is_read", "type": "bool", "required": true }, { "name": "read_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{notification_id}", "summary": "Delete Notification", "description": "Deletes a notification by ID. Returns 404 if the notification does not exist.", "path_params": [ { "name": "notification_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/{notification_id}/mark-read", "summary": "Mark Notification As Read", "description": "Marks a single notification as read and sets the read_at timestamp. Returns 404 if the notification does not exist.", "path_params": [ { "name": "notification_id", "type": "str" } ], "response": { "schema_name": "NotificationResponse", "fields": [ { "name": "user_id", "type": "str", "required": false }, { "name": "notification_type", "type": "str", "required": false }, { "name": "title", "type": "str", "required": false }, { "name": "message", "type": "str", "required": false }, { "name": "action_url", "type": "str", "required": false, "nullable": true }, { "name": "related_entity_type", "type": "str", "required": false, "nullable": true }, { "name": "related_entity_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "is_read", "type": "bool", "required": true }, { "name": "read_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/users/{user_id}/mark-all-read", "summary": "Mark All Notifications As Read", "description": "Marks all unread notifications for a specific user as read. Returns the count of notifications marked as read. Returns 400 if the user does not exist.", "path_params": [ { "name": "user_id", "type": "str" } ], "status_code": 200 }, { "method": "GET", "path": "/users/{user_id}/unread-count", "summary": "Get Unread Notification Count", "description": "Returns the count of unread notifications for a specific user. Returns 400 if the user does not exist.", "path_params": [ { "name": "user_id", "type": "str" } ], "status_code": 200 } ] }, { "name": "Reports", "prefix": "/reports", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Report", "description": "Creates a new report for a user or listing. Either reported_user_id or reported_listing_id must be provided. Returns 404 if the reporter, reported user, or reported listing does not exist. Returns 400 if neither target is provided.", "request_body": { "schema_name": "ReportCreate", "fields": [ { "name": "reporter_id", "type": "str", "required": true }, { "name": "reported_user_id", "type": "str", "required": false, "nullable": true }, { "name": "reported_listing_id", "type": "str", "required": false, "nullable": true }, { "name": "report_type", "type": "ReportType", "required": true, "enum_values": [ "FRAUDULENT_LISTING", "COUNTERFEIT", "INAPPROPRIATE_CONTENT", "HARASSMENT", "SPAM", "OTHER" ] }, { "name": "description", "type": "str", "required": true } ] }, "response": { "schema_name": "ReportResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "reporter_id", "type": "str", "required": true }, { "name": "reported_user_id", "type": "str", "required": false, "nullable": true }, { "name": "reported_listing_id", "type": "str", "required": false, "nullable": true }, { "name": "report_type", "type": "ReportType", "required": true, "enum_values": [ "FRAUDULENT_LISTING", "COUNTERFEIT", "INAPPROPRIATE_CONTENT", "HARASSMENT", "SPAM", "OTHER" ] }, { "name": "description", "type": "str", "required": true }, { "name": "status", "type": "ReportStatus", "required": true, "enum_values": [ "PENDING", "UNDER_REVIEW", "RESOLVED", "DISMISSED" ] }, { "name": "reviewed_by_id", "type": "str", "required": false, "nullable": true }, { "name": "resolution_notes", "type": "str", "required": false, "nullable": true }, { "name": "resolved_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/{id}", "summary": "Get Report", "description": "Returns a single report by ID. Returns 404 if the report does not exist.", "path_params": [ { "name": "id", "type": "str" } ], "response": { "schema_name": "ReportResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "reporter_id", "type": "str", "required": true }, { "name": "reported_user_id", "type": "str", "required": false, "nullable": true }, { "name": "reported_listing_id", "type": "str", "required": false, "nullable": true }, { "name": "report_type", "type": "ReportType", "required": true, "enum_values": [ "FRAUDULENT_LISTING", "COUNTERFEIT", "INAPPROPRIATE_CONTENT", "HARASSMENT", "SPAM", "OTHER" ] }, { "name": "description", "type": "str", "required": true }, { "name": "status", "type": "ReportStatus", "required": true, "enum_values": [ "PENDING", "UNDER_REVIEW", "RESOLVED", "DISMISSED" ] }, { "name": "reviewed_by_id", "type": "str", "required": false, "nullable": true }, { "name": "resolution_notes", "type": "str", "required": false, "nullable": true }, { "name": "resolved_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/", "summary": "List Reports", "description": "Returns a paginated list of reports. Supports optional filters for reporter_id, reported_user_id, reported_listing_id, status, and report_type.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "reporter_id", "type": "str", "required": false }, { "name": "reported_user_id", "type": "str", "required": false }, { "name": "reported_listing_id", "type": "str", "required": false }, { "name": "status", "type": "ReportStatus", "required": false }, { "name": "report_type", "type": "str", "required": false } ], "response": { "schema_name": "ReportResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "reporter_id", "type": "str", "required": true }, { "name": "reported_user_id", "type": "str", "required": false, "nullable": true }, { "name": "reported_listing_id", "type": "str", "required": false, "nullable": true }, { "name": "report_type", "type": "ReportType", "required": true, "enum_values": [ "FRAUDULENT_LISTING", "COUNTERFEIT", "INAPPROPRIATE_CONTENT", "HARASSMENT", "SPAM", "OTHER" ] }, { "name": "description", "type": "str", "required": true }, { "name": "status", "type": "ReportStatus", "required": true, "enum_values": [ "PENDING", "UNDER_REVIEW", "RESOLVED", "DISMISSED" ] }, { "name": "reviewed_by_id", "type": "str", "required": false, "nullable": true }, { "name": "resolution_notes", "type": "str", "required": false, "nullable": true }, { "name": "resolved_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/{id}", "summary": "Update Report", "description": "Updates an existing report. Returns 404 if the report, reported user, reported listing, or reviewer does not exist.", "path_params": [ { "name": "id", "type": "str" } ], "request_body": { "schema_name": "ReportUpdate", "fields": [ { "name": "reporter_id", "type": "str", "required": false, "nullable": true }, { "name": "reported_user_id", "type": "str", "required": false, "nullable": true }, { "name": "reported_listing_id", "type": "str", "required": false, "nullable": true }, { "name": "report_type", "type": "ReportType", "required": false, "nullable": true, "enum_values": [ "FRAUDULENT_LISTING", "COUNTERFEIT", "INAPPROPRIATE_CONTENT", "HARASSMENT", "SPAM", "OTHER" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "ReportStatus", "required": false, "nullable": true, "enum_values": [ "PENDING", "UNDER_REVIEW", "RESOLVED", "DISMISSED" ] }, { "name": "reviewed_by_id", "type": "str", "required": false, "nullable": true }, { "name": "resolution_notes", "type": "str", "required": false, "nullable": true }, { "name": "resolved_at", "type": "datetime", "required": false, "nullable": true } ] }, "response": { "schema_name": "ReportResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "reporter_id", "type": "str", "required": true }, { "name": "reported_user_id", "type": "str", "required": false, "nullable": true }, { "name": "reported_listing_id", "type": "str", "required": false, "nullable": true }, { "name": "report_type", "type": "ReportType", "required": true, "enum_values": [ "FRAUDULENT_LISTING", "COUNTERFEIT", "INAPPROPRIATE_CONTENT", "HARASSMENT", "SPAM", "OTHER" ] }, { "name": "description", "type": "str", "required": true }, { "name": "status", "type": "ReportStatus", "required": true, "enum_values": [ "PENDING", "UNDER_REVIEW", "RESOLVED", "DISMISSED" ] }, { "name": "reviewed_by_id", "type": "str", "required": false, "nullable": true }, { "name": "resolution_notes", "type": "str", "required": false, "nullable": true }, { "name": "resolved_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{id}", "summary": "Delete Report", "description": "Deletes a report by ID. Returns 404 if the report does not exist.", "path_params": [ { "name": "id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/{id}/review", "summary": "Review Report", "description": "Allows a moderator or admin to review a report and mark it as resolved or dismissed. Returns 404 if the report or reviewer does not exist. Returns 400 if the report is not in a reviewable state or if the new status is invalid.", "path_params": [ { "name": "id", "type": "str" } ], "request_body": { "schema_name": "ReportStatus", "fields": [] }, "response": { "schema_name": "ReportResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "reporter_id", "type": "str", "required": true }, { "name": "reported_user_id", "type": "str", "required": false, "nullable": true }, { "name": "reported_listing_id", "type": "str", "required": false, "nullable": true }, { "name": "report_type", "type": "ReportType", "required": true, "enum_values": [ "FRAUDULENT_LISTING", "COUNTERFEIT", "INAPPROPRIATE_CONTENT", "HARASSMENT", "SPAM", "OTHER" ] }, { "name": "description", "type": "str", "required": true }, { "name": "status", "type": "ReportStatus", "required": true, "enum_values": [ "PENDING", "UNDER_REVIEW", "RESOLVED", "DISMISSED" ] }, { "name": "reviewed_by_id", "type": "str", "required": false, "nullable": true }, { "name": "resolution_notes", "type": "str", "required": false, "nullable": true }, { "name": "resolved_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{id}/details", "summary": "Get Report Details", "description": "Returns detailed information about a report including reporter, reported user, reported listing, and reviewer information. Returns 404 if the report does not exist.", "path_params": [ { "name": "id", "type": "str" } ], "response": { "schema_name": "ReportDetailResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "reporter_id", "type": "str", "required": true }, { "name": "reported_user_id", "type": "str", "required": false, "nullable": true }, { "name": "reported_listing_id", "type": "str", "required": false, "nullable": true }, { "name": "report_type", "type": "ReportType", "required": true, "enum_values": [ "FRAUDULENT_LISTING", "COUNTERFEIT", "INAPPROPRIATE_CONTENT", "HARASSMENT", "SPAM", "OTHER" ] }, { "name": "description", "type": "str", "required": true }, { "name": "status", "type": "ReportStatus", "required": true, "enum_values": [ "PENDING", "UNDER_REVIEW", "RESOLVED", "DISMISSED" ] }, { "name": "reviewed_by_id", "type": "str", "required": false, "nullable": true }, { "name": "resolution_notes", "type": "str", "required": false, "nullable": true }, { "name": "resolved_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "reporter", "type": "dict", "required": false, "nullable": true }, { "name": "reported_user", "type": "dict", "required": false, "nullable": true }, { "name": "reported_listing", "type": "dict", "required": false, "nullable": true }, { "name": "reviewed_by", "type": "dict", "required": false, "nullable": true } ], "is_list": false }, "status_code": 200 } ] }, { "name": "Promotions", "prefix": "/promotions", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Promotion", "description": "Creates a new promotion with discount rules and validity period. Returns 409 if the promotion code already exists. Validates that expiration date is after start date and required discount fields are present based on promotion type.", "request_body": { "schema_name": "PromotionCreate", "fields": [ { "name": "code", "type": "str", "required": false, "nullable": true }, { "name": "name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "promotion_type", "type": "PromotionType", "required": true, "enum_values": [ "PERCENTAGE_DISCOUNT", "FIXED_DISCOUNT", "FREE_SHIPPING", "FEATURED_LISTING" ] }, { "name": "discount_percentage", "type": "Decimal", "required": false, "nullable": true }, { "name": "discount_amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "minimum_purchase_amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "max_uses", "type": "int", "required": false, "nullable": true }, { "name": "starts_at", "type": "datetime", "required": true }, { "name": "expires_at", "type": "datetime", "required": true }, { "name": "is_active", "type": "bool", "required": false, "default": true } ] }, "response": { "schema_name": "PromotionResponse", "fields": [ { "name": "code", "type": "str", "required": false, "nullable": true }, { "name": "name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "promotion_type", "type": "PromotionType", "required": true, "enum_values": [ "PERCENTAGE_DISCOUNT", "FIXED_DISCOUNT", "FREE_SHIPPING", "FEATURED_LISTING" ] }, { "name": "discount_percentage", "type": "Decimal", "required": false, "nullable": true }, { "name": "discount_amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "minimum_purchase_amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "max_uses", "type": "int", "required": false, "nullable": true }, { "name": "starts_at", "type": "datetime", "required": true }, { "name": "expires_at", "type": "datetime", "required": true }, { "name": "is_active", "type": "bool", "required": false, "default": true }, { "name": "id", "type": "str", "required": true }, { "name": "current_uses", "type": "int", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/", "summary": "List Promotions", "description": "Returns a paginated list of promotions. Supports optional filters for active status, promotion type, and search by name or code.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "is_active", "type": "bool", "required": false }, { "name": "promotion_type", "type": "str", "required": false }, { "name": "search", "type": "str", "required": false } ], "response": { "schema_name": "PromotionResponse", "fields": [ { "name": "code", "type": "str", "required": false, "nullable": true }, { "name": "name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "promotion_type", "type": "PromotionType", "required": true, "enum_values": [ "PERCENTAGE_DISCOUNT", "FIXED_DISCOUNT", "FREE_SHIPPING", "FEATURED_LISTING" ] }, { "name": "discount_percentage", "type": "Decimal", "required": false, "nullable": true }, { "name": "discount_amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "minimum_purchase_amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "max_uses", "type": "int", "required": false, "nullable": true }, { "name": "starts_at", "type": "datetime", "required": true }, { "name": "expires_at", "type": "datetime", "required": true }, { "name": "is_active", "type": "bool", "required": false, "default": true }, { "name": "id", "type": "str", "required": true }, { "name": "current_uses", "type": "int", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/{id}", "summary": "Get Promotion By ID", "description": "Returns a single promotion by ID. Returns 404 if the promotion does not exist.", "path_params": [ { "name": "id", "type": "str" } ], "response": { "schema_name": "PromotionResponse", "fields": [ { "name": "code", "type": "str", "required": false, "nullable": true }, { "name": "name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "promotion_type", "type": "PromotionType", "required": true, "enum_values": [ "PERCENTAGE_DISCOUNT", "FIXED_DISCOUNT", "FREE_SHIPPING", "FEATURED_LISTING" ] }, { "name": "discount_percentage", "type": "Decimal", "required": false, "nullable": true }, { "name": "discount_amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "minimum_purchase_amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "max_uses", "type": "int", "required": false, "nullable": true }, { "name": "starts_at", "type": "datetime", "required": true }, { "name": "expires_at", "type": "datetime", "required": true }, { "name": "is_active", "type": "bool", "required": false, "default": true }, { "name": "id", "type": "str", "required": true }, { "name": "current_uses", "type": "int", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/code/{code}", "summary": "Get Promotion By Code", "description": "Returns a single promotion by its unique code. Returns 404 if the promotion code does not exist.", "path_params": [ { "name": "code", "type": "str" } ], "response": { "schema_name": "PromotionResponse", "fields": [ { "name": "code", "type": "str", "required": false, "nullable": true }, { "name": "name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "promotion_type", "type": "PromotionType", "required": true, "enum_values": [ "PERCENTAGE_DISCOUNT", "FIXED_DISCOUNT", "FREE_SHIPPING", "FEATURED_LISTING" ] }, { "name": "discount_percentage", "type": "Decimal", "required": false, "nullable": true }, { "name": "discount_amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "minimum_purchase_amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "max_uses", "type": "int", "required": false, "nullable": true }, { "name": "starts_at", "type": "datetime", "required": true }, { "name": "expires_at", "type": "datetime", "required": true }, { "name": "is_active", "type": "bool", "required": false, "default": true }, { "name": "id", "type": "str", "required": true }, { "name": "current_uses", "type": "int", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{id}", "summary": "Update Promotion", "description": "Updates an existing promotion. Returns 404 if the promotion does not exist. Returns 409 if the new code conflicts with an existing promotion. Validates date ranges if start or expiration dates are updated.", "path_params": [ { "name": "id", "type": "str" } ], "request_body": { "schema_name": "PromotionUpdate", "fields": [ { "name": "code", "type": "str", "required": false, "nullable": true }, { "name": "name", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "promotion_type", "type": "PromotionType", "required": false, "nullable": true, "enum_values": [ "PERCENTAGE_DISCOUNT", "FIXED_DISCOUNT", "FREE_SHIPPING", "FEATURED_LISTING" ] }, { "name": "discount_percentage", "type": "Decimal", "required": false, "nullable": true }, { "name": "discount_amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "minimum_purchase_amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "max_uses", "type": "int", "required": false, "nullable": true }, { "name": "current_uses", "type": "int", "required": false, "nullable": true }, { "name": "starts_at", "type": "datetime", "required": false, "nullable": true }, { "name": "expires_at", "type": "datetime", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "nullable": true } ] }, "response": { "schema_name": "PromotionResponse", "fields": [ { "name": "code", "type": "str", "required": false, "nullable": true }, { "name": "name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "promotion_type", "type": "PromotionType", "required": true, "enum_values": [ "PERCENTAGE_DISCOUNT", "FIXED_DISCOUNT", "FREE_SHIPPING", "FEATURED_LISTING" ] }, { "name": "discount_percentage", "type": "Decimal", "required": false, "nullable": true }, { "name": "discount_amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "minimum_purchase_amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "max_uses", "type": "int", "required": false, "nullable": true }, { "name": "starts_at", "type": "datetime", "required": true }, { "name": "expires_at", "type": "datetime", "required": true }, { "name": "is_active", "type": "bool", "required": false, "default": true }, { "name": "id", "type": "str", "required": true }, { "name": "current_uses", "type": "int", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{id}", "summary": "Delete Promotion", "description": "Deletes a promotion by ID. Returns 404 if the promotion does not exist. Cascades to delete all associated promotion usages.", "path_params": [ { "name": "id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/validate", "summary": "Validate Promotion Code", "description": "Validates a promotion code for a specific user and order total. Checks if the promotion is active, within validity period, has not exceeded usage limits, and meets minimum purchase requirements. Returns 400 if validation fails, 404 if promotion not found.", "query_params": [ { "name": "code", "type": "str", "required": false, "default": null }, { "name": "user_id", "type": "str", "required": false, "default": null }, { "name": "order_total", "type": "float", "required": false, "default": null } ], "response": { "schema_name": "PromotionResponse", "fields": [ { "name": "code", "type": "str", "required": false, "nullable": true }, { "name": "name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "promotion_type", "type": "PromotionType", "required": true, "enum_values": [ "PERCENTAGE_DISCOUNT", "FIXED_DISCOUNT", "FREE_SHIPPING", "FEATURED_LISTING" ] }, { "name": "discount_percentage", "type": "Decimal", "required": false, "nullable": true }, { "name": "discount_amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "minimum_purchase_amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "max_uses", "type": "int", "required": false, "nullable": true }, { "name": "starts_at", "type": "datetime", "required": true }, { "name": "expires_at", "type": "datetime", "required": true }, { "name": "is_active", "type": "bool", "required": false, "default": true }, { "name": "id", "type": "str", "required": true }, { "name": "current_uses", "type": "int", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/usages", "summary": "Create Promotion Usage", "description": "Records a promotion usage for a specific order. Increments the promotion's current usage count. Returns 404 if promotion, user, or order does not exist.", "request_body": { "schema_name": "PromotionusageCreate", "fields": [ { "name": "promotion_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "order_id", "type": "str", "required": true }, { "name": "discount_applied", "type": "Decimal", "required": true } ] }, "response": { "schema_name": "PromotionusageResponse", "fields": [ { "name": "promotion_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "order_id", "type": "str", "required": true }, { "name": "discount_applied", "type": "Decimal", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/usages", "summary": "List Promotion Usages", "description": "Returns a paginated list of promotion usages. Supports optional filters for promotion ID, user ID, and order ID.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "promotion_id", "type": "str", "required": false }, { "name": "user_id", "type": "str", "required": false }, { "name": "order_id", "type": "str", "required": false } ], "response": { "schema_name": "PromotionusageResponse", "fields": [ { "name": "promotion_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "order_id", "type": "str", "required": true }, { "name": "discount_applied", "type": "Decimal", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/usages/{id}", "summary": "Get Promotion Usage By ID", "description": "Returns a single promotion usage record by ID. Returns 404 if the usage record does not exist.", "path_params": [ { "name": "id", "type": "str" } ], "response": { "schema_name": "PromotionusageResponse", "fields": [ { "name": "promotion_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "order_id", "type": "str", "required": true }, { "name": "discount_applied", "type": "Decimal", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/usages/{id}", "summary": "Update Promotion Usage", "description": "Updates an existing promotion usage record. Returns 404 if the usage record, promotion, user, or order does not exist.", "path_params": [ { "name": "id", "type": "str" } ], "request_body": { "schema_name": "PromotionusageUpdate", "fields": [ { "name": "promotion_id", "type": "str", "required": false, "nullable": true }, { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "order_id", "type": "str", "required": false, "nullable": true }, { "name": "discount_applied", "type": "Decimal", "required": false, "nullable": true } ] }, "response": { "schema_name": "PromotionusageResponse", "fields": [ { "name": "promotion_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "order_id", "type": "str", "required": true }, { "name": "discount_applied", "type": "Decimal", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/usages/{id}", "summary": "Delete Promotion Usage", "description": "Deletes a promotion usage record by ID. Returns 404 if the usage record does not exist.", "path_params": [ { "name": "id", "type": "str" } ], "status_code": 200 } ] }, { "name": "Platform Settings", "prefix": "/platform-settings", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Platform Setting", "description": "Creates a new platform setting with a unique key. Returns 409 if the setting key already exists.", "request_body": { "schema_name": "PlatformsettingCreate", "fields": [ { "name": "setting_key", "type": "str", "required": false }, { "name": "setting_value", "type": "str", "required": false }, { "name": "setting_type", "type": "SettingType", "required": true, "enum_values": [ "STRING", "NUMBER", "BOOLEAN", "JSON" ] }, { "name": "description", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "PlatformsettingResponse", "fields": [ { "name": "setting_key", "type": "str", "required": false }, { "name": "setting_value", "type": "str", "required": false }, { "name": "setting_type", "type": "SettingType", "required": true, "enum_values": [ "STRING", "NUMBER", "BOOLEAN", "JSON" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/", "summary": "List Platform Settings", "description": "Returns a paginated list of platform settings. Supports optional filtering by setting type and search term on key and description fields.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "setting_type", "type": "SettingType", "required": false }, { "name": "search", "type": "str", "required": false } ], "response": { "schema_name": "PlatformsettingResponse", "fields": [ { "name": "setting_key", "type": "str", "required": false }, { "name": "setting_value", "type": "str", "required": false }, { "name": "setting_type", "type": "SettingType", "required": true, "enum_values": [ "STRING", "NUMBER", "BOOLEAN", "JSON" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/by-key/{setting_key}", "summary": "Get Platform Setting By Key", "description": "Retrieves a platform setting by its unique key. Returns 404 if the setting key is not found.", "path_params": [ { "name": "setting_key", "type": "str" } ], "response": { "schema_name": "PlatformsettingResponse", "fields": [ { "name": "setting_key", "type": "str", "required": false }, { "name": "setting_value", "type": "str", "required": false }, { "name": "setting_type", "type": "SettingType", "required": true, "enum_values": [ "STRING", "NUMBER", "BOOLEAN", "JSON" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{id}", "summary": "Get Platform Setting", "description": "Retrieves a platform setting by its ID. Returns 404 if the setting is not found.", "path_params": [ { "name": "id", "type": "str" } ], "response": { "schema_name": "PlatformsettingResponse", "fields": [ { "name": "setting_key", "type": "str", "required": false }, { "name": "setting_value", "type": "str", "required": false }, { "name": "setting_type", "type": "SettingType", "required": true, "enum_values": [ "STRING", "NUMBER", "BOOLEAN", "JSON" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{id}", "summary": "Update Platform Setting", "description": "Updates an existing platform setting. Only provided fields are updated. Returns 404 if the setting is not found, 409 if the new key conflicts with an existing setting.", "path_params": [ { "name": "id", "type": "str" } ], "request_body": { "schema_name": "PlatformsettingUpdate", "fields": [ { "name": "setting_key", "type": "str", "required": false, "nullable": true }, { "name": "setting_value", "type": "str", "required": false, "nullable": true }, { "name": "setting_type", "type": "SettingType", "required": false, "nullable": true, "enum_values": [ "STRING", "NUMBER", "BOOLEAN", "JSON" ] }, { "name": "description", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "PlatformsettingResponse", "fields": [ { "name": "setting_key", "type": "str", "required": false }, { "name": "setting_value", "type": "str", "required": false }, { "name": "setting_type", "type": "SettingType", "required": true, "enum_values": [ "STRING", "NUMBER", "BOOLEAN", "JSON" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{id}", "summary": "Delete Platform Setting", "description": "Deletes a platform setting by its ID. Returns 404 if the setting is not found.", "path_params": [ { "name": "id", "type": "str" } ], "status_code": 200 } ] } ], "enums": { "UserRole": [ "GUEST", "BUYER", "SELLER", "MODERATOR", "ADMIN" ], "AddressType": [ "SHIPPING", "BILLING" ], "CardType": [ "POKEMON", "TRAINER", "ENERGY" ], "ListingStatus": [ "DRAFT", "ACTIVE", "SOLD", "RESERVED", "INACTIVE", "REMOVED" ], "CardCondition": [ "MINT", "NEAR_MINT", "LIGHTLY_PLAYED", "MODERATELY_PLAYED", "HEAVILY_PLAYED", "DAMAGED" ], "OrderStatus": [ "PENDING", "PAID", "PROCESSING", "SHIPPED", "DELIVERED", "CANCELLED", "REFUNDED", "DISPUTED" ], "PaymentMethod": [ "CREDIT_CARD", "DEBIT_CARD", "PAYPAL", "STRIPE", "BANK_TRANSFER" ], "PaymentStatus": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "REFUNDED", "CANCELLED" ], "ShipmentStatus": [ "PENDING", "LABEL_CREATED", "IN_TRANSIT", "OUT_FOR_DELIVERY", "DELIVERED", "FAILED", "RETURNED" ], "OfferStatus": [ "PENDING", "ACCEPTED", "REJECTED", "CANCELLED", "EXPIRED" ], "DisputeReason": [ "ITEM_NOT_RECEIVED", "ITEM_NOT_AS_DESCRIBED", "DAMAGED_ITEM", "COUNTERFEIT", "OTHER" ], "DisputeStatus": [ "OPEN", "UNDER_REVIEW", "RESOLVED", "CLOSED", "ESCALATED" ], "TransactionTypeEnum": [ "SALE", "PURCHASE", "REFUND", "PAYOUT", "PLATFORM_FEE", "ADJUSTMENT" ], "TransactionStatusEnum": [ "PENDING", "COMPLETED", "FAILED", "CANCELLED" ], "NotificationType": [ "ORDER", "MESSAGE", "OFFER", "REVIEW", "SHIPMENT", "PAYMENT", "SYSTEM", "PROMOTION" ], "ReportType": [ "FRAUDULENT_LISTING", "COUNTERFEIT", "INAPPROPRIATE_CONTENT", "HARASSMENT", "SPAM", "OTHER" ], "ReportStatus": [ "PENDING", "UNDER_REVIEW", "RESOLVED", "DISMISSED" ], "PromotionType": [ "PERCENTAGE_DISCOUNT", "FIXED_DISCOUNT", "FREE_SHIPPING", "FEATURED_LISTING" ], "SettingType": [ "STRING", "NUMBER", "BOOLEAN", "JSON" ] } }