API Reference

Read and manage your DabDash store programmatically — inventory, orders, customers, campaigns, pricing, and more. Every endpoint here maps 1:1 to what the SDKs call under the hood, so the examples below work with or without one.

JavaScript / TypeScript

npm i @shadow-software/dabdash-sdkComing soon to npm.

PHP

require shadow-software/dabdash-sdkComing soon to Packagist.

OpenAPI Spec

The full machine-readable spec behind this page — import it into any API client.

Download openapi/tenant.json →

Authentication

Every request needs an API token. Create one from your store's dashboard under Settings → AI Assistant, then send it as a bearer token. Read-only tokens can call read endpoints only; read & write tokens can call all of them.

Authorization: Bearer YOUR_API_TOKEN

Base URL

Every endpoint is a POST request to https://your-store-slug.dabdash.com/api/v1/tools/{tool} — your own store's subdomain or mapped custom domain. This API is never served from dabdash.com itself.

Errors

Every non-2xx response is JSON with an error code and a human-readable message. Codes are consistent across every tool — read this once instead of per endpoint.

401unauthenticated

Missing, invalid, or expired bearer token for this store.

402subscription_required

The store's subscription has lapsed with no active trial or grace period.

403forbidden

A read-only token was used to call a write tool.

404tool_not_found

The tool name in the URL doesn't match any available tool.

422validation_failed

A required parameter was missing or malformed — see the response's errors object for which field.

422tool_error

The request was well-formed, but the tool itself rejected it (e.g. a business rule, or a record that doesn't exist).

500internal_error

Something went wrong on our end. The message is always generic — check the request id if you contact support.

Endpoints

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)

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
    • fromstring
    • tostring
  • 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)

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
    • idinteger
    • namestring
    • emailstring
    • phonestring
    • default_address_idinteger
  • addressesarray
    • idinteger
    • labelstring
    • addressstring
    • latitudenumber
    • longitudenumber
    • saved_zoneobject
      • idinteger
      • namestring
    • detected_zoneobject
      • idinteger
      • namestring
    • zone_matches_saved_zoneboolean
    • is_defaultboolean

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

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)

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)

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".

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',
]);

Response

  • tenantobject
    • idinteger
    • slugstring
  • cutoffstring
  • not_found_product_idsarray
  • productsarray
    • product_idinteger
    • product_namestring
    • product_slugstring
    • current_stateobject
      • tracking_typestring
      • inventory_modestring
      • pricing_structure_idinteger
      • product_stock_quantitynumber
      • variationsarray
        • idinteger
        • namestring
        • is_activeboolean
        • stock_quantitynumber
        • price_centsinteger
        • weight_valuenumber
        • sort_orderinteger
    • audit_historyarray
      • variation_idinteger
      • last_quantity_after_before_cutoffnumber
      • last_actionstring
      • last_notesstring
      • last_reference_typestring
      • last_logged_atstring
      • variation_currently_existsboolean
      • variation_current_namestring
      • variation_current_stocknumber

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)

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).

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
    • last_synced_uidinteger
    • last_synced_atstring
    • minutes_since_last_syncinteger
    • last_sync_errorstring
    • last_sync_error_atstring
    • minutes_since_last_errorinteger
  • ingestionobject
    • inbound_countinteger
    • outbound_countinteger
    • total_countinteger
    • last_inbound_fetched_atstring
    • last_inbound_minutes_agointeger
  • 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)

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
    • matched_ordersinteger
    • total_revenue_centsinteger
    • total_revenuestring
  • 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.

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
    • idinteger
    • slugstring
  • mix_match_settingsobject
    • default_quantityinteger
    • default_discount_typestring
    • default_discount_valuenumber
    • rulesarray
  • productsarray
    • idinteger
    • namestring
    • slugstring
    • tracking_typestring
    • inventory_modestring
    • stock_quantitynumber
    • stock_statusstring
    • pricing_structurestring
    • variationsarray
      • idinteger
      • namestring
      • is_activeboolean
      • price_centsinteger
      • price_displaystring
      • compare_at_price_centsinteger
      • compare_at_price_displaystring
      • on_saleboolean
      • mix_match_tagsarray
      • weight_valuenumber
      • stock_quantitynumber

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)

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
    • idinteger
    • order_numberstring
    • statusstring
    • payment_statusstring
    • subtotalinteger
    • delivery_feeinteger
    • service_feeinteger
    • discount_amountinteger
    • coupon_codestring
    • coupon_typestring
    • coupon_discountinteger
    • mix_match_discountinteger
    • loyalty_points_redeemedinteger
    • loyalty_discountinteger
    • totalinteger
    • zonestring
    • itemsarray
      • productstring
      • variationstring
      • quantityinteger
      • unit_priceinteger
      • line_totalinteger
  • storewide_saleobject
    • activeboolean
    • typestring
    • amountnumber
  • loyaltyobject
    • enabledboolean
    • points_per_dollarnumber
    • redeem_points_per_dollarnumber
  • 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
    • idinteger
    • codestring
    • typestring
    • valuenumber
    • min_orderinteger
    • max_usesinteger
    • used_countinteger
    • max_uses_per_customerinteger
    • applies_tostring
    • applies_to_idsarray
    • starts_atstring
    • expires_atstring
    • is_activeboolean
  • 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)

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,
]);

