FulfillmentService - admin-graphql - OBJECT

Version: 2024-04

Description:

A **Fulfillment Service** 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 `FulfillmentService` on a store, Shopify automatically creates a `Location` that's associated to the fulfillment service. To learn more about fulfillment services, refer to [Manage fulfillments as a fulfillment service app](https://shopify.dev/apps/fulfillment/fulfillment-service-apps) guide. ## Mutations You can work with the `FulfillmentService` object with the [fulfillmentServiceCreate](https://shopify.dev/api/admin-graphql/latest/mutations/fulfillmentServiceCreate), [fulfillmentServiceUpdate](https://shopify.dev/api/admin-graphql/latest/mutations/fulfillmentServiceUpdate), and [fulfillmentServiceDelete](https://shopify.dev/api/admin-graphql/latest/mutations/fulfillmentServiceDelete) mutations. ## Hosted endpoints 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 `callbackUrl` parameter in the [fulfillmentServiceCreate](https://shopify.dev/api/admin-graphql/latest/mutations/fulfillmentServiceCreate) mutation. - Shopify sends POST requests to the `<callbackUrl>/fulfillment_order_notification` endpoint to notify the fulfillment service about fulfillment requests and fulfillment cancellation requests. For more information, refer to [Receive fulfillment requests and cancellations](https://shopify.dev/apps/fulfillment/fulfillment-service-apps/manage-fulfillments#step-2-receive-fulfillment-requests-and-cancellations). - Shopify sends GET requests to the `<callbackUrl>/fetch_tracking_numbers` endpoint to retrieve tracking numbers for orders, if `trackingSupport` is set to `true`. For more information, refer to [Enable tracking support](https://shopify.dev/apps/fulfillment/fulfillment-service-apps/manage-fulfillments#step-8-enable-tracking-support-optional). Fulfillment services can also update tracking information with the [fulfillmentTrackingInfoUpdate](https://shopify.dev/api/admin-graphql/unstable/mutations/fulfillmentTrackingInfoUpdate) mutation, rather than waiting for Shopify to ask for tracking numbers. - Shopify sends GET requests to the `<callbackUrl>/fetch_stock` endpoint to retrieve inventory levels, if `inventoryManagement` is set to `true`. For more information, refer to [Sharing inventory levels with Shopify](https://shopify.dev/apps/fulfillment/fulfillment-service-apps/manage-fulfillments#step-9-share-inventory-levels-with-shopify-optional). To make sure you have everything set up correctly, you can test the `callbackUrl`-prefixed endpoints in your development store. ## Resources and webhooks There are a variety of objects and webhooks that enable a fulfillment service to work. To exchange fulfillment information with Shopify, fulfillment services use the [FulfillmentOrder](https://shopify.dev/api/admin-graphql/latest/objects/FulfillmentOrder), [Fulfillment](https://shopify.dev/api/admin-graphql/latest/objects/Fulfillment) and [Order](https://shopify.dev/api/admin-graphql/latest/objects/Order) objects and related mutations. To act on fulfillment process events that happen on the Shopify side, besides awaiting calls to `callbackUrl`-prefixed endpoints, fulfillment services can subscribe to the [fulfillment order](https://shopify.dev/apps/fulfillment/fulfillment-service-apps/manage-fulfillments#webhooks) and [order](https://shopify.dev/api/admin-rest/latest/resources/webhook) webhooks.

Access Scopes

Fields

