Welcome to DotApparel Core

In this guide, you'll find all the documentation you need to get up and running with different aspects of DotApparel Core, our Apparel21 and Shopify solutionI.

This guide is for front-end developers who are building the user-facing elements of a website that incorporates DotApparel Core. It includes instructions for integrating with DotApparel's API, which powers website features such as gift cards, check stock, rewards programs, and retail transactions.

Steps for front-end implementation

At handover, the back-end app installation has already been taken care of, and we're ready to move on to front-end development in a staging environment. The DotApparel webhooks will be disabled while front-end development is in progress, then re-enabled for final testing on staging before going live in production.

1. Review the front-end guide: Review the front-end guide before starting the implementation.

2. Confirm the AP21 connection: The DotApparel staging app will be installed in a staging Shopify store and connected to a test Apparel21 instance (i.e., testApparel21Connection).

3. Start front-end development: With the front-end guide and the suitable connection in place, start developing the front-end of the application as per the requirements. This would involve creating the user interface, setting up the product pages, and integrating it with DotApparel.

Front-end testing checklist

Make sure that the front end is usable (able to place test orders and sign up for the newsletter) and that the website is connected to the DotApparel app.

Shopify App proxy

Online store must not have the password page enable when calling the app proxy

The DotApparel app itself is hosted in a serverless environment on Google Cloud. Each time the frontend needs to make an API request to the app to retrieve data, it will call a designated API endpoint for that type of data.

Rather than making direct requests to the Google Cloud endpoints, we strongly recommend using the Shopify App proxy. Using the app proxy means that if your Shopify store is hosted on http://acme.myshopify.com , you would make a request to the following endpoint.

• https://acme.myshopify.com/apps/dotapparel/[endpoint]

• [Deprecated] https://acme.myshopify.com/apps/dotapparel21/[endpoint]

Using the app proxy means that the browser is only making requests to the current domain, which negates the need to handle and other cross-origin concerns.

When the DotApparel app is installed into your store, the API endpoints listed in this guide will always be available at /apps/dotapparel. The remainder of this guide will use the above domain as an example.

Usage

Each of the API endpoints is documented in the specific section. For example, if you’re looking to access in-store orders, see

Being a POS platform, Apparel21 is able to capture physical in-store orders, as well as web orders. If the POS operator collects the customers' personal information at checkout, then the order will be attached to the Apparel21 “person” record associated with that customer.

If the orders are attached to the relevant person in Apparel21 (using the same email address as the one used online), then it’s possible to show the customer a list of their in-store orders on the website.

DotApparel achieves this by exposing an API endpoint which when called with the customer email address and a special signature, a live request is made to Apparel21 to fetch the retail transactions, before returning them back to the website frontend for display.

Customer signatures

All customer-specific endpoints in DotApparel are secured using an HMAC signature, which consists of the customer email address, signed using HMAC and a shared secret. This mechanism is in place such that unauthorized users cannot make requests for email addresses that do not belong to them.

You should read the before proceeding.

Using the API endpoints

If you’re , then you can make a POST request to /apps/dotapparel/api-retailTransactions with the following JSON payload.

In this guide, you'll find all the documentation you need to get up and running with the DotApparel API.

The API endpoints utilise basic authentication and feature access control based on user roles. The different roles and their respective scopes are:

• admin: has unrestricted access

The endpoints listed on this page are used for managing user authentication within DotApparel API. It typically includes endpoints for creating, updating, and deleting user accounts:

1. Creating Users: The administrator is able to generate new user credentials with an assigned role.

2. Updating Users: The administrator has the ability to modify the role or reset the password of a specific API user.

3. Deleting Users: The administrator has the authority to revoke a user's authentication.

Our base domain URL is https://api.dotapparel.io. Before you get started, please make sure you have an account with us. If you do not have an account, please reach out to us to request an admin account.

Get your API keys

Our API uses basic authentication with username and password. To authenticate your requests, include your username and password as a header in your HTTP requests.

Authorization: Basic <YOUR_API_KEY>

To ensure each colour of a product has its own unique page and is listed separately on collection pages, DotDev recommends representing each colour as its own product in Shopify.

However, since Shopify doesn't have a built-in relationship between these products, displaying a "swatch picker" that allows customers to switch between colours of the same style can be difficult for merchants.

To solve this problem, DotApparel syncs tags to each product that detail its "siblings," allowing product detail pages to be linked together using Liquid or Javascript.

Option A: Product sibling metafields

DotApparel provides the "siblings" metafield, which is used to indicate sibling products. To enhance the product page, the frontend can be improved by utilising the new metafields structure to fetch information about sibling products.

