Migrate from deprecated Shopify Fulfillment API endpoints

Quick references:

• Migrate to fulfillment orders
• Create a new Fulfillment

Shopify removed support for fulfillment resources to fulfill orders from the 2022-07 version; the last version of the API that supported a few fulfillment endpoints was 2022-04. Shopify recently announced the retirement date for fulfillment and order API resources and will deprecate API version 2022-04 on June 30th, 2023. If you have any existing integrations with Shopify, it’s important to review your existing flows to ensure they do not call the endpoints scheduled for retirement.

To accommodate this change, we are removing the API version 2022-04 from the Shopify connector that has the following six endpoints with the 2023.3.1 release (March 2023): 

• Create a new Fulfillment(Deprecated) 
• Modify an existing Fulfillment (Deprecated)
• Create or Update (Deprecated) 
• Cancel a Fulfillment (Deprecated)
• Transition a fulfillment from pending to open (Deprecated) 
• Complete a Fulfillment (Deprecated)

The endpoints Transition a fulfillment from pending to open (Deprecated) and Complete a Fulfillment (Deprecated) do not have any replacement endpoints.

This article explains how to find deprecated endpoints, and replace them with new endpoints,  for both Shopify connectors and templates.

Contents

• Endpoint replacement list
• A. Update your Shopify connection
• B. Find deprecated endpoints in existing flows
• C. Update flows to use replacement endpoints
  • Create a new Fulfillment(Deprecated) to Creates a fulfillment for one or many fulfillment orders
  • Modify an existing Fulfillment(Deprecated) to Updates the tracking information for a fulfillment
  • Create or Update(Deprecated) to Create or Update a Fulfillment
  • Cancel a Fulfillment(Deprecated) to Cancel a Fulfillment
• D. Fulfillment flow changes in Shopify Templates 

Endpoint replacement list

The following table lists the endpoints scheduled for retirement on April 1st, 2023, and their replacements:

A. Find your connection and configure scopes

The following scopes are required to access Fulfillment Order API. Update your Shopify connections by adding these scopes.

To update your Shopify connection:

1. From the Resources menu, navigate to Connections.
2. Search for Shopify.
3. Select the matching Shopify connection(s). In the Version dropdown, check if the version is 2022-04, if yes, click the Version dropdown and choose 2022-07 or the higher API version.
4. In the Configure scopes section, click Configure scopes. The Scopes editor page is displayed.
5. Select the list of scopes mentioned below and use the > button to add them to your configured scopes.
   
   • • read_merchant_managed_fulfillment_orders
     • write_merchant_managed_fulfillment_orders
     • read_third_party_fulfillment_orders
     • write_third_party_fulfillment_orders
     • read_assigned_fulfillment_orders
     • Write_assigned_fulfillment_orders

   Important: If you are using the OAuth 2.0 authentication type, make sure to include these scopes and click Save & authorize. If you are using Basic or Token-based authentication, make sure to include these scopes in the custom app that you have created, and update it.

6. Click Save when you’re ready to leave the editor and finish setting up your connection.
   
   

B. Find deprecated endpoints in existing flows

1. From the Resources menu, navigate to Connections.
2. Search for Shopify.
3. In your first matching Shopify connection, select Used by from the Actions overflow (...) menu. A list of all items that use this connection appears.
4. Right-click the first flow step in the list and select your browser’s option to open it in a new tab.
5. Review the configuration for any of the deprecated endpoints listed in the table below:

C. Update flows to use replacement endpoints

Create a new Fulfillment(Deprecated) to Creates a fulfillment for one or many fulfillment orders

Important: The flow configuration changes depending on whether the flow does complete fulfillment or partial fulfillment.

• Complete fulfillment: If the previous fulfillment flow uses only the location ID for the fulfillment mappings, then it does a complete fulfillment since it's not using any specific line item IDs and their quantity.
• Partial fulfillment: If the previous fulfillment flow uses line IDs and quantity fields, the flow supports partial fulfillment.

