# 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
{}
```