The "siblings" metafield is located within the "dotapparel21" namespace and contains relevant details about sibling products. This information includes the color name, color code, title, handle, publishing status, tags, and other related data.

For example:

Option B: Product sibling tags

When a product has multiple colours, a series of sibling tags will be applied to the product, pointing at the Shopify product handles of each sibling colour. These tags include the "current" product in addition to the sibling colours, as often, the "current" colour will itself be displayed.

Let's say we have an ACME T-Shirt which comes in Red, Green and Blue. It has the style code ABC. The Red product (which has handle abc-acme-tshirt-red) would have the following tags automatically written by the DotApparel app.

• x-sibling-handle:abc-acme-tshirt-red

• x-sibling-handle:abc-acme-tshirt-blue

• x-sibling-handle:abc-acme-tshirt-green

Liquid or Javascript can be used to loop over these tags, and fetch the full product data from Shopify using the attached handle. Then, the name of the colour, the image or anything else on the product as dictated by the design can be output in the swatch area, thus linking the products together.

Prepending style codes to handles

We strongly recommend including the product style code at the start of the product handle. This is so that handles are guaranteed to always be unique. Often, merchants will add an “acme-tshirt”, and then later on, perhaps years later, add another product with the same title, which Shopify will then assign “acme-tshirt-1” as the handle.

Using handles which are not guaranteed to be unique, often causes issues for things like swatch resolution, so where possible, we always recommend prepending the style code.

Use the Gift Card validation API

If there is a need to redeem the gift card outside the checkout page, specifically on the cart page, DotApparel offers a Gift Card validating API to address this scenario. The API endpoint employs the GET method and accepts query parameters such as the voucher number, PIN, and amount. Upon verifying the validity of the voucher number and PIN, the API will respond with a Shopify gift card code as part of the payload. Furthermore, the API will provide information about the available amount and other relevant details pertaining to the voucher. In this approach, the frontend can utilise the gift card code to include the gift card during the checkout process. For more comprehensive information, please refer to the section on the Gift Card validation API below.

Use the new SKU structure

Each denomination of the gift card and gift card type (physical or digital) should be defined as a separate variant of the Shopify product. The SKU structure should define the type and denomination so you might have AP21GIFTCARD-2124-0-1, AP21GIFTCARD-2124-0-2, AP21GIFTCARD-2124-0-3, AP21GIFTCARD-2124-0-4. The frontend template should allow the customer to select a gift card type (physical/digital) and then a denomination, which should select the appropriate variant.

Update the custom line item attributes

The custom line item attributes must have the following names.

• From - This is the name of the sender.

• To - This is the name of the receiver.

• Email - This is the email of the receiver, for digital vouchers.

Please note: Make sure all key names above are capitalised as they are case-sensitive within DotApparel.

Gift Card validation API

Check Gift Card balance API

DotApparel's APIs are public by default because they are designed to be called from the website's front end. For endpoints that expose public data, like product availability or gift card balances, no authentication is necessary. However, for endpoints that return customer-specific data, such as retail transactions, authentication is required to prevent unauthorised access.

To solve this problem, DotApparel requires an additional signature property, which is an HMAC of the customer's email address, for endpoints that identify customers with email addresses. The shared secret used to generate this HMAC is available in the DotApparel app backend and should never be made public to the website's front end.

Generating a signature

To generate an HMAC signature, you must have access to a secure environment, where the shared secret will not be exposed to the front-end.

• If you have a Shopify Liquid theme, then you can generate the secret using a Liquid filter, and store the shared secret in your theme settings

• If you have a headless front-end, then we recommend generating the signature using a serverless function, after you have authenticated the customer using your own methods

Using a Liquid filter

Generating the HMAC signature in a Liquid theme is trivial because Shopify already handles the customer authentication for you. Inside a Liquid theme, if you have access to the {{ customer }} object, then you know that the customer has already authenticated, thus you can generate a signature for them using the .

When the signature is available on the page, you can then use it in the Javascript helper to access a customer instance, or use it to directly call the API endpoints.

The Check stock API endpoint receives an SKU parameter for a particular product. The SKU can be found in the Shopify variant sku attribute.

In return, DotApparel will respond with a list of inventory locations, identified by their Apparel21 store ID, and the current stock level for each location. This data should be matched with the enriched store data stored elsewhere, and displayed to the customer.

1. Make a request

Make a

DotApparel integrates Apparel21 "vouchers" with Shopify for purchase, redemption, and balance checking. Apparel21 vouchers, similar to "gift cards" in e-commerce, have a voucher number, PIN, and balance.

