Shopify Triggers & Events

You can use these triggers to start a job when a Shopify event occurs.

---

Triggers

All triggers can be create folllowing the same pattern:

shopify.on("topic")

topic · string

The webhook topic you want to subscribe to. Generally a pattern of <resource>/<action>.

Helpers

The filter() method returns a new trigger with the applied payload filter:

const trigger = shopify.on("topic").filter(filter)

filter · EventFilter · required

A filter to apply to the event. See our EventFilter guide.

Events

What follows is a small selection of webhook topics and associated payloads. A complete list of possible topic names and payloads can be found here.

fulfillments/create

Occurs when a fulfillment is created. Official Shopify docs.

usage.ts

client.defineJob({
  id: "<my-id>",
  name: "<my-job-name>",
  version: "0.1.0",
  trigger: shopify.on("fulfillments/create"),
  run: async (payload, io, ctx) => {
    // Add tasks here
  },
});

'fulfillments/create' example payload

{
  "id": 123456,
  "order_id": 820982911946154500,
  "status": "pending",
  "created_at": "2021-12-31T19:00:00-05:00",
  "service": null,
  "updated_at": "2021-12-31T19:00:00-05:00",
  "tracking_company": "UPS",
  "shipment_status": null,
  "location_id": null,
  "origin_address": null,
  "email": "[e-mail]",
  "destination": {
    "first_name": "Steve",
    "address1": "123 Shipping Street",
    "phone": "555-555-SHIP",
    "city": "Shippington",
    "zip": "40003",
    "province": "Kentucky",
    "country": "United States",
    "last_name": "Shipper",
    "address2": null,
    "company": "Shipping Company",
    "latitude": null,
    "longitude": null,
    "name": "Steve Shipper",
    "country_code": "US",
    "province_code": "KY"
  },
  "line_items": [
    {
      "id": 866550311766439000,
      "variant_id": 808950810,
      "title": "IPod Nano - 8GB",
      "quantity": 1,
      "sku": "IPOD2008PINK",
      "variant_title": null,
      "vendor": null,
      "fulfillment_service": "manual",
      "product_id": 632910392,
      "requires_shipping": true,
      "taxable": true,
      "gift_card": false,
      "name": "IPod Nano - 8GB",
      "variant_inventory_management": "shopify",
      "properties": [],
      "product_exists": true,
      "fulfillable_quantity": 1,
      "grams": 567,
      "price": "199.00",
      "total_discount": "0.00",
      "fulfillment_status": null,
      "price_set": {
        "shop_money": {
          "amount": "199.00",
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": "199.00",
          "currency_code": "USD"
        }
      },
      "total_discount_set": {
        "shop_money": {
          "amount": "0.00",
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": "0.00",
          "currency_code": "USD"
        }
      },
      "discount_allocations": [],
      "duties": [],
      "admin_graphql_api_id": "gid://shopify/LineItem/866550311766439020",
      "tax_lines": []
    },
    {
      "id": 141249953214522980,
      "variant_id": 808950810,
      "title": "IPod Nano - 8GB",
      "quantity": 1,
      "sku": "IPOD2008PINK",
      "variant_title": null,
      "vendor": null,
      "fulfillment_service": "manual",
      "product_id": 632910392,
      "requires_shipping": true,
      "taxable": true,
      "gift_card": false,
      "name": "IPod Nano - 8GB",
      "variant_inventory_management": "shopify",
      "properties": [],
      "product_exists": true,
      "fulfillable_quantity": 1,
      "grams": 567,
      "price": "199.00",
      "total_discount": "5.00",
      "fulfillment_status": null,
      "price_set": {
        "shop_money": {
          "amount": "199.00",
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": "199.00",
          "currency_code": "USD"
        }
      },
      "total_discount_set": {
        "shop_money": {
          "amount": "5.00",
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": "5.00",
          "currency_code": "USD"
        }
      },
      "discount_allocations": [
        {
          "amount": "5.00",
          "discount_application_index": 0,
          "amount_set": {
            "shop_money": {
              "amount": "5.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "5.00",
              "currency_code": "USD"
            }
          }
        },
        {
          "amount": "5.00",
          "discount_application_index": 2,
          "amount_set": {
            "shop_money": {
              "amount": "5.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "5.00",
              "currency_code": "USD"
            }
          }
        }
      ],
      "duties": [],
      "admin_graphql_api_id": "gid://shopify/LineItem/141249953214522974",
      "tax_lines": []
    }
  ],
  "tracking_number": "1z827wk74630",
  "tracking_numbers": ["1z827wk74630"],
  "tracking_url": "https://www.ups.com/WebTracking?loc=en_US&requester=ST&trackNums=1z827wk74630",
  "tracking_urls": [
    "https://www.ups.com/WebTracking?loc=en_US&requester=ST&trackNums=1z827wk74630"
  ],
  "receipt": {},
  "name": "#9999.1",
  "admin_graphql_api_id": "gid://shopify/Fulfillment/123456"
}

