Admin-API/ext/fulfillment.graphql

# Represents a fulfillment service.
# A fulfillment service is a third-party service that prepares and ships orders on behalf of the store owner.
type FulfillmentService {
    # The callback URL that the fulfillment service has registered for requests. The following considerations apply:
    #
    # Shopify queries the <code>callback_url/fetch_tracking_numbers</code> endpoint to retrieve tracking numbers
    # for orders, if inventoryManagement is set to true.
    # Shopify queries the <code>callback_url/fetch_stock</code> endpoint to retrieve inventory levels,
    # if trackingSupport is set to true.
    # Shopify uses the <code>callback_url/fulfillment_order_notification</code> endpoint to send
    # fulfillment and cancellation requests,
    # if the fulfillment service has opted in to the fulfillment order based workflow for managing fulfillments
    # (fulfillmentOrdersOptIn is set to true).
    callbackUrl: URL

    # Whether the fulfillment service uses the fulfillment order based workflow for managing fulfillments.
    fulfillmentOrdersOptIn: Boolean!

    # Human-readable unique identifier for this fulfillment service.
    handle: String!

    # The ID of the fulfillment service.
    id: ID!

    # Whether the fulfillment service tracks product inventory and provides updates to Shopify.
    inventoryManagement: Boolean!

    # Location associated with the fulfillment service.
    location: Location

    # Whether the fulfillment service can stock inventory alongside other locations.
    permitsSkuSharing: Boolean!

    # Whether the fulfillment service supports local deliveries.
    productBased: Boolean!

    # The name of the fulfillment service as seen by merchants.
    serviceName: String!

    # Type associated with the fulfillment service.
    type: FulfillmentServiceType!
}

# The quantities of an inventory item that are related to a specific location.
type InventoryLevel implements Node {
    # The quantity of inventory items that are available at the inventory level's associated location.
    available: Int!

    # Whether the inventory items associated with the inventory level can be deactivated.
    canDeactivate: Boolean!

    # The date and time when the inventory level was created.
    createdAt: DateTime!

    # Describes either the impact of deactivating the inventory level, or why the inventory level can't be deactivated.
    deactivationAlert: String

    # Describes, in HTML with embedded URLs, either the impact of deactivating the inventory level or why the inventory level can't be deactivated.
    deactivationAlertHtml: FormattedString

    # A globally-unique identifier.
    id: ID!

    # The quantity of inventory items that are going to the inventory level's associated location.
    incoming: Int!

    # Inventory item associated with the inventory level.
    item: InventoryItem!

    # The location associated with the inventory level.
    location: Location!

    # The date and time when the inventory level was updated.
    updatedAt: DateTime!
}

# Represents a fulfillment. In Shopify, a fulfillment represents a shipment of one or more items in an order.
# When an order has been completely fulfilled, it means that all the items that are included in the order have been sent to the customer.
# There can be more than one fulfillment for an order.
type Fulfillment implements LegacyInteroperability&Node {
    # The date and time when the fulfillment was created.
    createdAt: DateTime!

    # The date that this fulfillment was delivered.
    deliveredAt: DateTime

    # Human readable display status for this fulfillment.
    displayStatus: FulfillmentDisplayStatus

    # The estimated date that this fulfillment will arrive.
    estimatedDeliveryAt: DateTime

    # The history of events associated with this fulfillment.
    events(
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
        sortKey: FulfillmentEventSortKeys = HAPPENED_AT
    ): FulfillmentEventConnection!

    # List of the fulfillment's line items.
    fulfillmentLineItems(
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
    ): FulfillmentLineItemConnection!

    # A paginated list of fulfillment orders for the fulfillment.
    fulfillmentOrders(
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
    ): FulfillmentOrderConnection!

    # A globally-unique identifier.
    id: ID!

    # The date and time when the fulfillment went into transit.
    inTransitAt: DateTime

    # The ID of the corresponding resource in the REST Admin API.
    legacyResourceId: UnsignedInt64!

    # The location that the fulfillment was processed at.
    location: Location

    # Human readable reference identifier for this fulfillment.
    name: String!

    # The order for which the fulfillment was created.
    order: Order!

    # The address at which the fulfillment occurred.
    # Typically this is the address of the warehouse or fulfillment center.
    originAddress: FulfillmentOriginAddress

    # Whether any of the line items in the fulfillment require shipping.
    requiresShipping: Boolean!

    # Fulfillment service associated with the fulfillment.
    service: FulfillmentService

    # The status of the fulfillment.
    status: FulfillmentStatus!

    # Sum of all line item quantities for the fulfillment.
    totalQuantity: Int!

    # Tracking information associated with the fulfillment,
    # such as the tracking company, tracking number, and tracking URL.
    trackingInfo(first: Int): [FulfillmentTrackingInfo!]!

    # The date and time when the fulfillment was last modified.
    updatedAt: DateTime!
}

