工具

Web 开发

Web 服务

Shopify GraphQL API 学习笔记

快速入门

Shop

销售渠道

列出一个店铺的销售渠道列表（Sales Channels）

{
  publications(first: 5) {
    edges {
      node {
        id
        name
      }
    }
  }
}

在我的测试店铺中获取到 2 个销售渠道：

  • Online Store - gid://shopify/Publication/78684160251
  • Shopify GraphiQL App - gid://shopify/Publication/93448569083

查询一个销售渠道的具体数据

{
  publication(id: "gid://shopify/Publication/78684160251") {
    id
    name
  }
}

可以获得发布于这个销售渠道的：

  • collections
  • products

将产品发布到一个销售渠道

只有 Shopify Plus 店铺才有这个 API 权限，且：

  • 有 write_publications 权限

  • 有 Storefront API product_listings 的可读权限

  • productPublish

不推荐使用的 API，需要 Shopify Plus 店铺且有 write_publications 权限。

Collection

查询店铺前 5 个 Collections 数据：

{
  collections(first: 5) {
    edges {
      node {
        id
        handle
        productsCount
      }
    }
  }
}

查询店铺前 5 个 Collections 的前 5 个产品数据（一共最多获得 25 个产品数据）：

{
  collections(first: 5) {
    edges {
      node {
        id
        handle
        productsCount
        products(first: 5) {
          edges {
            node {
              id
              handle
            }
          }
        }
      }
    }
  }
}

查询店铺前 3 个 Collections 的前 3 个产品以及每个产品的前 3 个变体（一共最多获得 9 个变体数据）：