inventory_items/update

Occurs when an inventory item is updated. Official Shopify docs.

usage.ts

client.defineJob({
  id: "<my-id>",
  name: "<my-job-name>",
  version: "0.1.0",
  trigger: shopify.on("inventory_items/update"),
  run: async (payload, io, ctx) => {
    // Add tasks here
  },
});

'inventory_items/update' example payload

{
  "id": 271878346596884000,
  "sku": "example-sku",
  "created_at": "2021-12-31T19:00:00-05:00",
  "updated_at": "2021-12-31T19:00:00-05:00",
  "requires_shipping": true,
  "cost": null,
  "country_code_of_origin": null,
  "province_code_of_origin": null,
  "harmonized_system_code": null,
  "tracked": true,
  "country_harmonized_system_codes": [],
  "admin_graphql_api_id": "gid://shopify/InventoryItem/271878346596884015"
}

orders/delete

Occurs when a order is deleted. Official Shopify docs.

usage.ts

client.defineJob({
  id: "<my-id>",
  name: "<my-job-name>",
  version: "0.1.0",
  trigger: shopify.on("orders/delete"),
  run: async (payload, io, ctx) => {
    // Add tasks here
  },
});

'orders/delete' example payload

{
  "id": 820982911946154500
}

orders/paid

Occurs when an order is paid. Official Shopify docs.

usage.ts

client.defineJob({
  id: "<my-id>",
  name: "<my-job-name>",
  version: "0.1.0",
  trigger: shopify.on("orders/paid"),
  run: async (payload, io, ctx) => {
    // Add tasks here
  },
});

'orders/paid' example payload

