# Purple Dot Overview ### [What is Purple Dot?](#what-is-purple-dot) Purple Dot is a pre-order management platform. It enables you to easily sell stock before it arrives through creating pre-order experiences. Purple Dot provides all the tooling required to manage pre-orders including the customer experience (display components), transacting the customer (payments, including 100% pay upfront, split payment with a deposit upfront and rest on ship, or full charge on ship) customer service flows (customer self-service, with internal dashboards and integrations), communications (email) and data (as events, visualizations and downloads). To set-up a product a pre-order, a Waitlist is created that takes an item from your existing catalog, adds estimated ship dates as a date range along with the number of units you want to pre-sell by SKU or total. Purple Dot then enables customers to pre-order this product (checking out), the pre-order wait experience (self-serve amend, cancel and email updates), and the transition of pre-orders to regular orders when the product arrives in your warehouse. ### [Why use Purple Dot for pre-orders?](#what-is-purple-dot) We are the only pre-order solution that is * fully FTC compliant in charging upfront for pre-orders * compatible with all major downstream 3PL and warehouse / shopping partners * always keeps the customer up to date on where their pre-order is at A small amount of engineering effort is required to get started, and the integration can be done by you or by Purple Dot. See our [Getting Started Guide](/docs/getting-started). Pricing is a flat all-in % transaction fee, depending on your country and with additional volume discounts available. **This includes all payment processing fees.** There are no additional payment or transaction fees from your eCommerce platform since Purple Dot is transacting the pre-order instead of your eCommerce platform. #### [How does Purple Dot work?](#feature-comparison) Once you're up and running with Purple Dot, we automatically adjust your customers' online shopping experience to provide the 3 core value props listed above: | | As separate checkout | As payment provider (Shopify Plus only) | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Visual changes in your store |

For products that have a Waitlist, a Pre-order button with estimated delivery dates replaces your regular Add to Cart button.

Sold Out labels for these products are removed.

| Same. | | Checkout flow |

Clicking the Pre-order button leads into a new checkout flow, that mirrors your brand’s look, feel and existing checkout functionality.

This separate checkout is what enables pre-orders to be held outside your system until stock arrives, and the FTC compliant payment flow for pre-orders.

