> ## Documentation Index
> Fetch the complete documentation index at: https://developer.vetcove.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API v2 migration guide

> This guide is designed to help users currently using the **Home Delivery** API v1 transition smoothly to v2. Below, we’ve mapped out all v1 endpoints and their associated fields, showing where they can be found in v2 and highlighting any changes that were made. These mappings provide a quick reference to understand how existing v1 functionality translates into v2, making migration more straightforward and reliable.

This guide was last updated on September 29, 2025. Our v2 External API is still evolving, and this migration guide may become outdated. We are regularly making improvements, and fields may be added, changed, or removed. Please refer to the API endpoint document for the most accurate information.

## Orders endpoint

In **v1**, the Orders API combined both **Order Analytics** and **nested Order Items** in a single response. This meant that each order included its own embedded list of items.

In **v2**, we've separated these into two endpoints:

* **Order Analytics endpoint**: returns high-level order information
* **Order Items endpoint**: returns individual order item-level information

This change was introduced to improve performance and ensure the data model scales more effectively.

### Field updates

| v1 Orders | v2 Order Analytics | v2 Order Items | Notes |
| - | - | - | - |
| `id` | ✅ `id` | — | Order ID |
| `order_placed_datetime` | ✅ `order_placed_datetime` | — | — |
| `modified` | ❌ | — | ⚠️ Removed to avoid redundancy. Use `last_modified` if needed. |
| `last_modified` | ✅ `last_modified` | — | — |
| `subtotal` | ✅ `subtotal` | — | — |
| `total` | ✅ `total` | — | — |
| `tax` | ✅ `tax` | — | — |
| `shipping` | ✅ `shipping` | — | — |
| `handling_fee` | ✅ `handling_fee` | ✅ `handling_fee` | — |
| `discount` | ✅ `discount` | — | — |
| `client_note` | ✅ `client_note` | — | — |
| `clinic_note` | ✅ `clinic_note` | — | — |
| `status` | ✅ `status` | ✅ `status` | Order and item-level statuses |
| `status_display` | ✅ `status_display` | — | — |
| `display_number` | ✅ `display_number` | — | — |
| `is_urgent` | ✅ `is_urgent` | — | — |
| `urgency_fee` | ✅ `urgency_fee` | ✅ `urgency_fee` | — |
| `charge_capture_date` | ✅ `charge_capture_date` | — | — |
| `cart_id` | ✅ `cart_id` | — | — |
| `creator_type` | ✅ `creator_type` | — | — |
| `client_type` | ✅ `client_type` | — | — |
| `clinic` (object) | ⚠️ **replaced** → `clinic_id` | — | Object no longer embedded, use Clinics endpoint by id |
| `client` (object) | ⚠️ **replaced** → `clinic_client_id` | — | Object no longer embedded, use Clients endpoint by id |
| `payment_method` (object) | ⚠️ **replaced** → `payment_method_id` | — | Object no longer embedded, use Payment Methods endpoint by id |
| `shipping_address` (object) | ✅ `shipping_address` (object) | — | Still embedded on orders |
| `shipping_address.id` | ✅ | — | — |
| `shipping_address.name` | ✅ | — | — |
| `shipping_address.address_one` | ✅ | — | — |
| `shipping_address.address_two` | ✅ | — | — |
| `shipping_address.city` | ✅ | — | — |
| `shipping_address.state` | ✅ | — | — |
| `shipping_address.zipcode` | ✅ | — | — |
| `shipping_address.phone_number` | ✅ | — | — |
| `transfers` (array of objects) | ⚠️ **replaced** → `transfer_ids` | — | Object no longer embedded, use Transfers endpoint by id |
| `refunds` (array of objects) | ⚠️ **replaced** → `refund_ids` | — | Object no longer embedded, use Refunds endpoint by id |
| `order_items` (array of objects) | ⚠️ **replaced** → `order_item_ids[]` | — | Object no longer embedded, moved to Order Items endpoint |
| `order_items[].id` | — | ✅ `id` | — |
| `order_items[].quantity` | — | ✅ `quantity` | — |
| `order_items[].price` (string) | — | ⚠️ `unit_price` (number) | Renamed + type change |
| `order_items[].handling_fee` | — | ✅ `handling_fee` | — |
| `order_items[].status` | — | ✅ `status` | — |
| `order_items[].is_subscription` | — | ✅ `is_subscription` | — |
| `order_items[].is_pickup` | — | ✅ `is_pickup` | — |
| `order_items[].vendor_subtotal` | — | ✅ `vendor_subtotal` | — |
| `order_items[].vendor_fees` | — | ✅ `vendor_fees` | — |
| `order_items[].vendor_shipping` | — | ✅ `vendor_shipping` | — |
| `order_items[].client_price` | — | ✅ `client_price` | — |
| `order_items[].current_chewy_price` | — | ✅ `current_chewy_price` | — |
| `order_items[].revenue` | — | ✅ `revenue` | — |
| `order_items[].profit` | — | ✅ `profit` | — |
| `order_items[].margin` | — | ✅ `margin` | — |
| `order_items[].ship_date` | — | ✅ `ship_date` | — |
| `order_items[].vc_marketplace_facilitator_tax` | — | ✅ `vc_marketplace_facilitator_tax` | — |
| `order_items[].clinic_discounts` | — | ✅ `clinic_discounts` | — |
| `order_items[].rebate_discounts` | — | ✅ `rebate_discounts` | — |
| `order_items[].diet_fulfillment_fee` | — | ✅ `diet_fulfillment_fee` | — |
| `order_items[].processing_fee` | — | ⚠️ `credit_card_processing_fee` ⚠️ `order_processing_fee` | Replaced with two new fields that provide more transparency. Their sum equals the former processing fee. |
| `order_items[].refunded_amount` | — | ✅ `refunded_amount` | — |
| `order_items[].net_payout` | — | ✅ `net_payout` | — |
| `order_items[].authorizing_vet` | — | ✅ `authorizing_vet` | — |
| `order_items[].delivered_date` | — | ✅ `delivered_date` | — |
| `order_items[].dvm_authorization_date` | — | ✅ `dvm_authorization_date` | — |
| `order_items[].gl_codes[]` | — | ✅ `gl_codes[]` | — |
| `order_items[].stripe_payouts[].id` | — | ⚠️ `stripe_payouts[].stripe_id` | Renamed |
| `order_items[].stripe_payouts[].date` | — | ⚠️ `stripe_payouts[].created` | Renamed |
| `order_items[].Item` (object) | — | ⚠️ **replaced** → `item_id` | Object no longer embedded, use Catalog Items endpoint |
| `order_items[].Patient` (object) | — | ⚠️ **replaced** → `patient_id` | Object no longer embedded, use Patients endpoint |