Response

  • tenantobject
    • idinteger
    • slugstring
    • namestring
    • is_activeboolean
  • vendor_userobject
    • idinteger
    • namestring
    • emailstring
  • firebase_configobject
    • configuredboolean
    • credentials_sourcestring
    • project_idstring
    • statusstring
  • token_healthstring
  • notification_settingsobject
    • notify_new_order_pushboolean
    • notify_new_order_emailboolean
    • notify_low_stockboolean
    • notify_restock_requestboolean
    • notestring
  • recent_notificationsobject
    • lookback_hoursinteger
    • totalinteger
    • push_sent_countinteger
    • email_sent_countinteger
    • neither_sent_countinteger
    • push_rate_pctnumber
    • by_typeobject
    • entriesarray
      • idinteger
      • typestring
      • titlestring
      • push_sentboolean
      • email_sentboolean
      • is_readboolean
      • read_atstring
      • created_atstring
  • diagnosisobject
    • overall_statusstring
    • blockersarray
    • warningsarray
    • summarystring

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)

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();

Response

  • storeobject
    • idinteger
    • namestring
    • slugstring
    • timezonestring
    • currencystring
    • countrystring
    • on_trialboolean
    • has_active_subscriptionboolean

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)

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,
]);

Response

  • tenantobject
    • idinteger
    • slugstring
    • namestring
  • sourcestring
  • address_coordinatesobject
    • latitudenumber
    • longitudenumber
  • saved_zoneobject
    • idinteger
    • namestring
    • insideboolean
  • detected_zoneobject
    • idinteger
    • namestring
    • priorityinteger
  • zonesarray
    • idinteger
    • namestring
    • priorityinteger
    • delivery_feeinteger
    • service_feeinteger
    • min_orderinteger
    • colorstring
    • insideboolean
    • polygon_pointsinteger
    • polygonarray

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).

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,
]);

Response

  • tenantobject
    • idinteger
    • slugstring
  • summaryobject
    • totalinteger
    • activeinteger
    • zero_discountinteger
  • zero_discount_bundlesarray
  • bundlesarray
    • idinteger
    • namestring
    • slugstring
    • quantityinteger
    • discount_typestring
    • discount_valuenumber
    • discount_displaystring
    • is_activeboolean
    • is_exampleboolean
    • starts_atstring
    • ends_atstring
    • variation_countinteger
    • variation_idsarray

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".

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,
]);

Response

  • actionstring
  • bundle_idinteger
  • namestring
  • quantityinteger
  • discount_typestring
  • discount_valuenumber
  • discount_value_unitstring
  • is_activeboolean
  • starts_atstring
  • ends_atstring
  • variation_countinteger
  • messagestring

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.

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',
]);

Response

  • errorstring
  • available_templatesarray
    • idstring
    • namestring
    • descriptionstring
  • actionstring
  • campaign_idinteger
  • template_idstring
  • html_body_lengthinteger
  • has_unsubscribe_tokenboolean
  • messagestring

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.

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.

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).

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.

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,
]);

Response

  • actionstring
  • campaign_idinteger
  • media_idinteger
  • image_urlstring
  • filled_placeholderboolean
  • appendedboolean
  • image_in_bodyboolean
  • messagestring

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.

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',
]);

Response

  • actionstring
  • campaign_idinteger
  • namestring
  • channelstring
  • subjectstring
  • modestring
  • statusstring
  • audience_includes_customersboolean
  • messagestring
  • sms_body_lengthinteger
  • html_body_lengthinteger
  • has_unsubscribe_tokenboolean

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.

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,
]);

Response

  • dry_runboolean
  • base_namestring
  • survivor_product_idinteger
  • survivor_slugstring
  • products_removedinteger
  • total_gramsnumber
  • cost_per_gram_centsinteger
  • tiersarray
    • labelstring
    • weight_gramsnumber
    • price_centsinteger
  • absorbedarray
    • product_idinteger
    • namestring
  • notesarray
  • tenant_slugstring
  • next_stepstring

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.

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
    • idinteger
    • slugstring
  • 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.

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
    • idinteger
    • namestring
    • emailstring
    • phonestring
    • email_opt_outboolean
    • sms_marketing_opt_outboolean
    • sms_notifications_mutedboolean
    • updated_atstring
  • 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).

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.

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
    • idinteger
    • slugstring
  • 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).

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).

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
    • identifierinteger
    • product_idinteger
    • product_namestring
    • statusstring
    • reasonstring
    • orphaned_structure_deletedinteger

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.

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
    • idinteger
    • namestring
    • statusstring
    • reasonstring
    • product_countinteger
    • product_count_at_deletioninteger

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.

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
    • idinteger
    • slugstring
  • summaryobject
    • totalinteger
    • bundle_countinteger
    • inline_countinteger
  • structuresarray
    • idinteger
    • kindstring
    • namestring
    • tracking_typestring
    • familystring
    • is_defaultboolean
    • product_countinteger
    • product_idsarray
    • tiersarray
      • idinteger
      • namestring
      • weight_gramsnumber
      • price_centsinteger
      • price_displaystring
      • compare_at_price_centsinteger
      • compare_at_price_displaystring
      • cost_price_centsinteger
      • mix_match_tagsarray
      • sort_orderinteger

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).

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',
]);

Response

  • product_idinteger
  • product_namestring
  • new_structure_idinteger
  • tracking_typestring
  • inventory_modestring
  • tiersarray
    • tier_namestring
    • variation_idinteger
    • actionstring
    • stock_quantitynumber
  • unreferenced_variationsarray
    • variation_idinteger
    • namestring
    • stock_quantitynumber
  • unreferenced_actionstring

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)}.

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.

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.

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
    • idinteger
    • slugstring
  • 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
API Reference — DabDash Developer Docs Saltar al contenido principal