Back to All
added

API v3 Release Notes

2 months ago by Ron

In the last few months we’ve been working on a brand new version of fabric’s API known as V3. The main driver behind this new version is to bring better consistency across fabric’s products and follow common API design patterns.

Since V3 is a major version including numerous breaking changes, it’s challenging to provide a one-to-one changelog between V2 to V3. While the functionality is intended to provide full parity, the mapping is not always direct.

We will try to cover the high-level changes here but encourage you to read the updated documentation for further details. If you have any additional questions, please use our community forums.

High-Level Changes

The information below describes changes as they were done across the fabric products, regardless of the product in question. As the changes are cross-functional, the new API version will feel more familiar when you work with one product or the other.

Path changes

  • Paths previously could contain both nouns and verbs. Paths now contain only nouns with the exception of custom actions (see below).

  • Plural vs singular noun usage - Paths now reference plural nouns when addressing a collection. An individual instance that’s referenced as a path parameter will be singular. For example:

​ /v3/carts/{cartId} - carts being the collection of carts and {cartId} being the individual cart identifier.

  • Standardize the function of HTTP methods:
    • GET /v3/carts will retrieve the collection of carts.
    • GET /v3/carts/{cartId} will retrieve a single cart with the provided id.
    • POST /v3/carts will create a new cart under the carts collection.
    • PUT/PATCH /v3/carts/{cartId} will update a specific cart in the carts collection (please check the documentation to see which method is supported).
    • DELETE /v3/carts/{cartId} will delete a specific cart.
  • As mentioned before, custom actions are an exception to the rule when using verbs. They allow the user to run special actions that are available on a given entity. For example, POST /carts/{id}/actions/apply-coupon allows you to apply a coupon to a specific cart.

Headers

  • All custom fabric headers now start with the prefix of x-fabric-. A few examples are x-fabric-channel-id, x-fabric-request-id.
  • Some headers were removed and converted to query parameters.

Response Codes

  • Response codes now follow their HTTP definitions. A few examples:
    • 201 for a newly created resource.
    • 204 for a successful operation that has no content.
    • 400 for a bad request from the client.
    • 401 for unauthorized access.

Product-Specific Changes

The information below gives you the highlights about changes as they were implemented in the different products fabric offers.

Cart & Checkout

Cart-level - Cart Endpoints

  • Cart V3 introduces /carts endpoints which allow merchants to create and manage carts in a RESTful manner.
  • Cart V3 introduces a new merge cart functionality which allows merchants to merge carts in many different configurations. This new merge endpoint is the default merge cart endpoint.
  • V3 leverages standard REST verbs like PATCH and DELETE vs custom actions like removePromo in V2.

Line Item - Line item endpoints

  • Cart V3 introduces dedicated endpoints for line item management under /line-items. V2 managed items under cart.
  • New endpoints use standard verbs like POST, PUT, PATCH vs custom actions like addItem in V2.
  • We have introduced a fulfillment entity within which we can set custom fulfillment options for each line item. This allows for split fulfillment in Cart.

Shipping Details - Shipping Details endpoints

  • ShipMethod information has been moved to the root level of ShippingDetails. Previously details such as cost, discount and other details were part of ShipMethod. This was confusing for developers: we were not actually persisting the shipMethod at source or updating it. These fields are actually just references and are now at the root level of ShippingDetails.

Actions

  • Cart V3 implements coupon apply and remove as standard POST actions using paths like /actions/apply-coupon. V2 used custom endpoints like /promos/{promoCode} that overloaded GET and POST.
  • We also expose /v3/carts/actions/merge as a new endpoint to merge two carts.

Checkout APIs - Checkout endpoints

  • Checkout V3 terminology has changed: you now create a checkout session
  • V3 uses an enum for checkout session status compared to a boolean flag in V2.
  • V3 has structured error types like PAYMENT_FAILURE vs generic errors in V2 for better handling.

Products

Attributes - Attributes Endpoint

  • V2 uses one bulk endpoint for attributes whereas V3 follows REST standards and has separate operations for CRUD.
  • V2 follows similar structure of attributes (i.e. one bulk endpoint) for attribute-grouping and mapping as well. V3 follows the REST standards for attribute-grouping and mapping. V3 supports all the attributes supported by V2 with only on caveat, V3 doesn’t trigger a job automatically when an attribute is updated.
    • For example if a formula value has been updated, then there wont be a background job created to update the existing data. There is a user action needed to trigger the job. While the job is in progress, no other updates can be triggered. User will be provided an option to cancel the job if he/she wishes to update the formula. This was introduced to avoid the load on the system incase of an unintentional update.
  • In V3, all the APIs expect the Ids of the attributes instead of names of the attributes. This will avoid the attribute name collision across locales.

