--- title: Sync orders and subscriptions description: Learn some common order management scenarios that relate to fulfillment orders and subscription contracts. source_url: html: https://shopify.dev/docs/apps/build/purchase-options/subscriptions/fulfillments/sync-orders-subscriptions md: https://shopify.dev/docs/apps/build/purchase-options/subscriptions/fulfillments/sync-orders-subscriptions.md --- ExpandOn this page * [Keeping orders and subscription contracts in sync](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/fulfillments/sync-orders-subscriptions#keeping-orders-and-subscription-contracts-in-sync) * [Order tagging](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/fulfillments/sync-orders-subscriptions#order-tagging) * [Automatic fulfillment](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/fulfillments/sync-orders-subscriptions#automatic-fulfillment) * [Order CSV export](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/fulfillments/sync-orders-subscriptions#order-csv-export) * [Order webhooks](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/fulfillments/sync-orders-subscriptions#order-webhooks) * [Next steps](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/fulfillments/sync-orders-subscriptions#next-steps) # Sync orders and subscriptions When an order is created by Shopify, and [delivery anchors](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/selling-plans#anchors) exist, the order contains delayed fulfillment orders for prepaid items. This guide describes how to keep your orders and subscription contracts in sync, and covers some common order management scenarios that relate to fulfillment orders and subscription contracts. Caution [Order editing](https://shopify.dev/docs/apps/build/orders-fulfillment/order-management-apps/edit-orders) in the Shopify admin isn't supported for orders with prepaid subscriptions. *** ## Keeping orders and subscription contracts in sync Changes to prepaid subscription contracts aren't automatically reflected on the associated orders. For example, when a customer updates their address for a prepaid subscription in an app, their address isn't automatically updated in the order. The following diagram shows the required actions that your app must take to sync updates for prepaid subscription contracts: ![Workflow for interacting with fulfillment orders and subscription contracts](https://cdn.shopify.com/shopifycloud/shopify-dev/production/assets/assets/images/api/subscriptions/app-fulfillment-orders-subscription-contract-CVlNOjSF.png) * If the item hasn't been billed for, then update the information on the subscription contract using the [`subscriptionContract`](https://shopify.dev/docs/api/admin-graphql/latest/objects/subscriptioncontract) and [`subscriptionDraft`](https://shopify.dev/docs/api/admin-graphql/latest/objects/subscriptiondraft) objects. * If the item has been billed for, then update the information on the order using the [`Order`](https://shopify.dev/docs/api/admin-graphql/latest/objects/order) and [`FulfillmentOrder`](https://shopify.dev/docs/api/admin-graphql/latest/objects/fulfillmentorder) objects. Tip Learn how to interact with the [`SubscriptionDraft`](https://shopify.dev/docs/api/admin-graphql/latest/objects/subscriptiondraft) object by completing the [Update a subscription contract](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts/update-a-subscription-contract) tutorial. ### Managing cancellations The cancellation of orders doesn't automatically cancel related subscription contracts. It's recommended that apps subscribe to the [`orders/cancel`](#order-webhooks) webhook and communicate with merchants when subscription contract orders are cancelled, so that merchants know that the subscription contract hasn't also been cancelled. #### Subscription cancellation through a customer portal When a customer cancels a subscription order through the customer portal, apps need to notify the merchant of this cancellation. If the cancellation is initiated through the app, then the app needs to handle the associated [refunds](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/fulfillments#refunds). This applies to both prepaid and subscribe-and-save subscriptions. *** ## Order tagging Merchants often identify and filter subscription orders in the Shopify admin. To tag orders for subscriptions from your app, you can call the [`tagsAdd`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/tagsadd) mutation. The following example adds tags to a specified order using the order ID: ## POST https\://{shop}.myshopify.com/admin/api/{api\_version}/graphql.json ## GraphQL mutation ```graphql mutation tagsAdd($id: ID!, $tags: [String!]!) { tagsAdd(id: $id, tags: $tags) { node { id } userErrors { field message } } } ``` ## Variables ```json { "id": "gid://shopify/Order/2067697074232", "tags": ["subscription", "prepaid"] } ``` ## JSON response ```json { "data": { "orderUpdate": { "order": { "id": "gid://shopify/Order/2067697074232" }, "userErrors": [] } } } ``` *** ## Automatic fulfillment Scheduled fulfillment orders aren't eligible for [automatic fulfillment](https://help.shopify.com/manual/checkout-settings/order-processing#automatically-fulfill-orders). However, if a prepaid subscription order is created with its first fulfillment order set to the `OPEN` state, then the fulfillment order is automatically fulfilled. *** ## Order CSV export Apps that use CSV exports to manage fulfillments can rely on the value of `lineItem.fulfillableQuantity` to determine which orders are ready to fulfill. This is because `SCHEDULED` fulfillment orders aren't included in the calculation of the order `lineItem.fulfillableQuantity`. For example, consider a fulfillment order scheduled to ship on January 15. Before January 15, `lineItem.fulfillableQuantity` is set to 0. After January 15, `lineItem.fulfillableQuantity` is set to 1. Then, after the item is fulfilled, `lineItem.fulfillableQuantity` is set back to 0. *** ## Order webhooks Your app can subscribe to order webhooks that are useful for apps that manage fulfillment orders for merchants. The following examples show the JSON responses from each of the available webhooks. To learn how to set up and consume webhooks, refer to [Webhooks configuration](https://shopify.dev/apps/webhooks/configuration). ## Example webhook responses ```json // Occurs when an order is created. Subscription apps need to query the order's line items for their selling plan to determine whether this is a subscription order that they own. { "id": 820982911946154508, "email": "jon@doe.ca", "closed_at": null, "created_at": "2022-10-03T12:55:00-04:00", "updated_at": "2022-10-03T12:55:00-04:00", "number": 234, "note": null, "token": "123456abcd", "gateway": null, "test": true, "total_price": "403.00", "subtotal_price": "393.00", "total_weight": 0, "total_tax": "0.00", "taxes_included": false, "currency": "USD", "financial_status": "voided", "confirmed": false, "total_discounts": "5.00", "total_line_items_price": "398.00", "cart_token": null, "buyer_accepts_marketing": true, "name": "#9999", "referring_site": null, "landing_site": null, "cancelled_at": "2022-10-03T12:55:00-04:00", "cancel_reason": "customer", "total_price_usd": null, "checkout_token": null, "reference": null, "user_id": null, "location_id": null, "source_identifier": null, "source_url": null, ``` ```json // Occurs when an order is updated or when a scheduled fulfillment order is transitioned to the `OPEN` state. For example, this webhook can be used to track address updates. { "id": 820982911946154508, "email": "jon@doe.ca", "closed_at": null, "created_at": "2022-10-03T12:55:00-04:00", "updated_at": "2022-10-03T12:55:00-04:00", "number": 234, "note": null, "token": "123456abcd", "gateway": null, "test": true, "total_price": "403.00", "subtotal_price": "393.00", "total_weight": 0, "total_tax": "0.00", "taxes_included": false, "currency": "USD", "financial_status": "voided", "confirmed": false, "total_discounts": "5.00", "total_line_items_price": "398.00", "cart_token": null, "buyer_accepts_marketing": true, "name": "#9999", "referring_site": null, "landing_site": null, "cancelled_at": "2022-10-03T12:55:00-04:00", "cancel_reason": "customer", "total_price_usd": null, "checkout_token": null, "reference": null, "user_id": null, "location_id": null, "source_identifier": null, "source_url": null, ``` ```json // Occurs when an order is cancelled. Subscription apps can use this webhook to ensure the related contract is cancelled as well, if that's the merchant's intention. { "id": 820982911946154508, "email": "jon@doe.ca", "closed_at": null, "created_at": "2022-10-03T12:55:00-04:00", "updated_at": "2022-10-03T12:55:00-04:00", "number": 234, "note": null, "token": "123456abcd", "gateway": null, "test": true, "total_price": "403.00", "subtotal_price": "393.00", "total_weight": 0, "total_tax": "0.00", "taxes_included": false, "currency": "USD", "financial_status": "voided", "confirmed": false, "total_discounts": "5.00", "total_line_items_price": "398.00", "cart_token": null, "buyer_accepts_marketing": true, "name": "#9999", "referring_site": null, "landing_site": null, "cancelled_at": "2022-10-03T12:55:00-04:00", "cancel_reason": "customer", "total_price_usd": null, "checkout_token": null, "reference": null, "user_id": null, "location_id": null, "source_identifier": null, "source_url": null, ``` ```json // Occurs when a refund is created. This webhook can be used to ensure contracts get updated as well, if that's the merchant's intention. { "id": 890088186047892319, "order_id": 820982911946154508, "created_at": null, "note": "Things were damaged", "user_id": 548380009, "processed_at": null, "restock": false, "duties": [ ], "total_duties_set": { "shop_money": { "amount": "0.00", "currency_code": "USD" }, "presentment_money": { "amount": "0.00", "currency_code": "USD" } }, "admin_graphql_api_id": "gid:\/\/shopify\/Refund\/890088186047892319", "refund_line_items": [ { "id": 866550311766439093, "quantity": 1, "line_item_id": 866550311766439020, "location_id": null, "restock_type": "no_restock", "subtotal": 199.0, "total_tax": 0.0, "subtotal_set": { "shop_money": { "amount": "199.00", "currency_code": "USD" ``` ##### orders/create ``` // Occurs when an order is created. Subscription apps need to query the order's line items for their selling plan to determine whether this is a subscription order that they own. { "id": 820982911946154508, "email": "jon@doe.ca", "closed_at": null, "created_at": "2022-10-03T12:55:00-04:00", "updated_at": "2022-10-03T12:55:00-04:00", "number": 234, "note": null, "token": "123456abcd", "gateway": null, "test": true, "total_price": "403.00", "subtotal_price": "393.00", "total_weight": 0, "total_tax": "0.00", "taxes_included": false, "currency": "USD", "financial_status": "voided", "confirmed": false, "total_discounts": "5.00", "total_line_items_price": "398.00", "cart_token": null, "buyer_accepts_marketing": true, "name": "#9999", "referring_site": null, "landing_site": null, "cancelled_at": "2022-10-03T12:55:00-04:00", "cancel_reason": "customer", "total_price_usd": null, "checkout_token": null, "reference": null, "user_id": null, "location_id": null, "source_identifier": null, "source_url": null, "processed_at": null, "device_id": null, "phone": null, "customer_locale": "en", "app_id": null, "browser_ip": null, "landing_site_ref": null, "order_number": 1234, "discount_applications": [ { "type": "manual", "value": "5.0", "value_type": "fixed_amount", "allocation_method": "each", "target_selection": "explicit", "target_type": "line_item", "description": "Discount", "title": "Discount" } ], "discount_codes": [ ], "note_attributes": [ ], "payment_gateway_names": [ "visa", "bogus" ], "processing_method": "", "checkout_id": null, "source_name": "web", "fulfillment_status": "pending", "tax_lines": [ ], "tags": "", "contact_email": "jon@doe.ca", "order_status_url": "https://jsmith.myshopify.com/548380009/orders/123456abcd/authenticate?key=abcdefg", "presentment_currency": "USD", "total_line_items_price_set": { "shop_money": { "amount": "398.00", "currency_code": "USD" }, "presentment_money": { "amount": "398.00", "currency_code": "USD" } }, "total_discounts_set": { "shop_money": { "amount": "5.00", "currency_code": "USD" }, "presentment_money": { "amount": "5.00", "currency_code": "USD" } }, "total_shipping_price_set": { "shop_money": { "amount": "10.00", "currency_code": "USD" }, "presentment_money": { "amount": "10.00", "currency_code": "USD" } }, "subtotal_price_set": { "shop_money": { "amount": "393.00", "currency_code": "USD" }, "presentment_money": { "amount": "393.00", "currency_code": "USD" } }, "total_price_set": { "shop_money": { "amount": "403.00", "currency_code": "USD" }, "presentment_money": { "amount": "403.00", "currency_code": "USD" } }, "total_tax_set": { "shop_money": { "amount": "0.00", "currency_code": "USD" }, "presentment_money": { "amount": "0.00", "currency_code": "USD" } }, "line_items": [ { "id": 866550311766439020, "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": 141249953214522974, "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" } } } ], "duties": [ ], "admin_graphql_api_id": "gid://shopify/LineItem/141249953214522974", "tax_lines": [ ] } ], "fulfillments": [ ], "refunds": [ ], "total_tip_received": "0.0", "original_total_duties_set": null, "current_total_duties_set": null, "payment_terms": null, "admin_graphql_api_id": "gid://shopify/Order/820982911946154508", "shipping_lines": [ { "id": 271878346596884015, "title": "Generic Shipping", "price": "10.00", "code": null, "source": "shopify", "phone": null, "requested_fulfillment_service_id": null, "delivery_category": null, "carrier_identifier": null, "discounted_price": "10.00", "price_set": { "shop_money": { "amount": "10.00", "currency_code": "USD" }, "presentment_money": { "amount": "10.00", "currency_code": "USD" } }, "discounted_price_set": { "shop_money": { "amount": "10.00", "currency_code": "USD" }, "presentment_money": { "amount": "10.00", "currency_code": "USD" } }, "discount_allocations": [ ], "tax_lines": [ ] } ], "billing_address": { "first_name": "Bob", "address1": "123 Billing Street", "phone": "555-555-BILL", "city": "Billtown", "zip": "K2P0B0", "province": "Kentucky", "country": "United States", "last_name": "Biller", "address2": null, "company": "My Company", "latitude": null, "longitude": null, "name": "Bob Biller", "country_code": "US", "province_code": "KY" }, "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" }, "customer": { "id": 115310627314723954, "email": "john@example.com", "accepts_marketing": false, "created_at": null, "updated_at": null, "first_name": "John", "last_name": "Smith", "orders_count": 0, "state": "disabled", "total_spent": "0.00", "last_order_id": null, "note": null, "verified_email": true, "multipass_identifier": null, "tax_exempt": false, "tags": "", "last_order_name": null, "currency": "USD", "phone": null, "accepts_marketing_updated_at": null, "marketing_opt_in_level": null, "sms_marketing_consent": null, "admin_graphql_api_id": "gid://shopify/Customer/115310627314723954", "default_address": { "id": 715243470612851245, "customer_id": 115310627314723954, "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 } } } ``` ##### orders/updated ``` // Occurs when an order is updated or when a scheduled fulfillment order is transitioned to the `OPEN` state. For example, this webhook can be used to track address updates. { "id": 820982911946154508, "email": "jon@doe.ca", "closed_at": null, "created_at": "2022-10-03T12:55:00-04:00", "updated_at": "2022-10-03T12:55:00-04:00", "number": 234, "note": null, "token": "123456abcd", "gateway": null, "test": true, "total_price": "403.00", "subtotal_price": "393.00", "total_weight": 0, "total_tax": "0.00", "taxes_included": false, "currency": "USD", "financial_status": "voided", "confirmed": false, "total_discounts": "5.00", "total_line_items_price": "398.00", "cart_token": null, "buyer_accepts_marketing": true, "name": "#9999", "referring_site": null, "landing_site": null, "cancelled_at": "2022-10-03T12:55:00-04:00", "cancel_reason": "customer", "total_price_usd": null, "checkout_token": null, "reference": null, "user_id": null, "location_id": null, "source_identifier": null, "source_url": null, "processed_at": null, "device_id": null, "phone": null, "customer_locale": "en", "app_id": null, "browser_ip": null, "landing_site_ref": null, "order_number": 1234, "discount_applications": [ { "type": "manual", "value": "5.0", "value_type": "fixed_amount", "allocation_method": "each", "target_selection": "explicit", "target_type": "line_item", "description": "Discount", "title": "Discount" } ], "discount_codes": [ ], "note_attributes": [ ], "payment_gateway_names": [ "visa", "bogus" ], "processing_method": "", "checkout_id": null, "source_name": "web", "fulfillment_status": "pending", "tax_lines": [ ], "tags": "", "contact_email": "jon@doe.ca", "order_status_url": "https:\/\/jsmith.myshopify.com\/548380009\/orders\/123456abcd\/authenticate?key=abcdefg", "presentment_currency": "USD", "total_line_items_price_set": { "shop_money": { "amount": "398.00", "currency_code": "USD" }, "presentment_money": { "amount": "398.00", "currency_code": "USD" } }, "total_discounts_set": { "shop_money": { "amount": "5.00", "currency_code": "USD" }, "presentment_money": { "amount": "5.00", "currency_code": "USD" } }, "total_shipping_price_set": { "shop_money": { "amount": "10.00", "currency_code": "USD" }, "presentment_money": { "amount": "10.00", "currency_code": "USD" } }, "subtotal_price_set": { "shop_money": { "amount": "393.00", "currency_code": "USD" }, "presentment_money": { "amount": "393.00", "currency_code": "USD" } }, "total_price_set": { "shop_money": { "amount": "403.00", "currency_code": "USD" }, "presentment_money": { "amount": "403.00", "currency_code": "USD" } }, "total_tax_set": { "shop_money": { "amount": "0.00", "currency_code": "USD" }, "presentment_money": { "amount": "0.00", "currency_code": "USD" } }, "line_items": [ { "id": 866550311766439020, "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": 141249953214522974, "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" } } } ], "duties": [ ], "admin_graphql_api_id": "gid:\/\/shopify\/LineItem\/141249953214522974", "tax_lines": [ ] } ], "fulfillments": [ ], "refunds": [ ], "total_tip_received": "0.0", "original_total_duties_set": null, "current_total_duties_set": null, "payment_terms": null, "admin_graphql_api_id": "gid:\/\/shopify\/Order\/820982911946154508", "shipping_lines": [ { "id": 271878346596884015, "title": "Generic Shipping", "price": "10.00", "code": null, "source": "shopify", "phone": null, "requested_fulfillment_service_id": null, "delivery_category": null, "carrier_identifier": null, "discounted_price": "10.00", "price_set": { "shop_money": { "amount": "10.00", "currency_code": "USD" }, "presentment_money": { "amount": "10.00", "currency_code": "USD" } }, "discounted_price_set": { "shop_money": { "amount": "10.00", "currency_code": "USD" }, "presentment_money": { "amount": "10.00", "currency_code": "USD" } }, "discount_allocations": [ ], "tax_lines": [ ] } ], "billing_address": { "first_name": "Bob", "address1": "123 Billing Street", "phone": "555-555-BILL", "city": "Billtown", "zip": "K2P0B0", "province": "Kentucky", "country": "United States", "last_name": "Biller", "address2": null, "company": "My Company", "latitude": null, "longitude": null, "name": "Bob Biller", "country_code": "US", "province_code": "KY" }, "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" }, "customer": { "id": 115310627314723954, "email": "john@example.com", "accepts_marketing": false, "created_at": null, "updated_at": null, "first_name": "John", "last_name": "Smith", "orders_count": 0, "state": "disabled", "total_spent": "0.00", "last_order_id": null, "note": null, "verified_email": true, "multipass_identifier": null, "tax_exempt": false, "tags": "", "last_order_name": null, "currency": "USD", "phone": null, "accepts_marketing_updated_at": null, "marketing_opt_in_level": null, "sms_marketing_consent": null, "admin_graphql_api_id": "gid:\/\/shopify\/Customer\/115310627314723954", "default_address": { "id": 715243470612851245, "customer_id": 115310627314723954, "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 } } } ``` ##### orders/cancelled ```` // Occurs when an order is cancelled. Subscription apps can use this webhook to ensure the related contract is cancelled as well, if that's the merchant's intention. { "id": 820982911946154508, "email": "jon@doe.ca", "closed_at": null, "created_at": "2022-10-03T12:55:00-04:00", "updated_at": "2022-10-03T12:55:00-04:00", "number": 234, "note": null, "token": "123456abcd", "gateway": null, "test": true, "total_price": "403.00", "subtotal_price": "393.00", "total_weight": 0, "total_tax": "0.00", "taxes_included": false, "currency": "USD", "financial_status": "voided", "confirmed": false, "total_discounts": "5.00", "total_line_items_price": "398.00", "cart_token": null, "buyer_accepts_marketing": true, "name": "#9999", "referring_site": null, "landing_site": null, "cancelled_at": "2022-10-03T12:55:00-04:00", "cancel_reason": "customer", "total_price_usd": null, "checkout_token": null, "reference": null, "user_id": null, "location_id": null, "source_identifier": null, "source_url": null, "processed_at": null, "device_id": null, "phone": null, "customer_locale": "en", "app_id": null, "browser_ip": null, "landing_site_ref": null, "order_number": 1234, "discount_applications": [ { "type": "manual", ```json "value": "5.0", "value_type": "fixed_amount", "allocation_method": "each", "target_selection": "explicit", "target_type": "line_item", "description": "Discount", "title": "Discount" } ], "discount_codes": [ ], "note_attributes": [ ], "payment_gateway_names": [ "visa", "bogus" ], "processing_method": "", "checkout_id": null, "source_name": "web", "fulfillment_status": "pending", "tax_lines": [ ], "tags": "", "contact_email": "jon@doe.ca", "order_status_url": "https://jsmith.myshopify.com/548380009/orders/123456abcd/authenticate?key=abcdefg", "presentment_currency": "USD", "total_line_items_price_set": { "shop_money": { "amount": "398.00", "currency_code": "USD" }, "presentment_money": { "amount": "398.00", "currency_code": "USD" } }, "total_discounts_set": { "shop_money": { "amount": "5.00", "currency_code": "USD" }, "presentment_money": { "amount": "5.00", "currency_code": "USD" } }, "total_shipping_price_set": { "shop_money": { "amount": "10.00", "currency_code": "USD" }, "presentment_money": { "amount": "10.00", "currency_code": "USD" } }, "subtotal_price_set": { "shop_money": { "amount": "393.00", "currency_code": "USD" }, "presentment_money": { "amount": "393.00", "currency_code": "USD" } }, "total_price_set": { "shop_money": { "amount": "403.00", "currency_code": "USD" }, "presentment_money": { "amount": "403.00", "currency_code": "USD" } }, "total_tax_set": { "shop_money": { "amount": "0.00", "currency_code": "USD" }, "presentment_money": { "amount": "0.00", "currency_code": "USD" } }, "line_items": [ { "id": 866550311766439020, "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": 141249953214522974, "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" } } } ], "duties": [ ], "admin_graphql_api_id": "gid://shopify/LineItem/141249953214522974", "tax_lines": [ ] } ], "fulfillments": [ ], "refunds": [ ], "total_tip_received": "0.0", "original_total_duties_set": null, "current_total_duties_set": null, "payment_terms": null, "admin_graphql_api_id": "gid://shopify/Order/820982911946154508", "shipping_lines": [ { "id": 271878346596884015, "title": "Generic Shipping", "price": "10.00", "code": null, "source": "shopify", "phone": null, "requested_fulfillment_service_id": null, "delivery_category": null, "carrier_identifier": null, "discounted_price": "10.00", "price_set": { "shop_money": { "amount": "10.00", "currency_code": "USD" }, "presentment_money": { "amount": "10.00", "currency_code": "USD" } }, "discounted_price_set": { "shop_money": { "amount": "10.00", "currency_code": "USD" }, "presentment_money": { "amount": "10.00", "currency_code": "USD" } }, "discount_allocations": [ ], "tax_lines": [ ] } ], "billing_address": { "first_name": "Bob", "address1": "123 Billing Street", "phone": "555-555-BILL", "city": "Billtown", "zip": "K2P0B0", "province": "Kentucky", "country": "United States", "last_name": "Biller", "address2": null, "company": "My Company", "latitude": null, "longitude": null, "name": "Bob Biller", "country_code": "US", "province_code": "KY" }, "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" }, "customer": { "id": 115310627314723954, "email": "john@example.com", "accepts_marketing": false, "created_at": null, "updated_at": null, "first_name": "John", "last_name": "Smith", "orders_count": 0, "state": "disabled", "total_spent": "0.00", "last_order_id": null, "note": null, "verified_email": true, "multipass_identifier": null, "tax_exempt": false, "tags": "", "last_order_name": null, "currency": "USD", "phone": null, "accepts_marketing_updated_at": null, "marketing_opt_in_level": null, "sms_marketing_consent": null, "admin_graphql_api_id": "gid://shopify/Customer/115310627314723954", "default_address": { "id": 715243470612851245, "customer_id": 115310627314723954, "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 } } } ```` ##### refunds/create ``` // Occurs when a refund is created. This webhook can be used to ensure contracts get updated as well, if that's the merchant's intention. { "id": 890088186047892319, "order_id": 820982911946154508, "created_at": null, "note": "Things were damaged", "user_id": 548380009, "processed_at": null, "restock": false, "duties": [ ], "total_duties_set": { "shop_money": { "amount": "0.00", "currency_code": "USD" }, "presentment_money": { "amount": "0.00", "currency_code": "USD" } }, "admin_graphql_api_id": "gid:\/\/shopify\/Refund\/890088186047892319", "refund_line_items": [ { "id": 866550311766439093, "quantity": 1, "line_item_id": 866550311766439020, "location_id": null, "restock_type": "no_restock", "subtotal": 199.0, "total_tax": 0.0, "subtotal_set": { "shop_money": { "amount": "199.00", "currency_code": "USD" }, "presentment_money": { "amount": "199.00", "currency_code": "USD" } }, "total_tax_set": { "shop_money": { "amount": "0.00", "currency_code": "USD" }, "presentment_money": { "amount": "0.00", "currency_code": "USD" } }, "line_item": { "id": 866550311766439020, "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": 141249953214523047, "quantity": 1, "line_item_id": 141249953214522974, "location_id": null, "restock_type": "no_restock", "subtotal": 199.0, "total_tax": 0.0, "subtotal_set": { "shop_money": { "amount": "199.00", "currency_code": "USD" }, "presentment_money": { "amount": "199.00", "currency_code": "USD" } }, "total_tax_set": { "shop_money": { "amount": "0.00", "currency_code": "USD" }, "presentment_money": { "amount": "0.00", "currency_code": "USD" } }, "line_item": { "id": 141249953214522974, "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" } } } ], "duties": [ ], "admin_graphql_api_id": "gid:\/\/shopify\/LineItem\/141249953214522974", "tax_lines": [ ] } } ], "transactions": [ ], "order_adjustments": [ ] } ``` Note To know when items should be fulfilled, apps should query `fulfillmentOrders` when they receive the `orders/create` webhook. If apps don't query `fulfillmentOrders` and submit a request to create fulfillments for items that shouldn't be fulfilled yet, then the request fails. *** ## Next steps * Learn about [fulfillments for prepaid subscriptions](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/fulfillments). *** * [Keeping orders and subscription contracts in sync](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/fulfillments/sync-orders-subscriptions#keeping-orders-and-subscription-contracts-in-sync) * [Order tagging](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/fulfillments/sync-orders-subscriptions#order-tagging) * [Automatic fulfillment](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/fulfillments/sync-orders-subscriptions#automatic-fulfillment) * [Order CSV export](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/fulfillments/sync-orders-subscriptions#order-csv-export) * [Order webhooks](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/fulfillments/sync-orders-subscriptions#order-webhooks) * [Next steps](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/fulfillments/sync-orders-subscriptions#next-steps)