Build a Custom Store with droplinked Headless APIs

Platform

Ready to get started?

Platform Functionalities

Physical Inventory

Manage and sell physical products with full inventory control.

Digital Goods

Sell downloadable and digital products instantly.

Affiliate Network

Earn with agentic distribution, verified attribution, and early payouts.

Payment Links

Create shareable payment links to sell faster.

Onboarding Rewards

Get a free month of the Pro plan for getting set up.

Enterprise

Business Financing

Access financing tools to accelerate business growth.

Inventory OS

Mirror Shopify, your affiliate network, and your PSP — then unlock AI shoppers and lender visibility.

DPP

Enable product traceability and trust with digital product passports.

DIMST

Use dynamic merchandising and strategy tools for advanced commerce.

Book a Demo

Talk to our team and see how the platform fits your business.

Connectors & Extensions

Distributed 1-Click Checkout (Embeddables)

Sell on any website with a one-tap checkout — paid on your own account.

Inventory MCP

Expose inventory and orders to AI shopper agents via Model Context Protocol.

Crypto Payments

Accept stablecoins and crypto alongside cards, wallets, and regional rails.

Product Authenticity

Give every product a verifiable record of authenticity and ownership.

Loyalty & Rewards

Launch branded loyalty and rewards programs for your customers.

Subscriptions

Run recurring billing and subscriptions on any payment rail.

Ready to get started?

Home

Blogs

Build a Custom Store with droplinked Headless APIs

Admin

7 Mins Read

Why Headless Commerce Matters

Traditional e-commerce platforms often limit how you can design and manage your store. Templates, fixed workflows, and rigid integrations can slow you down and reduce flexibility.

droplinked Headless APIs solve this.

By separating the frontend (what your customers see) from the backend (where inventory, orders, and payments are handled), droplinked gives you the freedom to:

Build Anywhere: Create fully custom stores directly on your platform or app.

Sync in Real-Time: Keep inventory synced across all channels instantly.

Checkout Your Way: Offer flexible checkout flows that fit your user journey.

Scale Without Limits: Grow without being tied to a single platform's infrastructure.

Who Can Use This Guide?

This guide is designed for anyone who needs a custom commerce experience:

👩‍💻 Developers & Engineers: Integrate a store directly into your app or platform.

🛍️ Brands & E-commerce Managers: Take full control over storefront design, checkout, and user experience.

🎨 Creators & Agencies: Embed commerce into websites, apps, or content platforms.

🚀 Startups & Founders: Launch scalable stores without building everything from scratch.

Who Benefits & How

Developers & Engineers: Save time with clear API documentation, SDKs, and copy-paste examples that work out of the box.

Brands & Retailers: Scale effortlessly. Sync inventory across online and offline channels in real-time while maintaining total control over your customer experience.

Publishers: Turn content into commerce. Embed shoppable products directly into your articles, newsletters, or feeds to monetize readers without sending them away.

Creators: Monetize directly inside your app, game, or platform. Keep your users in your ecosystem instead of linking out to third-party marketplaces.

What You Can Build

With droplinked Headless APIs, the "walled garden" is gone. Here is what you can build today:

Custom Storefronts: Design your store to match your brand and platform perfectly.

Real-Time Inventory: Keep stock synced and accurate across users and channels.

Flexible Checkout: Accept multiple payment methods directly within your app.

Fast Implementation: Use our clear guides, examples, and code snippets to build faster.

Get Started Today

Ready to see droplinked Headless APIs in action? We have created a full API Cookbook, complete with step-by-step tutorials and code examples.

Follow the guide below to build a headless store that fits your platform or app perfectly:

👉 Read the Guide: Building a Custom Store with droplinked Headless APIs

Bottom Line

droplinked Headless APIs give you the flexibility, control, and scalability to create a seamless, fully custom commerce experience, without the limits of traditional platforms.

Getting Started

Prerequisites

Before you begin, you'll need:

Getting Your API Key

Base URL

All droplinked API requests use:

