Migrating from API v2

Why migrate?

  1. Because API v3 is just better! :)
  2. Support for API v2 will be terminated soon, probably by the summer of 2021.
  3. All new features will be added only to API v3.
  4. API v3 provides uniquer features such as removing products and moving them between stores.
  5. API v3 provides more convenient methods to manipulate products and other entities.
  6. API v3 accepts and returns JSON.

Main differences between API v3 and API v2.

Camel-case vs. snake-case

API v3 uses camel-case names, like mainImage. API v2 uses snake-case name, like main_image.

application/json vs. application/x-www-form-urlencoded

Most POST endpoints in API v3 accept request bodies in application/json format, like

{
	"name": "My Product Name",
	"brand": "My Brand"
}

Most POST endpoints in API v2 accept request bodies in application/x-www-form-urlencoded format, like

name=My%20Product%20Name&brand=My%20Brand

JSON format is more clear and easy to read, fields are typed, complex objects and arrays are supported. In JSON it is easy to write things like

{
	"name": "My Product Name",
	"variants": [
		{
			"sku": "Variant1",
			"shippingWeight": 0.3
		},
		{
			"sku": "Variant2",
			"shippingWeight": 0.35
		}
	]
}

It would be hard to represent such data in application/x-www-form-urlencoded format in a comprehensible way.

Working with products and variants

Endpoints in API v3 dealing with products work with the whole product with all its variants. E.g., you can update a product and all its variants in a single API call. There are no separate endpoints for variants.

How to migrate

Entity models (Products and Orders) are mainly the same in both APIs. So, you won’t have to significantly change your logic.

  1. Using the documentations for API v2 and API v3, check all endpoints for Products and Orders that you use in API v2. There is a corresponding endpoint in API v3 for each API v2 endpoint. You should use it instead.
  2. Check the field names correspondences. Names with multiple words changed from snake-case to camel-case.
  3. Check the new fields that appeared in API v3. You might want to use them.
  4. Change your format for POST endpoints to JSON.
  5. Please, pay special attention to the changes in product creation and update. Whenever you want to change several variants of a single product, please do it in a single call in API v3. That will save your time and request rate limit.
  6. If you check the result of your POST call in API v2 by making a GET call on the modified entity, you can spare the second call, because most API v3 POST endpoints return the modified entity.

What stays in API v2

API v3 is a work in progress. You can use some endpoint from API v2 and some endpoints from API v3 at the same. API v3 endpoints accept access tokens from API v2.

Authorization endpoints have not been introduced to API v3 yet. Continue to use API v2 to get your access tokens.

If you haven’t been using some parts of API v2, integrate via API v3.