Migrating from Wholesale v1 to v2

The Wholesale API v2 is more powerful and consistent than its v1 predecessor, but also includes changes that may require updating your integration. In some cases, that we tried to restrict to minor use cases, these changes are backward incompatible. This article will guide you through these changes and new features. 

For additional details on endpoints, responses and payloads, please refer to the Wholesale API v2 docs and Wholesale API v1 (legacy) docs.

• Main differences
• Backward compatible and incompatible changes
• New features

Main differences

• In "single" endpoints, numeric ids (eg. Le New Black internal identifier) been replaced with code or reference (eg. brand's own identifier)

• Distinct methods for creating (POST) and updating (PATCH) are now handled by the unique POST method, which uses a create-or-update strategy based on the identifier included in the payload

• New "multi/..." endpoints lets you create or update bulk data (ex: multi/retailers/)

• New "files/..." endpoints lets you manage images and files (ex: files/products/)

Backward compatible and incompatible changes

Backward compatible changes

These are the main changes requiring an update of your integration. While responses and payloads schemas are mostly identical in v1 and v2 APIs, there may be minor differences that are not documented here. 

• GET collections, products, products+variants, retailers, sizings -> replace {id} with {code} or {reference}

• POST inventory (by eans or skus) -> replace with POST request to /multi/inventory/ean or POST /multi/inventory/sku

• PATCH any endpoint -> replace with POST request, the identifier (eg. product.model, retailer.reference...) provided in the payload will be used to decide whether to create or update)

Backward incompatible changes

• /appointments -> removed (all methods: GET), may be managed in back-office

• /categories -> removed (all methods: GET, POST, PATCH), may be managed in v2 /products endpoint

• /collections/{id}/categories -> removed (all methods: GET, POST, PATCH), may be managed in v2 /products endpoint

• /fabrics -> removed (all methods: GET, POST, PATCH), may be managed in v2 /products endpoint

• /lines -> removed (all methods: GET, POST, PATCH), may be managed in back-office

• /materials -> removed (all methods: GET, POST, PATCH), may be managed in back-office

• /price_catalogs -> removed (all methods: GET), may be managed in back-office

• /selections -> removed (all methods: GET), may be managed in back-office

Special case: changes in endpoint GET /orders/{id}

Endpoint

• Replace {id} with PO-{id} in URL

Response

id (int) -> replaced with reference (string)
order_time -> removed
price_catalog_id (int) -> replaced with price_list_code (string)
price_catalog -> removed
sales_catalog -> removed
line_id -> removed
season_id -> removed
notify_message -> removed
order_name -> removed
invoicing_address -> removed

New features

New endpoints

• POST/DELETE /files  -> file management for products, fabrics and sales documents

• POST /multi -> bulk management for most data types

• GET/POST /prices 

• GET/POST /sales_catalogs 

• GET/POST /sales_documents 

• POST /inventory -> create inventory (v1  only allowed updating)

• POST /products  -> create products (v1  only allowed updating)

• POST /products/{model}/{fabric_code}  -> create variants (v1  only allowed updating)

• POST /products-variants  -> create variants (alternate payload schema)

• POST /retailers -> create or update retailers, including buyers and delivery addresses

• POST /sizings -> create or update sizings

New responses

• GET /products -> product variants now include their array of skus