Docs
Search
K

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.

Overview

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 */
}

Endpoints

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 waitlists
    • id - The waitlist ID
    • state - The waitlist state
    • display_dispatch_date - The waitlist estimated shipping dates
    • payment_plan_descriptions - (platform integrations only, otherwise null) Shopper friendly description of your store's pre-order payment plan, if any
    • selling_plan_id - (Shopify app integrations only, otherwise null) The Shopify ID of the selling plan linked to this Waitlist
    • product - An object containing the waitlist product
      • id - The ID of the product used by the connected store, e.g. Shopify product.id
      • product_code - The product code used by the connected store, e.g. Shopify product.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 key
  • product_id- The ID of the product used by the connected store, e.g. Shopify product.id
Response:
  • data
    • id - The ID of the product used by the connected store, e.g. Shopify product.id
    • product_code - The product code used by the connected store, e.g. Shopify product.handle
    • available - Boolean indicating whether the product has any remaining Waitlist stock
    • available_stock - The number of units (across all variants) that are available on the Waitlist
    • variants - An array containing all the product's variants
      • id - The ID of the product used by the connected store, e.g. Shopify variant.id
      • sku - The SKU used by the connected store, e.g. Shopify variant.sku
      • available - Boolean indicating whether this variant has any remaining Waitlist stock
      • available_stock - The number of units available for this variant on the Waitlist
      • available_in_stock - Purple Dot's view of the number of units available for this variant in your Shopify store
      • oversell_enabled - Boolean indicating Purple Dot's view if this variant has its inventory_policy set to continue in Shopify. Should be true for any variant in a store using the Combined Cart checkout type if this variant has Waitlist stock and that Waitlist is live
      • waitlist_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 key
  • handle- The Shopify handle of the product
Response:
  • data
    • state - One of NO_OPEN_WAITLISTS, AVAILABLE_IN_STOCK, ON_PREORDER, SOLD_OUT
    • waitlist - The product's waitlist or null 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 key
  • variant_id- The Shopify handle of the product
Response:
  • data
    • state - One of NO_OPEN_WAITLISTS, AVAILABLE_IN_STOCK, ON_PREORDER, SOLD_OUT
    • waitlist - The product's waitlist or null 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.