Categories & Collection - Category & Collections Endpoint

  • All the actions supported in V2 are supported in V3 as well but the API structure has changed.
  • V2 has common APIs for both categories and collections (alternate categories). In V3, a new set of APIs were created for collections (alternate categories) to separate them out from the categories.
  • In V2 every change is eventually consistent where as in V3 all changes are strongly consistent except for collections/{id}/products which alone is eventually consistent.
  • V3 provides a /jobs API to provide visibility on the background jobs to show their progress.

Products - Products Endpoint

  • V2 has all the actions combined under one API. V3 has a separate set of APIs to handle actions such as attaching/detaching variants & bundles, publishing/unpublishing of products, change of categories, etc.
  • V2 has the entire drafts and product response in one go which changes the response model based on the object if it has a draft or not. V3 has a consistent response even when the product has a draft. At any given point in V3, you would get either a draft version of the product or the live version of the product with indication whether the product has the live version if the response is draft and vice-versa.
  • V2 and V3 both support bulk creations/updates but the data is immediately available for the storefront or merchant use-cases in V3 unlike V2 which would be eventually available for consumption.
  • V2 has multiple APIs for search scenario which has been all combined to one in API in V3 /products/search.
  • V2 provides the full denormalized data when searched for a product where as V3 provides only the required data as the full denormalized data is covered as part of published-products.

Published Product - Published Products Endpoint

All shopper facing endpoints are covered in this section. In V2, there was no distinction between shopper facing and merchant facing endpoints but in V3 the endpoints are separated out.

  • In V2 we have the /products endpoint which returns both live and draft products. In V3 we have /published-products endpoints which return live products alone that can then be consumed by the storefront users.
  • V3 also supports accessing of the products via:
    • /published-products/{id}
    • /published-products/{sku} - sku (stock keeping unit)
    • /published-products/{itemid} - itemId ( to be deprecated - fabric internal identifier -numeric)
  • V3 get product response would be detailed enough to generate the Product Detail Page (PDP) page. It provides the following details which are provided in V2 as well:
    • Product attributes.
    • Hierarchy of categories along with its attributes at each level.
    • Hierarchy of each collection it belongs to, along with their attribute details.
    • Variants, if any, along with its full attribute details.
    • Bundle product details, if the id passed is a bundle, i.e. the products that are part of the bundle.
  • With the above detailed response, in V2, we have an issue with reaching the response size limit of 10MB. V3 allows the exclusion of part of the response via query parameters to reduce the size.
  • In V3, separate endpoints are provided to facilitate fetching of subsections of responses such as:
    • /published-products/{id}/variants
    • /published-products/{id}/bundle-products
    • /published-products/{id}/collections
  • V3 also supports fetching of multiple products at once by the listing endpoint /published-products/ids.
  • V3 supports localised data and expects the locale to be passed along each of the apis. If the product is not active in the requested locale, InActiveProduct error is thrown.

Files & Jobs - Files and Jobs Endpoints

  • V2 supports product upload via providing the template to fill the products and triggers a job which would provide the progress of the file. V3 operates in a similar fashion but operates at a much faster rate (about 3x) than v2. V3 provides some extra functionality such as showing the background jobs as well.
Files API
  • In V2, the files API supports upsert which inherently supported creation/updation of products, variants , bundles and making them live. However, V2 does not support deletion functionality. V3 supports all the operations that the APIs support i.e. create, update, delete on products, variants and bundles.
  • Apart from the above, V3 also supports a separate column called Action & Variant which provides additional functionality such as UPSERT, PUBLISH, UNPUBLISH_KEEP_DRAFT, UNPUBLISH_KEEP_LIVE , ATTACH_VARIANT, DETACH_VARIANT , ATTACH_BUNDLE_PRODUCTS, DETACH_BUNDLE_PRODUCTS , CHANGE_CATEGORY and DELETE. This accurately captures the user's intention, thus providing an improved experience.
  • V3 provides API to provide the uploaded file just like V2, but gives you visibility into the import process using the /jobs endpoint.
  • V3 provides 2 files in case of an error while uploading the file just like V2 . One file comprises of combination of all errors for the given product and its sku while the other has the original records limited to failed SKUs so that the user can update the file and re-upload only the errored ones.
Jobs API:

  • V3 provides the functionality to view the jobs that are triggered in background as well.

  • V3 provides new capabilities to export data based on the filter criteria.

Offers

