Fundamentals

Accounts

Check out this API in postman >

In this section, we are going to control and edit the user accounts in Arcadier. For onboarding of accounts or account creation, please refer to the authorization section. In Arcadier, everyone is a user account, and Consumer, Merchant and Admin are user accounts with a role attached to it. By default, a newly created user will given the Consumer role. To become a Merchant, you need to convert the Consumer role to a Merchant one.

For authorization, the Consumer, you are only able to read and write your own user account. For Merchant, you are able to read and write yours own and Consumer’s user account. And for Admin, you are able to read and write all user accounts in your marketplace.

Time Zone is more relevant for the Spacetime template. In Arcadier’s database, we are using Coordinated Universal Time (UTC) as the standard time for item scheduling. For Merchants in the Spacetime template, the Merchant’s time zone will determine the timing of their services in the marketplace. This will be helpful For example, a Merchant has indicated using Singapore time (GMT+8) in his settings page, all bookings made by the Consumer will be in the Singapore time zone, regardless of the Consumer’s time zone.

Addresses

Check out this API in postman >

In Arcadier, addresses can be used by many different functionalities in the system. By using the different properties, you are able to use addresses for the following:

  1. Pickup Location
  2. Address book in the checkout page
  3. User’s address in login and settings page
  4. Item’s location

In Arcadier, the address book in the checkout page and the user’s address in login and settings pages are using the same things. Simply set delivery to “true” if you want to use this particular address in those pages. Pickup location in Arcadier meant a prearranged place where the Consumer goes to collect their item from the Merchant. Once created, these Pickup location will appear in the Item upload page for the Merchant to select which pickup point is available for that particular item. The Merchant has an endpoint to list out all the pickup is “true” addresses and then link the PickupAddresses ID to the item during item creation. 

For Spacetime, location is mandatory during item upload so that the items can be shown in a map. Once the Merchant create an item, a location ID will also be created. Even if items are using the same address, different Address ID will be created.

For authorization, the Consumer, you are only able to read and write your own addresses. Except for Consumer - Get Pickup Method by Item ID, it allows Consumer and Guests to read all Pickup locations for a particular Item, so that one can choose a location for checkout. For Merchant, you are able to read and write yours own and Consumer’s addresses. And for Admin, you are able to read and write all user’s addresses in your marketplace.

Addresses

Checkout

This set of APIs are the basic ones needed to create a simple Checkout process. They are the same APIs found in the “Cart” and “Orders” API sections, but consolidated into one “Checkout” folder for a more convenient reference. 

Carts & Orders

Check out this API in postman >

A shopping cart in Arcadier is a piece of software that keeps a record of the items a Consumer has chosen from the Marketplace. This cart saves the items, variants, qty and delivery type that the Consumer has selected, it also the Consumer to make modifications, add additional item, delete items and to select certain items for checkout. 

As you add an item into the cart as a Guest or signed in Consumer, a Cart ID will be created. If you add items of different variant combination into the cart, multiple Cart IDs will be created. This is the same for identical items with different shipping method. You can then select which Cart ID you want to select for checkout. For the checkout, please refer to the checkout section. 

When you add an item into the Cart as a Guest, an Access token and Cart IDs will be created. You can then save this access token into the cookies. When you add an item into the Cart as a signed in Consumer, Cart IDs will be created.  

Categories

Check out this API in postman >

Category is used to sort and group Items into different sections. This is to help your Consumers to navigate around your marketplace and help Merchants to know how to group their Items. 

Through our APIs, you can create unlimited categories, as well as branch them (parent/children). Testing the limits of that, however, is not recommended because having too many categories creates a complicated (and therefore unpleasant) experience for the Consumers. We encourage the use of Sorting and Filters to enhance the search experience. We do not recommend to rely solely on the use of Categories. 

Example 1:

An item/listing can belong to one or many categories.

A category can have 0 or many items/listings. 

A parent category can have 0 or many children categories. 

A child category can have only 1 parent category. 

A parent category has "Level": 0. 

The children category have "Level": 1. 

The grandchildren have "Level": 2. 

Custom Fields

Check out this API in postman >

In Arcadier Custom Fields are the adding of additional properties to a specific table. This is to create more data points for your marketplace to store and use. 

There are different type of Input type for custom fields:

  1. Text Field
  2. Hyperlink
  3. Email
  4. Location
  5. Percentage
  6. Number
  7. Checkout
  8. Dropdown
  9. Date / Time picker