# Represents the tracking information for a fulfillment.
type FulfillmentTrackingInfo {
    # The name of the tracking company.
    company: String

    # The tracking number of the fulfillment.
    number: String

    # The URLs to track the fulfillment.
    url: URL
}

# Represents a fulfillment order. In Shopify, a fulfillment order represents a group of one or more items
# in an order that are to be fulfilled from the same location. There can be more than one fulfillment order
# for an order at a given location. Fulfillment orders are created automatically when an order is created.
# To learn how to build a fulfillment app, refer to Fulfillment apps.
type FulfillmentOrder implements Node {
    # The fulfillment order's assigned location. This is the location where the fulfillment is expected to happen.
    #
    # The fulfillment order's assigned location might change in the following cases:
    #
    # The fulfillment order has been entirely moved to a new location. For example, the fulfillmentOrderMove mutation has been called, and you see the original fulfillment order in the movedFulfillmentOrder field within the mutation's response.
    # Work on the fulfillment order has not yet begun, which means that the fulfillment order has the
    # OPEN,
    # SCHEDULED, or
    # ON_HOLD
    # status, and the shop's location properties might be undergoing edits (for example, in the Shopify admin).
    assignedLocation: FulfillmentOrderAssignedLocation!

    # Delivery method of this fulfillment order.
    deliveryMethod: DeliveryMethod

    # The destination where the items should be sent.
    destination: FulfillmentOrderDestination

    # The date and time at which the fulfillment order will be fulfillable.
    # When this date and time is reached, the scheduled fulfillment order is automatically transitioned to open.
    # For example, the fulfill_at date for a subscription order might be the 1st of each month, a pre-order fulfill_at date would be nil, and a standard order fulfill_at date would be the order creation date.
    fulfillAt: DateTime

    # The latest date and time by which all items in the fulfillment order need to be fulfilled.
    fulfillBy: DateTime

    # The fulfillment holds applied on the fulfillment order.
    fulfillmentHolds: [FulfillmentHold!]!

    # A list of fulfillments for the fulfillment order.
    fulfillments(
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
    ): FulfillmentConnection!

    # A globally-unique identifier.
    id: ID!

    # The duties delivery method of this fulfillment order.
    internationalDuties: FulfillmentOrderInternationalDuties

    # A list of the fulfillment order's line items.
    lineItems(
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
    ): FulfillmentOrderLineItemConnection!

    # A list of locations that the fulfillment order can potentially move to.
    locationsForMove(
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
    ): FulfillmentOrderLocationForMoveConnection!

    # A list of requests sent by the merchant to the fulfillment service for this fulfillment order.
    merchantRequests(
        kind: FulfillmentOrderMerchantRequestKind
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
    ): FulfillmentOrderMerchantRequestConnection!

    # The order that's associated with the fulfillment order.
    order: Order!

    # The request status of the fulfillment order.
    requestStatus: FulfillmentOrderRequestStatus!

    # The status of the fulfillment order.
    status: FulfillmentOrderStatus!

    # The actions that can be performed on this fulfillment order.
    supportedActions: [FulfillmentOrderSupportedAction!]!
}

