Version 5.0 release information

🎉 ShopifySharp v5.0 has been released and published on nuget! You can install it with the dotnet CLI like this:

dotnet add package ShopifySharp --version 5.0.3

I’ve written a guide here for migrating from v4 to v5. It doesn’t cover every little change, but it does cover the big ones that are most likely to cause you issues when upgrading. If you think something is missing from this guide, let me know down below.

ShopifySharp version 5 migration guide.

You can use this thread to ask about changes, report bugs, and let me know if a class or property you were previously using is missing.

Paginated listing

The big change in this version is the new paginated listing operations that Shopify is now requiring. You can no longer request page 1, page 2, page 3, etc. of orders/customers/whatevers. You must use a special parameter they return during list operations to get the next page or the previous page. If you do not use that parameter, you will only ever get the first page of results.

Since listing all customers/orders is a common question I get, here’s how you do that going forward in ShopifySharp v5.0:

var allOrders = new List<Order>();
var service = new OrderService(domain, accessToken);
var list = await service.ListAsync(new OrderListFilter 
{ 
    Limit = 250 
});

while (true)
{
    allOrders.AddRange(list.Items);

    if (!list.HasNextPage)
    {
        break;
    }

    list = await service.ListAsync(list.GetNextPageFilter());
}

A couple important things to note about the above example:

• You must use the list result’s LinkHeader to get a filter that will let you request the next page or the previous page.
• The link header may be null, so you must check it before using it. This can happen e.g. if you’re on page one and there’s only one page total.
• The next page link and previous page link headers may specifically be null, even if the link header itself is not. This can happen e.g. when you’re at the end of the list, there will be no next page link, but there will be a previous page link, and vice versa.
• Once you’ve listed the first page, you cannot change any filter properties except for Limit and Fields. Beyond the first page, Shopify will “remember” the filter properties you used previously and continue to apply them to all subsequent pages. If you want to make a change to one of those properties, you need to create a new filter and start over with the first page.

~TODO~ Implemented

(This section was tracking changes that needed to be made before the v5.0 release. They are now obsolete as v5.0 has been published.)

Things to consider/implement before the full release is published:

• What if we want to save the PageInfo parameter and then use it later, outside of the LinkHeader class? Since ListFilter has an internal constructor, there’s no way to reconstruct this class at a later point. We’d have to use the dedicated filter classes, but those contain properties that are not relevant to getting next/previous pages.
  • Do we add a ListFilter<T>.FromPageInfo(string pageInfo)?
  • Use case: I want to show my users a list of their orders with a next/previous page link. I take the PageInfo value and store it in that link, then when they click it I use it to get either the next page or the previous page.
• Rename PreviousLink.GetFollowingPageFilter()? The name might be confusing when you’re getting the previous page, not the following page.
• We need to manually set the filter.Limit each time we get the next/previous page filter from LinkHeader. Can we parse that out and set it automatically? Does Limit and Fields appear in the Link header returned by Shopify?
• Better error parsing. ShopifySharp fails to parse error messages in may cases, instead returning a nearly useless Response did not indicate success. 400 Bad Request message instead.
  • Example: creating a fulfillment without a LocationId value will return a message that looks like {"error": "Fulfillment must set LocationId"}. But ShopifySharp does not parse that and just returns the 400 Bad Request message instead.
• Add filter class for FulfillmentServiceService.ListAsync()
• Add filter class for TransactionService.GetAsync()?
• Add tests for the Parameterizable class to ensure it serializes things like IEnumerable<long> properly.
• Update obsolete messages in ShopifySharp v4.x to note that ShopifySharp v5 is available.

There are a few other breaking changes, but the paginated list change is the major one. I’ll update this post later on as I document the other changes.

[nozzlegear]

Quick update for everyone, it looks like Shopify has delayed the mandatory API migration due to COVID-19. You now have until July 1st to update, delayed from April 1st. Here’s the email I got:

Hello there,

With the evolving concerns around COVID-19’s impact on communities around the world, we know that partners and merchants are making adjustments to continue running their businesses smoothly. That’s why we’ve decided to postpone the April 1 version removal to July 1, 2020.

What does this change mean? This means that you have additional time until July 1 to update your apps to account for changes in both 2019-07 and 2019-10 API versions. Specifically, the move from page to cursor based pagination will come into effect for all endpoints on July 1, which should simplify the migration process for your apps.

To see which deprecated API calls your apps are making, check out the API Health report on the Partner Dashboard.

For those of you who’ve put in the time and energy to update already, we want to say thank you for your diligence and understanding in the extension—your efforts haven’t gone to waste.

If you have any questions, chat with us in the API forums or the Support section of the Partner Dashboard.

Thank you, Shopify Apps Team

[nozzlegear]

@nozzlegear , will you create a new branch for 2020-01?

@clement911 done! 2020-01 branch has been created.