Third-party marketplace order and fulfillment workflow recommendations
Orders created through third-party marketplaces, like Facebook or Google, use Shopify Payments as the payment processor. The following guide explains when events are fired and what values are captured within the Order and Fulfillment records that are accessible using Shopify APIs.
Workflow details
Anchor link to section titled "Workflow details"Orders aren't created with an automatically-captured transaction. Merchants have to complete fulfillment on an order before the transaction is captured automatically and the order is marked as paid. Transaction capture is initiated by the third-party marketplace.
Orders can't be fulfilled immediately. They must be held until a period between 30 minutes and 24 hours has passed before they can be fulfilled. This is to account for buyer cancellation, payment authorization, and fraud and risk analysis.
From the time that payment is authorized until it is captured, merchants can't perform the following actions on an order:
Change the destination address
Edit the order
Issue refunds for custom amounts
Capture the payment manually
Order response
Anchor link to section titled "Order response"Use the following information from the order response to identify an order processed with Shopify Payments.
For Facebook, review the differences in the order response values for orders processed using Facebook Payments and Shopify Payments.
Field | Shopify Payments value | Facebook Payments value |
---|---|---|
financial_status |
authorized | paid |
gateway |
shopify_payments | |
payment_gateway_names |
["shopify_payments"] | ["instagram"] |
processing_method |
"direct" | "" |
source_identifier |
250736083723744,2283522795111633 | 255082969810519 |
reference |
nil | 255082969810519 |
customer_locale |
en | nil |
shipping_lines |
source: custom title: STANDARD (3-5 Business days) |
source: nil title: FB STANDARD (3-7 Business days) |
Field | Shopify Payments value | Facebook Payments value |
---|---|---|
displayFulfillmentStatus |
ON_HOLD | UNFULFILLED |
displayFinancialStatus |
AUTHORIZED | PAID |
paymentGatewayNames |
["shopify_payments"] | ["instagram"] |
Recommended workflow
Anchor link to section titled "Recommended workflow"Review the following recommendations for tracking and fulfilling orders placed through third-party marketplaces using Shopify APIs.
Use the fulfillment order API
Anchor link to section titled "Use the fulfillment order API"Use the fulfillment order API to perform fulfillment-related work.
You should use the GraphQL FulfillmentOrder
object or the REST FulfillmentOrder
resource instead of using the Fulfillment
and Order
resource separately. FulfillmentOrder
gives you more control over how you manage fulfillments. Learn how to migrate to the FulfillmentOrder resource.
Use the fulfillment order status and the order financial status to determine if an order can be fulfilled
Anchor link to section titled "Use the fulfillment order status and the order financial status to determine if an order can be fulfilled"Use the fulfillment order status and order financial status to determine if an order should be fulfilled.
You can use the fulfillment order status on the GraphQL or REST FulfillmentOrder
resource to determine if an order can be fulfilled. A fulfillment order is ready for fulfillment when its status
is set to open
. Also each FulfillmentOrder
object includes a list of supported fulfillment order actions to determine which actions it can take. Learn how to manage orders by using fulfillment order actions.
Sales channel apps for third-party marketplaces require that an order is fulfilled before payments are automatically captured by the marketplace. To prevent expiration of authorized payment, a post-order workflow shouldn't use payment captured as the condition for fulfillment. Instead, determine if an order has payment authorization (status: authorized
) and fulfillment order open (status: open
) before fulfillment. To do this, you can use the financial_status
of the REST Order
resource, or the displayFinancialStatus
of the GraphQL Order
resource.
Resource | Property | Value |
---|---|---|
Order |
financial_status |
authorized or paid |
FulfillmentOrder |
status |
open |
Object | Field | Value |
---|---|---|
Order |
displayFinancialStatus |
AUTHORIZED or PAID |
FulfillmentOrder |
status |
OPEN |
orders/updated
fulfillment_orders/ready_to_fulfill
(unstable)
Considerations
Anchor link to section titled "Considerations"You can't use
line_items#fulfillable_quantity
to determine if an order is fulfillable if the fulfillment order is on hold. The value0
is returned.Check the on hold status before you create a fulfillment following an
order/create
webhook. If you don't, then the API request fails.Avoid using a predetermined value for the on-hold time period. This value differs across marketplaces.
Avoid using
gateway
to determine if an order is created through a channel. For example, following a migration, thegateway
value of an order created on the Facebook sales channel app will change frominstagram/facebook
toshopify_payments
. Instead, usesource_name
to determine the source of an order.
Determine the source of an order
Anchor link to section titled "Determine the source of an order"Because orders placed through third-party marketplaces use Shopify Payments instead of a unique payment gateway, the gateway
value doesn't reflect the channel in which the order is created. Fields such as reference
and source_identifier
aren't guaranteed across different apps.
Orders created using the API can be assigned any of the source_name
values listed in the Partner Dashboard. Use the source_name
of an order to determine its channel source. The source_name
property can be set only during order creation. It's not writeable afterwards.
Alternatively, orders can be assigned a custom string or left unspecified:
If
source_name
is a custom string, then the order is unattributed.If
source_name
is unspecified, then new orders are assigned the value of your app's ID.
The following are Admin API resources for determining the source channel for an order:
If you're using the REST Admin API, then use the
Order
orCheckout
resources.If you're using the GraphQL Admin API, then use the
DraftOrderInput
mutation.
Untether fulfillment from order creation events
Anchor link to section titled "Untether fulfillment from order creation events"Avoid workflows that depend on the orders/create
, order_transactions/create
or order/paid
webhook events to initiate fulfillments. Instead, use the orders/updated
or the fulfillment_orders/ready_to_fulfill
events (available in the unstable version of the API) and FulfillmentOrder
response body to determine if a fulfillment order is ready for fulfillment.
Transitioning between Facebook and Shopify Payment platforms
Anchor link to section titled "Transitioning between Facebook and Shopify Payment platforms"During the transition, apps need to support both the Facebook Payments and Shopify Payments workflows.
For the transition period, we recommend determining the post-order workflow based on the gateway. Orders created through a sales channel app on a Shopify Payments-enabled store will see transactions created in an authorized state. Orders have to complete fulfillment before payment is captured automatically by the marketplace. During the transition period, create a condition check on the payment gateways value to determine the post-order workflow.