Store
Work with your Store's orders, Products, stock and discounts from your own systems.
The Store API lets a program you run, such as a warehouse, shipping or accounting system, read orders and add shipments and refunds, change prices and stock, read returns and customers, and create discounts. Webhooks send a signed POST to an address you choose when an order is paid, shipped, refunded or canceled, a Product or its stock changes, or a customer asks for a return.
Get started freeAPI keys and Store permissions
Each request includes an API key. API keys need Pro on the account of the person who creates them, and a key's secret is shown once. The X-Magpie-Team-Id header chooses which of that person's teams the request works in.
A key can do in Store what the person who created it can. Team admins can do everything; another member needs the Store permission for each kind of request, which an admin gives one at a time.
- See orders
- List and read orders and returns.
- Ship and edit orders
- Add shipments, notes and tags.
- Refund and cancel orders
- Refund orders.
- Manage products and Manage stock
- Read Products and change prices and SKUs; set stock and record stock changes.
- Manage customers and Manage discounts
- Read customers; list, create, change and deactivate discounts.
- Webhooks
- Only team admins can add and change webhooks.
Orders
- List and read
- List orders newest first, filtered by search text, payment, fulfillment, sales channel, tag and dates. One order comes with its items, how many of each have shipped, shipments, refunds, returns, addresses and history.
- Add a shipment
- Send the carrier, tracking number and link, and the items in it, or leave the items out to ship everything left. The customer will be emailed, as when a shipment is added on the order's page.
- Refund
- Refund an amount, or everything still refundable, and choose items to put back into stock. An order paid through Stripe will be refunded in your Stripe account.
- Sent once
- With an Idempotency-Key header on a refund or shipment, a repeated request returns the first answer and is not carried out twice.
Products, stock, returns and customers
- Products and prices
- Read each Product with every variant's price, SKU and stock, and change a variant's price, compare-at price or SKU.
- Stock changes
- Set a variant's units on hand, recorded in its stock history as a count correction, or add or remove stock with a reason: received, count, damaged, lost, returned or other. Stock received can include its cost per item, and a change can name a stock location.
- Low stock
- The inventory list gives units on hand, held for checkouts and available for each variant that tracks stock, or only those at or below their reorder point.
- Returns and customers
- Read return requests, and customers with their order count, spending, tags and marketing consent.
Discounts
Create and change discounts with the same settings as a discount's page in Store.
- A code or automatic
- A discount is a code buyers enter, or an automatic discount with a title.
- Kinds and limits
- A percentage, a fixed amount, free shipping, or buy X get Y, on everything or on chosen Products or collections, with a minimum, usage limits, a customer segment, and start and end dates.
- Draft until active
- A new discount is a draft until it is sent with the active status. If one value in a change is refused, the answer names it and nothing is changed.
- Deactivate
- Deactivating archives a discount: it stops applying at checkout and keeps its history.
Webhook events
A webhook sends a POST to an HTTPS address when something happens in the Store. Team admins add webhooks in Store settings, with no API key needed, or through the API, up to 20 for a Store, and choose the events each one receives.
- store.order.paid
- An order is paid, online or recorded by hand.
- store.order.fulfilled
- A shipment is added, once for each shipment.
- store.order.ready_for_pickup
- A pickup order is marked ready for pickup.
- store.order.refunded and store.order.canceled
- A refund succeeds, or an unpaid order is canceled.
- store.product.updated
- A Product or its prices change.
- store.stock.low
- A variant's stock reaches its reorder point.
- store.return.requested
- A customer asks to return items.
Signatures, retries and the delivery log
Each POST has the headers X-Magpie-Event, X-Magpie-Id, X-Magpie-Timestamp and X-Magpie-Signature. The signature is an HMAC-SHA256 of the timestamp, a full stop and the raw body, made with the webhook's signing secret. The secret is shown once and can be replaced with a new one. X-Magpie-Id stays the same when a delivery is sent again, so your program can ignore a repeat.
Answer with any 2xx status. Any other answer, or none, will be retried with longer waits over about two days, up to 8 attempts. The webhook's page lists recent deliveries with their results, and Send again resends a failed one.
Amounts, pages and the API reference
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 a page. Orders and customers include names, email addresses, phone numbers and addresses, so treat what your program stores as customer data.
The API reference at /docs/api links to the OpenAPI file, which lists every field.
Connect your Store to your own systems.
Create a Magpie account and set up a Store. Add a webhook in Store settings, or create an API key on Pro.