Supports single-item, multi-item, and mixed cart flows (where the customer's cart contains both in-stock and pre-order items).

|

Clicking the Pre-order button leads into your existing checkout flow.

To provide FTC compliant payment flow for pre-orders, Purple Dot will be the only payment option available when customer is buying a pre-order.

| | Emails | **Pre-order post-purchase transactional emails**, including: confirmation, updated shipping dates, amended or canceled order. | Same. | | Customer payment |

You can choose to charge the customer in full at checkout, some upfront and the rest later, or all later.

Funds are held until pre-orders are exported as ready to fulfil, which enables an FTC compliant payment flow for pre-orders. Customers can cancel for a full refund anytime before ship. See Cancellations.

There is an option to release the funds early for an extra charge.

|

Customer is always charged in full at checkout.

Otherwise same.

| | Pre-order tracking | **Pre-orders are held in Purple Dot until you are ready to fulfil** (typically when the product(s) arrive at your warehouse), at which point they are exported to your e-commerce platform and fulfilled as regular orders. |

An order with "On Hold" against the pre-order line item is created in Shopify as soon as the checkout completes.

Once stock arrives and you are ready to fulfil, you can remove this fulfilment hold in Purple Dot or your Shopify portal.

Some ERP/3PL do not support these Shopify "On Hold"s - in those cases we integrate with the ERP/3PL directly to ensure only pre-orders that are ready to fulfil flow down to your ERP/3PL.

| | Cancellations | Pre-order cancellations can be **facilitated by the customer via the Purple Dot self-serve embedded in your site or the Purple Dot** [**self-service pre-order management page**](https://www.getpurpledot.com/shopper) **or by you via your Purple Dot Merchant Portal**, at any point before the pre-order is ready to fulfil. | Same. | | Refunds |

Refunds for returned pre-orders are processed by Purple Dot, and can be issued from the Purple Dot Merchant Portal.

Optionally, refunds can also be triggered automatically based on events from your e-commerce platform delivered as webhooks.

| Same. | | Analytics | **Purple Dot integrates seamlessly with your analytics, advertising and CRM tracking libraries**. Events like conversions can be forwarded to any client library included on the page. | Same. | | Shipping rates |

Can use the same rate settings as your in-stock orders, or you can configure pre-order specific rates.

You can also choose to ship a pre-order and in-stock order together or separately, or let the customer choose.

| Uses the same settings as your in-stock orders. | | Cost | A % transaction fee depending on country and with volume discounts available. **This includes all payment processing fees.** [Contact](mailto:sales@getpurpledot.com) us for pricing. | Same. | # Getting Started Start by signing up to Purple Dot as a Merchant. If you don't have a Merchant Account yet, send us an email at and we'll get you set up. Once you have your Purple Dot account, you can finish the rest of the setup: 1. **Sign in** to the [Merchant Portal](https://www.purpledotprice.com/merchant-portal) with your email. This is where you manage your Waitlists, pre-orders and configure the integration. You can also **add more team members** there. 2. **Connect Purple Dot** to your eCommerce store 1. [Shopify](/docs/shopify-stores/install-our-app) 2. [Salesforce](/docs/salesforce-stores/integrate-purple-dot-with-salesforce) 3. [Other](/docs/other-e-comm-platforms/integrate-into-another-platform) 3. **Configure email styling, shipping rates and taxes** in your [Merchant Portal](https://www.purpledotprice.com/merchant-portal). 4. **Connect your bank account** to receive payouts from Purple Dot on your pre-order sales. To do this, use our Stripe onboarding flow in the Balance section of the [Merchant Portal](https://www.purpledotprice.com/merchant-portal/finances). Once you've completed those steps, you can [test your integration](/docs/shopify-stores/test-the-integration) and launch it! # Install our app You will be given a unique link to single-click install Purple Dot into your Shopify store. The app is verified and approved by Shopify and distributed via the App Store, but it is not listed in the App Store as it is unique to your store. The app will ask for certain permissions that allow Purple Dot to do what we need to be able to do * stay in sync with your product catalog * see and create customer data * see and create orders Please approve the required permissions and install the app. # Integrate Purple Dot with your Storefront ### [Overview](#overview) How you integrate Purple Dot into your storefront depends on how it is built: * [Integrate into Shopify Themes built with Liquid](/docs/shopify-stores/integrate-purple-dot-with-your-storefront/integrate-into-shopify-themes-built-with-liquid) * [Integrate into Shopify Headless Storefronts](/docs/shopify-stores/integrate-purple-dot-with-your-storefront/integrate-into-shopify-headless-storefronts) * [Integrate into Shopify Hydrogen Storefronts](/docs/shopify-stores/integrate-purple-dot-with-your-storefront/integrate-into-shopify-hydrogen-storefronts) ### [Before you continue](#before-you-continue) Having a product with some variant(s) on pre-order will make it easier to test each step from the integration guides above. You may re-use an exisiting product, or create a new one specifically for testing the Purple Dot integration: #### [1. Create a test product](#1.-create-a-test-product) * Go to your Shopify Admin page and go to the Products list page. * Click Add Product * Set the name of the product to `Z - Purple Dot Test Product` and make sure it is not added to any collections or tags to make it difficult for real shoppers to find * Set the sales channels to Online Store only * Give the product 3 Size options/variants * Small should be out of stock * Medium should have 1 unit of stock * Large should be out of stock * Set the price of these variants to free just in case anybody does find it #### [2. Set up its Waitlist](#2.-set-up-a-waitlist) * Go to your Purple Dot [Merchant Portal](https://www.purpledotprice.com/merchant-portal), navigate to Waitlists and click New Waitlist * Select the `Z - Purple Dot Test Product` you created earlier * Pick any future ship dates * Set up incoming pre-order stock * Small should be out of pre-order stock * Medium should have 1 unit of pre-order stock * Large should have 1 unit of pre-order stock * Save the Waitlist ### [Testing the Integration](#testing-the-integration) To check that everything is working correctly, look for the following [**On the PDP**](#on-the-pdp) Referencing the test product setup outlined earlier * When the Small variant is selected, the product appears as out of stock and no pre-order messaging is shown. * When the Medium variant is selected, the product appears as in stock and no pre-order messaging is shown. When added to cart, the standard Shopify checkout is used. * The Large variant is selected, the CTA changes to "Pre-order" and the Waitlist ship dates are displayed underneath. When added to cart, the Purple Dot checkout is used (Combined, Separate or Express) and the expected ship dates are shown. If using Express Checkout: * The express checkout opens when the Pre-order button is clicked. If using Separate Cart: * The product is added to a dedicated pre-order cart and the pre-order cart button is now showing throughout the store. If using Combined Cart: * The Purple Dot checkout is used whenever you try to check out, from the /cart page and from any quick checkout links. [**On the PLP**](#on-the-plp) If you have any quick view components or modals, any Add to Cart functionality in those should work the same as on a PDP. [**Extra testing if using Combined Cart**](#extra-testing-if-using-combined-cart) To enable this checkout type, Purple Dot ticks "Continue selling when out of stock" for every product variant that is on pre-order. Our system ensures that no oversell can occur beyond the defined pre-order stock level but only if our Pre-order button shows in every instance where the shopper can add products to their cart. Please check that: * In your Shopify store every product with a Live Waitlist has only the Online Store sales channel turned on * Purple Dot's Pre-order button shows for size Large everywhere it is possible to add products to the cart * Products on pre-order are excluded from any functionality that can automatically add products to the cart thereby bypassing Purple Dot (e.g. buy one get one free) * If you have other apps in your Shopify store that also use 3rd party checkout you must disable these once the shopper's cart contains a line item on pre-order with Purple Dot. You can check for this by inspecting if any of the line items in the Shopify cart contains a `__releaseId` property. # Integrate into Shopify Themes built with Liquid #### [1. Enable Purple Dot in your theme](#id-1.-enable-purple-dot-in-your-theme) Having completed [Install our app](/docs/shopify-stores/install-our-app) 1. Navigate to a theme where you wish to test Purple Dot 2. Click "Edit theme", then "App embeds" on the sidebar of the theme code editor 3. Search for "Purple Dot" 4. Provide the "Purple Dot API Key" and "Purple Dot Shared Secret" values that you can find at the bottom of the Integrations page in our [Merchant Portal](https://www.purpledotprice.com/merchant-portal/settings/integrations) 5. Enable the embed and save the theme #### [2. Add the Shopper Portal](#id-6.-add-the-shopper-portal) The shopper portal allows your customers to see their pre-order history and cancel pre-orders before they are fulfilled. We recommend hosting the shopper portal iframe on a new page - e.g. `/pages/manage-pre-orders` - that is linked from your support pages, similar to how a returns portal would be. The title of the page should be **Manage Pre-orders.** The following snippet should be placed on a Shopify page by editing the page's HTML: ``` ``` #### [**3. Configure Separate Cart (optional)**](#id-3.-configure-separate-cart-optional) If your preferred checkout method is to use a separate cart, there is some additional configuration required to place the separate cart icon and enable the variant selectors on liquid theme: 1. **Configure the cart placement** ```js window.PurpleDotConfig = { ... cart: { // Icon styles fill: '#000000', strokeWidth: '1.5px', matchFill: '.icon--cart', width: '22px', height: '22px', // Function to place the cart element onto the page placeElement: (cartElement, cartLink) => { const cartLinkContainer = cartLink.parentElement; const pdCartContainer = cartLinkContainer.cloneNode(); // Adjust these next two lines to your DOM, if necessary pdCartContainer.appendChild(cartElement); cartLinkContainer.insertAdjacentElement('beforebegin', pdCartContainer); // Returns the container element return pdCartContainer; }, }, }; ``` {% hint style="info" %} **Unexpected DOM structure?** Sometimes, you may find empty elements with padding/margin etc., if the theme you're working on is different to the one assumed in our previous example. If this is the case, you can set up a mutation observer on an ancestor of the cart icon like so: {% endhint %} ```js // Function to place the cart element onto the page placeElement: (cartElement, cartLink) => { const cartLinkContainer = cartLink.parentElement; const pdCartContainer = cartLinkContainer.cloneNode(); const nav = document.querySelector('nav.Header__SecondaryNav'); // Define observer callback const observer = new MutationObserver(() => { const iframe = document.querySelector('iframe.purple-dot-frame'); if (iframe.style.display === "none") { pdCartContainer.style.display = "none"; } else { // May need to adjust this line to suit your theme pdCartContainer.style.display = "inline-block"; } }); // Adjust these next two lines to your DOM, if necessary pdCartContainer.appendChild(cartElement); cartLinkContainer.insertAdjacentElement('beforebegin', pdCartContainer); // Set up observer: // IMPORTANT: 'attributes' must be true, as iframe.style.display will change observer.observe(nav, { attributes: true, childList: true, subtree: true }); // Returns the container element return pdCartContainer; }, ``` 2. **Configure variant selectors on a PDP** Sometimes, a PDP will have variant selectors that show the variant as sold out, even though the variant is available for preorder. In this case, we can target these elements, and remove a 'disabled' class (or similar) from them in order to 'enable' them. There are two ways of selecting elements (depending on whether or not they are inside an ATC form), but you must always provide a class to remove. ```js window.PurpleDotConfig = { ... pdp: { variantSelector: { // CSS selector to be queried for inside the ATC form selector: '.some-selector', // Find variant selector elements that are outside the ATC form find: () => document.querySelectorAll('.another-selector'), // Class to remove to enable the variant disabledClass: 'disabled', }, }, }; ```
# Minimum Theme Requirements For Shopify merchants integrating Purple Dot into Shopify Themes built with Liquid, the theme must meet the 3 criteria below. If you need help, please contact [support](mailto:support@getpupledot.com). ### Requirements #### [1. Add to Cart Button with type="submit" (inside \
)](#1.-add-to-cart-button-with-type-submit-inside-less-than-form-greater-than) Any button that is used to add products to the cart should have the type attribute set to `submit` and should also be inside the \ HTML element. ```html ``` #### [2. Form Element with action="/cart/add"](#2.-form-element-with-action-cart-add) Each of these buttons must be wrapped in a `` element, with the action attribute set to `/cart/add`. ```html
``` #### [3. Variant selectors](#3.-variant-selectors) Within the form, there should be an `input` or `select` element with the name attribute set to `id`. The value of this input element must be updated dynamically based on the current variant selected in the form. This ensures that Purple Dot can correctly identify the selected product variant. ```html ``` Additional requirement for a `select` based implementation is that only the `option` of the variant the shopper had actually selected is `selected`. ```html ``` ### Test your PDP Run this code in your console, when on a merchants PDP: ```javascript const form = document.querySelector('form[action*="/cart/add"]'); const variantID = form?.querySelector('[name="id"]'); const button = form?.querySelector('button[type="submit"]'); console.log('form should exist -->', !!form); console.log('form should contain an element identifying the product variant -->', !!variantID); console.log('form should contain a submit button -->', !!button); ``` # Integrate into Shopify Headless Storefronts ## Headless integration overview Purple Dot integrates with your existing storefront and enables you to create pre-order experiences. When integrating with a headless storefront Purple Dot, provides a set of components that can be used to build the integration. Purple Dot supports a number of different checkout flows for headless stores: * [**Combined**](https://docs.getpurpledot.com/docs/platform-integration-with-shopify/integrate-purple-dot-with-your-storefront/integrate-into-shopify-headless-storefronts/shopify-headless-combined-checkout)**:** This checkout method allows the shopper to add a pre-order item to their cart, but also continue shopping for other in-stock and pre-order items. When they are ready to checkout, they can be presented with a checkout that allows them to combine both pre-order and in-stock items at once, and choose to either ship them together or separately. This flow uses your store’s normal Shopify cart. * [**Express**](https://docs.getpurpledot.com/docs/shopify-stores/integrate-purple-dot-with-your-storefront/integrate-into-shopify-headless-storefronts/shopify-headless-express-checkout): This checkout method presents a quick checkout modal to the shopper that opens directly when the Add to Cart button is clicked, so that the shopper can pre-order that single item right away. This flow (also referred to as “Separate Bag”) uses Purple Dot’s own cart, separate from your Shopify cart. {% hint style="info" %} If you are unsure which checkout flow your store is configured for, please reach out to Purple Dot Support to confirm, or to switch from one checkout method to another. {% endhint %} The integration requirements will differ slightly depending on which checkout method is chosen. # Shopify Headless - Combined Checkout ## Combined checkout overview The Combined Checkout flow uses your store’s normal Shopify cart, unlike the Express flow, which uses Purple Dot’s own cart. This means that pre-order and in-stock items coexist within the same Shopify cart, and Purple Dot’s integration layers on top of your existing cart implementation to manage pre-order metadata and checkout routing. There are 5 key requirements an integration needs to implement for a Combined checkout: * **Displaying pre-order items.** Purple Dot is the source of data for which items are on pre-order and their estimated ship dates. The integration needs to show that those items are on pre-order, with the estimated ship dates, the "Learn more” informational content and a “Pre-order” call to action. * **Adding pre-order items to cart.** When adding an item to cart, the integration needs to determine if it is a pre-order, and attach the waitlist ID and ship dates if it is. * **Showing pre-order items in cart.** When a pre-order item is in the cart, the estimated ship dates need to be displayed. * **Using the Combined pre-order checkout.** The Purple Dot pre-order checkout lets shoppers checkout with pre-order items. When a pre-order item is in the cart, the integration needs to direct the shopper to the Purple Dot pre-order checkout instead of the Shopify checkout. * **Shopper portal.** The shopper self-service portal lets shoppers manage their pre-orders. The integration needs to be embedded on a page in the storefront that the shoppers will be directed to in their confirmation email. Purple Dot currently supports two types of carts: * Shopify [AJAX API cart](https://shopify.dev/docs/api/ajax/reference/cart) * Shopify [Storefront API cart](https://shopify.dev/docs/api/storefront/2023-07/queries/cart) Some aspects of the integration differ depending on what cart is being used. ### Displaying pre-order items Purple Dot is the source of data for which items are on pre-order and their estimated ship dates. The[ Pre-order availability API](#pre-order-availability-api) can be queried for the pre-order status of any product or variant on the store. When a variant has an open waitlist, it will be set to “continue selling” in Shopify, and how it should be displayed is determined by the [Pre-order availability API](#pre-order-availability-api). #### Product pages Anywhere a product can be added to cart - on product pages, or collection pages and elsewhere with add to cart controls - the integration should use the variant's pre-order state provided by the [Pre-order availability API](#pre-order-availability-api) to determine how a variant should be treated. There are 4 possible states: * `NO_WAITLISTS` state means the variant has no open waitlists and no changes need to be made. * `AVAILABLE_IN_STOCK` state means the variant has an open waitlist but also has stock available in Shopify, and should be treated like a regular in-stock product. * `ON_PREORDER` state means the variant has an open waitlist and no stock in Shopify and should be treated as a pre-order. The following should be shown: * Change the add to cart button label to “Pre-order”, if the button has a label. * Show the estimated ship dates. This is the `display_dispatch_date` as returned by the 2 [Pre-order availability API](#pre-order-availability-api) endpoints. * Show the [Learn more](#learn-more-component) component near the button. * `SOLD_OUT` state means the variant has an open waitlist but no stock in Purple Dot or Shopify. The add to cart button must be disabled and the label should be changed to “Sold out”. Whenever a new variant is selected, for example using a size or colour picker, the [Pre-order availability API](#pre-order-availability-api) state should be used to determine how to display the newly selected variant. For products with multiple variants, it is possible for some variants to be on pre-order while others are in-stock or sold out. #### Collection pages On collection pages and in any panels that list products, the integration may show a “Pre-order” label for products that are fully on pre-order, using the state provided by the product pre-order state endpoint. The possible states are the same as for a single variant, but take into account all of the product's variants, and are therefore suitable for cases where no variant is selected. ### Adding pre-order items to cart Whenever a pre-order item is added to cart, two line item properties must be added to it: * `__releaseId`, a hidden property whose value indicates which waitlist it's on. This is the `id` as returned by the 2 [Pre-order availability API](#pre-order-availability-api) endpoints. * `Purple Dot Pre-order`, a property whose value has the estimated ship dates and that indicates that something is a pre-order. This is the `display_dispatch_date` as returned by the 2 [Pre-order availability API](#pre-order-availability-api) endpoints. Whenever an item is added to cart from anywhere on the site, it's pre-order status needs to be checked, and properties added if it is in `ON_PREORDER` or `SOLD_OUT` state (nothing needs to be done if it is `NO_WAITLISTS` or `AVAILABLE_IN_STOCK`state). If using the AJAX API cart, Purple Dot provides a pre-built component (see [below](#working-with-the-cart)) that can intercept all calls to the cart API and insert the required properties automatically. If using the Storefront API, the integration must take care to always attach these properties when a pre-order item is added to cart. ### Showing pre-order items in cart When displaying items in the side cart or on a cart page, the `Purple Dot Pre-order` line item property should always be displayed. It indicates that the item is a pre-order and its estimated ship dates. Most storefronts already display the cart item properties, so this should happen automatically. If not, you need to make sure the property is shown in the side cart and on the cart page. ### Using the Combined pre-order checkout In order to hold pre-orders outside your downstream systems and for FTC compliance, the mirrored Purple Dot pre-order checkout is used when the shopper is checking out with pre-order items in their card. When a pre-order item is in the cart, the integration needs to direct the shopper to the Purple Dot checkout instead of the Shopify checkout. Purple Dot provides a pre-built component for checking the cart state (see below), which can be used to conditionally change any links to the checkout. The pre-order checkout can be opened on any page as an overlay iframe, or it can be hosted on the cart page and opened conditionally on load. ### Shopper portal The shopper portal is an iframe that embeds a portal that lets shoppers manage their pre-orders. The integration must embed the shopper portal component on a dedicated page, so that shoppers can be linked to it from their confirmation emails. ## Components Purple Dot provides a package that includes the components needed for the integration. It can be installed from `npm`, and must be included and initialised whenever the storefront is loaded. ```bash npm install -S @purple-dot/browser ``` ```jsx import * as PurpleDot from '@purple-dot/browser'; PurpleDot.init({ apiKey: 'xxx', }); ``` > 💡 Your API key can be found in the Merchant Portal under Settings > Integration. When initialised, it will inject a ` ``` {% endcode %} ## Test the Integration Follow the steps below to validate that you have successfully installed the Purple Dot cartridge. ### Business Manager \[Inventory Management] All cartridge components are located in "Merchant Tools > Site Preferences > Custom Site Preference > PurpleDot".
PurpleDot service needs to be enabled. Specify your *PurpleDot Public Key* and *PurpleDot API Key*. #### **Configure product** 1. Go to Merchant Tools > Products and Catalogs >Inventory. 2. Choose an inventory book assigned to the current site. 3. Go to the “Records” tab, find the product that should be configured and click the “Edit” button.
4. Configure the product’s availability settings by setting “Allocation” field value to 0.0 (zero). 5. Set the “None” checkbox in for the “Pre-Order/Backorder Handling” field.
Product Availability Status should change to **Not Available.** #### **Synchronize catalog and shipping methods with Purple Dot platform** 1. Go to Administration > Operations > Jobs > \[\[PurpleDot\_Job]]
2. Run each job by clicking the “Run now” button
#### **Create waitlist in the Purple Dot dashboard** 3. Create a waitlist in the PurpleDot dashboard \[Putting a Product on Pre-order]
4. Add configured product to the waitlist \[From your Catalogue]
5. Configure and save a waitlist.
### Storefront \[Visual Components – PDP, Checkout and Self Service] #### PDP On the PDP page with the configured product the custom “Pre-order” button should appear.
After adding the configured product to the pre-order list, the custom Purple Dot cart icon should appear near the default storefront cart icon. In the BM inventory data should change: * Pre-Order/Backorder Allocation: *your data*. * Availability Status: **Pre-order**.
Proceed to checkout by clicking the “Checkout” button.
The modal window with Purple Dot pre-order checkout should appear.
#### **Pre-order label** On the product tile of the configured product the “Pre-order” label should appear.
#### **Self-service widget** Click the “Pre-order history” link.
A new page with PurpleDot self-service widget should open.
### Other \[Refund, Taxes and SSO] #### **Refunds** Place an order using Purple Dot pre-order checkout. Go to the Purple Dot dashboard and find your pre-order in the “Pre-orders” tab. Click on the pre-order.
Export your pre-order to the SFCC by clicking the “Export pre-order to SFCC button”. Click the “Refund payment” button.
Enter the refund amount and click the “Confirm refund” button.
Go to the BM: `Merchant Tools > Ordering > Orders` and find order.
Check order notes. A note with the refund amount in the order’s “Notes” tab should appear in order notes. #### **Login** Login to the Purple Dot dashboard is via an email magic link of SSO. See separate documentation for SSO configuration. #### **Gift Cards** If required, ask the Purple Dot team to enable the Clutch Gift Cards integration. ## Download Documentation Download the full Purple Dot cartridge documentation: {% file src="/files/zVoyU0TmkV5m8PoDSFFX" %} v22.1.0 Docs {% endfile %} # Upgrading to 2024-08-29 We are improving our exports process for SFCC, this will require SLAS credentials for our integration and a cartridge update. You can create the required client credentials for us by following the [SFCC documentation here](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html). Specifically we need a private client which has sufficient scopes to use the [createOrders](https://developer.salesforce.com/docs/commerce/commerce-api/references/orders?meta=createOrders) API. This should be just be `sfcc.ts_ext_on_behalf_of` and `sfcc.orders.rw`. Once the client has been created you can add the new credentials in the Purple Dot integration settings page. To fully benefit from this upgrade you will also need to upgrade your client to install some additional hooks which will ensure that the shoppers email address is set correctly on the order and also automatically set the confirmed flag and export status. We will share both an updated copy of the cartridge code and also a Git repository so you can easily identify the changes between versions. ### Changes * SLAS client credentials are now required to export orders from Purple Dot to SFCC * This makes exporting easier and more reliable by decoupling it from the Basket in SFCC which means you can export orders even if the waitlist is closed, and will improve the accuracy of prices on the exported order. * Order attributes * purpleDot\_isRefunded has been removed, it was never set. * Product Line Item attributes * purpleDot\_waitlistId has been added. * purpleDot\_shipDates has been removed. * Orders will be automatically created with the following attributes * purpleDot\_isPreOrdered: true * Confirmation Status: Confirmed * Export Status: Ready to Export * Preorder line items will automatically have: * purpleDot\_waitlistId: {The ID of the waitlist the item was assigned to in Purple Dot} * purpleDot\_lineItemId: {The ID of the line item in Purple Dot} * The default checkout mode is now express instead of separate bag. ### Upgrade process To upgrade to the new release you will need to follow this process * [Create a private SLAS client](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html) with the scopes `sfcc.ts_ext_on_behalf_of` and `sfcc.orders.rw` for Purple Dot and save the client id and secret in your Purple Dot integration settings page. * Upgrade the cartridge to the latest release. If you have modified the cartridge you can follow the diff in git to apply the required changes. * In System Object Attribute settings find Product Line Items and remove the `purpleDot_shipDates` attribute. It was never used. * In System Object Attribute settings find Orders and remove the `purpleDot_isRefunded` attribute. It was never used. # Integrate into another platform *While Purple Dot natively integrates with Shopify and Salesforce, it can be easily adapted to integrate with other e-commerce platforms by using our APIs and SDKs directly.* ## Platform integration overview Purple Dot integrates with your existing storefront and enables you to create pre-order experiences. ### Choose a Checkout Flow Purple Dot supports a number of different checkout flows: * **Express:** This checkout method presents a quick checkout modal to the shopper that opens directly when the Add to Cart button is clicked, so that the shopper can pre-order one or more of that item right away without any other products. * **Separate Bag:** This checkout method is much like Express but adds a pre-order specific cart for the shopper to use to purchase multiple different pre-order items in one go. This comes with an additional pre-order cart component you can integrate into your store. This is a great option for situations in which a Shopper might want to pre-order multiple variants of the same product or products that go well together. * **Combined:** This checkout method allows the shopper to add a pre-order item to their cart, but also continue shopping for other in-stock and pre-order items. When they are ready to checkout, they can be presented with a checkout that allows them to combine both pre-order and in-stock items at once, and choose to either ship them together or separately. *This method is not publicly available on non-Shopify stores please contact Purple Dot support if you need this option.* {% hint style="info" %} If you are unsure which checkout flow your store is configured for, please reach out to Purple Dot Support to confirm, or to switch from one checkout method to another. {% endhint %} The integration requirements will differ slightly depending on which checkout method is chosen. ## Express & separate bag ### Overview There are 3 key requirements an integration needs to implement for an Express checkout: * **Displaying pre-order items.** Purple Dot is the source of data for which items are on pre-order and their estimated ship dates. The integration needs to show that those items are on pre-order, with the estimated ship dates, the "Learn more” informational content and a “Pre-order” call to action. * **Using the Express pre-order checkout.** When pre-ordering an item, instead of adding the item to the cart, the integration needs to launch our Express checkout modal and provide the variant ID, release ID, currency, and quantity. * **Embedding the Shopper portal.** The shopper self-service portal lets shoppers manage their pre-orders. The integration needs to be embedded on a page in the storefront that the shoppers will be directed to in their confirmation email. ### Displaying pre-order items Purple Dot is the source of data for which items are on pre-order and their estimated ship dates. The [Pre-order availability API](#purple-dot-browser-availability) can be queried for the pre-order status of any product or variant on the store. Anywhere a product can be added to cart (on product pages, or collection pages and elsewhere with add to cart controls) we need to decide whether the product is in stock, sold out or on pre-order. To help with this we provide an extensible product availability API which you can use to check the state of the item. #### **Pre-order pages** On pre-order pages you should check the *active variant* against the availability API. If it is on pre-order you must show the Pre-order CTA, required estimated shipping dates, and Purple Dot branding to the shopper. #### Collection pages On collection pages and in any situation in which you display a "product" rather than individual variants you may wish to display a specific "Pre-order" label on the item. The availability API can be used for this by calling it with a product handle or identifier rather than a variant. ### Purchasing pre-order items Once you've used the availability API to determine the correct state for the item, you need to trigger Purple Dot whenever the Shopper interacts with the Pre-order button via our Checkout API. For Express this will display an overlay with the first page of the pre-order checkout for the Shopper to buy the item. For separate bag this will display the shoppers pre-order cart where they can add and remove any items before continuing to checkout. ### Shopper self-service We also provide Shoppers with self-service tools for managing their pre-order such as cancelling items, or updating their payment method. This can be integrated on any page you like within your store using our SDK. ### @purple-dot/browser Purple Dot provides an [npm package](https://www.npmjs.com/package/@purple-dot/browser) that includes the components needed for the integration. It must be included and initialised whenever the storefront is loaded, likely in the root layout of your storefront application. ```bash npm install -S @purple-dot/browser ``` ```jsx import * as PurpleDot from '@purple-dot/browser'; PurpleDot.init({ apiKey: '$YOUR_API_KEY', }); ``` > 💡 Your API key can be found in the Merchant Portal under Settings > Integration. You can find examples of using the SDK here [github.com/purple-dot/browser-examples](https://www.github.com/purple-dot/browser-examples). #### @purple-dot/browser/availability The pre-order availability API should be used for determining if a product or a variant should be displayed as a pre-order and the estimated ship dates if so. Purple Dot provides a client library that can be used like: ```typescript import * as PurpleDot from '@purple-dot/browser'; import { availability } from '@purple-dot/browser/availability'; async function inStockInMyStore({ variantId }) { const response = await fetch(`/your/api/product.json?variant=${variantId}`); const data = response.json(); // Return a truthy value when the item is In Stock. return data.quantity; } const preorderState = await availability({ variantId: variant.id }, inStockInMyStore); ``` The `availability` call takes 2 arguments * `request`: An object with either a `variantId` or `productHandle` property indicating the item to look up the preorder state for. * `inStockCallback` (optional): A callback used to check if the item is instock against your own inventory system before checking the preorder status. The result is and object with this shape * `state` * `AVAILABLE_IN_STOCK` * The variant is available in stock and should not be sold as a pre-order. * `ON_PREORDER` * The variant is available as a pre-order only. * `SOLD_OUT` * The variant is neither available in stock or on a pre-order. * `waitlist` (if state is `ON_PREORDER`) * `id` - the waitlist ID * `display_dispatch_date` - the estimated ship date to display for the variant if on pre-order #### @purple-dot/browser/checkout This module provides access to the Purple Dot checkout APIs so that you can open the checkout and items to the separate bag. To start an Express checkout use `openExpressCheckout(variantId, releaseId, currency, quantity);` To add an item to the Separate Cart use `addItem(variantId, releaseId, currency, quantity);` #### Learn more component When a variant is on pre-order, the estimated ship dates and the “Pre-order protected by” branding must be displayed near the “Pre-order” call to action. Purple Dot provides a Web Component that can be used with any JS framework.

Simply place a `` HTML element near the Pre-order button. #### Separate pre-order bag When using the Separate Bag checkout you will probably want to show the shopper a separate pre-order cart next to your normal in stock item cart in your navigation. To support this we provide a `` component which can be customised to fit the look and feel of your store. This component comes with some default styling but you are free to add your own elements inside it which will override our defaults. The element will automatically have some attributes to help you style it as desired. * The `data-item-count` attribute will always be set to the current number of items in the pre-order cart. * When the shopper has pre-order items in the cart `class="purple-dot-separate-bag--has-items"` will be added to the element. You should use these to do things like hide the separate cart element when the cart is empty, or to indicate the number of items in the bag to the shopper. #### Shopper self-service portal component Purple Dot provides a portal where shoppers can manage their pre-orders. The portal can be embedded onto any page in your storefront: 1. Create a new page that can host the portal, e.g. `/account/manage-pre-orders` 2. Place a `` component where you would like the self service iframe to appear. This component is framework-agnostic and is compatible with all popular frameworks like React and Vue. # Public API ### [Overview](#webhooks) This reference documents the public API that can be used to get information about Waitlists and product availability, both server- and client-side. ### [Authentication](#authentication) Include your store's public API key as an `api_key` query parameter in all requests. ### [Versioning](#versioning) The API is versioned using a URL prefix. The current version is `v1`, and all endpoints use the `/api/v1/` namespace. ### [Response Format](#response-format) All responses follow a common format: {% code overflow="wrap" %} ```json { "meta": { "result": "success" }, "data": /* Response data */ } ``` {% endcode %} ### [Endpoints](#endpoints) [/waitlists](/docs/purple-dot-apis/public-api/waitlists) [/availability](/docs/purple-dot-apis/public-api/availability) [/products/preorder-state](/docs/purple-dot-apis/public-api/products-preorder-state) [/variants/preorder-state](/docs/purple-dot-apis/public-api/variants-preorder-state) [/pre-orders](/docs/purple-dot-apis/public-api/pre-orders) # /waitlists #### [`GET /waitlists`](#get-waitlists) Get all open Waitlists. Useful for determining which products have a Waitlist. Request query parameters: * `api_key` - Required. Your Purple Dot store's public API key Response: * `data` - An array containing all the open Waitlists * `id` - The Waitlist ID * `state` - one of: * `SCHEDULED` - to start selling pre-orders, stock levels and [Operations settings inside Purple Dot](https://www.purpledotprice.com/merchant-portal) permitting, from `launch_date` * `OPEN` - is now selling pre-orders, stock levels and Operations settings permitting * `PAUSED` - non terminal state, can be made `OPEN` in the future * `CLOSED` - terminal state, will not change again * `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 * `is_scheduled` - If this Waitlist is yet to go live in your storefront * `launch_date`: The date this Waitlist goes live in your storefront * `product` - An object containing the Waitlisted 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: ```bash curl --request GET \ --url 'https://www.purpledotprice.com/api/v1/waitlists?api_key=<...> ``` {% code overflow="wrap" %} ```json { "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" } } ] } ``` {% endcode %} # /availability #### [`GET /availability`](#get-availability) 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 query parameters: * `api_key` - Required. Your Purple Dot store's public API key * `product_id`- Required. 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](https://shopify.dev/docs/api/admin-rest/2022-07/resources/product-variant) set to `continue` in Shopify. Should be `true` for any variant in a store using the [Combined Cart](https://docs.getpurpledot.com/docs/platform-integration-with-shopify/integrate-with-shopify-using-liquid-templates#5.-setup-your-preferred-checkout-method) 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: ```bash curl --request GET \ --url 'https://www.purpledotprice.com/api/v1/availability?product_id=4697179062404&api_key=<...>' ``` {% code overflow="wrap" %} ```json { "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, } ] } } ``` {% endcode %} # /products/preorder-state #### [`GET /products/preorder-state`](#get-availability) 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 query parameters: * `api_key` - Required. Your Purple Dot store's public API key * `handle`- Required. The Shopify handle of the product * `country` - Optional. The country shopper is in Response: * `data` * `state` - One of: * `NO_OPEN_WAITLISTS` - there is no live or scheduled Waitlist inside Purple Dot for this product * `AVAILABLE_IN_STOCK` - when at least 1 variant is `AVAILABLE_IN_STOCK` * `ON_PREORDER` - when none of the variants are `AVAILABLE_IN_STOCK` but at least 1 variant is `ON_PREORDER` * `SOLD_OUT` - when all variants are `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. Examples: ```bash curl --request GET \ --url 'https://www.purpledotprice.com/api/v1/products/preorder-state?api_key=<...>&handle=womens-white-sneakers' ``` {% code overflow="wrap" %} ```json { "meta": { "result": "success" }, "data": [ { "state": "ON_PREORDER", "waitlist": { "id": "00fe49ba-8e43-4b10-9588-dccaa30f19ac", "display_dispatch_date": "Estimated ship date 10–15 Jun", "payment_plan_descriptions": null, "selling_plan_id": null, }, "product": { "id": "4697179062404", "product_code": "womens-white-sneakers" } } ] } ``` {% endcode %} # /variants/preorder-state #### [`GET /variants/preorder-state`](#get-availability) 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 query parameters: * `api_key` - Required. Your Purple Dot store's public API key * `variant_id`- Required. The Shopify variant id of the product variant * `country` - Optional. The country shopper is in Response: * `data` * `state` - One of: * `NO_OPEN_WAITLISTS` - there is no live or scheduled Waitlist inside Purple Dot for this variant * `AVAILABLE_IN_STOCK` - there is a live or scheduled Waitlist inside Purple Dot but the variant is not selling as a pre-order because one of your Shopify locations has stock for it and the [Operations settings inside Purple Dot](https://www.purpledotprice.com/merchant-portal) to "Watch inventory levels in Shopify" dictate that this should be cleared down first before this variant starts to sell as a pre-order. * `ON_PREORDER` - the variant will sell as a pre-order, either because you have * no stock in your own Shopify locations and some stock on a live Waitlist * you have some stock in your own Shopify locations but set your Operations settings inside Purple Dot to not "Watch inventory levels in Shopify" * `SOLD_OUT` - there is no stock remaining for this variant, neither in your own Shopify locations, nor on any Waitlist * `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. Examples: ```bash curl --request GET \ --url 'https://www.purpledotprice.com/api/v1/variants/preorder-state?api_key=<...>&variant_id=55391387124086' ``` {% code overflow="wrap" %} ```json { "meta": { "result": "success" }, "data": { "state": "ON_PREORDER", "waitlist": { "id": "00fe49ba-8e43-4b10-9588-dccaa30f19ac", "is_scheduled": false, "launch_date": null, "selling_plan_id": null, "display_dispatch_date": "Estimated ship date 1–8 Jul", "payment_plan_descriptions": null, "use_extended_delivery_language": false, "units_left": 1 }, "product": { "id": "15121333223798", "handle": "the-complete-snowboard" } } } ``` {% endcode %} # /pre-orders ### [Authentication](#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 paramWhere to find it
api_keyThis is available on the integration page on your merchant portal under 'Public API Key'
emailThis is the email of the shopper you're looking up the info for
timestampThis is the browser timestamp in the epoch format
tokenThis 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 below.
#### How to generate the `token` Purple Dot expects a SHA-256 hash of the `email` and the `timestamp` in the following format: `:` This allows us to verify the integrity and authenticity of the request by having it securely assigned using a shared secret. The generated token will only be valid for 10 seconds within the timestamp; to make the same API call for updated data, a new token must be generated. You can generate the token within a Shopify theme in a `.liquid` file as shown below: ```liquid {% assign timestamp = 'now' | date: '%s' %} {% assign token_value = customer.email | append: ':' | append: timestamp %} {% assign token = token_value | hmac_sha256: 'YOUR_SHARED_SECRET' %} ``` To generate the token using Javascipt and the native [browser `crypto` APIs](https://developer.mozilla.org/en-US/docs/Web/API/Crypto), you can add the following ` ``` If testing this in an API tool like Postman, you can generate the token using a pre-request script. Within Postman, you can import the `crypto-js` library, which simplifies some of the token generation ```javascript const crypto = require('crypto-js'); const API_KEY = 'YOUR_API_KEY'; const SHARED_SECRET = 'YOUR_SHARED_SECRET'; const email = 'customer@example.com'; const timestampInSeconds = Math.floor(Date.now() / 1000); const tokenValue = `${email}:${timestampInSeconds}`; const hash = crypto.HmacSHA256(tokenValue, SHARED_SECRET); const token = crypto.enc.Hex.stringify(hash); pm.request.addQueryParams(`api_key=${API_KEY}&token=${token}×tamp=${timestampInSeconds}&email=${email}`); ``` #### [`GET /pre-orders`](#get-pre-orders) Get all pre-orders for a given shopper email address. Request: * `limit` (number) - Optional. The number of pre-orders to retrieve. Set to 10 by default but can be set up to 100 * `starting_after` (UUID) - Optional. 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` - ISO8610 timestamp of when the pre-order was placed * `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: {% code overflow="wrap" %} ```bash curl --request GET \ --url 'https://www.purpledotprice.com/api/v1/pre-orders?api_key=<>&email=<>×tamp=<>&token=<>' ``` {% endcode %} ```json { "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": "+441974616161" } } ], "has_more": true, "starting_after": "2174855e-0f3c-482d-9cf0-f2b5cb6213cf" } } ``` # Private API ### [Overview](#webhooks) This reference documents the private API that can be used to access private data in Purple Dot. ### [Authentication](#authentication) Include your Purple Dot store's private access token as `X-Purple-Dot-Access-Token` header in all requests. ### [Versioning](#versioning) The API is versioned using a URL prefix. The current version is `v1`, and all endpoints use the `/admin/api/v1/` namespace. ### [Response Format](#response-format) All responses follow a common format: {% code overflow="wrap" %} ```json { "meta": { "success": true }, "data": /* Response data */ } ``` {% endcode %} ### [Endpoints](#endpoints) [/waitlists](/docs/purple-dot-apis/private-api/waitlists) [/pre-orders](/docs/purple-dot-apis/private-api/pre-orders) [/pre-orders/count](/docs/purple-dot-apis/private-api/pre-orders-count) [/pre-orders/count-units/sku/:sku](/docs/purple-dot-apis/private-api/pre-orders-count-units-sku-sku) [/inventory](/docs/purple-dot-apis/private-api/inventory) [/fulfillment-orders](/docs/purple-dot-apis/private-api/fulfillment-orders) [/fulfillment-orders/:id(uuid)](/docs/purple-dot-apis/private-api/fulfillment-orders-id-uuid) [/fulfillment](/docs/purple-dot-apis/private-api/fulfillment) [/refund](/docs/purple-dot-apis/private-api/refund) #### # /waitlists #### GET /admin/api/v1/waitlists Request: * `limit` (number) - Optional. The number of waitlists to retrieve. Set to 10 by default but can be set up to 100 * `created_at_min` (ISO8610 timestamp) - Optional. List waitlists created since the given time * `updated_at_min` (ISO8610 timestamp) - Optional. List waitlists updated since the given time * `starting_after` (UUID) - Optional. Paginate pre-orders after the given waitlist ID Headers: * `Link` - An IETF [RFC 8288](https://datatracker.ietf.org/doc/html/rfc8288#section-2) compliant header with links to previous and next page of results for the preorder query. Body: * `waitlists` - An array containing waitlists * `id` - ID used to identify the waitlist inside Purple Dot * `created_at` - ISO8610 timestamp of when the waitlist was created * `updated_at` - ISO8610 timestamp of when the waitlist was last updated * `earliest_ship_date` - ISO8610 timestamp of the earliest date the waitlisted product can ship * `latest_ship_date` - ISO8610 timestamp of the latest date the waitlisted product can ship * `state` - The state of the waitlist. This can be one of the following: * `LIVE` - Shoppers can start placing preorders for this product if there is no stock in Shopify * `PAUSED` - Shoppers cannot place preorders for this product until the waitlist is unpaused * `CLOSED` - Waitlist is now closed * `SCHEDULED` - Waitlist will be live on the launch date * `DRAFT` - Waitlist is in draft state and needs approval before going live * `launch_date` - ISO8610 timestamp of when the waitlist will be live * `scheduled_pause_date` - ISO8610 timestamp of when the waitlist will be paused * `labels` - Labels associated with the waitlist * `availability` - A map of the product & variant-wise sales data * `product` - Sales data for the product * `product_id` - Shopify ID for the product * `buy_size` - Total number of units allocated for preorder * `committed` - Total number of preorder units sold * `available` - Total number of preorder units available for sale * `variants` - An array of the sales data for all the product variants * `variant_id` - Shopify ID of the product variant * `sku` - SKU code of the product variant * `buy_size` - Total number of units of the product variant allocated for preorder (this will be null in the case of a per-product waitlist) * `committed` - Total number of preorder units of the product variant sold * `available` - Total number of preorder units available of the product variant for sale (this will be null in the case of a per-product waitlist) * `starting_after` - The ID of the last waitlist in the list which can then be used in the next request * `has_more` - Indicates whether there are more orders available to page through Examples: ```bash curl --request GET \ --url 'https://www.purpledotprice.com/admin/api/v1/waitlists?limit=1&created_at_min=2023-08-17T00:00:00.000Z' \ --header 'X-Purple-Dot-Access-Token: ' ```
This is what a per-variant waitlist response would look like: ```json { "meta":{ "result":"success" }, "data":{ "waitlists":[ { "id":"a2aecc56-ce64-49da-8ce6-099e664d85fd", "created_at":"2023-10-27T14:44:09.726Z", "earliest_ship_date":"2023-11-25T05:00:00.000Z", "latest_ship_date":"2023-12-10T04:59:59.999Z", "state":"CLOSED", "launch_date":"2023-12-10T00:00:00.000Z", "labels":[ ], "availability":{ "product":{ "product_id":"7257265143861", "buy_size":10, "committed":3, "available":10 }, "variants":[ { "variant_id":"42662551519285", "sku":"ZTEST", "buy_size":10, "committed":3, "available":10 } ] } } ], "has_more":true, "starting_after":"a2aecc56-ce64-49da-8ce6-099e664d85fd", "previous_cursor":"0c34fc59-8a99-427f-a340-857e1eb9b6d2" } } ```
This is what a per-product waitlist response would look like: ```json { "meta":{ "result":"success" }, "data":{ "waitlists":[ { "id":"c657585b-bfe0-4aca-867d-e2c3399969a3", "created_at":"2023-09-20T16:57:55.928Z", "earliest_ship_date":"2024-04-08T04:00:00.000Z", "latest_ship_date":"2024-04-19T04:00:00.000Z", "state":"CLOSED", "launch_date":null, "labels":[ ], "availability":{ "product":{ "product_id":"7233472626741", "buy_size":10, "committed":4, "available":10 }, "variants":[ { "variant_id":"42591503876149", "sku":"TEST-S", "buy_size":null, "committed":2, "available":null }, { "variant_id":"42591503843381", "sku":"TEST-M", "buy_size":null, "committed":1, "available":null }, { "variant_id":"42591503777845", "sku":"TEST-L", "buy_size":null, "committed":1, "available":null } ] } } ], "has_more":true, "starting_after":"c657585b-bfe0-4aca-867d-e2c3399969a3", "previous_cursor":null } } ```
#### POST /admin/api/v1/waitlists (Preview) Creates a new waitlist. Fails with `409 Conflict` if a waitlist already exists for the same product and ship date range. **Request Body** * `product_id` (string, required) — External product ID; the numeric suffix as a string (e.g. `"123"`) * `earliest_ship_date` (string, required) — ISO 8601 date; earliest expected ship date * `latest_ship_date` (string, required) — ISO 8601 date; latest expected ship date * `max_units` (array, required) — Per-SKU max units; at least one entry required. Each entry: * `sku_id` (string, required) — External SKU/variant ID; the numeric suffix as a string (e.g. `"456"`) * `max_units` (number, required) — Maximum units for this SKU (non-negative integer) * `state` (string, required) — One of: `OPEN`, `PAUSED`, `CLOSED`, `DRAFT` * `labels` (array, required) — Array of label strings (can be empty) **Example Request** ```json { "product_id": "123", "earliest_ship_date": "2025-03-01", "latest_ship_date": "2025-03-15", "max_units": [ { "sku_id": "456", "max_units": 50 }, { "sku_id": "789", "max_units": 30 } ], "state": "OPEN", "labels": ["spring-2025"] } ``` **Response** `201 Created` ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "product_id": "123", "state": "OPEN", "earliest_ship_date": "2025-03-01T00:00:00.000Z", "latest_ship_date": "2025-03-15T00:00:00.000Z", "max_units": [ { "sku_id": "456", "max_units": 50 }, { "sku_id": "789", "max_units": 30 } ], } ``` **Errors** * `400 Bad Request` — Invalid or missing required fields * `404 Not Found` — Product or variant not found for the store * `409 Conflict` — A waitlist already exists for this product and ship dates *** #### PUT /admin/api/v1/waitlists (Preview) Creates a new waitlist or updates an existing one, matched by product and ship date range. If a matching waitlist exists, it is updated; otherwise a new one is created. **Request Body** Same as Create Waitlist. **Response** `200 OK` Same structure as the Create response. Returns the created or updated waitlist. **Errors** * `400 Bad Request` — Invalid or missing required fields * `404 Not Found` — Product or variant not found for the store *** #### PUT /admin/api/v1/waitlists/:releaseId (Preview) Updates an existing waitlist by its ID. Use this when you know the waitlist's `id` (e.g. from a previous create/upsert or list response). **URL Parameters** * `releaseId` (string) — UUID of the waitlist to update **Request Body** Same as Create Waitlist. The `product_id` in the body must match the waitlist's current product. **Example Request** ``` PUT /waitlists/550e8400-e29b-41d4-a716-446655440000 Content-Type: application/json ``` ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "product_id": "123", "earliest_ship_date": "2025-03-01", "latest_ship_date": "2025-03-20", "max_units": [ { "sku_id": "456", "max_units": 75 } ], "state": "PAUSED", "labels": ["spring-2025", "delayed"] } ``` **Response** `200 OK` Same structure as the Create response. **Errors** * `400 Bad Request` — Invalid fields or `product_id` does not match the waitlist * `404 Not Found` — Waitlist not found, or belongs to another store # /pre-orders #### [`GET /pre-orders`](#list-all-pre-orders) #### List all pre-orders. Note for customers using our platform integration with combined cart: this data does not include in-stock purchases that went through Purple Dot's checkout. Request: * `limit` (number) - Optional. The number of pre-orders to retrieve. Set to 10 by default but can be set up to 200 * `created_at_min` (ISO8610 timestamp) - Optional. List pre-orders created since the given time * `updated_at_min` (ISO8610 timestamp) - Optional. List pre-orders updated since the given time * `updated_at_max` (ISO8610 timestamp) - Optional. List pre-orders updated no sooner than the given time * `references` (string) - Optional. Comma separated list of (URL-encoded) Purple Dot order references * `skus` (string) - Optional. Comma separated list of product variant SKUs * `email` (string) - Optional. List pre-orders placed by the given email * `all_line_items` (string) - Optional. List pre-orders where every line item is any of these comma separated states. Currently supported are `cancelled` and `exported` * `some_line_item` (string) - Optional. List pre-orders where at least 1 line item is any of these comma separated states. Currently supported are `cancelled` and `exported`. Cannot be used in conjunction with `all_line_items` * `starting_after` (UUID) - Optional. Paginate pre-orders after the given pre-order ID Headers: * `Link` - An IETF [RFC 8288](https://datatracker.ietf.org/doc/html/rfc8288#section-2) compliant header with links to previous and next page of results for the pre-order query. Body: * `orders` - An array containing pre-orders * `id` - ID used to identify the pre-order inside Purple Dot * `reference` - The Purple Dot order reference, the same as shared with the shoppers * `currency` - The presentment currency of the order * `created_at` - ISO8610 timestamp of when the pre-order was placed * `cancelled_at` - ISO8610 timestamp of when the whole order was canceled (null if not canceled) * `cancel_reason` - The reason for the cancelation * `customer` * `email` - The customer's email address * `external_id` - The Shopify ID of this customer, if we know it * `line_items` - Array of line items * `id` - The Purple Dot ID of the line item * `name` - The name of the product variant in this line item * `sku` - The SKU code of the product variant in this 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 * `waitlist_id` - The Purple Dot ID of the Waitlist this line item sold from. Could be null if the line item was in-stock at the time of sale but it was held back to ship with other line items that were on pre-order * `quantity` - The quantity of the line item * `price` - The total cost of this line item, before taxes/discounts etc * `unit_price` - `price` divided by `quantity` * `taxable` - Whether the product variant in this line item is taxable * `tax_lines` - The taxes applied to the line item * `price` - The total amount of tax for the line item * `rate` - The tax rate as a decimal * `title` - The name of the tax * `inclusive` - Whether this tax is already included in the line item price * `total_discount` - The total amount of discounts applied to the line item * `total` - The total cost of this line item, after tax/discounts etc * `unit_total` - `total` divided by `quantity` * `earliest_ship_date` - ISO8610 timestamp of the earliest date this line item is expected to ship * `latest_ship_date` - ISO8610 timestamp of the latest date this line item is expected to ship * `cancelled` - If this line item has been canceled * `cancelled_at` - ISO8610 timestamp of when the whole order was canceled (null if not canceled) * `shipping_address` * `first_name` * `last_name` * `address1` * `address2` * `city` * `postal_code` * `province_code` - The ISO3166 code of the second level administrative subdivision * `country` - The English name of the country * `country_code` - The ISO3166 code of the country * `phone` * `shipping_lines` - An array of shipping rates * `id` - The Purple Dot ID of the shipping line * `price` - The unit cost of this shipping line, before taxes/discounts etc * `total`- The total cost of this shipping line, after tax/discounts etc are considered * `title` - The user-facing name of the shipping rate * `code` - The shipping rate carrier code * `tax_lines` - The taxes applied to the shipping rate * `price` - The total amount of tax for the shipping line * `rate` - The tax rate as a decimal * `title` - The name of the tax * `inclusive` - Whether this tax is already included in the shipping line price * `line_items` - The line items this shipping rate applies to * `line_item_id` - The Purple Dot ID of the line item * `subtotal_price` - The total of the line items before taxes and shipping * `total_discounts` - The total discounts applied to the pre-order * `total_tax` - The total tax on the pre-order * `tax_included` - Whether the tax is included in listed prices or not * `tax_lines` - All the taxes applied to the pre-order * `price` * `rate` * `title` * `total_price` - The pre-order total * `total_refunded` - The total of all refunds issued from this pre-order * `exported_orders` - Any orders that were exported to Shopify from this pre-order * `id` - The Shopify ID of the order that was exported * `order_number` - The Shopify order number * `created_at` - ISO8610 timestamp of when this external order was created * `line_items` - The pre-order line items that were exported * `id` - The Shopify ID of the line item * `line_item_id` - The Purple Dot ID of the line item * `sales_channel` - This can be "online" or "pos" * `pos_sale` - This is available if the order was placed through Purple Dot POS * `staff_name` - The member of staff who completed the sale * `location_name` - The Shopify location name where the order was placed * `starting_after` - The ID of the last pre-order in the list which can then be used in the next request * `has_more` - Indicates whether there are more pre-orders available to page through Examples: {% code overflow="wrap" %} ``` curl --request GET \ --url 'https://www.purpledotprice.com/admin/api/v1/pre-orders?created_at_min=2023-08-17T00:00:00.000Z&references=%23PD325376&all_line_items=cancelled&skus=TEST1&limit=1' \ --header 'X-Purple-Dot-Access-Token: ' ``` {% endcode %} 
{
  "meta": {
    "result": "success"
  },
  "data": {
    "orders": [
      {
        "id": "58da51c9-9b48-48c6-beb5-46bd34834960",
        "reference": "#PD2850312",
        "cancel_reason": null,
        "cancelled_at": null,
        "created_at": "2024-11-14T16:18:25.635Z",
        "currency": "USD",
        "email": "test@getpurpledot.com",
        "customer": {
          "email": "test@getpurpledot.com",
          "external_id": "7287702192181"
        },
        "line_items": [
          {
            "id": "55bedf52-ccf0-431a-a75b-2e999e93a5da",
            "total": 26.01,
            "price": 39.99,
            "product_id": "6914583167029",
            "quantity": 1,
            "sku": "PS4-GRVN",
            "variant_id": "41125120573493",
            "name": "Test Product 1",
            "earliest_ship_date": "2025-03-01T05:00:00.000Z",
            "latest_ship_date": "2025-03-31T04:00:00.000Z",
            "taxable": true,
            "tax_lines": [
              {
                "price": 2.12,
                "rate": 0.08875,
                "title": "SALES_TAX",
                "inclusive": false
              }
            ],
            "total_discount": 16.1,
            "cancelled_at": null,
            "cancelled": false,
          },
          {
            "id": "e474a996-d861-41e0-8137-7fc2074dd6a5",
            "total": 22.75,
            "price": 34.99,
            "product_id": "7740980330549",
            "quantity": 1,
            "sku": "P5LR123",
            "variant_id": "44057813581877",
            "name": "Test Product 2",
            "earliest_ship_date": null,
            "latest_ship_date": null,
            "taxable": true,
            "tax_lines": [
              {
                "price": 1.85,
                "rate": 0.08875,
                "title": "SALES_TAX",
                "inclusive": false
              }
            ],
            "total_discount": 14.09,
            "cancelled_at": "2024-11-14T16:20:39.796Z",
            "cancelled": true
          }
        ],
        "shipping_address": {
          "address1": "10 Test Road",
          "address2": "",
          "city": "New York",
          "country": "United States",
          "country_code": "US",
          "first_name": "Test",
          "last_name": "Testington",
          "phone": "+19172756975",
          "province_code": "NY",
          "postal_code": "10463"
        },
        "shipping_lines": [
          {
            "id": "6dfe69ca-ba0e-5af5-864c-693982161631",
            "code": "usps_1058",
            "total": 3.9000000000000004,
            "price": 5.98,
            "title": "Calculated Shipping Rate",
            "tax_lines": [
              {
                "price": 0.32,
                "rate": 0.08875,
                "title": "SALES_TAX",
                "inclusive": false
              }
            ],
            "line_items": [
              {
                "line_item_id": "e474a996-d861-41e0-8137-7fc2074dd6a5"
              }
            ]
          },
          {
            "id": "ca1dc988-7078-5f95-b1a8-3c0722d41ba4",
            "code": "usps_1058",
            "total": 3.88,
            "price": 5.98,
            "title": "Calculated Shipping Rate",
            "tax_lines": [
              {
                "price": 0.31,
                "rate": 0.08875,
                "title": "SALES_TAX",
                "inclusive": false
              }
            ],
            "discount_allocations": [
              {
                "amount": 2.41,
                "discount_application_index": 0
              }
            ],
            "line_items": [
              {
                "line_item_id": "55bedf52-ccf0-431a-a75b-2e999e93a5da"
              }
            ]
          }
        ],
        "subtotal_price": 39.99,
        "tax_lines": [
          {
            "price": 2.12,
            "rate": 0.08875,
            "title": "SALES_TAX"
          }
        ],
        "tax_included": false,
        "total_discounts": 20.91,
        "total_price": 21.2,
        "total_tax": 2.12,
        "total_refunded": 56.54,
        "exported_orders": [
          {
            "id": "5616927408181",
            "created_at": "2024-11-14T16:22:59.432Z",
            "order_number": "#3114029",
            "line_items": [
              {
                "id": "13278614585397",
                "line_item_id": "55bedf52-ccf0-431a-a75b-2e999e93a5da"
              }
            ]
          }
        ],
        "sales_channel": "online",
        "pos_sale": null
      }
    ],
    "starting_after": "58da51c9-9b48-48c6-beb5-46bd34834960",
    "has_more": false,
    "previous_cursor": "935bad68-2726-4ad1-b299-a330650a2bbb"
  }
}
# /pre-orders/count #### [`GET /pre-orders/count`](#count-all-pre-orders) #### Count all pre-orders. Request: * `created_at_min` (ISO8610 timestamp) - Optional. Count pre-orders created since the given time * `updated_at_min` (ISO8610 timestamp) - Optional. Count pre-orders updated since the given time * `updated_at_max` (ISO8610 timestamp) - Optional. Count pre-orders updated no sooner than the given time * `skus` (string) - Optional. Comma separated list of product variant SKUs * `email` (string) - Optional. List pre-orders placed by the given email * `all_line_items` (string) - Optional. Count pre-orders where every line item is any of these comma separated states. Currently supported are `cancelled` and `exported` * `some_line_item` (string) - Optional. Count pre-orders where at least 1 line item is any of these comma separated states. Currently supported are `cancelled` and `exported`. Cannot be used in conjunction with `all_line_items` Body: * `count` - The number of pre-orders that meet the requested criteria Examples: {% code overflow="wrap" %} ``` curl --request GET \ --url 'https://www.purpledotprice.com/admin/api/v1/pre-orders/count?created_at_min=2023-08-17T00:00:00.000Z&all_line_items=cancelled&skus=TEST1&limit=1' \ --header 'X-Purple-Dot-Access-Token: ' ``` {% endcode %} {% code overflow="wrap" %} ```json { "meta": { "result": "success" }, "data": { "count": 1 } } ``` {% endcode %} # /pre-orders/count-units/sku/:sku #### [`GET /pre-orders/count-units/sku/:sku`](#count-all-pre-orders) #### Count open, canceled and exported units for the given SKU. Request: * `at_time` (ISO8610 timestamp) - Optional. Count open/canceled/exported units as of this timestamp. Defaults to now. Body: * `sku` - The SKU code of interest * `at_time` - ISO8610 timestamp of the count calculation * `open_units` - The number of units purchased through and still being held in Purple Dot because they are not yet ready for fulfilment. Excludes any units that are canceled or exported. An open unit can become either canceled or exported, not both. * `canceled_units` - The number of units purchased through and held in Purple Dot that were later canceled (either by the shopper or the merchant). * `exported_units` - The number of units purchased through Purple Dot that were held in Purple Dot that were later exported to the external eCommerce platform. Examples: {% code overflow="wrap" %} ``` curl --request GET \ --url 'https://www.purpledotprice.com/admin/api/v1/pre-orders/count-units/sku/LRS221?at_time=2023-08-18T09:57:49.576Z' \ --header 'X-Purple-Dot-Access-Token: ' ``` {% endcode %} {% code overflow="wrap" %} ```json { "meta": { "result": "success" }, "data": { "sku": "LRS221", "at_time": "2023-08-18T09:57:49.576Z", "open_units": 14, "canceled_units": 15, "exported_units": 12, } } ``` {% endcode %} # /inventory #### [`POST /inventory`](#update-the-available-inventory-used-by-purple-dot-for-exporting-pre-orders) #### Update the available inventory used by Purple Dot for exporting pre-orders. Request: * `sku` - Required. The SKU for which inventory level is being updated * `available_units` - Required. The number of units of this SKU that are available The request indicates the total number of units available, not the change since the last call, and is therefore idempotent. Response: * `201 Created` - Indicating the update has been received * `sku` - The SKU for which the inventory level was updated * `available_units` - The new number of units available Examples: ```bash curl --request POST \ --url 'https://www.purpledotprice.com/admin/api/v1/inventory' \ --header 'Content-Type: application/json' --header 'X-Purple-Dot-Access-Token: ' --data '{"sku": "foo", "available_units": 1}' ``` {% code overflow="wrap" %} ```json { "data": { "sku": "foo", "available_units": 1 } } ``` {% endcode %} # /fulfillment-orders #### `GET /fulfillment-orders` #### List all fulfillment orders. Request: * `limit` (number) - Optional. The number of fulfillment orders to retrieve. Set to 50 by default but can be set up to 250 * `created_at_min` (ISO8610 timestamp) - Optional. List fulfillment orders created since the given time * `starting_after` (UUID) - Optional. Paginate fulfillment orders after the given fulfillment order ID * `references` (string) - Optional. Comma separated list of (URL-encoded) Purple Dot fulfillment order references Body: * `fulfillment_orders` - An array containing fulfillment orders across pre-orders that are now fulfillable * `id` - The Purple Dot ID of the fulfillment order * `status` - The current status of the fulfillment order, which can be one of: * `UNFULFILLED` - the order has been placed and is waiting to be fulfilled * `FULFILLED` - all items have been fulfilled * `VOIDED` - the order was canceled * `created_at` (ISO8610 timestamp) - when this fulfillment order was created (effectively, when Purple Dot was told the related line items are ready to be fulfilled) * `purchased_at` (ISO8610 timestamp) - the `created_at` of the pre-order this fulfillment order originates from * `reference` - The Purple Dot fulfillment order reference, defined as `concat(Purple Dot pre-order reference, fulfillment order index)` * `customer` - The customer placing the order * `email` - The customer's email address * `external_id` - The Shopify ID of this customer, if we know it * `first_name` * `last_name` * `tags` - Shopify tags for the customer * `default_address` * `first_name` * `last_name` * `address1` * `address2` * `city` * `postal_code` * `province_code` - The ISO3166 code of the second level administrative subdivision * `country` - The English name of the country * `country_code` - The ISO3166 code of the country * `phone` * `currency` - The presentment currency of the order * `subtotal_price` - The total of the line items before taxes and shipping * `total_tax` - The total tax on the pre-order * `tax_included` - Whether the tax is included in listed prices or not * `total_discounts` - The total discounts applied to the fulfillment order * `total_price` - The fulfillment order total * `line_items` - Array of line items in this fulfillment order * `id` - The Purple Dot ID of the line item * `name` - The name of the product variant in this 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 * `sku` - The SKU code of the product variant in this line item * `price` - The unit cost of the product variant in this line item, before taxes/discounts etc * `quantity` - The quantity of the line item * `taxable` - Whether the product variant in this line item is taxable * `tax_lines` - The taxes applied to the line item * `price` - The total amount of tax for the line item * `rate` - The tax rate as a decimal * `title` - The name of the tax * `inclusive` - Whether this tax is already included in the line item price * `total_discount` - The total amount of discounts applied to the line item * `total` - The total cost of this line item, after tax/discounts etc, are considered * `shipping_address` * `first_name` * `last_name` * `address1` * `address2` * `city` * `postal_code` * `province_code` - The ISO3166 code of the second level administrative subdivision * `country` - The English name of the country * `country_code` - The ISO3166 code of the country * `phone` * `shipping_lines` - An array of shipping rates * `id` - The Purple Dot ID of the shipping line * `price` - The unit cost of this shipping line, before taxes/discounts etc * `total`- The total cost of this shipping line, after tax/discounts etc, are considered * `title` - The user-facing name of the shipping rate * `code` - The shipping rate carrier code * `tax_lines` - The taxes applied to the shipping rate * `price` - The total amount of tax for the shipping line * `rate` - The tax rate as a decimal * `title` - The name of the tax * `inclusive` - Whether this tax is already included in the shipping line price * `note` - optional notes from the Shopify order * `starting_after` - The ID of the last fulfillment order in the list, which can then be used in the next request * `has_more` - Indicates whether there are more fulfillment orders available to page through Examples: {% code overflow="wrap" %} ``` curl --request GET \ --url 'https://www.purpledotprice.com/admin/api/v1/fulfillment_orders?created_at_min=2023-08-17T00:00:00.000Z&limit=1' \ --header 'X-Purple-Dot-Access-Token: ' ``` {% endcode %} {% code overflow="wrap" %} ```json ``` {% endcode %} ``` curl --request GET \ --url 'https://www.purpledotprice.com/admin/api/v1/fulfillment_orders?references=#PD12345678/2,#PD87654321/1' \ --header 'X-Purple-Dot-Access-Token: ' ``` # /fulfillment-orders/:id(uuid) #### `GET /fulfillment-orders/:id(uuid)` #### Fetch a specific fulfillment order. Body: * `id` - The Purple Dot ID of the fulfillment order * `status` - The current status of the fulfillment order, which can be one of: * `UNFULFILLED` - the order has been placed and is waiting to be fulfilled * `FULFILLED` - all items have been fulfilled * `VOIDED` - the order was canceled * `created_at` (ISO8610 timestamp) - When this fulfillment order was created (effectively, when Purple Dot was told the related line items are ready to be fulfilled) * `purchased_at` (ISO8610 timestamp) - the `created_at` of the pre-order this fulfillment order originates from * `reference` - The Purple Dot fulfillment order reference, defined as `concat(Purple Dot pre-order reference, fulfillment order index)` * `currency` - The presentment currency of the order * `customer` - The customer placing the order * `email` - The customer's email address * `external_id` - The Shopify ID of this customer, if we know it * `first_name` * `last_name` * `tags` - Shopify tags for the customer * `default_address` * `first_name` * `last_name` * `address1` * `address2` * `city` * `postal_code` * `province_code` - The ISO3166 code of the second level administrative subdivision * `country` - The English name of the country * `country_code` - The ISO3166 code of the country * `phone` * `tax_included` - Whether the tax is included in listed prices or not * `total_tax` - The total tax on the pre-order * `total_discounts` - The total discounts applied to the fulfillment order * `subtotal_price` - The total of the line items before taxes and shipping * `total_price` - The fulfillment order total * `line_items` - Array of line items in this fulfillment order * `id` - The Purple Dot ID of the line item * `price` - The unit cost of the product variant in this line item, before taxes/discounts etc * `total` - The total cost of this line item, after tax/discounts etc are considered * `taxable` - Whether the product variant in this line item is taxable * `tax_lines` - The taxes applied to the line item * `price` - The total amount of tax for the line item * `rate` - The tax rate as a decimal * `title` - The name of the tax * `inclusive` - Whether this tax is already included in the line item price * `total_discount` - The total amount of discounts applied to the line item * `quantity` - The quantity 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 * `sku` - The SKU code of the product variant in this line item * `name` - The name of the product variant in this line item * `shipping_address` * `first_name` * `last_name` * `address1` * `address2` * `city` * `postal_code` * `province_code` - The ISO3166 code of the second level administrative subdivision * `country` - The English name of the country * `country_code` - The ISO3166 code of the country * `phone` * `shipping_lines` - An array of shipping rates * `id` - The Purple Dot ID of the shipping line * `price` - The unit cost of this shipping line, before taxes/discounts etc * `total`- The total cost of this shipping line, after tax/discounts etc are considered * `title` - The user-facing name of the shipping rate * `code` - The shipping rate carrier code * `tax_lines` - The taxes applied to the shipping rate * `price` - The total amount of tax for the shipping line * `rate` - The tax rate as a decimal * `title` - The name of the tax * `inclusive` - Whether this tax is already included in the shipping line price * `note` - optional notes from the Shopify order Examples: {% code overflow="wrap" %} ``` curl --request GET \ --url 'https://www.purpledotprice.com/admin/api/v1/fulfillment_order/a1b2c3d4-e5f6-7890-1234-567890abcdef' \ --header 'X-Purple-Dot-Access-Token: ' ``` {% endcode %} # /fulfillment #### `POST /fulfillment` #### Create a fulfillment for a fulfillment order. Request: * `fulfillment` * `fulfillment_order_id` (UUID) - Required. The ID of the Fulfillment Order you are fulfilling * `line_items` (array) - Optional. If left blank, all line items will be fulfilled * `id` (string) - Required. The Purple Dot ID of the line item * `quantity`(number) - Required. The quantity of that line item that are being fulfilled * `notify_customer` (boolean) - Optional. Whether the customer is notified. If `true`, then a notification is sent when the fulfillment is created. The default value is `false` * `tracking_info` - Optional. * `number` (string) - The tracking number of the fulfillment * `url` (string) - The URL to track the fulfillment Example payload: ``` { "fulfillment": { "fulfillment_order_id": "00000000-00000000-00000000-00000000", "line_items": [ { "id": "00000000-00000000-00000000-00000000", "quantity": 5 } ], "notify_customer": true, "tracking_info": { "number": "1234567890", "url": "https://www.myshipping.com/track/?tracknumbers=1234567890" } } } ``` # /refund #### `POST /refund` #### Create a refund for an order. Refunds money to the shopper against the underlying Purple Dot preorder payments. You must provide either a **line-item refund** (only supported for Shopify stores) or an **custom amount refund**, but not both. **Request Body**: * `id` (string) - Required. Idempotency key. * Must be unique for each distinct refund. This could be a refund document number, return ID, or support case/ticket ID tied to that specific refund. * Reuse the **same** `id`, `order`, and payload when retrying after a timeout or network error. A successful prior attempt returns the same result and will not refund the shopper twice. Sending a different payload for the same `id` and `order` returns 409 Conflict. * Use a **new** `id` for each separate refund, even on the same order. * Do **not** generate a new random ID on every HTTP retry. * `order` (string) - Required. External order ID to refund. * On Shopify stores, use the **Shopify order ID**. * For other e-commerce platforms, use the Purple Dot **fulfillment order UUID**. Look up the fulfillment order via [`GET /fulfillment-orders`](https://docs.getpurpledot.com/docs/purple-dot-apis/private-api/fulfillment-orders). For a **line-item refund**, provide at least one of: * `line_items` (array) - Optional. The line items to refund. Each element must have: * `id` (string) - Required. External line item ID (e.g. Shopify line item ID). * `quantity` (number) - Required. Must be 1. * `shipping` (boolean) - Optional. Refund shipping for the order. Shipping can only be refunded once per order. {% hint style="info" %} Note: line-item refunds are currently only supported for Shopify stores. {% endhint %} For a **custom amount** **refund**, provide: * `amount` (string) - Required. The amount to refund (must be a decimal string). * `currency` (string) - Required. Must match the order's presentment currency. **Response Data**: * `id` - The idempotency key from the request * `order` - The external order ID from the request * `refunded` * `amount` - The refunded amount as a string * `currency` - The refunded amount currency **Errors**: * `400` - `INVALID_REFUND_REQUEST`: Mixed line-item and appeasement payload; missing or invalid amount/currency for appeasement; or currency does not match the order. * `400` - `INVALID_LINE_ITEMS`: The line items array contains invalid entries (e.g. missing id or quantity, or quantity is not 1). * `400` - `CURRENCY_MISMATCH`: Appeasement refund currency does not match the order's presentment currency. * `400` - `SHIPPING_ALREADY_REFUNDED`: Line-item refund with shipping requested but shipping was already refunded for this order. * `400` - `NOT_ENOUGH_ITEMS_LEFT_TO_REFUND`: Requested line-item quantities exceed the remaining refundable quantity. * `404` - `UNKNOWN_ORDER`: Order not found or not for this store. * `404` - `UNKNOWN_LINE_ITEMS`: One or more line item ids are not on the order. * `409` - `IDEMPOTENT_REQUEST_PAYLOAD_MISMATCH`: Same id and order were used with a different payload. * `500` - REFUND\_FAILED: Order has mixed checkout/preorder line items, or the payment refund failed. * `501` - Orders that span multiple pre-orders are not supported. **Examples**: {% code overflow="wrap" %} ```bash curl --request POST \ --url 'https://www.purpledotprice.com/admin/api/v1/refund' \ --header 'Content-Type: application/json' \ --header 'X-Purple-Dot-Access-Token: ' \ --data '{"id": "refund-001", "order": "gid://shopify/Order/123", "line_items": [{"id": "gid://shopify/LineItem/456", "quantity": 1}], "shipping": false}' ``` {% endcode %} {% code overflow="wrap" %} ```bash curl --request POST \ --url 'https://www.purpledotprice.com/admin/api/v1/refund' \ --header 'Content-Type: application/json' \ --header 'X-Purple-Dot-Access-Token: ' \ --data '{"id": "refund-002", "order": "gid://shopify/Order/123", "amount": "10.00", "currency": "USD"}' ``` {% endcode %} {% code overflow="wrap" %} ```json { "meta": { "result": "success" }, "data": { "id": "refund-001", "order": "gid://shopify/Order/123", "refunded": { "amount": "42.00", "currency": "USD" } } } ``` {% endcode %}