Store API and webhooks

The Store API lets a program you run, such as a warehouse, shipping or accounting system, work with the selected team's Store. It uses an API key from API keys (see API keys and REST API); send X-Magpie-Team-Id to choose the team. A key can do in Store what its owner can: team admins can do everything, and a team member needs the matching Store permission, such as See orders to read orders or Refund and cancel orders to refund them.

Orders

• GET /api/v1/store-orders lists orders, newest first. Filter with q (order number, customer name or email), payment, fulfillment, channel, tag, from and to (dates as 2026-10-31).
• GET /api/v1/store-orders/ORDER_UUID returns the order with its items, how many of each have shipped, shipments, refunds, returns, addresses and history.
• POST /api/v1/store-orders/ORDER_UUID/fulfillments adds a shipment with carrier, tracking_number, tracking_url and the items in it. Without items, everything left to ship goes. The customer will be emailed, as when a shipment is added on the order page.
• POST /api/v1/store-orders/ORDER_UUID/refunds refunds an amount, or everything still refundable when there is no amount. Send restock_items to put items back into stock. An order paid through Stripe is refunded in your Stripe account.
• POST /api/v1/store-orders/ORDER_UUID/notes adds a note to the history, and PUT /api/v1/store-orders/ORDER_UUID/tags replaces the order's tags.

Send an Idempotency-Key header with each refund or shipment, for example a UUID your program makes. If the same request is sent again with the same key, for a day, the first answer is returned and nothing is done twice.

Orders include the customer's name, email, phone and addresses, so treat the data your program stores as customer data.

Products, stock, returns and customers

• GET /api/v1/store-products and GET /api/v1/store-products/PRODUCT_UUID return Products with every variant's price, SKU and stock.
• PATCH /api/v1/store-products/PRODUCT_UUID/variants/VARIANT_UUID changes price_amount, compare_at_amount, sku or on_hand. A new on_hand is recorded in the stock history as a count correction.
• POST .../variants/VARIANT_UUID/adjustments adds or removes stock with a reason (received, count, damaged, lost, returned or other).
• GET /api/v1/store-inventory lists variants that track stock with on hand, held for checkouts and available. Add low_stock=true for those at or below their reorder point.
• GET /api/v1/store-returns and GET /api/v1/store-customers list returns and customers; add a UUID to read one.

Discounts

These need Manage discounts.

• GET /api/v1/store-discounts lists discounts that are not archived. Filter with status (active, scheduled, expired, draft or archived) and q (name or code). GET /api/v1/store-discounts/DISCOUNT_UUID adds the products and collections it applies to and how many paid orders used it.
• POST /api/v1/store-discounts adds one. Send "method": "code" with a code, or "method": "automatic" with a title, then the other settings as on the discount's page: kind (percentage, fixed_amount, free_shipping or buy_x_get_y), percent_basis_points (1500 is 15%) or amount_off, applies_to with product_ids or collection_ids, a minimum, limits, starts_at and ends_at. It is a draft until you send "status": "active".
• PATCH /api/v1/store-discounts/DISCOUNT_UUID changes any of the same settings. If one value is refused, the answer names it and nothing is changed.
• POST /api/v1/store-discounts/DISCOUNT_UUID/deactivate archives the discount: it stops applying at checkout and keeps its history. Send "status": "active" to turn it on again.

Prices and totals are whole numbers in the smallest unit of the Store's currency: 1999 is 19.99 in dollars. Lists return up to 100 records per page.

Webhooks

A webhook sends a POST to an HTTPS address you choose when something happens in the Store. Team admins add them in Store settings › Webhooks: choose Add webhook and give a name and the address. The webhook's page opens with every event turned on and its signing secret shown once. Turn events on or off there, turn the webhook off, change its address, or choose New signing secret or Delete webhook from More. The page also lists the last 50 deliveries; Send again resends a failed one.

Webhooks can also be managed with POST /api/v1/store-webhooks, giving a name, the URL and the events:

A Store can have up to 20 webhooks. The response that adds a webhook shows its signing secret once; POST /api/v1/store-webhooks/WEBHOOK_UUID/rotate-secret replaces it.

Each POST has the headers X-Magpie-Event, X-Magpie-Id, X-Magpie-Timestamp and X-Magpie-Signature. Before using the body, compute the HMAC-SHA256 of the timestamp, a full stop and the raw body with the secret, and compare it with the v1 value in X-Magpie-Signature (t=<timestamp>,v1=<signature>). X-Magpie-Id stays the same when a webhook is sent again, so store it and ignore a repeat.

Answer with any 2xx status. Any other answer, or no answer, will be retried with longer waits over about two days; after 8 attempts the delivery fails. GET /api/v1/store-webhooks/WEBHOOK_UUID/deliveries lists each delivery and its last result, and POST .../deliveries/DELIVERY_ID/retry sends a failed one again. Turning a webhook off, or changing its URL or events, cancels what it has not received.

The full reference, with every field, is the OpenAPI file linked from /docs/api. If a webhook signature does not match or a response differs from the reference, Contact support.