1. From the list of all items that appeared in Step 3 of section B. Find deprecated endpoints in existing flows, and look for the fulfillment flow. 
2. Open the fulfillment import mappings and take a copy of the existing mappings as the new changes would remove the old mappings. You can capture screenshots of the existing mappings or clone the flow so that the mappings and other components will be stored for future reference. For more information, see Clone integrations and flows.
3. Click X at the right corner of the import to delete the existing fulfillment import step.
4. Click + to add a lookup bubble Get a list of fulfillment orders for a specific order to fetch the fulfillment orders by order ID using Retrieve a list of all fulfillment orders for an order endpoint.
   
   
5. Within the lookup, select Shipping and fulfillment : Fulfillment Order for the Resource setting, and Retrieve a list of all fulfillment orders for an order for the API endpoint. 
6. In the Order ID field, using handlebars, assign the value as shown in the screenshot.
   
   
7. Click the Output filter option and add an output filter that allows only the fulfillment order that doesn’t have the status of closed or canceled.
   
   
8. Click the Mappings icon and add the results mapping to capture the array of fulfillment orders for that order.
   
   
9. If the previous fulfillment flow supports the partial fulfillment, add a PostResponseMap hook for the above lookup.
10. Create a script under Resources > Scripts.
    

    Note: Make sure you have checked Developer mode in your profile settings.

    
11. In the Name field, provide a name to the script.
12. In the Edit content, write a script that does the following:
    1. For each source line item iterate over fulfillmentOrders[*].line_items, and allow only the fulfillmentOrders[*].line_items where its line_item_id matches with the source etail line item id.
    2. If source quantity is <= Shopify quantity
       • Add a new field to the fulfillmentOrders[*].line_items that holds the quantity value of source quantity  
    3. If source quantity is > Shopify quantity
       • Add a new field to the fulfillmentOrders[*].line_items that holds the quantity value of Shopify fulfillable_quantity
    4. If the  fulfillable_quantity of a fulfillment order’s line item is zero, the line item is already fulfilled, and trying to fulfill that line item gives an error. So, remove that specific line item from the fulfillment orders. For templates that perform partial fulfillments, use PostResponseMap hooks available in the specific template documents.
    5. Go back to the flow. In the Get a list of fulfillment orders for a specific order lookup, click + and then click the hook as shown in the screenshot.
    6. Select the script that you have created.
    7. Click Save and then click Close.
       
       
13. Add a Shopify import step Move the location of fulfillment order to the right of this lookup. Move the location of the fulfillment order to the desired Shopify location, if you want to fulfill a fulfillment order other than its assigned_location_id. The Shopify location coming from the source application might be different. If the location is not moved, the fulfillment order is not fulfilled to the desired Shopify location.
    

    Important: If you want to fulfill the fulfillment orders in their assigned location, ignore steps 13 to 16.

    
    
    
14. Open the import, and set the following:
    1. One to many as Yes
    2. Path to many as fulfillmentOrders
    3. Which field?, provide the fulfillment ID value using handlebars.
       
       
15. Add an input filter to the above import to allow only the records for which the assigned location id of the fulfillment order is different than the Shopify location id coming from the source. If you are storing Shopify’s location ID in some field of a source record, select the field here, if it's a hard-coded value, enter the value with the data type of String, or if the source location ID is not one of the Shopify location ID, then configure the handlebars using compare function as per your requirement. If the Rules in the input filter cannot handle your requirements, use a script for the filter. For more information on how to create a script for a filter in Shopify - Acumatica and Shopify - MYOB templates, see Shopify - Acumatica and Shopify - MYOB Advanced documents respectively.
    
    
16. Add mappings to the above import as per your requirement. If you are storing Shopify’s location ID in some field of a source record, select the field here, if it's a hard-coded value, enter the value with the data type of String, or if the source location ID is not one of the Shopify location ID, then configure the handlebars using compare function as per your requirement.
    
    
17. Add another Shopify import step Import Shopify Fulfimments to the right of the above import to create fulfillment orders using the replacement endpoint.
    
    
18. Open the import, and set the following:
    1. API name as Shipping and fulfillment : Fulfillment 
    2. Operation as Creates a fulfillment for one or many fulfillment orders. Refer to the import from the old flow for any other configurations needed, for example adding One to many, etc. 
       
       
    3. Add an input filter to allow only the records with fulfillmentOrders length greater than zero.
       
       
