Storefront Order Sync

Read and update orders, fulfillments, and refund drafts in Shopify/BigCommerce-class storefront systems through an org Integration row, keeping fulfillment status and refund paperwork current without touching customer payment data directly.

When to use

• A customer or teammate asks about the status of an order, its fulfillment, or a shipment tracking number.
• An order needs a status update, a fulfillment record created, or a refund drafted for review.
• You need to reconcile order data between the storefront platform and internal records.
• A requested change (large refund, bulk price edit, catalog write) exceeds the org's autonomous-action threshold.

Tools

• http-get — read orders, fulfillments, refund records, and catalog data from the storefront platform's REST API.
• http-post — create new records such as a fulfillment, a refund draft, or an order note.
• http-request — perform updates or deletes (PUT/PATCH/DELETE) on existing orders, fulfillments, or refund drafts.

Playbook

1. Identify the order by number or customer reference, then call http-get against the storefront's orders endpoint (e.g. GET https://{store}.myshopify.com/admin/api/2024-01/orders.json?name=#1001) to pull current status and line items.
2. If fulfillment detail is needed, call http-get on the fulfillments sub-resource (e.g. GET https://{store}.myshopify.com/admin/api/2024-01/orders/{order_id}/fulfillments.json).
3. To mark an order as shipped, call http-post to create a fulfillment record (e.g. POST https://{store}.myshopify.com/admin/api/2024-01/orders/{order_id}/fulfillments.json) with carrier and tracking details.
4. To correct an existing fulfillment or order field, call http-request with PATCH or PUT (e.g. PATCH https://{store}.myshopify.com/admin/api/2024-01/orders/{order_id}.json) rather than re-creating the record.
5. When a refund is warranted, calculate the refund amount and check it against the org's configured threshold before acting.
6. If the refund is at or above the threshold, or involves a bulk price or catalog change, stop and raise a create-task approval request describing the order, amount, and reason, and wait for a human decision — never issue the refund or write yourself.
7. If the refund is below the threshold, call http-post to create the refund draft (e.g. POST https://{store}.myshopify.com/admin/api/2024-01/orders/{order_id}/refunds.json), using calculate-then-create where the platform requires a preview call first.
8. For BigCommerce-class platforms, use the equivalent authenticated endpoints (e.g. GET/POST https://api.bigcommerce.com/stores/{store_hash}/v2/orders/{id}) via the same http-get/http-post/http-request pattern — the org Integration row supplies the correct host and auth either way.
9. After any write, re-read the affected record with http-get to confirm the change applied before reporting completion.

Failure modes

• 401/403 response or no matching Integration row for the host: stop immediately and message a human via send-message naming the service and the scopes needed — never prompt for or store credentials yourself.
• Refund amount or catalog/price change at or above the org threshold: never act autonomously; always route through a create-task approval first.
• Ambiguous order match (multiple orders with similar numbers or customer names): confirm the exact order with available identifiers before writing anything.
• Platform capability gap (e.g. a required update type isn't exposed by the API, or a needed action like manual carrier dispute isn't supported): stop and hand off to a human rather than guessing.

Done when

• The requested read is returned accurately, or the write (fulfillment, refund draft, order update) is confirmed via a follow-up read.
• Any threshold-crossing refund, price, or catalog change has a corresponding approval task and no unauthorized write occurred.
• The order's status in the storefront system reflects reality with no orphaned or duplicate fulfillment/refund records left behind.