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

# API Changelog

> Release notes and version-by-version changes to the Zinc API v2.

A version-by-version record of endpoints, fields, and schemas added or changed in the Zinc API.

For product updates, new features, and general improvements, see the [product changelog](/docs/changelog).

***

## 2026-10-09

<Info>This is the current API version.</Info>

**Changes**

* `OrderItemStatus` enum — Added `available_for_pickup`
* `ReturnRequestResponse` — Added `credited_amount`
* `ReturnRequestSummary` — Added `credited_amount`

***

## 2026-09-30

**New schemas**

* `LineRejection`
* `SearchRetailer` enum — `amazon`, `bestbuy`, `bhphotovideo`, `chewy`, `costco`, `homedepot`, `kohls`, `lowes`, `macys`, `newegg`, `staples`, `target`, `walmart`, `wayfair`
* `SearchSort` enum — `relevance`, `price_asc`, `price_desc`, `rating`

**Changes**

* `ErrorDetails` — Added `line_rejections`
* `FulfillmentPreferences` — Added `excluded_merchants`
* `OrderFulfillment` — Added `excluded_merchants`
* `OrderMilestone` — Added `available_for_pickup` to `type`
* `Sku` — Added `free_shipping`
* `TrackingNumberResponse` — Added `delivery_proof_url`
* `TrackingStatus` enum — Added `available_for_pickup`
* `GET /search` — Added query parameter `limit`, `retailer`, `sort`
* `POST /agent/search` — Added query parameter `limit`, `retailer`, `sort`
* `GET /orders` — Added query parameter `shipping_name`
* `GET /orders/export` — Added query parameter `shipping_name`
* `OrderCreate` — `max_price` now has a minimum of `0`; negative values are rejected
* `OrderPriceComponents` — Clarified `converted_payment_total`: on a non-USD order billed in USD, it's the USD amount charged, including the FX markup

***

## 2026-09-18

**New endpoints**

* `GET /retailers/check` — Check Retailer

**New schemas**

* `CoverageInfo`
* `CoveragePlatform`
* `RetailerCheckCheckout`
* `RetailerCheckEvidence`
* `RetailerCheckResponse`
* `RetailerCheckRetailer`

**Changes**

* `PublicRetailer` — Added `support`
* `PublicRetailerListResponse` — Added `coverage`
* `RetailerCredentialsResponse` — Added `retailer_id`
* `GET /retailers` — Added query parameter `include`

***

## 2026-09-11

**New schemas**

* `FulfillmentConcession`
* `FulfillmentMode` enum — `best_effort`
* `FulfillmentPreferences`
* `OrderFulfillment`
* `OrderPaymentInfo`

**Changes**

* `OrderCreate` — Added `fulfillment`
* `OrderItemResponse` — Added `error_type`
* `OrderResponse` — Added `fulfillment`, `payment`
* `GET /orders` — Added query parameter `user_email`
* `GET /orders/export` — Added query parameter `user_email`
* `GET /products/search` — Added response code `402`
* `GET /products/{product_id}` — Added response code `402`
* `GET /products/{product_id}/offers` — Added response code `402`
* `GET /search` — Added response code `402`

***

## 2026-08-21

No API changes in this version.

***

## 2026-08-11

**Changes**

* `OrderCreate` — Added `gift_message` (max 240 characters; requires `is_gift`)
* `OrderResponse` — Added `gift_message`, `merchant_order_ids`
* `GET /orders` — Added query parameter `merchant_order_id`, an exact-match filter on the retailer's own order number

**Behavior changes**