***

## Onboarding endpoint

In **v1**, the Onboarding endpoint returned a single combined object that included **nested client, clinic, and patient objects** inside each onboarding record. Subscriptions also contained a full embedded `patient` object.

In **v2**, the Onboarding endpoint remains a **single endpoint**, but the structure has been flattened:

* `client` → replaced by `client_id`
* `clinic` → replaced by `clinic_id`
* `subscriptions.patient` → replaced by `patient_id`

Additional new fields were added, but all nested objects were removed in favor of **IDs that link to other endpoints** (Clients, Patients, Clinics).

This shift makes the data model **simpler and more consistent** across endpoints, while still allowing users to retrieve full related records from their dedicated endpoints when needed.

### Field updates

| v1 Onboarding | v2 Client Onboarding | Notes |
| - | - | - |
| `created` | ✅ `created` | — |
| `id` | ✅ `id` | — |
| `clinic` (object) | ⚠️ **replaced** → `clinic_id` | Object no longer embedded, use Clinics endpoint by id |
| `client` (object) | ⚠️ **replaced** → `client_id` | Object no longer embedded, use Clients endpoint by id |
| `subscription_message_sent_at` | ✅ `subscription_message_sent_at` | — |
| `onboarding_events[].created` | ✅ `created` | — |
| `onboarding_events[].kind` | ✅ `kind` | — |
| `onboarding_events[].note` | ✅ `note` | — |
| `onboarding_events[].acting_user` | ❌ | ⚠️ Removed |
| `subscriptions[].item` | ✅ `item` | — |
| `subscriptions[].Patient` (object) | ⚠️ **replaced** → `patient_id` | Object no longer embedded, use Patients endpoint by id |
| `subscriptions[].frequency` (number) | ✅ `frequency` (string) | ⚠️ Type change |
| `subscriptions[].next_order_date` | ✅ `next_order_date` | — |
| `subscriptions[].estimated_autoship_value` | ⚠️ `estimated_value_annual` | ⚠️ Renamed |

***

## Catalog endpoint

In **v1**, the Catalog endpoint was a **single combined endpoint** that returned item data together with nested product and product line details.

In **v2**, the catalog has been **split into three distinct endpoints**:

* **List All Items** → lightweight listing of catalog items
* **Fetch Item** → fetches full details for a specific item
* **Fetch Product** → fetches product-level details, linked via `product_id`

This separation makes the API **faster, more modular, and easier to navigate**: users can fetch only what they need (items, products, or both), rather than downloading large nested structures for every catalog request.

