Skip to main content
In this guide, you’ll build your own Web3 shop using Droplinked’s API and infrastructure with only frontend code. By leveraging the ready-made APIs, you can set up a fully decentralized e-commerce store with minimal backend involvement.
API reference For the full interactive endpoint browser, see the API Reference tab in this docs site, or the legacy Swagger at apiv3.droplinked.com/v1/public-apis/document.

​
Setting up — your shop API key (x-shop-id)

To make authenticated API calls you first need to generate a unique x-shop-id from your Droplinked dashboard. This ID is included in the headers of every API request to identify and authorize your shop.
Your shop must be upgraded to access API features. API keys are only available to upgraded shops.

​
Steps to generate your x-shop-id

1

Log into Droplinked

Go to droplinked.com and sign in.
2

Open Account Settings

Navigate to Account Settings from the menu.
3

Privacy and Security

Open the Privacy and Security tab.
4

Register your domain

In the Domain section, enter the domain name from which you plan to make API requests (e.g. https://yourstore.com).
5

Copy the generated x-shop-id

Once the domain is added, your unique shop ID is generated. Copy the x-shop-id from the dashboard — you’ll need it for all API calls.
Your request headers should look like this: 
{
  "x-shop-id": "YOUR_SHOP_ID"
}

​
Base URL and authentication

All Droplinked API requests are made to the following base URL: 
https://apiv3.droplinked.com
Include your x-shop-id in the headers of every API call. This value ties each request to your specific shop. 
{
  "x-shop-id": "YOUR_SHOP_ID"
}
All API requests must include this header. Without it, the request will be rejected.

​
API flow overview

The Droplinked API flow follows a simple four-step structure:
1

Shop & product setup

Fetch shop information and available products to display in your frontend.
2

Cart management

Create a cart, add products, update quantities, and attach customer details (email, shipping address).
3

Checkout & payment

Use the checkout APIs and integrate the Droplinked Stripe payment component to process customer payments.
4

Order handling

Retrieve and display final order details for confirmation or tracking.

​
1. Shop and product retrieval

​
Get shop information

Retrieve metadata about your shop — name, description, logo, and other configuration.

​
List products (paginated)

Returns a paginated list of products. Use query parameters to control pagination and filtering.

​
Get product by slug

Useful for SEO-friendly URLs or product pages.

​
Get product by ID

Useful for internal lookups or cart operations.

​
2. Cart management

Once a user starts interacting with products, you’ll need to create and manage a shopping cart session.

​
Create a new shopping cart

​
Retrieve cart information

​
Add product to cart

​
Update cart item quantity

​
Remove item from cart

​
Attach additional details to cart

Add customer-specific information such as email, shipping address, and optional notes — usually required before checkout.

​
3. Customer address (physical products only)

For physical products that require shipping, collect and attach a customer address to the cart.
Address creation is only required if the cart contains physical (non-digital) items.

​
Search available countries

​
Search cities by country

​
Create a new customer address

The returned address ID will be included in the Attach Additional Details to Cart request.

​
4. Shipping management (physical products)

If a cart includes physical products, shipping information must be added before payment. Droplinked automatically returns available shipping methods as part of the cart data.

​
Available shipping options

When you retrieve the cart (GET /v1/cart/{cartId}), the response includes a list of available shipping rates in the shippingOptions (or shipping) section of the payload. These are dynamically generated based on:
  • The customer’s address
  • The cart contents (dimensions, weight, etc.)
  • Your shop’s shipping configuration
Always check for available shipping methods after setting the customer address.

​
Add shipping rate to cart

Once you’ve selected a shipping option, apply it to the cart. Pass the selected shipping-rate ID in the request body.

​
5. Checkout and payment

Once the cart has customer info and (if needed) a shipping rate, kick off the payment process. Droplinked uses Stripe under the hood and provides a dedicated package to simplify integration on the frontend.

​
Create Stripe payment session

Generate a clientSecret for the current cart. This secret is required to initiate the Stripe payment session on the frontend.

​
Install the Droplinked Stripe UI package

npm install droplinked-payment-intent

​
Implement the payment component

Import and use the <DroplinkedPaymentIntent /> component. Pass the clientSecret you got from the previous step, along with the callbacks. 
import React from 'react';
import { DroplinkedPaymentIntent } from 'droplinked-payment-intent';

function PaymentPage() {
  return (
    <div className="payment-container">
      <h2>Complete Your Payment</h2>
      <DroplinkedPaymentIntent
        clientSecret="your_client_secret"
        type="stripe"
        return_url="https://your-return-url.com"
        onSuccess={() => console.log('Payment successful')}
        onCancel={() => console.log('Payment canceled')}
        onError={(error) => console.error('Payment failed', error)}
        isTestnet={true} // Set to false for production
      />
    </div>
  );
}

export default PaymentPage;
Toggle isTestnet depending on whether you’re using a test or live environment.

​
6. Order retrieval

After a successful payment, retrieve the finalized order using the order ID to show confirmation details or track status.

​
Get order by ID