Using Apparel21 vouchers instead of Shopify gift cards allows customers to purchase and redeem vouchers at the point of sale (POS), enabling immediate online or in-store redemption.

It's important to note that Apparel21 is always the source of truth for vouchers in this model. When redeeming a voucher in Shopify, DotApparel verifies the PIN and balance directly with Apparel21 before applying it to the order.

Prerequisites

If setting up AP21 gift voucher:

• Apparel21 SKU IDX

• Apparel21 voucher type

If the merchant is using Shopify gift card:

• Apparel21 SKU IDX (dummy)

If setting up any other new payment gateway

• Ap21 Merchant ID

• Card Type

Implement Gift Cards with DotApparel

Purchasing vouchers

Purchasing vouchers in Shopify works like any other product, with the addition of some custom line item attributes which allow the customer to provide attributes such as the receivers name, email, and a personal message which is either included in the email (if it's a digital voucher) or included with the plastic card (if it's a physical voucher).

An example of this in action can be found at . The gift card itself is an ordinary Shopify product, which is manually created directly in Shopify. A custom product template is used to show the additional fields, which when added to the cart, are stored as line item attributes.

Each denomination of the gift card and gift card type (physical or digital) should be defined as a separate variant of the Shopify product. The SKU structure should define the type and denomination so you might have giftcard-p-20, giftcard-p-40, giftcard-e-20, giftcard-e-40. The frontend template should allow the customer to select a gift card type (physical/digital) and then a denomination, which should select the appropriate variant.

When added to the cart with these attributes, the rest of the process works like any other product through to checkout. When DotApparel receives the order, it will send the appropriate attributes to Apparel21 where a new voucher will be generated, and in the case of a digital voucher, an email will be sent directly from Apparel21 to the receiver, containing the voucher number and PIN.

Reducing fraud risk

Gift vouchers are subject to a high risk of fraudulent transactions. When a digital voucher is purchased, Apparel21 will immediately generate a voucher and email it to the receiver. If the purchaser has used fraudulent card details, this means that the merchant could be subject to a chargeback, but the attacker has already received their voucher number and PIN. By the time the fraud has been detected, the attacker could have purchased physical items from a store using the voucher at POS, which would not be recoverable.

DotDev strongly recommends that the Shopify system is utilised to detect potentially fraudulent transactions. Orders which are marked as fraud can be prevented from reaching Apparel21 using the following process.

1. In Shopify, configure transactions do not automatically capture, this means that by default, all payments will be authorized but not yet captured

2. Install and configure the app to check the fraud rating assigned by Shopify to each order, and also the value of any gift cards added to the order

3. If Shopify has assigned the order a low fraud rating, and the value of the gift cards is low (e.g. under $500), set Shopify Flow to automatically capture the payment on the order, this will result in the order flowing through to Apparel21 and the voucher being generated/sent

Redeeming vouchers

DotApparel provides a solution for redeeming Apparel21 vouchers at the Shopify checkout. This requires checkout customisations to be enabled, which is only available on the Shopify Plus plan as a custom form needs to be embedded into the checkout, to capture the voucher number and PIN.

Shopify itself only understands Shopify gift cards, and there is no other mechanism for applying a voucher-type discount to a Shopify order. Therefore, the DotApparel solution works by first capturing the voucher number and PIN from the customer, before validating that information with Apparel21 to check the number, PIN, and balance.

If the voucher is valid, a temporary Shopify gift card is created equal to the balance of the Apparel21 voucher. Behind the scenes, the Shopify gift card is applied to the checkout which reduces the payable amount. However, due to the checkout customisations, it looks like the Apparel21 voucher itself has been applied against the order.

When the order is completed, DotApparel detects that a Shopify gift card has been applied against the order, and swaps it out for the real Apparel21 voucher before sending the order to Apparel21. When Apparel21 receives the order, the voucher balance is deducted accordingly.

Because this solution uses temporary Shopify gift cards, it is to be expected that the Shopify backend will show a list of gift cards in the admin panel. These gift cards should be ignored as they are only for internal purposes. It is not possible to use Shopify gift cards at the same time as Apparel21 vouchers, any vouchers must be generated in Apparel21.

Check balance API

Headless Stores

Prerequisites

While there are no FE prerequisites for the checkout, to be able to query stock levels on the FE, you need the following:

• Shopify Storefront API version 2023-04 or above

• Stores set up in Shopify that allow in-store pickup

The Hook

To handle this, we’re best to create a useFindInStore hook — this would power a few parts:

• Fetching user location

• Fetching the product variant data