There are also different reference table you are able to add the custom fields to:

  1. Items
  2. Users
  3. Orders
  4. Payments
  5. Cart Items
  6. Categories
  7. Panels
  8. Panel Details
  9. Developer Packages (do not use)
  10. Implementations

Please refer to the more detailed explanation below on how to use custom fields for different reference table.
Please note not to create custom field for Developer Packages reference table

Users

User's gender can be stored as a custom field. A text field custom field named ‘Gender’ created under Users Reference table. All the users will have ‘Gender’ custom field added to their profile with their own individual value as shown in the diagram below.The reference id for the ‘Gender’ custom field will be link to the User Id.You can use this API Endpoint (GET /api/account/info)  to get the User Id. The reference id is required to fetch the ‘Gender’ custom field value of the user. 

If you want to have a sales indicator for your category, a drop down custom field name “Sale” for Categories Reference Table can be created. The “Sale” custom field is added to all the category record with its respective value. The reference id for “Sale” will be link to the Category Id. You can use this API Endpoint (GET /api/consumers/categories)  to get the Category Id. The reference id is required to fetch the ‘Sale’ custom field value of the category.

Categories

If you want to have a sales indicator for your category, a drop down custom field name “Sale” for Categories Reference Table can be created. The “Sale” custom field is added to all the category record with its respective value. The reference id for “Sale” will be link to the Category Id. You can use this API Endpoint (GET /api/consumers/categories)  to get the Category Id. The reference id is required to fetch the ‘Sale’ custom field value of the category.

Panels

Panels are section of information that are displayed in the Homepage. In a marketplace, you will have a Category and Latest Item panels. You can create new panel for Homepage via the Layout section in admin portal page. If you require a Facebook URL link to your panel you can create a hyperlink custom field name “Facebook Link” under the Panels reference table. The “Facebook Link” custom field will be added to the Panel with its respective value. The reference id for “Facebook Link” will be link to the Panel Id. You can retrieve the Panel Id via inspecting the Panel element in the Admin Portal Page like in the example below. The reference id is required to fetch the ‘Facebook Link’’ custom field value of the panel.

Access Homepage section via the Layout page from Admin portal page

Inspect the page and select the panel that the custom field need to tied to.

The panel id is the element data-id that is depict on the above image.

Panel Details

Panels details are partition of information that are displayed in the Panel. In your marketplace,you may have a Panel that have three split panel which are called Panel Details. You can create new panel for Homepage via the Layout section in admin portal page. If you require a Price to your panel detail you can create a textfield custom field name “Price” under the Panel Details reference table. The “Price” custom field will be added to the Panel Details with its respective value. The reference id for “Price” will be link to the Panel Details Id. You can retrieve the Panel Detail Id via inspecting the Panel Detail element in the Admin Portal Page like in the example below. The reference id is required to fetch the ‘Price’’ custom field value of the panel detail.

The panel detail id is the element data-id that is depict on the above image

Orders

If your orders require total weight information, a text field custom field name “Total Weight” can be created under the Orders reference table. The “Total Weight” custom field is added to all the order record with its respective value. The value “Total Weight” for the Order will need to compute with the custom field “Weight” that is created for the Item reference table. The reference id for “Total Weight” will be link to the Order Id. You can use this API Endpoint (GET /api/merchant/orders/order-history) to get the Order Id. The reference id is required to fetch the “Total Weight” custom field value of the order.

Payments

If you want to a Callback URL link for your own custom payment gateway, you can create a text field custom field name “Callback URL” for Payments Reference Table. The “Callback URL” custom field is added to the payment record with its callback url value. The reference id for “Callback URL” will be link to the Payment Method Type ID. You can use this API Endpoint (GET /api/admin/paymentmethod) to get the Payment Method Type ID. The reference id is required to fetch the “Callback URL” custom field value of the payment method

CartItems

If you want to track if cutlery is required for your cart item, a drop down custom field name "Cutlery" for CartItems Reference Table can be created. The “Cutlery” custom field is added to all the cart item record with its respective value. The reference id for “Cutlery” will be link to the Cart Item Id. You can use this API Endpoint (GET /api/consumers/carts) to get the Cart Item Id.The reference id is required to fetch the Cutlery custom field value of the cart item.

Implementations

You can add your blog URL address to your marketplace by creating a hyperlink custom field name “Blog Link” under Implementations Reference Table. The “Blog Link” custom field is added to the marketplace record with its value. The reference id for “Blog Link” will be link to the Marketplace Id. You can use this API Endpoint (GET /api/user/marketplace) to get the Marketplace Id. The reference id is required to fetch the “Blog Link” custom field value for the marketplace.