code Code

downloadcontent_copy

expand_less

https://api.io.droplinked.com

Authentication

Every API request requires your API key in the headers:

code Code

downloadcontent_copy

expand_less

x-droplinked-api-key: YOUR_API_KEY_HERE

Content-Type: application/json

Example using cURL:

code Bash

downloadcontent_copy

expand_less

curl -X GET "https://api.io.droplinked.com/shops/v2/public/name/lumen" \

-H "x-droplinked-api-key: YOUR_API_KEY" \

-H "Content-Type: application/json"

Building Your Shop: Step by Step

Step 1: Fetch Shop Information

Get your shop details to display your branding.

API Request:

code Code

downloadcontent_copy

expand_less

GET https://api.io.droplinked.com/shops/v2/public/name/{shopName}

Headers:

x-droplinked-api-key: YOUR_API_KEY

Content-Type: application/json

Response:

code JSON

downloadcontent_copy

expand_less

{

"_id": "69103f6e530855f4b75c4da2",

"id": "69103f6e530855f4b75c4da2",

"name": "Lumen",

"url": "lumen",

"description": "We believe light is an art form. We curate sculptural lamps and architectural lighting designed to transform your space.",

"currency": {

"abbreviation": "USD",

"symbol": "$",

"conversionRateToUSD": 1

}

What to do with this data:

Display shop name in your header

Show description on your homepage

Use currency info for price formatting

Step 2: Display Your Products

Fetch all products to create your product catalog.

API Request:

code Code

downloadcontent_copy

expand_less

GET https://api.io.droplinked.com/product-v2/public/shop/{shopName}

Headers:

x-droplinked-api-key: YOUR_API_KEY

Content-Type: application/json

Response:

code JSON

downloadcontent_copy

expand_less

{

"data": [

{

"id": "6911a2390b1483ce323968e0",

"title": "The Altar Table Lamp",

"slug": "the-altar-table-lamp-f11e0",

"type": "physical",

"status": "published",

"images": [

{

"original": "https://upload-file-droplinked.s3.amazonaws.com/28cefe88...png",

"thumbnail": "https://upload-file-droplinked.s3.amazonaws.com/28cefe88..._small.png",

"alt": "031_Output_Lamp.png"

}

"thumbnail": "https://upload-file-droplinked.s3.amazonaws.com/28cefe88..._small.png",

"isPurchasable": true,

"lowestPrice": 899

}

"currentPage": 1,

"totalPages": 1,

"totalDocuments": 10

}

Important Note: The lowestPrice shown here is for display only. To add items to cart, you need the SKU ID from the product details.

Step 3: Get Product Details (Including SKU)

When a customer clicks on a product, fetch the complete details including the SKU (Stock Keeping Unit) which contains the actual price and inventory.

API Request:

code Code

downloadcontent_copy

expand_less

GET https://api.io.droplinked.com/product-v2/public/{productId}

Headers:

x-droplinked-api-key: YOUR_API_KEY

Content-Type: application/json

Response:

code JSON

downloadcontent_copy

expand_less

{

"id": "6911a2390b1483ce323968e0",

"title": "The Altar Table Lamp",

"description": "A stunning sculptural lamp...",

"images": [

{

"original": "https://upload-file-droplinked.s3.amazonaws.com/...",

"thumbnail": "https://upload-file-droplinked.s3.amazonaws.com/..._small.png"

}

"skus": [

{

"id": "sku_lamp_abc123",

"price": 899,

"currency": "USD",

"inventory": {

"quantity": 10,

"available": true

}

]

}

Understanding SKUs:

Product = The general item (e.g., "Blue T-Shirt")

SKU = A specific variant with price (e.g., "Blue T-Shirt - Size Large - $29.99")

One product can have multiple SKUs (different sizes, colors, etc.)

You add the SKU to cart, not the product

Shopping Cart System

Step 1: Create a Cart

When a customer wants to add their first item, create a cart.

API Request:

code Code

downloadcontent_copy

expand_less

POST https://api.io.droplinked.com/v2/carts

Headers:

x-droplinked-api-key: YOUR_API_KEY

Content-Type: application/json

Body:

{

"shopId": "69103f6e530855f4b75c4da2"

}

Response:

code JSON

downloadcontent_copy

expand_less

{

"items": [],

"availableShipping": [],

"giftcard": null,

"additional": null,

"financialDetails": {

"tax": {

"total": 0,

"taxRate": null,

"droplinked": 0,

"producer": 0

"shipping": {

"total": 0,

"dropLinkedShare": 0,

"merchantShare": 0

"discounts": {

"ruleset": 0,

"giftCard": 0

"amounts": {

"productTotal": 0,

"productTotalAfterDiscount": null,

"discountTotal": 0,

"taxTotal": 0,

"shippingTotal": 0,

"totalBeforeDiscount": 0,

"totalCost": 0,

"finalTotalBeforeTax": 0,

"totalAmount": 0

}

"id": "6927faf705c8819a2dd672ae",

"shopId": "69103f6e530855f4b75c4da2",

"status": "ACTIVE",

"expiredAt": "2025-11-28T07:17:11.570Z",

"createdAt": "2025-11-27T07:17:11.571Z",

"updatedAt": "2025-11-27T07:17:11.571Z",

"_id": "6927faf705c8819a2dd672ae"

}

Save the cart ID: Store 6927faf705c8819a2dd672ae in localStorage (browser) or session (server) so customers can continue shopping.

Step 2: Add Product to Cart

Add items using the SKU ID (not the product ID).

API Request:

code Code

downloadcontent_copy

expand_less

POST https://api.io.droplinked.com/v2/carts/{cartId}/products

Headers:

x-droplinked-api-key: YOUR_API_KEY

Content-Type: application/json

Accept: /

Body:

{

"skuId": "sku_lamp_abc123",

"quantity": 1

}

Optional field m2m_data (only for made-to-measure/custom products):

code JSON

downloadcontent_copy

expand_less

{

"skuId": "sku_custom_item",

"quantity": 1,

"m2m_data": {

"position": "front",

"artworkUrl": "https://example.com/custom-design.png"

}

Response:

code JSON

downloadcontent_copy

expand_less

{

"success": true,

"data": {},

"message": "Product added to cart"

}

Step 3: View Cart Contents

API Request:

code Code

downloadcontent_copy

expand_less

GET https://api.io.droplinked.com/v2/carts/{cartId}

Headers:

x-droplinked-api-key: YOUR_API_KEY

Content-Type: application/json

Response:

code JSON

downloadcontent_copy

expand_less

{

"items": [

{

"skuId": "sku_lamp_abc123",

"title": "The Altar Table Lamp",

"price": 899,

"quantity": 1,

"subtotal": 899,

"image": "https://upload-file-droplinked.s3.amazonaws.com/..."

}

"financialDetails": {

"amounts": {

"productTotal": 899,

"totalAmount": 899

}

Step 4: Update Item Quantity

API Request:

code Code

downloadcontent_copy

expand_less

PATCH https://api.io.droplinked.com/v2/carts/{cartId}/products/{skuId}

Headers:

x-droplinked-api-key: YOUR_API_KEY

Content-Type: application/json

Body:

{

"quantity": 3

}

Response:

code JSON

downloadcontent_copy

expand_less

{

"success": true,

"message": "Quantity updated"

}

Step 5: Remove Item from Cart

API Request:

code Code

downloadcontent_copy

expand_less

DELETE https://api.io.droplinked.com/v2/carts/{cartId}/products/{skuId}

Headers:

x-droplinked-api-key: YOUR_API_KEY

Content-Type: application/json

Response:

code JSON

downloadcontent_copy

expand_less

{

"success": true,

"message": "Product removed from cart"

}

Checkout Process

Step 1: Get Shipping Rates

API Request:

code Code

downloadcontent_copy

expand_less

GET https://api.io.droplinked.com/v2/carts/{cartId}/shipping

Headers:

x-droplinked-api-key: YOUR_API_KEY

Content-Type: application/json

Response:

code JSON

downloadcontent_copy

expand_less

{

"success": true,

"data": [

{

"shipmentId": "shipment_001",

"rateId": "rate_standard",

"name": "Standard Shipping",

"price": 5.99,

"estimatedDays": "5-7 days"

{

"shipmentId": "shipment_001",

"rateId": "rate_express",

"name": "Express Shipping",

"price": 15.99,

"estimatedDays": "2-3 days"

}

]

}

Step 2: Select Shipping Rate

API Request:

code Code

downloadcontent_copy

expand_less

POST https://api.io.droplinked.com/v2/carts/{cartId}/shipping

Headers:

x-droplinked-api-key: YOUR_API_KEY

Content-Type: application/json

Body:

{

"selectedShippingRate": [

{

"shipmentId": "shipment_001",

"rateId": "rate_standard"

}

]

}

Response:

code JSON

downloadcontent_copy

expand_less

{

"success": true,

"message": "Shipping rate selected"

}

Step 3: Get Payment Methods

API Request:

code Code

downloadcontent_copy

expand_less

GET https://api.io.droplinked.com/v2/carts/{cartId}/payment-methods

Headers:

x-droplinked-api-key: YOUR_API_KEY

Content-Type: application/json

Response:

code JSON

downloadcontent_copy

expand_less

{

"success": true,

"data": [

{

"id": "stripe",

"name": "Credit Card",

"type": "card"

{

"id": "paypal",

"name": "PayPal",

"type": "paypal"

}

]

}

Step 4: Create Order

API Request:

code Code

downloadcontent_copy

expand_less

POST https://api.io.droplinked.com/v2/orders

Headers:

x-droplinked-api-key: YOUR_API_KEY

Content-Type: application/json

Body:

{

"cartId": "6927faf705c8819a2dd672ae"

}

Response:

code JSON

downloadcontent_copy

expand_less

{

"success": true,

"data": {

"orderId": "order_final_123",

"total": 904.99,

"status": "pending_payment",

"items": [

{

"title": "The Altar Table Lamp",

"quantity": 1,

"price": 899

}

"shipping": 5.99

}

Complete Code Example (JavaScript/TypeScript)

code JavaScript

downloadcontent_copy

expand_less

const API_KEY = "your-api-key-here";

const SHOP_NAME = "lumen";

const BASE_URL = "https://api.io.droplinked.com";

// Helper function for API calls

async function callAPI(endpoint, method = "GET", body = null) {

const options = {

method,

headers: {

"x-droplinked-api-key": API_KEY,

"Content-Type": "application/json"

}

};

if (body) {

options.body = JSON.stringify(body);

}

const response = await fetch(`${BASE_URL}${endpoint}`, options);

return response.json();

}

// 1. Get shop info

async function getShop() {

return callAPI(`/shops/v2/public/name/${SHOP_NAME}`);

}

// 2. Get all products

async function getProducts() {

return callAPI(`/product-v2/public/shop/${SHOP_NAME}`);

}

// 3. Get product details (with SKU)

async function getProductDetails(productId) {

return callAPI(`/product-v2/public/${productId}`);

}

// 4. Create cart

async function createCart(shopId) {

return callAPI("/v2/carts", "POST", { shopId });

}

// 5. Add to cart

async function addToCart(cartId, skuId, quantity = 1) {

return callAPI(`/v2/carts/${cartId}/products`, "POST", {

skuId,

quantity

});

}

// 6. Get cart

async function getCart(cartId) {

return callAPI(`/v2/carts/${cartId}`);

}

// 7. Update quantity

async function updateQuantity(cartId, skuId, quantity) {

return callAPI(`/v2/carts/${cartId}/products/${skuId}`, "PATCH", {

quantity

});

}

// 8. Remove item

async function removeFromCart(cartId, skuId) {

return callAPI(`/v2/carts/${cartId}/products/${skuId}`, "DELETE");

}

// 9. Get shipping rates

async function getShipping(cartId) {

return callAPI(`/v2/carts/${cartId}/shipping`);

}

// 10. Select shipping

async function selectShipping(cartId, shipmentId, rateId) {

return callAPI(`/v2/carts/${cartId}/shipping`, "POST", {

selectedShippingRate: [{ shipmentId, rateId }]

});

}

// 11. Get payment methods

async function getPaymentMethods(cartId) {

return callAPI(`/v2/carts/${cartId}/payment-methods`);

}

// 12. Create order

async function createOrder(cartId) {

return callAPI("/v2/orders", "POST", { cartId });

}

// Usage Example

async function completeShoppingFlow() {

try {

// Get shop

const shop = await getShop();

console.log("Shop:", shop.name);

// Get products

const productsData = await getProducts();

const products = productsData.data;

console.log(`Found ${products.length} products`);

// Get first product details

const product = await getProductDetails(products[0].id);

console.log("Product:", product.title);

// Get SKU ID

const skuId = product.skus[0].id;

console.log("SKU ID:", skuId);

// Create cart

const cartData = await createCart(shop.id);

const cartId = cartData.id;

console.log("Cart created:", cartId);

// Add to cart

await addToCart(cartId, skuId, 1);

console.log("Product added to cart");

// Get cart contents

const cart = await getCart(cartId);

console.log("Cart total:", cart.financialDetails.amounts.totalAmount);

// Get shipping options

const shipping = await getShipping(cartId);

console.log("Shipping options:", shipping.data.length);

// Select shipping

await selectShipping(

cartId,

shipping.data[0].shipmentId,

shipping.data[0].rateId

);

// Get payment methods

const paymentMethods = await getPaymentMethods(cartId);

console.log("Payment methods:", paymentMethods.data.length);

// Create order

const order = await createOrder(cartId);

console.log("Order created:", order.data.orderId);

} catch (error) {

console.error("Error:", error);

}

// Run the flow

completeShoppingFlow();

Complete Code Example (Python)

code Python

downloadcontent_copy

expand_less

import requests

API_KEY = "your-api-key-here"

SHOP_NAME = "lumen"

BASE_URL = "https://api.io.droplinked.com"

class DroplinkedAPI:

def init(self, api_key, shop_name):

self.api_key = api_key

self.shop_name = shop_name

self.headers = {

"x-droplinked-api-key": api_key,

"Content-Type": "application/json"

}

def get_shop(self):

url = f"{BASE_URL}/shops/v2/public/name/{self.shop_name}"

response = requests.get(url, headers=self.headers)

response.raise_for_status()

return response.json()

def get_products(self):

url = f"{BASE_URL}/product-v2/public/shop/{self.shop_name}"

response = requests.get(url, headers=self.headers)

response.raise_for_status()

return response.json()

def get_product_details(self, product_id):

url = f"{BASE_URL}/product-v2/public/{product_id}"

response = requests.get(url, headers=self.headers)

response.raise_for_status()

return response.json()

def create_cart(self, shop_id):

url = f"{BASE_URL}/v2/carts"

response = requests.post(

url,

headers=self.headers,

json={"shopId": shop_id}

)

response.raise_for_status()

return response.json()

def add_to_cart(self, cart_id, sku_id, quantity=1):

url = f"{BASE_URL}/v2/carts/{cart_id}/products"

response = requests.post(

url,

headers=self.headers,

json={"skuId": sku_id, "quantity": quantity}

)

response.raise_for_status()

return response.json()

def get_cart(self, cart_id):

url = f"{BASE_URL}/v2/carts/{cart_id}"

response = requests.get(url, headers=self.headers)

response.raise_for_status()

return response.json()

def update_quantity(self, cart_id, sku_id, quantity):

url = f"{BASE_URL}/v2/carts/{cart_id}/products/{sku_id}"

response = requests.patch(

url,

headers=self.headers,

json={"quantity": quantity}

)

response.raise_for_status()

return response.json()

def remove_from_cart(self, cart_id, sku_id):

url = f"{BASE_URL}/v2/carts/{cart_id}/products/{sku_id}"

response = requests.delete(url, headers=self.headers)

response.raise_for_status()

return response.json()

def get_shipping(self, cart_id):

url = f"{BASE_URL}/v2/carts/{cart_id}/shipping"

response = requests.get(url, headers=self.headers)

response.raise_for_status()

return response.json()

def select_shipping(self, cart_id, shipment_id, rate_id):

url = f"{BASE_URL}/v2/carts/{cart_id}/shipping"

response = requests.post(

url,

headers=self.headers,

json={

"selectedShippingRate": [

{"shipmentId": shipment_id, "rateId": rate_id}

]

}

)

response.raise_for_status()

return response.json()

def get_payment_methods(self, cart_id):

url = f"{BASE_URL}/v2/carts/{cart_id}/payment-methods"

response = requests.get(url, headers=self.headers)

response.raise_for_status()

return response.json()

def create_order(self, cart_id):

url = f"{BASE_URL}/v2/orders"

response = requests.post(

url,

headers=self.headers,

json={"cartId": cart_id}

)

response.raise_for_status()

return response.json()

# Usage Example

def main():

api = DroplinkedAPI(API_KEY, SHOP_NAME)

try:

# Get shop

shop = api.get_shop()

print(f"Shop: {shop['name']}")

# Get products

products_data = api.get_products()

products = products_data['data']

print(f"Found {len(products)} products")

# Get first product details

product = api.get_product_details(products[0]['id'])

print(f"Product: {product['title']}")

# Get SKU ID

sku_id = product['skus'][0]['id']

print(f"SKU ID: {sku_id}")

# Create cart

cart_data = api.create_cart(shop['id'])

cart_id = cart_data['id']

print(f"Cart created: {cart_id}")

# Add to cart

api.add_to_cart(cart_id, sku_id, 1)

print("Product added to cart")

# Get cart contents

cart = api.get_cart(cart_id)

total = cart['financialDetails']['amounts']['totalAmount']

print(f"Cart total: ${total}")

# Get shipping options

shipping = api.get_shipping(cart_id)

print(f"Shipping options: {len(shipping['data'])}")

# Select shipping

api.select_shipping(

cart_id,

shipping['data'][0]['shipmentId'],

shipping['data'][0]['rateId']

)

Format prices according to currency:

code JavaScript

downloadcontent_copy

expand_less

const formatPrice = (price, currency) => {

return new Intl.NumberFormat('en-US', {

style: 'currency',

currency: currency

}).format(price);

};

// Usage

formatPrice(899, 'USD'); // "$899.00"

Troubleshooting

Common Issues

Issue: "API key not configured"

Check that your API key is correct

Verify the header name is exactly x-droplinked-api-key

Ensure API key hasn't been revoked

Issue: "Cart ID not found"

Cart may have expired (check expiredAt field)

Create a new cart if expired

Verify cart ID is stored correctly

Issue: "Product not found"

Verify product ID is correct

Check product is published (status: "published")

Ensure product belongs to your shop

Issue: "No products returned"

Verify shop name is correct

Check products are published in dashboard

Ensure API key has access to shop

Issue: Can't add to cart

Make sure you're using SKU ID, not product ID

Check SKU has available inventory

Verify cart hasn't expired

API Reference Quick Guide

Conclusion

You now have everything you need to build a custom e-commerce store with droplinked APIs. The key steps are:

Remember:

Always use SKU IDs (not product IDs) for cart operations

Store cart IDs persistently

Handle errors gracefully

Check inventory before adding to cart

Test thoroughly before going live

Ready to build? Start with the shop and products endpoints, then add cart functionality, and finally implement checkout. Good luck building your custom store!

Need Help? Contact droplinked support or consult the official API documentation for more details