# FulfillmentService <p>A <strong>Fulfillment Service</strong> is a third party warehouse that prepares and ships orders on behalf of the store owner. Fulfillment services charge a fee to package and ship items and update product inventory levels. Some well known fulfillment services with Shopify integrations include: Amazon, Shipwire, and Rakuten. When an app registers a new <code>FulfillmentService</code> on a store, Shopify automatically creates a <code>Location</code> that's associated to the fulfillment service. To learn more about fulfillment services, refer to <a href="/apps/fulfillment/fulfillment-service-apps">Manage fulfillments as a fulfillment service app</a> guide. </p> <p>Using the <code>FulfillmentService</code> resource, you can register, edit, and delete a new fulfillment service.</p> <h2>Hosted endpoints</h2> <p>Fulfillment service providers integrate with Shopify by providing Shopify with a set of hosted endpoints that Shopify can query on certain conditions. These endpoints must have a common prefix, and this prefix should be supplied in the <code>callback_url</code> parameter in the request that creates the fulfillment service. </p> <ul> <li>Shopify sends POST requests to the <code>callback_url/fulfillment_order_notification</code> endpoint to notify the fulfillment service about fulfillment requests and fulfillment cancellation requests. <br><a href="/changelog/legacy-fulfillment-api-deprecation">As of the 2022-07 API version</a>, it's mandatory for a fulfillment service to follow a fulfillment order based workflow by hosting the <code>callback_url/fulfillment_order_notification</code> endpoint, and acting on fulfillment requests and cancellations. <br>For more information, refer to <a href="/apps/fulfillment/fulfillment-service-apps/manage-fulfillments#step-2-receive-fulfillment-requests-and-cancellations">Receive fulfillment requests and cancellations</a>. </li> <li>Shopify sends GET requests to the <code>callback_url/fetch_tracking_numbers</code> endpoint to retrieve tracking numbers for orders, if <code>tracking_support</code> is set to <code>true</code>. <br>For more information, refer to <a href="/apps/fulfillment/fulfillment-service-apps/manage-fulfillments#step-8-enable-tracking-support-optional">Enable tracking support</a>. <br>Fulfillment services can also update tracking information with a <a href="/api/admin-rest/latest/resources/fulfillment#post-fulfillments-fulfillment-id-update-tracking">corresponding API</a>, rather than waiting for Shopify to ask for tracking numbers. </li> <li>Shopify sends GET requests to the <code>callback_url/fetch_stock</code> endpoint to retrieve inventory levels, if <code>inventory_management</code> is set to <code>true</code>. <br>For more information, refer to <a href="/apps/fulfillment/fulfillment-service-apps/manage-fulfillments#step-9-share-inventory-levels-with-shopify-optional">Sharing inventory levels with Shopify</a>. </li> </ul> <p>To make sure you have everything set up correctly, you can test the <code>callback_url</code>-prefixed endpoints in your development store.</p> <h2>Resources and webhooks</h2> <p>There are a variety of REST resources and webhooks that enable a fulfillment service to work. To exchange fulfillment information with Shopify, fulfillment services use the <a href="/api/admin-rest/latest/resources/fulfillmentorder">FulfillmentOrder</a>, <a href="/api/admin-rest/latest/resources/fulfillmentrequest">FulfillmentRequest</a>, and <a href="/api/admin-rest/latest/resources/cancellationrequest">CancellationRequest</a>, <a href="/api/admin-rest/latest/resources/fulfillment">Fulfillment</a> and <a href="/api/admin-rest/latest/resources/order">Order</a> resources. To act on fulfillment process events that happen on the Shopify side, besides awaiting calls to <code>callback_url</code>-prefixed endpoints, fulfillment services can subscribe to the <a href="/apps/fulfillment/fulfillment-service-apps/manage-fulfillments#webhooks">fulfillment order</a> and <a href="/api/admin-rest/latest/resources/webhook">order</a> webhooks. </p> ## Resource Properties ### FulfillmentService * admin_graphql_api_id: The GraphQL GID for this fulfillment service. * Type: x-string * Example: "gid://shopify/FulfillmentService/1" * callback_url: The callback URL that the fulfillment service has registered for requests. The following considerations apply: <ul> <li> Shopify queries the <code>callback_url/fetch_tracking_numbers</code> endpoint to retrieve tracking numbers for orders, if <code>tracking_support</code> is set to <code>true</code>.</li> <li> Shopify queries the <code>callback_url/fetch_stock</code> endpoint to retrieve inventory levels, if <code>inventory_management</code> is set to <code>true</code>.</li> <li> Shopify uses the <code>callback_url/fulfillment_order_notification</code> endpoint to send <a href="/apps/fulfillment/fulfillment-service-apps/manage-fulfillments#step-2-receive-fulfillment-requests-and-cancellations"> fulfillment and cancellation requests</a> </ul> * Type: x-string * Example: "http://myapp.com" * fulfillment_orders_opt_in: Whether the fulfillment service uses the <a href="/apps/fulfillment/fulfillment-service-apps/manage-fulfillments">fulfillment order based workflow</a> for managing fulfillments.<br><a href="/changelog/legacy-fulfillment-api-deprecation">As of 2022-07 API version</a>, the fulfillment order based workflow is the only way to manage fulfillments, and <code>fulfillment_orders_opt_in</code> must be set to <code>true</code>.<br>As the migration is now finished, the <code>fulfillment_orders_opt_in</code> property is <a href="/changelog/deprecation-of-the-fulfillmentservice-fulfillmentordersoptin-field">deprecated</a> and is always set to <code>true</code> on correctly functioning fulfillment services. * Type: x-string * Example: true * permits_sku_sharing: Whether the fulfillment service can stock inventory alongside other locations. * Type: x-string * Example: true * handle: Human-readable unique identifier for this fulfillment service. * Type: x-string * Example: "my-fulfillment-service" * inventory_management: Whether the fulfillment service tracks product inventory and provides updates to Shopify. Valid values: <code>true</code> and <code>false</code>. * Type: x-string * Example: true * location_id: The unique identifier of the location associated with the fulfillment service * Type: x-string * Example: 19 * name: The name of the fulfillment service as seen by merchants. * Type: x-string * Example: "My Fulfillment Service" * provider_id: A unique identifier for the fulfillment service provider. * Type: x-string * Example: nil * requires_shipping_method: Whether the fulfillment service requires products to be physically shipped. Valid values: <code>true</code> and <code>false</code>. * Type: x-string * Example: true * tracking_support: Whether the fulfillment service provides tracking numbers for packages. Valid values: <code>true</code> and <code>false</code>. * Type: x-string * Example: true ## Receive a list of all FulfillmentServices ### Endpoint /admin/api/#{api_version}/fulfillment_services.json?scope=all (GET) ### Parameters * api_version (required): * scope: Specify which fulfillment services to retrieve. ### Responses #### 200 Receive a list of all FulfillmentServices Examples: ##### List all of the shop's fulfillment services Request: ``` GET /admin/api/unstable/fulfillment_services.json ``` Response: ``` HTTP/1.1 200 OK {"fulfillment_services":[{"id":611870435,"name":"Venus Fulfillment","email":null,"service_name":"Venus Fulfillment","handle":"venus-fulfillment","fulfillment_orders_opt_in":true,"include_pending_stock":false,"provider_id":null,"location_id":611870435,"callback_url":"http://google.com/","tracking_support":false,"inventory_management":false,"admin_graphql_api_id":"gid://shopify/ApiFulfillmentService/611870435","permits_sku_sharing":false,"requires_shipping_method":true},{"id":755357713,"name":"Mars Fulfillment","email":null,"service_name":"Mars Fulfillment","handle":"mars-fulfillment","fulfillment_orders_opt_in":true,"include_pending_stock":false,"provider_id":null,"location_id":24826418,"callback_url":"http://google.com/","tracking_support":true,"inventory_management":true,"admin_graphql_api_id":"gid://shopify/ApiFulfillmentService/755357713","permits_sku_sharing":true,"requires_shipping_method":true}]} ``` ##### List your app's fulfillment services Request: ``` GET /admin/api/unstable/fulfillment_services.json ``` Response: ``` HTTP/1.1 200 OK {"fulfillment_services":[{"id":755357713,"name":"Mars Fulfillment","email":null,"service_name":"Mars Fulfillment","handle":"mars-fulfillment","fulfillment_orders_opt_in":true,"include_pending_stock":false,"provider_id":null,"location_id":24826418,"callback_url":"http://google.com/","tracking_support":true,"inventory_management":true,"admin_graphql_api_id":"gid://shopify/ApiFulfillmentService/755357713","permits_sku_sharing":true,"requires_shipping_method":true}]} ``` ## Create a new FulfillmentService ### Endpoint /admin/api/#{api_version}/fulfillment_services.json (POST) ### Parameters * api_version (required): * callback_url: The callback URL that the fulfillment service has registered for requests. The following considerations apply: <ul> <li> Shopify queries the <code>callback_url/fetch_tracking_numbers</code> endpoint to retrieve tracking numbers for orders, if <code>tracking_support</code> is set to <code>true</code>.</li> <li> Shopify queries the <code>callback_url/fetch_stock</code> endpoint to retrieve inventory levels, if <code>inventory_management</code> is set to <code>true</code>.</li> <li> Shopify uses the <code>callback_url/fulfillment_order_notification</code> endpoint to send <a href="/apps/fulfillment/fulfillment-service-apps/manage-fulfillments#step-2-receive-fulfillment-requests-and-cancellations"> fulfillment and cancellation requests</a> </ul> * fulfillment_orders_opt_in: Whether the fulfillment service uses the <a href="/apps/fulfillment/fulfillment-service-apps/manage-fulfillments">fulfillment order based workflow</a> for managing fulfillments.<br>As the migration is now finished, the <code>fulfillment_orders_opt_in</code> property is <a href="/changelog/deprecation-of-the-fulfillmentservice-fulfillmentordersoptin-field">deprecated</a> and will be removed in the next API version. This API version defaults it to <code>true</code> for a smooth migration experience. Do not set the <code>fulfillment_orders_opt_in</code> argument, and you are ready for the next API version release. * inventory_management: Whether the fulfillment service tracks product inventory and provides updates to Shopify. Valid values: <code>true</code> and <code>false</code>. * name: The name of the fulfillment service as seen by merchants. * permits_sku_sharing: Whether the fulfillment service can stock inventory alongside other locations. * requires_shipping_method: Whether the fulfillment service requires products to be physically shipped. Valid values: <code>true</code> and <code>false</code>. * tracking_support: Whether the fulfillment service provides tracking numbers for packages. Valid values: <code>true</code> and <code>false</code>. ### Responses #### 201 Create a new FulfillmentService Examples: ##### Create a fulfillment service Request: ``` POST /admin/api/2024-04/fulfillment_services.json {"fulfillment_service":{"name":"Jupiter Fulfillment","callback_url":"http://google.com","inventory_management":true,"tracking_support":true,"permits_sku_sharing":true}} ``` Response: ``` HTTP/1.1 201 Created {"fulfillment_service":{"id":1061774487,"name":"Jupiter Fulfillment","email":null,"service_name":"Jupiter Fulfillment","handle":"jupiter-fulfillment","fulfillment_orders_opt_in":true,"include_pending_stock":false,"provider_id":null,"location_id":1072404544,"callback_url":"http://google.com/","tracking_support":true,"inventory_management":true,"admin_graphql_api_id":"gid://shopify/ApiFulfillmentService/1061774487","permits_sku_sharing":true,"requires_shipping_method":true}} ``` ## Receive a single FulfillmentService ### Endpoint /admin/api/#{api_version}/fulfillment_services/{fulfillment_service_id}.json (GET) ### Parameters * api_version (required): * fulfillment_service_id (required): ### Responses #### 200 Receive a single FulfillmentService Examples: ##### Get a single fulfillment service by its ID Request: ``` GET /admin/api/unstable/fulfillment_services/755357713.json ``` Response: ``` HTTP/1.1 200 OK {"fulfillment_service":{"id":755357713,"name":"Mars Fulfillment","email":null,"service_name":"Mars Fulfillment","handle":"mars-fulfillment","fulfillment_orders_opt_in":true,"include_pending_stock":false,"provider_id":null,"location_id":24826418,"callback_url":"http://google.com/","tracking_support":true,"inventory_management":true,"admin_graphql_api_id":"gid://shopify/ApiFulfillmentService/755357713","permits_sku_sharing":true,"requires_shipping_method":true}} ``` ## Modify an existing FulfillmentService ### Endpoint /admin/api/#{api_version}/fulfillment_services/{fulfillment_service_id}.json (PUT) ### Parameters * api_version (required): * fulfillment_service_id (required): * callback_url: The callback URL that the fulfillment service has registered for requests. The following considerations apply: <ul> <li> Shopify queries the <code>callback_url/fetch_tracking_numbers</code> endpoint to retrieve tracking numbers for orders, if <code>tracking_support</code> is set to <code>true</code>.</li> <li> Shopify queries the <code>callback_url/fetch_stock</code> endpoint to retrieve inventory levels, if <code>inventory_management</code> is set to <code>true</code>.</li> <li> Shopify uses the <code>callback_url/fulfillment_order_notification</code> endpoint to send <a href="/apps/fulfillment/fulfillment-service-apps/manage-fulfillments#step-2-receive-fulfillment-requests-and-cancellations"> fulfillment and cancellation requests</a> </ul> * fulfillment_orders_opt_in: Whether the fulfillment service uses the <a href="/apps/fulfillment/fulfillment-service-apps/manage-fulfillments">fulfillment order based workflow</a> for managing fulfillments.<br>As the migration is now finished, the <code>fulfillment_orders_opt_in</code> property is <a href="/changelog/deprecation-of-the-fulfillmentservice-fulfillmentordersoptin-field">deprecated.</a> * inventory_management: Whether the fulfillment service tracks product inventory and provides updates to Shopify. Valid values: <code>true</code> and <code>false</code>. * name: The name of the fulfillment service as seen by merchants. * permits_sku_sharing: Whether the fulfillment service can stock inventory alongside other locations. * requires_shipping_method: Whether the fulfillment service requires products to be physically shipped. Valid values: <code>true</code> and <code>false</code>. * tracking_support: Whether the fulfillment service provides tracking numbers for packages. Valid values: <code>true</code> and <code>false</code>. ### Responses #### 200 Modify an existing FulfillmentService Examples: ##### Update a fulfillment service Request: ``` PUT /admin/api/unstable/fulfillment_services/755357713.json {"fulfillment_service":{"id":755357713,"name":"New Fulfillment Service Name"}} ``` Response: ``` HTTP/1.1 200 OK {"fulfillment_service":{"id":755357713,"name":"New Fulfillment Service Name","email":null,"service_name":"New Fulfillment Service Name","handle":"mars-fulfillment","fulfillment_orders_opt_in":true,"include_pending_stock":false,"provider_id":null,"location_id":24826418,"callback_url":"http://google.com/","tracking_support":true,"inventory_management":true,"admin_graphql_api_id":"gid://shopify/ApiFulfillmentService/755357713","permits_sku_sharing":true,"requires_shipping_method":true}} ``` ## Remove an existing FulfillmentService ### Endpoint /admin/api/#{api_version}/fulfillment_services/{fulfillment_service_id}.json (DELETE) ### Parameters * api_version (required): * fulfillment_service_id (required): ### Responses #### 200 Remove an existing FulfillmentService Examples: ##### Destroy a fulfillment service Request: ``` DELETE /admin/api/unstable/fulfillment_services/755357713.json ``` Response: ``` HTTP/1.1 200 OK {} ```