19. Add mappings to the above import as shown below:
    1. Complete fulfillment flow: The required mappings are demonstrated below (highlighted in purple).
       
       

       Source field	Shopify field
       fulfillmentOrders[*].id	fulfillment.line_items_by_fulfillment_order[*].fulfillment_order_id
       fulfillmentOrders[*].line_items[*].id	fulfillment.line_items_by_fulfillment_order[*].fulfillment_order_line_items[*].id
       fulfillmentOrders[*].line_items[*].fulfillable_quantity	fulfillment.line_items_by_fulfillment_order[*].fulfillment_order_line_items[*].quantity
       Tracking Numbers	fulfillment.tracking_info.number

    2. Partial fulfillment flow: Use the new quantity field created in the above PostResponseMap hook and map that field with the quantity field under fulfillment_order_line_items as shown in the screenshot. For example, in the PostResponseMap hook, we have added the newQuantity field.
       
       

       Source field	Shopify field
       fulfillmentOrders[*].id	fulfillment.line_items_by_fulfillment_order[*].fulfillment_order_id
       fulfillmentOrders[*].line_items[*].id	fulfillment.line_items_by_fulfillment_order[*].fulfillment_order_line_items[*].id
       fulfillmentOrders[*].line_items[*].newQuantity	fulfillment.line_items_by_fulfillment_order[*].fulfillment_order_line_items[*].quantity
       Tracking Numbers	fulfillment.tracking_info.number

Refer to the previous flow that you have cloned, check for any result/response mapping or any important configuration that was missing, and apply the same to the newly configured flow. If the previous mappings consist of any other fields such as tracking number, add those as well. For more information on the mapping structure, see https://shopify.dev/api/admin-rest/2023-01/resources/fulfillment#post-fulfillments

Modify an existing Fulfillment(Deprecated) to Updates the tracking information for a fulfillment

1. Go to the existing flow that uses the endpoint Modify an existing Fulfillment(Deprecated).
2. Open the fulfillment import mappings and take a screenshot or clone the flow to store the mappings and other components for future reference.
3. Delete any import that is using this deprecated endpoint.
4. Create an import using Updates the tracking information for a fulfillment or update the existing import by changing the endpoint to Updates the tracking information for a fulfillment.
5. Provide the fulfillment ID value using handlebars. For example, see the screenshot below.
   
   
6. Review the old mappings, identify the necessary Shopify fields, and map accordingly with the source fields.
   

   Shopify Fields

   fulfillment.notify_customer

   fulfillment.tracking_info.number

   fulfillment.tracking_info.url

   fulfillment.tracking_info.company

Refer to the previous flow that you have cloned, check for any result/response mapping or any important configuration that was missing, and apply the same to the newly configured flow.

Create or Update(Deprecated) to Create or Update a Fulfillment

1. Go to the existing flow that uses the endpoint Create or Update(Deprecated).
2. Open the fulfillment import mappings and take a screenshot or clone the flow to store the mappings and other components for future reference.
3. Follow the instructions from Steps 3 to 16 in the section Create a new Fulfillment(Deprecated) to Creates a fulfillment for one or many fulfillment orders.
4. After the 16th step, set the following:
   1. API name as Shipping and fulfillment : Fulfillment
   2. Operation as Create or Update a Fulfillment
   3. Which field?,  provide the fulfillment ID value using handlebars.
      
      

Refer to the previous flow that you have cloned, check for any result/response mapping or any important configuration that was missing, and apply the same to the newly configured flow.

Cancel a Fulfillment(Deprecated) to Cancel a Fulfillment

1. Go to the existing flow that uses the endpoint Cancel a Fulfillment(Deprecated).
2. Open the fulfillment import mappings and take a screenshot or clone the flow to store the mappings and other components for future reference.
3. Delete any import that is using this deprecated endpoint.
4. Create an import using Cancel a Fulfillment or update the existing import by changing the endpoint to Cancel a Fulfillment.
5. Provide the fulfillment ID value using handlebars. See the screenshot below for an example.
   
   

Refer to the previous flow that you have cloned, check for any result/response mapping or any important configuration that was missing, and apply the same to the newly configured flow.

D. Fulfillment flow changes in Shopify Templates 

There are five flows that do fulfillments in Shopify and are classified according to the type of fulfillment. 

Partial fulfillment

• Acumatica shipments to Shopify fulfillments
• MYOB Advanced shipments to Shopify fulfillments
• lexbizz shipments to Shopify fulfillments

Complete fulfillment

• NetSuite item shipments to Shopify fulfillments
• Microsoft Dynamics 365 Business Central fulfillments(SO with status fulfilled) to Shopify fulfillments