Promotions API

  • For the create promotion endpoint, V3 uses consistent nested JSON structure with proper naming for attributes.

  • V2 uses the base URL of /promo for promotion operations. v3 uses /promotions instead and follows the HTTP standards mentioned above for update and delete operations.

Read Promotion

  • For reading all promotions V2 uses the URL like POST /api-offers/promo/list. List API on V3 is as follows GET /promotions?size=10&sort={{couponSortVal}}
  • V2 uses limit and skip in the query parameters for pagination and return a query object with total count, limit and skip values. V3 uses startCursor and size parameters for pagination, and returns a query object with next cursor and size values. The next cursor acts as a placeholder for next request which can use this value in start cursor field.
  • V2 uses sortBy and sortOrder fields for sorting for example {"sortBy": "updatedAt", "sortOrder": "asc" } is passed in the body. V3 uses sort in params for example ?sort=+updatedAt. +,- denote ascending and descending order.

Pricing

  • In V2, the base URL is /price. In V3, the base URL is /prices.
  • For the create price endpoint, V3 uses consistent nested JSON structure with proper naming for attributes.

Get Prices

  • For reading all prices V2 uses the URL like POST /price. List api on v3 is as follows /prices.
  • v2 uses limit and skip in the query parameters for pagination and return a query object with total count, limit and skip values. v3 uses startCursor and size parameters for pagination and returns a query object with next cursor and size values. The next cursor acts as a placeholder for next request which can use this value in start cursor field.

Delete Price

  • V2 uses DELETE for deleting a price and the URL is structured as /price/{priceId}/priceList/{priceListId}.
  • V2 accepts a type query param to decide whether to delete by itemId,itemSku or _id.
  • V3 uses DELETE for deleting the price but the delete action is split into two sub APIs:
    • /prices/{itemId}?priceListId={priceListId}
    • /prices/sku/{sku}?priceListId={priceListId}

OMS

Inventory

  • Following the new standard for URLs, in V2 the endpoints are /inventory, /inventory/network, /inventory/counters, etc, whereas in V3 the endpoints are /inventories, /inventory-counters, /inventory-networks, etc.

Locations

  • Similarly, in V2 the endpoints are /location & /location/attributes, wheras in V3 the endpoints are /locations and /locations-attributes.

Orders

  • V3 introduces several new order retrieval options. V2 only has GET /order to retrieve an order by ID or number. However, V3 adds:
  • GET /orders/{orderId} to get order by ID.
  • GET /orders/order-number/{orderNumber} to get order by number.
  • POST /orders/search to search for orders based on complex criteria.

Allocation

  • V3 adds a more robust search with filtering and pagination via /allocations/search. V2 only has /allocation/query.
  • V3 allows updating allocations via PUT /allocations/allocation-request-id/{allocationRequestId} with full allocation document. V2 has multiple APIs to perform an update to allocation PUT /allocation/{allocationId} updates reallocation via PUT /allocation/reallocate.

Appeasement

  • V3 introduces order and item level appeasements via /orders/{orderId}/actions/create-appeasement and /orders/order-number/{orderNumber}/actions/create-appeasement.V2 had only order appesements by orderId.

Backorder/Preorder

  • In V2 the base path for BackOrder/PreOrder is /backpre-order, whereas in v3 it is /backorders-preorders.
  • V3 adds a more robust search with filtering and pagination via /backorders-preorders/search. V2 only supports fetching of documents by reservation Ids.

Shipment

  • V3 adds a more robust search with filtering and pagination via /shipment/search. V2 only has /shipment/query.

Shipping Lists

  • In V3, a new endpoint is introduced to fetch a list along with items for a single user /users/{userId}/actions/get-list-details-with-items.
  • In V3, the new endpoint to add-or-update, /{listId}/actions/add-or-update-list-items, automatically checks if the item is not there then it adds or else if the item is there then it replaces their quantity. If incrementQuantity is enabled then it only increases the quantity.
  • In V3, the delete list endpoint is converted from DELETE to POST /{listId}/actions/delete-list-items.
  • V3 introduces attributes and created/updated at for ListItems.

Order Cancellation

  • V2 has GET /order/cancel and POST /order/cancel to check eligibility and cancel orders. However, in v3 the endpoints are changed to actions POST /order/{orderId}/actions/cancel & POST /order/{orderId}/actions/check-cancel-eligibility. The same actions can be invoked by orderNumber as well.

Order Returns & Exchange

  • V2 has /order/return & /order/exchange for eligibility and return/exchange of the ordered items. V3 introduces changes to actions POST /order/{orderId}/actions/returns, POST /order/{orderId}/actions/exchange and /order/{orderId}/actions/check-return-eligibility. V3 supports invoking these actions both orderId & orderNumber.