## v3 vs v4 API

The Wineshipping API is currently on **v3** (`/v3`), which is **generally available** for all production workloads. **v4** (`/v4`) is now available as a **public preview** — endpoints and behavior may change before general availability.

### Quick Comparison

| Feature | v3 | v4 |
|  --- | --- | --- |
| Base URL (Production) | `https://api.wineshipping.com/v3` | `https://api.wineshipping.com/v4` |
| Base URL (Test) | `https://api-test.wineshipping.com/v3` | `https://api-test.wineshipping.com/v4` |
| Authentication | `Authentication` object in request body | TBD |
| Fulfillment | ✅ Available | Planned |
| Inventory | ✅ Available | Planned |
| Tracking | ✅ Available | Planned |
| Commerce | ✅ Available | TBD |
| Product | ✅ Available | TBD |


## What is in v3

v3 is the current production API and is available at `https://api.wineshipping.com/v3`.

### Authentication

Every v3 request that requires authorization must include an `Authentication` object in the request body containing a `UserKey`, `Password`, and `CustomerNo`. See the [Authentication guide](/docs/authentication) for full details.

### Fulfillment

These endpoints manage the full lifecycle of customer sales orders.

| Operation | Description |
|  --- | --- |
| [CreateSalesOrder](/api/v3.1/openapi/fulfillment/createsalesorder) | Submit a new customer or DTC sales/fulfillment order. Supports standard shipping, carrier pick-up-at-location, and international orders. |
| [UpdateSalesOrder](/api/v3.1/openapi/fulfillment/updatesalesorder) | Modify an existing open sales order. |
| [CancelSalesOrder](/api/v3.1/openapi/fulfillment/cancelsalesorder) | Cancel an open sales order before it has been fulfilled. |
| [GetOrdersOnHold](/api/v3.1/openapi/fulfillment/getordersonhold) | Retrieve all orders currently on hold for a customer account. |
| [GetReturns](/api/v3.1/openapi/fulfillment/getreturns) | Retrieve a list of return sales orders received at a Wineshipping warehouse. |
| [GenerateJitLabel](/api/v3.1/openapi/fulfillment/generatejitlabel) | Generate a Just-In-Time (JIT) shipping label or packing slip in PDF or PNG format. |
| [BatchSalesOrder](/api/v3.1/openapi/fulfillment/batchsalesorder) | *(Deprecated)* Create multiple orders in a single request. Use individual `CreateSalesOrder` calls instead. |


### Inventory

These endpoints manage inbound inventory (purchase orders), inventory transfers, and real-time inventory data.

| Operation | Description |
|  --- | --- |
| [CreatePurchaseOrder](/api/v3.1/openapi/inventory/createpurchaseorder) | Create an inbound inventory receipt request (drop-off at warehouse or customer pickup). |
| [UpdatePurchaseOrder](/api/v3.1/openapi/inventory/updatepurchaseorder) | Update an existing open purchase order. |
| [CancelPurchaseOrder](/api/v3.1/openapi/inventory/cancelpurchaseorder) | Cancel an open purchase order. Only allowed before warehouse work has started. |
| [CreateTransferOrder](/api/v3.1/openapi/inventory/createtransferorder) | Request an inventory transfer between two Wineshipping-managed warehouse locations. |
| [UpdateTransferOrder](/api/v3.1/openapi/inventory/updatetransferorder) | Update an open transfer order. |
| [CancelTransferOrder](/api/v3.1/openapi/inventory/canceltransferorder) | Cancel an open transfer order. Only allowed before warehouse work has started. |
| [GetInventoryTransactions](/api/v3.1/openapi/inventory/getinventorytransactions) | Retrieve inventory transaction history (sales orders, purchase orders, transfers, adjustments, and more). |
| [GetInventoryStatus](/api/v3.1/openapi/inventory/getinventorystatus) | Retrieve real-time physical inventory details by item, warehouse, and unit of measure. |
| [GetSellable](/api/v3.1/openapi/inventory/getsellable) | Retrieve real-time sellable inventory quantities for use in e-commerce, POS, or wine club platforms. |


### Tracking

These endpoints provide shipment and package tracking information.

For reliability and scalability, prefer [event-driven tracking via webhooks](/docs/eventdriventracking) over polling `GetDetails`.

| Operation | Description |
|  --- | --- |
| [GetDetails](/api/v3.1/openapi/tracking/getdetails) | Retrieve order tracking status, carrier tracking number, and shipment details for a single order. |
| [GetPackages](/api/v3.1/openapi/tracking/getpackages) | Retrieve package-level shipping details including tracking numbers and carrier status. |


### Commerce

These endpoints support pre-order address and carrier services.

| Operation | Description |
|  --- | --- |
| [AddressValidation](/api/v3.1/openapi/commerce/addressvalidation) | Validate and correct a U.S. delivery address and classify it as residential or commercial. |
| [GetCarrierLocations](/api/v3.1/openapi/commerce/getcarrierlocations) | Retrieve available carrier hold/pickup locations near a given address. |
| [GetDeliveryEstimates](/api/v3.1/openapi/commerce/getdeliveryestimates) | Get estimated delivery dates for FedEx and UPS services to a given U.S. address. |


### Product

These endpoints manage SKU definitions and item metadata.

| Operation | Description |
|  --- | --- |
| [CreateSKU](/api/v3.1/openapi/product/createsku) | Define a new SKU for wine, merchandise, or marketing materials. Supports detailed wine classification and metadata. |
| [UpdateSKU](/api/v3.1/openapi/product/updatesku) | Update the metadata for an existing SKU. |
| [RetireSKU](/api/v3.1/openapi/product/retiresku) | Mark a SKU as retired to prevent future orders from being placed against it. |


## What is in v4 (Coming Soon)

## What is in v4 (Preview)

v4 is now available as a public preview at `https://api.wineshipping.com/v4`. The server base URL changes from `/v3` to `/v4`.

v4 is a **preview** and not yet generally available. Endpoints and response shapes may change without notice before GA. Continue using v3 for all production workloads until v4 reaches general availability.

The initial v4 scope targets the three most critical integration areas:

- **Fulfillment** — Sales order creation, management, and fulfillment operations.
- **Inventory** — Inventory management, purchase orders, and transfer orders.
- **Tracking** — Shipment and package tracking.


Details on Commerce and Product endpoints for v4 are to be determined. Continue using v3 for those capabilities until v4 reaches general availability.

Contact [api@wineshipping.com](mailto:api@wineshipping.com) for updates on the v4 release timeline.