analytics_query
read
Run read-only analytics queries against the production database.
Parameters
reportstringrequired
The report to run
date_fromstringoptional
Start date for the report period (YYYY-MM-DD, default: 30 days ago)
date_tostringoptional
End date for the report period (YYYY-MM-DD, default: today)
| Name | Type | Required | Description |
|---|
| report | string | required | The report to run |
| date_from | string | optional | Start date for the report period (YYYY-MM-DD, default: 30 days ago) |
| date_to | string | optional | End date for the report period (YYYY-MM-DD, default: today) |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/analytics_query" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"report": "example",
"date_from": "example",
"date_to": "example"
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.analytics_query({
"report": "example",
"date_from": "example",
"date_to": "example"
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->analyticsQuery([
'report' => 'example',
'date_from' => 'example',
'date_to' => 'example',
]);
Response
reportstring
periodobject
tenantstring
resultsstring
catalog_flattening_audit
read
Read-only.
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/catalog_flattening_audit" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.catalog_flattening_audit({});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->catalogFlatteningAudit();
Response
tenant_slugstring
summaryobject
flattened_productsinteger
collapsible_familiesinteger
blocked_familiesinteger
products_removed_if_mergedinteger
familiesarray
base_namestring
collapsibleboolean
blockerstring
membersarray
product_idinteger
namestring
slugstring
weight_gramsnumber
price_centsinteger
cost_centsinteger
stock_unitsnumber
customer_addresses
read
Return a customer's saved addresses, coordinates, saved zones, and zone mismatch diagnostics.
Parameters
customer_idintegeroptional
Exact customer id (optional)
emailstringoptional
Exact customer email (optional)
phonestringoptional
Customer phone number (optional)
| Name | Type | Required | Description |
|---|
| customer_id | integer | optional | Exact customer id (optional) |
| email | string | optional | Exact customer email (optional) |
| phone | string | optional | Customer phone number (optional) |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/customer_addresses" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"customer_id": 10,
"email": "example",
"phone": "example"
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.customer_addresses({
"customer_id": 10,
"email": "example",
"phone": "example"
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->customerAddresses([
'customer_id' => 10,
'email' => 'example',
'phone' => 'example',
]);
Response
tenantobject
idinteger
slugstring
namestring
customerobject
addressesarray
customer_list
read
Page through all customers for a tenant, optionally filtered to those updated since a given time.
Parameters
updated_sincestringoptional
ISO-8601 timestamp — only return customers updated at or after this time (optional)
limitintegeroptional
Rows per page (default 25, max 100)
cursorstringoptional
Opaque cursor from a previous response's next_cursor — omit to start from the first page
| Name | Type | Required | Description |
|---|
| updated_since | string | optional | ISO-8601 timestamp — only return customers updated at or after this time (optional) |
| limit | integer | optional | Rows per page (default 25, max 100) |
| cursor | string | optional | Opaque cursor from a previous response's next_cursor — omit to start from the first page |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/customer_list" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"updated_since": "example",
"limit": 10,
"cursor": "example"
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.customer_list({
"updated_since": "example",
"limit": 10,
"cursor": "example"
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->customerList([
'updated_since' => 'example',
'limit' => 10,
'cursor' => 'example',
]);
Response
tenantobject
idinteger
slugstring
namestring
customersarray
idinteger
namestring
emailstring
phonestring
loyalty_pointsinteger
email_verified_atstring
last_login_atstring
id_verified_atstring
medical_record_verified_atstring
phone_verified_atstring
phone_validation_statusstring
no_loyaltyboolean
no_couponsboolean
deletion_requested_atstring
email_opt_outboolean
sms_marketing_opt_outboolean
sms_notifications_mutedboolean
updated_atstring
has_moreboolean
next_cursorstring
customer_lookup
read
Find customers by id, email, phone, or name and return their recent addresses, orders, and support context.
Parameters
customer_idintegeroptional
Exact customer id (optional)
emailstringoptional
Exact customer email (optional)
phonestringoptional
Customer phone number, digits or formatted (optional)
namestringoptional
Partial customer name (optional)
limitintegeroptional
Number of matches to return (default 10, max 25)
| Name | Type | Required | Description |
|---|
| customer_id | integer | optional | Exact customer id (optional) |
| email | string | optional | Exact customer email (optional) |
| phone | string | optional | Customer phone number, digits or formatted (optional) |
| name | string | optional | Partial customer name (optional) |
| limit | integer | optional | Number of matches to return (default 10, max 25) |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/customer_lookup" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"customer_id": 10,
"email": "example",
"phone": "example"
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.customer_lookup({
"customer_id": 10,
"email": "example",
"phone": "example"
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->customerLookup([
'customer_id' => 10,
'email' => 'example',
'phone' => 'example',
]);
Response
tenantobject
idinteger
slugstring
namestring
matched_customersinteger
customersarray
idinteger
namestring
emailstring
phonestring
loyalty_pointsinteger
email_verified_atstring
last_login_atstring
default_address_idinteger
id_verified_atstring
medical_record_verified_atstring
phone_verified_atstring
phone_validation_statusstring
no_loyaltyboolean
no_couponsboolean
deletion_requested_atstring
email_opt_outboolean
sms_marketing_opt_outboolean
sms_notifications_mutedboolean
addresses_countinteger
orders_countinteger
conversation_countinteger
addressesarray
idinteger
labelstring
addressstring
latitudenumber
longitudenumber
zone_idinteger
zone_namestring
is_defaultboolean
recent_ordersarray
idinteger
order_numberstring
statusstring
payment_statusstring
totalinteger
total_displaystring
coupon_codestring
created_atstring
google_analytics
read
Query Google Analytics (GA4) data for the platform (dabdash.com) or a specific tenant with a connected GA integration.
Parameters
reportstringrequired
The report type to run
daysintegeroptional
Number of days to look back (default 30, max 365)
| Name | Type | Required | Description |
|---|
| report | string | required | The report type to run |
| days | integer | optional | Number of days to look back (default 30, max 365) |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/google_analytics" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"report": "example",
"days": 10
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.google_analytics({
"report": "example",
"days": 10
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->googleAnalytics([
'report' => 'example',
'days' => 10,
]);
Response
scopestring
propertystring
property_idstring
reportstring
daysinteger
resultsstring
inventory_audit_lookup
read
Look up the historical inventory state of a list of products from the inventory_audit_logs table.
Parameters
product_idsarrayrequired
List of product IDs to look up.
cutoff_isostringrequired
ISO8601 timestamp. The last quantity_after strictly BEFORE this moment is returned for each variation. Example: "2026-05-03T00:00:00Z".
| Name | Type | Required | Description |
|---|
| product_ids | array | required | List of product IDs to look up. |
| cutoff_iso | string | required | ISO8601 timestamp. The last quantity_after strictly BEFORE this moment is returned for each variation. Example: "2026-05-03T00:00:00Z". |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/inventory_audit_lookup" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"product_ids": [],
"cutoff_iso": "example"
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.inventory_audit_lookup({
"product_ids": [],
"cutoff_iso": "example"
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->inventoryAuditLookup([
'product_ids' => [],
'cutoff_iso' => 'example',
]);
inventory_status
read
Get inventory status across all tenants or a specific tenant.
Parameters
alert_onlybooleanoptional
If true, return only low-stock and out-of-stock items (default false)
| Name | Type | Required | Description |
|---|
| alert_only | boolean | optional | If true, return only low-stock and out-of-stock items (default false) |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/inventory_status" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"alert_only": true
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.inventory_status({
"alert_only": true
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->inventoryStatus([
'alert_only' => true,
]);
Response
summaryobject
total_productsinteger
in_stockinteger
low_stock_alertsinteger
out_of_stockinteger
low_stock_alertsarray
tenantstring
productstring
quantitynumber
thresholdnumber
out_of_stockarray
tenantstring
productstring
in_stock_itemsarray
tenantstring
productstring
quantitynumber
mailbox_inspect
read
Inspect a tenant inbound mailbox: sync watermark, last error, recent ingestion counts (inbound/outbound), and a healthy/bootstrap/stalled/quiet verdict.
Parameters
platformbooleanoptional
Inspect a platform-owned mailbox (tenant_id IS NULL). When true, tenant_slug is ignored and email_account_id is required.
email_account_idintegeroptional
Specific EmailAccount id (required for platform=true; optional for tenant_slug — defaults to the tenant's single mailbox).
| Name | Type | Required | Description |
|---|
| platform | boolean | optional | Inspect a platform-owned mailbox (tenant_id IS NULL). When true, tenant_slug is ignored and email_account_id is required. |
| email_account_id | integer | optional | Specific EmailAccount id (required for platform=true; optional for tenant_slug — defaults to the tenant's single mailbox). |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/mailbox_inspect" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"platform": true,
"email_account_id": 10
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.mailbox_inspect({
"platform": true,
"email_account_id": 10
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->mailboxInspect([
'platform' => true,
'email_account_id' => 10,
]);
Response
accountobject
idinteger
tenant_idinteger
tenant_slugstring
labelstring
protocolstring
hoststring
portinteger
usernamestring
encryptionstring
folderstring
is_activeboolean
leave_on_serverboolean
sync_stateobject
ingestionobject
verdictobject
statestring
explanationstring
suggested_actionstring
recent_messagesarray
idinteger
directionstring
from_domainstring
subject_lengthinteger
fetched_atstring
has_attachmentsboolean
metrc_diagnostics
read
Returns a JSON summary of Metrc compliance status for a tenant: integration mode, sync states, audit log counts by HTTP status, and pending/failed report counts.
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/metrc_diagnostics" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.metrc_diagnostics({});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->metrcDiagnostics();
Response
tenantobject
idinteger
slugstring
namestring
integrationstring
sync_statesarray
resourcestring
last_run_atstring
last_errorstring
staleboolean
audit_log_counts_by_http_statusobject
report_counts_by_statusobject
last_reconciliation_runobject
run_atstring
matched_countinteger
drifted_countinteger
notestring
order_dashboard
read
Query orders across all tenants.
Parameters
order_numberstringoptional
Exact order number (optional)
customer_emailstringoptional
Exact customer email (optional)
customer_phonestringoptional
Customer phone number, digits or formatted (optional)
statusstringoptional
Filter by order status: pending, confirmed, preparing, out_for_delivery, delivered, cancelled
payment_statusstringoptional
Filter by payment status: pending, paid, failed, refunded
date_fromstringoptional
Start date filter (YYYY-MM-DD format)
date_tostringoptional
End date filter (YYYY-MM-DD format)
min_totalintegeroptional
Minimum order total in cents
limitintegeroptional
Number of orders to return (default 25, max 100)
| Name | Type | Required | Description |
|---|
| order_number | string | optional | Exact order number (optional) |
| customer_email | string | optional | Exact customer email (optional) |
| customer_phone | string | optional | Customer phone number, digits or formatted (optional) |
| status | string | optional | Filter by order status: pending, confirmed, preparing, out_for_delivery, delivered, cancelled |
| payment_status | string | optional | Filter by payment status: pending, paid, failed, refunded |
| date_from | string | optional | Start date filter (YYYY-MM-DD format) |
| date_to | string | optional | End date filter (YYYY-MM-DD format) |
| min_total | integer | optional | Minimum order total in cents |
| limit | integer | optional | Number of orders to return (default 25, max 100) |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/order_dashboard" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"order_number": "example",
"customer_email": "example",
"customer_phone": "example"
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.order_dashboard({
"order_number": "example",
"customer_email": "example",
"customer_phone": "example"
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->orderDashboard([
'order_number' => 'example',
'customer_email' => 'example',
'customer_phone' => 'example',
]);
Response
summaryobject
ordersarray
idinteger
order_numberstring
tenantstring
statusstring
payment_statusstring
subtotalstring
totalstring
customer_emailstring
customer_phonestring
coupon_codestring
coupon_discountstring
mix_match_discountstring
loyalty_discountstring
is_asapboolean
scheduled_atstring
delivered_atstring
created_atstring
product_inspect
read
Inspect a specific product including every variation's price, compare_at_price, mix_match_tags, stock, and the tenant's mix & match rule settings.
Parameters
product_idintegeroptional
Exact product id (optional if name_query or sku supplied)
name_querystringoptional
Partial product name match (optional if product_id or sku supplied)
skustringoptional
Exact SKU of a variation belonging to the product (optional if product_id or name_query supplied). SKUs are unique per tenant.
| Name | Type | Required | Description |
|---|
| product_id | integer | optional | Exact product id (optional if name_query or sku supplied) |
| name_query | string | optional | Partial product name match (optional if product_id or sku supplied) |
| sku | string | optional | Exact SKU of a variation belonging to the product (optional if product_id or name_query supplied). SKUs are unique per tenant. |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/product_inspect" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"product_id": 10,
"name_query": "example",
"sku": "example"
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.product_inspect({
"product_id": 10,
"name_query": "example",
"sku": "example"
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->productInspect([
'product_id' => 10,
'name_query' => 'example',
'sku' => 'example',
]);
Response
tenantobject
mix_match_settingsobject
productsarray
idinteger
namestring
slugstring
tracking_typestring
inventory_modestring
stock_quantitynumber
stock_statusstring
pricing_structurestring
variationsarray
promotion_audit
read
Inspect coupons, freebies, mix and match rules, loyalty settings, and storewide sale state for overcharge or missed-discount support tickets.
Parameters
order_numberstringoptional
Optional order number to compare against configured promotions
include_inactivebooleanoptional
Include inactive or expired promotions too (optional)
| Name | Type | Required | Description |
|---|
| order_number | string | optional | Optional order number to compare against configured promotions |
| include_inactive | boolean | optional | Include inactive or expired promotions too (optional) |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/promotion_audit" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"order_number": "example",
"include_inactive": true
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.promotion_audit({
"order_number": "example",
"include_inactive": true
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->promotionAudit([
'order_number' => 'example',
'include_inactive' => true,
]);
Response
tenantobject
idinteger
slugstring
namestring
orderobject
storewide_saleobject
activeboolean
typestring
amountnumber
loyaltyobject
bundlesarray
idinteger
namestring
quantityinteger
discount_typestring
discount_valuenumber
discount_displaystring
is_activeboolean
variation_countinteger
mix_matchobject
notestring
rulesarray
tagstring
quantityinteger
discount_typestring
discount_valuenumber
tagged_variationsarray
variation_idinteger
productstring
variationstring
priceinteger
tagsarray
couponsarray
freebiesarray
idinteger
namestring
spend_thresholdinteger
quantityinteger
is_stackableboolean
is_activeboolean
starts_atstring
ends_atstring
productstring
variationstring
push_notification_diagnostics
read
Diagnose push notification (FCM) delivery for a vendor.
Parameters
hoursintegeroptional
Lookback window for notification history in hours (default 72, max 720)
limitintegeroptional
Max recent notifications to return (default 50, max 200)
| Name | Type | Required | Description |
|---|
| hours | integer | optional | Lookback window for notification history in hours (default 72, max 720) |
| limit | integer | optional | Max recent notifications to return (default 50, max 200) |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/push_notification_diagnostics" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"hours": 10,
"limit": 10
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.push_notification_diagnostics({
"hours": 10,
"limit": 10
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->pushNotificationDiagnostics([
'hours' => 10,
'limit' => 10,
]);
search_console
read
Query Google Search Console data for the platform (dabdash.com) or a specific tenant with a connected GSC integration.
Parameters
reportstringrequired
The report type to run
daysintegeroptional
Number of days to look back (default 30, max 365)
| Name | Type | Required | Description |
|---|
| report | string | required | The report type to run |
| days | integer | optional | Number of days to look back (default 30, max 365) |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/search_console" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"report": "example",
"days": 10
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.search_console({
"report": "example",
"days": 10
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->searchConsole([
'report' => 'example',
'days' => 10,
]);
Response
scopestring
site_urlstring
reportstring
daysinteger
resultsstring
store_info
read
Identify the connected store — name, slug, timezone, currency, country, and subscription status.
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/store_info" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.store_info({});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->storeInfo();
zone_diagnostics
read
Inspect zone polygons against customer or order coordinates to explain why an address is inside or outside delivery coverage.
Parameters
customer_address_idintegeroptional
Saved customer address id to inspect (optional)
order_numberstringoptional
Order number whose delivery address should be checked (optional)
zone_idintegeroptional
Specific zone to compare against (optional)
latitudenumberoptional
Manual latitude to test (optional)
longitudenumberoptional
Manual longitude to test (optional)
| Name | Type | Required | Description |
|---|
| customer_address_id | integer | optional | Saved customer address id to inspect (optional) |
| order_number | string | optional | Order number whose delivery address should be checked (optional) |
| zone_id | integer | optional | Specific zone to compare against (optional) |
| latitude | number | optional | Manual latitude to test (optional) |
| longitude | number | optional | Manual longitude to test (optional) |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/zone_diagnostics" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"customer_address_id": 10,
"order_number": "example",
"zone_id": 10
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.zone_diagnostics({
"customer_address_id": 10,
"order_number": "example",
"zone_id": 10
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->zoneDiagnostics([
'customer_address_id' => 10,
'order_number' => 'example',
'zone_id' => 10,
]);
bundle_list
write
List a tenant's bundle deals ("mix & match" — e.g.
Parameters
include_variation_idsbooleanoptional
Include the list of attached product variation IDs for each bundle. Defaults to false.
only_activebooleanoptional
Return only is_active bundles. Defaults to false (all bundles).
| Name | Type | Required | Description |
|---|
| include_variation_ids | boolean | optional | Include the list of attached product variation IDs for each bundle. Defaults to false. |
| only_active | boolean | optional | Return only is_active bundles. Defaults to false (all bundles). |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/bundle_list" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"include_variation_ids": true,
"only_active": true
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.bundle_list({
"include_variation_ids": true,
"only_active": true
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->bundleList([
'include_variation_ids' => true,
'only_active' => true,
]);
bundle_upsert
write
Create or update a bundle deal (mix & match) on behalf of a tenant.
Parameters
bundle_idintegeroptional
ID of an existing bundle to update. Omit to create a new bundle.
namestringoptional
Bundle name shown to vendors and customers (e.g. "Any 4 for $77"). Required when creating.
quantityintegeroptional
Trigger threshold — number of cart units that activates the deal. Min 2. Required when creating.
discount_typestringoptional
"percent", "fixed" (per-unit dollars), or "fixed_total" (dollars for the whole set). Required when creating.
discount_valuenumberoptional
Percent 0–100 for "percent"; dollars for "fixed" and "fixed_total". Required when creating.
is_activebooleanoptional
Whether the bundle is live. Defaults to true on create; left unchanged on update unless passed.
starts_atstringoptional
Optional start datetime (tenant timezone, stored as UTC). Pass null to clear.
ends_atstringoptional
Optional end datetime (tenant timezone, stored as UTC). Must be on/after starts_at. Pass null to clear.
variation_idsarrayoptional
Product variation IDs to apply the bundle to. Omit to leave membership unchanged.
variation_modestringoptional
How to apply variation_ids: "replace" (default), "add", or "detach".
| Name | Type | Required | Description |
|---|
| bundle_id | integer | optional | ID of an existing bundle to update. Omit to create a new bundle. |
| name | string | optional | Bundle name shown to vendors and customers (e.g. "Any 4 for $77"). Required when creating. |
| quantity | integer | optional | Trigger threshold — number of cart units that activates the deal. Min 2. Required when creating. |
| discount_type | string | optional | "percent", "fixed" (per-unit dollars), or "fixed_total" (dollars for the whole set). Required when creating. |
| discount_value | number | optional | Percent 0–100 for "percent"; dollars for "fixed" and "fixed_total". Required when creating. |
| is_active | boolean | optional | Whether the bundle is live. Defaults to true on create; left unchanged on update unless passed. |
| starts_at | string | optional | Optional start datetime (tenant timezone, stored as UTC). Pass null to clear. |
| ends_at | string | optional | Optional end datetime (tenant timezone, stored as UTC). Must be on/after starts_at. Pass null to clear. |
| variation_ids | array | optional | Product variation IDs to apply the bundle to. Omit to leave membership unchanged. |
| variation_mode | string | optional | How to apply variation_ids: "replace" (default), "add", or "detach". |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/bundle_upsert" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"bundle_id": 10,
"name": "example",
"quantity": 10
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.bundle_upsert({
"bundle_id": 10,
"name": "example",
"quantity": 10
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->bundleUpsert([
'bundle_id' => 10,
'name' => 'example',
'quantity' => 10,
]);
campaign_apply_template
write
Apply a built-in system email template to a DRAFT campaign, replacing its html_body with the.
Parameters
campaign_idintegerrequired
ID of the DRAFT campaign to apply the template to.
template_idstringoptional
System template id (e.g. "summer-new-arrivals"). Omit to list available templates.
| Name | Type | Required | Description |
|---|
| campaign_id | integer | required | ID of the DRAFT campaign to apply the template to. |
| template_id | string | optional | System template id (e.g. "summer-new-arrivals"). Omit to list available templates. |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/campaign_apply_template" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"campaign_id": 10,
"template_id": "example"
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.campaign_apply_template({
"campaign_id": 10,
"template_id": "example"
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->campaignApplyTemplate([
'campaign_id' => 10,
'template_id' => 'example',
]);
campaign_control
write
Pause or resume a vendor email/SMS campaign.
Parameters
campaign_idintegerrequired
ID of the campaign to pause or resume.
actionstringrequired
"pause" or "resume".
dry_runbooleanoptional
If true (default), report without writing. Pass false to apply.
| Name | Type | Required | Description |
|---|
| campaign_id | integer | required | ID of the campaign to pause or resume. |
| action | string | required | "pause" or "resume". |
| dry_run | boolean | optional | If true (default), report without writing. Pass false to apply. |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/campaign_control" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"campaign_id": 10,
"action": "example",
"dry_run": true
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.campaign_control({
"campaign_id": 10,
"action": "example",
"dry_run": true
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->campaignControl([
'campaign_id' => 10,
'action' => 'example',
'dry_run' => true,
]);
Response
actionstring
dry_runboolean
tenant_slugstring
campaign_idinteger
campaign_namestring
previous_statusstring
statusstring
messagestring
campaign_recipients_requeue
write
Unstick a vendor email/SMS campaign that auto-paused or stalled mid-send.
Parameters
campaign_idintegerrequired
ID of the campaign to unstick.
include_failedbooleanoptional
Reset failed recipients to pending. Default true.
reset_stale_sendingbooleanoptional
Reset stuck status=sending recipients to pending. Default true.
retry_sending_log_errorsbooleanoptional
Retry recipients listed in the campaign sending error log (retryable types only). Default false.
dispatch_limitintegeroptional
Max immediate send jobs when retry_sending_log_errors=true (default 200, max 500).
dry_runbooleanoptional
If true (default), report counts without writing. Pass false to apply.
| Name | Type | Required | Description |
|---|
| campaign_id | integer | required | ID of the campaign to unstick. |
| include_failed | boolean | optional | Reset failed recipients to pending. Default true. |
| reset_stale_sending | boolean | optional | Reset stuck status=sending recipients to pending. Default true. |
| retry_sending_log_errors | boolean | optional | Retry recipients listed in the campaign sending error log (retryable types only). Default false. |
| dispatch_limit | integer | optional | Max immediate send jobs when retry_sending_log_errors=true (default 200, max 500). |
| dry_run | boolean | optional | If true (default), report counts without writing. Pass false to apply. |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/campaign_recipients_requeue" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"campaign_id": 10,
"include_failed": true,
"reset_stale_sending": true
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.campaign_recipients_requeue({
"campaign_id": 10,
"include_failed": true,
"reset_stale_sending": true
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->campaignRecipientsRequeue([
'campaign_id' => 10,
'include_failed' => true,
'reset_stale_sending' => true,
]);
Response
actionstring
dry_runboolean
tenant_slugstring
campaign_idinteger
campaign_namestring
previous_statusstring
statusstring
pending_beforeinteger
failed_beforeinteger
sending_beforeinteger
failed_requeuedinteger
sending_resetinteger
pending_afterinteger
failed_afterinteger
sending_log_error_rowsinteger
sending_log_recipients_matchedinteger
sending_log_recipients_resetinteger
sending_log_jobs_dispatchedinteger
messagestring
campaign_send_test
write
Send a single test copy of a campaign so the design and copy can be reviewed before the real send.
Parameters
campaign_idintegerrequired
ID of the campaign to send a test copy of.
to_emailstringoptional
Email address for an email campaign test copy.
to_phonestringoptional
Phone number for a text campaign test copy (E.164 or local format).
| Name | Type | Required | Description |
|---|
| campaign_id | integer | required | ID of the campaign to send a test copy of. |
| to_email | string | optional | Email address for an email campaign test copy. |
| to_phone | string | optional | Phone number for a text campaign test copy (E.164 or local format). |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/campaign_send_test" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"campaign_id": 10,
"to_email": "example",
"to_phone": "example"
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.campaign_send_test({
"campaign_id": 10,
"to_email": "example",
"to_phone": "example"
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->campaignSendTest([
'campaign_id' => 10,
'to_email' => 'example',
'to_phone' => 'example',
]);
Response
actionstring
channelstring
campaign_idinteger
sent_tostring
messagestring
campaign_set_image
write
Drop an image from the tenant's media library into a DRAFT campaign — no link copying, no manual.
Parameters
campaign_idintegerrequired
ID of the DRAFT campaign to place the image into.
media_idintegerrequired
ID of a public image in the tenant's media library to insert.
slot_indexintegeroptional
1-based placeholder to fill when the body has more than one. Defaults to the first.
alt_textstringoptional
Override alt text. Defaults to the media asset's own alt text, then the campaign name.
| Name | Type | Required | Description |
|---|
| campaign_id | integer | required | ID of the DRAFT campaign to place the image into. |
| media_id | integer | required | ID of a public image in the tenant's media library to insert. |
| slot_index | integer | optional | 1-based placeholder to fill when the body has more than one. Defaults to the first. |
| alt_text | string | optional | Override alt text. Defaults to the media asset's own alt text, then the campaign name. |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/campaign_set_image" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"campaign_id": 10,
"media_id": 10,
"slot_index": 10
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.campaign_set_image({
"campaign_id": 10,
"media_id": 10,
"slot_index": 10
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->campaignSetImage([
'campaign_id' => 10,
'media_id' => 10,
'slot_index' => 10,
]);
campaign_upsert
write
Create or edit a vendor email campaign on behalf of a tenant.
Parameters
campaign_idintegeroptional
ID of an existing campaign to edit. Omit to create a new draft.
namestringoptional
Internal campaign name (max 120 chars). Required when creating.
channelstringoptional
"email" (default) or "sms" (text blast). Only set on create.
subjectstringoptional
Email subject line shown to recipients (max 200 chars). Required when creating an email campaign.
html_bodystringoptional
Full email HTML. Sanitized on save. Use {{unsubscribe_url}}, {{first_name}}, {{last_name}} tokens.
sms_bodystringoptional
Text message body for SMS campaigns (max 1600 chars). Required when creating a text campaign.
plain_bodystringoptional
Optional plain-text alternative. Auto-derived from the HTML at send time if omitted.
modestringoptional
"smtp" (default) or "webhook". Left unchanged on update unless passed.
audience_includes_customersbooleanoptional
Whether to include the tenant's customers in the audience. Defaults to true on create.
| Name | Type | Required | Description |
|---|
| campaign_id | integer | optional | ID of an existing campaign to edit. Omit to create a new draft. |
| name | string | optional | Internal campaign name (max 120 chars). Required when creating. |
| channel | string | optional | "email" (default) or "sms" (text blast). Only set on create. |
| subject | string | optional | Email subject line shown to recipients (max 200 chars). Required when creating an email campaign. |
| html_body | string | optional | Full email HTML. Sanitized on save. Use {{unsubscribe_url}}, {{first_name}}, {{last_name}} tokens. |
| sms_body | string | optional | Text message body for SMS campaigns (max 1600 chars). Required when creating a text campaign. |
| plain_body | string | optional | Optional plain-text alternative. Auto-derived from the HTML at send time if omitted. |
| mode | string | optional | "smtp" (default) or "webhook". Left unchanged on update unless passed. |
| audience_includes_customers | boolean | optional | Whether to include the tenant's customers in the audience. Defaults to true on create. |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/campaign_upsert" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"campaign_id": 10,
"name": "example",
"channel": "example"
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.campaign_upsert({
"campaign_id": 10,
"name": "example",
"channel": "example"
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->campaignUpsert([
'campaign_id' => 10,
'name' => 'example',
'channel' => 'example',
]);
catalog_collapse
write
Merges a group of size-split products into ONE product with size options.
Parameters
base_namestringrequired
The group to merge, exactly as returned by catalog_flattening_audit (e.g. "GLITTER BOMB | TOP SHELF FLOWER").
dry_runbooleanoptional
Defaults to TRUE — shows the plan without changing anything. Pass false to actually merge.
| Name | Type | Required | Description |
|---|
| base_name | string | required | The group to merge, exactly as returned by catalog_flattening_audit (e.g. "GLITTER BOMB | TOP SHELF FLOWER"). |
| dry_run | boolean | optional | Defaults to TRUE — shows the plan without changing anything. Pass false to actually merge. |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/catalog_collapse" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"base_name": "example",
"dry_run": true
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.catalog_collapse({
"base_name": "example",
"dry_run": true
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->catalogCollapse([
'base_name' => 'example',
'dry_run' => true,
]);
category_manage
write
List, create, update, or delete a tenant's storefront categories.
Parameters
actionstringoptional
"list" (default), "create", "update", or "delete".
category_idintegeroptional
ID of an existing category. Required for update and delete.
namestringoptional
Category name shown to customers. Required when creating.
slugstringoptional
URL slug, unique per tenant. Auto-generated from name when omitted on create.
descriptionstringoptional
Optional category description.
parent_idintegeroptional
Parent category id, or null for a top-level category.
sort_orderintegeroptional
Display order (lower sorts first).
is_activebooleanoptional
Whether the category is visible on the storefront.
is_featuredbooleanoptional
Whether the category appears in the homepage featured grid.
media_idintegeroptional
Media library asset id to set as image_path (the branded, customer-facing image).
base_media_idintegeroptional
Media library asset id to set as base_image_path (the unbranded source canvas).
confirmbooleanoptional
Required (true) for action=delete.
| Name | Type | Required | Description |
|---|
| action | string | optional | "list" (default), "create", "update", or "delete". |
| category_id | integer | optional | ID of an existing category. Required for update and delete. |
| name | string | optional | Category name shown to customers. Required when creating. |
| slug | string | optional | URL slug, unique per tenant. Auto-generated from name when omitted on create. |
| description | string | optional | Optional category description. |
| parent_id | integer | optional | Parent category id, or null for a top-level category. |
| sort_order | integer | optional | Display order (lower sorts first). |
| is_active | boolean | optional | Whether the category is visible on the storefront. |
| is_featured | boolean | optional | Whether the category appears in the homepage featured grid. |
| media_id | integer | optional | Media library asset id to set as image_path (the branded, customer-facing image). |
| base_media_id | integer | optional | Media library asset id to set as base_image_path (the unbranded source canvas). |
| confirm | boolean | optional | Required (true) for action=delete. |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/category_manage" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"action": "example",
"category_id": 10,
"name": "example"
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.category_manage({
"action": "example",
"category_id": 10,
"name": "example"
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->categoryManage([
'action' => 'example',
'category_id' => 10,
'name' => 'example',
]);
Response
actionstring
tenantobject
totalinteger
categoriesarray
idinteger
namestring
slugstring
parent_idinteger
sort_orderinteger
is_activeboolean
is_featuredboolean
image_urlstring
base_image_pathstring
product_countinteger
categoryobject
idinteger
namestring
slugstring
parent_idinteger
sort_orderinteger
is_activeboolean
is_featuredboolean
image_urlstring
base_image_pathstring
messagestring
customer_update
write
Update a customer's contact fields (name, email, phone) and/or suppress marketing consent (email_opt_out, sms_marketing_opt_out, sms_notifications_muted — one-way, cannot un-suppress).
Parameters
customer_idintegerrequired
The customer to update
namestringoptional
New display name
emailstringoptional
New email address (must be unique within the tenant)
phonestringoptional
New phone number, digits or formatted
email_opt_outbooleanoptional
Set true to suppress marketing email. Cannot be set to false — un-suppression happens in DabDash only.
sms_marketing_opt_outbooleanoptional
Set true to suppress marketing texts. Cannot be set to false.
sms_notifications_mutedbooleanoptional
Set true to mute transactional/order SMS notifications. Cannot be set to false.
| Name | Type | Required | Description |
|---|
| customer_id | integer | required | The customer to update |
| name | string | optional | New display name |
| email | string | optional | New email address (must be unique within the tenant) |
| phone | string | optional | New phone number, digits or formatted |
| email_opt_out | boolean | optional | Set true to suppress marketing email. Cannot be set to false — un-suppression happens in DabDash only. |
| sms_marketing_opt_out | boolean | optional | Set true to suppress marketing texts. Cannot be set to false. |
| sms_notifications_muted | boolean | optional | Set true to mute transactional/order SMS notifications. Cannot be set to false. |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/customer_update" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"customer_id": 10,
"name": "example",
"email": "example"
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.customer_update({
"customer_id": 10,
"name": "example",
"email": "example"
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->customerUpdate([
'customer_id' => 10,
'name' => 'example',
'email' => 'example',
]);
Response
customerobject
updated_fieldsarray
media_compose
write
Build a finished campaign image ON THE SERVER: take a base picture, drop the vendor's logo on.
Parameters
base_media_idintegeroptional
ID of a library image to use as the background. Provide exactly one of base_media_id or base_url.
base_urlstringoptional
Public http(s) URL of the background image. Provide exactly one of base_media_id or base_url.
logo_media_idintegeroptional
ID of a library image to place on top, unaltered. At most one of logo_media_id or logo_url.
logo_urlstringoptional
Public http(s) URL of the logo to place on top, unaltered.
headlinestringoptional
Large text under the logo (max 120 chars). Wrapped to at most 2 lines.
subtitlestringoptional
Smaller text under the headline (max 200 chars). Wrapped to at most 3 lines.
fontstringoptional
Typeface: anton, bebas, oswald, playfair, sans, serif. Defaults to "sans".
logo_positionstringoptional
Vertical placement of the whole block: "top", "center" (default) or "bottom".
logo_width_pctnumberoptional
Logo width as a fraction of the base width, 0.05-0.90. Defaults to 0.30.
text_colorstringoptional
Headline colour as #RRGGBB. Defaults to #FFFFFF.
subtitle_colorstringoptional
Subtitle colour as #RRGGBB. Defaults to text_color.
headline_size_pctnumberoptional
Headline size as a fraction of base width, 0.01-0.25. Defaults to 0.07.
subtitle_size_pctnumberoptional
Subtitle size as a fraction of base width, 0.01-0.15. Defaults to 0.035.
scrimstringoptional
Darkening behind the logo/text for legibility: "none", "soft" (default) or "strong".
text_shadowbooleanoptional
Draw a soft shadow under the text. Defaults to true.
filenamestringoptional
Filename to record for the new asset (e.g. "natal-day-hero.png").
alt_textstringoptional
Alt text for accessibility and captions (max 500 chars).
folderstringoptional
Library folder to group the asset under (max 100 chars).
| Name | Type | Required | Description |
|---|
| base_media_id | integer | optional | ID of a library image to use as the background. Provide exactly one of base_media_id or base_url. |
| base_url | string | optional | Public http(s) URL of the background image. Provide exactly one of base_media_id or base_url. |
| logo_media_id | integer | optional | ID of a library image to place on top, unaltered. At most one of logo_media_id or logo_url. |
| logo_url | string | optional | Public http(s) URL of the logo to place on top, unaltered. |
| headline | string | optional | Large text under the logo (max 120 chars). Wrapped to at most 2 lines. |
| subtitle | string | optional | Smaller text under the headline (max 200 chars). Wrapped to at most 3 lines. |
| font | string | optional | Typeface: anton, bebas, oswald, playfair, sans, serif. Defaults to "sans". |
| logo_position | string | optional | Vertical placement of the whole block: "top", "center" (default) or "bottom". |
| logo_width_pct | number | optional | Logo width as a fraction of the base width, 0.05-0.90. Defaults to 0.30. |
| text_color | string | optional | Headline colour as #RRGGBB. Defaults to #FFFFFF. |
| subtitle_color | string | optional | Subtitle colour as #RRGGBB. Defaults to text_color. |
| headline_size_pct | number | optional | Headline size as a fraction of base width, 0.01-0.25. Defaults to 0.07. |
| subtitle_size_pct | number | optional | Subtitle size as a fraction of base width, 0.01-0.15. Defaults to 0.035. |
| scrim | string | optional | Darkening behind the logo/text for legibility: "none", "soft" (default) or "strong". |
| text_shadow | boolean | optional | Draw a soft shadow under the text. Defaults to true. |
| filename | string | optional | Filename to record for the new asset (e.g. "natal-day-hero.png"). |
| alt_text | string | optional | Alt text for accessibility and captions (max 500 chars). |
| folder | string | optional | Library folder to group the asset under (max 100 chars). |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/media_compose" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"base_media_id": 10,
"base_url": "example",
"logo_media_id": 10
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.media_compose({
"base_media_id": 10,
"base_url": "example",
"logo_media_id": 10
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->mediaCompose([
'base_media_id' => 10,
'base_url' => 'example',
'logo_media_id' => 10,
]);
Response
actionstring
media_idinteger
urlstring
mime_typestring
widthinteger
heightinteger
size_bytesinteger
original_filenamestring
alt_textstring
folderstring
visibilitystring
composed_layersstring
wrappedboolean
messagestring
media_list
write
List the images in a tenant's media library — id, public URL, dimensions, filename, folder, and alt.
Parameters
visibilitystringoptional
"public" (default), "private", or "all".
folderstringoptional
Only return assets in this exact library folder.
searchstringoptional
Filter by a substring of the original filename.
| Name | Type | Required | Description |
|---|
| visibility | string | optional | "public" (default), "private", or "all". |
| folder | string | optional | Only return assets in this exact library folder. |
| search | string | optional | Filter by a substring of the original filename. |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/media_list" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"visibility": "example",
"folder": "example",
"search": "example"
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.media_list({
"visibility": "example",
"folder": "example",
"search": "example"
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->mediaList([
'visibility' => 'example',
'folder' => 'example',
'search' => 'example',
]);
Response
tenantobject
visibilitystring
totalinteger
returnedinteger
truncatedboolean
assetsarray
media_idinteger
urlstring
original_filenamestring
mime_typestring
widthinteger
heightinteger
orientationstring
folderstring
alt_textstring
size_bytesinteger
visibilitystring
created_atstring
media_upload
write
Upload an image into a tenant's media library (the same library the vendor admin uses).
Parameters
source_urlstringoptional
Public http(s) URL to fetch the image from. Provide exactly one source.
source_pathstringoptional
Local file path to read the image from. Provide exactly one source.
source_base64stringoptional
Base64-encoded image bytes (data: prefix optional). Provide exactly one source.
filenamestringoptional
Original filename to record (e.g. "summer-flyer.png"). Defaults to a derived name.
alt_textstringoptional
Alt text for accessibility and captions (max 500 chars).
folderstringoptional
Optional library folder to group the asset under (max 100 chars).
| Name | Type | Required | Description |
|---|
| source_url | string | optional | Public http(s) URL to fetch the image from. Provide exactly one source. |
| source_path | string | optional | Local file path to read the image from. Provide exactly one source. |
| source_base64 | string | optional | Base64-encoded image bytes (data: prefix optional). Provide exactly one source. |
| filename | string | optional | Original filename to record (e.g. "summer-flyer.png"). Defaults to a derived name. |
| alt_text | string | optional | Alt text for accessibility and captions (max 500 chars). |
| folder | string | optional | Optional library folder to group the asset under (max 100 chars). |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/media_upload" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"source_url": "example",
"source_path": "example",
"source_base64": "example"
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.media_upload({
"source_url": "example",
"source_path": "example",
"source_base64": "example"
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->mediaUpload([
'source_url' => 'example',
'source_path' => 'example',
'source_base64' => 'example',
]);
Response
actionstring
media_idinteger
urlstring
mime_typestring
widthinteger
heightinteger
size_bytesinteger
original_filenamestring
alt_textstring
folderstring
visibilitystring
messagestring
pricing_structure_assign
write
Assign a shared bundle pricing structure to one or more products.
Parameters
structure_idintegerrequired
ID of the shared BUNDLE structure to assign. Must NOT be a hidden (inline) structure.
product_slugsarrayoptional
List of product slugs to assign to this structure. Provide product_slugs or product_ids (or both).
product_idsarrayoptional
List of product IDs to assign to this structure. Provide product_slugs or product_ids (or both).
| Name | Type | Required | Description |
|---|
| structure_id | integer | required | ID of the shared BUNDLE structure to assign. Must NOT be a hidden (inline) structure. |
| product_slugs | array | optional | List of product slugs to assign to this structure. Provide product_slugs or product_ids (or both). |
| product_ids | array | optional | List of product IDs to assign to this structure. Provide product_slugs or product_ids (or both). |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/pricing_structure_assign" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"structure_id": 10,
"product_slugs": [],
"product_ids": []
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.pricing_structure_assign({
"structure_id": 10,
"product_slugs": [],
"product_ids": []
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->pricingStructureAssign([
'structure_id' => 10,
'product_slugs' => [],
'product_ids' => [],
]);
Response
structure_idinteger
structure_namestring
tracking_typestring
summaryobject
assignedinteger
skippedinteger
refusedinteger
not_foundinteger
resultsarray
pricing_structure_delete
write
Delete one or more pricing structures by ID.
Parameters
structure_idsarrayrequired
List of structure IDs to delete. Bundle structures are always accepted; inline structures are only accepted when product_count=0.
forcebooleanoptional
If true, deletes even if products are still assigned (they will be orphaned — use only after migrating products). Requires orphan_products_acknowledged=true alongside.
orphan_products_acknowledgedbooleanoptional
Explicit acknowledgment that force=true will orphan products. Required when force=true and any structure has product_count > 0. Defaults to false.
| Name | Type | Required | Description |
|---|
| structure_ids | array | required | List of structure IDs to delete. Bundle structures are always accepted; inline structures are only accepted when product_count=0. |
| force | boolean | optional | If true, deletes even if products are still assigned (they will be orphaned — use only after migrating products). Requires orphan_products_acknowledged=true alongside. |
| orphan_products_acknowledged | boolean | optional | Explicit acknowledgment that force=true will orphan products. Required when force=true and any structure has product_count > 0. Defaults to false. |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/pricing_structure_delete" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"structure_ids": [],
"force": true,
"orphan_products_acknowledged": true
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.pricing_structure_delete({
"structure_ids": [],
"force": true,
"orphan_products_acknowledged": true
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->pricingStructureDelete([
'structure_ids' => [],
'force' => true,
'orphan_products_acknowledged' => true,
]);
Response
summaryobject
deletedinteger
refusedinteger
not_foundinteger
resultsarray
pricing_structure_list
write
List all pricing structures for a tenant with their kind (inline|bundle), product count, tracking type,.
Parameters
kindstringoptional
Filter by kind: "inline" for hidden 1:1 structures, "bundle" for shared structures, or omit for all.
include_tiersbooleanoptional
Include tier details for each structure. Defaults to false.
include_product_idsbooleanoptional
Include the list of product IDs assigned to each structure. Defaults to false.
| Name | Type | Required | Description |
|---|
| kind | string | optional | Filter by kind: "inline" for hidden 1:1 structures, "bundle" for shared structures, or omit for all. |
| include_tiers | boolean | optional | Include tier details for each structure. Defaults to false. |
| include_product_ids | boolean | optional | Include the list of product IDs assigned to each structure. Defaults to false. |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/pricing_structure_list" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"kind": "example",
"include_tiers": true,
"include_product_ids": true
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.pricing_structure_list({
"kind": "example",
"include_tiers": true,
"include_product_ids": true
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->pricingStructureList([
'kind' => 'example',
'include_tiers' => true,
'include_product_ids' => true,
]);
Response
tenantobject
summaryobject
totalinteger
bundle_countinteger
inline_countinteger
structuresarray
idinteger
kindstring
namestring
tracking_typestring
familystring
is_defaultboolean
product_countinteger
product_idsarray
tiersarray
pricing_structure_restore
write
Surgical restore tool.
Parameters
product_idintegerrequired
The product whose pricing structure and variations will be rebuilt.
tracking_typestringrequired
Tracking type for the new inline structure: simple, unit, weight, matrix, matrix_unit.
inventory_modestringoptional
Inventory mode override: "product" or "variation". If omitted, defaults are applied per tracking_type rules (weight→product, matrix→variation).
product_stock_quantitynumberoptional
When inventory_mode=product, the value to set on products.stock_quantity. Ignored otherwise.
tiersarrayrequired
Array of tiers. Each: {name (string, required), price (dollars, required), compare_at_price (dollars, nullable), cost_price (dollars, nullable), weight_grams (number, required for weight/matrix), mix_match_tags (array, nullable), stock_quantity (number, required), restore_variation_id (int, optional — re-uses an existing variation row).}
delete_unreferencedbooleanoptional
If true, hard-deletes variations not referenced in tiers. Default false (deactivates them).
| Name | Type | Required | Description |
|---|
| product_id | integer | required | The product whose pricing structure and variations will be rebuilt. |
| tracking_type | string | required | Tracking type for the new inline structure: simple, unit, weight, matrix, matrix_unit. |
| inventory_mode | string | optional | Inventory mode override: "product" or "variation". If omitted, defaults are applied per tracking_type rules (weight→product, matrix→variation). |
| product_stock_quantity | number | optional | When inventory_mode=product, the value to set on products.stock_quantity. Ignored otherwise. |
| tiers | array | required | Array of tiers. Each: {name (string, required), price (dollars, required), compare_at_price (dollars, nullable), cost_price (dollars, nullable), weight_grams (number, required for weight/matrix), mix_match_tags (array, nullable), stock_quantity (number, required), restore_variation_id (int, optional — re-uses an existing variation row).} |
| delete_unreferenced | boolean | optional | If true, hard-deletes variations not referenced in tiers. Default false (deactivates them). |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/pricing_structure_restore" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"product_id": 10,
"tracking_type": "example",
"inventory_mode": "example"
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.pricing_structure_restore({
"product_id": 10,
"tracking_type": "example",
"inventory_mode": "example"
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->pricingStructureRestore([
'product_id' => 10,
'tracking_type' => 'example',
'inventory_mode' => 'example',
]);
pricing_structure_upsert
write
Create or edit a pricing structure's tiers, name, and tracking type.
Parameters
structure_idintegeroptional
ID of an existing BUNDLE structure to update. Must NOT be a hidden (inline) structure. Omit to create a new bundle or to edit inline via product_slug/product_id.
product_slugstringoptional
Product slug for inline (1:1) mode. Identifies which product's hidden structure to edit. Mutually exclusive with structure_id.
product_idintegeroptional
Product id for inline (1:1) mode. Alternative to product_slug. Mutually exclusive with structure_id.
namestringoptional
Structure name. Required when creating a bundle. Ignored for inline structures (name is derived from the product name).
tracking_typestringoptional
Pricing type: simple, weight, unit, matrix, or matrix_unit. Required when creating. For updates, changing tracking_type re-syncs all linked products.
tiersarrayoptional
Replacement tier list. Each tier: {name (string, required), weight_grams (number, required for weight/matrix), price (dollars, required), compare_at_price (dollars, nullable), cost_price (dollars, nullable), mix_match_tags (array of strings, nullable)}.
| Name | Type | Required | Description |
|---|
| structure_id | integer | optional | ID of an existing BUNDLE structure to update. Must NOT be a hidden (inline) structure. Omit to create a new bundle or to edit inline via product_slug/product_id. |
| product_slug | string | optional | Product slug for inline (1:1) mode. Identifies which product's hidden structure to edit. Mutually exclusive with structure_id. |
| product_id | integer | optional | Product id for inline (1:1) mode. Alternative to product_slug. Mutually exclusive with structure_id. |
| name | string | optional | Structure name. Required when creating a bundle. Ignored for inline structures (name is derived from the product name). |
| tracking_type | string | optional | Pricing type: simple, weight, unit, matrix, or matrix_unit. Required when creating. For updates, changing tracking_type re-syncs all linked products. |
| tiers | array | optional | Replacement tier list. Each tier: {name (string, required), weight_grams (number, required for weight/matrix), price (dollars, required), compare_at_price (dollars, nullable), cost_price (dollars, nullable), mix_match_tags (array of strings, nullable)}. |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/pricing_structure_upsert" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"structure_id": 10,
"product_slug": "example",
"product_id": 10
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.pricing_structure_upsert({
"structure_id": 10,
"product_slug": "example",
"product_id": 10
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->pricingStructureUpsert([
'structure_id' => 10,
'product_slug' => 'example',
'product_id' => 10,
]);
Response
modestring
structure_idinteger
namestring
tracking_typestring
tier_countinteger
products_resyncedinteger
warningstring
product_idinteger
product_namestring
messagestring
product_update_by_sku
write
Update a simple product's stock quantity and/or price by SKU — the inventory-sync path for an external POS.
Parameters
skustringrequired
Exact SKU of the product's variation. SKUs are unique per tenant.
stock_quantitynumberoptional
New absolute stock quantity (unit count, not grams). Omit to leave stock unchanged.
pricenumberoptional
New price in dollars (e.g. 24.99). Omit to leave price unchanged.
| Name | Type | Required | Description |
|---|
| sku | string | required | Exact SKU of the product's variation. SKUs are unique per tenant. |
| stock_quantity | number | optional | New absolute stock quantity (unit count, not grams). Omit to leave stock unchanged. |
| price | number | optional | New price in dollars (e.g. 24.99). Omit to leave price unchanged. |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/product_update_by_sku" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"sku": "example",
"stock_quantity": 10.5,
"price": 10.5
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.product_update_by_sku({
"sku": "example",
"stock_quantity": 10.5,
"price": 10.5
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->productUpdateBySku([
'sku' => 'example',
'stock_quantity' => 10.5,
'price' => 10.5,
]);
Response
product_idinteger
variation_idinteger
skustring
stock_quantitynumber
price_centsinteger
updated_fieldsarray
widget_manage
write
List, create, update, or delete a tenant's homepage marketing widgets (the hero slider cards.
Parameters
actionstringoptional
"list" (default), "create", "update", or "delete".
widget_idintegeroptional
ID of an existing widget. Required for update and delete.
titlestringoptional
Widget headline. Required when creating.
subtitlestringoptional
Widget sub-label shown under the headline.
cta_textstringoptional
Call-to-action button text (e.g. "Shop Now").
link_typestringoptional
"product", "category", "mix_match", or "featured". See LINK_TYPE in the tool description.
product_idintegeroptional
Target product id when link_type=product.
category_idintegeroptional
Target category id when link_type=category.
mix_match_tagstringoptional
Target mix & match tag when link_type=mix_match.
sort_orderintegeroptional
Display order (lower sorts first).
is_activebooleanoptional
Whether the widget is visible on the storefront.
media_idintegeroptional
Media library asset id to set as image_path (the branded, customer-facing image).
base_media_idintegeroptional
Media library asset id to set as base_image_path (the unbranded source canvas).
confirmbooleanoptional
Required (true) for action=delete.
| Name | Type | Required | Description |
|---|
| action | string | optional | "list" (default), "create", "update", or "delete". |
| widget_id | integer | optional | ID of an existing widget. Required for update and delete. |
| title | string | optional | Widget headline. Required when creating. |
| subtitle | string | optional | Widget sub-label shown under the headline. |
| cta_text | string | optional | Call-to-action button text (e.g. "Shop Now"). |
| link_type | string | optional | "product", "category", "mix_match", or "featured". See LINK_TYPE in the tool description. |
| product_id | integer | optional | Target product id when link_type=product. |
| category_id | integer | optional | Target category id when link_type=category. |
| mix_match_tag | string | optional | Target mix & match tag when link_type=mix_match. |
| sort_order | integer | optional | Display order (lower sorts first). |
| is_active | boolean | optional | Whether the widget is visible on the storefront. |
| media_id | integer | optional | Media library asset id to set as image_path (the branded, customer-facing image). |
| base_media_id | integer | optional | Media library asset id to set as base_image_path (the unbranded source canvas). |
| confirm | boolean | optional | Required (true) for action=delete. |
curl -X POST "https://your-store-slug.dabdash.com/api/v1/tools/widget_manage" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"action": "example",
"widget_id": 10,
"title": "example"
}'
import { DabDash } from '@shadow-software/dabdash-sdk';
const dabdash = new DabDash({ token: process.env.DABDASH_API_TOKEN });
const result = await dabdash.tools.widget_manage({
"action": "example",
"widget_id": 10,
"title": "example"
});
use ShadowSoftware\DabDash\DabDashClient;
$dabdash = new DabDashClient(token: $_ENV['DABDASH_API_TOKEN']);
$result = $dabdash->tools()->widgetManage([
'action' => 'example',
'widget_id' => 10,
'title' => 'example',
]);
Response
actionstring
tenantobject
totalinteger
widgetsarray
idinteger
titlestring
subtitlestring
cta_textstring
link_typestring
destination_urlstring
sort_orderinteger
is_activeboolean
image_urlstring
base_image_pathstring
widgetobject
idinteger
titlestring
subtitlestring
cta_textstring
link_typestring
destination_urlstring
sort_orderinteger
is_activeboolean
image_urlstring
base_image_pathstring
messagestring