{
  "openapi": "3.1.0",
  "info": {
    "title": "Purple Dot Public API",
    "description": "Waitlist, availability and pre-order state for your storefront, server-side or client-side. Every request takes your store's public API key as the `api_key` query parameter. Successful responses are `{ meta: { result: \"success\" }, data }`.",
    "version": "v1"
  },
  "servers": [
    {
      "url": "https://www.purpledotprice.com/api/v1",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "/waitlists",
      "x-page-title": "/waitlists"
    },
    {
      "name": "/availability",
      "x-page-title": "/availability"
    },
    {
      "name": "/products/preorder-state",
      "x-page-title": "/products/preorder-state"
    },
    {
      "name": "/variants/preorder-state",
      "x-page-title": "/variants/preorder-state"
    },
    {
      "name": "/pre-orders",
      "x-page-title": "/pre-orders"
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "query",
        "name": "api_key",
        "description": "Your store's public API key, from the Integration page of the Purple Dot merchant portal."
      },
      "requestSignature": {
        "type": "apiKey",
        "in": "query",
        "name": "token",
        "description": "Required by `GET /pre-orders` together with `api_key`, `timestamp` and `email`. The hex HMAC-SHA256 of `<email>:<timestamp>`, keyed with your shared secret (on the Integration page of the Purple Dot merchant portal). Sign requests in code you control, because the shared secret must not be exposed. A token is valid for under 60 seconds after its `timestamp`, so generate a new one for each request."
      },
      "requestTimestamp": {
        "type": "apiKey",
        "in": "query",
        "name": "timestamp",
        "description": "Required by `GET /pre-orders` together with `api_key`, `token` and `email`. The time the token was signed, in epoch seconds."
      },
      "customerAccountSessionToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "A Shopify Customer Account session token, sent as `Authorization: Bearer <token>`. Accepted by `GET /pre-orders` only, in place of `api_key`, `token`, `timestamp` and `email`: the shopper is identified by the session."
      }
    },
    "schemas": {
      "Pre-order": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Purple Dot pre-order ID.",
            "example": "58da51c9-9b48-48c6-beb5-46bd34834960"
          },
          "reference": {
            "type": "string",
            "description": "Purple Dot reference number, shared with shoppers.",
            "example": "#PD404821"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the pre-order was placed.",
            "example": "2024-11-14T16:18:25.635Z"
          },
          "placed_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the pre-order was placed.",
            "example": "2024-11-14T16:18:25.635Z"
          },
          "total_amount": {
            "type": "number",
            "example": 129.99
          },
          "currency": {
            "type": "string",
            "description": "Presentment currency.",
            "example": "GBP"
          },
          "line_items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "example": "55bedf52-ccf0-431a-a75b-2e999e93a5da"
                },
                "estimated_ship_dates": {
                  "type": "string",
                  "description": "Formatted in the store's locale. Use the ISO dates to format for the shopper instead.",
                  "example": "Estimated ship date 10–15 Jun"
                },
                "earliest_ship_date": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "example": "2025-06-10T00:00:00.000Z"
                },
                "latest_ship_date": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "example": "2025-06-15T00:00:00.000Z"
                },
                "product_handle": {
                  "type": "string",
                  "example": "womens-white-sneakers"
                },
                "product_name": {
                  "type": "string",
                  "example": "Women’s White Sneakers"
                },
                "image_url": {
                  "type": "string",
                  "example": "https://cdn.example.com/sneakers.jpg"
                },
                "product_id": {
                  "type": "string",
                  "example": "4697179062404"
                },
                "variant_id": {
                  "type": "string",
                  "example": "32813576749188"
                },
                "order_id": {
                  "type": "string",
                  "description": "Set once the line item has been exported to your platform.",
                  "example": "5616927408181"
                },
                "external_order_id": {
                  "type": "string",
                  "description": "The platform's own order ID (Shopify's for Shopify stores).",
                  "example": "gid://shopify/Order/5616927408181"
                },
                "is_ready_to_fulfill": {
                  "type": "boolean",
                  "example": false
                },
                "is_fulfilled": {
                  "type": "boolean",
                  "example": false
                },
                "order_reference": {
                  "type": "string",
                  "example": "#3114029"
                },
                "order_token": {
                  "type": "string",
                  "example": "c1f2a8e0d4b64a7f9e3c5b2a1d0f8e67"
                },
                "cancelled": {
                  "type": "boolean",
                  "example": false
                }
              },
              "required": [
                "id",
                "estimated_ship_dates",
                "earliest_ship_date",
                "latest_ship_date",
                "product_handle",
                "product_name",
                "image_url",
                "product_id",
                "variant_id",
                "is_ready_to_fulfill",
                "is_fulfilled",
                "cancelled"
              ]
            }
          },
          "payment_status": {
            "type": "string",
            "enum": [
              "Paid",
              "Partially paid",
              "Partially refunded",
              "Refunded",
              "Unpaid"
            ],
            "example": "Paid"
          },
          "cancelled": {
            "type": "boolean",
            "example": false
          },
          "timezone": {
            "type": "string",
            "description": "The store's IANA timezone, which ship dates fall in.",
            "example": "Europe/London"
          },
          "shipping_address": {
            "type": "object",
            "properties": {
              "first_name": {
                "type": "string",
                "example": "Ada"
              },
              "last_name": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "Lovelace"
              },
              "address1": {
                "type": "string",
                "example": "1 Analytical Way"
              },
              "address2": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "Flat 2"
              },
              "city": {
                "type": "string",
                "example": "London"
              },
              "postal_code": {
                "type": "string",
                "example": "N1 1AA"
              },
              "province_code": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "LND"
              },
              "country_code": {
                "type": "string",
                "example": "GB"
              },
              "phone": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "+447700900123"
              }
            },
            "required": [
              "first_name",
              "last_name",
              "address1",
              "address2",
              "city",
              "postal_code",
              "province_code",
              "country_code",
              "phone"
            ]
          }
        },
        "required": [
          "id",
          "reference",
          "created_at",
          "placed_at",
          "total_amount",
          "currency",
          "line_items",
          "payment_status",
          "cancelled",
          "timezone",
          "shipping_address"
        ]
      },
      "AuthErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "meta": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "Human-readable message."
              },
              "errorData": {
                "type": "object",
                "additionalProperties": {},
                "description": "Structured detail about the error."
              }
            },
            "required": [
              "error",
              "errorData"
            ]
          },
          "data": {
            "type": "object",
            "properties": {}
          }
        },
        "required": [
          "meta",
          "data"
        ]
      },
      "Availability": {
        "type": "object",
        "properties": {
          "id": {
            "type": [
              "string",
              "null"
            ],
            "description": "The product ID from the connected store.",
            "example": "4697179062404"
          },
          "product_code": {
            "type": [
              "string",
              "null"
            ],
            "description": "The product code from the connected store (for example, Shopify `product.handle`).",
            "example": "womens-white-sneakers"
          },
          "available": {
            "type": "boolean",
            "description": "Whether the product has any remaining Waitlist stock.",
            "example": true
          },
          "available_stock": {
            "type": "number",
            "description": "Total Waitlist units available across all variants.",
            "example": 750
          },
          "available_in_stock": {
            "type": [
              "number",
              "null"
            ],
            "example": 0
          },
          "variants": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "The variant ID from the connected store.",
                  "example": "32813576749188"
                },
                "sku": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "example": "PD3-10"
                },
                "available": {
                  "type": "boolean",
                  "description": "Whether this variant has remaining Waitlist stock.",
                  "example": true
                },
                "available_stock": {
                  "type": "number",
                  "description": "Waitlist units available for this variant.",
                  "example": 500
                },
                "available_in_stock": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Purple Dot's count of units for this variant in your store.",
                  "example": 0
                },
                "oversell_enabled": {
                  "type": [
                    "boolean",
                    "null"
                  ],
                  "description": "Whether Purple Dot sees the variant's inventory policy as continue-selling in the store. For stores using the Combined Cart checkout this should be `true` when the variant has Waitlist stock and that Waitlist is live.",
                  "example": true
                },
                "waitlist_id": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "uuid",
                  "description": "Purple Dot's ID of the Waitlist holding stock for this variant, or `null`.",
                  "example": "578a2f72-bbd9-41e1-9330-7eb3ba190f00"
                }
              },
              "required": [
                "id",
                "sku",
                "available",
                "available_stock",
                "available_in_stock",
                "oversell_enabled",
                "waitlist_id"
              ]
            }
          }
        },
        "required": [
          "id",
          "product_code",
          "available",
          "available_stock",
          "available_in_stock",
          "variants"
        ]
      },
      "Waitlist": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The Waitlist ID.",
            "example": "3bbc58c6-9a11-422f-9cf5-6a5ac8468eec"
          },
          "state": {
            "type": "string",
            "description": "On the waitlist endpoints, one of `SCHEDULED` (will start taking pre-orders on `launch_date`), `OPEN` (currently taking pre-orders), `PAUSED` (not terminal, can return to `OPEN`) or `CLOSED` (terminal). On `/products/preorder-state` and `/variants/preorder-state`, the pre-order state of the product or variant, for example `ON_PREORDER`.",
            "example": "OPEN"
          },
          "is_scheduled": {
            "type": "boolean",
            "description": "Whether the Waitlist is not yet live.",
            "example": false
          },
          "launch_date": {
            "type": [
              "string",
              "null"
            ],
            "description": "The date the Waitlist goes live in the storefront.",
            "example": "2025-05-01T00:00:00.000Z"
          },
          "scheduled_pause_date": {
            "type": [
              "string",
              "null"
            ],
            "example": "2025-06-01T00:00:00.000Z"
          },
          "display_dispatch_date": {
            "type": [
              "string",
              "null"
            ],
            "description": "The estimated shipping dates shown to shoppers.",
            "example": "Shipping 10–15 Jun"
          },
          "payment_plan_descriptions": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "long": {
                "type": "string",
                "example": "Pay in full now, or pay a deposit now and the rest when it ships"
              },
              "short": {
                "type": "string",
                "example": "Pay a deposit now"
              }
            },
            "required": [
              "long",
              "short"
            ],
            "description": "Shopper-friendly description of any pre-order payment plan. Platform integrations only; otherwise `null`."
          },
          "use_extended_delivery_language": {
            "type": "boolean",
            "example": false
          },
          "use_partnership_branding": {
            "type": "boolean",
            "example": false
          },
          "selling_plan_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "The Shopify ID of the linked selling plan. Shopify app integrations only; otherwise `null`.",
            "example": "689468694"
          },
          "inventory_location_id": {
            "type": [
              "string",
              "null"
            ],
            "example": "7a4d2c1e-5b8f-4e36-9a0c-3d1f6b2e8c47"
          },
          "product": {
            "type": "object",
            "properties": {
              "id": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The product ID in the connected store. On `/products/preorder-state` and `/variants/preorder-state`, the Purple Dot product ID instead.",
                "example": "4697179062404"
              },
              "product_code": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The product code in the connected store (for example, Shopify `product.handle`).",
                "example": "womens-white-sneakers"
              }
            }
          },
          "compatible_checkouts": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "purple_dot",
                "native"
              ],
              "example": "purple_dot"
            }
          },
          "shipping_dates": {
            "type": "object",
            "properties": {
              "earliest": {
                "type": "string",
                "example": "2025-06-10T00:00:00.000Z"
              },
              "latest": {
                "type": "string",
                "example": "2025-06-15T00:00:00.000Z"
              }
            },
            "required": [
              "earliest",
              "latest"
            ]
          },
          "cancellation_policy": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "cancellable_until": {
                "type": [
                  "string",
                  "null"
                ],
                "enum": [
                  "SCHEDULED_PAUSE",
                  null
                ],
                "example": "SCHEDULED_PAUSE"
              }
            },
            "required": [
              "cancellable_until"
            ],
            "description": "The date-based cancellation window. `null` means the pre-order is not cancellable from the shopper’s point of view."
          }
        },
        "required": [
          "id",
          "state",
          "is_scheduled",
          "launch_date",
          "scheduled_pause_date",
          "display_dispatch_date",
          "payment_plan_descriptions",
          "use_extended_delivery_language",
          "use_partnership_branding",
          "selling_plan_id",
          "inventory_location_id",
          "product",
          "shipping_dates",
          "cancellation_policy"
        ]
      }
    },
    "parameters": {}
  },
  "paths": {
    "/pre-orders": {
      "get": {
        "tags": [
          "/pre-orders"
        ],
        "summary": "List a shopper’s pre-orders",
        "description": "Retrieves all pre-orders for a shopper email address. Unlike the other public endpoints, `api_key` alone is not enough: either sign the request, sending `api_key`, `email`, `timestamp` and a `token` computed from them (see Authorizations), or authenticate the shopper with a Shopify Customer Account session token.",
        "security": [
          {
            "apiKey": [],
            "requestSignature": [],
            "requestTimestamp": []
          },
          {
            "customerAccountSessionToken": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "The email address of the shopper whose pre-orders you want. Required with `api_key`; not sent with a Customer Account session token.",
              "example": "ada@example.com"
            },
            "required": false,
            "description": "The email address of the shopper whose pre-orders you want. Required with `api_key`; not sent with a Customer Account session token.",
            "name": "email",
            "in": "query",
            "example": "ada@example.com"
          },
          {
            "schema": {
              "type": "integer",
              "default": 10,
              "description": "Number of pre-orders to return. Defaults to 10.",
              "example": 10
            },
            "required": false,
            "description": "Number of pre-orders to return. Defaults to 10.",
            "name": "limit",
            "in": "query",
            "example": 10
          },
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Returns pre-orders after the given pre-order ID.",
              "example": "58da51c9-9b48-48c6-beb5-46bd34834960"
            },
            "required": false,
            "description": "Returns pre-orders after the given pre-order ID.",
            "name": "starting_after",
            "in": "query",
            "example": "58da51c9-9b48-48c6-beb5-46bd34834960"
          },
          {
            "schema": {
              "type": "string",
              "description": "Pre-orders placed at or after this time.",
              "example": "2025-01-01T00:00:00.000Z"
            },
            "required": false,
            "description": "Pre-orders placed at or after this time.",
            "name": "created_at_min",
            "in": "query",
            "example": "2025-01-01T00:00:00.000Z"
          },
          {
            "schema": {
              "type": "string",
              "description": "Pre-orders placed at or before this time.",
              "example": "2025-12-31T23:59:59.000Z"
            },
            "required": false,
            "description": "Pre-orders placed at or before this time.",
            "name": "created_at_max",
            "in": "query",
            "example": "2025-12-31T23:59:59.000Z"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "created_at_asc",
                "created_at_desc"
              ],
              "default": "created_at_asc",
              "description": "Sort order by creation time. Defaults to `created_at_asc`.",
              "example": "created_at_desc"
            },
            "required": false,
            "description": "Sort order by creation time. Defaults to `created_at_asc`.",
            "name": "sort",
            "in": "query",
            "example": "created_at_desc"
          }
        ],
        "responses": {
          "200": {
            "description": "The shopper’s pre-orders.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "meta": {
                      "type": "object",
                      "properties": {
                        "result": {
                          "type": "string",
                          "enum": [
                            "success"
                          ],
                          "example": "success"
                        }
                      },
                      "required": [
                        "result"
                      ]
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "pre_orders": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Pre-order"
                          }
                        },
                        "has_more": {
                          "type": "boolean",
                          "description": "Whether more results are available after this page.",
                          "example": false
                        },
                        "starting_after": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "uuid",
                          "description": "ID of the last item returned. Pass it as `starting_after`.",
                          "example": "58da51c9-9b48-48c6-beb5-46bd34834960"
                        }
                      },
                      "required": [
                        "pre_orders",
                        "has_more",
                        "starting_after"
                      ]
                    }
                  },
                  "required": [
                    "meta",
                    "data"
                  ]
                },
                "example": {
                  "meta": {
                    "result": "success"
                  },
                  "data": {
                    "pre_orders": [
                      {
                        "id": "58da51c9-9b48-48c6-beb5-46bd34834960",
                        "reference": "#PD404821",
                        "created_at": "2024-11-14T16:18:25.635Z",
                        "placed_at": "2024-11-14T16:18:25.635Z",
                        "total_amount": 129.99,
                        "currency": "GBP",
                        "payment_status": "Paid",
                        "cancelled": false,
                        "timezone": "Europe/London",
                        "line_items": [
                          {
                            "id": "55bedf52-ccf0-431a-a75b-2e999e93a5da",
                            "estimated_ship_dates": "Estimated ship date 10–15 Jun",
                            "earliest_ship_date": "2025-06-10T00:00:00.000Z",
                            "latest_ship_date": "2025-06-15T00:00:00.000Z",
                            "product_handle": "womens-white-sneakers",
                            "product_name": "Women’s White Sneakers",
                            "image_url": "https://cdn.example.com/sneakers.jpg",
                            "product_id": "4697179062404",
                            "variant_id": "32813576749188",
                            "order_id": "5616927408181",
                            "external_order_id": "gid://shopify/Order/5616927408181",
                            "is_ready_to_fulfill": false,
                            "is_fulfilled": false,
                            "order_reference": "#3114029",
                            "order_token": "c1f2a8e0d4b64a7f9e3c5b2a1d0f8e67",
                            "cancelled": false
                          }
                        ],
                        "shipping_address": {
                          "first_name": "Ada",
                          "last_name": "Lovelace",
                          "address1": "1 Analytical Way",
                          "address2": "Flat 2",
                          "city": "London",
                          "postal_code": "N1 1AA",
                          "province_code": "LND",
                          "country_code": "GB",
                          "phone": "+447700900123"
                        }
                      }
                    ],
                    "has_more": false,
                    "starting_after": "58da51c9-9b48-48c6-beb5-46bd34834960"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or unknown `api_key`. Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/AuthErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "The `token`, `email` and `timestamp` do not form a valid signature. The body is the plain text `Unauthorized`, not the error envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string",
                  "example": "Unauthorized"
                },
                "example": "Unauthorized"
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "HTTP",
            "label": "HTTP (signed request)",
            "source": "GET /api/v1/pre-orders?api_key=<api_key>&email=ada%40example.com&timestamp=<timestamp>&token=<token> HTTP/1.1\nHost: www.purpledotprice.com\nAccept: application/json"
          },
          {
            "lang": "cURL",
            "label": "cURL (signed request)",
            "source": "# Sign \"<email>:<timestamp>\" with your shared secret (HMAC-SHA256, hex).\nEMAIL='ada@example.com'\nTIMESTAMP=$(date +%s)\nTOKEN=$(printf '%s' \"$EMAIL:$TIMESTAMP\" | openssl dgst -sha256 -hmac \"$SHARED_SECRET\" | sed 's/^.* //')\n\ncurl -G 'https://www.purpledotprice.com/api/v1/pre-orders' \\\n  --data-urlencode \"api_key=$API_KEY\" \\\n  --data-urlencode \"email=$EMAIL\" \\\n  --data-urlencode \"timestamp=$TIMESTAMP\" \\\n  --data-urlencode \"token=$TOKEN\""
          },
          {
            "lang": "JavaScript",
            "label": "JavaScript (signed request)",
            "source": "import { createHmac } from 'node:crypto';\n\nconst email = 'ada@example.com';\nconst timestamp = String(Math.floor(Date.now() / 1000));\nconst token = createHmac('sha256', process.env.SHARED_SECRET)\n  .update(email + ':' + timestamp)\n  .digest('hex');\n\nconst query = new URLSearchParams({\n  api_key: process.env.API_KEY,\n  email,\n  timestamp,\n  token,\n});\n\nconst response = await fetch('https://www.purpledotprice.com/api/v1/pre-orders?' + query);\nconsole.log(await response.json());"
          },
          {
            "lang": "Python",
            "label": "Python (signed request)",
            "source": "import hashlib\nimport hmac\nimport os\nimport time\n\nimport requests\n\nemail = \"ada@example.com\"\ntimestamp = str(int(time.time()))\ntoken = hmac.new(\n    os.environ[\"SHARED_SECRET\"].encode(),\n    f\"{email}:{timestamp}\".encode(),\n    hashlib.sha256,\n).hexdigest()\n\nresponse = requests.get(\n    \"https://www.purpledotprice.com/api/v1/pre-orders\",\n    params={\n        \"api_key\": os.environ[\"API_KEY\"],\n        \"email\": email,\n        \"timestamp\": timestamp,\n        \"token\": token,\n    },\n)\nprint(response.json())"
          },
          {
            "lang": "HTTP",
            "label": "HTTP (Customer Account session)",
            "source": "GET /api/v1/pre-orders HTTP/1.1\nHost: www.purpledotprice.com\nAuthorization: Bearer <session_token>\nAccept: application/json"
          },
          {
            "lang": "cURL",
            "label": "cURL (Customer Account session)",
            "source": "curl 'https://www.purpledotprice.com/api/v1/pre-orders' \\\n  -H \"Authorization: Bearer $SESSION_TOKEN\""
          },
          {
            "lang": "JavaScript",
            "label": "JavaScript (Customer Account session)",
            "source": "const response = await fetch('https://www.purpledotprice.com/api/v1/pre-orders', {\n  headers: { Authorization: 'Bearer ' + process.env.SESSION_TOKEN },\n});\nconsole.log(await response.json());"
          },
          {
            "lang": "Python",
            "label": "Python (Customer Account session)",
            "source": "import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://www.purpledotprice.com/api/v1/pre-orders\",\n    headers={\"Authorization\": \"Bearer \" + os.environ[\"SESSION_TOKEN\"]},\n)\nprint(response.json())"
          }
        ]
      }
    },
    "/availability": {
      "get": {
        "tags": [
          "/availability"
        ],
        "summary": "Get Waitlist stock for a product",
        "description": "Returns Purple Dot stock levels for a product and all of its variants. Use it to check whether a variant has Waitlist stock available. Pass `product_id` or `variant_id`.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "The product ID from the connected store (for example, Shopify `product.id`).",
              "example": "4697179062404"
            },
            "required": false,
            "description": "The product ID from the connected store (for example, Shopify `product.id`).",
            "name": "product_id",
            "in": "query",
            "example": "4697179062404"
          },
          {
            "schema": {
              "type": "string",
              "description": "The variant ID from the connected store.",
              "example": "32813576749188"
            },
            "required": false,
            "description": "The variant ID from the connected store.",
            "name": "variant_id",
            "in": "query",
            "example": "32813576749188"
          },
          {
            "schema": {
              "type": "string",
              "description": "The shopper’s country, as an ISO 3166 code.",
              "example": "GB"
            },
            "required": false,
            "description": "The shopper’s country, as an ISO 3166 code.",
            "name": "country",
            "in": "query",
            "example": "GB"
          }
        ],
        "responses": {
          "200": {
            "description": "Stock levels.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "meta": {
                      "type": "object",
                      "properties": {
                        "result": {
                          "type": "string",
                          "enum": [
                            "success"
                          ],
                          "example": "success"
                        }
                      },
                      "required": [
                        "result"
                      ]
                    },
                    "data": {
                      "$ref": "#/components/schemas/Availability"
                    }
                  },
                  "required": [
                    "meta",
                    "data"
                  ]
                },
                "example": {
                  "meta": {
                    "result": "success"
                  },
                  "data": {
                    "id": "4697179062404",
                    "product_code": "womens-white-sneakers",
                    "available": true,
                    "available_stock": 750,
                    "available_in_stock": 0,
                    "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": true,
                        "available_stock": 250,
                        "available_in_stock": 0,
                        "oversell_enabled": true,
                        "waitlist_id": "578a2f72-bbd9-41e1-9330-7eb3ba190f00"
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or unknown `api_key`. Neither `product_id` nor `variant_id` was passed.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/AuthErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No product or variant matches the supplied ID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/waitlists": {
      "get": {
        "tags": [
          "/waitlists"
        ],
        "summary": "List open Waitlists",
        "description": "Returns all open Waitlists, which shows which products currently have one.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "The shopper’s country, as an ISO 3166 code. Only Waitlists whose stock ships to it are returned.",
              "example": "GB"
            },
            "required": false,
            "description": "The shopper’s country, as an ISO 3166 code. Only Waitlists whose stock ships to it are returned.",
            "name": "country",
            "in": "query",
            "example": "GB"
          },
          {
            "schema": {
              "type": "string",
              "description": "The shopper’s language, as a BCP 47 tag such as `de-DE`. For stores that translate their Waitlists, Waitlist text such as ship dates and payment plans is shown in it when it differs from the store’s own language.",
              "example": "en-GB"
            },
            "required": false,
            "description": "The shopper’s language, as a BCP 47 tag such as `de-DE`. For stores that translate their Waitlists, Waitlist text such as ship dates and payment plans is shown in it when it differs from the store’s own language.",
            "name": "locale",
            "in": "query",
            "example": "en-GB"
          }
        ],
        "responses": {
          "200": {
            "description": "The open Waitlists.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "meta": {
                      "type": "object",
                      "properties": {
                        "result": {
                          "type": "string",
                          "enum": [
                            "success"
                          ],
                          "example": "success"
                        }
                      },
                      "required": [
                        "result"
                      ]
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Waitlist"
                      }
                    }
                  },
                  "required": [
                    "meta",
                    "data"
                  ]
                },
                "example": {
                  "meta": {
                    "result": "success"
                  },
                  "data": [
                    {
                      "id": "3bbc58c6-9a11-422f-9cf5-6a5ac8468eec",
                      "state": "OPEN",
                      "is_scheduled": false,
                      "launch_date": "2025-05-01T00:00:00.000Z",
                      "scheduled_pause_date": "2025-06-01T00:00:00.000Z",
                      "display_dispatch_date": "Shipping 10–15 Jun",
                      "payment_plan_descriptions": {
                        "long": "Pay in full now, or pay a deposit now and the rest when it ships",
                        "short": "Pay a deposit now"
                      },
                      "use_extended_delivery_language": false,
                      "use_partnership_branding": false,
                      "selling_plan_id": "689468694",
                      "inventory_location_id": "7a4d2c1e-5b8f-4e36-9a0c-3d1f6b2e8c47",
                      "product": {
                        "id": "4697179062404",
                        "product_code": "womens-white-sneakers"
                      },
                      "compatible_checkouts": [
                        "purple_dot",
                        "native"
                      ],
                      "shipping_dates": {
                        "earliest": "2025-06-10T00:00:00.000Z",
                        "latest": "2025-06-15T00:00:00.000Z"
                      },
                      "cancellation_policy": {
                        "cancellable_until": "SCHEDULED_PAUSE"
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Missing or unknown `api_key`. Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/AuthErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/products/preorder-state": {
      "get": {
        "tags": [
          "/products/preorder-state"
        ],
        "summary": "Get the pre-order state of a product",
        "description": "Returns the pre-order state of a whole product. Useful for showing a product's status in a collection grid.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "The product's Shopify handle.",
              "example": "womens-white-sneakers"
            },
            "required": true,
            "description": "The product's Shopify handle.",
            "name": "handle",
            "in": "query",
            "example": "womens-white-sneakers"
          },
          {
            "schema": {
              "type": "string",
              "description": "The shopper’s country, as an ISO 3166 code.",
              "example": "GB"
            },
            "required": false,
            "description": "The shopper’s country, as an ISO 3166 code.",
            "name": "country",
            "in": "query",
            "example": "GB"
          },
          {
            "schema": {
              "type": "string",
              "description": "The shopper’s language, as a BCP 47 tag such as `de-DE`. For stores that translate their Waitlists, Waitlist text such as ship dates and payment plans is shown in it when it differs from the store’s own language.",
              "example": "en-GB"
            },
            "required": false,
            "description": "The shopper’s language, as a BCP 47 tag such as `de-DE`. For stores that translate their Waitlists, Waitlist text such as ship dates and payment plans is shown in it when it differs from the store’s own language.",
            "name": "locale",
            "in": "query",
            "example": "en-GB"
          }
        ],
        "responses": {
          "200": {
            "description": "The product state.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "meta": {
                      "type": "object",
                      "properties": {
                        "result": {
                          "type": "string",
                          "enum": [
                            "success"
                          ],
                          "example": "success"
                        }
                      },
                      "required": [
                        "result"
                      ]
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "state": {
                          "type": "string",
                          "enum": [
                            "NO_OPEN_WAITLISTS",
                            "AVAILABLE_IN_STOCK",
                            "ON_PREORDER",
                            "SOLD_OUT"
                          ],
                          "description": "`NO_OPEN_WAITLISTS`: no live or scheduled Waitlist exists for the product. `AVAILABLE_IN_STOCK`: at least one variant is in stock. `ON_PREORDER`: no variant is in stock, but at least one is on pre-order. `SOLD_OUT`: all variants are sold out.",
                          "example": "ON_PREORDER"
                        },
                        "waitlist": {
                          "allOf": [
                            {
                              "$ref": "#/components/schemas/Waitlist"
                            },
                            {
                              "type": [
                                "object",
                                "null"
                              ],
                              "description": "The open Waitlist, or `null` if none is open."
                            }
                          ]
                        }
                      },
                      "required": [
                        "state",
                        "waitlist"
                      ]
                    }
                  },
                  "required": [
                    "meta",
                    "data"
                  ]
                },
                "example": {
                  "meta": {
                    "result": "success"
                  },
                  "data": {
                    "state": "ON_PREORDER",
                    "waitlist": {
                      "id": "3bbc58c6-9a11-422f-9cf5-6a5ac8468eec",
                      "state": "OPEN",
                      "is_scheduled": false,
                      "launch_date": "2025-05-01T00:00:00.000Z",
                      "scheduled_pause_date": "2025-06-01T00:00:00.000Z",
                      "display_dispatch_date": "Shipping 10–15 Jun",
                      "payment_plan_descriptions": {
                        "long": "Pay in full now, or pay a deposit now and the rest when it ships",
                        "short": "Pay a deposit now"
                      },
                      "use_extended_delivery_language": false,
                      "use_partnership_branding": false,
                      "selling_plan_id": "689468694",
                      "inventory_location_id": "7a4d2c1e-5b8f-4e36-9a0c-3d1f6b2e8c47",
                      "product": {
                        "id": "4697179062404",
                        "product_code": "womens-white-sneakers"
                      },
                      "compatible_checkouts": [
                        "purple_dot",
                        "native"
                      ],
                      "shipping_dates": {
                        "earliest": "2025-06-10T00:00:00.000Z",
                        "latest": "2025-06-15T00:00:00.000Z"
                      },
                      "cancellation_policy": {
                        "cancellable_until": "SCHEDULED_PAUSE"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or unknown `api_key`. Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/AuthErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No product has that handle.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/variants/preorder-state": {
      "get": {
        "tags": [
          "/variants/preorder-state"
        ],
        "summary": "Get the pre-order state of a variant",
        "description": "Returns the pre-order state of a variant. Use it to decide whether to show a pre-order call to action on the product detail page.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "The Shopify variant ID.",
              "example": "32813576749188"
            },
            "required": true,
            "description": "The Shopify variant ID.",
            "name": "variant_id",
            "in": "query",
            "example": "32813576749188"
          },
          {
            "schema": {
              "type": "string",
              "description": "The shopper’s country, as an ISO 3166 code.",
              "example": "GB"
            },
            "required": false,
            "description": "The shopper’s country, as an ISO 3166 code.",
            "name": "country",
            "in": "query",
            "example": "GB"
          },
          {
            "schema": {
              "type": "string",
              "description": "The shopper’s language, as a BCP 47 tag such as `de-DE`. For stores that translate their Waitlists, Waitlist text such as ship dates and payment plans is shown in it when it differs from the store’s own language.",
              "example": "en-GB"
            },
            "required": false,
            "description": "The shopper’s language, as a BCP 47 tag such as `de-DE`. For stores that translate their Waitlists, Waitlist text such as ship dates and payment plans is shown in it when it differs from the store’s own language.",
            "name": "locale",
            "in": "query",
            "example": "en-GB"
          }
        ],
        "responses": {
          "200": {
            "description": "The variant state.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "meta": {
                      "type": "object",
                      "properties": {
                        "result": {
                          "type": "string",
                          "enum": [
                            "success"
                          ],
                          "example": "success"
                        }
                      },
                      "required": [
                        "result"
                      ]
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "state": {
                          "type": "string",
                          "enum": [
                            "NO_OPEN_WAITLISTS",
                            "AVAILABLE_IN_STOCK",
                            "ON_PREORDER",
                            "SOLD_OUT"
                          ],
                          "description": "`NO_OPEN_WAITLISTS`: no live or scheduled Waitlist exists for the variant. `AVAILABLE_IN_STOCK`: a Waitlist exists, but stock in your store sells first, per your Operations settings. `ON_PREORDER`: selling as a pre-order. `SOLD_OUT`: no stock remains in your store or on any Waitlist.",
                          "example": "ON_PREORDER"
                        },
                        "waitlist": {
                          "allOf": [
                            {
                              "$ref": "#/components/schemas/Waitlist"
                            },
                            {
                              "type": [
                                "object",
                                "null"
                              ],
                              "properties": {
                                "units_left": {
                                  "type": "number",
                                  "description": "Waitlist units still available."
                                }
                              },
                              "required": [
                                "units_left"
                              ]
                            }
                          ],
                          "description": "The open Waitlist, or `null` if none is open."
                        },
                        "product": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "example": "4697179062404"
                            },
                            "handle": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "The product's Shopify handle.",
                              "example": "womens-white-sneakers"
                            }
                          },
                          "required": [
                            "id",
                            "handle"
                          ]
                        },
                        "requires_components": {
                          "type": "boolean",
                          "description": "Whether the variant is a bundle whose components are listed in `components`.",
                          "example": false
                        },
                        "components": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "state": {
                                "type": "string",
                                "enum": [
                                  "NO_OPEN_WAITLISTS",
                                  "AVAILABLE_IN_STOCK",
                                  "ON_PREORDER",
                                  "SOLD_OUT"
                                ]
                              },
                              "waitlist": {
                                "allOf": [
                                  {
                                    "$ref": "#/components/schemas/Waitlist"
                                  },
                                  {
                                    "type": [
                                      "object",
                                      "null"
                                    ],
                                    "properties": {
                                      "units_left": {
                                        "type": "number",
                                        "description": "Waitlist units still available."
                                      }
                                    },
                                    "required": [
                                      "units_left"
                                    ]
                                  }
                                ]
                              },
                              "product": {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": [
                                      "string",
                                      "null"
                                    ]
                                  },
                                  "handle": {
                                    "type": [
                                      "string",
                                      "null"
                                    ],
                                    "description": "The product's Shopify handle."
                                  }
                                },
                                "required": [
                                  "id",
                                  "handle"
                                ]
                              },
                              "isInStock": {
                                "type": "boolean"
                              }
                            },
                            "required": [
                              "state",
                              "waitlist",
                              "product",
                              "isInStock"
                            ]
                          }
                        }
                      },
                      "required": [
                        "state",
                        "waitlist",
                        "product",
                        "requires_components",
                        "components"
                      ]
                    }
                  },
                  "required": [
                    "meta",
                    "data"
                  ]
                },
                "example": {
                  "meta": {
                    "result": "success"
                  },
                  "data": {
                    "state": "ON_PREORDER",
                    "waitlist": {
                      "id": "3bbc58c6-9a11-422f-9cf5-6a5ac8468eec",
                      "state": "OPEN",
                      "is_scheduled": false,
                      "launch_date": "2025-05-01T00:00:00.000Z",
                      "scheduled_pause_date": "2025-06-01T00:00:00.000Z",
                      "display_dispatch_date": "Shipping 10–15 Jun",
                      "payment_plan_descriptions": {
                        "long": "Pay in full now, or pay a deposit now and the rest when it ships",
                        "short": "Pay a deposit now"
                      },
                      "use_extended_delivery_language": false,
                      "use_partnership_branding": false,
                      "selling_plan_id": "689468694",
                      "inventory_location_id": "7a4d2c1e-5b8f-4e36-9a0c-3d1f6b2e8c47",
                      "product": {
                        "id": "4697179062404",
                        "product_code": "womens-white-sneakers"
                      },
                      "compatible_checkouts": [
                        "purple_dot",
                        "native"
                      ],
                      "shipping_dates": {
                        "earliest": "2025-06-10T00:00:00.000Z",
                        "latest": "2025-06-15T00:00:00.000Z"
                      },
                      "cancellation_policy": {
                        "cancellable_until": "SCHEDULED_PAUSE"
                      },
                      "units_left": 12
                    },
                    "product": {
                      "id": "4697179062404",
                      "handle": "womens-white-sneakers"
                    },
                    "requires_components": false,
                    "components": []
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or unknown `api_key`. Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/AuthErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No variant has that ID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "webhooks": {}
}
