Public API
If you are using our Shopify App, this section is irrelevant and you should follow Installing our Shopify App instead. See Purple Dot Overview for the comparison of our Shopify App vs. Platform integrations.
This reference documents the public API that can be used to get information about Waitlists and product availability, both server- and client-side.
Include your store's public API key as an
api_key
query parameter in all requests.The API is versioned using a URL prefix. The current version is
v1
, and all endpoints use the /api/v1/
namespace.All responses follow a common format:
{
"meta": {
"result": "success"
},
"data": /* Response data */
}
Get all open waitlists. Useful for determining which products have a waitlist.
Request:
api_key
- Your Purple Dot store's public API key
Response:
data
- An array containing all the open waitlistsid
- The waitlist IDstate
- The waitlist statedisplay_dispatch_date
- The waitlist estimated shipping datespayment_plan_descriptions
- (platform integrations only, otherwisenull
) Shopper friendly description of your store's pre-order payment plan, if anyselling_plan_id
- (Shopify app integrations only, otherwisenull
) The Shopify ID of the selling plan linked to this Waitlistproduct
- An object containing the waitlist productid
- The ID of the product used by the connected store, e.g. Shopifyproduct.id
product_code
- The product code used by the connected store, e.g. Shopifyproduct.handle
Examples:
curl 'https://www.purpledotprice.com/api/v1/waitlists?api_key=<...>
{
"meta": {
"result": "success"
},
"data": [
{
"id": "3bbc58c6-9a11-422f-9cf5-6a5ac8468eec",
"state": "OPEN",
"display_dispatch_date": "Shipping 10–15 Jun",
"payment_plan_descriptions": null,
"selling_plan_id": null,
"product": {
"id": "4697179062404",
"product_code": "womens-white-sneakers"
}
}
]
}
Get the Purple Dot stock levels for a product and all its variants. Useful for determining whether a particular variant has stock available in Purple Dot.
Request:
api_key
- Your Purple Dot store's public API keyproduct_id
- The ID of the product used by the connected store, e.g. Shopifyproduct.id
Response:
data
id
- The ID of the product used by the connected store, e.g. Shopifyproduct.id
product_code
- The product code used by the connected store, e.g. Shopifyproduct.handle
available
- Boolean indicating whether the product has any remaining Waitlist stockavailable_stock
- The number of units (across all variants) that are available on the Waitlistvariants
- An array containing all the product's variantsid
- The ID of the product used by the connected store, e.g. Shopifyvariant.id
sku
- The SKU used by the connected store, e.g. Shopifyvariant.sku
available
- Boolean indicating whether this variant has any remaining Waitlist stockavailable_stock
- The number of units available for this variant on the Waitlistavailable_in_stock
- Purple Dot's view of the number of units available for this variant in your Shopify storeoversell_enabled
- Boolean indicating Purple Dot's view if this variant has its inventory_policy set tocontinue
in Shopify. Should betrue
for any variant in a store using the Combined Cart checkout type if this variant has Waitlist stock and that Waitlist is livewaitlist_id
- Purple Dot's internal ID of the Waitlist that has stock of this variant, if any
Examples:
curl 'https://www.purpledotprice.com/api/v1/availability?product_id=4697179062404&api_key=<...>'
{
"meta": {
"result": "success"
},
"data": {
"id": "4697179062404",
"product_code": "womens-white-sneakers",
"available": true,
"available_stock": 500,
"variants": [
{
"id": "32813576749188",
"sku": "PD3-10",
"available": true,
"available_stock": 500,
"available_in_stock": 0,
"oversell_enabled": true,
"waitlist_id": "578a2f72-bbd9-41e1-9330-7eb3ba190f00",
},
{
"id": "32813576388740",
"sku": "PD3-5",
"available": false,
"available_stock": 0
"available_in_stock": 0
"oversell_enabled": false,
"waitlist_id": null,
}
]
}
}
Get the pre-order state of a whole product. Useful for determining whether a particular product as a whole is on pre-order, for example when displaying a product in a collection grid.
Request:
api_key
- Your Purple Dot store's public API keyhandle
- The Shopify handle of the product
Response:
data
state
- One ofNO_OPEN_WAITLISTS
,AVAILABLE_IN_STOCK
,ON_PREORDER
,SOLD_OUT
waitlist
- The product's waitlist ornull
if there isn't an open waitlist.display_dispatch_date
- The string that should be shown as the estimated dispatch date for the product.
product
handle
- The product's handle.
Get the pre-order state of a variant. Useful for determining whether a particular variant is on pre-order, for example when displaying a call to action on the PDP.
Request:
api_key
- Your Purple Dot store's public API keyvariant_id
- The Shopify handle of the product
Response:
data
state
- One ofNO_OPEN_WAITLISTS
,AVAILABLE_IN_STOCK
,ON_PREORDER
,SOLD_OUT
waitlist
- The product's waitlist ornull
if there isn't an open waitlist.display_dispatch_date
- The string that should be shown as the estimated dispatch date for the product.
product
- The product that the variant belongs to.handle
- The product's Shopify handle.