Purple Dot
Test Purple Dot Token
Check a Purple Dot Private API token without saving it. With `include_unmatched: true` the answer also lists the store's Waitlist variants that no SKU.io product matches under `sku_match_key`.
Update Purple Dot Connection
Partial settings update, token replacement and live ↔ paused. A given `access_token` is validated live before it replaces the old one.
Preview Purple Dot Connection
Starts a dry-run in the background. It builds the planned inventory the first push would send, reads every held pre-order from Purple Dot with the purchase order line that would cover it (or shelf stock, or nothing, or no matching product), and the release budget per SKU. Nothing is sent to Purple Dot and no SKU.io demand is created; only `GET /pre-orders` is read. Replaces the previous dry-run. The connection's `preview` block (`state`: none / running / succeeded / stale / failed, `tracked_job_log_id`, `succeeded_at`) records the result; Go live requires `succeeded` for the current settings. Returns the id of the background job to follow; read the rows with List Purple Dot Preview Rows when it completes. 422 `no_token` when no access token is stored. Requires integrations.sync.
List Purple Dot Preview Rows
Lists the rows of the latest dry-run, oldest first. The `payload` depends on `kind`: `planned_inventory` (product, purchase_order, source_label, quantity_expected net of backorders, quantity_arrived, date_expected, location_name), `preorder` (reference, customer_name, sku, quantity, coverage = covered | shelf | uncovered | unmapped, purchase_order with eta; a pre-order line split across purchase orders gives one row per part) or `release` (sku, product, held_units, available_units). Rows are dropped when the connection goes live. Requires integrations.show.
Go Live with Purple Dot
Puts a pending (or paused) connection live: the dry-run rows are dropped and the initial sync starts in the background — every held pre-order is imported as backorder demand, then planned inventory is pushed, then every release budget. Returns the id of the background job and the updated connection. 422 `already_live` when the connection is live; `not_allowed` when it has no access token or no supply warehouse, or — for a connection that never went live — when no dry-run has succeeded for its current settings (the dry-run is still running, failed, or the supply / matching / budget settings changed since; the message says which). The connection's `preview.state` shows the same check. Requires integrations.sync.
List Purple Dot Planned Inventory
The planned inventory SKU.io last sent to Purple Dot, one row per supply source: a purchase order line, an inbound shipment carrying it, or an inbound warehouse transfer line into a supply warehouse. Quantities and `date_expected` are what Purple Dot last accepted; `pending_date_expected` and `eta_review_id` describe an ETA slip waiting for review. `netted_backorder_units` are units held back for SKU.io's own backorders. `status` pending = Purple Dot did not acknowledge the last push (5xx, 429 or network); the item is retried automatically with backoff using the values computed at retry time, `last_error` shows the failure and `next_retry_at` when it is next tried (null for any other status). error = Purple Dot rejected the item (4xx); it is not retried automatically.
Push Purple Dot Planned Inventory
Starts a background push of planned inventory to Purple Dot for the given products, or every product when `product_ids` is empty. Items are re-sent even when unchanged since the last push (the automatic pushes skip those); ETA slips over the connection's review threshold are held for review instead of being pushed. Returns the id of the background job to follow. 422 `not_live` when the connection is not live, `push_disabled` when the planned-inventory push is off.
List Purple Dot ETA Reviews
ETA slips held back from Purple Dot, oldest first. Purple Dot emails shoppers when a Waitlist's dates change, so a slip over the review threshold waits for an approve or dismiss. `held_preorder_units` / `held_preorder_count` are the held pre-orders waiting on that PO for the product.
Approve Purple Dot ETA Review
Approves the slip and pushes the new date to Purple Dot, which then emails affected shoppers. 422 `not_allowed` when the review is no longer pending; 404 for another connection's review.
Dismiss Purple Dot ETA Review
Keeps the old date in Purple Dot. Other changes to the same source (quantities) are still pushed with the old date. SKU.io asks again when the ETA changes to a different date. 422 `not_allowed` when the review is no longer pending.
List Purple Dot Waitlists
Purple Dot Waitlists mirrored into SKU.io, compared with SKU.io inbound. `cap`, `committed` and `available` sum the Waitlist's variants. `sku_io_inbound` is the open supply last sent as planned inventory for the Waitlist's products arriving by its latest ship date; `is_over_committed` is true when the cap is larger (pre-selling more than is coming). `is_managed` Waitlists carry the `sku-io` label and can be paused, resumed or closed; others link to the Purple Dot Merchant Portal (`merchant_portal_url`). `state` is OPEN, SCHEDULED, PAUSED, DRAFT or CLOSED.
Set Purple Dot Waitlist State
Opens, pauses or closes a Waitlist in Purple Dot. Only Waitlists labelled `sku-io` can be changed; any other returns 422 `not_allowed`. Shoppers can no longer pre-order a paused or closed Waitlist. A token Purple Dot rejects returns 422 `invalid_token`.
Get Product Purple Dot Summary
The product's Purple Dot pre-order summary: its current Waitlist (state, ship window, cap, committed, available, managed), held pre-order units, units set aside awaiting export, and held units no purchase order covers. `data` is an empty object when Purple Dot is not connected.
List Purple Dot Pre-orders
Paginated mirror of the connection's Purple Dot pre-orders, newest placed first, with lines, matched products, Waitlists, demand rows (status, warehouse, covering PO line and ETA) and the sales order an export was handed to.
Get Purple Dot Pre-order
One pre-order of the connection with its lines and demand rows. 404 when the pre-order belongs to another connection.
Sync Purple Dot Pre-orders
Poll Purple Dot for new and changed pre-orders now (queued). New held pre-orders become backorder demand covered by purchase orders; cancellations free their coverage. Requires integrations.sync. 422 `not_live` when the connection is not live.
Map Purple Dot Variant to Product
Point a Purple Dot SKU and/or Shopify variant at a SKU.io product. Held pre-order lines for that variant that had no product are matched and become backorder demand.
List Purple Dot Release Budgets
Per external Purple Dot SKU (several Purple Dot SKUs can map to one SKU.io product; each pre-order line's allocated units count toward its own SKU): the number of held pre-order units Purple Dot may export now as SKU.io computes it (`computed_units`), the value Purple Dot last acknowledged (`available_units`, null before the first acknowledged push), and the held and allocated units behind it. In allocation release mode the budget is the units SKU.io has set aside from stock in the supply warehouses; in shelf mode it is their sellable on-hand. A bundle's budget is the minimum across its components.
Push Purple Dot Release Budgets
Re-send release budgets to Purple Dot (queued), even when unchanged. Body `product_ids` (array of product ids, optional; omit for every pre-order SKU). Requires integrations.sync.
List Unmatched Exports
Lists exported Shopify orders that imported without a matching Purple Dot pre-order, newest first. SKU.io retries the match after every pre-order poll; rows open for more than an hour have `is_overdue: true`.
Match Unmatched Export
Matches an open unmatched export to a pre-order by hand. The pre-order's reserved demand moves onto the order's lines (keeping its status, PO coverage and priority), any allocation the order holds beyond its open quantity is released (weakest first), the pre-order line is marked exported, and the order is tagged `purple-dot` with its Purple Dot reference and payment status.
Dismiss Unmatched Export
Marks an open unmatched export as reviewed without moving any reservation.
Get Refund Preview
Returns what can be refunded through Purple Dot on an exported order: each Purple Dot line with its unit price, the quantity on the given return (received, or expected while nothing is received, less what was already refunded for that return) and the most that can still be refunded, plus the shipping still refundable (0 once shipping was refunded), currency and the connection's refund mode (`ask`, `auto`, `off`). A bundle is ONE line (`is_bundle: true`) keyed by its first component line and counted in purchased bundles; its unit price is the bundle's price.
Create Refund
Refunds lines (and optionally shipping) of an exported Purple Dot order through Purple Dot. Purple Dot is sent one `line_items` entry of quantity 1 per unit, and `shipping: true` for shipping; a bundle is refunded in whole purchased bundles. The refund is stored as unconfirmed (holding its units) before Purple Dot is called, sent in one attempt, and on success gets a note on the sales order.
Resolve Unconfirmed Refund
Closes a refund Purple Dot never confirmed (`uncertain: true`, listed in the refund preview's `pending_refunds`) with what the merchant found after checking the Purple Dot Merchant Portal. Runs under the same per-order lock as sending a refund, so it cannot race a retry or a late confirmation.
List Refunds
Lists refunds issued through Purple Dot from SKU.io for a connection, newest first. Failed refunds (for example an automatic refund on return receipt that Purple Dot refused) keep their error and Purple Dot's response code.
Get Purple Dot Summary
Returns the dashboard numbers of a Purple Dot connection: held pre-orders, units and shoppers; units covered by open purchase orders, uncovered, allocated and waiting for Purple Dot to export, and on unmapped variants; pre-orders exported, cancelled and refunded in the last 30 days; per purchase order, the units pre-sold next to its open quantity and other backorders; the counts that need attention (pending ETA reviews, exported orders unmatched for over an hour, unmapped variants, over-committed Waitlists, failed refunds, errors in the last 24 hours); and the last release-budget push and reconcile. Dates are Y-m-d in the account timezone; times are ISO 8601 UTC. Requires integrations.show.
List Purple Dot Activity
Lists the connection's activity log, newest first: planned-inventory and release-budget pushes, pre-order polls, export handoffs, cancellations, refunds, reconciles, webhooks, connection changes and errors. `response_code` is Purple Dot's HTTP status when the row came from a call; `is_error` marks error rows and answers of 400 or more. `detail` carries the payload summary and Purple Dot's error text. Rows are kept for 90 days. Requires integrations.show. Search with `filter[search]`, narrowed by `search_columns` (id, reference, sku, summary) and `search_strict_columns`; `filter[id.<operator>]` filters on the row id.
Reconcile Purple Dot
Starts a reconcile in the background (it also runs nightly at 03:00 account time): for each SKU with held pre-orders it compares Purple Dot's open pre-order units with SKU.io's and re-reads that SKU's pre-orders when they differ; it checks that no purchase order line covers more backorders than it still has open; then it re-pushes every release budget and the planned inventory. Differences appear in the activity log and the summary. Returns the id of the background job to follow. 422 `not_live` when the connection is not live. Requires integrations.sync.