{ "swagger": "2.0", "info": { "version": "v4", "title": "BookVAULT API" }, "host": "api.bookvault.app", "schemes": [ "https" ], "paths": { "/v4/account": { "get": { "tags": [ "Account" ], "summary": "Load Your Account", "description": "Returns the profile for your BookVAULT account.", "operationId": "Account_Get", "consumes": [], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns your account profile", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Account" } }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Insufficient scope" } } }, "put": { "tags": [ "Account" ], "summary": "Update Your Account", "description": "Updates the profile for your BookVAULT account and returns the updated profile.", "operationId": "Account_Put", "consumes": [ "application/json", "text/json", "application/xml", "text/xml", "application/x-www-form-urlencoded" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "request", "in": "body", "description": "The account details to update", "required": true, "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.AccountUpdateRequest" } }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns your updated account profile", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Account" } }, "400": { "description": "Invalid input was supplied" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Insufficient scope" } } } }, "/v4/codelist": { "get": { "tags": [ "Codelists" ], "summary": "Get a codelist", "description": "Returns the entries for a codelist of the supplied type. Some codelist types (e.g. stocks,\r\n bindings and laminations) include a type-specific object with extra information for\r\n each entry. Types without extras return a null Details.", "operationId": "Codelist_Get", "consumes": [], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "type", "in": "query", "description": "The type of codelist to return.", "required": true, "type": "string", "enum": [ "Imprints", "Subjects", "ContributorRoles", "ContentType", "SubjectType", "BISACCodes", "BICCodes", "AudienceCodes", "Lamination", "Binding", "CoverStocks", "TextStocks", "FoilStocks", "Countries", "SpineFoilLocations", "FrontFoilLocations", "ContactGroups", "THEMACodes", "PublishingCountries", "ProductForms", "Publishers", "Languages", "CaseFoiling", "BespokeOptions" ] }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the codelist", "schema": { "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.CodelistEntry" } } }, "400": { "description": "Invalid input was supplied" }, "401": { "description": "Invalid or missing API key" } } } }, "/v4/dispatch": { "get": { "tags": [ "Dispatch" ], "summary": "Load the available services", "description": "Load the available services for an order base on its total weight.", "operationId": "Dispatch_Get", "consumes": [], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "countryCode", "in": "query", "description": "The ISO code of the delivery address country.", "required": true, "type": "string" }, { "name": "areaCode", "in": "query", "description": "The postcode or area code of the delivery address.", "required": true, "type": "string" }, { "name": "weight", "in": "query", "description": "The weight of the order in grams. Must be greater than zero.", "required": true, "type": "integer", "format": "int32", "minimum": 1 }, { "name": "partner", "in": "query", "description": "The requested print partner.", "required": true, "type": "string", "enum": [ "Bookvault_UK", "Bookvault_US", "Bookvault_AU", "Bookvault_CA" ] }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the available dispatch services.", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.DispEst" } }, "400": { "description": "Invalid input was supplied." }, "404": { "description": "Country or partner not found." } } }, "post": { "tags": [ "Dispatch" ], "summary": "Calculate available services", "description": "Returns the calculated dispatch estimate for an order payload", "operationId": "Dispatch_Post", "consumes": [ "application/json", "text/json", "application/xml", "text/xml", "application/x-www-form-urlencoded" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "request", "in": "body", "description": "The dispatch estimate request payload.", "required": true, "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.DispEstimatePostRequest" } }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the dispatch estimate.", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.DispEst" } }, "400": { "description": "Invalid input was supplied." }, "404": { "description": "Title not found." } } } }, "/v4/distribution/imprints": { "get": { "tags": [ "Distribution" ], "summary": "List imprints", "description": "Returns the imprints on your account. An imprint must exist before it can be assigned to a\r\n title's distribution metadata.", "operationId": "Distribution_GetImprints", "consumes": [], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the imprints", "schema": { "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Imprint" } } }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Insufficient scope" } } }, "post": { "tags": [ "Distribution" ], "summary": "Add an imprint", "description": "Adds a new imprint to your account.", "operationId": "Distribution_PostImprint", "consumes": [ "application/json", "text/json", "application/xml", "text/xml", "application/x-www-form-urlencoded" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "request", "in": "body", "description": "The imprint to add", "required": true, "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.ImprintRequest" } }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the created imprint", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Imprint" } }, "400": { "description": "Invalid input was supplied" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Insufficient scope" }, "422": { "description": "The imprint could not be added (e.g. a duplicate name)" } } } }, "/v4/distribution/imprints/{id}": { "put": { "tags": [ "Distribution" ], "summary": "Rename an imprint", "description": "Renames an existing imprint on your account.", "operationId": "Distribution_PutImprint", "consumes": [ "application/json", "text/json", "application/xml", "text/xml", "application/x-www-form-urlencoded" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "id", "in": "path", "description": "The id of the imprint to rename", "required": true, "type": "integer", "format": "int32" }, { "name": "request", "in": "body", "description": "The new imprint details", "required": true, "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.ImprintRequest" } }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the updated imprint", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Imprint" } }, "400": { "description": "Invalid input was supplied" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Insufficient scope" }, "404": { "description": "Imprint not found" }, "422": { "description": "The imprint could not be updated (e.g. a duplicate name)" } } } }, "/v4/distribution/{ISBN}": { "get": { "tags": [ "Distribution" ], "summary": "Get distribution metadata", "description": "Returns a title's wholesale/distribution metadata - the ONIX record that governs how it is\r\n offered to wholesale retailers and The Great British Bookshop.", "operationId": "Distribution_Get", "consumes": [], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "isbn", "in": "path", "description": "The ISBN13 of the title", "required": true, "type": "string" }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the distribution metadata", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.RetailProduct" } }, "400": { "description": "Invalid input was supplied" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Insufficient scope" }, "404": { "description": "Title or distribution metadata not found" } } }, "put": { "tags": [ "Distribution" ], "summary": "Edit distribution metadata", "description": "Replaces a title's existing wholesale/distribution metadata with the supplied values. The\r\n supplied contributors, prices, subjects, content and so on replace those currently held.", "operationId": "Distribution_Put", "consumes": [ "application/json", "text/json", "application/xml", "text/xml", "application/x-www-form-urlencoded" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "request", "in": "body", "description": "The distribution metadata to save", "required": true, "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.DistributionRequest" } }, { "name": "isbn", "in": "path", "description": "The ISBN13 of the title", "required": true, "type": "string" }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the saved distribution metadata", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.RetailProduct" } }, "400": { "description": "Invalid input was supplied" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Insufficient scope" }, "404": { "description": "Title or distribution metadata not found" }, "422": { "description": "The metadata could not be saved (e.g. failed validation)" } } }, "post": { "tags": [ "Distribution" ], "summary": "Add distribution metadata", "description": "Adds wholesale/distribution metadata to a title that does not already have any. Use the\r\n edit endpoint (PUT) to change metadata that already exists.", "operationId": "Distribution_Post", "consumes": [ "application/json", "text/json", "application/xml", "text/xml", "application/x-www-form-urlencoded" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "request", "in": "body", "description": "The distribution metadata to add", "required": true, "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.DistributionRequest" } }, { "name": "isbn", "in": "path", "description": "The ISBN13 of the title", "required": true, "type": "string" }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the saved distribution metadata", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.RetailProduct" } }, "400": { "description": "Invalid input was supplied" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Insufficient scope" }, "404": { "description": "Title not found" }, "422": { "description": "The metadata could not be saved (e.g. it already exists, or failed validation)" } } } }, "/v4/title/files/{ISBN}": { "get": { "tags": [ "Files" ], "summary": "Get a title's files", "description": "Returns the file information for each of a title's possible files. Optionally supply a\r\n list of file types to return only those files.", "operationId": "File_GetTitleFiles", "consumes": [], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "isbn", "in": "path", "description": "The ISBN13 of the title.", "required": true, "type": "string" }, { "name": "files", "in": "query", "description": "Optionally restrict the results to these file types. Omit to return every possible file.", "required": false, "type": "array", "items": { "type": "string", "enum": [ "None", "Cover", "Text", "Insert", "Jacket", "FoilBlock", "TearCover", "Disc", "DiscLabel", "CoverFoil", "JacketFoil", "EndPapers", "BoxSet", "SprayedEdges" ] }, "collectionFormat": "multi" }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the title's files", "schema": { "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.TitleFile" } } }, "400": { "description": "Invalid input was supplied" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Insufficient scope" }, "404": { "description": "Title not found" } } } }, "/v4/title/files/upload": { "get": { "tags": [ "Files" ], "summary": "Get file drop statuses", "description": "Returns the current status of the supplied file drops.", "operationId": "File_GetDropStatuses", "consumes": [], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "dropIDs", "in": "query", "description": "The IDs of the file drops to return the status for.", "required": true, "type": "array", "items": { "type": "integer", "format": "int32" }, "collectionFormat": "multi" }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the drop statuses", "schema": { "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.FileDropStatus" } } }, "400": { "description": "Invalid input was supplied" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Insufficient scope" } } } }, "/v4/title/files/upload/{ISBN}": { "post": { "tags": [ "Files" ], "summary": "Create file drops for a title", "description": "Creates a download file drop for each of the supplied files, downloaded by BookVAULT from\r\n the supplied URLs and linked to the title. Returns the created drop IDs, which can be passed to the\r\n drop status endpoint to track progress.", "operationId": "File_CreateFileDrops", "consumes": [ "application/json", "text/json", "application/xml", "text/xml", "application/x-www-form-urlencoded" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "files", "in": "body", "description": "The files to create drops for", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.FileUploadRequest" } } }, { "name": "isbn", "in": "path", "description": "The ISBN13 of the title", "required": true, "type": "string" }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the created drops", "schema": { "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.FileDropCreated" } } }, "400": { "description": "Invalid input was supplied" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Insufficient scope" }, "404": { "description": "Title not found" } } } }, "/v4/order": { "get": { "tags": [ "Orders" ], "summary": "Load An Order", "description": "Load an order using the defined reference type and identifier value", "operationId": "Order_Get", "consumes": [], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "type", "in": "query", "description": "The type of reference being used to load the order.", "required": true, "type": "string", "enum": [ "PodRef", "DocRef" ] }, { "name": "value", "in": "query", "description": "The search value for the reference type.", "required": true, "type": "string" }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the requested order", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Order" } }, "400": { "description": "Invalid input was supplied" }, "404": { "description": "Order not found" } } }, "post": { "tags": [ "Orders" ], "summary": "Place An Order", "description": "Create a new order for your BookVAULT account.", "operationId": "Order_Post", "consumes": [ "application/json", "text/json", "application/xml", "text/xml", "application/x-www-form-urlencoded" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.OrderPostRequest" } }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Order created", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.OrderPostResponse" } }, "400": { "description": "Invalid input was supplied" }, "422": { "description": "Order failed to save" } } }, "delete": { "tags": [ "Orders" ], "summary": "Cancel An Order", "description": "Cancel an order using the defined reference type and identifier value.", "operationId": "Order_Delete", "consumes": [], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "type", "in": "query", "description": "The type of reference being used to identify the order.", "required": true, "type": "string", "enum": [ "PodRef", "DocRef" ] }, { "name": "value", "in": "query", "description": "The search value for the reference type.", "required": true, "type": "string" }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Order cancelled successfully", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.OrderDeleteResponse" } }, "400": { "description": "Invalid input was supplied" }, "404": { "description": "Order not found" }, "422": { "description": "Order could not be cancelled" } } } }, "/v4/order/reference": { "get": { "tags": [ "Orders" ], "summary": "Generate An Order Reference", "description": "Generates the next order reference for your account to use as the\r\n document reference when placing an order. This only computes the next available reference - nothing\r\n is reserved until an order is actually placed.", "operationId": "Order_GetReference", "consumes": [], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the generated order reference", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.OrderReference" } }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Insufficient scope" } } } }, "/v4/order/transientsku": { "post": { "tags": [ "Orders" ], "summary": "Generate A Transient Product SKU", "description": "Builds a correctly-formatted transient product SKU from its component parts (paper,\r\n lamination, binding and size), so you don't have to encode the SKU string yourself. Use the returned\r\n SKU on a transient order line.", "operationId": "Order_GenerateTransientSku", "consumes": [ "application/json", "text/json", "application/xml", "text/xml", "application/x-www-form-urlencoded" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "request", "in": "body", "description": "The transient product specification", "required": true, "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.TransientSkuRequest" } }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the generated SKU", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.TransientSkuResponse" } }, "400": { "description": "Invalid input was supplied" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Insufficient scope" }, "422": { "description": "The specification could not be resolved to a valid SKU (e.g. unsupported binding/lamination)" } } } }, "/v4/order/validate": { "post": { "tags": [ "Orders" ], "summary": "Validate An Order", "description": "Validates an order without placing it, returning whether it passed and any messages raised.\r\n Use the validation type to control which parts are checked; it defaults to a full validation.", "operationId": "Order_Validate", "consumes": [ "application/json", "text/json", "application/xml", "text/xml", "application/x-www-form-urlencoded" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "request", "in": "body", "description": "The order to validate", "required": true, "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.OrderPostRequest" } }, { "name": "type", "in": "query", "description": "The type of validation to perform (defaults to Full)", "required": false, "type": "string", "enum": [ "Full", "Reference", "OrderLinesAndRef", "Address", "OrderLines", "AddressCustoms", "Proof", "FullButPayment", "UpdatePayment" ] }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the validation result", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.OrderValidation" } }, "400": { "description": "Invalid input was supplied" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Insufficient scope" } } } }, "/v4/orders": { "get": { "tags": [ "Orders" ], "summary": "Load multiple orders", "description": "Loads a batch of orders with pagination options to retrieve more where available", "operationId": "Orders_Get", "consumes": [], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "ordersPerPage", "in": "query", "description": "Number of orders to show per page", "required": true, "type": "integer", "format": "int32", "maximum": 10, "minimum": 1 }, { "name": "pageNumber", "in": "query", "description": "The page number to load", "required": true, "type": "integer", "format": "int32", "minimum": 1 }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the batch of orders", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.OrdersResponse" } }, "400": { "description": "Invalid input was supplied" } } }, "post": { "tags": [ "Orders" ], "summary": "Load multiple orders with filters", "description": "Loads a batch of orders based on specified filters with pagination options to retrieve more where available", "operationId": "Orders_Post", "consumes": [ "application/json", "text/json", "application/xml", "text/xml", "application/x-www-form-urlencoded" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.OrdersPostRequest" } }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the filtered batch of orders", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.OrdersResponse" } }, "400": { "description": "Invalid input was supplied" } } } }, "/v4/title/{ISBN}": { "get": { "tags": [ "Titles" ], "summary": "Load a title", "description": "Loads a specific title", "operationId": "Title_GetFull", "consumes": [], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "isbn", "in": "path", "description": "The ISBN13 of the title", "required": true, "type": "string" }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the title", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Product" } }, "400": { "description": "Invalid input was supplied" }, "404": { "description": "Title not found" } } }, "put": { "tags": [ "Titles" ], "summary": "Update a title", "description": "Updates an existing title on your BookVAULT account. The supplied title, specifications\r\n and bespoke options replace those currently held against the title.", "operationId": "Title_Update", "consumes": [ "application/json", "text/json", "application/xml", "text/xml", "application/x-www-form-urlencoded" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "request", "in": "body", "description": "The updated title details", "required": true, "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.TitlePutRequest" } }, { "name": "isbn", "in": "path", "description": "The ISBN13 of the title", "required": true, "type": "string" }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the updated title", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Product" } }, "400": { "description": "Invalid input was supplied" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Insufficient scope" }, "404": { "description": "Title not found" }, "422": { "description": "The title could not be updated" } } }, "delete": { "tags": [ "Titles" ], "summary": "Delete a title", "description": "Deletes a title from your BookVAULT account.", "operationId": "Title_Delete", "consumes": [], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "isbn", "in": "path", "description": "The ISBN13 of the title", "required": true, "type": "string" }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "204": { "description": "The title was deleted", "schema": { "type": "object" } }, "400": { "description": "Invalid input was supplied" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Insufficient scope" }, "404": { "description": "Title not found" } } } }, "/v4/title/lite/{ISBN}": { "get": { "tags": [ "Titles" ], "summary": "Load a lite title", "description": "Loads a 'lite' version of a specific title", "operationId": "Title_GetLite", "consumes": [], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "isbn", "in": "path", "description": "The ISBN13 of the title", "required": true, "type": "string" }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the lite title", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ProductLite" } }, "400": { "description": "Invalid input was supplied" }, "404": { "description": "Title not found" } } } }, "/v4/title": { "post": { "tags": [ "Titles" ], "summary": "Add a title", "description": "Creates a new title on your BookVAULT account.", "operationId": "Title_Post", "consumes": [ "application/json", "text/json", "application/xml", "text/xml", "application/x-www-form-urlencoded" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "request", "in": "body", "description": "The title to add", "required": true, "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.TitlePostRequest" } }, { "name": "currency", "in": "query", "description": "The currency used to pay for the title creation", "required": false, "type": "string", "enum": [ "GBP", "USD", "AUD" ] }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the created title", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Product" } }, "400": { "description": "Invalid input was supplied" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Insufficient scope" }, "422": { "description": "The title could not be created" } } } }, "/v4/title/bundle": { "post": { "tags": [ "Titles" ], "summary": "Create a bundle", "description": "Creates a new bundle (a group of existing titles) on your BookVAULT account.", "operationId": "Title_PostBundle", "consumes": [ "application/json", "text/json", "application/xml", "text/xml", "application/x-www-form-urlencoded" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "request", "in": "body", "description": "The bundle to create", "required": true, "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.BundlePostRequest" } }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the created bundle", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Product" } }, "400": { "description": "Invalid input was supplied" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Insufficient scope" }, "422": { "description": "The bundle could not be created" } } } }, "/v4/title/bundle/{ISBN}": { "put": { "tags": [ "Titles" ], "summary": "Update a bundle", "description": "Updates an existing bundle on your BookVAULT account. The supplied name, member titles and\r\n box/slipcase replace those currently held against the bundle. Only bundles can be updated here.", "operationId": "Title_PutBundle", "consumes": [ "application/json", "text/json", "application/xml", "text/xml", "application/x-www-form-urlencoded" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "request", "in": "body", "description": "The updated bundle details", "required": true, "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.BundlePutRequest" } }, { "name": "isbn", "in": "path", "description": "The ISBN13 of the title", "required": true, "type": "string" }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the updated bundle", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Product" } }, "400": { "description": "Invalid input was supplied" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Insufficient scope" }, "404": { "description": "Bundle not found" }, "422": { "description": "The bundle could not be updated (e.g. it is not a bundle, or is in production)" } } } }, "/v4/title/calculate": { "post": { "tags": [ "Titles" ], "summary": "Calculate a title", "description": "Calculates a title's derived specifications - size, spine, weight and pricing - from the\r\n supplied details without saving anything. Use a Spine calculation type when only the spine width is\r\n needed (less data is required).", "operationId": "Title_PostCalculate", "consumes": [ "application/json", "text/json", "application/xml", "text/xml", "application/x-www-form-urlencoded" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "request", "in": "body", "description": "The title to calculate", "required": true, "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.TitleSpecRequest" } }, { "name": "calculationType", "in": "query", "description": "The type of calculation to run", "required": false, "type": "string", "enum": [ "Full", "Spine" ] }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the calculated title", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Product" } }, "400": { "description": "Invalid input was supplied" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Insufficient scope" } } } }, "/v4/title/availability": { "post": { "tags": [ "Titles" ], "summary": "List available print partners", "description": "Supply a title's details and receive the print partners able to produce it. Only the\r\n supplied specification fields are considered.", "operationId": "Title_PostAvailability", "consumes": [ "application/json", "text/json", "application/xml", "text/xml", "application/x-www-form-urlencoded" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "request", "in": "body", "description": "The title to check", "required": true, "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.TitleSpecRequest" } }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the partners that can print the title", "schema": { "type": "array", "items": { "enum": [ "Bookvault_UK", "Bookvault_US", "Bookvault_AU", "Bookvault_CA" ], "type": "string" } } }, "400": { "description": "Invalid input was supplied" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Insufficient scope" } } } }, "/v4/title/approve/{ISBN}": { "post": { "tags": [ "Titles" ], "summary": "Approve a title", "description": "Approves a title that is awaiting your approval, accepting its proof.", "operationId": "Title_Approve", "consumes": [], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "isbn", "in": "path", "description": "The ISBN13 of the title", "required": true, "type": "string" }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "204": { "description": "The title was approved", "schema": { "type": "object" } }, "400": { "description": "Invalid input was supplied" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Insufficient scope" }, "404": { "description": "Title not found" }, "422": { "description": "The title is not awaiting approval" } } } }, "/v4/title/pay/{ISBN}": { "post": { "tags": [ "Titles" ], "summary": "Pay for a title", "description": "Pays the setup fee for a title that is awaiting payment. Payment is taken automatically from\r\nyour saved card or account credit where possible, otherwise a checkout link is returned in to complete the payment.\r\nOnly standalone titles can be paid for here (not bundles or boxes).", "operationId": "Title_PayTitle", "consumes": [], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "currency", "in": "query", "description": "The currency to charge in", "required": true, "type": "string", "enum": [ "GBP", "USD", "AUD" ] }, { "name": "promoCode", "in": "query", "description": "An optional promo code to apply to the payment", "required": false, "type": "string" }, { "name": "isbn", "in": "path", "description": "The ISBN13 of the title", "required": true, "type": "string" }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "The payment was taken, or a checkout link was issued", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.TitlePayment" } }, "400": { "description": "Invalid input was supplied" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Insufficient scope" }, "404": { "description": "Title not found" }, "422": { "description": "The title cannot be paid for (e.g. it is a bundle/box, or is not awaiting payment)" } } } }, "/v4/title/preview/{ISBN}": { "get": { "tags": [ "Titles" ], "summary": "Generate a title preview link", "description": "Generates a time-limited link for previewing a title's proof.", "operationId": "Title_GetPreview", "consumes": [], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "isbn", "in": "path", "description": "The ISBN13 of the title", "required": true, "type": "string" }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the preview link", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.TitlePreview" } }, "400": { "description": "Invalid input was supplied" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Insufficient scope" }, "404": { "description": "Title not found" } } } }, "/v4/titles": { "get": { "tags": [ "Titles" ], "summary": "Load multiple titles", "description": "Loads a batch of titles with pagination options to retrieve more where available", "operationId": "Titles_Get", "consumes": [], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "titlesPerPage", "in": "query", "description": "Number of titles to show per page", "required": true, "type": "integer", "format": "int32", "maximum": 10, "minimum": 1 }, { "name": "pageNumber", "in": "query", "description": "The page number to load", "required": true, "type": "integer", "format": "int32", "minimum": 1 }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the batch of titles", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.TitlesResponse" } }, "400": { "description": "Invalid input was supplied" } } }, "post": { "tags": [ "Titles" ], "summary": "Load multiple titles with filters", "description": "Loads a batch of titles based on specified filters with pagination options to retrieve more where available", "operationId": "Titles_Post", "consumes": [ "application/json", "text/json", "application/xml", "text/xml", "application/x-www-form-urlencoded" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.TitlesPostRequest" } }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the filtered batch of titles", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.TitlesResponse" } }, "400": { "description": "Invalid input was supplied" } } } }, "/v4/titles/upload": { "post": { "tags": [ "Titles" ], "summary": "Bulk import titles", "description": "Uploads a completed bulk title import template (an .xlsx workbook) as a Base64-encoded string and\r\nqueues its titles for creation. Every row is validated before anything is queued - if any column is\r\nmissing or any row is invalid, the whole upload is rejected and nothing is created. The titles are\r\ncreated asynchronously, so a bulk import id is returned; use the status endpoint to track its progress.", "operationId": "Titles_Upload", "consumes": [ "application/json", "text/json", "application/xml", "text/xml", "application/x-www-form-urlencoded" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "request", "in": "body", "description": "The Base64-encoded bulk title import template", "required": true, "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.BulkTitleUploadRequest" } }, { "name": "currency", "in": "query", "description": "The currency used to pay for the created titles", "required": false, "type": "string", "enum": [ "GBP", "USD", "AUD" ] }, { "name": "promoCode", "in": "query", "description": "An optional promo code to apply to the created titles", "required": false, "type": "string" }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "202": { "description": "The import was accepted and queued", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.BulkTitleImport" } }, "400": { "description": "Invalid input was supplied" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Insufficient scope" }, "422": { "description": "The template could not be processed (e.g. missing columns or invalid rows)" } } } }, "/v4/titles/upload/template": { "get": { "tags": [ "Titles" ], "summary": "Download the bulk import template", "description": "Downloads the bulk title import template as an .xlsx workbook. Fill it in and submit it\r\n back to the upload endpoint to bulk import titles.", "operationId": "Titles_GetUploadTemplate", "consumes": [], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the template file", "schema": { "type": "object" } }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Insufficient scope" } } } }, "/v4/titles/upload/{id}": { "get": { "tags": [ "Titles" ], "summary": "Get a bulk import status", "description": "Returns the status of a bulk title import that you previously queued, including how many\r\n titles have been processed and, once complete, a link to pay for the created titles where required.", "operationId": "Titles_GetUploadStatus", "consumes": [], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "id", "in": "path", "description": "The id of the bulk import", "required": true, "type": "integer", "format": "int32" }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the bulk import status", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.BulkTitleImport" } }, "400": { "description": "Invalid input was supplied" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "Insufficient scope" }, "404": { "description": "Bulk import not found" } } } }, "/v4/webhook/{ID}": { "get": { "tags": [ "Webhooks" ], "summary": "Retrieve webhook subscription", "description": "Retrieve information regarding a specific webhook", "operationId": "Webhook_Get", "consumes": [], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "id", "in": "path", "description": "The ID of the webhook", "required": true, "type": "integer", "format": "int64" }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the requested webhook.", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Webhook" } }, "400": { "description": "Invalid input was supplied." }, "404": { "description": "Webhook not found." } } }, "put": { "tags": [ "Webhooks" ], "summary": "Update webhook subscription", "description": "Updates the information regarding a specific webhook", "operationId": "Webhook_Put", "consumes": [ "application/json", "text/json", "application/xml", "text/xml", "application/x-www-form-urlencoded" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "request", "in": "body", "description": "The webhook request payload.", "required": true, "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.WebhookPutRequest" } }, { "name": "id", "in": "path", "description": "The ID of the webhook", "required": true, "type": "integer", "format": "int64" }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Updates the specified webhook and returns it.", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Webhook" } }, "400": { "description": "Invalid input was supplied." }, "404": { "description": "Webhook not found." } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Unsubscribe from a webhook", "description": "Deletes a webhook subscription", "operationId": "Webhook_Delete", "consumes": [], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "id", "in": "path", "description": "The ID of the webhook", "required": true, "type": "integer", "format": "int64" }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Unsubscribes from the specified webhook.", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.WebhookDeleteResponse" } }, "400": { "description": "Invalid input was supplied." }, "404": { "description": "Webhook not found." } } } }, "/v4/webhook": { "post": { "tags": [ "Webhooks" ], "summary": "Subscribe to a webhook", "description": "Subscribes the user to a particular webhook event", "operationId": "Webhook_Post", "consumes": [ "application/json", "text/json", "application/xml", "text/xml", "application/x-www-form-urlencoded" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "request", "in": "body", "description": "The webhook request payload.", "required": true, "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.WebhookPostRequest" } }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Subscribes to the webhook and returns it.", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Webhook" } }, "400": { "description": "Invalid input was supplied." } } } }, "/v4/webhook/{ID}/status": { "patch": { "tags": [ "Webhooks" ], "summary": "Update webhook subscription status", "description": "Updates the status of an existing webhook subscription. Can be used to pause/resume a webhook", "operationId": "Webhook_PatchStatus", "consumes": [ "application/json", "text/json", "application/xml", "text/xml", "application/x-www-form-urlencoded" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "request", "in": "body", "description": "The webhook request payload.", "required": true, "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.WebhookStatusPatchRequest" } }, { "name": "id", "in": "path", "description": "The ID of the webhook", "required": true, "type": "integer", "format": "int64" }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Webhook status updated successfully.", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Webhook" } }, "400": { "description": "Invalid input was supplied." }, "404": { "description": "Webhook not found." } } } }, "/v4/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "Load multiple webhooks", "description": "Loads a batch of webhooks with pagination options to retrieve more where available", "operationId": "Webhooks_Get", "consumes": [], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "webhooksPerPage", "in": "query", "description": "Number of webhooks to show per page", "required": true, "type": "integer", "format": "int32", "maximum": 10, "minimum": 1 }, { "name": "pageNumber", "in": "query", "description": "The page number to load", "required": true, "type": "integer", "format": "int32", "minimum": 1 }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the batch of webhooks", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.WebhooksResponse" } }, "400": { "description": "Invalid input was supplied." } } }, "post": { "tags": [ "Webhooks" ], "summary": "Load multiple webhooks with filters", "description": "Loads a batch of webhooks based on specified filters with pagination options to retrieve more where available", "operationId": "Webhooks_Post", "consumes": [ "application/json", "text/json", "application/xml", "text/xml", "application/x-www-form-urlencoded" ], "produces": [ "application/json", "text/json", "application/xml", "text/xml" ], "parameters": [ { "name": "request", "in": "body", "description": "The webhook request payload.", "required": true, "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.WebhooksPostRequest" } }, { "name": "x-bookvault-api-key", "in": "header", "description": "Your API key", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the filtered batch of webhooks", "schema": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.WebhooksResponse" } }, "400": { "description": "Invalid input was supplied." } } } } }, "definitions": { "BookVAULT.ApiUtilities.DTOs.Responses.Account": { "description": "Your BookVAULT account profile.", "type": "object", "properties": { "details": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.AccountDetails", "description": "The personal details of the profile." }, "accountManager": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.AccountManager", "description": "The account manager assigned to the account." }, "settings": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.AccountSettings", "description": "Settings specific to the account." }, "financial": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.AccountFinancial", "description": "Financial information for the account." }, "setup": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.AccountSetup", "description": "How far the account has progressed through the onboarding journey." }, "activePromotion": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.AccountPromotion", "description": "The promotion currently applied to the account, if any." }, "surcharges": { "description": "Current surcharges applied to the account.", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.AccountSurcharge" } } } }, "BookVAULT.ApiUtilities.DTOs.Responses.AccountDetails": { "description": "The personal details of an account profile.", "type": "object", "properties": { "title": { "description": "The title of the person assigned to the profile.", "type": "string" }, "firstName": { "description": "The first name of the person assigned to the profile.", "type": "string" }, "lastName": { "description": "The last name of the person assigned to the profile.", "type": "string" }, "email": { "description": "The email of the person assigned to the profile.", "type": "string" }, "phone": { "description": "The contact phone number for the profile.", "type": "string" }, "jobTitle": { "description": "The job title of the person assigned to the profile (e.g. Marketing Manager).", "type": "string" }, "allowNotifications": { "description": "Whether the profile opts in to order notifications.", "type": "boolean" }, "createdDate": { "format": "date-time", "description": "The date the account was created.", "type": "string" }, "accountRole": { "description": "The name of the BookVAULT access role assigned to the profile (e.g. Admin).", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.AccountManager": { "description": "The account manager assigned to an account.", "type": "object", "properties": { "firstName": { "description": "The first name of the account manager.", "type": "string" }, "lastName": { "description": "The last name of the account manager.", "type": "string" }, "telephone": { "description": "The telephone number of the account manager.", "type": "string" }, "email": { "description": "The email address of the account manager.", "type": "string" }, "image": { "description": "An image of the account manager.", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.AccountSettings": { "description": "Settings specific to an account.", "type": "object", "properties": { "allowPremium": { "description": "Whether premium (inkjet/toner) pricing is available to the account.", "type": "boolean" }, "planName": { "description": "The name of the plan assigned to the account.", "type": "string" }, "planEnd": { "description": "The date the current plan is due to end.", "type": "string" }, "titleSetupFee": { "format": "double", "description": "The cost to set up a new title.", "type": "number" }, "fileReplacementFee": { "format": "double", "description": "The cost to replace files on a title.", "type": "number" }, "publishingFee": { "format": "double", "description": "The cost to publish a book.", "type": "number" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.AccountFinancial": { "description": "Financial information for an account.", "type": "object", "properties": { "vatNumber": { "description": "The VAT number for the account.", "type": "string" }, "billingAddress": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.AccountAddress", "description": "The billing address for the account." }, "paymentInfo": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.AccountPaymentInfo", "description": "The bank/remittance details for the account." }, "discounts": { "description": "The volume discounts available to the account.", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.AccountVolumeDiscount" } } } }, "BookVAULT.ApiUtilities.DTOs.Responses.AccountSetup": { "description": "The onboarding progress of an account.", "type": "object", "properties": { "setupComplete": { "description": "Whether the initial setup process is complete.", "type": "boolean" }, "addedFunds": { "description": "Whether funds have been added to the account.", "type": "boolean" }, "addedTitle": { "description": "Whether a title has been added to the account.", "type": "boolean" }, "addedFiles": { "description": "Whether files have been added to a title.", "type": "boolean" }, "placedOrder": { "description": "Whether an order has been placed.", "type": "boolean" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.AccountPromotion": { "description": "A promotion currently applied to an account.", "type": "object", "properties": { "name": { "description": "The name of the promotion.", "type": "string" }, "details": { "description": "Details of the promotion.", "type": "string" }, "startDate": { "format": "date-time", "description": "The start date of the promotion.", "type": "string" }, "endDate": { "format": "date-time", "description": "The end date of the promotion.", "type": "string" }, "printPercentage": { "format": "double", "description": "The discount percentage applied to print.", "type": "number" }, "titleSetupPercentage": { "format": "double", "description": "The discount percentage applied to setting up new titles.", "type": "number" }, "fileReplacementPercentage": { "format": "double", "description": "The discount percentage applied to replacing files.", "type": "number" }, "pickPackFeeDiscount": { "format": "double", "description": "The discount applied to pick/pack fees.", "type": "number" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.AccountSurcharge": { "description": "A surcharge applied to an account.", "type": "object", "properties": { "title": { "description": "The title of the surcharge.", "type": "string" }, "description": { "description": "A description of the surcharge.", "type": "string" }, "productionPercentage": { "format": "double", "description": "The percentage applied to production.", "type": "number" }, "dispatchPercentage": { "format": "double", "description": "The percentage applied to dispatch.", "type": "number" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.AccountAddress": { "description": "A billing address for an account.", "type": "object", "properties": { "addressee": { "description": "The addressee / name on the address.", "type": "string" }, "company": { "description": "The company name on the address.", "type": "string" }, "address1": { "description": "The first line of the address.", "type": "string" }, "address2": { "description": "The second line of the address.", "type": "string" }, "address3": { "description": "The third line of the address.", "type": "string" }, "address4": { "description": "The fourth line of the address.", "type": "string" }, "town": { "description": "The town/city of the address.", "type": "string" }, "county": { "description": "The county/state of the address.", "type": "string" }, "postcode": { "description": "The postcode/zip of the address.", "type": "string" }, "country": { "description": "The country name of the address.", "type": "string" }, "telNumber": { "description": "The contact telephone number for the address.", "type": "string" }, "email": { "description": "The contact email for the address.", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.AccountPaymentInfo": { "description": "Bank/remittance details for an account.", "type": "object", "properties": { "accountName": { "description": "The name on the bank account.", "type": "string" }, "accountNumber": { "description": "The bank account number.", "type": "string" }, "sortCode": { "description": "The bank sort code.", "type": "string" }, "ibanCode": { "description": "The IBAN of the bank account.", "type": "string" }, "swiftCode": { "description": "The SWIFT/BIC of the bank account.", "type": "string" }, "routingNumber": { "description": "The routing number of the bank account.", "type": "string" }, "bsbNumber": { "description": "The BSB number of the bank account.", "type": "string" }, "bankType": { "description": "The type of bank account (Personal or Business).", "enum": [ "NotSet", "Personal", "Business" ], "type": "string" }, "remittenceEmail": { "description": "The email address remittance advices are sent to.", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.AccountVolumeDiscount": { "description": "A volume discount tier available to an account.", "type": "object", "properties": { "minQty": { "format": "int32", "description": "The minimum quantity the discount applies from.", "type": "integer" }, "maxQty": { "format": "int32", "description": "The maximum quantity the discount applies to.", "type": "integer" }, "hasMax": { "description": "Whether the tier has an upper quantity limit.", "type": "boolean" }, "percentage": { "format": "double", "description": "The discount percentage applied.", "type": "number" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.AccountUpdateRequest": { "description": "The details required to update your BookVAULT account profile.\r\nOnly the fields consumed by the account update are accepted.", "required": [ "title", "firstName", "lastName", "jobTitle", "phone" ], "type": "object", "properties": { "title": { "description": "The title of the person assigned to the profile (e.g. Mr, Mrs, Dr).", "maxLength": 50, "minLength": 0, "type": "string" }, "firstName": { "description": "The first name of the person assigned to the profile.", "maxLength": 100, "minLength": 0, "type": "string" }, "lastName": { "description": "The last name of the person assigned to the profile.", "maxLength": 100, "minLength": 0, "type": "string" }, "jobTitle": { "description": "The job title of the person assigned to the profile (e.g. Marketing Manager).", "maxLength": 100, "minLength": 0, "type": "string" }, "phone": { "description": "The contact phone number for the profile.", "maxLength": 35, "minLength": 0, "type": "string" }, "allowNotifications": { "description": "Whether the profile opts in to order notifications.", "type": "boolean" }, "financial": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.AccountFinancial", "description": "Optional financial details to update. Omit to leave existing details unchanged." } } }, "BookVAULT.ApiUtilities.DTOs.Requests.AccountFinancial": { "description": "Financial details that can be updated on the account.", "type": "object", "properties": { "vatNumber": { "description": "The VAT number for the account.", "type": "string" }, "paymentInfo": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.AccountPaymentInfo", "description": "The bank/remittance details used to pay the account." }, "billingAddress": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.AccountAddress", "description": "The billing address for the account." } } }, "BookVAULT.ApiUtilities.DTOs.Requests.AccountPaymentInfo": { "description": "Bank/remittance details for the account.", "required": [ "remittenceEmail" ], "type": "object", "properties": { "accountName": { "description": "The name on the bank account.", "maxLength": 100, "minLength": 0, "type": "string" }, "accountNumber": { "description": "The bank account number.", "maxLength": 50, "minLength": 0, "type": "string" }, "sortCode": { "description": "The bank sort code.", "maxLength": 20, "minLength": 0, "type": "string" }, "ibanCode": { "description": "The IBAN of the bank account.", "maxLength": 50, "minLength": 0, "type": "string" }, "swiftCode": { "description": "The SWIFT/BIC of the bank account.", "maxLength": 20, "minLength": 0, "type": "string" }, "routingNumber": { "description": "The routing number of the bank account.", "maxLength": 50, "minLength": 0, "type": "string" }, "bsbNumber": { "description": "The BSB number of the bank account.", "maxLength": 20, "minLength": 0, "type": "string" }, "bankType": { "description": "The type of bank account (Personal or Business).", "enum": [ "NotSet", "Personal", "Business" ], "type": "string" }, "countryCode": { "description": "The ISO country code of the country the bank account is held in.", "maxLength": 2, "minLength": 2, "type": "string" }, "remittenceEmail": { "description": "The email address remittance advices are sent to.", "maxLength": 120, "minLength": 0, "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.AccountAddress": { "description": "A billing address for the account.", "required": [ "addressee", "address1", "town", "postcode", "countryCode" ], "type": "object", "properties": { "addressee": { "description": "The addressee / name on the address.", "maxLength": 200, "minLength": 0, "type": "string" }, "company": { "description": "The company name on the address.", "maxLength": 200, "minLength": 0, "type": "string" }, "address1": { "description": "The first line of the address.", "maxLength": 200, "minLength": 0, "type": "string" }, "address2": { "description": "The second line of the address.", "maxLength": 250, "minLength": 0, "type": "string" }, "address3": { "description": "The third line of the address.", "maxLength": 99, "minLength": 0, "type": "string" }, "address4": { "description": "The fourth line of the address.", "maxLength": 99, "minLength": 0, "type": "string" }, "town": { "description": "The town/city of the address.", "maxLength": 99, "minLength": 0, "type": "string" }, "county": { "description": "The county/state of the address.", "maxLength": 200, "minLength": 0, "type": "string" }, "postcode": { "description": "The postcode/zip of the address.", "maxLength": 99, "minLength": 0, "type": "string" }, "countryCode": { "description": "The ISO country code of the address.", "maxLength": 2, "minLength": 2, "type": "string" }, "telNumber": { "description": "The contact telephone number for the address.", "maxLength": 35, "minLength": 0, "type": "string" }, "email": { "description": "The contact email for the address.", "maxLength": 120, "minLength": 0, "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.CodelistGetRequest": { "description": "Request for a codelist of a particular type.", "required": [ "type" ], "type": "object", "properties": { "type": { "description": "The type of codelist to return.", "enum": [ "Imprints", "Subjects", "ContributorRoles", "ContentType", "SubjectType", "BISACCodes", "BICCodes", "AudienceCodes", "Lamination", "Binding", "CoverStocks", "TextStocks", "FoilStocks", "Countries", "SpineFoilLocations", "FrontFoilLocations", "ContactGroups", "THEMACodes", "PublishingCountries", "ProductForms", "Publishers", "Languages", "CaseFoiling", "BespokeOptions" ], "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.CodelistEntry": { "description": "A single codelist entry: its type, its display value, its identifier, and - for codelist types\r\nthat carry extra information - a type-specific {BookVAULT.ApiUtilities.DTOs.Responses.CodelistEntry.Details} object.", "type": "object", "properties": { "type": { "description": "The type of codelist this entry belongs to.", "enum": [ "Imprints", "Subjects", "ContributorRoles", "ContentType", "SubjectType", "BISACCodes", "BICCodes", "AudienceCodes", "Lamination", "Binding", "CoverStocks", "TextStocks", "FoilStocks", "Countries", "SpineFoilLocations", "FrontFoilLocations", "ContactGroups", "THEMACodes", "PublishingCountries", "ProductForms", "Publishers", "Languages", "CaseFoiling", "BespokeOptions" ], "type": "string" }, "id": { "format": "int32", "description": "The identifier of the entry (the value to submit when using this code).", "type": "integer" }, "value": { "description": "The display value of the entry.", "type": "string" }, "details": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ICodelistDetails", "description": "Extra, type-specific information for this entry. Null for codelist types that carry no extras." } } }, "BookVAULT.ApiUtilities.DTOs.Responses.ICodelistDetails": { "description": "Extra details for a codelist entry. Each codelist type that carries extra\r\ninformation provides its own implementation, so the shape of 'Details' is specific to the codelist type being returned.\r\nNot all code list types have extra details.", "type": "object", "properties": {} }, "BookVAULT.ApiUtilities.DTOs.Requests.DispEstimateGetRequest": { "required": [ "countryCode", "areaCode", "weight", "partner" ], "type": "object", "properties": { "countryCode": { "description": "The ISO code of the delivery address country.", "type": "string" }, "areaCode": { "description": "The postcode or area code of the delivery address.", "type": "string" }, "weight": { "format": "int32", "description": "The weight of the order in grams. Must be greater than zero.", "minimum": 1, "type": "integer" }, "partner": { "description": "The requested print partner.", "enum": [ "Bookvault_UK", "Bookvault_US", "Bookvault_AU", "Bookvault_CA" ], "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.DispEst": { "type": "object", "properties": { "partner": { "description": "The print partner.", "enum": [ "Bookvault_UK", "Bookvault_US", "Bookvault_AU", "Bookvault_CA" ], "type": "string" }, "country": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Country", "description": "The country of the delivery address." }, "weight": { "format": "int32", "description": "The weight of the order in grams.", "type": "integer" }, "notes": { "description": "Any notes on the service. For example, whether the service is deemed as hard to reach.", "type": "string" }, "requestedServices": { "description": "IDs of services that have been requested.", "type": "array", "items": { "format": "int32", "type": "integer" } }, "services": { "description": "A list of available services.", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Service" } } } }, "BookVAULT.ApiUtilities.DTOs.Responses.Country": { "type": "object", "properties": { "name": { "description": "The name of the country.", "type": "string" }, "isoCode": { "description": "The 2-digit ISO 3166-2 country code.", "maxLength": 2, "minLength": 2, "type": "string" }, "postCodeRequired": { "description": "Whether the country requires a postcode. If true, a postcode will be required when placing an order.", "type": "boolean" }, "postCodeFormat": { "description": "The expected format of the country in RegEx format. If a postcode does not satisfy this,\r\nan address error will be thrown when placing an order.", "type": "string" }, "eu": { "description": "Specifies whether the country is based in the EU", "type": "boolean" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.Service": { "type": "object", "properties": { "servID": { "format": "int32", "description": "ID number used to identify the service.", "type": "integer" }, "serviceName": { "description": "The name of the service.", "type": "string" }, "serviceDetail": { "description": "The description/detail of the service.", "type": "string" }, "tracked": { "description": "Whether the service is tracked.", "type": "boolean" }, "minWeight": { "format": "int32", "description": "The minimum weight in grams of the service's price bracket.", "type": "integer" }, "maxWeight": { "format": "int32", "description": "The maximum weight in grams of the service's price bracket.", "type": "integer" }, "pickPackFee": { "format": "double", "description": "The pick pack fee of the order as per your BookVAULT agreement.", "type": "number" }, "deliveryTotal": { "format": "double", "description": "The total cost for picking, packing and delivering your order.", "type": "number" }, "sundayDelivery": { "description": "Whether Sunday delivery is attempted by carrier.", "type": "boolean" }, "saturdayDelivery": { "description": "Whether Saturday delivery is attempted by carrier.", "type": "boolean" }, "minDeliveryDays": { "format": "int32", "description": "The minimum estimated time to deliver your order (in working days). If not available, 0 supplied.", "type": "integer" }, "maxDeliveryDays": { "format": "int32", "description": "The maximum estimated time to deliver your order (in working days). If not available, 0 supplied.", "type": "integer" }, "notes": { "description": "Notes relating to the supplied service, such as if a surcharge has been applied to the delivery cost.", "type": "string" }, "serviceCode": { "description": "A service code used to identify the service.", "type": "string" }, "serviceImage": { "description": "An image relating to the service.", "type": "string" }, "minEstimatedDelivery": { "format": "date-time", "description": "The earliest estimated delivery date.", "type": "string" }, "maxEstimatedDelivery": { "format": "date-time", "description": "The latest estimated delivery date.", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.DispEstimatePostRequest": { "required": [ "orderLines", "countryCode", "serviceLevel", "currency", "shipmentDate", "areaCode" ], "type": "object", "properties": { "orderLines": { "description": "The lines of the order a service is requested for.", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.OrderLine" } }, "countryCode": { "description": "The country code of the delivery address in ISO 3166-2 format.", "type": "string" }, "serviceLevel": { "description": "The requested service when placing an order, allowing either a specific\r\nservice to be selected, or the logic to choose which service to use.", "enum": [ "Quickest", "Cheapest", "Specified", "Tracked", "NotSpecified", "CheapestTracked" ], "type": "string" }, "partner": { "description": "The partner shipping is being requested from.\r\nIf omitted, the most suitable print partner will be chosen", "enum": [ "Bookvault_UK", "Bookvault_US", "Bookvault_AU", "Bookvault_CA" ], "type": "string" }, "currency": { "description": "The base currency of the rates.", "enum": [ "GBP", "USD", "AUD" ], "type": "string" }, "shipmentDate": { "format": "date-time", "description": "The date the shipment will be made.", "type": "string" }, "areaCode": { "description": "The postal/zip code of the delivery address.", "type": "string" }, "requestedServIds": { "description": "The service IDs requested. Only required if using the\r\n[Specified] requested service type.", "type": "array", "items": { "format": "int32", "type": "integer" } } } }, "BookVAULT.ApiUtilities.DTOs.Requests.OrderLine": { "required": [ "lineNumber", "quantity" ], "type": "object", "properties": { "lineNumber": { "format": "int32", "description": "The line number of the order, incrementing from 1 for each line.", "minimum": 1, "type": "integer" }, "isbn": { "description": "The 13 digit ISBN of the required title. Supply this for a library title, or leave it empty and\r\nsupply Transient instead for a one-off (transient) product.", "maxLength": 13, "minLength": 0, "type": "string" }, "transient": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.OrderTransient", "description": "A one-off (\"transient\") product for this line, described inline rather than referenced by ISBN.\r\nSupply this instead of ISBN. Exactly one of the two must be provided." }, "quantity": { "format": "int32", "description": "The quantity of books required.", "minimum": 1, "type": "integer" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.OrderTransient": { "description": "Defines a one-off (\"transient\") product for an order line - an item not held in your library,\r\ndescribed inline by its SKU rather than referenced by an ISBN. Use the transient SKU endpoint to\r\ngenerate a correctly-formatted SKU from its component parts.", "required": [ "productSku" ], "type": "object", "properties": { "productSku": { "description": "The product SKU, which encodes the transient product's paper, lamination, binding and size.\r\nGenerate one with the transient SKU endpoint.", "type": "string" }, "lineTitle": { "description": "The title/name for the line.", "type": "string" }, "colourPages": { "format": "int32", "description": "The number of colour pages.", "minimum": 0, "type": "integer" }, "monoPages": { "format": "int32", "description": "The number of mono (black & white) pages.", "minimum": 0, "type": "integer" }, "files": { "description": "The files for the transient product, keyed by item type (e.g. Cover, Text).", "type": "object", "properties": { "none": { "type": "string" }, "cover": { "type": "string" }, "text": { "type": "string" }, "insert": { "type": "string" }, "jacket": { "type": "string" }, "foilBlock": { "type": "string" }, "tearCover": { "type": "string" }, "disc": { "type": "string" }, "discLabel": { "type": "string" }, "coverFoil": { "type": "string" }, "jacketFoil": { "type": "string" }, "endPapers": { "type": "string" }, "boxSet": { "type": "string" }, "sprayedEdges": { "type": "string" } } } } }, "BookVAULT.ApiUtilities.DTOs.Responses.Imprint": { "description": "An imprint on your account.", "type": "object", "properties": { "id": { "format": "int32", "description": "The identifier of the imprint.", "type": "integer" }, "name": { "description": "The name of the imprint.", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.ImprintRequest": { "description": "The details of an imprint to add or rename on your account.", "required": [ "name" ], "type": "object", "properties": { "name": { "description": "The name of the imprint.", "maxLength": 100, "minLength": 0, "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.TitleGetRequest": { "required": [ "isbn" ], "type": "object", "properties": { "isbn": { "description": "The ISBN13 of the title", "maxLength": 13, "minLength": 13, "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.RetailProduct": { "type": "object", "properties": { "wholesaleEnabled": { "description": "Whether the title is made available to our wholesale retailers", "type": "boolean" }, "tgbbsEnabled": { "description": "Whether the title is made available to The Great British Bookshop", "type": "boolean" }, "productFormCode": { "description": "The form of the product (as per ONIX code list 150)", "enum": [ "Undefined", "Book", "Hardback", "Paperback_softback", "Looseleaf", "Spiral_bound", "Leather_fine_binding", "Notebook_blank_book", "Shrinkwrapped_pack" ], "type": "string" }, "subTitle": { "description": "The subtitle of the product", "type": "string" }, "contributors": { "description": "A list of contributors which are responsible for the product", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ProductContributor" } }, "audience": { "description": "A list of audiences the product links to", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ProductAudience" } }, "content": { "description": "Content relating to the title", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ProductContent" } }, "keywords": { "description": "Keywords related to the title", "type": "array", "items": { "type": "string" } }, "language": { "description": "Language of the title", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ProductLanguage" } }, "retail": { "description": "The retailing offerings of the title. If a currency code is not provided, it won't be offered to retailers in that region.", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ProductRetail" } }, "publication": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ProductPublication", "description": "Publication information related to the title" }, "subjects": { "description": "The subjects of the product", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ProductSubject" } }, "resources": { "description": "Resources related to the product", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ProductResource" } }, "listings": { "description": "The products listings on our distribution partners", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ProductListing" } }, "messages": { "description": "A list of messages about the product, including any issues associated with it", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Message" } } } }, "BookVAULT.ApiUtilities.DTOs.Responses.ProductContributor": { "description": "Information regarding a product contributor", "type": "object", "properties": { "role": { "description": "The role of the contributor", "enum": [ "By_author", "Libretto_by", "Illustrated_by", "Photographs_by", "Text_by", "Preface_by", "Afterword_by", "Notes_by", "Commentaries_by", "Foreword_by", "Introduction_by", "Contributions_by", "Drawings_by", "Edited_by", "Revised_by", "Adapted_by", "Translated_by", "Series_edited_by", "Volume_editor", "Founded_by", "Compiled_by", "Selected_by" ], "type": "string" }, "firstName": { "description": "The first name of the contributor", "type": "string" }, "lastName": { "description": "The surname of the contributor", "type": "string" }, "lettersAfterName": { "description": "Letters after name, e.g. OBE", "type": "string" }, "brandName": { "description": "The brand name of the contributor", "type": "boolean" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.ProductAudience": { "description": "Audience information for a product", "type": "object", "properties": { "type": { "description": "The audience code type", "enum": [ "ONIX_audience_codes" ], "type": "string" }, "value": { "description": "The value of the audience", "enum": [ "General_trade", "Children_juvenile", "Young_adult", "Primary_and_secondary_elementary_and_high_school", "College_higher_education", "Professional_and_scholarly", "ELT_ESL", "Adult_education", "Second_language_teaching" ], "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.ProductContent": { "description": "Content information about a product", "type": "object", "properties": { "type": { "description": "The type of content provided", "enum": [ "Senderdefined_text", "Short_description_annotation", "Description", "Table_of_contents", "Flap_cover_copy", "Review_quote", "Review_quote_previous_edition", "Review_quote_previous_work", "Endorsement", "Promotional_headline", "Feature", "Biographical_note", "Publishers_notice", "Excerpt", "Index", "Short_description_annotation_for_collection", "Description_for_collection", "New_feature", "Version_history", "Open_access_statement", "Digital_exclusivity_statement", "Official_recommendation", "JBPA_description", "schema_org_snippet", "Errata", "Introduction", "Secondary_flap_cover_copy", "Full_cast_and_credit_list", "Bibliography", "Abstract", "Rules_or_instructions" ], "type": "string" }, "value": { "description": "The text value of the content", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.ProductLanguage": { "description": "Language information about a product", "type": "object", "properties": { "languageRole": { "description": "Language role as per ONIX list 22", "enum": [ "Language_of_text", "Original_language_of_a_translated_text", "Language_of_abstracts", "Original_language_in_a_multilingual_edition", "Translated_language_in_a_multilingual_edition", "Language_of_audio_track", "Language_of_subtitles", "Language_of_original_audio_track", "Original_language_audio_track_in_a_multilingual_product", "Language_of_notes" ], "type": "string" }, "languageCode": { "format": "int32", "description": "Language code as per ONIX list 54", "type": "integer" }, "language": { "description": "The associated language value", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.ProductRetail": { "description": "Information regarding a retail offering of a product", "type": "object", "properties": { "priceAmount": { "format": "double", "description": "The amount we should advertise your product as", "type": "number" }, "currencyCode": { "description": "The currency code of the retail offering", "enum": [ "EUR", "GBP", "USD" ], "type": "string" }, "publisherDiscount": { "format": "int32", "description": "The percentage discount you wish to offer on the product", "type": "integer" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.ProductPublication": { "description": "Publication information related to a title", "type": "object", "properties": { "imprintName": { "description": "The imprint name of the product", "type": "string" }, "publishers": { "description": "The publishers assigned to the product", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ProductPublisher" } }, "publicationDates": { "description": "The dates the title was published", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ProductPublishDate" } } } }, "BookVAULT.ApiUtilities.DTOs.Responses.ProductSubject": { "description": "Information about a subject related to a product", "type": "object", "properties": { "subjectIdentifier": { "description": "The scheme of the subject", "enum": [ "BISAC_Subject_Heading", "BIC_subject_category", "Thema_subject_category" ], "type": "string" }, "subjectCode": { "description": "The string value of the subject code", "type": "string" }, "headingText": { "description": "The heading of the subject code", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.ProductResource": { "description": "Resource related to a product", "type": "object", "properties": { "contentType": { "description": "The type of file", "enum": [ "Front_cover" ], "type": "string" }, "fileName": { "description": "The filename/URL of the content", "type": "string" }, "fileType": { "description": "The type of content to be returned", "enum": [ "JPEG" ], "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.ProductListing": { "description": "Information related to a product listing", "type": "object", "properties": { "retailer": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Retailer", "description": "The retailer of the product" }, "url": { "description": "URL of the product on the retailers website", "type": "string" }, "dateUpdated": { "format": "date-time", "description": "The last time the retailers listing was updated", "type": "string" }, "status": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.WholesaleStatus", "description": "The Current Status of the product" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.Message": { "description": "An informational message from the system", "type": "object", "properties": { "identity": { "type": "string" }, "errorText": { "type": "string" }, "message": { "description": "The error information", "type": "string" }, "level": { "description": "The level of message reported", "enum": [ "Error", "Warning", "Message" ], "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.ProductPublisher": { "description": "Publisher information", "type": "object", "properties": { "cityOfPublication": { "description": "The city the title was published in", "type": "string" }, "publisherName": { "description": "The name of the publisher", "type": "string" }, "countryOfPublication": { "format": "int32", "description": "The country the title was published in as per ONIX list 91", "type": "integer" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.ProductPublishDate": { "description": "Product publication date information", "type": "object", "properties": { "publishingDateRole": { "description": "The purpose of the date supplied", "enum": [ "Publication_date" ], "type": "string" }, "dateValue": { "format": "date-time", "description": "The value of the date", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.Retailer": { "description": "Information regarding a retailer", "type": "object", "properties": { "name": { "description": "The name of the retailer", "type": "string" }, "iconImage": { "description": "Link to an image of the retailer's icon", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.WholesaleStatus": { "description": "The wholesale status of a product", "type": "object", "properties": { "status": { "description": "The current status of the product", "enum": [ "Pending", "Active", "Action_Needed", "Pending_Deletion", "Deleted", "Not_Available", "Disabled", "Awaiting_Validation" ], "type": "string" }, "beautified": { "description": "A beautified string of the value", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.DistributionRequest": { "description": "The wholesale/distribution metadata for a title. Supplied when adding or editing a title's\r\ndistribution record. The system-managed parts of the record (identifiers, barcodes, resources,\r\nlistings) are not accepted here - they are generated by BookVAULT.", "required": [ "wholesaleEnabled", "bvRetailersEnabled", "contributors", "audience", "content", "language", "retail", "subjects", "publication" ], "type": "object", "properties": { "wholesaleEnabled": { "description": "Whether the title is made available to our wholesale retailers.", "type": "boolean" }, "bvRetailersEnabled": { "description": "Whether the title is made available to BookVAULT's own retailers - The Great British Bookshop and\r\nThe BookVAULT Shop.", "type": "boolean" }, "subTitle": { "description": "The subtitle of the product.", "maxLength": 255, "minLength": 0, "type": "string" }, "keywords": { "description": "Keywords related to the title (maximum of 5).", "type": "array", "items": { "type": "string" } }, "contributors": { "description": "The contributors responsible for the product (authors, editors, illustrators, ...). Atleast one 'by_author' contributor is required.", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.DistributionContributor" } }, "audience": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.DistributionAudience", "description": "The audience the product is aimed at." }, "content": { "description": "Descriptive content for the title. A short description and a long description are both required.", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.DistributionContent" } }, "language": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.DistributionLanguage", "description": "The language of the title." }, "retail": { "description": "The retail offerings of the title, one per currency. A currency not provided here is not offered\r\nin that region.", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.DistributionPrice" } }, "subjects": { "description": "The subjects (BIC/BISAC/THEMA) of the product.", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.DistributionSubject" } }, "publication": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.DistributionPublication", "description": "Publication information (imprint, publisher, publication date)." } } }, "BookVAULT.ApiUtilities.DTOs.Requests.DistributionContributor": { "description": "A contributor responsible for the product.", "required": [ "role", "firstName" ], "type": "object", "properties": { "role": { "description": "The role of the contributor.", "enum": [ "By_author", "Libretto_by", "Illustrated_by", "Photographs_by", "Text_by", "Preface_by", "Afterword_by", "Notes_by", "Commentaries_by", "Foreword_by", "Introduction_by", "Contributions_by", "Drawings_by", "Edited_by", "Revised_by", "Adapted_by", "Translated_by", "Series_edited_by", "Volume_editor", "Founded_by", "Compiled_by", "Selected_by" ], "type": "string" }, "firstName": { "description": "The first name of the contributor (a brand-name contributor's name goes here).", "maxLength": 255, "minLength": 0, "type": "string" }, "lastName": { "description": "The surname of the contributor. If a brand-name is supplied, this can be left blank.", "maxLength": 255, "minLength": 0, "type": "string" }, "lettersAfterName": { "description": "Letters after the name, e.g. OBE.", "maxLength": 45, "minLength": 0, "type": "string" }, "brandName": { "description": "Whether the contributor is a brand name rather than a person. If set to 'true', only the 'firstName' field is required, which should be populated with the brand name.", "type": "boolean" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.DistributionAudience": { "description": "The audience the product is aimed at.", "required": [ "type", "value" ], "type": "object", "properties": { "type": { "description": "The audience code type (ONIX list 29).", "enum": [ "ONIX_audience_codes" ], "type": "string" }, "value": { "description": "The audience value (ONIX list 28).", "enum": [ "General_trade", "Children_juvenile", "Young_adult", "Primary_and_secondary_elementary_and_high_school", "College_higher_education", "Professional_and_scholarly", "ELT_ESL", "Adult_education", "Second_language_teaching" ], "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.DistributionContent": { "description": "A piece of descriptive content for the title.", "required": [ "type", "value" ], "type": "object", "properties": { "type": { "description": "The type of content (short description, long description, ...).", "enum": [ "Senderdefined_text", "Short_description_annotation", "Description", "Table_of_contents", "Flap_cover_copy", "Review_quote", "Review_quote_previous_edition", "Review_quote_previous_work", "Endorsement", "Promotional_headline", "Feature", "Biographical_note", "Publishers_notice", "Excerpt", "Index", "Short_description_annotation_for_collection", "Description_for_collection", "New_feature", "Version_history", "Open_access_statement", "Digital_exclusivity_statement", "Official_recommendation", "JBPA_description", "schema_org_snippet", "Errata", "Introduction", "Secondary_flap_cover_copy", "Full_cast_and_credit_list", "Bibliography", "Abstract", "Rules_or_instructions" ], "type": "string" }, "value": { "description": "The text value of the content.", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.DistributionLanguage": { "description": "The language of the title.", "required": [ "languageRole", "languageCode" ], "type": "object", "properties": { "languageRole": { "description": "The language role (ONIX list 22).", "enum": [ "Language_of_text", "Original_language_of_a_translated_text", "Language_of_abstracts", "Original_language_in_a_multilingual_edition", "Translated_language_in_a_multilingual_edition", "Language_of_audio_track", "Language_of_subtitles", "Language_of_original_audio_track", "Original_language_audio_track_in_a_multilingual_product", "Language_of_notes" ], "type": "string" }, "languageCode": { "format": "int32", "description": "The language code (ONIX list 74).", "type": "integer" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.DistributionPrice": { "description": "A retail offering of the title.", "required": [ "priceAmount", "currencyCode", "publisherDiscount" ], "type": "object", "properties": { "priceAmount": { "format": "double", "description": "The advertised retail price.", "type": "number" }, "currencyCode": { "description": "The currency of the retail offering.", "enum": [ "EUR", "GBP", "USD" ], "type": "string" }, "publisherDiscount": { "format": "int32", "description": "The percentage publisher discount offered on the product.", "type": "integer" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.DistributionSubject": { "description": "A subject classification for the title.", "required": [ "subjectIdentifier", "subjectCode" ], "type": "object", "properties": { "subjectIdentifier": { "description": "The subject scheme (BIC, BISAC, THEMA).", "enum": [ "BISAC_Subject_Heading", "BIC_subject_category", "Thema_subject_category" ], "type": "string" }, "subjectCode": { "description": "The subject code value, e.g. \"FIC000000\".", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.DistributionPublication": { "description": "Publication information for the title.", "required": [ "imprintName", "publisher", "publicationDate" ], "type": "object", "properties": { "imprintName": { "description": "The imprint name. It must already exist on your account.", "maxLength": 100, "minLength": 0, "type": "string" }, "publisher": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.DistributionPublisher", "description": "The publisher of the title." }, "publicationDate": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.DistributionPublishDate", "description": "The publication date of the title." } } }, "BookVAULT.ApiUtilities.DTOs.Requests.DistributionPublisher": { "description": "A publisher of the title.", "required": [ "cityOfPublication", "publisherName", "countryOfPublication" ], "type": "object", "properties": { "cityOfPublication": { "description": "The city the title was published in.", "maxLength": 99, "minLength": 0, "type": "string" }, "publisherName": { "description": "The name of the publisher.", "maxLength": 255, "minLength": 0, "type": "string" }, "countryOfPublication": { "format": "int32", "description": "The country of publication (ONIX list 91).", "type": "integer" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.DistributionPublishDate": { "description": "A publication date for the title.", "required": [ "publishingDateRole", "dateValue" ], "type": "object", "properties": { "publishingDateRole": { "description": "The purpose of the date.", "enum": [ "Publication_date" ], "type": "string" }, "dateValue": { "format": "date-time", "description": "The value of the date.", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.TitleFilesGetRequest": { "description": "Request for a title's file information, optionally filtered to specific file types.", "required": [ "isbn" ], "type": "object", "properties": { "isbn": { "description": "The ISBN13 of the title.", "maxLength": 13, "minLength": 13, "type": "string" }, "files": { "description": "Optionally restrict the results to these file types. Omit to return every possible file.", "type": "array", "items": { "enum": [ "None", "Cover", "Text", "Insert", "Jacket", "FoilBlock", "TearCover", "Disc", "DiscLabel", "CoverFoil", "JacketFoil", "EndPapers", "BoxSet", "SprayedEdges" ], "type": "string" } } } }, "BookVAULT.ApiUtilities.DTOs.Responses.TitleFile": { "description": "Information about one of a title's possible files.", "type": "object", "properties": { "fileType": { "description": "The type of file.", "enum": [ "None", "Cover", "Text", "Insert", "Jacket", "FoilBlock", "TearCover", "Disc", "DiscLabel", "CoverFoil", "JacketFoil", "EndPapers", "BoxSet", "SprayedEdges" ], "type": "string" }, "fileName": { "description": "The file's name, if one has been supplied.", "type": "string" }, "requested": { "description": "Whether this file is required/requested for the title.", "type": "boolean" }, "found": { "description": "Whether the file has been located.", "type": "boolean" }, "passed": { "description": "Whether the file has passed validation (checksum verified against the current preflight version).", "type": "boolean" }, "pendingUpload": { "description": "Whether the file is awaiting upload.", "type": "boolean" }, "checksum": { "description": "The MD5 checksum of the file, if known.", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.FileDropStatusGetRequest": { "description": "Request for the statuses of specific file drops.", "required": [ "dropIDs" ], "type": "object", "properties": { "dropIDs": { "description": "The IDs of the file drops to return the status for.", "type": "array", "items": { "format": "int32", "type": "integer" } } } }, "BookVAULT.ApiUtilities.DTOs.Responses.FileDropStatus": { "description": "The current status of a file drop.", "type": "object", "properties": { "dropID": { "format": "int32", "description": "The ID of the file drop.", "type": "integer" }, "fileType": { "description": "The type of file the drop is for.", "enum": [ "None", "Cover", "Text", "Insert", "Jacket", "FoilBlock", "TearCover", "Disc", "DiscLabel", "CoverFoil", "JacketFoil", "EndPapers", "BoxSet", "SprayedEdges" ], "type": "string" }, "status": { "description": "The current status of the drop.", "enum": [ "Downloading_File", "Processing", "Accepted", "Failed" ], "type": "string" }, "fileName": { "description": "The file name of the drop.", "type": "string" }, "checksum": { "description": "The MD5 checksum of the drop", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.FileUploadRequest": { "description": "A single file to create a download drop for, supplied by a publicly-accessible URL.", "required": [ "fileType", "url", "checksum" ], "type": "object", "properties": { "fileType": { "description": "The type of file being supplied.", "enum": [ "None", "Cover", "Text", "Insert", "Jacket", "FoilBlock", "TearCover", "Disc", "DiscLabel", "CoverFoil", "JacketFoil", "EndPapers", "BoxSet", "SprayedEdges" ], "type": "string" }, "url": { "description": "A publicly-accessible URL that BookVAULT will download the file from.", "type": "string" }, "checksum": { "description": "The MD5 checksum of the file. BookVAULT validates the downloaded file against it to detect\r\ncorruption.", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.FileDropCreated": { "description": "The result of creating a file drop: the file type it was created for and the assigned drop ID.", "type": "object", "properties": { "fileType": { "description": "The type of file the drop was created for.", "enum": [ "None", "Cover", "Text", "Insert", "Jacket", "FoilBlock", "TearCover", "Disc", "DiscLabel", "CoverFoil", "JacketFoil", "EndPapers", "BoxSet", "SprayedEdges" ], "type": "string" }, "dropID": { "format": "int32", "description": "The ID assigned to the created drop. Use it with the drop status endpoint to track progress.\r\nZero if the drop could not be created.", "type": "integer" }, "errors": { "description": "Any errors encountered while creating this drop. Empty when the drop was created successfully.", "type": "array", "items": { "type": "string" } } } }, "BookVAULT.ApiUtilities.DTOs.Requests.OrderGetRequest": { "required": [ "type", "value" ], "type": "object", "properties": { "type": { "description": "The type of reference being used to load the order.", "enum": [ "PodRef", "DocRef" ], "type": "string" }, "value": { "description": "The search value for the reference type.", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.Order": { "type": "object", "properties": { "identification": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.OrderIdentification", "description": "Identification details for the order" }, "metadata": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.OrderMetaData", "description": "The metadata for the order" }, "financials": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.OrderFinancials", "description": "The financial details for the order" }, "fulfillment": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.OrderFulfillment", "description": "The fulfillment details of the order" }, "orderLines": { "description": "The lines of the order.", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.OrderLine" } }, "bulkInfo": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.BulkInfo", "description": "If the order is part of a bulk import, information will be provided on the bulk orders" }, "messages": { "description": "A list of messages reported by the endpoint", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Message" } }, "criticalError": { "description": "True if an error occured which prevented the order from processing", "type": "boolean" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.OrderIdentification": { "description": "Identification details for an order", "type": "object", "properties": { "podRef": { "description": "Our reference for the order", "type": "string" }, "docRef": { "description": "Your order reference.", "type": "string" }, "custRef": { "description": "Your customer reference.", "type": "string" }, "custRef2": { "description": "Your second customer reference.", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.OrderMetaData": { "description": "Metadata for an order", "type": "object", "properties": { "dateCreated": { "format": "date-time", "description": "Date the order was created", "type": "string" }, "status": { "description": "The status of the order", "enum": [ "Draft", "Active", "PreSale", "BatchPayment", "Deleted" ], "type": "string" }, "orderMethod": { "description": "The method in which the order was received", "enum": [ "API", "Shopify", "WooCommerce", "Wix", "PayHip", "Zapier", "Kickstarter", "ImportTool", "Proof", "Other", "Collaborators_API" ], "type": "string" }, "weight": { "format": "int32", "description": "The total weight of the order in grams", "type": "integer" }, "productionLevel": { "description": "The level of service for the order", "enum": [ "Standard", "Express", "Priority", "Bespoke" ], "type": "string" }, "partner": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Partner", "description": "The partner the order was sent to" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.OrderFinancials": { "description": "Financial details for an order", "type": "object", "properties": { "orderCost": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.OrderCost", "description": "The cost breakdown of an order" }, "additionalCharges": { "description": "Additional Charges on the order", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.AdditionalItems" } }, "promoCode": { "description": "The promo code associated with this order, if applicable", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.OrderFulfillment": { "description": "Fulfillment details for an order", "type": "object", "properties": { "address": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.OrderAddress", "description": "The address to ship the order to." }, "service": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Service", "description": "The delivery service details of the order" }, "availableProdOptions": { "description": "The level of production available on this order", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ProductionOption" } }, "trackingDetails": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.TrackingDetails", "description": "Tracking details for the order" }, "progress": { "$ref": "#/definitions/BookVAULT.Progress", "description": "The progress of the order" }, "customsDeclaration": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.CustomsDeclaration", "description": "The customs declaration for overseas orders" }, "orderNotifications": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.OrderNotifications", "description": "The notification choices for the order" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.OrderLine": { "type": "object", "properties": { "lineNumber": { "format": "int32", "description": "The line number of the order, incrementing from 1 for each line", "type": "integer" }, "isbn": { "description": "The 13 digit ISBN of the required title", "type": "string" }, "quantity": { "format": "int32", "description": "The quantity of books required", "type": "integer" }, "linePrice": { "format": "double", "description": "The price of the order line", "type": "number" }, "linePricing": { "description": "The pricing breakdown for the order line", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.LinePricing" } }, "title": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ProductLite", "description": "The title associated with the order line" }, "lineProgress": { "$ref": "#/definitions/BookVAULT.Progress", "description": "The progress of the order line" }, "transient": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.OrderTransient", "description": "Transient (one-off) product details, present only when this line is a transient product rather\r\nthan a library title." } } }, "BookVAULT.ApiUtilities.DTOs.Responses.BulkInfo": { "description": "Bulk order information including total cost, partners, and progress.", "type": "object", "properties": { "name": { "description": "The name of the bulk order batch.", "type": "string" }, "orderCount": { "format": "int32", "description": "The total number of orders in this bulk batch.", "type": "integer" }, "totalQuantity": { "format": "int32", "description": "The total quantity of items across all orders in the bulk batch.", "type": "integer" }, "costs": { "description": "The total costs within the bulk batch, grouped by currency.", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.BulkInfoCost" } }, "partners": { "description": "The list of partners associated with this bulk batch.", "type": "array", "items": { "enum": [ "Bookvault_UK", "Bookvault_US", "Bookvault_AU", "Bookvault_CA" ], "type": "string" } }, "progress": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.BulkProgress", "description": "The progress information for this bulk batch." } } }, "BookVAULT.ApiUtilities.DTOs.Responses.Partner": { "description": "Represents a print or production partner in the BookVAULT system.", "type": "object", "properties": { "name": { "description": "The name of the partner.", "type": "string" }, "currencyID": { "description": "The base currency ID used by the partner.", "enum": [ "GBP", "USD", "AUD" ], "type": "string" }, "currency": { "description": "The human-readable currency name (beautified).", "type": "string" }, "originCountry": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Country", "description": "The origin country of the partner." }, "prodLevels": { "description": "A list of production options supported by the partner.", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.PartnerProdOption" } } } }, "BookVAULT.ApiUtilities.DTOs.Responses.OrderCost": { "description": "The cost breakdown of an order", "type": "object", "properties": { "productionCost": { "format": "double", "description": "The total production cost of the order", "type": "number" }, "dispatchCost": { "format": "double", "description": "The dispatch cost of the order", "type": "number" }, "surcharges": { "format": "double", "description": "Surcharges applicable to the order", "type": "number" }, "extrasCost": { "format": "double", "description": "The cost of extras on the order", "type": "number" }, "discount": { "format": "double", "description": "The total production cost of the order after promo code", "type": "number" }, "grandTotal": { "format": "double", "description": "The total cost of the order", "type": "number" }, "taxRates": { "description": "The tax lines on an order", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.TaxRate" } }, "tax": { "format": "double", "description": "The amount of Tax/VAT due on the order", "type": "number" }, "dutiesTaxesAndFees": { "format": "double", "description": "The import duties and taxes recharged on this order. Only non-zero where the\r\ncustoms declaration is DDP - under DDU the recipient pays the carrier on delivery,\r\nand under IOSS the VAT is accounted for against your own IOSS number. This amount\r\nis already included in 'extrasCost' and 'grandTotal'.", "type": "number" }, "paymentLink": { "description": "The link returned if funds need to be added to your account", "type": "string" } } }, "BookVAULT.AdditionalItems": { "type": "object", "properties": { "description": { "description": "The description of the additional item", "type": "string", "readOnly": true }, "ammount": { "format": "double", "description": "The ammount charged for the item", "type": "number", "readOnly": true }, "type": { "description": "The type of charge", "enum": [ "Title_Fee", "Additional_Tree", "Production_Upgrade", "Carbon_Offset", "Impact_Scheme", "Surcharge", "Duties_Taxes_And_Fees" ], "type": "string", "readOnly": true } } }, "BookVAULT.ApiUtilities.DTOs.Responses.OrderAddress": { "type": "object", "properties": { "addressee": { "description": "The name of the addressee (person receiving the item).", "type": "string" }, "address1": { "description": "The first line of the address.", "type": "string" }, "address2": { "description": "The second line of the address.", "type": "string" }, "address3": { "description": "The third line of the address.", "type": "string" }, "address4": { "description": "The fourth line of the address.", "type": "string" }, "town": { "description": "The town or city of the address.", "type": "string" }, "county": { "description": "The county, region, or state of the address.", "type": "string" }, "country": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Country", "description": "The destination country of the address." }, "postCode": { "description": "The postal or ZIP code.", "type": "string" }, "company": { "description": "The company name, if applicable.", "type": "string" }, "email": { "description": "The email address associated with the order.", "type": "string" }, "telNumber": { "description": "The telephone number associated with the order.", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.ProductionOption": { "type": "object", "properties": { "level": { "description": "The service level", "enum": [ "Standard", "Express", "Priority", "Bespoke" ], "type": "string" }, "estDispatch": { "format": "date-time", "description": "The estimated date of dispatch", "type": "string" }, "estSentToPrint": { "format": "date-time", "description": "The estimated date/time when the title will be sent to print", "type": "string" }, "percentage": { "format": "double", "description": "The additional production percentage", "type": "number" }, "additionalCost": { "format": "double", "description": "The additional production cost", "type": "number" }, "totalCost": { "format": "double", "description": "The total production cost of the order", "type": "number" }, "partner": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Partner", "description": "The partner the price is associated with" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.TrackingDetails": { "description": "Tracking details for an order", "type": "object", "properties": { "tracked": { "description": "Whether the order was sent using a tracked service", "type": "boolean" }, "trackingNumber": { "description": "The tracking refernce supplied by the courrier", "type": "string" }, "baseURL": { "description": "The base URL used to track orders by this carrier", "type": "string" }, "combinedURL": { "description": "The full URL to track the order", "type": "string" }, "servName": { "description": "The name of the service used to send the order", "type": "string" }, "servDetail": { "description": "Description of the service which the order has been sent using", "type": "string" } } }, "BookVAULT.Progress": { "description": "The progress of an order/order line", "type": "object", "properties": { "status": { "description": "The current status of the order", "enum": [ "Created", "Acknowledged", "SentToPrint", "Batched", "Printed", "Dispatched", "Invoiced" ], "type": "string", "readOnly": true }, "created": { "format": "date-time", "description": "The date/time in which it was created", "type": "string", "readOnly": true }, "acknowledged": { "format": "date-time", "description": "The date/time in which it was acknowledged", "type": "string", "readOnly": true }, "isAcknowledged": { "description": "Whether it has been acknowledged", "type": "boolean", "readOnly": true }, "printSent": { "format": "date-time", "description": "The date/time in which it was sent to print", "type": "string", "readOnly": true }, "isPrintSent": { "description": "Wether the order has been sent to print", "type": "boolean", "readOnly": true }, "batched": { "format": "date-time", "description": "The date/time in which the order was batched for print", "type": "string", "readOnly": true }, "isBatched": { "description": "Whether the order has been bactched", "type": "boolean", "readOnly": true }, "printed": { "format": "date-time", "description": "The date/time in which the order was printed", "type": "string", "readOnly": true }, "isPrinted": { "description": "Whether the order has been printed", "type": "boolean", "readOnly": true }, "dispatched": { "format": "date-time", "description": "The date/time in which the order was dispatched", "type": "string", "readOnly": true }, "isDispatched": { "description": "Whether the order has been dispatched", "type": "boolean", "readOnly": true }, "invoiced": { "format": "date-time", "description": "The date/time in which the order was invoiced", "type": "string", "readOnly": true }, "isInvoiced": { "description": "Whether the order has been invoiced", "type": "boolean", "readOnly": true }, "deadLine": { "format": "date-time", "description": "The date/time in which the order is due", "type": "string", "readOnly": true }, "isDeadLine": { "description": "Whether the order has a deadline set", "type": "boolean", "readOnly": true } } }, "BookVAULT.ApiUtilities.DTOs.Responses.CustomsDeclaration": { "description": "The customs declaration for overseas orders", "type": "object", "properties": { "declaredValue": { "format": "double", "description": "The declared value of the shipment", "type": "number" }, "hsCode": { "description": "The HS Code of the order", "type": "string" }, "useIOSS": { "description": "Whether an IOSS code should be used", "type": "boolean" }, "ioss": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.IOSS", "description": "The IOSS information" }, "incoTerms": { "description": "The Incoterms to use when shipping this order", "type": "string" }, "useOrderValue": { "description": "Whether the declared value was taken from the order's own value rather than supplied.", "type": "boolean" }, "dutiesTaxesAndFees": { "format": "double", "description": "The import duties and taxes recharged on this order, as estimated by the carrier.\r\nOnly charged on DDP orders.", "type": "number" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.OrderNotifications": { "description": "The notification choices for the order", "type": "object", "properties": { "notifyCustomer": { "description": "Whether a dispatch notification is required. If requested, an email will be sent to the email registered to the account when the order has been dispatched.", "type": "boolean" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.LinePricing": { "type": "object", "properties": { "unitPrice": { "format": "double", "description": "The unit price of the requested title", "type": "number" }, "appliedDiscount": { "format": "double", "description": "The applied discount, as per your BookVAULT Pricing agreement", "type": "number" }, "volumeSaving": { "format": "double", "description": "The amount saved using your volume discount", "type": "number" }, "lineTotals": { "format": "double", "description": "The total cost of the order line", "type": "number" }, "partner": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Partner", "description": "The partner associated with the price" }, "canPrint": { "description": "Whether or not the line can be printed", "type": "boolean" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.ProductLite": { "type": "object", "properties": { "isbn": { "description": "The ISBN of the product", "type": "string" }, "title": { "description": "The title of the product", "type": "string" }, "status": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ProductStatus", "description": "The status of the product" }, "pricing": { "description": "Pricing information for the product", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ProductPricing" } }, "volumes": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ProductVolume", "description": "Defines whether the title is a volume set" }, "validated": { "description": "Whether the title has been Validated", "type": "boolean" }, "titleType": { "description": "The type of product", "enum": [ "Standard", "Transient", "Personalised", "Bespoke", "Box" ], "type": "string" }, "specs": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ProductLiteSpecs", "description": "Grouped specifications for the product" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.OrderTransient": { "description": "The transient (one-off) product details for an order line that was ordered as a transient item\r\nrather than a library title.", "type": "object", "properties": { "orderName": { "description": "The name given to the transient product/line.", "type": "string" }, "colourPages": { "format": "int32", "description": "The number of colour pages.", "type": "integer" }, "monoPages": { "format": "int32", "description": "The number of mono (black & white) pages.", "type": "integer" }, "sizeDepth": { "format": "int32", "description": "The spine/size depth in mm.", "type": "integer" }, "unitWeight": { "format": "int32", "description": "The unit weight in grams.", "type": "integer" }, "foilSpineText": { "description": "The spine foiling text, if any.", "type": "string" }, "coverFile": { "description": "The cover file reference.", "type": "string" }, "textFile": { "description": "The text (internal pages) file reference.", "type": "string" }, "insertFile": { "description": "The insert file reference, if any.", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.BulkInfoCost": { "description": "Represents a cost entry for a bulk order, containing a currency and corresponding amount.", "type": "object", "properties": { "currency": { "description": "The currency associated with the total amount.", "enum": [ "GBP", "USD", "AUD" ], "type": "string" }, "amount": { "format": "double", "description": "The total amount for the specified currency.", "type": "number" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.BulkProgress": { "description": "Represents the progress status of a bulk order batch, including various stages of processing.", "type": "object", "properties": { "created": { "format": "int32", "description": "The number of orders created.", "type": "integer" }, "acknowledged": { "format": "int32", "description": "The number of orders acknowledged.", "type": "integer" }, "sentToPrint": { "format": "int32", "description": "The number of orders sent to print.", "type": "integer" }, "printed": { "format": "int32", "description": "The number of orders that have been printed.", "type": "integer" }, "dispatched": { "format": "int32", "description": "The number of orders that have been dispatched.", "type": "integer" }, "invoiced": { "format": "int32", "description": "The number of orders that have been invoiced.", "type": "integer" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.PartnerProdOption": { "description": "Represents a production level option supported by a partner.", "type": "object", "properties": { "level": { "description": "The production level (e.g., Standard, Express).", "enum": [ "Standard", "Express", "Priority", "Bespoke" ], "type": "string" }, "days": { "format": "int32", "description": "The estimated number of production days required for this option.", "type": "integer" }, "cutoffTime": { "format": "int32", "description": "The time of day after which production rolls over to the next working day.", "type": "integer" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.TaxRate": { "type": "object", "properties": { "name": { "description": "The name of the tax rate", "type": "string" }, "percentage": { "format": "double", "description": "The percentage of the tax rate", "type": "number" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.IOSS": { "type": "object", "properties": { "registeredName": { "description": "The name registered to the IOSS Number", "type": "string" }, "iossCode": { "description": "The IOSS Code", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.ProductStatus": { "description": "The status of a product", "type": "object", "properties": { "status": { "description": "The current status of the product", "enum": [ "Pending_Approval", "Active", "Suspended", "On_Proof", "Stock_Only", "Cancelled", "Awaiting_Payment", "Pending_Publication", "Customer_Approval", "Pending_Review", "Action_Required", "Blocked" ], "type": "string" }, "beautified": { "description": "A beautified string of the value", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.ProductPricing": { "type": "object", "properties": { "price": { "format": "double", "description": "The total price of the product", "type": "number" }, "bindPrice": { "format": "double", "description": "The total price of binding the product", "type": "number" }, "chargedColourPages": { "format": "int32", "description": "The total amount charged for colour printing", "type": "integer" }, "colourPagePrice": { "format": "double", "description": "The price charged per colour page", "type": "number" }, "chargedMonoPages": { "format": "int32", "description": "The total amount charged for mono printing", "type": "integer" }, "monoPagePrice": { "format": "double", "description": "The price charged per mono page", "type": "number" }, "printPrice": { "format": "double", "description": "The total price charged for printing", "type": "number" }, "extrasPrice": { "format": "double", "description": "The price of any extras added", "type": "number" }, "canPrint": { "description": "Whether the partner can print this product", "type": "boolean" }, "messages": { "description": "Where applicable, why the partner is unable to print the product", "type": "array", "items": { "type": "string" } }, "partner": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Partner", "description": "The partner associated with the pricing" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.ProductVolume": { "type": "object", "properties": { "hasVolumes": { "description": "Whether the product volume has volumes within it", "type": "boolean" }, "boxSet": { "description": "Whether the product volume is a box set", "type": "boolean" }, "children": { "description": "The child volumes within the product volume", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ProductChild" } }, "box": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ProductLite", "description": "The box product if applicable" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.ProductLiteSpecs": { "type": "object", "properties": { "pages": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ProductLiteSpecPages", "description": "Page-related specifications." }, "dimensions": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ProductLiteSpecDimensions", "description": "Dimension-related specifications." }, "weight": { "format": "int32", "description": "The weight of the product in grams", "type": "integer" }, "textStock": { "format": "int32", "description": "The text stock of the title", "type": "integer" }, "coverStock": { "format": "int32", "description": "The Cover stock of the title", "type": "integer" }, "lamination": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.LaminationType", "description": "The Lamination of the product" }, "binding": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Binding", "description": "The binding of the product" }, "premium": { "description": "Whether the product is premium", "type": "boolean" }, "hasJacket": { "description": "Whether the product has a jacket", "type": "boolean" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.ProductChild": { "type": "object", "properties": { "isbn": { "description": "The ISBN of the child volume", "type": "string" }, "title": { "description": "The title of the child volume", "type": "string" }, "quantity": { "format": "int32", "description": "The quantity of the child volume", "type": "integer" }, "binding": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Binding", "description": "The binding of the child volume" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.ProductLiteSpecPages": { "type": "object", "properties": { "colourPages": { "format": "int32", "description": "The total number of colour pages in the book", "type": "integer" }, "monoPages": { "format": "int32", "description": "The total number of mono pages in the book", "type": "integer" }, "totalPages": { "format": "int32", "description": "The total number of pages in the book", "type": "integer" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.ProductLiteSpecDimensions": { "type": "object", "properties": { "sizeHeight": { "format": "int32", "description": "The height of the title", "type": "integer" }, "sizeWidth": { "format": "int32", "description": "The width of the title", "type": "integer" }, "spine": { "format": "int32", "description": "The spine width of the product", "type": "integer" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.LaminationType": { "description": "The lamination of a product", "type": "object", "properties": { "beautified": { "description": "String value of the products lamination", "type": "string" }, "lamination": { "description": "The lamination of the product", "enum": [ "Gloss", "Matte" ], "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.Binding": { "type": "object", "properties": { "bindType": { "description": "The binding of the product", "enum": [ "PerfectBound", "CasePPC", "CaseCloth", "WireBound", "SaddleStitch", "SpiralBound", "None", "Bundle" ], "type": "string" }, "beautified": { "description": "String value of the products binding", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.OrderPostRequest": { "required": [ "docRef", "address", "orderLines", "dispatchRequest", "partner" ], "type": "object", "properties": { "docRef": { "description": "Your order reference.", "maxLength": 90, "minLength": 0, "type": "string" }, "custRef": { "description": "Your customer reference.", "maxLength": 90, "minLength": 0, "type": "string" }, "custRef2": { "description": "Your second customer reference.", "maxLength": 90, "minLength": 0, "type": "string" }, "address": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.OrderAddress", "description": "The address to ship the order to." }, "orderLines": { "description": "The lines of the order.", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.OrderLine" } }, "dispatchRequest": { "$ref": "#/definitions/BookVAULT.DispatchRequest", "description": "The requested service when placing an order, allowing either a specific service\r\nto be selected, or the logic to choose which service to use." }, "productionLevel": { "description": "The level of service for the order, default standard.", "enum": [ "Standard", "Express", "Priority", "Bespoke" ], "type": "string" }, "partner": { "description": "The print partner to use for the order.", "enum": [ "Bookvault_UK", "Bookvault_US", "Bookvault_AU", "Bookvault_CA" ], "type": "string" }, "customsDeclaration": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.CustomsDeclaration", "description": "Customs declaration information for orders shipped internationally.\r\nThis is required when the destination country is different from the print partner's country." } } }, "BookVAULT.ApiUtilities.DTOs.Requests.OrderAddress": { "required": [ "addressee", "address1", "town", "countryCode", "postCode" ], "type": "object", "properties": { "addressee": { "description": "The name of the addressee (person receiving the item).\r\nFor US addresses, the first and last name is required.", "maxLength": 200, "minLength": 0, "type": "string" }, "address1": { "description": "The first line of the address.", "maxLength": 200, "minLength": 0, "type": "string" }, "address2": { "description": "The second line of the address.", "maxLength": 250, "minLength": 0, "type": "string" }, "address3": { "description": "The third line of the address.", "maxLength": 99, "minLength": 0, "type": "string" }, "address4": { "description": "The fourth line of the address.", "maxLength": 99, "minLength": 0, "type": "string" }, "town": { "description": "The town or city of the address.", "maxLength": 99, "minLength": 0, "type": "string" }, "county": { "description": "The county, region, or state of the address.\r\nFor US or Canada addresses, this is required and should be given as the 2-digit state/province code.", "maxLength": 200, "minLength": 0, "type": "string" }, "countryCode": { "description": "The ISO country code for the address.", "type": "string" }, "postCode": { "description": "The postal or ZIP code.", "maxLength": 99, "minLength": 0, "type": "string" }, "company": { "description": "The company name, if applicable.", "maxLength": 200, "minLength": 0, "type": "string" }, "email": { "description": "The email address associated with the order.", "maxLength": 120, "minLength": 0, "type": "string" }, "telNumber": { "description": "The telephone number associated with the order.", "maxLength": 35, "minLength": 0, "type": "string" } } }, "BookVAULT.DispatchRequest": { "description": "The requested service when placing an order, allowing either a specific service to be selected, or the logic to choose which service to use.", "required": [ "requestedService" ], "type": "object", "properties": { "requestedServID": { "description": "The ServIDs requested. Only required if using the [Specified] Requested Service Type.", "type": "array", "items": { "format": "int32", "type": "integer" } }, "requestedService": { "description": "The requested service type", "enum": [ "Quickest", "Cheapest", "Specified", "Tracked", "NotSpecified", "CheapestTracked" ], "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.CustomsDeclaration": { "required": [ "hsCode", "useIOSS", "incoTerms" ], "type": "object", "properties": { "declaredValue": { "format": "double", "description": "The declared value of the shipment in GBP (£). If payment is made in another currency, the value must be converted to GBP before being supplied.\r\nRequired unless 'useOrderValue' is set to 'true', in which case it is ignored and the order's own value is declared instead.", "type": "number" }, "useOrderValue": { "description": "Set to 'true' to declare the value of the order itself rather than supplying your own figure.\r\nWhen 'true', 'declaredValue' is not required and any value supplied is ignored.", "type": "boolean" }, "hsCode": { "description": "The Harmonized System (HS) code for the shipment.", "type": "string" }, "useIOSS": { "description": "Indicates whether IOSS should be used for this shipment. If set to 'true', an 'iossCode' must also be supplied.", "type": "boolean" }, "iossCode": { "description": "The IOSS code to use for the shipment. If supplied, 'useIOSS' must also be set to 'true'.", "type": "string" }, "incoTerms": { "description": "The Incoterms to apply to the shipment.", "enum": [ "DDU", "DDP", "DAP" ], "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.OrderPostResponse": { "type": "object", "properties": { "podRef": { "format": "int32", "description": "PodRef of the created order", "type": "integer" }, "message": { "description": "Status message of the response", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.OrderDeleteRequest": { "required": [ "type", "value" ], "type": "object", "properties": { "type": { "description": "The type of reference being used to identify the order.", "enum": [ "PodRef", "DocRef" ], "type": "string" }, "value": { "description": "The search value for the reference type.", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.OrderDeleteResponse": { "type": "object", "properties": { "success": { "description": "Whether the deletion was successful or not", "type": "boolean" }, "errors": { "description": "Any error messages returned during the deletion, if applicable", "type": "array", "items": { "type": "string" } } } }, "BookVAULT.ApiUtilities.DTOs.Responses.OrderReference": { "description": "A generated order reference, unique to your account, to use as the document reference when placing\r\nan order.", "type": "object", "properties": { "reference": { "description": "The generated order reference (e.g. \"ABC-#00001\").", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.TransientSkuRequest": { "description": "The component parts of a transient product, sent to the transient SKU endpoint to generate a\r\ncorrectly-formatted product SKU.", "required": [ "stockWeight", "lamination", "binding", "height", "width" ], "type": "object", "properties": { "stockWeight": { "format": "int32", "description": "The paper weight in gsm.", "maximum": 999, "minimum": 1, "type": "integer" }, "coated": { "description": "Whether the paper stock is coated.", "type": "boolean" }, "creamy": { "description": "Whether the paper stock is creamy (off-white). False means white.", "type": "boolean" }, "lamination": { "description": "The lamination applied to the cover.", "enum": [ "Gloss", "Matte" ], "type": "string" }, "binding": { "description": "The binding of the product.", "enum": [ "PerfectBound", "CasePPC", "CaseCloth", "WireBound", "SaddleStitch", "SpiralBound", "None", "Bundle" ], "type": "string" }, "height": { "format": "int32", "description": "The finished height in mm.", "maximum": 999, "minimum": 1, "type": "integer" }, "width": { "format": "int32", "description": "The finished width in mm.", "maximum": 999, "minimum": 1, "type": "integer" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.TransientSkuResponse": { "description": "A generated transient product SKU.", "type": "object", "properties": { "sku": { "description": "The generated, correctly-formatted transient product SKU.", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.OrderValidation": { "description": "The result of validating an order: whether it passed and any messages raised during validation.", "type": "object", "properties": { "valid": { "description": "True if the order passed validation (no critical errors were raised).", "type": "boolean" }, "messages": { "description": "The messages raised during validation (errors, warnings and information).", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Message" } } } }, "BookVAULT.ApiUtilities.DTOs.Requests.OrdersGetRequest": { "required": [ "ordersPerPage", "pageNumber" ], "type": "object", "properties": { "ordersPerPage": { "format": "int32", "description": "Number of orders to show per page", "maximum": 10, "minimum": 1, "type": "integer" }, "pageNumber": { "format": "int32", "description": "The page number to load", "minimum": 1, "type": "integer" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.OrdersResponse": { "type": "object", "properties": { "orders": { "description": "The list of orders returned", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Order" } }, "pagination": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.OrdersResponsePagination", "description": "Pagination options for loading any additional orders where available" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.OrdersResponsePagination": { "type": "object", "properties": { "currentPage": { "format": "int32", "description": "The current page number being viewed", "type": "integer" }, "ordersPerPage": { "format": "int32", "description": "The number of orders being shown per page", "type": "integer" }, "totalOrders": { "format": "int32", "description": "The total number of orders available", "type": "integer" }, "totalPages": { "format": "int32", "description": "The total number of pages available", "type": "integer" }, "hasNextPage": { "description": "True if there is a next page available", "type": "boolean" }, "hasPreviousPage": { "description": "True if there is a previous page available", "type": "boolean" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.OrdersPostRequest": { "required": [ "ordersPerPage", "pageNumber" ], "type": "object", "properties": { "ordersPerPage": { "format": "int32", "description": "Number of orders to show per page", "maximum": 10, "minimum": 1, "type": "integer" }, "pageNumber": { "format": "int32", "description": "The page number to load", "minimum": 1, "type": "integer" }, "createdAfter": { "format": "date-time", "description": "Show only orders placed after this date", "type": "string" }, "createdBefore": { "format": "date-time", "description": "Show only orders placed before this date", "type": "string" }, "podRefs": { "description": "Show only orders with the specified PodRefs", "type": "array", "items": { "format": "int32", "type": "integer" } }, "partners": { "description": "Show only orders from the given partners", "type": "array", "items": { "enum": [ "Bookvault_UK", "Bookvault_US", "Bookvault_AU", "Bookvault_CA" ], "type": "string" } } } }, "BookVAULT.ApiUtilities.DTOs.Responses.Product": { "required": [ "isbn" ], "type": "object", "properties": { "isbn": { "description": "The ISBN of the title in ISBN13 format", "maxLength": 13, "minLength": 13, "type": "string" }, "promoCode": { "description": "A promo code for adding the title if applicable", "type": "string" }, "dateCreated": { "format": "date-time", "description": "The date the title was created", "type": "string" }, "status": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ProductStatus", "description": "The current status of the title" }, "validated": { "description": "Whether the title has been validated", "type": "boolean" }, "titleIntent": { "description": "The intent of the title", "enum": [ "Print", "Distribution", "Publishing", "None", "Bundle", "Bespoke", "Box" ], "type": "string" }, "publishing": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ProductPublishing", "description": "The publishing information for your title. Only Applicable if the title is setup as a Bookvault publishing project" }, "linkedApps": { "description": "Apps linked to the title", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ProductApps" } }, "titleType": { "description": "The clasification of product within Bookvault", "enum": [ "Standard", "Transient", "Personalised", "Bespoke", "Box" ], "type": "string" }, "title": { "description": "The title of the product", "type": "string" }, "canProof": { "description": "Whether a virtual proof is available", "type": "boolean" }, "specifications": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ProductSpecifications", "description": "The specifications of the title" }, "bespokeOptions": { "description": "The list of bespoke options added to the title", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ChosenOption" } }, "pricing": { "description": "The pricing associated with the title", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ProductPricing" } }, "retailDetail": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.RetailProduct", "description": "The retail information about the title" }, "volumes": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ProductVolume", "description": "Defines whether the title is a volume set" }, "messages": { "description": "A list of messages reported by the endpoint", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Message" } } } }, "BookVAULT.ApiUtilities.DTOs.Responses.ProductPublishing": { "type": "object", "properties": { "progress": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.PublicationProgress", "description": "The progress of the publication project" }, "copyrightLocation": { "format": "int32", "description": "The page number that the copyright page will be placed", "type": "integer" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.ProductApps": { "type": "object", "properties": { "updated": { "format": "date-time", "description": "Date the app data was last updated.", "type": "string" }, "price": { "format": "double", "description": "Retail price of the product.", "type": "number" }, "content": { "description": "App content or description.", "type": "string" }, "preSale": { "description": "Indicates whether the product is available for pre-sale.", "type": "boolean" }, "releaseDate": { "format": "date-time", "description": "Scheduled release date.", "type": "string" }, "url": { "description": "Associated product URL.", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.ProductSpecifications": { "description": "The specifications of the product", "type": "object", "properties": { "monoPages": { "format": "int32", "description": "The number of mono pages the product has", "type": "integer" }, "colourPages": { "format": "int32", "description": "The number of colour pages the product has", "type": "integer" }, "totalPages": { "format": "int32", "description": "The total number of pages your product has", "type": "integer" }, "fullColour": { "description": "Whether the product is deemed as full colour as per your pricing agreement", "type": "boolean" }, "binding": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Binding", "description": "The binding of the product" }, "sizeType": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.SizeType", "description": "The size type of the product" }, "finishedHeight": { "format": "int32", "description": "The finished height of the product in mm", "type": "integer" }, "finishedWidth": { "format": "int32", "description": "The finished width of the product in mm", "type": "integer" }, "bulk": { "format": "double", "description": "The bulk of the paper in mm", "type": "number" }, "spine": { "format": "double", "description": "The spine width of the product in mm", "type": "number" }, "weight": { "format": "int32", "description": "The weight of the product in grams", "type": "integer" }, "stocks": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ProductStocks", "description": "The paper stocks used by the product" }, "lamination": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.LaminationType", "description": "The lamination of the product" }, "premium": { "description": "Whether the product is to be printed using premium methods", "type": "boolean" }, "sameDay": { "description": "Whether the product is available for same day dispatch (contract dependant)", "type": "boolean" }, "extras": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ProductExtras", "description": "Specifies any extras added to the product" }, "coverSizing": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.CoverSizing", "description": "Specifies the required size for the cover" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.ChosenOption": { "description": "Represents a selected option and its associated details.", "type": "object", "properties": { "choice": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.BasicOption", "description": "The base option that was chosen." }, "variation": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.VariationOption", "description": "The specific variation of the chosen option." }, "data": { "description": "Additional data supplied for this choice.", "type": "string" }, "price": { "format": "double", "description": "The price impact of the chosen option.", "type": "number" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.PublicationProgress": { "type": "object", "properties": { "status": { "description": "Publication status.", "enum": [ "Awaiting_ISBN", "Awaiting_Speicifications", "Awaiting_Files", "Awaiting_Proof", "Awaiting_MetaData", "Awaiting_Approval", "Awaiting_Publication", "Awaiting_Listing", "Complete" ], "type": "string" }, "statusDescription": { "description": "Description of the status.", "type": "string" }, "hasISBN": { "description": "Indicates whether the product has an ISBN.", "type": "boolean" }, "dateISBNAllocated": { "format": "date-time", "description": "Date the ISBN was allocated.", "type": "string" }, "hasSpecifications": { "description": "Indicates whether specifications have been supplied.", "type": "boolean" }, "dateSpecificationsSupplied": { "format": "date-time", "description": "Date specifications were supplied.", "type": "string" }, "hasFiles": { "description": "Indicates whether files have been supplied.", "type": "boolean" }, "dateFilesSupplied": { "format": "date-time", "description": "Date files were supplied.", "type": "string" }, "proofIsOrdered": { "description": "Indicates whether a proof is ordered.", "type": "boolean" }, "dateProofOrdered": { "format": "date-time", "description": "Date the proof was ordered.", "type": "string" }, "hasMeta": { "description": "Indicates whether metadata has been supplied.", "type": "boolean" }, "dateMetadataSupplied": { "format": "date-time", "description": "Date metadata was supplied.", "type": "string" }, "isApproved": { "description": "Indicates whether the product is approved.", "type": "boolean" }, "dateApproved": { "format": "date-time", "description": "Date the product was approved.", "type": "string" }, "isPublished": { "description": "Indicates whether the product is published.", "type": "boolean" }, "datePublished": { "format": "date-time", "description": "Date the product was published.", "type": "string" }, "isListed": { "description": "Indicates whether the product is listed.", "type": "boolean" }, "dateListed": { "format": "date-time", "description": "Date the product was listed.", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.SizeType": { "description": "The size type of a product", "type": "object", "properties": { "beautified": { "description": "String value of the size name", "type": "string" }, "sizeType": { "description": "The sizing of the product", "enum": [ "Standard", "Demy", "Custom", "Royal", "A4", "A5", "US_Royal", "Pinched_Crown", "B_Format", "Crown_Quarto", "Novel", "Square_210", "DL", "US_Letter" ], "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.ProductStocks": { "description": "The paper stocks used by a product", "type": "object", "properties": { "textStock": { "format": "int32", "description": "The text stock ID", "type": "integer" }, "textStockName": { "description": "The name of the text stock", "type": "string" }, "coverStock": { "format": "int32", "description": "The cover stock ID", "type": "integer" }, "coverStockName": { "description": "The name of the cover stock", "type": "string" }, "foilColour": { "format": "int32", "description": "The stock ID of the foil, set to 0 for no foil blocking", "type": "integer" }, "foilColourName": { "description": "The name of the chosen foil colour, if applicable", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.ProductExtras": { "description": "The extras associated with the product", "type": "object", "properties": { "hasJacket": { "description": "Whether the title has a jacket", "type": "boolean" }, "hasFrontFoil": { "description": "Whether the front cover has foil", "type": "boolean" }, "frontFoil": { "format": "int32", "description": "The position of the front foil, if applicable", "type": "integer" }, "hasSpineFoil": { "description": "Whether the spine has foil", "type": "boolean" }, "spineFoil": { "format": "int32", "description": "The position of the spine foil, if applicable", "type": "integer" }, "hasFoilText": { "description": "Whether the product has foil text added", "type": "boolean" }, "foilText": { "description": "The text to be added as digital foil blocking, if applicable", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.CoverSizing": { "description": "Specifies the required size for a title cover", "type": "object", "properties": { "expectedHeight": { "format": "int32", "description": "The expected height of the cover", "type": "integer" }, "expectedWidth": { "format": "int32", "description": "The expected width of the cover", "type": "integer" }, "hasBleed": { "description": "Whether the title has bleed", "type": "boolean" }, "requiredBleed": { "format": "int32", "description": "The bleed required for the cover (wrap around included for PPC covers)", "type": "integer" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.BasicOption": { "description": "Represents a basic option available for selection.", "type": "object", "properties": { "name": { "description": "The display name of the option.", "type": "string" }, "fileRequired": { "description": "Whether this option requires a file upload.", "type": "boolean" }, "allowMultiple": { "description": "Whether multiple selections of this option are permitted.", "type": "boolean" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.VariationOption": { "description": "Represents a variation of a basic option.", "type": "object", "properties": { "name": { "description": "The display name of the variation.", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.TitlePutRequest": { "description": "The details used to update an existing title. The title is identified by the ISBN in the route,\r\nso no ISBN is supplied here; the supplied title, specifications and bespoke options replace those\r\ncurrently held against the title.", "required": [ "title", "specifications" ], "type": "object", "properties": { "title": { "description": "The title of the product", "maxLength": 255, "minLength": 0, "type": "string" }, "specifications": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.TitleSpecifications", "description": "The specifications of the title" }, "bespokeOptions": { "description": "Optional bespoke options to add to the title. The supplied set replaces any existing options.", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.TitleBespokeOption" } } } }, "BookVAULT.ApiUtilities.DTOs.Requests.TitleSpecifications": { "description": "The specifications for a new title.", "required": [ "binding", "dimensions", "stocks", "lamination" ], "type": "object", "properties": { "monoPages": { "format": "int32", "description": "The number of mono (black & white) pages", "minimum": 0, "type": "integer" }, "colourPages": { "format": "int32", "description": "The number of colour pages", "minimum": 0, "type": "integer" }, "binding": { "description": "The binding of the title", "enum": [ "PerfectBound", "CasePPC", "CaseCloth", "WireBound", "SaddleStitch", "SpiralBound", "None", "Bundle" ], "type": "string" }, "dimensions": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.TitleDimensions", "description": "The finished dimensions of the title" }, "stocks": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.TitleStocks", "description": "The paper stocks used by the title" }, "lamination": { "description": "The lamination applied to the cover", "enum": [ "Gloss", "Matte" ], "type": "string" }, "premium": { "description": "Whether the title is printed using premium methods", "type": "boolean" }, "extras": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.TitleExtras", "description": "Optional extras for the title (e.g. dust jacket, foiling)" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.TitleBespokeOption": { "description": "A bespoke option to add to a title. Both identifiers are available from the codelist endpoint.", "type": "object", "properties": { "optionID": { "format": "int32", "description": "The identifier of the bespoke option.", "minimum": 1, "type": "integer" }, "choiceID": { "format": "int32", "description": "The identifier of the chosen variation/choice for the option.", "minimum": 1, "type": "integer" }, "data": { "description": "Optional data associated with the chosen option.", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.TitleDimensions": { "description": "The finished dimensions of a title. Height and width may be supplied in the unit of your\r\nchoice; they are converted to whole millimetres for storage.", "required": [ "height", "width" ], "type": "object", "properties": { "height": { "format": "double", "description": "The finished height of the title, in the supplied {BookVAULT.ApiUtilities.DTOs.Requests.TitleDimensions.Unit}.", "type": "number" }, "width": { "format": "double", "description": "The finished width of the title, in the supplied {BookVAULT.ApiUtilities.DTOs.Requests.TitleDimensions.Unit}.", "type": "number" }, "unit": { "description": "The unit the height and width are supplied in. Defaults to millimetres.", "enum": [ "Millimeter", "Centimeter", "Inch" ], "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.TitleStocks": { "description": "The paper stocks used by a title.", "type": "object", "properties": { "textStock": { "format": "int32", "description": "The identifier of the text (internal pages) stock", "minimum": 1, "type": "integer" }, "coverStock": { "format": "int32", "description": "The identifier of the cover stock. Required unless the BindType is 'None'.", "type": "integer" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.TitleExtras": { "description": "Optional extras that can be added to a title.", "type": "object", "properties": { "hasJacket": { "description": "Whether the title has a dust jacket", "type": "boolean" }, "foilText": { "description": "The text to be foiled, if foiling is required", "type": "string" }, "frontFoil": { "description": "The position of the foil on the front cover. Leave null for no front foil.", "enum": [ "Top", "Middle", "Bottom" ], "type": "string" }, "spineFoil": { "description": "The position of the foil on the spine. Leave null for no spine foil.", "enum": [ "Left", "Middle", "Right" ], "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.TitlePostRequest": { "description": "The details required to add a new title to your BookVAULT account.", "required": [ "title", "specifications" ], "type": "object", "properties": { "isbn": { "description": "The ISBN of the title in ISBN13 format. If omitted, a dummy ISBN will be generated for you.", "pattern": "Format: exactly 13 digits", "type": "string" }, "title": { "description": "The title of the product", "maxLength": 255, "minLength": 0, "type": "string" }, "promoCode": { "description": "An optional promo code to apply when adding the title", "type": "string" }, "specifications": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.TitleSpecifications", "description": "The specifications of the title" }, "bespokeOptions": { "description": "Optional bespoke options to add to the title.", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.TitleBespokeOption" } } } }, "BookVAULT.ApiUtilities.DTOs.Requests.BundlePostRequest": { "description": "The details required to create a new bundle on your BookVAULT account. A bundle groups existing\r\ntitles together as a single sellable item; its size, weight and pricing are derived from its\r\nmembers, so only the bundle name and the member titles need to be supplied.", "required": [ "title", "items" ], "type": "object", "properties": { "isbn": { "description": "The ISBN of the bundle in ISBN13 format (must start with 978 or 979). If omitted, a dummy\r\nISBN will be generated for you.", "pattern": "Format: exactly 13 digits, starting with 978 or 979", "type": "string" }, "title": { "description": "The name of the bundle", "maxLength": 255, "minLength": 0, "type": "string" }, "promoCode": { "description": "An optional promo code to apply when creating the bundle", "type": "string" }, "box": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.BundleBox", "description": "Optionally add a box or slipcase to the bundle. Omit to create the bundle without one.\r\nAll member titles must be the same size and binding for a box/slipcase to be produced." }, "items": { "description": "The existing titles that make up the bundle. At least one must be supplied.", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.BundleItem" } } } }, "BookVAULT.ApiUtilities.DTOs.Requests.BundleBox": { "description": "A box or slipcase to enclose a bundle. The box is sized automatically from the bundle's titles.", "required": [ "lamination" ], "type": "object", "properties": { "lamination": { "description": "The lamination of the box or slipcase. Only Matte or Gloss are supported.", "enum": [ "Gloss", "Matte" ], "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.BundleItem": { "description": "A single title within a bundle.", "required": [ "isbn" ], "type": "object", "properties": { "isbn": { "description": "The ISBN13 of an existing title on your account to include in the bundle", "pattern": "Format: exactly 13 digits", "type": "string" }, "quantity": { "format": "int32", "description": "The number of copies of this title to include in the bundle", "minimum": 1, "type": "integer" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.BundlePutRequest": { "description": "The details used to update an existing bundle. The bundle is identified by the ISBN in the route,\r\nso no ISBN is supplied here; the supplied name, member titles and box/slipcase replace those\r\ncurrently held against the bundle.", "required": [ "title", "items" ], "type": "object", "properties": { "title": { "description": "The name of the bundle", "maxLength": 255, "minLength": 0, "type": "string" }, "box": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.BundleBox", "description": "Optionally add a box or slipcase to the bundle. Omit to update the bundle without one; supplying\r\none replaces any existing box. All member titles must be the same size and binding for a\r\nbox/slipcase to be produced." }, "items": { "description": "The existing titles that make up the bundle. At least one must be supplied. The supplied set\r\nreplaces the bundle's current members.", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.BundleItem" } } } }, "BookVAULT.ApiUtilities.DTOs.Requests.TitleSpecRequest": { "description": "The specification of a title, used to calculate its derived values or to check which partners can\r\nprint it. Shared by the calculate and availability endpoints - it carries only the fields those\r\noperations need (no ISBN, title or promo code, which are only relevant when saving a title).", "required": [ "specifications" ], "type": "object", "properties": { "specifications": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.TitleSpecifications", "description": "The specifications of the title" }, "bespokeOptions": { "description": "Optional bespoke options applied to the title.", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Requests.TitleBespokeOption" } } } }, "BookVAULT.ApiUtilities.DTOs.Responses.TitlePayment": { "description": "The outcome of paying for a title. Payment is either taken immediately (from a saved card or\r\naccount credit) or, when it can't be, a checkout link is returned for the customer to pay manually.", "type": "object", "properties": { "status": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.ProductStatus", "description": "The status of the title after the payment attempt." }, "paymentRequired": { "description": "True if the customer must complete payment using the provided PaymentLink - i.e. payment could\r\nnot be taken automatically from a saved card or account credit. False if the title is now paid.", "type": "boolean" }, "paymentLink": { "description": "A checkout URL for the customer to complete payment, populated only when\r\nPaymentRequired is true. Empty when payment was taken automatically.", "type": "string" }, "messages": { "description": "Human-readable messages describing the payment outcome.", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Message" } } } }, "BookVAULT.ApiUtilities.DTOs.Responses.TitlePreview": { "description": "A time-limited link for previewing a title's proof.", "type": "object", "properties": { "url": { "description": "The preview URL. Open it to review the title's proof before approval.", "type": "string" }, "expiresAt": { "format": "date-time", "description": "The UTC date and time at which the preview link expires.", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.TitlesGetRequest": { "required": [ "titlesPerPage", "pageNumber" ], "type": "object", "properties": { "titlesPerPage": { "format": "int32", "description": "Number of titles to show per page", "maximum": 10, "minimum": 1, "type": "integer" }, "pageNumber": { "format": "int32", "description": "The page number to load", "minimum": 1, "type": "integer" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.TitlesResponse": { "type": "object", "properties": { "titles": { "description": "The list of titles returned", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Product" } }, "pagination": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.TitlesResponsePagination", "description": "Pagination options for loading any additional titles where available" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.TitlesResponsePagination": { "type": "object", "properties": { "currentPage": { "format": "int32", "description": "The current page number being viewed", "type": "integer" }, "titlesPerPage": { "format": "int32", "description": "The number of titles being shown per page", "type": "integer" }, "totalTitles": { "format": "int32", "description": "The total number of titles available", "type": "integer" }, "totalPages": { "format": "int32", "description": "The total number of pages available", "type": "integer" }, "hasNextPage": { "description": "True if there is a next page available", "type": "boolean" }, "hasPreviousPage": { "description": "True if there is a previous page available", "type": "boolean" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.TitlesPostRequest": { "required": [ "titlesPerPage", "pageNumber" ], "type": "object", "properties": { "titlesPerPage": { "format": "int32", "description": "Number of titles to show per page", "maximum": 10, "minimum": 1, "type": "integer" }, "pageNumber": { "format": "int32", "description": "The page number to load", "minimum": 1, "type": "integer" }, "createdAfter": { "format": "date-time", "description": "Show only titles created after this date", "type": "string" }, "createdBefore": { "format": "date-time", "description": "Show only titles created before this date", "type": "string" }, "isbnList": { "description": "Show only titles with the specified ISBNs", "type": "array", "items": { "type": "string" } }, "bindings": { "description": "Show only titles with the specified bindings", "type": "array", "items": { "enum": [ "PerfectBound", "CasePPC", "CaseCloth", "WireBound", "SaddleStitch", "SpiralBound", "None", "Bundle" ], "type": "string" } }, "statuses": { "description": "Show only titles with particular statuses", "type": "array", "items": { "enum": [ "Pending_Approval", "Active", "Suspended", "On_Proof", "Stock_Only", "Cancelled", "Awaiting_Payment", "Pending_Publication", "Customer_Approval", "Pending_Review", "Action_Required", "Blocked" ], "type": "string" } } } }, "BookVAULT.ApiUtilities.DTOs.Requests.BulkTitleUploadRequest": { "description": "A request to bulk import titles by uploading a completed bulk title import template.", "required": [ "template" ], "type": "object", "properties": { "template": { "description": "The completed bulk title import template (an .xlsx workbook) as a Base64-encoded string.", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.BulkTitleImport": { "description": "The state of a bulk title import. Returned when an import is queued and when its status is polled.\r\nTitles are created asynchronously by a background process, so a freshly queued import reports zero\r\nactioned titles and no payment link; both are populated as the import progresses and completes.", "type": "object", "properties": { "id": { "format": "int32", "description": "The identifier of the bulk import, used to poll its status.", "type": "integer" }, "titlesTotal": { "format": "int32", "description": "The total number of titles in the import.", "type": "integer" }, "titlesActioned": { "format": "int32", "description": "The number of titles processed so far.", "type": "integer" }, "complete": { "description": "Whether every title in the import has been processed.", "type": "boolean" }, "failed": { "description": "Whether the import failed.", "type": "boolean" }, "paymentLink": { "description": "Once the import is complete, a link to pay for the created titles where payment could not be\r\ntaken automatically. Empty while the import is still in progress or where no payment is required.", "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.WebhookGetRequest": { "required": [ "id" ], "type": "object", "properties": { "id": { "format": "int64", "description": "The ID of the webhook", "minimum": 1, "type": "integer" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.Webhook": { "type": "object", "properties": { "id": { "format": "int64", "description": "The ID of the webhook", "type": "integer" }, "dateCreated": { "format": "date-time", "description": "The date the webhook was created", "type": "string" }, "lastUpdated": { "format": "date-time", "description": "The date the webhook was last updated", "type": "string" }, "topic": { "description": "The topic associated with the webhook", "enum": [ "ORDER_CREATED", "ORDER_ACKNOWLEDGED", "ORDER_SENTTOPRINT", "ORDER_PRINTED", "ORDER_SHIPPED" ], "type": "string" }, "url": { "description": "The target URL endpoint to which the webhook event will be delivered", "type": "string" }, "status": { "description": "The status of the webhook", "enum": [ "Active", "Paused", "Suspended" ], "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.WebhookPutRequest": { "type": "object", "properties": { "url": { "description": "The new URL you wish for us to send the events to", "type": "string" }, "topic": { "description": "The new event you wish to subscribe to", "enum": [ "ORDER_CREATED", "ORDER_ACKNOWLEDGED", "ORDER_SENTTOPRINT", "ORDER_PRINTED", "ORDER_SHIPPED" ], "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.WebhookDeleteRequest": { "required": [ "id" ], "type": "object", "properties": { "id": { "format": "int64", "description": "The ID of the webhook", "minimum": 1, "type": "integer" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.WebhookDeleteResponse": { "type": "object", "properties": { "success": { "description": "Whether the deletion was successful or not", "type": "boolean" }, "errors": { "description": "Any error messages returned during the deletion, if applicable", "type": "array", "items": { "type": "string" } } } }, "BookVAULT.ApiUtilities.DTOs.Requests.WebhookPostRequest": { "required": [ "url", "topic" ], "type": "object", "properties": { "url": { "description": "The URL you wish for us to send the events to", "type": "string" }, "topic": { "description": "The event you wish to subscribe to", "enum": [ "ORDER_CREATED", "ORDER_ACKNOWLEDGED", "ORDER_SENTTOPRINT", "ORDER_PRINTED", "ORDER_SHIPPED" ], "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.WebhookStatusPatchRequest": { "required": [ "status" ], "type": "object", "properties": { "status": { "description": "The status you wish to update the webhook to", "enum": [ "Active", "Paused" ], "type": "string" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.WebhooksGetRequest": { "required": [ "webhooksPerPage", "pageNumber" ], "type": "object", "properties": { "webhooksPerPage": { "format": "int32", "description": "Number of webhooks to show per page", "maximum": 10, "minimum": 1, "type": "integer" }, "pageNumber": { "format": "int32", "description": "The page number to load", "minimum": 1, "type": "integer" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.WebhooksResponse": { "type": "object", "properties": { "webhooks": { "description": "The list of webhooks returned", "type": "array", "items": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.Webhook" } }, "pagination": { "$ref": "#/definitions/BookVAULT.ApiUtilities.DTOs.Responses.WebhooksResponsePagination", "description": "Pagination options for loading any additional webhooks where available" } } }, "BookVAULT.ApiUtilities.DTOs.Responses.WebhooksResponsePagination": { "type": "object", "properties": { "currentPage": { "format": "int32", "description": "The current page number being viewed", "type": "integer" }, "webhooksPerPage": { "format": "int32", "description": "The number of webhooks being shown per page", "type": "integer" }, "totalWebhooks": { "format": "int32", "description": "The total number of webhooks available", "type": "integer" }, "totalPages": { "format": "int32", "description": "The total number of pages available", "type": "integer" }, "hasNextPage": { "description": "True if there is a next page available", "type": "boolean" }, "hasPreviousPage": { "description": "True if there is a previous page available", "type": "boolean" } } }, "BookVAULT.ApiUtilities.DTOs.Requests.WebhooksPostRequest": { "required": [ "webhooksPerPage", "pageNumber" ], "type": "object", "properties": { "webhooksPerPage": { "format": "int32", "description": "Number of webhooks to show per page", "maximum": 10, "minimum": 1, "type": "integer" }, "pageNumber": { "format": "int32", "description": "The page number to load", "minimum": 1, "type": "integer" }, "createdAfter": { "format": "date-time", "description": "Show only webhooks placed after this date", "type": "string" }, "createdBefore": { "format": "date-time", "description": "Show only webhooks placed before this date", "type": "string" }, "ids": { "description": "Show only webhooks with the specified IDs", "type": "array", "items": { "format": "int32", "type": "integer" } }, "topics": { "description": "Show only webhooks for the given topics", "type": "array", "items": { "enum": [ "ORDER_CREATED", "ORDER_ACKNOWLEDGED", "ORDER_SENTTOPRINT", "ORDER_PRINTED", "ORDER_SHIPPED" ], "type": "string" } }, "urls": { "description": "Show only webhooks for the given URLs", "type": "array", "items": { "type": "string" } }, "statuses": { "description": "Show only webhooks with the specified statuses", "type": "array", "items": { "enum": [ "Active", "Paused", "Suspended" ], "type": "string" } } } } } }