# The fulfillment order's assigned location. This is the location where the fulfillment is expected to happen.
#
# The fulfillment order's assigned location might change in the following cases:
#
# The fulfillment order has been entirely moved to a new location. For example, the fulfillmentOrderMove mutation has been called, and you see the original fulfillment order in the movedFulfillmentOrder field within the mutation's response.
#
# Work on the fulfillment order has not yet begun, which means that the fulfillment order has the
# OPEN,
# SCHEDULED, or
# ON_HOLD
# status, and the shop's location properties might be undergoing edits (for example, in the Shopify admin).
#
# If the fulfillmentOrderMove mutation has moved the fulfillment order's line items to a new location,
# but hasn't moved the fulfillment order instance itself, then the original fulfillment order's assigned location
# doesn't change.
# This happens if the fulfillment order is being split during the move, or if all line items can be moved
# to an existing fulfillment order at a new location.
#
# Once the fulfillment order has been taken into work or canceled,
# which means that the fulfillment order has the
# IN_PROGRESS,
# CLOSED,
# CANCELLED, or
# INCOMPLETE
# status, FulfillmentOrderAssignedLocation acts as a snapshot of the shop's location content.
# Up-to-date shop's location data may be queried through location connection.
type FulfillmentOrderAssignedLocation {
    # The first line of the address for the location.
    address1: String

    # The second line of the address for the location.
    address2: String

    # The city of the location.
    city: String

    # The two-letter country code of the location.
    countryCode: CountryCode!

    # The location where the fulfillment is expected to happen. This value might be different from
    # FulfillmentOrderAssignedLocation if the location's attributes were updated
    # after the fulfillment order was taken into work of canceled.
    location: Location

    # The name of the location.
    name: String!

    # The phone number of the location.
    phone: String

    # The province of the location.
    province: String

    # The ZIP code of the location.
    zip: String
}

# Represents the goods available to be shipped to a customer.
# It holds essential information about the goods, including SKU and whether it is tracked.
type InventoryItem implements LegacyInteroperability&Node {
    # The ISO 3166-1 alpha-2 country code of where the item originated from.
    countryCodeOfOrigin: CountryCode

    # A list of country specific harmonized system codes.
    countryHarmonizedSystemCodes(
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
    ): CountryHarmonizedSystemCodeConnection!

    # The date and time when the inventory item was created.
    createdAt: DateTime!

    # The number of inventory items that share the same SKU with this item.
    duplicateSkuCount: Int!

    # The harmonized system code of the item.
    harmonizedSystemCode: String

    # A globally-unique identifier.
    id: ID!

    # The URL that points to the inventory history for the item.
    inventoryHistoryUrl: URL

    # The inventory item's quantities at the specified location.
    inventoryLevel(locationId: ID!): InventoryLevel

    # A list of the inventory item's quantities for each location that the inventory item can be stocked at.
    inventoryLevels(
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
        query: String
    ): InventoryLevelConnection!

    # The ID of the corresponding resource in the REST Admin API.
    legacyResourceId: UnsignedInt64!

    # The number of locations where this inventory item is stocked.
    locationsCount: Int!

    # The ISO 3166-2 alpha-2 province code of where the item originated from.
    provinceCodeOfOrigin: String

    # Whether the inventory item requires shipping.
    requiresShipping: Boolean!

    # Inventory item SKU.
    sku: String

    # Whether inventory levels are tracked for the item.
    tracked: Boolean!

    # Whether the value of the tracked field for the inventory item can be changed.
    trackedEditable: EditableProperty!

    # Unit cost associated with the inventory item.
    unitCost: MoneyV2

    # The date and time when the inventory item was updated.
    updatedAt: DateTime!

    # The variant that owns this inventory item.
    variant: ProductVariant!
}

# The address at which the fulfillment occurred.
# Typically this is the address of the warehouse or fulfillment center.
type FulfillmentOriginAddress {
    # The street address of the fulfillment location.
    address1: String

    # The second line of the address. Typically the number of the apartment, suite, or unit.
    address2: String

    # The city in which the fulfillment location is located.
    city: String

    # The country code of the fulfillment location.
    countryCode: String!

    # The province code of the fulfillment location.
    provinceCode: String

    # The zip code of the fulfillment location.
    zip: String
}

