## v3 vs v4 API

The Wineshipping API is currently on **v3** (`/v3`). **v4** (`/v4`) is the next major version, currently in development.

### 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)

v4 is the next major version of the Wineshipping REST API and is currently in development. The server base URL changes from `/v3` to `/v4`.

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.