{
  "id": 820982911946154500,
  "admin_graphql_api_id": "gid://shopify/Order/820982911946154508",
  "app_id": null,
  "browser_ip": null,
  "buyer_accepts_marketing": true,
  "cancel_reason": "customer",
  "cancelled_at": "2021-12-31T19:00:00-05:00",
  "cart_token": null,
  "checkout_id": null,
  "checkout_token": null,
  "client_details": null,
  "closed_at": null,
  "confirmation_number": null,
  "confirmed": false,
  "contact_email": "[e-mail]",
  "created_at": "2021-12-31T19:00:00-05:00",
  "currency": "USD",
  "current_subtotal_price": "398.00",
  "current_subtotal_price_set": {
    "shop_money": {
      "amount": "398.00",
      "currency_code": "USD"
    },
    "presentment_money": {
      "amount": "398.00",
      "currency_code": "USD"
    }
  },
  "current_total_additional_fees_set": null,
  "current_total_discounts": "0.00",
  "current_total_discounts_set": {
    "shop_money": {
      "amount": "0.00",
      "currency_code": "USD"
    },
    "presentment_money": {
      "amount": "0.00",
      "currency_code": "USD"
    }
  },
  "current_total_duties_set": null,
  "current_total_price": "398.00",
  "current_total_price_set": {
    "shop_money": {
      "amount": "398.00",
      "currency_code": "USD"
    },
    "presentment_money": {
      "amount": "398.00",
      "currency_code": "USD"
    }
  },
  "current_total_tax": "0.00",
  "current_total_tax_set": {
    "shop_money": {
      "amount": "0.00",
      "currency_code": "USD"
    },
    "presentment_money": {
      "amount": "0.00",
      "currency_code": "USD"
    }
  },
  "customer_locale": "en",
  "device_id": null,
  "discount_codes": [],
  "email": "[e-mail]",
  "estimated_taxes": false,
  "financial_status": "voided",
  "fulfillment_status": "pending",
  "landing_site": null,
  "landing_site_ref": null,
  "location_id": null,
  "merchant_of_record_app_id": null,
  "name": "#9999",
  "note": null,
  "note_attributes": [],
  "number": 234,
  "order_number": 1234,
  "order_status_url": "https://jsmith.myshopify.com/548380009/orders/123456abcd/authenticate?key=abcdefg",
  "original_total_additional_fees_set": null,
  "original_total_duties_set": null,
  "payment_gateway_names": [
    "visa",
    "bogus"
  ],
  "phone": null,
  "po_number": null,
  "presentment_currency": "USD",
  "processed_at": null,
  "reference": null,
  "referring_site": null,
  "source_identifier": null,
  "source_name": "web",
  "source_url": null,
  "subtotal_price": "388.00",
  "subtotal_price_set": {
    "shop_money": {
      "amount": "388.00",
      "currency_code": "USD"
    },
    "presentment_money": {
      "amount": "388.00",
      "currency_code": "USD"
    }
  },
  "tags": "",
  "tax_exempt": false,
  "tax_lines": [],
  "taxes_included": false,
  "test": true,
  "token": "123456abcd",
  "total_discounts": "20.00",
  "total_discounts_set": {
    "shop_money": {
      "amount": "20.00",
      "currency_code": "USD"
    },
    "presentment_money": {
      "amount": "20.00",
      "currency_code": "USD"
    }
  },
  "total_line_items_price": "398.00",
  "total_line_items_price_set": {
    "shop_money": {
      "amount": "398.00",
      "currency_code": "USD"
    },
    "presentment_money": {
      "amount": "398.00",
      "currency_code": "USD"
    }
  },
  "total_outstanding": "398.00",
  "total_price": "388.00",
  "total_price_set": {
    "shop_money": {
      "amount": "388.00",
      "currency_code": "USD"
    },
    "presentment_money": {
      "amount": "388.00",
      "currency_code": "USD"
    }
  },
  "total_shipping_price_set": {
    "shop_money": {
      "amount": "10.00",
      "currency_code": "USD"
    },
    "presentment_money": {
      "amount": "10.00",
      "currency_code": "USD"
    }
  },
  "total_tax": "0.00",
  "total_tax_set": {
    "shop_money": {
      "amount": "0.00",
      "currency_code": "USD"
    },
    "presentment_money": {
      "amount": "0.00",
      "currency_code": "USD"
    }
  },
  "total_tip_received": "0.00",
  "total_weight": 0,
  "updated_at": "2021-12-31T19:00:00-05:00",
  "user_id": null,
  "billing_address": {
    "first_name": "Steve",
    "address1": "123 Shipping Street",
    "phone": "555-555-SHIP",
    "city": "Shippington",
    "zip": "40003",
    "province": "Kentucky",
    "country": "United States",
    "last_name": "Shipper",
    "address2": null,
    "company": "Shipping Company",
    "latitude": null,
    "longitude": null,
    "name": "Steve Shipper",
    "country_code": "US",
    "province_code": "KY"
  },
  "customer": {
    "id": 115310627314723950,
    "email": "[e-mail]",
    "accepts_marketing": false,
    "created_at": null,
    "updated_at": null,
    "first_name": "John",
    "last_name": "Smith",
    "state": "disabled",
    "note": null,
    "verified_email": true,
    "multipass_identifier": null,
    "tax_exempt": false,
    "phone": null,
    "email_marketing_consent": {
      "state": "not_subscribed",
      "opt_in_level": null,
      "consent_updated_at": null
    },
    "sms_marketing_consent": null,
    "tags": "",
    "currency": "USD",
    "accepts_marketing_updated_at": null,
    "marketing_opt_in_level": null,
    "tax_exemptions": [],
    "admin_graphql_api_id": "gid://shopify/Customer/115310627314723954",
    "default_address": {
      "id": 715243470612851200,
      "customer_id": 115310627314723950,
      "first_name": null,
      "last_name": null,
      "company": null,
      "address1": "123 Elm St.",
      "address2": null,
      "city": "Ottawa",
      "province": "Ontario",
      "country": "Canada",
      "zip": "K2H7A8",
      "phone": "123-123-1234",
      "name": "",
      "province_code": "ON",
      "country_code": "CA",
      "country_name": "Canada",
      "default": true
    }
  },
  "discount_applications": [],
  "fulfillments": [],
  "line_items": [
    {
      "id": 866550311766439000,
      "admin_graphql_api_id": "gid://shopify/LineItem/866550311766439020",
      "attributed_staffs": [
        {
          "id": "gid://shopify/StaffMember/902541635",
          "quantity": 1
        }
      ],
      "fulfillable_quantity": 1,
      "fulfillment_service": "manual",
      "fulfillment_status": null,
      "gift_card": false,
      "grams": 567,
      "name": "IPod Nano - 8GB",
      "price": "199.00",
      "price_set": {
        "shop_money": {
          "amount": "199.00",
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": "199.00",
          "currency_code": "USD"
        }
      },
      "product_exists": true,
      "product_id": 632910392,
      "properties": [],
      "quantity": 1,
      "requires_shipping": true,
      "sku": "IPOD2008PINK",
      "taxable": true,
      "title": "IPod Nano - 8GB",
      "total_discount": "0.00",
      "total_discount_set": {
        "shop_money": {
          "amount": "0.00",
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": "0.00",
          "currency_code": "USD"
        }
      },
      "variant_id": 808950810,
      "variant_inventory_management": "shopify",
      "variant_title": null,
      "vendor": null,
      "tax_lines": [],
      "duties": [],
      "discount_allocations": []
    },
    {
      "id": 141249953214522980,
      "admin_graphql_api_id": "gid://shopify/LineItem/141249953214522974",
      "attributed_staffs": [],
      "fulfillable_quantity": 1,
      "fulfillment_service": "manual",
      "fulfillment_status": null,
      "gift_card": false,
      "grams": 567,
      "name": "IPod Nano - 8GB",
      "price": "199.00",
      "price_set": {
        "shop_money": {
          "amount": "199.00",
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": "199.00",
          "currency_code": "USD"
        }
      },
      "product_exists": true,
      "product_id": 632910392,
      "properties": [],
      "quantity": 1,
      "requires_shipping": true,
      "sku": "IPOD2008PINK",
      "taxable": true,
      "title": "IPod Nano - 8GB",
      "total_discount": "0.00",
      "total_discount_set": {
        "shop_money": {
          "amount": "0.00",
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": "0.00",
          "currency_code": "USD"
        }
      },
      "variant_id": 808950810,
      "variant_inventory_management": "shopify",
      "variant_title": null,
      "vendor": null,
      "tax_lines": [],
      "duties": [],
      "discount_allocations": []
    }
  ],
  "payment_terms": null,
  "refunds": [],
  "shipping_address": {
    "first_name": "Steve",
    "address1": "123 Shipping Street",
    "phone": "555-555-SHIP",
    "city": "Shippington",
    "zip": "40003",
    "province": "Kentucky",
    "country": "United States",
    "last_name": "Shipper",
    "address2": null,
    "company": "Shipping Company",
    "latitude": null,
    "longitude": null,
    "name": "Steve Shipper",
    "country_code": "US",
    "province_code": "KY"
  },
  "shipping_lines": [
    {
      "id": 271878346596884000,
      "carrier_identifier": null,
      "code": null,
      "discounted_price": "10.00",
      "discounted_price_set": {
        "shop_money": {
          "amount": "10.00",
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": "10.00",
          "currency_code": "USD"
        }
      },
      "phone": null,
      "price": "10.00",
      "price_set": {
        "shop_money": {
          "amount": "10.00",
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": "10.00",
          "currency_code": "USD"
        }
      },
      "requested_fulfillment_service_id": null,
      "source": "shopify",
      "title": "Generic Shipping",
      "tax_lines": [],
      "discount_allocations": []
    }
  ]
}

