API v2 migration guide

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`	—

Using the API

Developer guides

Accounts

Care plans

Catalog

Checkout links

Clients & patients

Clinics

External Rx

Insurance

Inbox

Invoices

Labs

Onboardings

Orders

Payments

PDFs

Prescriptions

Scheduler

Service pricing

Standard care

Subscriptions

File uploads

Inventory

Forms

Medical records

Orders endpoint

Field updates

Onboarding endpoint

Field updates

Catalog endpoint

Field updates

External prescription requests endpoint

Field updates

Accounts endpoint

Field updates

Client endpoint

Field updates

​Orders endpoint

​Field updates

​Onboarding endpoint

​Field updates

​Catalog endpoint

​Field updates

​External prescription requests endpoint

​Field updates

​Accounts endpoint

​Field updates

​Client endpoint

​Field updates

Orders endpoint

Field updates

Onboarding endpoint

Field updates

Catalog endpoint

Field updates

External prescription requests endpoint

Field updates

Accounts endpoint

Field updates

Client endpoint

Field updates