# 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.