/pre-orders

Authentication

As well as including your store's public API key as an api_key query parameter in all requests, this endpoint requires a few other parameters:

Query param	Where to find it
api_key	This is available on the integration page on your merchant portal under 'Public API Key'
email	This is the email of the shopper you're looking up the info for
timestamp	This is the browser timestamp in the epoch format
token	This is the security signature that Purple Dot uses to verify the authenticity of the request. This is generated by hashing the email and the timestamp against the 'Shared secret' found on the integration page. More on how to generate this token here.

How to generate the token

Purple Dot expects a SHA-256 hash of the email and the timestamp in the following format:

<email>:<timestamp>

You can generate the token in liquid as shown below:

{% assign timestamp = 'now' | date: '%s' %}
{% assign token_value = customer.email | append: ':' | append: timestamp %}
{% assign token = token_value | hmac_sha256: 'd9b24a0f-9c08-45e5-a6f7-53797906da19' %}

<script>
  window.PurpleDotAPICredentials = {
    timestamp: "{{ timestamp }}",
    email: "{{ customer.email }}",
    token: "{{ token }}"
  }
</script>

GET /pre-orders

Get all pre-orders for a given shopper email address.

Request:

• limit (number) - The number of pre-orders to retrieve. By default, it's set to 10 but can be set up to 100

• starting_after (UUID) - Paginate pre-orders after the given pre-order ID

Response:

• orders - An array containing all the pre-orders

  • id - The Purple Dot ID of the pre-order

  • reference - The Purple Dot reference number of the pre-order

  • created_at - The timestamp at which the pre-order was placed (formatted in the ISO 8601 format)

  • total_amount - The pre-order total

  • currency - The presentment currency of the pre-order

  • line_items - Array of line items

    • id - The Purple Dot ID of the line item

    • estimated_ship_dates - The estimated ship dates of the line item

    • product_id - The Shopify ID of the line item's product

    • variant_id - The Shopify ID of the line item's product variant

    • order_id - The Shopify order ID in (this will be null if the preorder/line-item is not exported to Shopify)

    • cancelled - Whether the line item is cancelled

  • shipping_address

    • first_name

    • last_name

    • address1

    • address2

    • city

    • postal_code

    • province_code - The ISO3166 code of the second level administrative subdivision

    • country_code - The ISO3166 code of the country

    • phone

• has_more - Indicates whether there are more pre-orders available to page through

• starting_after - The ID of the last pre-order in the list which can then be used in the next request

Examples:

curl --request GET \
  --url 'https://www.purpledotprice.com/api/v1/pre-orders?api_key=<<enter-api-key>>&email=<<enter-email>>&token=<<enter-generated-token>>' \

{
  "meta": {
    "result": "success"
  },
  "data": {
    "pre_orders": [
      {
        "id": "03cda1e6-0827-4092-ae97-5a4746bac0b3",
        "reference": "#PD404821",
        "created_at": "2023-12-07T10:59:24.248Z",
        "total_amount": 54.72,
        "currency": "USD",
        "line_items": [
          {
            "id": "628f7e83-c56f-4e16-9959-43e011f77e8f",
            "estimated_ship_dates": "Mar 1 – 2",
            "product_id": "9f32f1f6-42bc-49f3-8a55-d28362444ccf",
            "variant_id": "9c1206a0-7efa-43af-bbfa-52498f6af6aa",
            "order_id": null,
            "canceled": false
          }
        ],
        "shipping_address": {
          "first_name": "John",
          "last_name": "Smith",
          "address1": "8 York Road",
          "address2": null,
          "city": "London",
          "postal_code": "SW49 5LT",
          "province_code": null,
          "country_code": "GB",
          "phone": "[phone]"
        }
      }
    ],
    "has_more": true,
    "starting_after": "2174855e-0f3c-482d-9cf0-f2b5cb6213cf"
  }
}