callbackUrl: URL - The callback URL that the fulfillment service has registered for requests. The following considerations apply: - Shopify queries the `<callbackUrl>/fetch_tracking_numbers` endpoint to retrieve tracking numbers for orders, if `trackingSupport` is set to `true`. - Shopify queries the `<callbackUrl>/fetch_stock` endpoint to retrieve inventory levels, if `inventoryManagement` is set to `true`. - Shopify uses the `<callbackUrl>/fulfillment_order_notification` endpoint to send [fulfillment and cancellation requests](https://shopify.dev/apps/fulfillment/fulfillment-service-apps/manage-fulfillments#step-2-receive-fulfillment-requests-and-cancellations), if the fulfillment service has opted in to the fulfillment order based workflow for managing fulfillments (`fulfillmentOrdersOptIn` is set to `true`).
fulfillmentOrdersOptIn: Boolean! - Whether the fulfillment service uses the [fulfillment order based workflow](https://shopify.dev/apps/fulfillment/fulfillment-service-apps/manage-fulfillments) for managing fulfillments. As the migration is now finished, the `fulfillmentOrdersOptIn` property is [deprecated]( https://shopify.dev/changelog/deprecation-of-the-fulfillmentservice-fulfillmentordersoptin-field) and is always set to `true` on correctly functioning fulfillment services.
handle: String! - Human-readable unique identifier for this fulfillment service.
id: ID! - The ID of the fulfillment service.
inventoryManagement: Boolean! - Whether the fulfillment service tracks product inventory and provides updates to Shopify.
location: Location - Location associated with the fulfillment service.
permitsSkuSharing: Boolean! - Whether the fulfillment service can stock inventory alongside other locations.
productBased: Boolean! - Whether the fulfillment service supports local deliveries.
serviceName: String! - The name of the fulfillment service as seen by merchants.
shippingMethods: ShippingMethod! - Shipping methods associated with the fulfillment service provider. Applies only to Fulfill By Amazon fulfillment service.
type: FulfillmentServiceType! - Type associated with the fulfillment service.

Connections

Related queries

fulfillmentService Returns a FulfillmentService resource by ID.

Related mutations

fulfillmentServiceCreate Creates a fulfillment service. ## Fulfillment service location When creating a fulfillment service, a new location will be automatically created on the shop and will be associated with this fulfillment service. This location will be named after the fulfillment service and inherit the shop's address. If you are using API version `2023-10` or later, and you need to specify custom attributes for the fulfillment service location (for example, to change its address to a country different from the shop's country), use the [LocationEdit](https://shopify.dev/api/admin-graphql/latest/mutations/locationEdit) mutation after creating the fulfillment service.
fulfillmentServiceUpdate Updates a fulfillment service. If you are using API version `2023-10` or later, and you need to update the location managed by the fulfillment service (for example, to change the address of a fulfillment service), use the [LocationEdit](https://shopify.dev/api/admin-graphql/latest/mutations/locationEdit) mutation.

Related Unions

Examples

Receive a single FulfillmentService

        Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2024-04/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"query\": \"query FulfillmentServiceShow($id: ID!) { fulfillmentService(id: $id) { id callbackUrl fulfillmentOrdersOptIn permitsSkuSharing handle inventoryManagement serviceName location { legacyResourceId } } }\",\n \"variables\": {\n    \"id\": \"gid://shopify/FulfillmentService/18961920\"\n  }\n}'\n"
        Node example: "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n  data: {\n    \"query\": `query FulfillmentServiceShow($id: ID!) {\n      fulfillmentService(id: $id) {\n        id\n        callbackUrl\n        fulfillmentOrdersOptIn\n        permitsSkuSharing\n        handle\n        inventoryManagement\n        serviceName\n        location {\n          legacyResourceId\n        }\n      }\n    }`,\n    \"variables\": {\n      \"id\": \"gid://shopify/FulfillmentService/18961920\"\n    },\n  },\n});\n"
        Ruby example: "session = ShopifyAPI::Auth::Session.new(\n  shop: \"your-development-store.myshopify.com\",\n  access_token: access_token\n)\nclient = ShopifyAPI::Clients::Graphql::Admin.new(\n  session: session\n)\n\nquery = <<~QUERY\n  query FulfillmentServiceShow($id: ID!) {\n    fulfillmentService(id: $id) {\n      id\n      callbackUrl\n      fulfillmentOrdersOptIn\n      permitsSkuSharing\n      handle\n      inventoryManagement\n      serviceName\n      location {\n        legacyResourceId\n      }\n    }\n  }\nQUERY\n\nvariables = {\n  \"id\": \"gid://shopify/FulfillmentService/18961920\"\n}\n\nresponse = client.query(query: query, variables: variables)\n"
        PHP example: "use Shopify\\Clients\\Graphql;\n\n$client = new Graphql(\"your-development-store.myshopify.com\", $accessToken);\n$query = <<<QUERY\n  query FulfillmentServiceShow($id: ID!) {\n    fulfillmentService(id: $id) {\n      id\n      callbackUrl\n      fulfillmentOrdersOptIn\n      permitsSkuSharing\n      handle\n      inventoryManagement\n      serviceName\n      location {\n        legacyResourceId\n      }\n    }\n  }\nQUERY;\n\n$variables = [\n  \"id\" => \"gid://shopify/FulfillmentService/18961920\",\n];\n\n$response = $client->query([\"query\" => $query, \"variables\" => $variables]);\n"
        Remix example: "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n  `#graphql\n  query FulfillmentServiceShow($id: ID!) {\n    fulfillmentService(id: $id) {\n      id\n      callbackUrl\n      fulfillmentOrdersOptIn\n      permitsSkuSharing\n      handle\n      inventoryManagement\n      serviceName\n      location {\n        legacyResourceId\n      }\n    }\n  }`,\n  {\n    variables: {\n      \"id\": \"gid://shopify/FulfillmentService/18961920\"\n    },\n  },\n);\n\nconst data = await response.json();\n"
        Graphql query: "query FulfillmentServiceShow($id: ID!) {\n  fulfillmentService(id: $id) {\n    id\n    callbackUrl\n    fulfillmentOrdersOptIn\n    permitsSkuSharing\n    handle\n    inventoryManagement\n    serviceName\n    location {\n      legacyResourceId\n    }\n  }\n}"

input: {
  "id": "gid://shopify/FulfillmentService/18961920"
}

response: {
  "data": {
    "fulfillmentService": {
      "id": "gid://shopify/FulfillmentService/18961920?id=true",
      "callbackUrl": "http://shipwire.com",
      "fulfillmentOrdersOptIn": true,
      "permitsSkuSharing": true,
      "handle": "shipwire",
      "inventoryManagement": false,
      "serviceName": "Shipwire",
      "location": {
        "legacyResourceId": "215093630"
      }
    }
  }
}