* `OrderCreate.is_gift` — An order requesting `is_gift` now **fails** with the
  `gift_option_unavailable` error type when the retailer's checkout offers no free
  gift option, rather than being placed as a normal order. If gifting is optional
  in your flow, catch this error type and retry without `is_gift`. See
  [Gift orders](/docs/v2/api-reference/orders/create-order#gift-orders).

**New retailers**

* Added `zazzle` to the supported retailer catalog. See [`GET /retailers`](/docs/v2/api-reference/retailers/list-retailers) for the full list.

***

## 2026-08-10

No API changes in this version.

***

## 2026-07-29

**Removed endpoints**

* `GET /agent/products/details` — Agent Product Details
* `GET /agent/products/offers` — Agent Product Offers
* `GET /agent/products/search` — Agent Product Search
* `GET /agent/search` — Agent Search

**New schemas**

* `CustomerNotificationStatus`
* `CustomerNotifications`

**Changes**

* `OrderCreate` — Added `customer_notifications`
* `OrderResponse` — Added `customer_notifications`
* `ProductSearchResult` — Added `url`, `variant_id`
* `GET /orders` — Added query parameter `metadata_key`, `metadata_value`

***

## 2026-07-17

**New endpoints**

* `GET /track/{order_id}` — Get Public Tracking
* `POST /agent/products/details` — Agent Product Details
* `POST /agent/products/offers` — Agent Product Offers
* `POST /agent/products/search` — Agent Product Search
* `POST /agent/search` — Agent Search

**New schemas**

* `ErrorCode` enum — `unauthorized`, `forbidden`, `invalid_token`, `token_expired`, `not_found`, `already_exists`, `validation_error`, `insufficient_funds`, `payment_failed`, `payment_method_required`, `invalid_payment_method`, `invalid_shipping_address`, `url_unreachable`, `non_us_retailer`, `unsupported_retailer`, `unsupported_country`, `retailer_country_not_supported`, `guest_checkout_not_supported`, `invalid_variant`, `out_of_stock`, `shipping_unavailable`, `order_not_cancellable`, `return_not_allowed`, `external_service_error`, `stripe_error`, `stytch_error`, `internal_error`, `bad_request`, `rate_limit_exceeded`, `service_unavailable`
* `ErrorDetail`
* `ErrorResponse`
* `PublicTrackingDestination`
* `PublicTrackingItem`
* `PublicTrackingResponse`
* `PublicTrackingShipment`

**Changes**

* `OrderPriceComponents` — Added `discount`, `fees`
* `ReturnRequestListResponse` — Added `total`
* `GET /managed-accounts` — Added query parameter `limit`, `offset`, `search`
* `GET /orders` — Added query parameter `created_after`, `created_before`, `has_tracking`, `search`, `tracking_status`
* `GET /returns` — Added query parameter `limit`, `offset`, `search`, `status`
* `POST /returns` — Added response code `409`

***

## 2026-07-10

**Changes**

* `TrackingNumberResponse` — Added `estimated_delivery_date` (carrier-reported delivery estimate as a destination-local calendar date; `null` until the carrier reports one)
* `POST /agent/orders` — Added query parameter `method` (restrict the `402` response to a single payment method, e.g. `stripe`, `tempo`, or `x402`, instead of advertising every configured method)
* `POST /agent/orders` — A present-but-invalid body (including malformed or non-object JSON) is now rejected with `422` before any payment challenge is issued or honored; only a bodyless discovery probe receives the lenient `402`
* `GET /products/search` — `free_shipping` no longer filters Amazon results (upstream search data under-reports Prime, so filtering would drop valid items); the filter now applies to Walmart only, and defaults to `false` for all accounts (previously `true` for BizAPI-enrolled accounts)
* `GET /agent/products/search` — `free_shipping` no longer filters Amazon results; Walmart only

***

## 2026-07-06

**New endpoints**

* `GET /orders/{order_id}/timeline` — Get Order Timeline
* `GET /usage` — Get My Usage

**New schemas**

* `OrderMilestone`
* `OrderTimelineResponse`
* `RecentCall`
* `UsageMetric`
* `UserUsageResponse`

**Removed endpoints**

* `GET /orders/{order_id}/events` — Get Order Events (now admin-only; use [Get Order Timeline](/docs/v2/api-reference/orders/get-order-timeline) for order status)

**Removed schemas**

* `OrderEventsResponse`, `ProgressEventResponse`

**Changes**

* `ProductSearchResponse` — Added `next_page`
* `PublicRetailer` — Added `no_account_needed`, `use_your_account`
* `PublicRetailer` — Removed `supported`
* `TrackingNumberResponse` — Added `zinc_tracking_number`, `zinc_tracking_url`
* `GET /agent/products/search` — Added query parameter `free_shipping`
* `GET /products/search` — Added query parameter `free_shipping`

***

## 2026-06-26

**New endpoints**

* `GET /agent/products/details` — Agent Product Details
* `GET /agent/products/offers` — Agent Product Offers
* `GET /agent/products/search` — Agent Product Search
* `GET /agent/search` — Agent Search
* `GET /retailers` — List Retailers

**New schemas**

* `ErrorDetails`
* `FieldError`
* `PublicRetailer`
* `PublicRetailerListResponse`
* `TrackingCheckpointResponse`
* `TrackingStatus` enum — `pending`, `in_transit`, `delivered`

**Changes**

* `OrderJobResult` — Added `error_details`
* `TrackingNumberResponse` — Added `checkpoints`, `status`
* `GET /orders` — Added query parameter `include`

***

## 2026-06-19

**New schemas**

* `MarginSpec`
* `OrderConnectInfo`
* `OrderJobResult`
* `OrderPayment`
* `OrderPriceComponents`
* `ProductCondition` enum — `New`, `Refurbished`, `UsedLikeNew`, `UsedVeryGood`, `UsedGood`, `UsedAcceptable`

**Removed schemas**

* `JobResultPayload`
* `LineItem`
* `MerchantOrderId`
* `PriceComponents`

**Changes**

* `OrderCreate` — Added `handling_days_max`, `is_gift`, `payment`
* `OrderItemResponse` — Added `condition_in`, `condition_not_in`
* `OrderProduct` — Added `condition_in`, `condition_not_in`
* `OrderResponse` — Added `connect`, `handling_days_max`, `is_gift`, `job_result`

***

## 2026-06-11

**New endpoints**

* `GET /orders/bulk` — List Bulk Uploads
* `GET /orders/bulk/{batch_id}` — Get Bulk Upload
* `GET /orders/bulk/{batch_id}/results.csv` — Download Bulk Results
* `POST /orders/bulk` — Create Bulk Upload
* `POST /orders/bulk/validate` — Validate Bulk Upload

**New schemas**

* `BulkBatchListResponse`
* `BulkBatchResponse`
* `BulkBatchStatus` enum — `pending`, `processing`, `completed`, `failed`
* `BulkRowResult`
* `BulkRowValidation`
* `BulkUploadRequest`
* `BulkValidateResponse`

**Changes**

* `OrderResponse` — Added `retailer_credentials_uuid`
* `ReturnRequestStatus` enum — Added `credited` (return resolved by crediting the customer's wallet)

***

## 2026-03-30

**New endpoints**

* `POST /returns` — Create Return Request
* `GET /returns` — List Return Requests
* `GET /returns/{return_request_id}` — Get Return Request

**New schemas**

* `ReturnRequestCreate`, `ReturnRequestResponse`, `ReturnRequestListResponse`
* `ReturnRequestReason` enum — `return.request_label`, `nondelivery.not_delivered`, `nondelivery.damaged`, `nondelivery.empty_box`, `tracking.request_update`, `cancel.forced_cancellation`, `other`
* `ReturnRequestStatus` enum — `open`, `in_progress`, `approved`, `denied`, `completed`

***

## 2026-03-25

**New endpoints**

* `GET /products/search` — Search Products
* `GET /products/{product_id}` — Get Product
* `GET /products/{product_id}/offers` — Get Product Offers

**New schemas**

* `ProductSearchResponse`, `ProductSearchResult`

**Changes**

* `POST /agent/orders` — Added `402` response code for MPP payment challenges

***

## 2026-03-23

**New endpoints**

* `POST /agent/orders` — Create MPP Order

**New schemas**

* `LineItem`

**Changes**

* `PriceComponents` — Added `line_items` field (array of `LineItem`)
* `JobResultPayload` — Added `estimated_delivery` field

***

## 2026-02-19

**Changes**

* `RetailerCredentialsCreate` — Added `retailer_config` field
* `RetailerCredentialsUpdate` — Added `retailer_config` field
* `RetailerCredentialsResponse` — Added `retailer_config` and `forwarding_email` fields

***

## 2026-02-12

**New endpoints**

* `GET /managed-accounts` — List Managed Accounts
* `POST /managed-accounts` — Create Managed Account
* `PUT /managed-accounts/{short_id}` — Update Managed Account
* `DELETE /managed-accounts/{short_id}` — Delete Managed Account
* `GET /orders/{order_id}/events` — Get Order Events

**New schemas**

* `OrderEventsResponse`, `ProgressEventResponse`
* `RetailerCredentialsCreate`, `RetailerCredentialsListResponse`, `RetailerCredentialsResponse`, `RetailerCredentialsUpdate`

***

## 2026-02-05

**Changes**

* `Address` — `state` field made optional and nullable to support international addresses

***

## 2026-01-28

**Changes**

* `OrderCreate` — Added `po_number` field for purchase order tracking
* `OrderResponse` — Added `po_number` field

***

## 2026-01-21

**Changes**

* `OrderCreate` — Added `metadata` field for custom key-value data
* `OrderResponse` — Added `metadata` field

***

## 2026-01-19

**New endpoints**

* `GET /orders/test-products` — List Test Products

**New schemas**

* `TrackingNumberResponse`

**Changes**

* `OrderResponse` — Added `attempts` (integer) and `tracking_numbers` (array) fields

***

## 2026-01-09

**Changes**

* `GET /orders` — Added `order_id` query parameter for filtering
* `OrderCreate` — Added `retailer_credentials_id` field
* `OrderResponse` — Added `retailer_credentials_id` field

***

## 2025-12-19

**New endpoints**

* `POST /orders/{order_id}/cancel` — Cancel Order

**New schemas**

* `ProductVariant`

**Changes**

* `OrderItemResponse` — Added `variant` field
* `OrderProduct` — Added `variant` field
* `OrderStatus` enum — Added `cancelled` value
* `JobResultPayload` — Several fields made optional/nullable

***

## 2025-11-24

Initial API version.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.