Items

If you need item’s product origin need to be display. A text field custom field named ‘Product Origin’ will be created with Items as the reference table. ‘Product Origin’ custom field will appear in Create Item and Item Edit page for Merchant to input the value. The Item Details page will show the value of the item’s “Product Origin”.The reference id for “Product Origin” will be link to the Item Id. You can use this API Endpoint (GET /api/consumers/items/search) to get the Item Id. The reference id is required to fetch the “Product Origin” custom field value for the item.

Custom Tables

Check out this API in postman >

Custom Tables are essentially tables created and used by developers to store information in a quasi database manner. Do take note that this is for more advanced development jobs. For more information about Custom Tables, click on the link here.

Delivery 2.0

 

Delivery 2.0 was devised by Arcadier to offer Marketplaces the option to have flexible delivery/freight/shipping fees. Those fees would be dependant on the total price of a cart or the total weight of a cart. 

More details about the use of Delivery 2.0 on Arcadier's default marketplaces can be found here.

 

Delivery 2.0 and Arcadier API

As a developer, if you are building your own fulfillment flow and wish to use Delivery 2.0, these are the steps you need to follow:

1. Create different rates of your choice on the Admin portal as explained here.
2. Retrieve the rates in your app/plug-in using the Get Delivery 2.0 Shipping Rates API.
3. Use logic to detect the price/weight of a buyer's cart, and compare against the retrieved rates in #2.
4. Match and find the corresponding shipping fee.
5. Use Merchant - Edit Order Details or Admin - Edit Order Details to update the "Freight" field with that value.

From #2, this is what the API response might look like:

Get Delivery 2.0 Rates Example Response

The 3 most typically most important fields of this response are the

"ID" - The GUID of the delivery method

"Description" - The name of the delivery method

"Values" - Array of length 1, containing all the necessary information about the rates - in a single parsable string.

The first thing to do is obviously parsing CustomFields[0].Values, and extracting the rates out of it:

var obj = JSON.parse(price_dependant.CustomFields[0].Values); 

var rate = obj.Rates; 

Extra information such as the destination and origin countries and the minimum lead time can also be obtained by parsing this string.

Below is a JavaScript sample code to display the shipping fee, depending on the value of a variable, in console.log.

var variable = 15; //price or weight depending on how you created the Rates on the Admin portal


console.log("This item has a " + obj.CalculationType + " of " + variable + ".");

for (var i = 0; i < rate.length; i++) { 

  if (variable < rate[i].MaximumRange) { 

    console.log("Shipping Cost = $", rate[i].Cost);

    break;

  }

  if (rate[i].MaximumRange == "") { 

    console.log("Shipping Cost = $", rate[i].Cost);

  }

}

Email

Check out this API in postman >

An email notification is an email sent to either the Merchants or the Consumers when any of them has taken an action. Some examples include:

An email notification sent to the Merchant when Consumer has completed a purchase

An email notification sent to the Consumer once they have onboarded on the marketplace

Important things to know before using any of these APIs:

For everyone: 

  • languageCode = en. Always.

For HTML coders: 

  • Use " " in your code instead of “ ”.
  • When writing HTML, don’t forget to wrap your whole <body> in inverted commas
    "<body>...</body>"
  • When writing HTML as parameter, you just need to remember the above. When a response returns HTML data, however,
        - New lines will be represented by “ \n ” or “ \r ”
        - Tabs will be represented by “ \t ”.
        - Inverted commas in will be represented by “ \" ”

How to see the actual content of any template

  1. Refer to the table below
  2. Choose the templateID you want to check
  3. Use it as parameter in the “Get email template content by ID” API.
  4. Copy the contents of “Content” in the response.
  5. Replace all the “&lt;” with “<”, and “&gt;” with “>”.
  6. Paste it in the “Body” parameter of the “Send email” API.
  7. Send it to your own email.
  8. Check it.