products/create

Occurs when a product is created. Official Shopify docs.

usage.ts

client.defineJob({
  id: "<my-id>",
  name: "<my-job-name>",
  version: "0.1.0",
  trigger: shopify.on("products/create"),
  run: async (payload, io, ctx) => {
    // Add tasks here
  },
});

'products/create' example payload

{
  "admin_graphql_api_id": "gid://shopify/Product/788032119674292922",
  "body_html": "An example T-Shirt",
  "created_at": null,
  "handle": "example-t-shirt",
  "id": 788032119674292900,
  "product_type": "Shirts",
  "published_at": "2021-12-31T19:00:00-05:00",
  "template_suffix": null,
  "title": "Example T-Shirt",
  "updated_at": "2021-12-31T19:00:00-05:00",
  "vendor": "Acme",
  "status": "active",
  "published_scope": "web",
  "tags": "example, mens, t-shirt",
  "variants": [
    {
      "admin_graphql_api_id": "gid://shopify/ProductVariant/642667041472713922",
      "barcode": null,
      "compare_at_price": "24.99",
      "created_at": null,
      "fulfillment_service": "manual",
      "id": 642667041472714000,
      "inventory_management": "shopify",
      "inventory_policy": "deny",
      "position": 0,
      "price": "19.99",
      "product_id": 788032119674292900,
      "sku": "example-shirt-s",
      "taxable": true,
      "title": "",
      "updated_at": null,
      "option1": "Small",
      "option2": null,
      "option3": null,
      "grams": 200,
      "image_id": null,
      "weight": 200,
      "weight_unit": "g",
      "inventory_item_id": null,
      "inventory_quantity": 75,
      "old_inventory_quantity": 75,
      "requires_shipping": true
    },
    {
      "admin_graphql_api_id": "gid://shopify/ProductVariant/757650484644203962",
      "barcode": null,
      "compare_at_price": "24.99",
      "created_at": null,
      "fulfillment_service": "manual",
      "id": 757650484644203900,
      "inventory_management": "shopify",
      "inventory_policy": "deny",
      "position": 0,
      "price": "19.99",
      "product_id": 788032119674292900,
      "sku": "example-shirt-m",
      "taxable": true,
      "title": "",
      "updated_at": null,
      "option1": "Medium",
      "option2": null,
      "option3": null,
      "grams": 200,
      "image_id": null,
      "weight": 200,
      "weight_unit": "g",
      "inventory_item_id": null,
      "inventory_quantity": 50,
      "old_inventory_quantity": 50,
      "requires_shipping": true
    }
  ],
  "options": [],
  "images": [],
  "image": null
}

products/delete

Occurs when a product is deleted. Official Shopify docs.

usage.ts

client.defineJob({
  id: "<my-id>",
  name: "<my-job-name>",
  version: "0.1.0",
  trigger: shopify.on("products/delete"),
  run: async (payload, io, ctx) => {
    // Add tasks here
  },
});

'products/delete' example payload

{
  "id": 1
}

subscription_billing_attempts/failure

Occurs when a subscription billing attempt has failed. Official Shopify docs.

usage.ts

client.defineJob({
  id: "<my-id>",
  name: "<my-job-name>",
  version: "0.1.0",
  trigger: shopify.on("subscription_billing_attempts/failure"),
  run: async (payload, io, ctx) => {
    // Add tasks here
  },
});

'subscription_billing_attempts/failure' example payload

{
  "id": null,
  "admin_graphql_api_id": null,
  "idempotency_key": "9a453d81-d41d-403e-806f-714dee215ff9",
  "order_id": 1,
  "admin_graphql_api_order_id": "gid://shopify/Order/1",
  "subscription_contract_id": 9251185925,
  "admin_graphql_api_subscription_contract_id": "gid://shopify/SubscriptionContract/9251185925",
  "ready": true,
  "error_message": null,
  "error_code": null
}