### Field updates

| v1 Catalog | v2 Catalog Items | Notes |
| - | - | - |
| `id` | ✅ `id` | — |
| `sku` | ✅ `sku` | — |
| `full_name` | ✅ `full_name` | — |
| `is_active` | ✅ `is_active` | — |
| `manufacturer_no` | ✅ `manufacturer_no` | — |
| `shopping_path` | ✅ `shopping_path` | — |
| `vendor_stock_availability` | ✅ `vendor_stock_availability` | — |
| `etailer_price` | ✅ `etailer_price` | — |
| `image_url` | ✅ `image_url` | — |
| `alt_image_url` | ❌ | Removed in v2 |
| `Product` (object) | ⚠️ **replaced** → `product_id` | Object no longer embedded, fetch Product by id |

***

## External prescription requests endpoint

The structure of this endpoint remains largely the same, with only minor adjustments from **v1** to **v2**.

### Field updates

| v1 External Rx Requests | v2 External Rx Requests | Notes |
| - | - | - |
| `id` | ✅ `id` | — |
| `clinic_id` | ❌ | ️️️️️️Not returned in v2 |
| `clinic_name` | ❌ | ️️️️️️Not returned in v2 |
| `corporate_location_id` | ❌ | ️️️️️️Not returned in v2 |
| `requested_on` | ⚠️ **replaced** → `received_datetime` | Renamed + full timestamp |
| `client_id` | ❌ | ️️️Not returned in v2, update in progress |
| `client_pims_id` | ❌ | ️️️Not returned in v2 |
| `client_name` | ❌ | ️️️Not returned in v2, update in progress |
| `patient_id` | ✅ `patient_id` | — |
| `patient_pims_id` | ❌ | ️️️Not returned in v2 |
| `patient_name` | ❌ | ️️️Not returned in v2, update in progress |
| `item_id` | ✅ `item_id` | — |
| `item_name` | ✅ `item_name` | Returned if item is successfully mapped |
| `parsed_item_name` | ✅ `item_name` | Returned if item is not successfully mapped |
| `status` | ⚠️ `request_status` | ⚠️ Renamed |
| `status_modified_date` | ⚠️ `status_modified_datetime` | ⚠️ Renamed + timestamp |
| `last_note` | ✅ `last_note` | — |
| `last_note_date` | ⚠️ `last_note_datetime` | ⚠️ Renamed + timestamp |

***

## Accounts endpoint

The structure of this endpoint remains the same from **v1** to **v2**.

### Field updates

| v1 Accounts | v2 Accounts | Notes |
| - | - | - |
| `auto_auth_token` | ✅ `auto_auth_token` | — |
| `base_url` | ✅ `base_url` | — |
| `embed_url` | ✅ `embed_url` | — |
| `expiry` | ✅ `expiry` | — |
| `fullscreen_url` | ✅ `fullscreen_url` | — |

***

## Client endpoint

In **v1**, the Clients endpoint returned both **client records** and an embedded list of their **patients** within the same response.

In **v2**, this structure has been **split into two separate endpoints** for clarity and scalability:

* **Clients endpoint** → client-level information only
* **Patients endpoint** → patient-level information, linked back to clients

This separation makes the data model **cleaner, more modular, and easier to scale**, while also providing access to a richer patient schema through its own dedicated endpoint.

### Field updates

| v1 Clients | v2 Clients | v2 Patients | Notes |
| - | - | - | - |
| `id` | ✅ `id` | — | — |
| `clinic_id` | ✅ `clinic_id` | — | — |
| `first_name` | ✅ `first_name` | — | — |
| `last_name` | ✅ `last_name` | — | — |
| `email` | ✅ `email` | — | — |
| `phone_number` | ✅ `phone_number` | — | — |
| `pim_id` | ✅ `pim_id` | — | — |
| `primary_address.address_one` | ✅ `address_one` | — | — |
| `primary_address.address_two` | ✅ `address_two` | — | — |
| `primary_address.city` | ✅ `city` | — | — |
| `primary_address.state` | ✅ `state` | — | — |
| `primary_address.zipcode` | ✅ `zipcode` | — | — |
| Patient Object | ❌ | — | Object no longer embedded, use Patients endpoint by id |
| `patients[].name` | — | ✅ `name` | — |
| `patients[].species` | — | ✅ `species` | — |
| `patients[].pim_id` | — | ✅ `pim_id` | — |
| `patients[].weight` | — | ✅ `weight` | — |
| `patients[].birth_month` | — | ✅ `birth_month` | — |
| `patients[].birth_day` | — | ✅ `birth_day` | — |
| `patients[].birth_year` | — | ✅ `birth_year` | — |

***