• Handling errors

The GraphQL Query

The storeAvailability connection is available on the variant, so before you can run the query, the user should have already selected a variant (see 2 in need to knows).

We can then present the user with the option to search for store stock. An example would be:

With the following variables:

This will return this response:

From this response, you could flatten the array then sort by the distance:

Example Implementation

Whilst it is outdated, Tony Bianco is a good reference for how to implement native Shopify Pickup.

On the PDP, the drawer uses Google Maps API to search for the user's location with autocomplete, or the Find My Location uses navigator.geolocation to get the user's current position.

Links

• PDP:

• useFindStore Hook: (not the best reference because it’s outdated, but an okay-ish reference for how it all pieces together)

• Find In Store Components:

10 May 2024

ADDED New query parameters updated_before and asc for /orders/transactions/search

• The updated_before parameter enables users to filter and retrieve a list of retail transactions that were created before a specific date.

• The asc is a boolean parameter that allows the sorting of retail transactions by saleDate in ascending order. e.g. asc=true

Now users can limit order records for a specific date range by using both updated_before and updated_after.

20 March 2024

ADDED New fields emailSubscription and smsSubscription in the customers POST and PUT requests

The POST and PUT "customers" endpoints now accept boolean fields emailSubscription and smsSubscription. If either of these fields is set to true, it will automatically override the privacy field to false.

NOTE: Both emailSubscription and smsSubscription can modify customer references in Apparel21. However, this process requires mapping configuration within DotApparel Core. If you require assistance with this configuration, please reach out to [email protected]

08 March 2024

FIXED Both mobile and dateOfBirth attributes are optional in customer POST and PUT requests

Resolved an issue where the customer creation or update requests could fail because both the mobile and dateOfBirth attributes were mandatory in the request payload.

07 March 2024

ANNOUNCEMENT Introducing new Staff endpoints

We're thrilled to introduce new Staff endpoints equipped with pagination and filtering capabilities. This update brings improved efficiency to accessing staff data via our API.

GET /staff?email=<value>&code=<value>

GET /staff/{id}

26 July 2023

ADDED New store and loyalty fields in customers/search response payloads

Now, the GET customers/search API responses include additional data related to the "sign-up" store code and loyalty program code/name.

19 July 2023

BREAKING The updateTimeStamp field is no longer required in Customers PUT request

The updateTimeStamp field has been removed from the request payload of the Customers PUT method, as it will be handled internally.

11 July 2023

ANNOUNCEMENT Introducing new Retail Transactions and Customers endpoints with pagination and timestamp filtering support

We are introducing highly efficient API endpoints for retrieving a list of customers or retail transaction data.

GET /customers/search

GET /orders/transactions/search

The new endpoints implemented an optimised approach to enhance the speed and performance of data retrieval. The endpoints support pagination using a cursor-based approach, enabling retrieval of up to 100 records per page. They also support for querying data using a timestamp parameter, allowing for filtering based on updated records. For more detailed information and examples on how to utilise this new efficient endpoint, please refer to the API reference page.

9 July 2023

ANNOUNCEMENT Introducing Get All Payment Gateways endpoint

We added a new API endpoint for developers to easily retrieve the list of available payment gateway names, enabling them to seamlessly pick up a desired gateway when posting orders or gift vouchers to Apparel21.

5 July 2023

ANNOUNCEMENT Introducing return creation endpoint

We added a new API endpoint for developers to facilitate return creation in Apparel21. It is crucial to note that the SKU ID must be present on the original order for the return to be processed successfully. This new functionality enhances the flexibility and convenience of managing returns within Apparel21. Please refer to the Orders API documentation for detailed instructions on how to use this endpoint effectively.

ANNOUNCEMENT Introducing voucher creation endpoint

We are also introducing a new API endpoint for creating gift vouchers in Apparel21. This endpoint enables the creation of digital gift vouchers that can be sent to customers via email. Each gift voucher includes a voucher number and PIN that customers can use for making purchases. Prior to using this endpoint, it is important to ensure the configurations for Gift Card SKU IDX, Voucher Type and Gift Voucher function are in place. Please refer to the updated Vouchers API documentation for detailed instructions on how to utilise this endpoint and complete the necessary configurations in DotApparel and Apparel21.

27 June 2023

ANNOUNCEMENT Introducing rewards endpoints

We have implemented new endpoints that interact with the Apparel21 Rewards feature to retrieve essential information regarding retail rewards and gifts. This data can be used to display the shopper's reward balance accurately on the website. By utilising these endpoints, the website can seamlessly retrieve and present the necessary details related to retail rewards and gifts, ensuring an up-to-date and accurate representation of the shopper's reward balance.