Example of how you’d fully customise an email-template

  1. Decide the Template to customise. E.g: “Welcome Mail”, templateID = 1
  2. Check the default content of the template using the “Get email Template Content by ID”.
  3. Response:
    "ID" : 1,
    "Name": "Welcome Mail",
    "CustomisedContent": {
        "IsEnabled": false,
        "LanguageCode": "en",
        "Sender": "{{AdminEmail}}",
        "Subject": "Welcome to {{Marketname}}",
        "Content": "<body>\n . .(the default content). . </body>\n"
      }

    Find all &lt; Replace with <
    Find all &gt; Replace with >

  4. Copy the contents of "Content" to a text editor. Using the Find & Replace tool, 

    "<body>\n

    <div style=\"background-color=#5e5e5e;\">\n

    <p>Example</p>\n

    </div>\n

    </body>" (If you’re going to use dynamic parameters, make sure to read step 7 properly.) 

  5. Copy your customised contents to the “Content” param of “Edit Email Content” API.
    Changes to the recipients and sender can also be done in this API.
    Example:

     "IsEnabled": true,
     "languageCode": "en",
     "Sender": "tanoo_joy@email.com",
     "BCC": "sherz@emailtwo.com",
     "CC": "shers@emailthree.com",
     "Subject": "$10",
     "Content": "

    <body>\n

    <div style=\"background-color=#5e5e5e;\">\n

    <p>Example</p>\n

    </div>\n

    </body> ".

  6. If no syntax error was made, the “Get Email Template Content by ID” will show your changes. The only changes will be that "<" and ">" will be replaced by "&lt;" and "&gt;" which is normal.

  7. If you added dynamic parameters that are not the default one for that template, then you will need to use the “Get Customised Email Content” to add it to the default ones.

    Example: {{SellerName}} is added in the “Contents” of the email.

    "TemplateName": "welcomemail",
    "LanguageCode": "en",
    "DynamicValues": {
    	"AdminEmail": "tanoo_joy@email.com",
    	"Marketname": "Sherz",
    	"Logo": "sherz.sandbox.arcadier.io/images/logo-sherz.sandbox.arcadier.io.png",
    	"ConsumerFirstName": "Tanoo",
    	"ConsumerLastName": "Joy",
    	"ConsumerEmail": "tanoojoy@gmail.com",
    	"MarketplaceUrl": "sherz.sandbox.arcadier.io"
    	"SellerName": "Chris Evans" 
    },
    "Recipients": [
    	"tanoo_joy@emailtwo.com"
    ]
  8. Done.
    Template templateID templateName
    Welcome Mail 1 welcomemail
    Start Selling 2 startselling
    Account Suspended 3 accountsuspended
    Change of Payment 4 changeofpayment
    Reset Password 5 resetpassword
    New Order 6 neworder
    Received Order 7 receivedorder
    Order Pickup 8 orderpickup
    Order Shipped 9 ordershipped
    Acknowledged Order (Bespoke only) 10 acknowledgedorder
    Review Prompt 11 reviewprompt
    Offer from Seller (Spacetime only)
    12 offerfromseller
    Offer Declined (Spacetime only)
    13 offerdeclined
    Seller Invite 14 sellerinvite
    Buyer Invite 15 buyerinvite
    Enquiry from buyer (Spacetime only) 16 enquiryfrombuyer
    Message from seller 17 messagefromseller
    Message from buyer 18 messagefrombuyer
    Bespoke Email Template Default Parameters
    Template Default Parameters
    Welcome Mail "Logo", "ConsumerFirstName", "ConsumerLastName", "ConsumerEmail", "MarketplaceUrl", "Marketname"
    Start Selling "Logo": , "SellerName": , "MarketplaceUrl"”: , "Marketname":
    Account Suspended "MarketplaceUrl": , "Marketname": , "AdminContact": , "SupportEmail": , "SellerName": , "Logo":
    Change of Payment "Logo": , "SellerName": , "ReturnUrl": , "Marketname": ,
    Reset Password "Logo": , "Marketname": , "ReturnUrl":,
    New Order "Logo": , "SellerName": , "ConsumerFirstName": , "OrderID": , "InvoiceNo": , "Timestamp": , "OrderItemsString": , "DeliveryAddress": , "CurrencyCode": , "Subtotal": , "ShippingCost": , "BulkDeliveryCost": , "Total": , "Paid": , "ToBeCollected": , "OrderHistoryURL": , "ConsumerContact": , "ConsumerEmail}"Marketname": , "MarketplaceUrl":
    Received Order "Logo": , "ConsumerFirstName": , "SupportEmail": , "InvoiceNo": , "Timestamp": , "OrderItemsString": , "DeliveryAddress": , "CurrencyCode": , "Subtotal": , "ShippingCost": , "BulkDeliveryCost": , "Total": , "Paid": , "ToBeCollected": , "OrderHistoryURL": , "Marketname":
    Order Pickup "Logo": , "ConsumerFirstName": , "InvoiceNo": , "Timestamp": , "ImageUrl": , "ItemName": , "Quantity": , "Variants": , "CurrencyCode": , "ItemSubtotal": , "DeliveryMethodName": , "ConsumerEmail": , "SupportEmail": , "Marketname": , "MarketplaceUrl": ,
    Order Shipped "Logo": , "ConsumerFirstName": , "InvoiceNo": , "Timestamp": , "ImageUrl": , "ItemName": , "Quantity": , "Variants": , "DeliveryMethodName": , "DeliveryMethod": , "ConsumerEmail": , "DeliveryAddress": , "Marketname": , "MarketplaceUrl": ,
    Acknowledged Order "Logo": , "ConsumerFirstName": , "SupportEmail": , "Marketname": ,
    Review Prompt "Logo": , "ConsumerFirstName": , "ReviewPromptItemsString": , "MarketplaceUrl": , "InvoiceNo": , "Marketname": , "MarketplaceUrl": ,
    Seller Invite "Logo": , "Marketname": , "ReturnUrl": , "MarketplaceUrl": ,
    Buyer Invite "Logo": , "Marketname": , "ReturnUrl": , "MarketplaceUrl":
    Message from seller "Logo": , "ConsumerFirstName": , "SellerName": , "ReturnUrl": , "Marketname":
    Message from buyer "Logo": , "SellerName": , "ConsumerFirstName": , "ReturnUrl": , "Marketname":
    Group ID - Group Parameters
    1 - Marketplace

    {{Logo}}, {{MarketDomain}}, {{MarketName}}, {{MarketplaceURL}}

    2 - Items {{AddOns}}, {{ImageURL}}, {{ItemName}}, {{ItemPrice}}, {{ItemPriceUnit}}, {{ItemPriceUnitPlural}}, {{ItemSubTotal}}, {{Variants}}, {{VariantsDetail}}
    3 - Admin

    {{AdminContact}}, {{AdminEmail}}, {{AdminFullName}}, {{AdminName}}, {{EmailFromDomain}}, {{SupportEmail}}

    4 - Order {{Booking}}, {{BookingEndTime}}, {{CheckinCheckoutHour}}, {{InvoiceNo,}} {{OrderHistoryURL}}, {{OrderID}}, {{OrderItem}}, {{OrderItemsString}}, {{Paid}}, {{Quantity}}, {{ReviewPromptItemsString}}, {{ShowTime}}, {{Timestamp}}, {{ToBeCollected.}}
    5 - Pricing

    {{BulkDeliveryCost, {{DeliveryPrice}}, {{FreightCost}}, {{ShippingCost}}, {{Subtotal}}, {{Total}}

    6 - Consumer {{ConsumerAddress}}, {{ConsumerContact}}, {{ConsumerEmail}}, {{ConsumerFirstName, {{ConsumerLastNAme}}, {{ConsumerLoginID, {{DeliveryAddress, {{DeliveryMethod}}, {{DeliveryMethodName}}
    7 - Merchant {{SellerEmail}}, {{SellerName}}
    8 - General {{ArcadierURL}}, {{CurrencyCode}}, {{ReturnURL}}


Email API

What is an Electronic Direct Mail (EDM)?

 

Electronic Direct Mail (EDM) is an email marketing tool that involves directly sending automatic timely relevant promotions, reminders and responses to its customers. Arcadier’s marketplaces have their own triggers which send the EDMs automatically.

 

For example, a customisable “Welcome E-mail” is sent to a user as soon as they successfully create an account on the marketplace.

 

Other examples of those triggers are order confirmations, negotiation offers, message from a buyer, password resets, etc. All can be found in the Admin Portal > Email Notification > Email Template.

 

But to be truly customisable, Arcadier’s clients/developers need to be able to have their own triggers for their own emails.

To enable this, Arcadier has an Email API that can send emails on behalf of the developer to anyone with a valid email address. Using either client-side/server-side logic, the trigger can be any event in the marketplace. And the content accepts HTML, which allows the message to be very customisable.

 

Items

Check out this API in postman >

Custom Tables are essentially tables created and used by developers to store information in a quasi database manner. Do take note that this is for more advanced development jobs. For more information about Custom Tables, click on the link here.

An Item usually refers a physical item that Merchant sell to the Consumer. In Bespoke, it can mean an item object, for example a physical product, a classified listing and a service listing without calendar etc. If your Item needs a calendar engine attached to it, like a hotel booking, rental space booking - any service which involves time - please do refer to our Item (Spacetime).

Arcadier Item resources allow you and your Merchants to create products in Marketplace.

Items in Bespoke can posses various variants, which are basically different “models” of the same item. (Example: Size, Color, etc.). You can also add or update images to your items, as well as prices, shipping methods, pickup methods, and every detail a buyer would want to have about an item.

Admins and merchants have access inventory details about their items, like identification numbers, stock numbers, visibility, purchasability.

 

Moving items across categories

All items that have been created in a marketplace must be under at least 1 category. In other words, an item cannot exist without a category.

If you wish to shift items from one category to another , you should do so by shifting only the parent item.

The only way to do this is via API. More details can be found here.

Changing the Category IDs in the request body will OVERWRITE the item's current categories it belongs to.

So if an item belongs to Category A, Category B and Category C, and you want to change Category A to Category D, then the request body should look like this:

URL: api/v2/merchants/{ { merchantID } } /items/{ { itemId } }
Method: PUT
Auth:  Bearer { { merchant-token } } or Bearer { { admintoken } }
{
	"Categories" :[
		{
			ID: "category_D_id"
		},
		{
			ID: "category_B_id"
		},
		{
			ID: "category_C_id"
		}
	]
}
	

Omitting categories B and C will simply remove the item from them.

 

 

Visibility and Item Vetting

There are 3 free fields that can be edited in the Item API that affect the item’s visibility. Each is controlled by a different group of users:

“IsVisibletoCustomer” - controlled by Admin

“IsAvailable” - controlled by Merchants

“Active” - controlled by Arcadier

 All 3 of them are booleans, i.e, they only take either 'true' or 'false' as values.

  

IsAvailable

Outside API context, there is a toggle for merchants to decide if an item is purchasable or not. It is found on the merchant’s item list, as seen below:


Purchasable toggle on merchant’s list of items

This toggle affects the “IsAvailable” field.

  

IsVisibletoCustomer

On the Admin portal, admins also have some level of control over an item’s visibility. The toggle (shown below), affects the “IsVisibletoCustomer” field.

Purchasable toggle on admin item list

  

Active

Setting the “Active” field to false will soft delete it from the marketplace and will not be retrievable by anyone; not even APIs. If an item is set to “Active” falsely by mistake, contact devsupport@arcadier.com

 



Free Field

      Setting

true

false


“Active” 

Setting ‘true’ to this field will allow the respective item to be displayed on the marketplace and will be visible to all group users unless :


  • Admin set “IsVisibleToCustomer” to false 

  • Merchants set “Is Available” to false

Setting ‘false’ to this field will soft delete the item. It will not be displayed on the marketplace and will be invisible to all group users.


The item will still reside in the Arcadier system but will be non-existent in the marketplace.

 

Marketplace

Check out this API in postman >

Two simple APIs:

  • One API to GET general information about the marketplace and the custom fields associated with it 
  • One API to POST data in Custom Fields after being associated with the marketplace 

Relevant links :

Media

These APIs are coming soon! Stay tuned!

Orders

Check out this API in postman >

When a Consumer marks Cart Item (Cart ID) ready for checkout, it will orders and invoice. An Order is a commercial document issued by the Marketplace to the Merchant and Consumer. It recorded the sale transaction and indicates the items, services, quantities, agreed price for the items or services that Merchant has to fulfill. An Invoice is an aggregated view of all the items/services the Consumer has purchased within a single checkout. Even though, in our default Spacetime template only have a single checkout process, you are still able to create a cart and do multi-items checkout. If you wish to follow our default Spacetime template whereby you want to allow single item checkout, you will still have to insert the item into a backend cart and set the item ready for checkout. You will receive both an invoice and order ID.

If you allow Consumer to purchase items from multiple Merchants in a single checkout. This will create an Invoice ID for the Consumer’s reference, to see the full list of items they have bought within that checkout. In the backend, the checkout will breakup the items into separate Order IDs for each Merchant to fulfill respectively. In each Order ID, the Merchants are only able to see items/services related to them and also the breakdown of total item price less the commission to be paid to the Admin. This is for privacy purposes as a Marketplace will not want Merchants to know what Consumers ordered from other Merchants.

A Transaction ID is a unique string that is given by any payment gateway to identify each transactions that is passed through them. Arcadier does not created these Transaction IDs as they are created by the payment gateway once you run a payment through them. You can use this ID to track the payment status for to search for past transactions within the payment gateway platform. In a standard Arcadier checkout, there will be x+1 transactions, with x equals to the number of Merchants involved in the checkout and 1 is a transaction to the Admin for commission fee.

For authorization, the Consumer, you are only able to read invoice details that they checked out. For Merchant, you are able to read order details and update order status related to them. And for Admin, you are able to read all invoices, orders and transactions in your marketplace.

Payment Method

Check out this API in postman >

All APIs related to creating a payment gateway on your marketplace. This only creates entries like an ID, names, bank details (if any). However, it does NOT actually link the payment gateway APIs to our APIs. Kindly take note you will still need to do more developments linking those two. 

Pages (Plug-In)

Check out this API in postman >

These APIs creates pages such as FAQ and Privacy Policy for example. Have a look at our sample response on our API documentation page to see more. Click on the link above. 

Panels (Front-End)

Check out this API in postman >

The Panels referred here are the panels on the homepage (User-side) of the marketplace. Each panel has its own ID and using these APIs, together with some coding knowledge, you can have an exact replica of those panels on the other pages. 

Passwords


There are 2 scenarios in which a password would want to be changed: 

  • A user forgot their password

  • A user wishes to change a password they have not forgotten

     

Resetting forgotten passwords via API

A typical process of resetting password via API is shown in the sequence diagram below. The entire process will involve 2 different APIs:

 

 

Changing known passwords

A typical process of changing a known password is shown in the sequence diagram below. The entire process will involve only Update-Password API. 

 

Registering Users

 

Guest Users

Guest users are those who browse and make purchases on the marketplace without creating an account. 

Our core product and APIs can handle a user with no registered account to purchase something on a core marketplace. For example:

 

  1. Adding an item to cart on a core marketplace as a guest user : 

    1. Navigate to item 

    2. Click Add to Cart

    3. Click on View Cart

    4. Click on Checkout

    5. Fill in user details (addresses and names)

    6. Pay

 

  1. Adding item to cart using API, as a guest user : 

    1. Get the item GUID/child item GUID

    2. Input the Quantity

    3. Use admin token as authorization token

    4. Send request.

    5. API response contains 

      1. a GUID that belongs to that user

      2. a generated authorization token for that user

    6. Continue checkout flow using that user GUID and token 

 

Any new visitor to the marketplace will be a guest user. 

 

Upgrading user roles

Getting registered as a buyer, merchant or admin can easily be done on Arcadier's pages:

 

Guest > Registered Buyer

Click on "Register/Sign In" button

 

Guest > Registered Merchant

Click on "Be A Seller" button

 

Registered Buyer > Registered Merchant

Click on "Be A Seller" button

 

Guest OR Registered Buyer/Merchant > Sub-Admin Account

(Admin Portal) Click on "Permissions" and invite via email

On the other hand, if users are to be created or upgraded via API, this is the flow to be followed:



The 2 APIs involved in this flow are:

  1. Create User Account API - Creates an account for the user

  2. Upgrade User Role API - Upgrade the account from buyer to seller/admin

 

All details on how to use those API are found in their hyperlinks.

Shipping Method

Check out this API in postman >

Shipping (or Shipping methods) are the different type of options of delivering goods to the consumers. Currently in Arcadier, the Shipping surcharge is defined by the Merchants and it is per item. Inserting the price for Shipping in each item defines the additional amount Consumers have to pay during checkout.

For bulk shipping feature allows Merchant to reduce the individual item shipping charges if customer purchased more than one of the same item from them. This can be configured by adding value into the “CombinedPrice” property, this is also referred as “With Other Item (B)” in the consumer facing front. “CombinedPrice” is the delivery rate charged for every subsequent item that the Consumer purchases from the Merchant. There is currently no bulk shipping feature input field in the Spacetime template as there is no front-end cart. However, if you were to create a Spacetime cart using our APIs, you are able to tap on to the bulk shipping feature using APIs.

For Spacetime template users who doesn’t need the shipping feature can skip this step in the item creation process.

The bulk shipping calculation is as follows:

Delivery Service Single Item Shipping (A) With Other Item (B)
Merchant A
International 20 5
Local 10 2
Merchant B

Local 6 0
International 30 1
Fast Track 27 27

John purchases the following items from the Marketplace.

Item Purchased Merchant Shipping Chosen Original calculation Shipping Cost incurred Why?
Item A Merchant A International 20 20 The first item is charged at 20.
Item B X 2 Merchant A Local 20 12 10 for the first item and 2 for the second item
Item C Merchant B International 30 30 The first item is charged at 30
Item D X 2 Merchant B Local 12 6 Delivery for subsequent item is charged at (B)
Item E X 2 Merchant B Fast Track 54 54 Delivery for subsequent item is charged at (B)

Delivery cost for Merchant A = $20 + $12 = $32

Delivery cost for Merchant B = $30 + $6 + $54 = $90

Static

Check out this API in postman >

These APIs return general information like countries and timezones, which are useful only in specific cases. However, the information these APIs fetch cannot be changed.

Single Sign-On

 Our single sign-on API can be used to authenticate users who want to login from an external platform.

As long as the external platform provides Arcadier with a unique ID belonging to that user, this SSO API can be used to perform SSO login.

Below shows the process of using this API to log the user in on a Arcadier marketplace :

 

 

Tag

Tags are used on items only. This is to help developers group items together without using custom fields.

Get all items’ details and filter by Tag in JS

Transaction History

Check out this API in postman >

These set of APIs allows:

  • Admins to see the whole transaction history of the marketplace 
  • Admin to get a specific transaction 
  • Buyers to see their own transaction history 

Variant

Managing Variants

What is a variant in a marketplace?

A variant is essentially a different version of the same item. For example, a T-shirt (item) can have 3 variants : "Color", "Weight", "Material". 

Image caption: Buyer’s view of an item with variants

 

A variant option refers to the different types of a variant. For example, the variant "Color" of a T-shirt can have 3 variant options : "Red", "Blue", "Green".

  

What is the relationship between variants and the parent item?

The diagram below shows the relationship between a parent item and its variants , also known as the parent-child item relationship.

• The parent item is the T-shirt (in red). This is what the buyer will see on the client-side browser.

• The variants of the T-shirt are “Size”, “Color”, “Material” (in blue). These variants will be shown as individual options in the dropdown menu on the item detail page.

• The variant options of those variants, eg. “Red”, “Green” ,“Blue” (in yellow) will also be shown as individual options in the dropdown menu on the item detail page. 

Image caption: Relationship between parent item, variant groups, and variant options

  

Who creates the variants? 

Since parent items are created by merchants, the variants and its variant options are also created by merchants. They are in charge of choosing the names and types of variants and its variant options.

Image caption: merchant’s view when creating variants.

  

How is that relationship reflected in the system and APIs?

When a merchant creates an item with variants similar to the chart above, that means that there are (3 x 3 x 3) 27 possible variations of the same T-shirt. 

 

Of course, that doesn’t necessarily mean that the merchant must have all the possible combinations - that’s why we give the merchant the option to set a quantity for each one of them at the time of creation of the item.

 

In APIs:

 

For each possible combination, each variant will have its own unique item ID also known as a child item ID. In the example of the T-shirt, since there are 27 possible combinations of T-shirt variance, then there will be 27 child item IDs respectively. These child item IDs will be under the parent item ID. 

 

How is this important for developers?

Since a buyer has to choose a variant when buying a T-shirt like this, the Checkout and Cart APIs apply the same rule.

In other words, you have to use the child item ID to add the variant to the cart. In the example of the T-Shirt above, all 27 variants (child items) will have a unique item ID which is different from the parent item ID. 

 

Adding the parent item ID to the “Add Item to Cart API” will return a “null” response. So, do lookout for this!


Exact details can be found in the documentation here.

  

JSON structure of item details of an item with variants

Since a child item is basically an item on its own, all child items will be grouped in an array of child items, a.k.a, typical item detail responses nested within the parent item detail response.

The sample response below is that of an item with 2 variants (Child items): [Not all fields are shown]      


{
	ID: parent_item_ID
	SKU: "string"
	Price: 0
	Categories: [ ],
	CustomFields: [ ],
	HasChildItems: true,
	ChildItems: [{"Variants": [{"Name": "Black","GroupName": "Color"}],
	ID: child_item_ID,
	SKU: "string",
	Price: 1,
	Categories: [ ],
	CustomFields: [ ],
	HasChildItems: false,
	ChildItems: [ ],
	CreatedDateTime: 0,
	ModifiedDateTime: 0},
	{"Variants": [{"Name": "Black","GroupName": "Color",}],
	ID: child_item_ID,
	SKU: "string",
	Price: 1,
	Categories: [ ],
	CustomFields: [ ],
	HasChildItems: false,
	ChildItems: [ ],
	CreatedDateTime: 0,
	ModifiedDateTime: 0}],
	CreatedDateTime: 0,
	ModifiedDateTime: 0
}