{ "openapi": "3.1.0", "info": { "title": "Whatnot Seller API", "description": "REST API for Whatnot sellers to manage listings, orders, and products.", "contact": { "name": "Whatnot Seller API Support", "url": "https://whatnot.com/" }, "license": { "name": "Proprietary" }, "version": "2.0.0" }, "servers": [ { "url": "https://api.whatnot.com/seller-api/rest/v2" } ], "paths": { "/": { "get": { "summary": "Health check", "description": "Returns the current status of the Seller API v2.", "operationId": "root__get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RootResponse" } } } }, "503": { "description": "Service is unavailable (killswitch disabled)." } } } }, "/analytics/shows/{show_id}": { "get": { "tags": [ "Analytics" ], "summary": "Get show analytics", "description": "Retrieve the analytics for one show owned by the authenticated seller. A show without final analytics still returns 200 with null metrics and a `calculation_status` saying why: WILL_NOT_BE_CALCULATED if the show was cancelled, is private or is a rehearsal, NOT_ENDED if it has not ended, PENDING if it ended and the metrics are still being calculated. Requires read:reports.", "operationId": "get_show_analytics_analytics_shows__show_id__get", "parameters": [ { "name": "show_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Show Id" }, "description": "The show's ID." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShowAnalytics" } } } }, "404": { "description": "No such show, or it belongs to another seller." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/inventory/adjust": { "post": { "tags": [ "Inventory" ], "summary": "Adjust inventory", "description": "Change variants' available quantity by a delta.", "operationId": "adjust_inventory_inventory_adjust_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustInventoryLevelsRequest" } } }, "required": true }, "responses": { "207": { "description": "Per-item results, in input order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryBatchResult" } } } }, "403": { "description": "Inventory writes are not enabled for this seller." }, "422": { "description": "The request failed validation." } } } }, "/inventory/set": { "post": { "tags": [ "Inventory" ], "summary": "Set inventory", "description": "Set variants' available quantity to an absolute value.", "operationId": "set_inventory_inventory_set_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetInventoryLevelsRequest" } } }, "required": true }, "responses": { "207": { "description": "Per-item results, in input order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryBatchResult" } } } }, "403": { "description": "Inventory writes are not enabled for this seller." }, "422": { "description": "The request failed validation." } } } }, "/merchandising/products/{product_id}": { "post": { "tags": [ "Merchandising" ], "summary": "Update a product's merchandising", "description": "Set a product's sale format, the shows it appears in, and whether it is reserved for live, in one call. Omitted fields are left unchanged. A buy-it-now product that is not reserved for live is listed on the seller's profile shop. A draft product is published by the first call that sets the sale format, sets reserve_for_live, or adds it to shows. Publishing needs every variant priced, inventory, a description, an image, a value for each required category attribute and, in markets that require them, a dimension profile with dimensions. Anything missing is returned together in errors. Requires write:merchandising.", "operationId": "merchandise_product_endpoint_merchandising_products__product_id__post", "parameters": [ { "name": "product_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "title": "Product Id" }, "description": "The product's ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchandiseProductRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchandiseProductResponse" } } } }, "403": { "description": "The seller is not approved to manage inventory." }, "404": { "description": "Product not found." }, "422": { "description": "The merchandising change could not be applied. When a product isn't ready to publish, errors lists each field to fix." } } }, "get": { "tags": [ "Merchandising" ], "summary": "Get a product's merchandising", "description": "Get how and where a product is currently being sold: its sale format, whether it is reserved for live, and whether it is assigned to any upcoming or live show. A buy-it-now product that is not reserved for live is listed for sale on the seller's profile shop. List the assigned shows at GET /merchandising/products/{product_id}/shows. Requires read:merchandising.", "operationId": "seller_api_v2_get_product_merchandising_merchandising_products__product_id__get", "parameters": [ { "name": "product_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "title": "Product Id" }, "description": "The product's ID." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductMerchandising" } } } }, "404": { "description": "Product not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/merchandising/products/{product_id}/shows": { "get": { "tags": [ "Merchandising" ], "summary": "List a product's shows", "description": "List the upcoming or live shows the product is assigned to, by scheduled start time, latest first by default; set reverse=false for earliest first. Ended and cancelled shows are not listed. Only the product's 250 most recent show assignments are considered. Requires read:merchandising and read:shows.", "operationId": "seller_api_v2_list_product_shows_merchandising_products__product_id__shows_get", "parameters": [ { "name": "product_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "title": "Product Id" }, "description": "The product's ID." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Maximum results per page.", "default": 10, "title": "Limit" }, "description": "Maximum results per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "description": "Cursor from the previous page.", "title": "Cursor" }, "description": "Cursor from the previous page." }, { "name": "reverse", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Return descending order when true; ascending when false.", "default": true, "title": "Reverse" }, "description": "Return descending order when true; ascending when false." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageResponse_Show_" } } } }, "404": { "description": "Product not found." }, "422": { "description": "Invalid limit, cursor, or reverse flag." } } } }, "/orders/{order_id}": { "get": { "tags": [ "Orders" ], "summary": "Get an order", "description": "Retrieve an order sold by the authenticated seller. Requires read:orders.", "operationId": "get_order_orders__order_id__get", "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "title": "Order Id" }, "description": "The order's ID." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "404": { "description": "Order not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/orders/{order_id}/items/{item_id}": { "get": { "tags": [ "Orders" ], "summary": "Get an order item", "description": "Retrieve an item on an order sold by the authenticated seller. Requires read:orders.", "operationId": "get_order_item_orders__order_id__items__item_id__get", "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "title": "Order Id" }, "description": "The order's ID." }, { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "title": "Item Id" }, "description": "The order item's ID." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderItem" } } } }, "404": { "description": "Order item not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/orders": { "get": { "tags": [ "Orders" ], "summary": "List orders", "description": "List orders newest first by default; set reverse=false for oldest first. Offers that were never accepted aren't listed. Requires read:orders.", "operationId": "list_orders_orders_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Maximum results per page.", "default": 10, "title": "Limit" }, "description": "Maximum results per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "description": "Cursor from the previous page.", "title": "Cursor" }, "description": "Cursor from the previous page." }, { "name": "reverse", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Return descending order when true; ascending when false.", "default": true, "title": "Reverse" }, "description": "Return descending order when true; ascending when false." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageResponse_Order_" } } } }, "422": { "description": "Invalid limit, cursor, or reverse flag." } } } }, "/orders/{order_id}/items": { "get": { "tags": [ "Orders" ], "summary": "List order items", "description": "List an order's items newest first by default; set reverse=false for oldest first. Requires read:orders.", "operationId": "list_order_items_orders__order_id__items_get", "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "title": "Order Id" }, "description": "The order's ID." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Maximum results per page.", "default": 10, "title": "Limit" }, "description": "Maximum results per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "description": "Cursor from the previous page.", "title": "Cursor" }, "description": "Cursor from the previous page." }, { "name": "reverse", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Return descending order when true; ascending when false.", "default": true, "title": "Reverse" }, "description": "Return descending order when true; ascending when false." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageResponse_OrderItem_" } } } }, "404": { "description": "Order not found." }, "422": { "description": "Invalid limit, cursor, or reverse flag." } } } }, "/orders/{order_id}/cancel": { "post": { "tags": [ "Orders" ], "summary": "Cancel an order", "description": "Cancel an order that hasn't been fulfilled, and return the order afterwards. Requires write:orders.", "operationId": "cancel_order_orders__order_id__cancel_post", "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "title": "Order Id" }, "description": "The order's ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelOrderRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "404": { "description": "Order not found." }, "409": { "description": "The order can't be cancelled." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/products": { "post": { "tags": [ "Products" ], "summary": "Create a product", "description": "Create a product in the seller's catalog. Whatnot creates one variant for every combination of the product's option values, or a single variant when it has no options. Variants start without a price or inventory, so the product is not on sale until you price them, set their inventory, and merchandise the product.", "operationId": "create_product_products_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProductRequest" } } } }, "responses": { "201": { "description": "The product was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } }, "headers": { "Location": { "description": "URI of the created product.", "schema": { "type": "string", "format": "uri" } } } }, "403": { "description": "The seller is not approved to create products, or product creation is not enabled for them." }, "422": { "description": "The request failed validation." } } }, "get": { "tags": [ "Products" ], "summary": "List products", "description": "List the authenticated seller's products, newest first by default.", "operationId": "seller_api_v2_list_products_products_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Maximum results per page.", "default": 10, "title": "Limit" }, "description": "Maximum results per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "description": "Cursor from the previous page.", "title": "Cursor" }, "description": "Cursor from the previous page." }, { "name": "reverse", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Return descending order when true; ascending when false.", "default": true, "title": "Reverse" }, "description": "Return descending order when true; ascending when false." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageResponse_Product_" } } } }, "422": { "description": "The pagination parameters are invalid." } } } }, "/products/{product_id}": { "patch": { "tags": [ "Products" ], "summary": "Update a product", "description": "Partially update a product; omitted fields are unchanged. Use merchandising APIs to update the transaction type, add to shows, or make available for sale on your profile shop.", "operationId": "update_product_products__product_id__patch", "parameters": [ { "name": "product_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "title": "Product Id" }, "description": "The product's ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProductRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "403": { "description": "The seller is not approved to update products, or product updates are not enabled for them." }, "404": { "description": "Product not found." }, "422": { "description": "The request failed validation." } } }, "get": { "tags": [ "Products" ], "summary": "Get a product", "description": "Fetch a single product owned by the authenticated seller.", "operationId": "seller_api_v2_get_product_products__product_id__get", "parameters": [ { "name": "product_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "title": "Product Id" }, "description": "The product's ID." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "404": { "description": "Product not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Products" ], "summary": "Delete a product", "description": "Delete a product from the seller's catalog.", "operationId": "delete_product_products__product_id__delete", "parameters": [ { "name": "product_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "title": "Product Id" }, "description": "The product's ID." } ], "responses": { "204": { "description": "The product was deleted." }, "404": { "description": "Product not found." }, "409": { "description": "The product cannot be deleted in its current state." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/products/{product_id}/variants": { "patch": { "tags": [ "Products" ], "summary": "Update product variants", "description": "Partially update one or more of a product's variants; omitted fields are unchanged. `media` replaces a variant's image with one item; a variant image cannot be removed. A new image is ingested asynchronously and may be missing from this response. With allow_partial_updates, valid variants are applied and the rest are returned in errors. Without it, any invalid variant rejects the whole batch.", "operationId": "seller_api_v2_batch_update_product_variants_products__product_id__variants_patch", "parameters": [ { "name": "product_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "title": "Product Id" }, "description": "The product's ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProductVariantsRequest" } } } }, "responses": { "207": { "description": "The updated variants, plus per-variant errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariantBatchResult" } } } }, "404": { "description": "Product not found." }, "422": { "description": "The request failed validation." } } }, "get": { "tags": [ "Products" ], "summary": "List product variants", "description": "List variants newest first by default; set reverse=false for oldest first.", "operationId": "seller_api_v2_list_product_variants_products__product_id__variants_get", "parameters": [ { "name": "product_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "title": "Product Id" }, "description": "The product's ID." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Maximum results per page.", "default": 10, "title": "Limit" }, "description": "Maximum results per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "description": "Cursor from the previous page.", "title": "Cursor" }, "description": "Cursor from the previous page." }, { "name": "reverse", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Return descending order when true; ascending when false.", "default": true, "title": "Reverse" }, "description": "Return descending order when true; ascending when false." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageResponse_ProductVariant_" } } } }, "404": { "description": "Product not found." }, "422": { "description": "Invalid limit, cursor, or reverse flag." } } } }, "/products/{product_id}/variants/{id}": { "get": { "tags": [ "Products" ], "summary": "Get a product variant", "operationId": "seller_api_v2_get_product_variant_products__product_id__variants__id__get", "parameters": [ { "name": "product_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "title": "Product Id" }, "description": "The product's ID." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Id" }, "description": "The variant's ID." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductVariant" } } } }, "404": { "description": "Variant not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/reports/{report_id}": { "get": { "tags": [ "Reports and Statements" ], "summary": "Get a report", "description": "Retrieve one of the seller's report generation runs. Requires read:reports.", "operationId": "seller_api_v2_get_report_reports__report_id__get", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The report run's ID.", "title": "Report Id" }, "description": "The report run's ID." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Report" } } } }, "404": { "description": "Report not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/reports": { "get": { "tags": [ "Reports and Statements" ], "summary": "List reports", "description": "List the seller's report generation runs, most recently requested first by default; set reverse=false for oldest first. Requires read:reports.", "operationId": "list_reports_reports_get", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "enum": [ "pending", "in_progress", "completed", "failed", "cancelled" ] }, { "type": "null" } ], "title": "Status" }, "description": "Only list runs with this status." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Maximum results per page.", "default": 10, "title": "Limit" }, "description": "Maximum results per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "description": "Cursor from the previous page.", "title": "Cursor" }, "description": "Cursor from the previous page." }, { "name": "reverse", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Return descending order when true; ascending when false.", "default": true, "title": "Reverse" }, "description": "Return descending order when true; ascending when false." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageResponse_Report_" } } } }, "422": { "description": "Invalid status, limit, cursor, or reverse flag." } } }, "post": { "tags": [ "Reports and Statements" ], "summary": "Generate a report", "description": "Request a report generation run and return it. `report_type` selects the kind of report and the parameters it accepts. The run is created `pending`; generation happens asynchronously. When an identical request is already in flight or recently completed, that existing run is returned instead of starting a new one. Requires write:reports.", "operationId": "generate_report_reports_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateReportRequest" } } } }, "responses": { "201": { "description": "The run that will produce the report.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Report" } } }, "headers": { "Location": { "description": "URI of the report run.", "schema": { "type": "string", "format": "uri" } } } }, "422": { "description": "The report parameters are not valid." } } } }, "/shipments/{shipment_id}": { "get": { "tags": [ "Shipments" ], "summary": "Get a shipment", "description": "Retrieve a shipment owned by the authenticated seller. Requires read:shipments.", "operationId": "get_shipment_shipments__shipment_id__get", "parameters": [ { "name": "shipment_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "title": "Shipment Id" }, "description": "The shipment's ID." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shipment" } } } }, "404": { "description": "Shipment not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/shipments/{shipment_id}/items/{item_id}": { "get": { "tags": [ "Shipments" ], "summary": "Get a shipment item", "operationId": "get_shipment_item_shipments__shipment_id__items__item_id__get", "parameters": [ { "name": "shipment_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "title": "Shipment Id" }, "description": "The shipment's ID." }, { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "title": "Item Id" }, "description": "The shipment item's ID." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentItem" } } } }, "404": { "description": "Shipment item not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/shipments": { "get": { "tags": [ "Shipments" ], "summary": "List shipments", "description": "List shipments newest first by default; set reverse=false for oldest first.", "operationId": "list_shipments_shipments_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Maximum results per page.", "default": 10, "title": "Limit" }, "description": "Maximum results per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "description": "Cursor from the previous page.", "title": "Cursor" }, "description": "Cursor from the previous page." }, { "name": "reverse", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Return descending order when true; ascending when false.", "default": true, "title": "Reverse" }, "description": "Return descending order when true; ascending when false." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageResponse_Shipment_" } } } }, "422": { "description": "Invalid limit, cursor, or reverse flag." } } } }, "/shipments/{shipment_id}/items": { "get": { "tags": [ "Shipments" ], "summary": "List shipment items", "description": "List active shipment items newest first by default; set reverse=false for oldest first.", "operationId": "list_shipment_items_shipments__shipment_id__items_get", "parameters": [ { "name": "shipment_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "title": "Shipment Id" }, "description": "The shipment's ID." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Maximum results per page.", "default": 10, "title": "Limit" }, "description": "Maximum results per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "description": "Cursor from the previous page.", "title": "Cursor" }, "description": "Cursor from the previous page." }, { "name": "reverse", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Return descending order when true; ascending when false.", "default": true, "title": "Reverse" }, "description": "Return descending order when true; ascending when false." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageResponse_ShipmentItem_" } } } }, "404": { "description": "Shipment not found." }, "422": { "description": "Invalid limit, cursor, or reverse flag." } } } }, "/shipments/add_tracking_code": { "post": { "tags": [ "Shipments" ], "summary": "Add a tracking code to order items", "description": "Ship order items under a tracking code from the seller's own label. The items move onto one shipment with the tracking code, usually a new one, so read each item's shipment afterwards. The items must ship to the same buyer and address, their shipments must not have been dropped off or shipped, and the seller must be able to use their own labels. Requires write:shipments.", "operationId": "add_tracking_code_shipments_add_tracking_code_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddTrackingCodeRequest" } } }, "required": true }, "responses": { "204": { "description": "Successful Response" }, "409": { "description": "The order items can't take this tracking code." }, "422": { "description": "Invalid request, unknown order items, or an invalid tracking code." }, "503": { "description": "Seller-provided tracking codes are unavailable." } } } }, "/shipments/{shipment_id}/generate_label": { "post": { "tags": [ "Shipments" ], "summary": "Request a shipping label", "description": "Queue label generation using the shipment's saved settings. HTTP 200 means enqueued, not generated. Preflight errors are returned synchronously. Receive successful labels through the label-created webhook; worker failures are not currently exposed by this API.", "operationId": "generate_label_shipments__shipment_id__generate_label_post", "parameters": [ { "name": "shipment_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "title": "Shipment Id" }, "description": "The shipment's ID." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelGenerationAcceptedResponse" } } } }, "403": { "description": "Seller verification required, or insufficient scope." }, "404": { "description": "Shipment not found." }, "409": { "description": "Shipment state, settings, or seller setup prevents generation." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "503": { "description": "Label generation is unavailable." } } } }, "/shipping/dimension_profiles/{dimension_profile_id}": { "get": { "tags": [ "Shipping" ], "summary": "Get a dimension profile", "description": "Retrieve a dimension profile owned by the authenticated seller or provided by Whatnot, including inactive profiles. Requires read:inventory.", "operationId": "get_dimension_profile_shipping_dimension_profiles__dimension_profile_id__get", "parameters": [ { "name": "dimension_profile_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "title": "Dimension Profile Id" }, "description": "The dimension profile's ID." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DimensionProfile" } } } }, "404": { "description": "Dimension profile not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/shipping/dimension_profiles": { "get": { "tags": [ "Shipping" ], "summary": "List dimension profiles", "description": "List the seller's own active dimension profiles newest first by default; set reverse=false for oldest first. Requires read:inventory.", "operationId": "list_dimension_profiles_shipping_dimension_profiles_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Maximum results per page.", "default": 10, "title": "Limit" }, "description": "Maximum results per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "description": "Cursor from the previous page.", "title": "Cursor" }, "description": "Cursor from the previous page." }, { "name": "reverse", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Return descending order when true; ascending when false.", "default": true, "title": "Reverse" }, "description": "Return descending order when true; ascending when false." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageResponse_DimensionProfile_" } } } }, "422": { "description": "Invalid limit, cursor, or reverse flag." } } } }, "/shows/{show_id}": { "get": { "tags": [ "Shows" ], "summary": "Get a show", "description": "Retrieve a show owned by the authenticated seller. Requires read:shows.", "operationId": "get_show_shows__show_id__get", "parameters": [ { "name": "show_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Show Id" }, "description": "The show's ID." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Show" } } } }, "404": { "description": "Show not found." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/shows": { "get": { "tags": [ "Shows" ], "summary": "List shows", "description": "List shows with the given status by scheduled start time, latest first by default; set reverse=false for earliest first. Shows without a scheduled start time are listed last. Requires read:shows.", "operationId": "list_shows_shows_get", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "scheduled", "live", "stopped", "ended", "cancelled" ], "default": "scheduled", "title": "Status" }, "description": "Only list shows with this status. Defaults to scheduled." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Maximum results per page.", "default": 10, "title": "Limit" }, "description": "Maximum results per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "description": "Cursor from the previous page.", "title": "Cursor" }, "description": "Cursor from the previous page." }, { "name": "reverse", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Return descending order when true; ascending when false.", "default": true, "title": "Reverse" }, "description": "Return descending order when true; ascending when false." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageResponse_Show_" } } } }, "422": { "description": "Invalid status, limit, cursor, or reverse flag." } } } }, "/users/me": { "get": { "tags": [ "Users" ], "summary": "Get the current user", "description": "Retrieve the seller authenticated by the calling application's token.", "operationId": "get_me_users_me_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "description": "A valid seller API token is required." } } } }, "/users/disconnect": { "post": { "tags": [ "Users" ], "summary": "Disconnect the current application", "description": "Remove the authenticated seller's installation of the calling application and expire its tokens, including refresh tokens. Subsequent requests using this installation's tokens are unauthorized. Other installations are unaffected.", "operationId": "disconnect_users_disconnect_post", "responses": { "204": { "description": "Successful Response" }, "401": { "description": "A valid seller API token is required." }, "500": { "description": "The application could not be disconnected." } } } } }, "components": { "schemas": { "AddTrackingCodeRequest": { "properties": { "order_item_ids": { "items": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "type": "array", "maxItems": 100, "minItems": 1, "uniqueItems": true, "title": "Order Item Ids", "description": "The decimal IDs of the order items to ship under the tracking code." }, "tracking_code": { "type": "string", "minLength": 1, "title": "Tracking Code", "description": "The carrier's tracking code for the package." }, "carrier": { "type": "string", "title": "Carrier", "description": "The carrier delivering the package.", "examples": [ "usps" ] } }, "type": "object", "required": [ "order_item_ids", "tracking_code", "carrier" ], "title": "AddTrackingCodeRequest" }, "AdjustInventoryLevelsRequest": { "properties": { "items": { "items": { "$ref": "#/components/schemas/AdjustInventoryItem" }, "type": "array", "maxItems": 10, "minItems": 1, "title": "Items", "description": "The variants to adjust, applied independently. At most 10 items per request." } }, "additionalProperties": false, "type": "object", "required": [ "items" ], "title": "AdjustInventoryLevelsRequest" }, "CancelOrderRequest": { "properties": { "reason": { "$ref": "#/components/schemas/OrderCancellationReason", "description": "The reason for cancelling the order. `break_did_not_fill` is accepted only for orders from a break." } }, "type": "object", "required": [ "reason" ], "title": "CancelOrderRequest" }, "CreateProductRequest": { "properties": { "title": { "type": "string", "title": "Title", "description": "The product's title." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "The product's description." }, "external_id": { "anyOf": [ { "type": "string", "maxLength": 150 }, { "type": "null" } ], "title": "External Id", "description": "The seller-provided external identifier for the product." }, "category": { "$ref": "#/components/schemas/Category", "description": "The product's category." }, "attributes": { "items": { "$ref": "#/components/schemas/ProductAttribute" }, "type": "array", "title": "Attributes", "description": "The product's attribute values." }, "options": { "items": { "$ref": "#/components/schemas/ProductOption" }, "type": "array", "maxItems": 3, "title": "Options", "description": "The product's option axes (e.g. Color, Size). At most 3 options are allowed, and the product of their value counts must not exceed the seller's variant limit." }, "media": { "items": { "$ref": "#/components/schemas/Media" }, "type": "array", "title": "Media", "description": "The product's images." }, "dimension_profile": { "$ref": "#/components/schemas/DimensionProfile", "description": "The product's dimension profile." } }, "additionalProperties": false, "type": "object", "required": [ "title", "category", "dimension_profile" ], "title": "CreateProductRequest", "description": "The settable fields when creating a product.\n\nOnly what a seller can set on create: server-derived fields (id, url,\ntimestamps) live on ExternalProduct and are not accepted here.", "example": { "attributes": [ { "id": "7", "value": "Near Mint" } ], "category": { "id": "42" }, "description": "A very rare card.", "dimension_profile": { "dimensions": { "height": 1, "length": 6, "unit": "inch", "width": 4 }, "weight": { "unit": "ounce", "value": 4 } }, "external_id": "uuid-123", "media": [ { "alt": "front", "url": "https://images.whatnot.com/example.jpg" } ], "options": [ { "name": "Color", "values": [ "Red", "Blue" ] } ], "title": "Rare Holographic Card" } }, "AdjustInventoryItem": { "properties": { "variant_id": { "type": "string", "title": "Variant Id", "description": "The variant's id." }, "delta": { "type": "integer", "maximum": 2147483647, "minimum": -2147483647, "title": "Delta", "description": "The change to apply to the available quantity. A result below zero is floored at 0." }, "idempotency_key": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Idempotency Key", "description": "Caller-supplied key that makes this item idempotent: a retried item with the same key applies at most once and reports already_applied. Keys are scoped to the seller. Use a unique key for each distinct write, such as a V4 UUID." } }, "additionalProperties": false, "type": "object", "required": [ "variant_id", "delta", "idempotency_key" ], "title": "AdjustInventoryItem" }, "AnalyticsOverviewReportParameters": { "properties": { "report_type": { "type": "string", "const": "analytics_overview_report", "title": "Report Type", "description": "The type of report these parameters describe." }, "start_at": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$", "format": "date-time", "title": "Start At", "description": "The start of the reported window." }, "end_at": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$", "format": "date-time", "title": "End At", "description": "The end of the reported window. Must be after `start_at`." } }, "additionalProperties": false, "type": "object", "required": [ "report_type", "start_at", "end_at" ], "title": "AnalyticsOverviewReportParameters", "description": "Parameters for an `analytics_overview_report` run.\n\nThe report is one row per calendar day of the window.", "example": { "end_at": "2026-10-01T00:00:00.000Z", "report_type": "analytics_overview_report", "start_at": "2026-09-01T00:00:00.000Z" } }, "Category": { "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "title": "Id", "description": "The category's id." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "The category's display name.", "readOnly": true } }, "type": "object", "required": [ "id" ], "title": "Category" }, "DimensionProfile": { "properties": { "id": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, { "type": "null" } ], "title": "Id", "description": "An existing dimension profile id to reference." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "The dimension profile's name. When auto-creating a profile this is used as a name prefix, with the weight and dimensions appended." }, "weight": { "anyOf": [ { "$ref": "#/components/schemas/Weight" }, { "type": "null" } ], "description": "The profile's per-item weight." }, "dimensions": { "anyOf": [ { "$ref": "#/components/schemas/Dimensions" }, { "type": "null" } ], "description": "The profile's package dimensions." }, "ownership": { "anyOf": [ { "$ref": "#/components/schemas/DimensionProfileOwnership" }, { "type": "null" } ], "description": "Whether the dimension profile belongs to the seller or Whatnot.", "readOnly": true }, "active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Active", "description": "Whether the dimension profile is active.", "readOnly": true } }, "type": "object", "title": "DimensionProfile", "description": "A dimension profile, also embedded in products and shipment items.\n\nOn read, the resolved profile. On create, reference an existing profile by\n`id`, or supply `weight` and `dimensions` (with an optional `name`) to\nauto-create one." }, "DimensionProfileOwnership": { "type": "string", "enum": [ "seller", "whatnot" ], "title": "DimensionProfileOwnership" }, "DimensionUnit": { "type": "string", "enum": [ "inch", "feet", "centimeter", "meter" ], "title": "DimensionUnit" }, "Dimensions": { "properties": { "length": { "type": "number", "title": "Length", "description": "The package length." }, "width": { "type": "number", "title": "Width", "description": "The package width." }, "height": { "type": "number", "title": "Height", "description": "The package height." }, "unit": { "$ref": "#/components/schemas/DimensionUnit", "description": "The dimension unit." } }, "type": "object", "required": [ "length", "width", "height", "unit" ], "title": "Dimensions" }, "FinancialReportParameters": { "properties": { "report_type": { "type": "string", "const": "seller_financial_report", "title": "Report Type", "description": "The type of report these parameters describe." }, "start_date": { "anyOf": [ { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$", "format": "date-time" }, { "type": "null" } ], "title": "Start Date", "description": "Include only transactions completed at or after this time. Defaults to one week before `end_date`." }, "end_date": { "anyOf": [ { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$", "format": "date-time" }, { "type": "null" } ], "title": "End Date", "description": "Include only transactions completed before this time. Defaults to one week after `start_date`, or to the current hour when neither end is given." } }, "additionalProperties": false, "type": "object", "required": [ "report_type" ], "title": "FinancialReportParameters", "description": "Parameters for a `seller_financial_report` run.", "example": { "end_date": "2026-09-08T00:00:00.000Z", "report_type": "seller_financial_report", "start_date": "2026-09-01T00:00:00.000Z" } }, "FixedPriceDiscount": { "properties": { "type": { "type": "string", "const": "fixed_price", "title": "Type", "description": "A fixed amount off the order." }, "amount": { "$ref": "#/components/schemas/Money", "description": "The amount discounted." } }, "type": "object", "required": [ "type", "amount" ], "title": "FixedPriceDiscount" }, "FulfillmentMethod": { "type": "string", "enum": [ "shipping", "pickup" ], "title": "FulfillmentMethod" }, "HazardousMaterial": { "type": "string", "enum": [ "not_hazardous", "standard", "lithium_battery" ], "title": "HazardousMaterial" }, "InventoryBatchResult": { "properties": { "results": { "items": { "$ref": "#/components/schemas/InventoryResult" }, "type": "array", "title": "Results", "description": "Per-item results, in the same order as the input items." } }, "type": "object", "required": [ "results" ], "title": "InventoryBatchResult" }, "InventoryResult": { "properties": { "variant_id": { "type": "string", "title": "Variant Id", "description": "The item's variant_id, echoed from input." }, "idempotency_key": { "type": "string", "title": "Idempotency Key", "description": "The item's idempotency_key, echoed from input." }, "status": { "type": "string", "enum": [ "applied", "already_applied", "variant_not_found", "inventory_level_not_found", "inventory_not_supported" ], "title": "Status", "description": "What happened to this item." }, "previous_quantity": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Previous Quantity", "description": "The available quantity just before this item applied." }, "new_quantity": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "New Quantity", "description": "The available quantity after this item." }, "warnings": { "items": { "type": "string", "enum": [ "result_clamped_to_zero" ] }, "type": "array", "title": "Warnings", "description": "Non-fatal conditions observed while applying this item." } }, "type": "object", "required": [ "variant_id", "idempotency_key", "status", "previous_quantity", "new_quantity", "warnings" ], "title": "InventoryResult" }, "LivestreamsReportParameters": { "properties": { "report_type": { "type": "string", "const": "analytics_livestreams_report", "title": "Report Type", "description": "The type of report these parameters describe." }, "all_matching": { "anyOf": [ { "$ref": "#/components/schemas/MatchingShowsFilter" }, { "type": "null" } ], "description": "Report on every show matching the filter, most recently started first. An empty filter covers all of the seller's shows." }, "specific_shows": { "anyOf": [ { "$ref": "#/components/schemas/SpecificShows" }, { "type": "null" } ], "description": "Report on exactly these shows." } }, "additionalProperties": false, "type": "object", "required": [ "report_type" ], "title": "LivestreamsReportParameters", "description": "Parameters for an `analytics_livestreams_report` run.\n\nExactly one of `all_matching` and `specific_shows` selects the shows.", "example": { "all_matching": { "start_time": { "start": "2026-09-01T00:00:00.000Z" } }, "report_type": "analytics_livestreams_report" } }, "MatchingShowsFilter": { "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title", "description": "Include only shows whose title matches this text." }, "start_time": { "anyOf": [ { "$ref": "#/components/schemas/ShowStartTimeRange" }, { "type": "null" } ], "description": "Include only shows that started within this range." } }, "additionalProperties": false, "type": "object", "title": "MatchingShowsFilter", "description": "Which of the seller's shows an `all_matching` report covers." }, "Media": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id", "description": "The image's id.", "readOnly": true }, "url": { "type": "string", "title": "Url", "description": "On create, the image URL to ingest. On read, the CDN URL of the ingested image." }, "alt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Alt", "description": "The image's alt text / label, if set." } }, "type": "object", "required": [ "url" ], "title": "Media" }, "MerchandisingTransactionType": { "type": "string", "enum": [ "buy_it_now", "auction" ], "title": "MerchandisingTransactionType", "description": "The sale formats a merchandising call can set." }, "Money": { "properties": { "amount": { "type": "string", "title": "Amount", "description": "Decimal amount in major currency units, e.g. 42.00." }, "currency": { "type": "string", "title": "Currency", "description": "ISO 4217 currency code." } }, "type": "object", "required": [ "amount", "currency" ], "title": "Money" }, "Order": { "properties": { "id": { "type": "string", "title": "Id", "description": "The order's ID." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url", "description": "The url of the order in the seller's dashboard." }, "status": { "$ref": "#/components/schemas/OrderStatus", "description": "The order's status. `pending` orders aren't ready to fulfill; fulfill `pending_fulfillment` orders." }, "show_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Show Id", "description": "The show the order was placed in; null for orders placed anywhere else." }, "transaction_type": { "anyOf": [ { "$ref": "#/components/schemas/OrderTransactionType" }, { "type": "null" } ], "description": "How the order was sold, if recorded. `other` covers retired formats." }, "buyer": { "anyOf": [ { "$ref": "#/components/schemas/UserSummary" }, { "type": "null" } ], "description": "The Whatnot user who placed the order; requires read:customers." }, "amounts": { "$ref": "#/components/schemas/OrderAmounts", "description": "The order's monetary amounts." }, "created_at": { "anyOf": [ { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$", "format": "date-time" }, { "type": "null" } ], "title": "Created At", "description": "Creation timestamp, if recorded." }, "updated_at": { "anyOf": [ { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$", "format": "date-time" }, { "type": "null" } ], "title": "Updated At", "description": "Last update timestamp, if recorded." }, "cancelled_at": { "anyOf": [ { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$", "format": "date-time" }, { "type": "null" } ], "title": "Cancelled At", "description": "When the order was cancelled, if it was." } }, "type": "object", "required": [ "id", "url", "status", "show_id", "transaction_type", "buyer", "amounts", "created_at", "updated_at", "cancelled_at" ], "title": "Order", "example": { "amounts": { "applied_discount": { "amount": { "amount": "2", "currency": "USD" }, "type": "fixed_price" }, "shipping": { "amount": "5.99", "currency": "USD" }, "subtotal": { "amount": "42", "currency": "USD" }, "tax": { "amount": "3.78", "currency": "USD" }, "total": { "amount": "49.77", "currency": "USD" } }, "buyer": { "display_name": "Card Collector", "id": "6789", "username": "cardcollector" }, "created_at": "2026-09-21T12:00:00.000Z", "id": "123456", "show_id": "0b6f3c1e-8a52-4d2e-9f7a-3c5d1e2f4a6b", "status": "pending_fulfillment", "transaction_type": "auction", "updated_at": "2026-09-21T13:00:00.000Z", "url": "https://www.whatnot.com/dashboard/orders/5f0c2b7e-1d3a-4c6b-9e8f-7a6b5c4d3e2f" } }, "OrderAmounts": { "properties": { "subtotal": { "$ref": "#/components/schemas/Money", "description": "The price of the items ordered." }, "shipping": { "$ref": "#/components/schemas/Money", "description": "Shipping charged to the buyer." }, "tax": { "$ref": "#/components/schemas/Money", "description": "Tax charged to the buyer." }, "applied_discount": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/FixedPriceDiscount" }, { "$ref": "#/components/schemas/PercentageDiscount" } ], "discriminator": { "propertyName": "type", "mapping": { "fixed_price": "#/components/schemas/FixedPriceDiscount", "percentage": "#/components/schemas/PercentageDiscount" } } }, { "type": "null" } ], "title": "Applied Discount", "description": "The discount from the seller's coupon; null when none applied or the coupon isn't the seller's." }, "total": { "$ref": "#/components/schemas/Money", "description": "The total the buyer paid." } }, "type": "object", "required": [ "subtotal", "shipping", "tax", "applied_discount", "total" ], "title": "OrderAmounts" }, "OrderCancellationReason": { "type": "string", "enum": [ "item_damaged", "item_sold", "item_missing", "break_did_not_fill", "other" ], "title": "OrderCancellationReason" }, "OrderItem": { "properties": { "id": { "type": "string", "title": "Id", "description": "The order item's ID." }, "order_id": { "type": "string", "title": "Order Id", "description": "The ID of the order containing this item." }, "product_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Product Id", "description": "The purchased product's ID, if known." }, "variant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Variant Id", "description": "The purchased variant's ID, if the product has variants." }, "product_external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Product External Id", "description": "The seller-provided external ID of the purchased product, if set." }, "variant_external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Variant External Id", "description": "The seller-provided external ID of the purchased variant, if set." }, "purchased_item": { "anyOf": [ { "$ref": "#/components/schemas/PurchasedItem" }, { "type": "null" } ], "description": "The item as listed when it was purchased, if recorded." }, "quantity": { "type": "integer", "title": "Quantity", "description": "The number of units purchased." }, "unit_price": { "$ref": "#/components/schemas/Money", "description": "The price of one unit." }, "price_includes_tax": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Price Includes Tax", "description": "Whether unit_price includes tax, if recorded." }, "shipment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Shipment Id", "description": "The ID of the shipment currently containing this item, if any." } }, "type": "object", "required": [ "id", "order_id", "product_id", "variant_id", "product_external_id", "variant_external_id", "purchased_item", "quantity", "unit_price", "price_includes_tax", "shipment_id" ], "title": "OrderItem", "example": { "id": "987654", "order_id": "123456", "price_includes_tax": false, "product_external_id": "shopify-product-1", "product_id": "4321", "purchased_item": { "description": "Near mint, graded PSA 9.", "sku": "CHAR-BS-PSA9", "title": "Charizard Holo - Base Set" }, "quantity": 1, "shipment_id": "55555", "unit_price": { "amount": "42", "currency": "USD" }, "variant_external_id": "shopify-variant-1", "variant_id": "0f5e1c9a-2b7d-4e3f-8a6b-1c2d3e4f5a6b" } }, "OrderStatus": { "type": "string", "enum": [ "pending", "pending_fulfillment", "completed", "cancelled", "failed" ], "title": "OrderStatus" }, "OrderTransactionType": { "type": "string", "enum": [ "buy_it_now", "auction", "giveaway", "other" ], "title": "OrderTransactionType" }, "PercentageDiscount": { "properties": { "type": { "type": "string", "const": "percentage", "title": "Type", "description": "A percentage off the order." }, "amount": { "$ref": "#/components/schemas/Money", "description": "The amount discounted." } }, "type": "object", "required": [ "type", "amount" ], "title": "PercentageDiscount" }, "Product": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id", "description": "The product's id.", "readOnly": true }, "title": { "type": "string", "title": "Title", "description": "The product's title." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "The product's description." }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Id", "description": "The seller-provided external identifier for the product." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url", "description": "The url of the product in the seller's inventory dashboard.", "readOnly": true }, "category": { "anyOf": [ { "$ref": "#/components/schemas/Category" }, { "type": "null" } ], "description": "The product's category." }, "attributes": { "items": { "$ref": "#/components/schemas/ProductAttribute" }, "type": "array", "title": "Attributes", "description": "The product's attribute values." }, "options": { "items": { "$ref": "#/components/schemas/ProductOption" }, "type": "array", "title": "Options", "description": "The product's option axes (e.g. Color, Size)." }, "media": { "items": { "$ref": "#/components/schemas/Media" }, "type": "array", "title": "Media", "description": "The product's images." }, "dimension_profile": { "anyOf": [ { "$ref": "#/components/schemas/DimensionProfile" }, { "type": "null" } ], "description": "The product's dimension profile." }, "created_at": { "anyOf": [ { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$", "format": "date-time" }, { "type": "null" } ], "title": "Created At", "description": "When the product was created.", "readOnly": true }, "updated_at": { "anyOf": [ { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$", "format": "date-time" }, { "type": "null" } ], "title": "Updated At", "description": "When the product was last updated.", "readOnly": true } }, "type": "object", "required": [ "title" ], "title": "Product", "description": "The full representation of a product, shared by the REST v2 `get_product`\nresponse and any full-body product webhooks.", "example": { "attributes": [ { "id": "7", "name": "Condition", "value": "Near Mint" } ], "category": { "id": "42", "name": "Trading Cards" }, "created_at": "2026-01-15T12:00:00.000Z", "description": "A very rare card.", "dimension_profile": { "active": true, "dimensions": { "height": 1, "length": 6, "unit": "inch", "width": 4 }, "id": "88", "name": "API 4 oz", "ownership": "seller", "weight": { "unit": "ounce", "value": 4 } }, "external_id": "ext-123", "id": "12345", "media": [ { "alt": "front", "id": "555", "url": "https://cdn.whatnot.com/i/555.jpg" } ], "options": [ { "id": "1001", "name": "Color", "values": [ "Red", "Blue" ] } ], "title": "Rare Holographic Card", "updated_at": "2026-01-15T12:00:00.000Z", "url": "https://www.whatnot.com/product/abc123" } }, "ProductAttribute": { "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "title": "Id", "description": "The product attribute's id." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "The product attribute's display name, if the definition is known.", "readOnly": true }, "value": { "type": "string", "title": "Value", "description": "The attribute's value for this product." } }, "type": "object", "required": [ "id", "value" ], "title": "ProductAttribute" }, "ProductMerchandising": { "properties": { "transaction_type": { "anyOf": [ { "$ref": "#/components/schemas/TransactionType" }, { "type": "null" } ], "description": "The configured sale format; selects which variant pricing is used. Null when the product has no listing." }, "reserved_for_live": { "type": "boolean", "title": "Reserved For Live", "description": "Whether the product is sold only in live shows. Auctions are always reserved for live. A buy-it-now product that is not reserved for live is listed for sale on the seller's profile shop." }, "active_in_shows": { "type": "boolean", "title": "Active In Shows", "description": "Whether the product is assigned to at least one upcoming or live show. List the shows at GET /merchandising/products/{product_id}/shows." } }, "type": "object", "required": [ "transaction_type", "reserved_for_live", "active_in_shows" ], "title": "ProductMerchandising", "description": "How and where a product is currently being sold.\n\nThe seller-facing merchandising view of a product: its sale format, whether\nit is reserved for live, and whether it is assigned to any upcoming or live\nshows. The shows themselves are paginated separately at\n``GET /merchandising/products/{product_id}/shows``.", "example": { "active_in_shows": true, "reserved_for_live": false, "transaction_type": "buy_it_now" } }, "ProductOption": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id", "description": "The product option's id.", "readOnly": true }, "name": { "type": "string", "title": "Name", "description": "The option's display name, e.g. 'Color'." }, "values": { "items": { "type": "string" }, "type": "array", "title": "Values", "description": "The option's values, e.g. ['Red', 'Blue']." } }, "type": "object", "required": [ "name", "values" ], "title": "ProductOption" }, "ProductVariant": { "properties": { "id": { "type": "string", "title": "Id", "description": "The variant's id." }, "product_id": { "type": "string", "title": "Product Id", "description": "Parent product identifier." }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sku", "description": "Seller SKU, if set." }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Id", "description": "Seller external identifier, if set." }, "selected_options": { "items": { "$ref": "#/components/schemas/SelectedOption" }, "type": "array", "title": "Selected Options", "description": "Selected product option values." }, "pricing": { "$ref": "#/components/schemas/VariantPricing", "description": "Staged format-specific prices." }, "country_of_origin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country Of Origin", "description": "Seller-declared country of origin." }, "inventory": { "$ref": "#/components/schemas/VariantInventory", "description": "Default-location inventory." }, "media": { "items": { "$ref": "#/components/schemas/Media" }, "type": "array", "title": "Media", "description": "Resolved variant images." } }, "type": "object", "required": [ "id", "product_id", "sku", "external_id", "selected_options", "pricing", "country_of_origin", "inventory", "media" ], "title": "ProductVariant" }, "ProductVariantPatch": { "properties": { "id": { "type": "string", "title": "Id", "description": "The variant's id." }, "sku": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Sku", "description": "Seller SKU. Send null to clear." }, "external_id": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "External Id", "description": "Seller external identifier. Send null to clear." }, "pricing": { "anyOf": [ { "$ref": "#/components/schemas/VariantPricingInput" }, { "type": "null" } ], "description": "Format-specific prices to stage." }, "country_of_origin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country Of Origin", "description": "Seller-declared country of origin, ISO 3166-1 alpha-2." }, "media": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Media" }, "type": "array", "maxItems": 1, "minItems": 1 }, { "type": "null" } ], "title": "Media", "description": "Replaces the variant's image. Send one item. Omit the field to leave it unchanged. A variant image cannot be removed. Ingest is asynchronous, so a new image may be missing from this response." } }, "additionalProperties": false, "type": "object", "required": [ "id" ], "title": "ProductVariantPatch", "description": "A partial variant update. Omitted fields are left unchanged." }, "PurchasedItem": { "properties": { "title": { "type": "string", "title": "Title", "description": "The item's title when it was purchased." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "The item's description when it was purchased, if set." }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sku", "description": "The item's SKU when it was purchased, if set." } }, "type": "object", "required": [ "title", "description", "sku" ], "title": "PurchasedItem" }, "Report": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "The report run's ID." }, "report_type": { "$ref": "#/components/schemas/ReportType", "description": "The type of report this run generates." }, "status": { "$ref": "#/components/schemas/ReportStatus", "description": "The status of the run." }, "report_parameters": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/FinancialReportParameters" }, { "$ref": "#/components/schemas/AnalyticsOverviewReportParameters" }, { "$ref": "#/components/schemas/LivestreamsReportParameters" } ], "discriminator": { "propertyName": "report_type", "mapping": { "analytics_livestreams_report": "#/components/schemas/LivestreamsReportParameters", "analytics_overview_report": "#/components/schemas/AnalyticsOverviewReportParameters", "seller_financial_report": "#/components/schemas/FinancialReportParameters" } } }, { "type": "null" } ], "title": "Report Parameters", "description": "The parameters this run covers, after defaults were applied. The shape depends on `report_type`. Null when the run has no parameters." }, "report_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Report Url", "description": "URL of the generated report file. Null until the run is `completed`. See [Reports and Statements](/reports) for each report type's CSV columns." }, "created_at": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$", "format": "date-time", "title": "Created At", "description": "When the run was requested." }, "updated_at": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$", "format": "date-time", "title": "Updated At", "description": "When the run was last updated." } }, "type": "object", "required": [ "id", "report_type", "status", "report_parameters", "report_url", "created_at", "updated_at" ], "title": "Report", "description": "One asynchronous report generation run.\n\nRuns are created `pending`; generation happens asynchronously.", "example": { "created_at": "2026-09-20T18:30:00.000Z", "id": "0199a7c2-3f4e-7a1b-9c2d-4e5f6a7b8c9d", "report_parameters": { "end_date": "2026-09-08T00:00:00.000Z", "report_type": "seller_financial_report", "start_date": "2026-09-01T00:00:00.000Z" }, "report_type": "seller_financial_report", "status": "pending", "updated_at": "2026-09-20T18:30:00.000Z" } }, "ReportStatus": { "type": "string", "enum": [ "pending", "in_progress", "completed", "failed", "cancelled" ], "title": "ReportStatus" }, "ReportType": { "type": "string", "enum": [ "seller_financial_report", "analytics_overview_report", "analytics_livestreams_report" ], "title": "ReportType" }, "SelectedOption": { "properties": { "id": { "type": "string", "title": "Id", "description": "Stable product option identifier." }, "name": { "type": "string", "title": "Name", "description": "Product option display name." }, "value_id": { "type": "string", "title": "Value Id", "description": "Stable option value identifier." }, "value": { "type": "string", "title": "Value", "description": "Selected option value." } }, "type": "object", "required": [ "id", "name", "value_id", "value" ], "title": "SelectedOption" }, "SetInventoryItem": { "properties": { "variant_id": { "type": "string", "title": "Variant Id", "description": "The variant's id." }, "quantity": { "type": "integer", "maximum": 2147483647, "minimum": 0, "title": "Quantity", "description": "The available quantity to set." }, "idempotency_key": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Idempotency Key", "description": "Caller-supplied key that makes this item idempotent: a retried item with the same key applies at most once and reports already_applied. Keys are scoped to the seller. Use a unique key for each distinct write, such as a V4 UUID." } }, "additionalProperties": false, "type": "object", "required": [ "variant_id", "quantity", "idempotency_key" ], "title": "SetInventoryItem" }, "Shipment": { "properties": { "id": { "type": "string", "title": "Id", "description": "The shipment's ID." }, "url": { "type": "string", "title": "Url", "description": "The url of the shipment in the seller's dashboard." }, "status": { "$ref": "#/components/schemas/ShipmentStatus", "description": "The current fulfillment status of this shipment." }, "fulfillment_method": { "$ref": "#/components/schemas/FulfillmentMethod", "description": "The method of fulfillment for this shipment." }, "recipient": { "anyOf": [ { "$ref": "#/components/schemas/UserSummary" }, { "type": "null" } ], "description": "The Whatnot user receiving this shipment; requires read:customers." }, "weight": { "anyOf": [ { "$ref": "#/components/schemas/Weight" }, { "type": "null" } ], "description": "Package weight, if known and valid." }, "dimensions": { "anyOf": [ { "$ref": "#/components/schemas/Dimensions" }, { "type": "null" } ], "description": "Package dimensions, if known and valid." }, "signature_required": { "type": "boolean", "title": "Signature Required", "description": "Whether delivery requires a signature." }, "hazardous_material": { "anyOf": [ { "$ref": "#/components/schemas/HazardousMaterial" }, { "type": "null" } ], "description": "The hazardous-material classification of this shipment's contents." }, "tracking": { "anyOf": [ { "$ref": "#/components/schemas/ShipmentTracking" }, { "type": "null" } ], "description": "Carrier and tracking information." }, "documents": { "anyOf": [ { "$ref": "#/components/schemas/ShipmentDocuments" }, { "type": "null" } ], "description": "The shipping documents available for this shipment; requires read:customers." }, "insurance": { "anyOf": [ { "$ref": "#/components/schemas/ShipmentInsurance" }, { "type": "null" } ], "description": "Shipping insurance, if present." }, "seller_paid_shipping_cost": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "The seller's share of shipping across this shipment's active orders, set at checkout by the seller's shipping settings. Not the label's purchase price, and excludes later carrier adjustments. Null when none was recorded." }, "required_actions": { "items": { "$ref": "#/components/schemas/ShipmentRequiredAction" }, "type": "array", "title": "Required Actions", "description": "Actions required before fulfillment." }, "dropoff_due": { "anyOf": [ { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$", "format": "date-time" }, { "type": "null" } ], "title": "Dropoff Due", "description": "Due date at seller-local midnight, serialized with timezone; not the overdue cutoff. Null for pickup, non-pre-transit shipments, or missing inputs." }, "replacement_shipment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Replacement Shipment Id", "description": "Immediate successor shipment ID after replacement, bundling, or splitting; not the final successor in a chain." }, "created_at": { "anyOf": [ { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$", "format": "date-time" }, { "type": "null" } ], "title": "Created At", "description": "Creation timestamp, if recorded." }, "updated_at": { "anyOf": [ { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$", "format": "date-time" }, { "type": "null" } ], "title": "Updated At", "description": "Last update timestamp, if recorded." } }, "type": "object", "required": [ "id", "url", "status", "fulfillment_method", "recipient", "weight", "dimensions", "signature_required", "hazardous_material", "tracking", "documents", "insurance", "seller_paid_shipping_cost", "required_actions", "dropoff_due", "replacement_shipment_id", "created_at", "updated_at" ], "title": "Shipment", "example": { "created_at": "2026-09-21T12:00:00.000Z", "dimensions": { "height": 1, "length": 6, "unit": "inch", "width": 4 }, "documents": { "bundled_url": "https://example.com/documents.pdf", "label_url": "https://example.com/label.pdf" }, "dropoff_due": "2026-09-23T07:00:00.000Z", "fulfillment_method": "shipping", "hazardous_material": "not_hazardous", "id": "12345", "insurance": { "amount": { "amount": "25.00", "currency": "USD" }, "contents": "Trading cards" }, "recipient": { "display_name": "Card Collector", "id": "6789", "username": "cardcollector" }, "required_actions": [], "seller_paid_shipping_cost": { "amount": "5.99", "currency": "USD" }, "signature_required": false, "status": "label_generated", "tracking": { "carrier": "usps", "service": "usps_ground_advantage", "tracking_code": "9400111899223100012345" }, "updated_at": "2026-09-21T13:00:00.000Z", "url": "https://www.whatnot.com/dashboard/shipments/U2hpcG1lbnROb2RlOjUxMjU0MTM5Mw==", "weight": { "unit": "ounce", "value": 4 } } }, "ShipmentDocuments": { "properties": { "label_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label Url", "description": "Shipping label URL, if available. Usually hosted by the label provider, which sets how long it stays valid." }, "bundled_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Bundled Url", "description": "Combined label and packing slip, or pickup slip URL. This presigned URL is valid for up to 1 hour; re-fetch the shipment with `GET /shipments/{shipment_id}` for a fresh link." }, "commercial_invoice_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Commercial Invoice Url", "description": "Commercial invoice URL from the label provider, if one was issued." } }, "type": "object", "required": [ "label_url", "bundled_url", "commercial_invoice_url" ], "title": "ShipmentDocuments" }, "ShipmentInsurance": { "properties": { "amount": { "$ref": "#/components/schemas/Money", "description": "Insured value." }, "contents": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contents", "description": "Description of insured contents." } }, "type": "object", "required": [ "amount", "contents" ], "title": "ShipmentInsurance" }, "ShipmentItem": { "properties": { "id": { "type": "string", "title": "Id", "description": "The shipment item's ID; distinct from its order-item ID." }, "shipment_id": { "type": "string", "title": "Shipment Id", "description": "The ID of the shipment currently containing this item." }, "order_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Order Id", "description": "The ID of the order associated with this item, if available." }, "order_item_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Order Item Id", "description": "The ID of the order item associated with this shipment item, if available." }, "dimension_profile": { "anyOf": [ { "$ref": "#/components/schemas/DimensionProfile" }, { "type": "null" } ], "description": "The item's dimension profile, if available." }, "hazardous_material": { "anyOf": [ { "$ref": "#/components/schemas/HazardousMaterial" }, { "type": "null" } ], "description": "The hazardous-material classification of this item." }, "country_of_origin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country Of Origin", "description": "Country of origin, if recorded." }, "created_at": { "anyOf": [ { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$", "format": "date-time" }, { "type": "null" } ], "title": "Created At", "description": "Creation timestamp, if recorded." }, "updated_at": { "anyOf": [ { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$", "format": "date-time" }, { "type": "null" } ], "title": "Updated At", "description": "Last update timestamp, if recorded." } }, "type": "object", "required": [ "id", "shipment_id", "order_id", "order_item_id", "dimension_profile", "hazardous_material", "country_of_origin", "created_at", "updated_at" ], "title": "ShipmentItem" }, "ShipmentRequiredAction": { "type": "string", "enum": [ "country_of_origin_required", "itn_required", "order_pending_cancellation", "package_review_required" ], "title": "ShipmentRequiredAction" }, "ShipmentStatus": { "type": "string", "enum": [ "created", "label_generated", "dropped_off", "in_transit", "delivered", "failed", "cancelled", "cancelled_not_shipped", "cancelled_not_shipped_with_dropoff", "cancelled_tracking_stuck" ], "title": "ShipmentStatus" }, "ShipmentTracking": { "properties": { "carrier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Carrier", "description": "The carrier delivering this shipment." }, "service": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Service", "description": "The carrier service used for this shipment." }, "tracking_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tracking Code", "description": "The carrier's tracking code for this shipment." }, "last_mile_tracking_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Mile Tracking Code", "description": "The tracking code used for the final leg of delivery." } }, "type": "object", "required": [ "carrier", "service", "tracking_code", "last_mile_tracking_code" ], "title": "ShipmentTracking" }, "Show": { "properties": { "id": { "type": "string", "title": "Id", "description": "The show's ID." }, "title": { "type": "string", "title": "Title", "description": "The show's title." }, "url": { "type": "string", "title": "Url", "description": "The url of the show in the seller's dashboard." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "The show's description, if set." }, "status": { "$ref": "#/components/schemas/ShowStatus", "description": "The show's lifecycle status. A stopped show can resume; an ended show cannot." }, "visibility": { "$ref": "#/components/schemas/ShowVisibility", "description": "Whether the show is visible to everyone or only to invited viewers." }, "scheduled_start_at": { "anyOf": [ { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$", "format": "date-time" }, { "type": "null" } ], "title": "Scheduled Start At", "description": "When the show is scheduled to start. Not updated when the show goes live." }, "ended_at": { "anyOf": [ { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$", "format": "date-time" }, { "type": "null" } ], "title": "Ended At", "description": "When the show ended, if it has." }, "thumbnail": { "anyOf": [ { "$ref": "#/components/schemas/Media" }, { "type": "null" } ], "description": "The show's thumbnail image, if set." }, "created_at": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$", "format": "date-time", "title": "Created At", "description": "Creation timestamp." }, "updated_at": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$", "format": "date-time", "title": "Updated At", "description": "Last update timestamp." } }, "type": "object", "required": [ "id", "title", "url", "description", "status", "visibility", "scheduled_start_at", "ended_at", "thumbnail", "created_at", "updated_at" ], "title": "Show", "example": { "created_at": "2026-09-20T18:30:00.000Z", "description": "Vintage and modern breaks, giveaways every 30 minutes.", "id": "0b6f3c1e-8a52-4d2e-9f7a-3c5d1e2f4a6b", "scheduled_start_at": "2026-09-27T01:00:00.000Z", "status": "scheduled", "thumbnail": { "id": "12345", "url": "https://images.whatnot.com/thumbnail.jpg" }, "title": "Sunday Night Pokémon Breaks", "updated_at": "2026-09-21T09:15:00.000Z", "url": "https://www.whatnot.com/dashboard/lives/edit/0b6f3c1e-8a52-4d2e-9f7a-3c5d1e2f4a6b", "visibility": "public" } }, "ShowAnalytics": { "properties": { "show_id": { "type": "string", "title": "Show Id", "description": "The show these analytics describe." }, "title": { "type": "string", "title": "Title", "description": "The show's title." }, "start_time": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$", "format": "date-time", "title": "Start Time", "description": "When the show started." }, "calculation_status": { "anyOf": [ { "$ref": "#/components/schemas/ShowAnalyticsStatus" }, { "type": "null" } ], "description": "WILL_NOT_BE_CALCULATED if the show was cancelled, is private or is a rehearsal, so no analytics will ever exist. NOT_ENDED while the show has not ended, so no analytics exist yet. PENDING once it has ended but the metrics are still being calculated. GENERATED once they are final. Metrics are null unless GENERATED." }, "sales": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "Gross sales." }, "estimated_earnings": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "Estimated earnings; can be negative after refunds and fees." }, "orders_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Orders Count", "description": "Number of orders." }, "average_order_value": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "Average order value." }, "giveaway_orders_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Giveaway Orders Count", "description": "Number of giveaway orders." }, "giveaway_spend": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "Amount spent on giveaways; can be negative." }, "show_impression_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Show Impression Count", "description": "Number of times the show was shown to viewers." }, "show_clickthrough_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Show Clickthrough Rate", "description": "Percentage of impressions that were tapped, to two decimal places. Null when there were no impressions." }, "buyers_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Buyers Count", "description": "Number of distinct buyers." }, "first_time_buyers_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "First Time Buyers Count", "description": "Buyers purchasing from the seller for the first time." }, "returning_buyers_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Returning Buyers Count", "description": "Buyers who had purchased from the seller before." }, "giveaway_winners_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Giveaway Winners Count", "description": "Number of distinct giveaway winners." }, "first_time_giveaway_winners_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "First Time Giveaway Winners Count", "description": "Giveaway winners who had not bought from the seller before." }, "returning_giveaway_winners_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Returning Giveaway Winners Count", "description": "Giveaway winners who had bought from the seller before." }, "buyer_shares_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Buyer Shares Count", "description": "Number of times buyers shared the show." }, "stream_minutes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Stream Minutes", "description": "Minutes the show ran." }, "max_concurrent_viewers": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Concurrent Viewers", "description": "Peak number of simultaneous viewers." }, "total_views": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Views", "description": "Total views." }, "distinct_viewers_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Distinct Viewers Count", "description": "Number of distinct viewers." }, "average_rating": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Average Rating", "description": "Average viewer rating of the show." } }, "type": "object", "required": [ "show_id", "title", "start_time", "calculation_status", "sales", "estimated_earnings", "orders_count", "average_order_value", "giveaway_orders_count", "giveaway_spend", "show_impression_count", "show_clickthrough_rate", "buyers_count", "first_time_buyers_count", "returning_buyers_count", "giveaway_winners_count", "first_time_giveaway_winners_count", "returning_giveaway_winners_count", "buyer_shares_count", "stream_minutes", "max_concurrent_viewers", "total_views", "distinct_viewers_count", "average_rating" ], "title": "ShowAnalytics" }, "ShowAnalyticsStatus": { "type": "string", "enum": [ "WILL_NOT_BE_CALCULATED", "NOT_ENDED", "PENDING", "GENERATED" ], "title": "ShowAnalyticsStatus" }, "ShowStartTimeRange": { "properties": { "start": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$", "format": "date-time", "title": "Start", "description": "Include only shows that started at or after this time." }, "end": { "anyOf": [ { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$", "format": "date-time" }, { "type": "null" } ], "title": "End", "description": "Include only shows that started at or before this time. Defaults to the end of the current hour." } }, "additionalProperties": false, "type": "object", "required": [ "start" ], "title": "ShowStartTimeRange" }, "ShowStatus": { "type": "string", "enum": [ "scheduled", "live", "stopped", "ended", "cancelled" ], "title": "ShowStatus" }, "ShowStrategy": { "type": "string", "enum": [ "ADD", "REMOVE", "REPLACE" ], "title": "ShowStrategy", "description": "The public, user-facing values for reconciling a product's shows." }, "ShowVisibility": { "type": "string", "enum": [ "public", "private" ], "title": "ShowVisibility" }, "ShowsInput": { "properties": { "strategy": { "$ref": "#/components/schemas/ShowStrategy", "description": "ADD leaves the product's other shows untouched and adds these; REMOVE takes it off these shows; REPLACE makes these the product's only shows, removing it from any others." }, "show_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "maxItems": 25, "title": "Show Ids", "description": "The shows to add or remove, by show ID. For replace, the product's complete set of shows after the call; an empty list removes it from every show." } }, "additionalProperties": false, "type": "object", "required": [ "strategy", "show_ids" ], "title": "ShowsInput", "description": "The requested change to which shows a product appears in." }, "SpecificShows": { "properties": { "show_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "maxItems": 100, "minItems": 1, "title": "Show Ids", "description": "The shows to report on, in the order their rows appear. Every show must be hosted by the seller." } }, "additionalProperties": false, "type": "object", "required": [ "show_ids" ], "title": "SpecificShows" }, "TransactionType": { "type": "string", "enum": [ "buy_it_now", "auction", "giveaway" ], "title": "TransactionType", "description": "The public, user-facing transaction type values." }, "User": { "properties": { "id": { "type": "string", "title": "Id", "description": "The user's ID, encoded as a decimal string." }, "username": { "type": "string", "title": "Username", "description": "The user's username." }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Display Name", "description": "The user's display name, if set." }, "image": { "anyOf": [ { "$ref": "#/components/schemas/Media" }, { "type": "null" } ], "description": "The user's profile image, if set." }, "seller_currency": { "type": "string", "title": "Seller Currency", "description": "The seller's ISO 4217 currency code." }, "country_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country Code", "description": "The user's ISO 3166-1 alpha-2 country code." }, "can_go_live": { "type": "boolean", "title": "Can Go Live", "description": "Whether the user is allowed to go live." } }, "type": "object", "required": [ "id", "username", "display_name", "image", "seller_currency", "country_code", "can_go_live" ], "title": "User" }, "UserSummary": { "properties": { "id": { "type": "string", "title": "Id", "description": "The user's decimal ID." }, "username": { "type": "string", "title": "Username", "description": "The user's username." }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Display Name", "description": "The user's display name." } }, "type": "object", "required": [ "id", "username", "display_name" ], "title": "UserSummary" }, "VariantAuction": { "properties": { "start_price": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "Auction start price." } }, "type": "object", "required": [ "start_price" ], "title": "VariantAuction" }, "VariantAuctionInput": { "properties": { "start_price": { "$ref": "#/components/schemas/Money", "description": "Auction start price, in whole currency units." } }, "additionalProperties": false, "type": "object", "required": [ "start_price" ], "title": "VariantAuctionInput" }, "VariantBatchResult": { "properties": { "variants": { "items": { "$ref": "#/components/schemas/ProductVariant" }, "type": "array", "title": "Variants", "description": "The updated variants, in input order." }, "errors": { "anyOf": [ { "items": { "$ref": "#/components/schemas/VariantError" }, "type": "array" }, { "type": "null" } ], "title": "Errors", "description": "Patches that were not applied, in input order. Present only when allow_partial_updates is true." } }, "type": "object", "required": [ "variants" ], "title": "VariantBatchResult" }, "VariantBuyItNow": { "properties": { "price": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "Buy-it-now price." } }, "type": "object", "required": [ "price" ], "title": "VariantBuyItNow" }, "VariantBuyItNowInput": { "properties": { "price": { "$ref": "#/components/schemas/Money", "description": "Buy-it-now price, in whole currency units." } }, "additionalProperties": false, "type": "object", "required": [ "price" ], "title": "VariantBuyItNowInput" }, "VariantError": { "properties": { "id": { "type": "string", "title": "Id", "description": "The patch's id, echoed from input." }, "code": { "type": "string", "enum": [ "variant_not_found", "variant_not_editable", "pricing_not_supported", "variants_not_supported" ], "title": "Code", "description": "Why the patch was not applied." }, "message": { "type": "string", "title": "Message", "description": "A human-readable explanation." } }, "type": "object", "required": [ "id", "code", "message" ], "title": "VariantError" }, "VariantInventory": { "properties": { "available_quantity": { "type": "integer", "title": "Available Quantity", "description": "Available inventory quantity." } }, "type": "object", "required": [ "available_quantity" ], "title": "VariantInventory" }, "VariantPricing": { "properties": { "buy_it_now": { "$ref": "#/components/schemas/VariantBuyItNow" }, "auction": { "$ref": "#/components/schemas/VariantAuction" } }, "type": "object", "required": [ "buy_it_now", "auction" ], "title": "VariantPricing" }, "VariantPricingInput": { "properties": { "buy_it_now": { "anyOf": [ { "$ref": "#/components/schemas/VariantBuyItNowInput" }, { "type": "null" } ] }, "auction": { "anyOf": [ { "$ref": "#/components/schemas/VariantAuctionInput" }, { "type": "null" } ] } }, "additionalProperties": false, "type": "object", "title": "VariantPricingInput", "description": "Prices to stage per format. An omitted format is left unchanged." }, "Weight": { "properties": { "value": { "type": "number", "title": "Value", "description": "The weight amount." }, "unit": { "$ref": "#/components/schemas/WeightUnit", "description": "The weight unit." } }, "type": "object", "required": [ "value", "unit" ], "title": "Weight" }, "WeightUnit": { "type": "string", "enum": [ "ounce", "pound", "gram", "kilogram" ], "title": "WeightUnit", "description": "The unit used to express weight." }, "GenerateReportRequest": { "properties": { "report_parameters": { "oneOf": [ { "$ref": "#/components/schemas/FinancialReportParameters" }, { "$ref": "#/components/schemas/AnalyticsOverviewReportParameters" }, { "$ref": "#/components/schemas/LivestreamsReportParameters" } ], "title": "Report Parameters", "description": "The parameters of the report to generate. `report_type` selects the kind of report and the other fields it accepts.", "discriminator": { "propertyName": "report_type", "mapping": { "analytics_livestreams_report": "#/components/schemas/LivestreamsReportParameters", "analytics_overview_report": "#/components/schemas/AnalyticsOverviewReportParameters", "seller_financial_report": "#/components/schemas/FinancialReportParameters" } } } }, "additionalProperties": false, "type": "object", "required": [ "report_parameters" ], "title": "GenerateReportRequest", "example": { "report_parameters": { "end_date": "2026-09-08T00:00:00.000Z", "report_type": "seller_financial_report", "start_date": "2026-09-01T00:00:00.000Z" } } }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "LabelGenerationAcceptedResponse": { "properties": { "shipment_id": { "type": "string", "title": "Shipment Id", "description": "Shipment whose label generation was requested." } }, "type": "object", "required": [ "shipment_id" ], "title": "LabelGenerationAcceptedResponse" }, "MerchandiseProductRequest": { "properties": { "transaction_type": { "anyOf": [ { "$ref": "#/components/schemas/MerchandisingTransactionType" }, { "type": "null" } ], "description": "The product's sale format. When provided, overwrites the format on the product. Auctions are always reserved for live and are sold only in shows; add the product to one with shows, in this call or a later one, or it is not purchasable anywhere." }, "reserve_for_live": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Reserve For Live", "description": "Whether the product is held for live shows only. Auctions are always reserved for live, so this is rejected as false when transaction_type is auction in the same request, and ignored for a product that is already an auction. A buy-it-now product is purchasable on the seller's profile shop only when this is not true. When omitted, the product's current choice is kept. A draft buy-it-now product with no choice yet is treated as false when transaction_type is set, which publishes it to the profile shop. Switching to auction records the product as reserved for live, so switching back to buy-it-now keeps it off the profile shop until this is sent as false." }, "shows": { "anyOf": [ { "$ref": "#/components/schemas/ShowsInput" }, { "type": "null" } ], "description": "The change to which shows the product appears in. Adding a product to a show that is not among the seller's next upcoming shows is applied in the background. Omit to leave the product's shows unchanged." } }, "additionalProperties": false, "type": "object", "title": "MerchandiseProductRequest", "description": "Merchandising changes to apply to a product in a single call.\n\nEvery field is optional; an omitted field leaves that facet unchanged. The\nchanges are applied together: transaction type first, then show membership,\nthen profile-shop publication.", "example": { "reserve_for_live": false, "shows": { "show_ids": [ "0b6f3c1e-8a52-4d2e-9f7a-3c5d1e2f4a6b" ], "strategy": "ADD" }, "transaction_type": "buy_it_now" } }, "MerchandiseProductResponse": { "properties": { "product_id": { "type": "string", "title": "Product Id", "description": "The product that was merchandised." }, "transaction_type": { "anyOf": [ { "$ref": "#/components/schemas/TransactionType" }, { "type": "null" } ], "description": "The product's sale format after the call." }, "reserved_for_live": { "type": "boolean", "title": "Reserved For Live", "description": "Whether the product is sold only in live shows. Auctions are always reserved for live. A buy-it-now product that is not reserved for live is listed for sale on the seller's profile shop." } }, "type": "object", "required": [ "product_id", "transaction_type", "reserved_for_live" ], "title": "MerchandiseProductResponse", "description": "The outcome of a merchandising call for a product.", "example": { "product_id": "12345", "reserved_for_live": false, "transaction_type": "buy_it_now" } }, "PageResponse_DimensionProfile_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/DimensionProfile" }, "type": "array", "title": "Data", "description": "Results in the requested order." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Continuation cursor; null when there are no more results." } }, "type": "object", "required": [ "data", "next_cursor" ], "title": "PageResponse[DimensionProfile]" }, "PageResponse_OrderItem_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/OrderItem" }, "type": "array", "title": "Data", "description": "Results in the requested order." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Continuation cursor; null when there are no more results." } }, "type": "object", "required": [ "data", "next_cursor" ], "title": "PageResponse[OrderItem]" }, "PageResponse_Order_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Order" }, "type": "array", "title": "Data", "description": "Results in the requested order." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Continuation cursor; null when there are no more results." } }, "type": "object", "required": [ "data", "next_cursor" ], "title": "PageResponse[Order]" }, "PageResponse_ProductVariant_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ProductVariant" }, "type": "array", "title": "Data", "description": "Results in the requested order." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Continuation cursor; null when there are no more results." } }, "type": "object", "required": [ "data", "next_cursor" ], "title": "PageResponse[ProductVariant]" }, "PageResponse_Product_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Product" }, "type": "array", "title": "Data", "description": "Results in the requested order." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Continuation cursor; null when there are no more results." } }, "type": "object", "required": [ "data", "next_cursor" ], "title": "PageResponse[Product]" }, "PageResponse_Report_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Report" }, "type": "array", "title": "Data", "description": "Results in the requested order." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Continuation cursor; null when there are no more results." } }, "type": "object", "required": [ "data", "next_cursor" ], "title": "PageResponse[Report]" }, "PageResponse_ShipmentItem_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ShipmentItem" }, "type": "array", "title": "Data", "description": "Results in the requested order." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Continuation cursor; null when there are no more results." } }, "type": "object", "required": [ "data", "next_cursor" ], "title": "PageResponse[ShipmentItem]" }, "PageResponse_Shipment_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Shipment" }, "type": "array", "title": "Data", "description": "Results in the requested order." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Continuation cursor; null when there are no more results." } }, "type": "object", "required": [ "data", "next_cursor" ], "title": "PageResponse[Shipment]" }, "PageResponse_Show_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Show" }, "type": "array", "title": "Data", "description": "Results in the requested order." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Continuation cursor; null when there are no more results." } }, "type": "object", "required": [ "data", "next_cursor" ], "title": "PageResponse[Show]" }, "RootResponse": { "properties": { "status": { "type": "string", "title": "Status", "description": "Current API status.", "examples": [ "ok" ] } }, "type": "object", "required": [ "status" ], "title": "RootResponse" }, "SetInventoryLevelsRequest": { "properties": { "items": { "items": { "$ref": "#/components/schemas/SetInventoryItem" }, "type": "array", "maxItems": 10, "minItems": 1, "title": "Items", "description": "The variants to set, applied independently. At most 10 items per request." } }, "additionalProperties": false, "type": "object", "required": [ "items" ], "title": "SetInventoryLevelsRequest" }, "UpdateProductRequest": { "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title", "description": "The product's title." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "The product's description." }, "external_id": { "anyOf": [ { "type": "string", "maxLength": 150 }, { "type": "null" } ], "title": "External Id", "description": "The seller-provided external identifier for the product." }, "category": { "anyOf": [ { "$ref": "#/components/schemas/Category" }, { "type": "null" } ], "description": "The product's category." }, "attributes": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ProductAttribute" }, "type": "array" }, { "type": "null" } ], "title": "Attributes", "description": "The product's attribute values." }, "options": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ProductOption" }, "type": "array", "maxItems": 3 }, { "type": "null" } ], "title": "Options", "description": "The product's option axes (e.g. Color, Size)." }, "media": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Media" }, "type": "array" }, { "type": "null" } ], "title": "Media", "description": "The product's images." }, "dimension_profile": { "anyOf": [ { "$ref": "#/components/schemas/DimensionProfile" }, { "type": "null" } ], "description": "The product's dimension profile." } }, "additionalProperties": false, "type": "object", "title": "UpdateProductRequest", "description": "The mutable fields for a partial product update." }, "UpdateProductVariantsRequest": { "properties": { "variants": { "items": { "$ref": "#/components/schemas/ProductVariantPatch" }, "type": "array", "maxItems": 10, "minItems": 1, "title": "Variants", "description": "The variant patches, each keyed by id. At most 10 per request, and each id at most once." }, "allow_partial_updates": { "type": "boolean", "title": "Allow Partial Updates", "description": "When true, valid variants are applied and failures are returned in errors. When false, any invalid variant rejects the whole batch with a 422 and nothing is written.", "default": false } }, "additionalProperties": false, "type": "object", "required": [ "variants" ], "title": "UpdateProductVariantsRequest" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } }, "securitySchemes": { "OAuth2": { "type": "oauth2", "description": "OAuth 2.0 authorization code flow against the Seller API's own authorization server.", "oauth2MetadataUrl": "https://api.whatnot.com/.well-known/oauth-authorization-server/seller-api", "flows": { "authorizationCode": { "authorizationUrl": "https://api.whatnot.com/seller-api/rest/oauth/authorize", "tokenUrl": "https://api.whatnot.com/seller-api/rest/oauth/token", "scopes": { "read:inventory": "Read your product inventory", "write:inventory": "Write to your product inventory", "read:merchandising": "Read how and where your products are sold", "write:merchandising": "Change how and where your products are sold", "read:orders": "Read your orders", "write:orders": "Write to your orders", "read:shipments": "Retrieve your shipment details", "write:shipments": "Make changes to your shipments (including generating a shipping label)", "read:customers": "Read your customer's information such as address, email, and phone number", "read:reports": "Read your financial reports", "write:reports": "Generate reports about your finances", "read:shows": "Read your shows" } } } } } }, "tags": [ { "name": "Analytics", "description": "Retrieve analytics for a seller's shows. Currently this covers a single show; more analytics endpoints will be added under this resource." }, { "name": "Inventory", "description": "Set and adjust available quantity on product variants." }, { "name": "Merchandising", "description": "Manage a product's sale format, show lineup, and profile-shop publication." }, { "name": "Orders", "description": "Retrieve and act on orders." }, { "name": "Products", "description": "Create and manage products in a seller's catalog.\n\nA product holds what buyers see: title, description, images, category, and the options it comes in, such as Color or Size. Each variant is one purchasable version of the product, such as Red / Small, and that is where its price, image, and inventory are set. A product with no options still has one variant.\n\nCreating a product does not put it on sale. Whatnot creates the variants for you, with no price, image, or inventory, so a new product is sellable only after you complete these steps in order:\n\n1. Create the product with `POST /products`. One variant is created for every combination of its option values.\n2. Get its variants with `GET /products/{product_id}/variants` to get their ids.\n3. Set each variant's price for the format you will sell it in (`pricing.buy_it_now.price` or `pricing.auction.start_price`) and its image (`media`, at most one) with `PATCH /products/{product_id}/variants`, and its inventory with `POST /inventory/set`.\n4. Put the product on sale with `POST /merchandising/products/{product_id}`. Set `transaction_type` to `buy_it_now` or `auction`, and use `shows` to add it to shows. A buy-it-now product is sold on your profile shop unless `reserve_for_live` is true; auctions are always reserved for live. Every variant must be priced for that format and at least one must have inventory.\n\nA product with no options follows the same steps. Its single variant appears in `GET /products/{product_id}/variants`, and that is where you price it, set its image, and set its inventory. Adding options or option values later creates new variants that also start without a price, an image, or inventory. Set their price, image, and inventory the same way." }, { "name": "Reports and Statements", "description": "Request and retrieve the seller's generated reports and statements. See [Reports and Statements](/reports) for each report type's CSV columns." }, { "name": "Shipments", "description": "Retrieve and fulfill seller shipments." }, { "name": "Shipping", "description": "Retrieve a seller's shipping configuration, such as dimension profiles." }, { "name": "Shows", "description": "Retrieve the seller's shows." }, { "name": "Users", "description": "Retrieve the current seller and disconnect the calling application." } ], "security": [ { "OAuth2": [] } ], "x-artifact-schemas": { "seller-report-artifacts": { "seller_financial_report": { "description": "One CSV row per transaction. Field order is the CSV column order.\n\nThe CSV header is this TypedDict's own fields, so a column added to the\npage query must be added here too (a test enforces it). These are this\nmodule's own names, not all identical to the real table's: the SQL\naliases shipping_fee/tax_on_commission_fee/payment_processing_fee/\ntax_on_payment_processing_fee to the names below (see the page query). The\nreal table (models/products/receipts/migration/docs/\ntreasury__seller_earnings_and_costs.yml in Whatnot-Inc/dbt) also has no\ncolumn for buyer_shipping_paid or sales_tax_collected, so this report does\nnot carry them; snapshot_at and report_start_date exist on that table but\nare not selected here either.", "properties": { "transaction_completed_at_utc": { "description": "When this ledger transaction completed, in UTC.", "format": "date-time", "title": "Transaction Completed At Utc", "type": "string" }, "order_placed_at_utc": { "description": "When the order was placed, in UTC. Null for a transaction not tied to a specific order, such as a shipping charge, carrier adjustment, or tip.", "format": "date-time", "title": "Order Placed At Utc", "type": "string" }, "seller_id": { "description": "The ID of the seller this report is for.", "title": "Seller Id", "type": "string" }, "transaction_type": { "description": "The kind of ledger transaction: ORDER_EARNINGS, SHIPPING_CHARGE, CARRIER_ADJUSTMENT, CARRIER_ADJUSTMENT_REFUND, ORDER_REFUND, ORDER_REFUND_SHIPPING_COSTS, APPEALED_ORDER_REFUND, APPEALED_ORDER_REFUND_SHIPPING_COSTS, or TIP.", "title": "Transaction Type", "type": "string" }, "transaction_message": { "description": "A human-readable note recorded on the ledger transaction.", "title": "Transaction Message", "type": "string" }, "order_id": { "description": "The order this transaction is for. Null for a transaction not tied to a specific order, such as a carrier adjustment or tip.", "title": "Order Id", "type": "string" }, "listing_title": { "description": "The title of the listing sold. Set only for ORDER_EARNINGS.", "title": "Listing Title", "type": "string" }, "listing_description": { "description": "The description of the listing sold. Set only for ORDER_EARNINGS.", "title": "Listing Description", "type": "string" }, "product_category": { "description": "The category of the product sold. Set only for ORDER_EARNINGS.", "title": "Product Category", "type": "string" }, "buy_format": { "description": "How the item was sold, such as auction or buy it now. Set only for ORDER_EARNINGS.", "title": "Buy Format", "type": "string" }, "sale_type": { "description": "FLASH when the item was sold as part of a flash sale, otherwise null. Set only for ORDER_EARNINGS.", "title": "Sale Type", "type": "string" }, "quantity_sold": { "description": "The quantity of the item sold. Set only for ORDER_EARNINGS.", "title": "Quantity Sold", "type": "integer" }, "sku": { "description": "The SKU of the item sold. Set only for ORDER_EARNINGS.", "title": "Sku", "type": "string" }, "cost_of_goods": { "description": "The seller's recorded per-item cost for the item sold, in major currency units. Set only for ORDER_EARNINGS.", "title": "Cost Of Goods", "type": "number" }, "livestream_id": { "description": "The show this transaction is associated with. Null for a transaction not tied to a show, such as a carrier adjustment or an order placed outside a show.", "title": "Livestream Id", "type": "string" }, "livestream_title": { "description": "The title of the associated show.", "title": "Livestream Title", "type": "string" }, "buyer_name": { "description": "The buyer's username. Set only for ORDER_EARNINGS and TIP transactions.", "title": "Buyer Name", "type": "string" }, "buyer_state": { "description": "The buyer's shipping address state. Set only for ORDER_EARNINGS.", "title": "Buyer State", "type": "string" }, "buyer_country": { "description": "The buyer's shipping address country code. Set only for ORDER_EARNINGS.", "title": "Buyer Country", "type": "string" }, "shipment_id": { "description": "The shipment this transaction is associated with. Null for a transaction not tied to a shipment, such as a tip.", "title": "Shipment Id", "type": "string" }, "transaction_currency": { "description": "The currency transaction_amount and the fee columns are in.", "title": "Transaction Currency", "type": "string" }, "transaction_amount": { "description": "The signed amount of this ledger transaction, in major currency units. Negative for charges and refunds.", "title": "Transaction Amount", "type": "number" }, "buyer_paid": { "description": "The order's total amount charged to the buyer, in major currency units. Set only for ORDER_EARNINGS.", "title": "Buyer Paid", "type": "number" }, "original_item_price": { "description": "The item's price before any seller-generated coupon was applied, in major currency units. Set only for ORDER_EARNINGS.", "title": "Original Item Price", "type": "number" }, "coupon_cost": { "description": "The seller-generated coupon amount applied to the order, in major currency units; negative when a coupon was applied. Set only for ORDER_EARNINGS.", "title": "Coupon Cost", "type": "number" }, "post_coupon_price": { "description": "The item's price after any seller-generated coupon was applied: original_item_price plus coupon_cost. Set only for ORDER_EARNINGS.", "title": "Post Coupon Price", "type": "number" }, "seller_shipping_charge": { "description": "Shipping costs paid by the seller on this order, in major currency units. Set only for ORDER_EARNINGS.", "title": "Seller Shipping Charge", "type": "number" }, "commission_fee": { "description": "Whatnot's commission on this order, in major currency units. Set only for ORDER_EARNINGS.", "title": "Commission Fee", "type": "number" }, "commission_tax": { "description": "Tax charged on commission_fee, in major currency units. Set only for ORDER_EARNINGS.", "title": "Commission Tax", "type": "number" }, "processing_fee": { "description": "Payment processing fee charged on this order, in major currency units. Set only for ORDER_EARNINGS.", "title": "Processing Fee", "type": "number" }, "processing_fee_tax": { "description": "Tax charged on processing_fee, in major currency units. Set only for ORDER_EARNINGS.", "title": "Processing Fee Tax", "type": "number" }, "ledger_transaction_id": { "description": "The ID of the underlying ledger transaction.", "title": "Ledger Transaction Id", "type": "string" } }, "required": [ "transaction_completed_at_utc", "order_placed_at_utc", "seller_id", "transaction_type", "transaction_message", "order_id", "listing_title", "listing_description", "product_category", "buy_format", "sale_type", "quantity_sold", "sku", "cost_of_goods", "livestream_id", "livestream_title", "buyer_name", "buyer_state", "buyer_country", "shipment_id", "transaction_currency", "transaction_amount", "buyer_paid", "original_item_price", "coupon_cost", "post_coupon_price", "seller_shipping_charge", "commission_fee", "commission_tax", "processing_fee", "processing_fee_tax", "ledger_transaction_id" ], "title": "FinancialReportRow", "type": "object" }, "analytics_overview_report": { "description": "One CSV row per calendar day. Field order is the CSV column order.\n\nEvery field but `date` and `currency` is `None` for a day with no record\nin any Laser family. A CSV writer renders `None` as an empty cell, so\nthat day is blank rather than a row of zeros: no activity, not activity\ntotalling zero.", "properties": { "date": { "description": "The calendar day this row covers, in ISO 8601.", "title": "Date", "type": "string" }, "currency": { "description": "The currency the money fields in this row are denominated in.", "title": "Currency", "type": "string" }, "estimated_sales": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The sum of the final purchase prices of completed orders, after any seller-generated coupons have been applied. Does not include shipping costs, taxes, or non-order revenue like tips.", "title": "Estimated Sales" }, "in_show_estimated_sales": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Estimated sales from orders placed during a show.", "title": "In Show Estimated Sales" }, "marketplace_estimated_sales": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Estimated sales from orders placed on the profile shop outside a show.", "title": "Marketplace Estimated Sales" }, "estimated_earnings": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Estimated sales for completed orders minus fees and costs, such as commission, payment processing fees, and seller-paid shipping costs.", "title": "Estimated Earnings" }, "in_show_estimated_earnings": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Estimated earnings from orders placed during a show.", "title": "In Show Estimated Earnings" }, "marketplace_estimated_earnings": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Estimated earnings from orders placed on the profile shop outside a show.", "title": "Marketplace Estimated Earnings" }, "orders_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The number of unique transactions paid for by buyers.", "title": "Orders Count" }, "in_show_orders_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The number of orders placed during a show.", "title": "In Show Orders Count" }, "marketplace_orders_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The number of orders placed on the profile shop outside a show.", "title": "Marketplace Orders Count" }, "giveaway_orders_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The number of giveaway orders.", "title": "Giveaway Orders Count" }, "average_order_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The average final purchase price of each completed order, calculated by dividing estimated sales by orders.", "title": "Average Order Value" }, "buyers_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The number of unique buyers who completed a purchase.", "title": "Buyers Count" }, "new_buyers_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The number of unique buyers who bought from the seller for the first time.", "title": "New Buyers Count" }, "returning_buyers_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The number of unique buyers who had bought from the seller before and bought again.", "title": "Returning Buyers Count" }, "follows_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The number of people who followed the seller.", "title": "Follows Count" }, "referral_follows_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The number of follows that came from a referral.", "title": "Referral Follows Count" }, "non_referral_follows_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The number of follows that did not come from a referral.", "title": "Non Referral Follows Count" }, "livestreams_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The number of shows the seller went live for.", "title": "Livestreams Count" }, "stream_minutes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The total duration of the seller's shows, in minutes.", "title": "Stream Minutes" }, "viewers_per_hour": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The average number of unique viewers per hour.", "title": "Viewers Per Hour" }, "average_watch_time_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The average length of time each viewer watched, in seconds.", "title": "Average Watch Time Seconds" } }, "required": [ "date", "currency", "estimated_sales", "in_show_estimated_sales", "marketplace_estimated_sales", "estimated_earnings", "in_show_estimated_earnings", "marketplace_estimated_earnings", "orders_count", "in_show_orders_count", "marketplace_orders_count", "giveaway_orders_count", "average_order_value", "buyers_count", "new_buyers_count", "returning_buyers_count", "follows_count", "referral_follows_count", "non_referral_follows_count", "livestreams_count", "stream_minutes", "viewers_per_hour", "average_watch_time_seconds" ], "title": "OverviewAnalyticsReportRow", "type": "object" }, "analytics_livestreams_report": { "description": "One CSV row per livestream. Field order is the CSV column order.", "properties": { "livestream_id": { "description": "The ID of the show this row covers.", "title": "Livestream Id", "type": "string" }, "livestream_title": { "description": "The title of the show.", "title": "Livestream Title", "type": "string" }, "start_time": { "description": "When the show started.", "format": "date-time", "title": "Start Time", "type": "string" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The currency the money fields in this row are denominated in. Null when the show has no sales, earnings, or giveaway spend.", "title": "Currency" }, "livestream_impression_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Times the show's thumbnail appeared in the feed or in search before the show ended.", "title": "Livestream Impression Count" }, "livestream_clickthrough_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The percentage of people who clicked into the show after seeing its thumbnail in the feed or search before the show ended.", "title": "Livestream Clickthrough Rate" }, "sales": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Total sales from orders in this show, excluding shipping, taxes, and tips.", "title": "Sales" }, "estimated_earnings": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Estimated sales minus fees and costs, such as Whatnot's commission, payment processing fees, and seller-paid shipping costs.", "title": "Estimated Earnings" }, "orders_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The number of unique transactions paid for by buyers during this show.", "title": "Orders Count" }, "average_order_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The average final purchase price of each completed order.", "title": "Average Order Value" }, "giveaway_orders_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The number of giveaway orders during this show.", "title": "Giveaway Orders Count" }, "giveaway_spend": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Total shipping costs on giveaway orders from this show.", "title": "Giveaway Spend" }, "buyers_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The total number of unique buyers who bought from the seller during this show.", "title": "Buyers Count" }, "first_time_buyers_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The number of unique buyers who bought from the seller for the first time during this show.", "title": "First Time Buyers Count" }, "returning_buyers_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The number of unique buyers who had bought from the seller before and bought again during this show.", "title": "Returning Buyers Count" }, "giveaway_winners_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The number of unique buyers who won a giveaway during this show.", "title": "Giveaway Winners Count" }, "first_time_giveaway_winners_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The number of unique buyers who won a giveaway from the seller for the first time during this show.", "title": "First Time Giveaway Winners Count" }, "returning_giveaway_winners_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The number of unique buyers who had won a giveaway from the seller before and won again during this show.", "title": "Returning Giveaway Winners Count" }, "buyer_shares_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The number of times the show was shared by users.", "title": "Buyer Shares Count" }, "stream_minutes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The total duration of the show, in minutes.", "title": "Stream Minutes" }, "max_concurrent_viewers": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The highest number of viewers watching the show at one given time.", "title": "Max Concurrent Viewers" }, "total_views": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The total number of times viewers watched the show for 30 seconds or more. A viewer can count more than once if they leave and rejoin.", "title": "Total Views" }, "distinct_viewers_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The total number of unique viewers who watched the show for 30 seconds or more.", "title": "Distinct Viewers Count" }, "average_rating": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The average rating buyers gave for orders from this show.", "title": "Average Rating" } }, "required": [ "livestream_id", "livestream_title", "start_time", "currency", "livestream_impression_count", "livestream_clickthrough_rate", "sales", "estimated_earnings", "orders_count", "average_order_value", "giveaway_orders_count", "giveaway_spend", "buyers_count", "first_time_buyers_count", "returning_buyers_count", "giveaway_winners_count", "first_time_giveaway_winners_count", "returning_giveaway_winners_count", "buyer_shares_count", "stream_minutes", "max_concurrent_viewers", "total_views", "distinct_viewers_count", "average_rating" ], "title": "LivestreamAnalyticsReportRow", "type": "object" }, "analytics_show_details_report": { "description": "One row per show. Field order is the CSV column order.", "properties": { "show": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The show's title.", "title": "Show" }, "start_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the show started.", "title": "Start Time" }, "duration_minutes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The show's length, in minutes.", "title": "Duration Minutes" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The show's product category.", "title": "Category" }, "thumbnail_impressions": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "How many times the show's thumbnail was shown in feeds.", "title": "Thumbnail Impressions" }, "thumbnail_ctr": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Share of thumbnail impressions that were tapped, in percentage points.", "title": "Thumbnail Ctr" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO currency code of the money fields in this row (estimated_sales, estimated_earnings, estimated_aov, sales_per_hour, giveaway_shipping_cost).", "title": "Currency" }, "estimated_sales": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Total sales from orders in this show, excluding shipping, taxes, and tips.", "title": "Estimated Sales" }, "estimated_sales_benchmark": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change in estimated_sales against the seller's own trailing average, in percentage points.", "title": "Estimated Sales Benchmark" }, "estimated_sales_benchmark_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What estimated_sales_benchmark is compared against.", "title": "Estimated Sales Benchmark Label" }, "estimated_earnings": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Estimated sales minus fees and costs (commission, payment processing, seller-paid shipping).", "title": "Estimated Earnings" }, "estimated_earnings_benchmark": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change in estimated_earnings against the seller's own trailing average, in percentage points.", "title": "Estimated Earnings Benchmark" }, "estimated_earnings_benchmark_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What estimated_earnings_benchmark is compared against.", "title": "Estimated Earnings Benchmark Label" }, "estimated_orders": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Estimated number of completed orders in this show, excluding cancellations.", "title": "Estimated Orders" }, "estimated_orders_benchmark": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change in estimated_orders against the seller's own trailing average, in percentage points.", "title": "Estimated Orders Benchmark" }, "estimated_orders_benchmark_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What estimated_orders_benchmark is compared against.", "title": "Estimated Orders Benchmark Label" }, "estimated_aov": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Average order value for this show (estimated_sales divided by estimated_orders).", "title": "Estimated Aov" }, "estimated_aov_benchmark": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change in estimated_aov against the seller's own trailing average, in percentage points.", "title": "Estimated Aov Benchmark" }, "estimated_aov_benchmark_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What estimated_aov_benchmark is compared against.", "title": "Estimated Aov Benchmark Label" }, "sales_per_hour": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "estimated_sales divided by the show's duration in hours.", "title": "Sales Per Hour" }, "sales_per_hour_benchmark": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change in sales_per_hour against the seller's own trailing average, in percentage points.", "title": "Sales Per Hour Benchmark" }, "sales_per_hour_benchmark_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What sales_per_hour_benchmark is compared against.", "title": "Sales Per Hour Benchmark Label" }, "orders_per_hour": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "estimated_orders divided by the show's duration in hours.", "title": "Orders Per Hour" }, "orders_per_hour_benchmark": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change in orders_per_hour against the seller's own trailing average, in percentage points.", "title": "Orders Per Hour Benchmark" }, "orders_per_hour_benchmark_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What orders_per_hour_benchmark is compared against.", "title": "Orders Per Hour Benchmark Label" }, "total_giveaway_orders": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of giveaway orders in this show.", "title": "Total Giveaway Orders" }, "buyer_giveaway_orders": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of buyer-appreciation giveaway orders in this show.", "title": "Buyer Giveaway Orders" }, "giveaway_shipping_cost": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The seller's total shipping cost on giveaway orders in this show.", "title": "Giveaway Shipping Cost" }, "giveaways_per_hour": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "total_giveaway_orders divided by the show's duration in hours.", "title": "Giveaways Per Hour" }, "unique_giveaway_entries": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Distinct people who entered any giveaway in this show, counted once each across giveaways.", "title": "Unique Giveaway Entries" }, "unique_giveaway_winners": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Distinct giveaway winners in this show.", "title": "Unique Giveaway Winners" }, "new_followers_from_giveaways": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "New followers gained as a result of giveaways in this show.", "title": "New Followers From Giveaways" }, "total_views": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Total times viewers watched this show for more than 30 seconds; a viewer can count more than once if they leave and rejoin.", "title": "Total Views" }, "max_concurrent_viewers": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Highest number of viewers watching this show at the same time.", "title": "Max Concurrent Viewers" }, "viewers_per_hour": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "unique_viewers divided by the show's duration in hours.", "title": "Viewers Per Hour" }, "viewers_per_hour_benchmark": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change in viewers_per_hour against the seller's own trailing average, in percentage points.", "title": "Viewers Per Hour Benchmark" }, "viewers_per_hour_benchmark_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What viewers_per_hour_benchmark is compared against.", "title": "Viewers Per Hour Benchmark Label" }, "avg_watch_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Average time each viewer spent watching this show, formatted as e.g. \"5 min 24s\".", "title": "Avg Watch Time" }, "avg_watch_time_benchmark": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change in average watch time against the seller's own trailing average, in percentage points.", "title": "Avg Watch Time Benchmark" }, "avg_watch_time_benchmark_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What avg_watch_time_benchmark is compared against.", "title": "Avg Watch Time Benchmark Label" }, "new_followers": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Net new followers gained during this show.", "title": "New Followers" }, "new_followers_benchmark": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change in new_followers against the seller's own trailing average, in percentage points.", "title": "New Followers Benchmark" }, "new_followers_benchmark_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What new_followers_benchmark is compared against.", "title": "New Followers Benchmark Label" }, "show_shares": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of times this show was shared by users.", "title": "Show Shares" }, "show_shares_benchmark": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Change in show_shares against the seller's own trailing average, in percentage points.", "title": "Show Shares Benchmark" }, "show_shares_benchmark_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What show_shares_benchmark is compared against.", "title": "Show Shares Benchmark Label" }, "unique_viewers": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Distinct viewers who watched this show for more than 30 seconds.", "title": "Unique Viewers" }, "returning_viewers": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Of unique_viewers, those who had watched this seller before.", "title": "Returning Viewers" }, "returning_viewers_percentage": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "returning_viewers as a share of unique_viewers, in percentage points.", "title": "Returning Viewers Percentage" }, "new_viewers": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Of unique_viewers, those watching this seller for the first time.", "title": "New Viewers" }, "new_viewers_percentage": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "new_viewers as a share of unique_viewers, in percentage points.", "title": "New Viewers Percentage" }, "unique_buyers": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Distinct buyers who purchased during this show.", "title": "Unique Buyers" }, "returning_buyers": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Of unique_buyers, those who had bought from this seller before.", "title": "Returning Buyers" }, "returning_buyers_percentage": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "returning_buyers as a share of unique_buyers, in percentage points.", "title": "Returning Buyers Percentage" }, "new_buyers": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Of unique_buyers, those buying from this seller for the first time.", "title": "New Buyers" }, "new_buyers_percentage": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "new_buyers as a share of unique_buyers, in percentage points.", "title": "New Buyers Percentage" } }, "required": [ "show", "start_time", "duration_minutes", "category", "thumbnail_impressions", "thumbnail_ctr", "currency", "estimated_sales", "estimated_sales_benchmark", "estimated_sales_benchmark_label", "estimated_earnings", "estimated_earnings_benchmark", "estimated_earnings_benchmark_label", "estimated_orders", "estimated_orders_benchmark", "estimated_orders_benchmark_label", "estimated_aov", "estimated_aov_benchmark", "estimated_aov_benchmark_label", "sales_per_hour", "sales_per_hour_benchmark", "sales_per_hour_benchmark_label", "orders_per_hour", "orders_per_hour_benchmark", "orders_per_hour_benchmark_label", "total_giveaway_orders", "buyer_giveaway_orders", "giveaway_shipping_cost", "giveaways_per_hour", "unique_giveaway_entries", "unique_giveaway_winners", "new_followers_from_giveaways", "total_views", "max_concurrent_viewers", "viewers_per_hour", "viewers_per_hour_benchmark", "viewers_per_hour_benchmark_label", "avg_watch_time", "avg_watch_time_benchmark", "avg_watch_time_benchmark_label", "new_followers", "new_followers_benchmark", "new_followers_benchmark_label", "show_shares", "show_shares_benchmark", "show_shares_benchmark_label", "unique_viewers", "returning_viewers", "returning_viewers_percentage", "new_viewers", "new_viewers_percentage", "unique_buyers", "returning_buyers", "returning_buyers_percentage", "new_buyers", "new_buyers_percentage" ], "title": "ShowDetailsReportRow", "type": "object" } } }, "x-ext-urls": {} }