ANNOUNCEMENT Introducing vouchers endpoints

We are introducing new endpoints that encapsulate the functionality of the Apparel21 Gift Vouchers feature. This includes retrieving information about a gift voucher and locking a gift voucher.

26 June 2023

FIXED Retrieving customers by updated_after parameter requires the AP21 Retail API version to be 2022.1 or higher

In the event that the AP21 Retail API falls below the required version, the endpoint will respond with an empty array. To ensure proper functionality, it is crucial to verify the current API version with the merchant and initiate an upgrade if it is determined to be necessary.

23 June 2023

ADDED New contact field in customer response payloads

The customer response now includes a new field called contact which is an object including email and phones. This field is a replacement for the existing contacts field.

BREAKING The updateTimeStamp and startDate fields in customer response have some changes

22 June 2023

ADDED New Shopify ID fields in customer response payloads

The customer response now includes two new fields called shopifyAdminId and shopifyLegacyId, which represents customer id in Shopify. Please note that these fields are not included in the response when using the "updated_after" parameter in a GET request.

FIXED Changing some address field names to using "camel" format in customer response payloads

The affected fields are addressLine2, state, city, postcode, and country

5 May 2023

ANNOUNCEMENT Introducing retail transactions endpoint

DotApparel API now supports looking up retail history for a shopper; including store sales, head office telephone/mail sales and web system sales.

21 April 2023

FIXED Changing customer privacy in Apparel21

DotApparel API now allows the modification of a customer's accept market status within Apparel21.

17 April 2023

ANNOUNCEMENT Introducing customer list endpoint

DotApparel API now supports returning a list of Apparel21 customers using a given update_after query parameter.

5 April 2023

ADDED New fields in API response payloads

This implementation involves updating the store, inventory, product and customer endpoints.

10 March 2023

ANNOUNCEMENT Introducing DotApparel API

The initial release of the API layer project.

DotApparel will expose an endpoint POST /api-rewardsAccount that accepts an email address and returns the details of the rewards account of the given customer.

The frontend will need to call the endpoint directly to get “rewards account” details.

Rewards Account Creation

If a customer does not have any rewards account in AP21, the endpoint is able to automatically create a new rewards account and proceed with the new account. (Please note that this option should be enabled in the app’s settings)

Rewards Tier Tags Synchronisation

When Sync customer rewards tier tags is enabled in DotApparel rewards settings:

• DotApparel will automatically add a tag in the format x-loyalty:{tierName} to the Shopify customer

• The tag prefix (e.g., x-loyalty) is configurable in the settings

Endpoint

Request:

Response:

Adding Reward to Orders

Endpoints

Get Reward Balance

Request:

Response:

UI example

Guest checkout

Customer logged in (Hide the form if the available balance is 0)

Form validations

It is important to ensure that all necessary validations are performed before requesting the redeem reward endpoint. The following validations are crucial:

• The "amount to redeem" must not exceed the available balance.

• Once the cart has a "REWARD" discount applied to it, the available balance must be calculated on the front end. Please note that the "available_rewards" value won't be reflected in the "Get Rewards Balance" API until the order is created.

Recommended workflow

1. Make an API call to the Get Reward Balance endpoint to retrieve the available balance (available_rewards) for the customer.

2. When a customer wishes to use their rewards, you'll need to add a "reward_amount" to the cart to trigger the Shopify Scripts that handle the rewards redemption. Follow these steps:

   • When the customer enters an amount to redeem their reward, programmatically add the relevant line item properties to the cart item(s) using Shopify's cart API.

Example discount_application of Reward Redemption in Shopify orders

Adding a Gift Product to Orders

• To apply the reward amount as a discount, you need to implement a Shopify Script. This script will identify the Loyalty Reward product in the cart and transform the reward amount into a discount. Follow these steps:

  • Create a new Shopify Script or modify an existing one to handle the Loyalty Reward redemption.

  • In the script, identify the Loyalty Reward product in the cart by checking the line item properties.

Similar to the "Rewards" redemption, DotApparel also provides the available gifts in the API response that a customer earned from a reward program.

The recommended workflow:

1. Make an API call to the DotApparel API endpoint to retrieve the available gifts for the customer.

2. When a customer wishes to redeem a gift, they need to add the corresponding gift product to their cart along with relevant line item properties. Follow these steps:

   • When the customer selects the option to redeem a gift, programmatically add the gift card product to their cart using Shopify's cart API.

Example payload of Gift Redemption discount and item in Shopify orders