--- updatedAt: 2026-05-26T22:53:01.000Z agentTools: projectIndex: https://developer.vinoshipper.com/llms.txt --- # Estimate Taxes Estimate taxes on the value of products and shipping prior to creating an order. The Vinoshipper [Create an Order](https://developer.vinoshipper.com/reference/createorder) API will automatically calculate the appropriate taxes and state fees, but if you want to display an estimate of tax and shipping costs to your customer prior to submitting the order, you can use the [Estimate Taxes](https://developer.vinoshipper.com/reference/estimatetaxes) and [Estimate Shipping](https://developer.vinoshipper.com/reference/estimateshipping) APIs. The Estimate Shipping API will return a list of available shipping rates, and the Estimate Taxes API will accept an optional shipping rate as in some cases shipping is taxable. Only the postal code is required to return an estimate, but rates will be more accurate with a fully complete address. # OpenAPI definition ```json { "openapi": "3.0.1", "info": { "title": "Vinoshipper API Docs", "version": "3.0", "x-logo": { "url": "/static/img/brand/vinoshipper-logo.svg" } }, "servers": [ { "url": "https://vinoshipper.com" } ], "tags": [ { "name": "Order", "description": "Post-purchase order operations" }, { "name": "Order", "description": "Pre-purchase order operations" } ], "paths": { "/api/v3/p/orders/estimate-taxes": { "post": { "tags": [ "Order" ], "summary": "Estimate Taxes", "description": "Estimate taxes on the value of products and shipping prior to creating an order.", "operationId": "estimateTaxes", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateTaxesRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxEstimate" } } } }, "400": { "description": "Request has failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed", "content": {} }, "403": { "description": "Insufficient permission", "content": {} }, "404": { "description": "Not Found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BasicAuth": [] } ] } } }, "components": { "schemas": { "Error": { "required": [ "code", "description" ], "type": "object", "properties": { "description": { "type": "string" }, "code": { "type": "string" }, "field": { "type": "string" }, "shortDescription": { "type": "string" } } }, "ErrorDetails": { "required": [ "status", "type" ], "type": "object", "properties": { "status": { "type": "integer", "format": "int32" }, "type": { "type": "string", "enum": [ "VALIDATION", "COMPLIANCE", "PAYMENT_FAILURE", "SERVER_ERROR", "ACCESS_DENIED", "CONFLICT" ] }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/Error" } } } }, "ErrorResponse": { "required": [ "error" ], "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorDetails" } } }, "BoxDimensions": { "required": [ "depthInches", "heightInches", "widthInches" ], "type": "object", "properties": { "widthInches": { "type": "number", "description": "The box width in inches" }, "heightInches": { "type": "number", "description": "The box height in inches" }, "depthInches": { "type": "number", "description": "The box depth in inches" } } }, "BoxWeight": { "required": [ "lbs" ], "type": "object", "properties": { "lbs": { "type": "number", "description": "The box weight in pounds" } } }, "ExtraFeeDetail": { "required": [ "amount", "label" ], "type": "object", "properties": { "label": { "type": "string" }, "amount": { "type": "number" }, "description": { "type": "string" } }, "description": "Extra fee details that add up to the extra fee total. " }, "OrderLine": { "required": [ "alcoholPercentage", "category", "discount", "price", "productId", "quantity", "sku", "taxes", "upc" ], "type": "object", "properties": { "productId": { "type": "integer", "format": "int32" }, "productName": { "type": "string" }, "productVintage": { "type": "string" }, "sku": { "type": "string" }, "upc": { "type": "string" }, "category": { "type": "string" }, "productTaxonomy": { "$ref": "#/components/schemas/ProductTaxonomyView" }, "quantity": { "type": "integer", "format": "int32" }, "price": { "type": "number" }, "discount": { "type": "number" }, "alcoholPercentage": { "type": "number" }, "packProductId": { "type": "integer", "format": "int32" }, "taxes": { "$ref": "#/components/schemas/Taxes" }, "cogs": { "type": "number", "description": "Cost of goods sold per unit, snapshotted at order time with fallback to historical average", "nullable": true }, "grossCogs": { "type": "number", "description": "Gross COGS (cogs × quantity)", "nullable": true } } }, "Package": { "required": [ "box" ], "type": "object", "properties": { "carrier": { "type": "string", "description": "The carrier that was actually used to ship the package or null if unknown", "enum": [ "UPS", "FEDEX", "GLS", "SELF" ] }, "trackingNumber": { "type": "string" }, "box": { "$ref": "#/components/schemas/ShipmentBox" } } }, "ProductTaxonomyView": { "required": [ "displayName", "externalId", "id", "sortOrder" ], "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "externalId": { "type": "string" }, "displayName": { "type": "string" }, "sortOrder": { "type": "integer", "format": "int32" } } }, "ShipmentBox": { "required": [ "containsAlcohol", "weight" ], "type": "object", "properties": { "weight": { "$ref": "#/components/schemas/BoxWeight" }, "dimensions": { "$ref": "#/components/schemas/BoxDimensions" }, "containsAlcohol": { "type": "boolean" } } }, "Shipper": { "required": [ "id", "isFulfillmentCenter", "name" ], "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "isFulfillmentCenter": { "type": "boolean", "description": "If true, the shipper is a fulfillment center and you cannot use the schedule shipment api to create shipping labels." } } }, "ShippingDetail": { "required": [ "carrier", "price", "rateCode", "shipper" ], "type": "object", "properties": { "carrier": { "type": "string", "enum": [ "UPS", "FEDEX", "GLS", "SELF" ] }, "rateCode": { "type": "string" }, "price": { "type": "number" }, "shipper": { "$ref": "#/components/schemas/Shipper" }, "rateDescription": { "type": "string" }, "packages": { "type": "array", "items": { "$ref": "#/components/schemas/Package" } }, "taxes": { "$ref": "#/components/schemas/Taxes" } } }, "TaxDetails": { "required": [ "cityTaxRate", "cityTaxes", "countyTaxRate", "countyTaxes", "customStateTaxes", "otherTaxRate", "otherTaxes", "stateTaxRate", "stateTaxes" ], "type": "object", "properties": { "county": { "type": "string" }, "countyTaxRate": { "type": "number" }, "countyReportingCode": { "type": "string" }, "countyTaxes": { "type": "number" }, "city": { "type": "string" }, "cityTaxRate": { "type": "number" }, "cityReportingCode": { "type": "string" }, "cityTaxes": { "type": "number" }, "state": { "type": "string" }, "stateTaxRate": { "type": "number" }, "stateTaxes": { "type": "number" }, "otherTaxRate": { "type": "number" }, "otherTaxes": { "type": "number" }, "customStateTaxes": { "type": "number" } }, "description": "The summary of taxes charged" }, "Taxes": { "required": [ "taxRate", "taxableValue", "taxes" ], "type": "object", "properties": { "taxRate": { "type": "number" }, "taxableValue": { "type": "number" }, "taxes": { "type": "number" } } }, "ProductQty": { "title": "Specifies a product that is added to an order", "required": [ "productId", "quantity" ], "type": "object", "properties": { "productId": { "type": "string", "description": "The product identifier" }, "quantity": { "minimum": 0, "type": "integer", "description": "How many of this product to add", "format": "int32" }, "price": { "minimum": 0, "exclusiveMinimum": false, "type": "number", "description": "\n An optional price override that will be used instead of the product's actual price.\n Note: You cannot override the price of a multi-pack product. Trying to do so will return an error.\n " } }, "description": "A list of products that will go on the order" }, "SelectedShippingRate": { "required": [ "rateCode" ], "type": "object", "properties": { "carrier": { "type": "string", "nullable": true, "enum": [ "UPS", "FEDEX", "GLS", "SELF" ] }, "rateCode": { "maxLength": 24, "minLength": 1, "type": "string" }, "price": { "type": "number", "nullable": true }, "rateDescription": { "maxLength": 50, "type": "string", "nullable": true } }, "description": "The shipping rate that will be used to ship the order. You can call the Estimate Shipping API to get a list of shipping rates for a specific address. You can also call the Get Shipping Rate Codes API to get a list of all possible rate codes for the producer." }, "StreetAddress": { "required": [ "city", "country", "postalCode", "stateCode", "street1" ], "type": "object", "properties": { "street1": { "type": "string" }, "street2": { "type": "string", "nullable": true }, "city": { "type": "string" }, "stateCode": { "type": "string" }, "postalCode": { "type": "string", "description": "ZIP Code" }, "country": { "type": "string", "description": "Two letter country code", "default": "US" } }, "description": "The address the sale is being delivered to or picked up from." }, "EstimateTaxesRequest": { "required": [ "productIdType", "shipToAddress" ], "type": "object", "properties": { "shipToAddress": { "$ref": "#/components/schemas/StreetAddress" }, "productIdType": { "type": "string", "description": "The type of `productId` used in the request to identify orders in our system. (SKU or VS_ID)", "enum": [ "SKU", "VS_ID" ] }, "products": { "type": "array", "description": "A list of products that will go on the order", "items": { "$ref": "#/components/schemas/ProductQty" } }, "shippingRate": { "$ref": "#/components/schemas/SelectedShippingRate" } } }, "TaxEstimate": { "required": [ "extraFeesTotal", "taxes", "taxesTotal", "taxesTotalWithoutFees" ], "type": "object", "properties": { "products": { "type": "array", "description": "A list of product line items with prices and taxes.", "items": { "$ref": "#/components/schemas/OrderLine" } }, "shipping": { "$ref": "#/components/schemas/ShippingDetail" }, "extraFees": { "type": "array", "description": "Extra fee details that add up to the extra fee total. ", "items": { "$ref": "#/components/schemas/ExtraFeeDetail" } }, "extraFeesTotal": { "type": "number", "description": "Extra fees total" }, "taxesTotal": { "type": "number", "description": "Total of taxes on value of products and shipping" }, "taxesTotalWithoutFees": { "type": "number" }, "taxes": { "$ref": "#/components/schemas/TaxDetails" } } } }, "securitySchemes": { "BasicAuth": { "type": "http", "scheme": "basic" } } } } ```