{
  collections(first: 3) {
    edges {
      node {
        id
        handle
        productsCount
        products(first: 3) {
          edges {
            node {
              id
              handle
              variants(first: 3) {
                edges {
                  node {
                    id
                    sku
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

查询一个 Collection 下的产品列表：

{
  collection(id: "gid://shopify/Collection/70598819862") {
    title
    handle
    products(first: 3) {
      edges {
        node {
          id
          title
          handle
        }
      }
    }
  }
}

Product

查询一个产品所属的 Collections

{
  product(id: "gid://shopify/Product/1974208299030") {
    collections(first: 30) {
      edges {
        node {
          id
          handle
        }
      }
    }
  }
}

SEO

更新 SEO 字段：

mutation {
  productUpdate(input: {
    id: "gid://shopify/Product/7812042391803", 
    seo: {
      title: "SEO title for 7812042391803",
      description: "SEO description for 7812042391803",
    }
  }) {
    product {
      id
      seo {
        title
        description
      }
    }
  }
}

产品类别 Category

每个产品都有一个产品类别（Product Category）和一个产品类型（Product Type）。

获取产品类别：

{
  products(first:3){
    edges {
      node {
        id
        productCategory {
          productTaxonomyNode {
            id
            fullName
          }
        }
      }
    }
  }
}

更新产品类别：

mutation {
  productUpdate(input: {
    id: "gid://shopify/Product/7812042391803", 
    productCategory: {
      productTaxonomyNodeId: "gid://shopify/ProductTaxonomyNode/5260"
    }
  }) {
    product {
      id
      handle
      productCategory {
        productTaxonomyNode {
          id
          fullName
        }
      }
    }
  }
}

将产品加入 Collection

将产品加入手工维护的 Collection

mutation {
  productUpdate(input: {
    id: "gid://shopify/Product/7812042391803", 
    collectionsToJoin: "gid://shopify/Collection/405028700411",
  }) {
    product {
      id
      collections(first: 3) {
        edges {
          node {
            id
            handle
          }
        }
      }
    }
  }
}

通过添加标签加入 Smart Collection

mutation {
  productUpdate(input: {
    id: "gid://shopify/Product/7812042391803", 
    tags: "auto-test",
  }) {
    product {
      id
      collections(first: 3) {
        edges {
          node {
            id
            handle
          }
        }
      }
    }
  }
}

选项、变体与库存

一个产品可以有多个选项（Options），如颜色、尺码、材料等。不同的选项组合形成产品变体（Variants）。

  • 产品 Product
    • 选项 Options
    • 变体 Variants
      • SKU
      • 选项组合 selectedOptions
      • 数量 inventoryQuantity
      • 库存 inventoryItem
        • HS 编码 harmonizedSystemCode

查询一个产品的选项与变体数据：

{
  product(id: "gid://shopify/Product/1974208299030") {
    handle
    options {
      id
      name
      values
    }
    variants(first: 2) {
      edges {
        node {
          id
          displayName
          sku
          inventoryQuantity
          selectedOptions {
            name
            value
          }
        }
      }
    }
  }
}

HS 编码

查询一个产品的 HS 编码 — 查询路径是产品 - 变体 - 库存 - HS：

{
  product(id: "gid://shopify/Product/1974208299030") {
    variants(first: 5) {
      edges {
        node {
          inventoryItem {
            harmonizedSystemCode
          }
        }
      }
    }
  }
}

Inventory

获取库存产品

{
  inventoryItems(first: 3) {
    edges {
      node {
        id
      }
    }
  }
}

获取库存在各个仓库的库存数量 — available 存储了各个仓库的库存值（可能为负数）：

{
  inventoryItems(first: 3) {
    edges {
      node {
        id
        variant {
          id
          product {
            id
            handle
          }
        }
        inventoryLevels(first: 3) {
          edges {
            node {
              id
              available
              location {
                id
                address {
                  city
                }
              }
            }
          }
        }
      }
    }
  }
}

在测试环境中，我们获取到以下 InventoryItem ID：

  • gid://shopify/InventoryItem/19848949301270
  • gid://shopify/InventoryItem/19848949334038
  • gid://shopify/InventoryItem/19848949366806

以及如下 Location ID：

  • gid://shopify/Location/17285971990

通过 InventoryItem ID 和 Location ID 的组合，即可查询到具体仓库的目标产品数量，如：

{
  inventoryItem(id: "gid://shopify/InventoryItem/19848949301270") {
    variant {
      inventoryQuantity
    }
    inventoryLevel(locationId: "gid://shopify/Location/17285971990") {
      available
    }
  }
}

注意，variant - inventoryQuantity 表示产品变体的库存值，它的值是通过所有 Location 的 available 求和计算而来。

Order

LineItem

当一个订单生成后，包含在一个具体订单里的变体数据。

{
  order(id: "gid://shopify/Order/5003857068283") {
    lineItems(first: 3) {
      edges {
        node {
          id
          title
          sku
          quantity
          variant {
            selectedOptions {
              name
              value
            }
          }
        }
      }
    }
  }
}

以上获取到的数据：

  • LineItem - gid://shopify/LineItem/12714633101563

FulfillmentOrder

当一个订单生成后，就会自动生成一个对应的 FulfillmentOrder 履约订单。在实际操作中，一个订单会可能会对应多个 FulfillmentOrder，例如：

  • 一个订单拆分为多个包裹发送，每个包裹对应一个 FulfillmentOrder
  • 订单状态发生变化时可能生成新的 FulfillmentOrder，例如订单从 Archive 状态回退到 Active 状态

查询目标订单的 FulfillmentOrder 数据：

{
  order(id: "gid://shopify/Order/5003857068283") {
    displayFulfillmentStatus
    fulfillmentOrders(first: 10) {
      edges {
        node {
          id
          fulfillments(first: 10) {
            edges {
              node {
                id
                location {
                  id
                  name
                }
                service {
                  serviceName
                }
                trackingInfo {
                  number
                  company
                }
              }
            }
          }
          lineItems(first: 10) {
            edges {
              node {
                id
                totalQuantity
                lineItem {
                  id
                  title
                  quantity
                  name
                  sku
                  variant {
                    title
                    selectedOptions {
                      name
                      value
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

以上获取到的数据：

  • FulfillmentOrder - gid://shopify/FulfillmentOrder/6068263977211
    • fulfillments - gid://shopify/Fulfillment/4476508373243
      • location - gid://shopify/Location/66597421307
      • service - serviceName - Manual
      • trackingInfo - number - EV007047131CN
    • lineItems - gid://shopify/FulfillmentOrderLineItem/12865561624827
      • lineItem - gid://shopify/LineItem/12714633101563

Fulfillment - 履约

Fulfillment 的含义是履约或发货。

Ecommerce fulfillment is the entire process of picking, packing, and shipping products to customers. It includes maintaining inventory, locating products within storage, packaging products, and managing the logistics of delivery.

Fulfillment methods 发货方式

  • 自己发货
    • 手动发货 Manual fulfillment
    • 自动发货 Automatic fulfillment
  • 使用第三方发货服务 Fulfillment services
    • 与 Shopify 集成的发货服务 Fulfillment services that integrate with Shopify
      • Dropshipping apps
      • Print-on-demand apps
    • 自定义发货服务 Custom fulfillment services
  • 综合使用以上两种方式

自定义发货服务 Custom fulfillment services 实际上比较少见，卖家在 Settings - Shipping and delivery - Custom order fulfillment 中添加一个履约服务商的邮箱账户。当你将订单状态修改为「已发货」时，Shopify 会给履约服务商发送一封邮件，对方在收到邮件后完成发货服务。

Fulfillment API 发布说明

自 2022-07 起，早期的 Order 和 Fulfillment 的发货方式将不再支持，你应该用新的 FulfillmentOrder API。

Shipping

Shopify 有几组 API 提供运输服务：

  • Fulfillment API - 履约服务，例如客户下单后 Shopify 通过 Fulfillment API 通知 APP
  • Carrier API - 承运人服务，例如各个运输方式的运费等，可能由 EMS, FedDex, UPS, USPS, Royal Mail 等运输服务商提供

DeliveryParticipant

A participant defines carrier-calculated rates for shipping services with a possible merchant-defined fixed fee or a percentage-of-rate fee.

–

查看店铺可以运输到的国家：

{
  shop {
    shipsToCountries
    countriesInShippingZones {
      countryCodes
    }
  }
}

查看店铺支持的运输服务 — 店铺的仓库：

{
  shop {
    fulfillmentServices {
      id
      handle
      serviceName
      location {
        name
      }
    }
  }
}
  • location - 表明从哪里发货
  • 卖家自发货的 ID - gid://shopify/FulfillmentService/manual

查看店铺支持的运输方式（如 EMS、DHL、Fedex 等）

{
  deliveryProfiles(first: 2) {
    edges {
      node {
        profileLocationGroups {
          locationGroupZones(first: 2) {
            edges {
              node {
                methodDefinitions(first: 2) {
                  edges {
                    node {
                      id
                      name
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Fulfillment

查询运单信息：

{
  orders(first: 1) {
    edges {
      node {
        id
        fulfillments(first: 50) {
          id
          name
          status
          service {
            id
            location {
              id
            }
          }
          trackingInfo {
            number
            company
          }
        }
      }
    }
  }
}

这里获取到的主要信息：

  • Order - gid://shopify/Order/4621561266427
  • Fulfillment
    • gid://shopify/Fulfillment/4204182405371
    • gid://shopify/Fulfillment/4203943035131
    • gid://shopify/Fulfillment/4203418452219
    • gid://shopify/Fulfillment/4203386044667
    • gid://shopify/Fulfillment/4200556003579
    • gid://shopify/Fulfillment/4200555446523
  • FulfillmentService - gid://shopify/FulfillmentService/manual
  • trackingInfo - number - EV006047541CN

查询指定运单：

{
  fulfillment(id: "gid://shopify/Fulfillment/4204182405371") {
    id
    status
    order {
      id
    }
    trackingInfo {
      number
      company
    }
  }
}

更新运单号：

mutation {
  fulfillmentTrackingInfoUpdateV2(
    fulfillmentId: "gid://shopify/Fulfillment/4204182405371"
  	trackingInfoInput: {
      number: "EV006047542CN"
    }) {
    fulfillment {
      trackingInfo {
        number
      }
    }
  }
}