# Represents the destination where the items should be sent upon fulfillment.
type FulfillmentOrderDestination implements Node {
    # The first line of the address of the destination.
    address1: String

    # The second line of the address of the destination.
    address2: String

    # The city of the destination.
    city: String

    # The company of the destination.
    company: String

    # The two-letter country code of the destination.
    countryCode: CountryCode

    # The email of the customer at the destination.
    email: String

    # The first name of the customer at the destination.
    firstName: String

    # A globally-unique identifier.
    id: ID!

    # The last name of the customer at the destination.
    lastName: String

    # The phone number of the customer at the destination.
    phone: String

    # The province of the destination.
    province: String

    # The ZIP code of the destination.
    zip: String
}

# A fulfillment hold currently applied on a fulfillment order.
type FulfillmentHold {
    # The reason for the fulfillment hold.
    reason: FulfillmentHoldReason!

    # Additional information about the fulfillment hold reason.
    reasonNotes: String
}

# The international duties relevant to a fulfillment order.
type FulfillmentOrderInternationalDuties {
    # The method of duties payment. Example values: DDP, DAP.
    incoterm: String!
}

# One of the actions that the fulfillment order supports in its current state.
type FulfillmentOrderSupportedAction {
    # The action value.
    action: FulfillmentOrderAction!

    # The external URL to be used to initiate the fulfillment process outside Shopify.
    # Applicable only when the action value is EXTERNAL.
    externalUrl: URL
}

# The fulfillment event that describes the fulfilllment status at a particular time.
type FulfillmentEvent implements Node {
    # The time at which this fulfillment event happened.
    happenedAt: DateTime!

    # A globally-unique identifier.
    id: ID!

    # The status of this fulfillment event.
    status: FulfillmentEventStatus!
}

# Represents a line item from an order that's included in a fulfillment.
type FulfillmentLineItem implements Node {
    # The total price after discounts are applied in shop and presentment currencies.
    discountedTotalSet: MoneyBag!

    # A globally-unique identifier.
    id: ID!

    # The associated order's line item.
    lineItem: LineItem!

    # The total price before discounts are applied in shop and presentment currencies.
    originalTotalSet: MoneyBag!

    # Number of line items in the fulfillment.
    quantity: Int
}

# Associates an order line item with quantities requiring fulfillment from the respective fulfillment order.
type FulfillmentOrderLineItem implements Node {
    # A globally-unique identifier.
    id: ID!

    # The associated order line item.
    lineItem: LineItem!

    # The number of units remaining to be fulfilled.
    remainingQuantity: Int!

    # The total number of units to be fulfilled.
    totalQuantity: Int!

    # Warning messages for a fulfillment order line item.
    warnings: [FulfillmentOrderLineItemWarning!]!
}

# A fulfillment order line item warning. For example, a warning about why a fulfillment request was rejected.
type FulfillmentOrderLineItemWarning {
    # The description of warning.
    description: String

    # The title of warning.
    title: String
}

# A location that a fulfillment order can potentially move to.
type FulfillmentOrderLocationForMove {
    # The location being considered as the fulfillment order's new assigned location.
    location: Location!

    # A human-readable string with the reason why the fulfillment order, or some of its line items, can't be
    # moved to the location.
    message: String

    # Whether the fulfillment order can be moved to the location.
    movable: Boolean!
}

# Represents a request made by the merchant to a fulfillment service for a fulfillment order.
type FulfillmentOrderMerchantRequest implements Node {
    # A globally-unique identifier.
    id: ID!

    # The kind of request made.
    kind: FulfillmentOrderMerchantRequestKind!

    # The optional message that the merchant included in the request.
    message: String

    # Additional options requested by the merchant. These depend on the kind of the request.
    # For example, for a FULFILLMENT_REQUEST, one option is notify_customer, which indicates whether the
    # merchant intends to notify the customer upon fulfillment. The fulfillment service can then set
    # notifyCustomer when making calls to FulfillmentCreateV2.
    requestOptions: JSON

    # The response from the fulfillment service.
    responseData: JSON

    # The timestamp when the request was made.
    sentAt: DateTime!
}