Skip to main content Skip to main navigation Skip to footer

API Reference

Connect Your Website to DotSquare

The DotSquare API is a PHP only service at this point in time. JSON is returned by all API responses, including errors.


Your API version is directly linked to the version of DotSquare that you are running so be mindful of this when upgrading dotSquare. You will need to FTP and initialize the DotSquare API on your web server each time you update to ensure everything functions properly.

API Library

The official dotSquare library is only available in PHP (version 5.6 or higher).

API EndPoint

https://cms.fiveonedevelopment.com/dotsquare/{API-VERSION}/api/

Authentication

Connect your account by including your DotSquare API key in API requests. You can find your DotSquare API key inside DotSquare. Then visit "Developers" → "Account". When connecting to DotSquare, your API key will also be set.

Example Request

\DotSquare\Initialize::connect({API-KEY});

Setting a New API Key

If you have multiple partitions, each partition has it's own API key. Be sure to use the key that correlates to desired partition. You can reset the API Key for the partition you need by simply calling setApiKey().

Example Request

\DotSquare\DotSquare::setApiKey('ds_HerEub8YjMvGOQmdGf0z');
// New key will now be used for all following requests

The Response Object

All DotSquare API responses output JSON objects.


Attributes

success
boolean
Has the value true if the the call returned no errors.
message
string
Returns a front end friendly message.
http_code
integer
Returns the HTTP code of the the response.
data
list
This is the heart of the response. All relevant data will be listed here. This list will be empty if an error is found.
error
list
The error data, if any.
  → type
    string
The error type. All possible error types are listed in the "Errors" section.
  → debug
    string
Outputs a string with more details on the error for development purposes.
Example Request

\DotSquare\Geo::getUSZipData([
  'us_zip'=>'92101'
]);
Example Response

DotSquare\Geo JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'city': 'San Diego',
    'state': 'US-CA',
    'lat': 32.726967,
    'lng': -117.164709
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Errors

DotSquare uses conventional HTTP response codes to indicates the status of an API request result.


Codes in the 500+ are indicative of a dotSquare error.

HTTP Status Codes

200 - OK
Everything worked as expected.
400 - Bad Request
The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized
No valid API key provided.
402 - Request Failed
The parameters were valid but the request failed.
404 - Not Found
Not Found The requested resource doesn't exist.
409 - Conflict
The request conflicts with another request (perhaps due to using the same idempotent key)
429 - Too Many Requests
Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server Errors
Something went wrong on DotSquare's end.
DotSquare Error Types
api_connection_error
Failure to connect to DotSquare's API.
api_error
API errors cover any other type of problem (e.g., a temporary problem with DotSquare's servers).
authentication_error
Failure to properly authenticate in the request.
idempotency_error
Idempotency errors occur when an Idempotency-Key is re-used on a request that does not match the first request's API endpoint and parameters.
invalid_request_error
Invalid request errors arise when your request has invalid parameters.
rate_limit_error
Too many requests ran through the DotSquare API too quickly.

Handing Errors

DotSquare API returns an array of information including elemnt containing success or failure or the call. You can test the "success" key for a true value to determine the status of the result.


If an error is thrown, you can display further error details inside the "error" array.

Example Request

$response = \DotSquare\Geo::getUSZipData([
	'us_zip'=>'92101'
]);
Example Response - Error Handing

if($response->success){
	// Do Something ...
} else {
	$type = $response->error->type;
	$debug = $response->error->debug;
}

Initialize

The first connection to DotSquare

This is the first thing that must be done when setting up a dotSquare website if not using our Framework. The DotSquare Framework natively handles this operation in the init.php file.


Arguments

key
Required
The API key provided by DotSquare

Data Attributes

database
list
Database connection credentials (host, user, pass, client_db, db_token).
account
list
Account details including ecommerce status and tier level.
paths
list
System paths (ds_path, base_url, upload paths, API base URLs).
UTC_timestamp
int
The current UTC timestamp.
UTC_offset
int
The UTC offset for the account time zone.
webspace
string
The webspace identifier.
ds_version
string
The current DotSquare version.
partition_id
int
The active partition ID.
salt
string
Security salt for the account.
time_zone
string
The account time zone (e.g. America/Los_Angeles).
live_mode
boolean
Whether the account is in live mode.
Example Request

\DotSquare\Initialize::connect({API-KEY});
Example Response

DotSquare\Initialize JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'database': {
      'host': 'fiveonedevelopment.com',
      'user': 'myUsername',
      'pass': 'myPassword',
      'client_db': 'my_db_name',
      'client_db_ecomm': 'my_db_name_ecomm',
      'db_connection_id': 2,
      'db_token': 'db_XXXXXXXXXXXXXX',
    },
    'account': {
      'ecommerce': true,
      'tier': 'multi_partition',
    },
    'paths': {
      'ds_path': 'dotsquare/6.64.0/',
      'base_url': '/',
      'upload_root_path': 'https://cms.fiveonedevelopment.com/',
      'upload_base_url': 'https://cms.fiveonedevelopment.com/',
      'ds_root_path': 'https://cms.fiveonedevelopment.com/',
      'ds_base_url': 'https://cms.fiveonedevelopment.com/',
      'gs_base_url': 'https://api.go-spotter.com/'
    },
    'UTC_timestamp': 1775772856,
    'UTC_offset': -8,
    'webspace': 'demoWebspace',
    'ds_version': '6.64.0',
    'cache_token': 'F5TRDKXwvO2MthyzpQ6r',
    'partition_id': 1,
    'custom_id': 1,
    'salt': 'SsWPMPcWkw4BoWXh6AOe',
    'cookie_prefix': 'demowebspace-XXXXX',
    'time_zone': 'America/Los_Angeles',
    'live_mode': true
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Analytics

Track Views and Admin Activity

Use this API class to log page views and retrieve admin login history.

Admin Login History

Retrieves login and logout history for one or more admin users. The admins parameter accepts an associative array of admin IDs grouped under custom keys that you define. The custom keys are not used to query data — they are simply passed through to organize the response. The database lookup is performed using only the admin IDs. Results are then returned under the same custom keys you provided, making it easy to group login history by partition, batch, department, or any other label meaningful to your application.


Arguments

admins
Required
An associative array where each key is a custom label used to group results in the response, and each value is an array of admin user IDs to look up. The keys are pass-through — only the admin IDs are queried.
Ex. array('partition_5'=>array('1','4','9'), 'partition_12'=>array('44','105'))

Data Attributes

history
list
Login/logout records grouped by the custom key provided.
  → admin_id
    int
The admin user ID.
  → login_datetime
    datetime
The login timestamp.
  → logout_datetime
    datetime
The logout timestamp.
  → last_visit_datetime
    datetime
The last activity timestamp during the session.
last_occurrence
list
The most recent login record per custom key.
  → admin_id
    int
The admin user ID.
  → login_datetime
    datetime
The login timestamp.
  → logout_datetime
    datetime
The logout timestamp.
  → last_visit_datetime
    datetime
The last activity timestamp during the session.
Example Request

\DotSquare\Analytics::getAdminLoginHistory([
  'admins' => [
    '2' => ['1', '4', '9'],
    '12' => ['44', '105']
  ]
]);
Example Response

DotSquare\Analytics JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'history': {
      '2': {'admin_id': 9, 'login_datetime': '2025-12-02 10:00:00', 'logout_datetime': null, 'last_visit_datetime': '2025-12-02 11:30:00'},
      '12': {'admin_id': 105, 'login_datetime': '2025-12-03 11:20:00', 'logout_datetime': '2025-12-03 18:00:00', 'last_visit_datetime': '2025-12-03 17:55:00'},
    },
    'last_occurrence': {
      '2': {'admin_id': 9, 'login_datetime': '2025-12-02 10:00:00', 'logout_datetime': null, 'last_visit_datetime': '2025-12-02 11:30:00'},
      '12': {'admin_id': 105, 'login_datetime': '2025-12-03 11:20:00', 'logout_datetime': '2025-12-03 18:00:00', 'last_visit_datetime': '2025-12-03 17:55:00'},
    },
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

New Page View

Logs a new page view with visitor tracking, traffic source detection, device type, geolocation data, and bot/spam detection. Also tracks daily active users.


Arguments

partition_id
Required
The partition ID for the view.
pseg_id
Required
The page segment ID.
user_id
optional
The logged-in user ID, if applicable.
page_id
Required
The page ID being viewed.
page_title
Required
The title of the page being viewed.
http_user_agent
Required
The visitor's user agent string.
ipv4
Required
The visitor's IPv4 address.
lat
optional
Latitude of the visitor.
lng
optional
Longitude of the visitor.
http_referer
optional
The HTTP referer URL.
visitor_key
optional
A unique visitor key for session tracking.
Example Request

\DotSquare\Analytics::newView([
  'partition_id' => 1,
  'pseg_id' => 1,
  'page_id' => 5,
  'page_title' => 'Home',
  'http_user_agent' => $_SERVER['HTTP_USER_AGENT'],
  'ipv4' => $_SERVER['REMOTE_ADDR'],
  'visitor_key' => 'abc123'
]);
Example Response

DotSquare\Analytics JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {},
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Data

Request Social Media, Custom Fields, and more

Use this API class to easily retrieve curated data from our servers.

Social Data

Returns data about a social website or app. This is useful when formatting icons and querying our database for listed social websites. For more information about social media data visit the Resource Guide


Arguments

social_id
optional
The dotSquare ID of the social media network or website. The social_id can be found by querying the database.

Data Attributes

site_name
string
The name of the website or app.
domain
string
The domain of the social website.
icon_name
string
The vector icon code name (svg file). All icons have a naming pattern of {STYLE-ID}{ICON-NAME}1.svg.
Ex. 4fb1.svg.

The "Style ID" determines the look such as a circle around the logo or a solid square.
category
string
The category of the social website or app.
Example Request

\DotSquare\Data::getSocialData([
  'social_id' => 1
]);
Example Response

DotSquare\Data JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
      1: {
        'site_name': 'Facebook',
        'domain': 'Facebook.com',
        'icon_name': 'fb',
        'category': 'social_media',
      }
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Custom Fields

DotSquare allows custom fields objects such as Staff, FAQS, etc. This is useful if you need very specific information about an object to be stored. For more information about custom fields visit the Resource Guide

Returns data about all fields used in your website.


Data Attributes

num_fields
int
Number of fields found
fields
list
List of all data
  → type_title
    string
A user friendly short decription of what this field is.
  → type
    string
The field type.
Ex. int, varchar, decimal, text, binary, datetime.
  → max_length
    int
The maximum characters the field can reach.
  → max_value
    int
The maximum amount that the field can reach.
  → multilingual
    string
Indicates if the field supports multilingual content.
Example Request

\DotSquare\Data::getFieldsData([]);
Example Response

DotSquare\Data JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'num_fields': 3,
    'fields': {
      0: {
        'type_title': 'Short Text',
        'type': 'varchar',
        'max_length': null,
        'max_value': null,
        'multilingual': 'no',
      }
      1: /* DotSquare Data */,
      2: /* DotSquare Data */
    },
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Edit Mode

In addition to editing website text directly through the dashboard app, in certain cases, DotSquare also allows admins to change app text (displayed on the website) in edit mode. This can make it more intuitive for admins to edit their website. This is natively included in the DotSquare Framework so no extra coding is required unless you wish to create custom features.

An example is if staff is listed with descriptions and titles. With this API, the bio and title for each staff member can be changed in edit mode.

Learn more about DotSqaure's Page Editor App


Arguments

col_id
Required
The ID of the edit mode reference. A full list of IDs can be found in the Reference Guide

Data Attributes

table_name
string
The name of the table dotSquare pulls from
row_target_name
string
The column name that is used to search the instance of the value specified. Think of this as the x-axis. Usually id.
col_target_name
string
The column name that is used for this data type. Think of this as the y-axis.
plain_text
boolean
Details whether or not the value returned is HTML or Plain Text.
max_length
int
If the field has a max length, specifies the number of characters.
Example Request

\DotSquare\Data::getEditModeData([
  'col_id' => 1
]);
Example Response

DotSquare\Data JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'table_name': 'cms_staff',
    'row_target_name': 'id',
    'col_target_name': 'title',
    'plain_text': false,
    'max_length': null,
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Fonts

Retrieves detailed font data from the Google Fonts library. Returns font family info, variants, file URLs, and supported subsets.


Arguments

font_family
Required
The font family name to look up.

Data Attributes

id
int
The font ID.
font_family
string
The font family name.
is_google_font
boolean
Whether the font is a Google Font.
category
string
The font category (e.g. serif, sans-serif).
variants
list
Available font weight/style variants.
font_files
list
URLs to font files for each variant.
subsets
list
Supported character subsets (e.g. latin, cyrillic).
Example Request

\DotSquare\Data::getFontsData([
  'font_family' => 'Roboto'
]);
Example Response

DotSquare\Data JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'id': 42,
    'font_family': 'Roboto',
    'is_google_font': true,
    'category': 'sans-serif',
    'variants': ['100', '300', 'regular', '500', '700', '900'],
    'font_files': {
      'regular': 'https://fonts.gstatic.com/s/roboto/v30/...',
    },
    'subsets': ['latin', 'latin-ext', 'cyrillic'],
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Integrations

Retrieves integration configurations including connection keys and settings. Returns all active integrations or a specific one by key.


Arguments

integration_key
optional
A specific integration identifier. If omitted, returns all active integrations.

Data Attributes

key
string
The integration identifier key.
name
string
The display name of the integration.
category
string
The integration category.
description
string
A description of the integration.
connection_type
string
The type of connection (e.g. api_key, oauth).
connection_keys
list
The connection credentials/keys for this integration.
Example Request

\DotSquare\Data::getIntegrationsData([
  'integration_key' => 'google_analytics'
]);
Example Response

DotSquare\Data JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'key': 'google_analytics',
    'name': 'Google Analytics',
    'category': 'analytics',
    'description': 'Track website traffic and user behavior.',
    'connection_type': 'api_key',
    'connection_keys': {
      // Integration-specific keys
    },
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Site Themes

Retrieves site template theme configurations including styles, CSS values, and associated Google Fonts. Returns all active themes or a specific one by ID.


Arguments

theme_id
optional
A specific theme ID. If omitted, returns all active themes for the partition type.

Data Attributes

theme_ider
string
The theme identifier string.
google_fonts
list
Google Fonts associated with this theme.
style
list
Theme style data.
  → values
    list
Style variable values.
  → css
    string
Compiled CSS output.
  → css_usage
    string
CSS usage instructions.
Example Request

\DotSquare\Data::getSiteThemesData([
  'theme_id' => 1
]);
Example Response

DotSquare\Data JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    1: {
      'theme_ider': 'modern_dark',
      'google_fonts': ['Roboto', 'Open Sans'],
      'style': {
        'values': { /* style variables */ },
        'css': '/* compiled CSS */',
        'css_usage': '/* usage notes */',
      },
    },
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Organization

Request Information Relevant to the Organization

Use this API class to easily retrieve information about an organizations service areas.

Service Areas

DotSquare allows you to store where a business or organization does business. This is useful in delivery businesses, organizations that have exclusive operations within a geography and more.

You can retrieve all service areas or retrieve a selected service area.


Arguments

location_id
optional
Request data only from a certain location id.
category_id
optional
Request data only from a certain category id.
select_by
optional
Specify if you wish to find a specific service area
Ex. coordinates, zip_code, city, county, state
select_arguments
optional assoc. array
The arguments to enter if select_by is specified.
  → lat
    required [1]
Specify the latitude to find results around coordinates. Must be used with the lng argument.
  → lng
    required [1]
Specify the longitude to find results around coordinates. Must be used with the lat argument.
  → distance
    optional
Specify the distance in miles around coordinates. Can only be used with the lat and lng arguments. Defaults to 100 miles if no argument is specified.
  → zip_code
    required [2]
The zip code to search for.
  → city
    required [3]
The city name to search for. May return multiple cities if there are multiple cities with the same name. Specify the state to return a unique city.
  → county
    required [4]
The county name to search for. May return multiple counties if there are multiple counties with the same name. Specify the state to return a unique county.
  → state
    optional
The full state name to search for (ex. California). If used in conjunction with city or county, this attribute will be used for filtering the city and county.
order_by
optional
All values are ordered Ascending. Order by distance can only be used with the select_by: coordinates argument.
Ex. distance, zip_code, city, county, state, random.
limit
optional
The maximum number of results returned. Default is 100.

Data Attributes

num_rows
int
Number of results found
rows
list
List of all data
  → zip_code
    string
The 5 digit US zip code
  → city
    string
Full city name
  → county
    string
Full county name
  → state
    string
Full US state name
  → distance
    decimal
Distance away from coordinates specified in miles. Maximum distance returned is 100 miles.
  → lat
    decimal
Latitude of the service area zip code.
  → lng
    decimal
Longitude of the service area zip code.
Example Request

\DotSquare\Org::getServiceAreas([
  'select_by' => 'coordinates',
  'select_arguments' => [
    'lat'=>32.7211000000,
    'lng'=>-117.1743660000
  ],
  'order_by'=>'distance',
  'limit'=>40
]);
Example Response

DotSquare\Org JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'num_rows': 40,
    'rows': {
      0: {
        'zip_code': '92101',
        'city': 'San Diego',
        'county': 'San Diego',
        'state': 'California',
        'lat': 32.7211000000,
        'lng': -117.1743660000,
        'distance': 0.1,
      },
      1: /* DotSquare Data */,
      2: /* DotSquare Data */
    },
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Display

Generate Sitemaps and Display Data

Use this API class to generate sitemaps and retrieve display-related data.

Site Map

Generates both HTML and XML sitemaps for the current partition. Includes pages, posts, blog entries, gallery items, portfolio items, batches, tags, and service areas.


Data Attributes

html
string
The generated HTML sitemap content.
xml
string
The generated XML sitemap content.
Example Request

\DotSquare\Display::getSiteMap([]);
Example Response

DotSquare\Display JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'html': '',
    'xml': '...',
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Files

Upload, Move, and Delete Files

Use this API class to manage file uploads, deletions, and file operations on the CMS.

Delete File

Deletes a file from the upload directory.


Arguments

file_path
Required
The file path relative to the uploads root directory.
Example Request

\DotSquare\Files::deleteFile([
  'file_path' => 'images/old_photo.jpg'
]);
Example Response

DotSquare\Files JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {},
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Move File

Moves or renames a file within the upload directory.


Arguments

from_file_path
Required
The current file path relative to the uploads root.
to_file_path
Required
The new file path relative to the uploads root.
Example Request

\DotSquare\Files::moveFile([
  'from_file_path' => 'images/photo.jpg',
  'to_file_path' => 'images/archive/photo.jpg'
]);
Example Response

DotSquare\Files JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {},
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Upload File

Uploads a document file to the CMS. Supports images, PDFs, Office documents, CSV, and text files.


Arguments

directory
Required
The target upload directory path.
size_limit
optional
Maximum file size in MB. Default is 5.

Data Attributes

file_name
string
The name of the uploaded file.
file_category
string
The category of the file (e.g. image, document).
file_type
string
The file extension/type.
Example Request

\DotSquare\Files::uploadDocument([
  'directory' => 'documents/invoices',
  'size_limit' => 10
]);
Example Response

DotSquare\Files JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'file_name': 'invoice_2024.pdf',
    'file_category': 'document',
    'file_type': 'pdf',
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Upload Image

Uploads an image file and automatically creates resized versions (large, medium, small).


Arguments

directory
Required
The target upload directory path.
size_limit
optional
Maximum file size in MB. Default is 5.

Data Attributes

file_name
string
The name of the uploaded image file.
H2W_ratio
decimal
The height-to-width ratio of the uploaded image.
Example Request

\DotSquare\Files::uploadImage([
  'directory' => 'images/products',
  'size_limit' => 5
]);
Example Response

DotSquare\Files JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'file_name': 'product_photo.jpg',
    'H2W_ratio': 0.75,
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Geo

Geographic and Location Data

Use this API class to retrieve geographic data such as IP geolocation, US zip code info, sales tax rates, and time zones.

Get IP Data

Retrieves geolocation data for an IP address using the ipstack API. Includes bot and spam detection.


Arguments

ip
Required
The IP address to look up.
access_key
Required
Your ipstack API access key.
http_user_agent
optional
The user agent string for bot detection.
http_referer
optional
The HTTP referer for spam detection.

Data Attributes

city
string
The city name.
region_name
string
The region or state name.
country_name
string
The country name.
zip
string
The postal/zip code.
latitude
decimal
Latitude of the IP location.
longitude
decimal
Longitude of the IP location.
Example Request

\DotSquare\Geo::getIpData([
  'ip' => '134.201.250.155',
  'access_key' => 'YOUR_IPSTACK_KEY'
]);
Example Response

DotSquare\Geo JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'city': 'Los Angeles',
    'region_name': 'California',
    'country_name': 'United States',
    'zip': '90012',
    'latitude': 34.0655,
    'longitude': -118.2405,
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Get US Sales Tax

Retrieves the sales tax rate for a given US zip code.


Arguments

us_zip
Required
A 5-digit US zip code.

Data Attributes

sales_tax_rate
decimal
The sales tax rate for the given zip code.
Example Request

\DotSquare\Geo::getUSSalesTax([
  'us_zip' => '92101'
]);
Example Response

DotSquare\Geo JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'sales_tax_rate': 0.0775,
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Get US Time Zone

Retrieves the UTC offset for a given US zip code.


Arguments

us_zip
Required
A 5-digit US zip code.

Data Attributes

utc_offset
int
The UTC offset for the given zip code.
Example Request

\DotSquare\Geo::getUSTimeZone([
  'us_zip' => '92101'
]);
Example Response

DotSquare\Geo JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'utc_offset': -8,
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Get US Zip Data

Retrieves city, county, state, and coordinates for a given US zip code.


Arguments

us_zip
Required
A 5-digit US zip code.

Data Attributes

city
string
The city name.
county
string
The county name.
state
string
The full state name.
lat
decimal
Latitude of the zip code.
lng
decimal
Longitude of the zip code.
Example Request

\DotSquare\Geo::getUSZipData([
  'us_zip' => '92101'
]);
Example Response

DotSquare\Geo JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'city': 'San Diego',
    'county': 'San Diego',
    'state': 'California',
    'lat': 32.726967,
    'lng': -117.164709,
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Notifications

Send Emails, SMS, and Check Spam

Use this API class to send emails, bulk emails, SMS messages, and evaluate submissions for spam.

Get Spam Filter

Evaluates a submission for spam by analyzing the submitter's email, phone, comments, and visitor key. Returns a spam index score.


Arguments

submitters_email
optional
The email address to evaluate for spam.
submitters_phone
optional
The phone number to evaluate.
comments
optional
An array of comment strings to check for spam keywords.
visitor_key
optional
A session/cookie visitor key. An empty or null value increases the spam score.

Data Attributes

spam_index
int
The calculated spam score. Higher values indicate a higher likelihood of spam.
Example Request

\DotSquare\Notifications::getSpamFilter([
  'submitters_email' => 'user@example.com',
  'comments' => ['Great service!'],
  'visitor_key' => 'abc123'
]);
Example Response

DotSquare\Notifications JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'spam_index': 2,
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Send Bulk Emails

Sends personalized emails to multiple recipients via Mailgun. Each recipient can have unique template variable replacements.


Arguments

subject
Required
The email subject line.
body
Required
The email body content (HTML).
recipients_w_variables_arr
Required
An associative array of recipient_email => variables_array for per-recipient personalization.
from_name
optional
The sender display name. Default is "dotSquare".
reply_to
optional
The reply-to email address.
Example Request

\DotSquare\Notifications::sendBulkEmails([
  'subject' => 'Monthly Newsletter',
  'body' => '
Hello [[name]]!
',
  'recipients_w_variables_arr' => [
    'john@example.com' => ['name' => 'John'],
    'jane@example.com' => ['name' => 'Jane'],
  ]
]);
Example Response

DotSquare\Notifications JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {},
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Send Email

Sends an email to one or more recipients. Supports custom templates, attachments, and template variable replacements.


Arguments

subject
Required
The email subject line.
body
Required
The email body content (HTML).
recipients
Required
An array of recipient email addresses.
from_name
optional
The sender display name. Default is "dotSquare".
reply_to
optional
The reply-to email address.
attachments_by_url
optional
An array of attachment URLs.
custom_template_id
optional
A custom email template ID.
template_parameters
optional
Template variable replacements.
Example Request

\DotSquare\Notifications::sendEmail([
  'subject' => 'Welcome!',
  'body' => '
Welcome to our platform.
',
  'recipients' => ['user@example.com'],
  'from_name' => 'My Company'
]);
Example Response

DotSquare\Notifications JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {},
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Send SMS

Sends an SMS text message to one or more phone numbers via Clickatell.


Arguments

recipients
Required
An array of phone numbers to send the SMS to.
body
Required
The SMS body text. HTML <br> tags are converted to newlines.
Example Request

\DotSquare\Notifications::sendSMS([
  'recipients' => ['16195551234'],
  'body' => 'Your order has shipped!'
]);
Example Response

DotSquare\Notifications JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {},
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Users

Payment Methods and Subscriptions

Use this API class to manage user payment cards, bank accounts, and payment subscriptions.

Create Payment Subscription

Creates a new payment subscription for a billing contact. Provide a plan_id to use a pre-configured plan (trial period comes from the plan), or omit it and provide custom_plan_info to create a custom subscription with manual details.


Arguments

contact_id
Required
The billing contact ID.
plan_id
conditional
The subscription plan ID. Required if custom_plan_info is not provided.
discount_id
optional
A discount ID to apply to the subscription.
allow_bill_immediately
optional
Allow the first invoice to be created immediately. Default is 1. Ignored during a trial period.
details
optional
General subscription settings.
  → auto_pay
    optional
Enable auto-pay. Default is 1.
  → pay_time
    optional
Payment timing: pre or post. Default is "post".
  → notify
    optional
Send notifications. Default is 1.
custom_plan_info
conditional
Custom subscription details. Required if plan_id is not provided.
  → title
    Required
Subscription title.
  → interval_count
    Required
Billing interval count (e.g. 1).
  → interval
    Required
Billing interval: day, week, month, or year.
  → items
    Required
Array of subscription line items (at least one). Each item: item_id (required), option_id, qty, price, tax_id, notes.
  → comment
    optional
Subscription comment/description.
  → payment_instructions
    optional
Payment instructions included on invoices.
  → initial_fee
    optional
Initial/setup fee. Default is 0.00.
  → trial_days
    optional
Number of trial days. Billing will not begin until the trial ends.

Data Attributes

subscription_id
int
The newly created subscription ID.
subscription_GUID
string
The subscription token (GUID).
subscription_schedule_id
int
The ID of the next scheduled billing entry.
first_invoice
array
The first invoice data, if one was created immediately. Empty array during a trial.
Example Request

// Plan-based subscription (trial comes from the plan)
\DotSquare\Users::createPaymentSubscription([
  'contact_id' => 42,
  'plan_id' => 3,
  'details' => [
    'auto_pay' => 1,
    'pay_time' => 'pre',
    'notify' => 1
  ]
]);

// Custom subscription (no plan)
\DotSquare\Users::createPaymentSubscription([
  'contact_id' => 42,
  'details' => [
    'auto_pay' => 1,
    'notify' => 1
  ],
  'custom_plan_info' => [
    'title' => 'Monthly Retainer',
    'comment' => 'Ongoing consulting services',
    'interval_count' => 1,
    'interval' => 'month',
    'initial_fee' => '50.00',
    'trial_days' => 7,
    'items' => [
      ['item_id' => 10, 'qty' => 1, 'price' => '200.00'],
      ['item_id' => 15, 'qty' => 2]
    ]
  ]
]);
Example Response

DotSquare\Users JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'subscription_id': 78,
    'subscription_GUID': 'sub_a1b2c3d4e5f67890abcd',
    'subscription_schedule_id': 12,
    'first_invoice': [],
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Cancel Payment Subscription

Cancels an active subscription. The subscription will remain active until the end of the current billing period, after which it will stop. The subscription can be restarted before it ends.


Arguments

subscription_GUID
Required
The subscription token (GUID).

Data Attributes

subscription_id
int
The subscription ID.
subscription_GUID
string
The subscription token (GUID).
Example Request

\DotSquare\Users::cancelPaymentSubscription([
  'subscription_GUID' => 'sub_a1b2c3d4e5f67890abcd'
]);
Example Response

DotSquare\Users JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'subscription_id': 78,
    'subscription_GUID': 'sub_a1b2c3d4e5f67890abcd',
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Restart Payment Subscription

Restarts a canceled subscription. If the subscription has not yet ended, the cancellation is reversed and no invoice is created. If the subscription has already ended, a new subscription is created as a copy of the original and an invoice/order is generated immediately (based on auto-pay settings).


Arguments

subscription_GUID
Required
The subscription token (GUID) of the canceled subscription.
allow_bill_immediately
optional
Allow the first invoice to be created immediately when restarting an ended subscription. Default is 1. Set to 0 to skip immediate billing and let cron handle it. Has no effect when the subscription has not yet ended.

Data Attributes

subscription_id
int
The subscription ID. May be a new ID if the original had already ended.
subscription_GUID
string
The subscription token (GUID). May be a new token if the original had already ended.
subscription_plan_id
int
The subscription plan ID if the subscription has a plan.
first_invoice
object
The invoice/order created on restart of an ended subscription. Only present when allow_bill_immediately is enabled and the subscription had already ended.
Example Request

\DotSquare\Users::restartPaymentSubscription([
  'subscription_GUID' => 'sub_a1b2c3d4e5f67890abcd',
  'allow_bill_immediately' => 1
]);
Example Response

DotSquare\Users JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'subscription_id': 78,
    'subscription_GUID': 'sub_x9y8z7w6v5u43210mnop',
    'subscription_plan_id': 46,
    'first_invoice': { ... },
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Change Payment Subscription

Changes an active subscription from one plan to another. Upgrades (new plan price ≥ current) are applied immediately with proration. Downgrades (new plan price < current) are deferred — the current plan stays active until the next billing cycle, when it automatically swaps to the new plan. Cancel pending change — if the subscription has a pending plan change and you pass the current plan's ID as new_plan_id, the pending change is cancelled and the subscription stays on the current plan. Only plan-based subscriptions can be changed (not custom subscriptions).


Arguments

subscription_GUID
Required
The subscription token (GUID).
new_plan_id
Required
The ID of the plan to switch to.
allow_proration
optional
Calculate proration for upgrades. Default is 1. Set to 0 to skip proration entirely (no proration data returned, no invoice created). Has no effect on downgrades.
allow_bill_immediately
optional
Create a prorated invoice on upgrade. Default is 1. Set to 0 to skip invoice creation (the plan still changes, but no proration invoice is generated). When enabled, auto-pay is attempted if available; otherwise an AR invoice is created.
discount_id
optional
A discount ID to apply when calculating the new plan price. If omitted, the subscription's existing discount is used.

Data Attributes

subscription_id
int
The subscription ID.
subscription_GUID
string
The subscription token (GUID).
change_type
string
The type of change: upgrade (immediate), downgrade (deferred to next billing cycle), or cancel_pending (clears a pending plan change).
old_plan_id
int
The plan ID that was active before the change.
new_plan_id
int
The plan ID that is now active (upgrade) or pending (downgrade).
effective_date
string
When the change takes effect. For upgrades, this is the current datetime. For downgrades, this is the end of the current billing cycle.
proration
object
Proration details. Only present for upgrades when allow_proration is enabled.
  → credit
    float
Credit from the old plan for remaining days in the cycle.
  → charge
    float
Charge for the new plan for remaining days in the cycle.
  → net
    float
Net amount (charge minus credit). Positive means customer owes; negative means customer receives credit.
  → days_remaining
    float
Days remaining in the current billing cycle.
  → days_in_cycle
    float
Total days in the current billing cycle.
proration_invoice
object
The prorated invoice, if one was created. Only present for upgrades when allow_proration and allow_bill_immediately are both enabled and the net amount is non-zero.
  → invoice_id
    int
The prorated invoice ID.
Example Request

// Upgrade example
\DotSquare\Users::changePaymentSubscription([
  'subscription_GUID' => 'sub_a1b2c3d4e5f67890abcd',
  'new_plan_id' => 5,
]);

// Downgrade example (deferred to next billing cycle)
\DotSquare\Users::changePaymentSubscription([
  'subscription_GUID' => 'sub_a1b2c3d4e5f67890abcd',
  'new_plan_id' => 1,
]);

// Cancel a pending plan change (pass the current plan ID)
\DotSquare\Users::changePaymentSubscription([
  'subscription_GUID' => 'sub_a1b2c3d4e5f67890abcd',
  'new_plan_id' => 5, // the plan the subscription is already on
]);

// Upgrade with a new discount, no proration
\DotSquare\Users::changePaymentSubscription([
  'subscription_GUID' => 'sub_a1b2c3d4e5f67890abcd',
  'new_plan_id' => 5,
  'discount_id' => 12,
  'allow_proration' => 0,
]);
Example Response

// Upgrade response
DotSquare\Users JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'subscription_id': 78,
    'subscription_GUID': 'sub_a1b2c3d4e5f67890abcd',
    'change_type': 'upgrade',
    'old_plan_id': 1,
    'new_plan_id': 5,
    'effective_date': '2026-03-25 14:30:00',
    'proration': {
      'credit': 12.50,
      'charge': 25.00,
      'net': 12.50,
      'days_remaining': 15,
      'days_in_cycle': 30,
    },
    'proration_invoice': {
      'invoice_id': 234,
    },
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

// Downgrade response
DotSquare\Users JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'subscription_id': 78,
    'subscription_GUID': 'sub_a1b2c3d4e5f67890abcd',
    'change_type': 'downgrade',
    'old_plan_id': 5,
    'new_plan_id': 1,
    'effective_date': '2026-04-25 00:00:00',
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

// Cancel pending change response
DotSquare\Users JSON: {
  'success': true,
  'message': 'Pending plan change cancelled.',
  'http_code': 200,
  'data': {
    'subscription_id': 78,
    'subscription_GUID': 'sub_a1b2c3d4e5f67890abcd',
    'change_type': 'cancel_pending',
    'old_plan_id': 5,
    'new_plan_id': 5,
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Create Bank Account

Creates a bank account record for a user or user group. The account must be verified before it can be used for payments.


Arguments

user_id
optional
The user ID. Provide user_id or account_id.
account_id
optional
The user group account ID. Alternative to user_id.
data
Required
The bank account details.
  → holder_name
    Required
The account holder name.
  → holder_type
    Required
Account holder type (e.g. individual, company).
  → routing_number
    Required
The bank routing number.
  → account_number
    Required
The bank account number.
  → country
    optional
Country code. Default is US.
  → currency
    optional
Currency code. Default is usd.
  → make_default
    optional
Set as default bank account. Default is false.

Data Attributes

method_token
string
The payment method token for the new bank account.
Example Request

\DotSquare\Users::createUserBankAccount([
  'user_id' => 15,
  'data' => [
    'holder_name' => 'John Doe',
    'holder_type' => 'individual',
    'routing_number' => '110000000',
    'account_number' => '000123456789',
    'make_default' => true
  ]
]);
Example Response

DotSquare\Users JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'method_token': 'ba_9f8e7d6c5b4a3210',
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Create Card

Creates a payment card record for a user or user group using a payment gateway token.


Arguments

token
Required
The payment gateway token for the card.
user_id
optional
The user ID. Provide user_id or account_id.
account_id
optional
The user group account ID. Alternative to user_id.
make_default
optional
Set as the default card. Default is false.

Data Attributes

method_token
string
The payment method token for the new card.
Example Request

\DotSquare\Users::createUserCard([
  'token' => 'tok_XXXXXXXXXXXXXX',
  'user_id' => 15,
  'make_default' => true
]);
Example Response

DotSquare\Users JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'method_token': 'card_3a4b5c6d7e8f9012',
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Default Bank Account

Sets a bank account as the default payment method for the user.


Arguments

method_token
Required
The method token identifying the bank account to set as default.
Example Request

\DotSquare\Users::defaultUserBankAccount([
  'method_token' => 'ba_XXXXXXXXXXXXXX'
]);
Example Response

DotSquare\Users JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {},
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Default Card

Sets a card as the default payment method for the user.


Arguments

method_token
Required
The method token identifying the card to set as default.
Example Request

\DotSquare\Users::defaultUserCard([
  'method_token' => 'card_XXXXXXXXXXXXXX'
]);
Example Response

DotSquare\Users JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {},
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Ecommerce

Carts, Orders, Payments, and Subscriptions

Use this API class to manage shopping carts, create orders, process payments, and handle subscriptions.

Create Cart Invoice

Creates an invoice from a shopping cart. Handles item totals, tax calculations, and optional transaction processing.


Arguments

cart_token
Required
The cart token.
contact_id
Required
The billing contact ID.
loc_id
Required
The location ID for tax/fee calculations.
payment_gateway
optional
The payment gateway name. Default is stripe.
num_checkout_steps
optional
Number of checkout steps. Default is 1.
invoice
optional
Invoice details object.
  → title
    Required
Invoice title.
  → type_id
    Required
Invoice type ID.
  → fulfillment_method_id
    Required
Fulfillment method ID.
  → comment
    optional
Invoice comment.

Data Attributes

invoice_id
int
The newly created invoice ID.
invoice_key
string
The invoice GUID key.
Example Request

\DotSquare\Ecommerce::createCartInvoice([
  'cart_token' => 'cart_XXXXXXXXXXXXXX',
  'contact_id' => 42,
  'loc_id' => 1,
  'invoice' => [
    'title' => 'Order #1001',
    'type_id' => 1,
    'fulfillment_method_id' => 2,
    'comment' => 'Rush delivery'
  ]
]);
Example Response

DotSquare\Ecommerce JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'invoice_id': 1001,
    'invoice_key': 'inv_a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Create Order

Creates a full order from a shopping cart including invoice creation and payment processing. Supports guest checkout.


Arguments

cart_token
Required
The cart token.
payment_token
optional
The payment gateway token.
payment_approach
optional
Payment approach. Default is traditional.
partition_id
optional
Filter to a specific partition.
multi_order
optional
Multi-order flag.
meta_data
optional
Additional metadata array.
guest_info
optional
Guest checkout information.
  → email
    optional
Guest email address.
  → name_first
    optional
Guest first name.
  → name_last
    optional
Guest last name.
  → phone_mobile
    optional
Guest mobile phone.

Data Attributes

invoice_id
int
The created invoice ID.
transaction_id
int
The created transaction ID, if payment was processed.
Example Request

\DotSquare\Ecommerce::createOrder([
  'cart_token' => 'cart_XXXXXXXXXXXXXX',
  'payment_token' => 'tok_XXXXXXXXXXXXXX',
  'guest_info' => [
    'email' => 'guest@example.com',
    'name_first' => 'John',
    'name_last' => 'Doe'
  ]
]);
Example Response

DotSquare\Ecommerce JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'invoice_id': 1002,
    'transaction_id': 5501,
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Create Payment Token

Creates a temporary payment token for a card or bank account. Used to securely process payments without storing raw payment details.


Arguments

method_type
Required
Must be card or bank_account.
address
optional
Billing address object.
  → country
    optional
ISO 3166-1 country code.
  → street
    optional
Billing street address.
  → city
    optional
Billing city.
  → subdivision
    optional
State/subdivision (e.g. US-CA).
  → postal_code
    optional
Postal code.
card
conditional
Required if method_type is "card".
  → holder_name
    Required
Cardholder name.
  → number
    Required
Card number (15-16 digits).
  → exp_month
    Required
Expiration month (1-12).
  → exp_year
    Required
Expiration year (4 digits).
  → cvc
    Required
CVC code (3-4 digits).
bank_account
conditional
Required if method_type is "bank_account".
  → holder_name
    Required
Account holder name.
  → routing_number
    Required
Routing number (9 digits).
  → account_number
    Required
Account number.

Data Attributes

token
string
The temporary payment token.
Example Request

\DotSquare\Ecommerce::createPaymentToken([
  'method_type' => 'card',
  'card' => [
    'holder_name' => 'John Doe',
    'number' => '4242424242424242',
    'exp_month' => 12,
    'exp_year' => 2027,
    'cvc' => '123'
  ],
  'address' => [
    'postal_code' => '92101'
  ]
]);
Example Response

DotSquare\Ecommerce JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'token': 'tok_XXXXXXXXXXXXXX',
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Create Return

Processes a return for one or more order items. Optionally processes a refund.


Arguments

items
Required
Array of items to return.
  → invoice_item_row_id
    Required
The invoice item row ID.
  → fulfillment_row_id
    Required
The fulfillment row ID.
  → new_qty
    Required
The quantity to return.
requestor_is_seller
optional
Whether the requestor is the seller. Default is false.
process_refund
optional
Whether to process a refund. Default is true.

Data Attributes

return_row_ids
list
Array of created return row IDs.
return_amount
decimal
The total refund amount.
Example Request

\DotSquare\Ecommerce::createReturn([
  'items' => [
    [
      'invoice_item_row_id' => 101,
      'fulfillment_row_id' => 55,
      'new_qty' => 1
    ]
  ],
  'process_refund' => true
]);
Example Response

DotSquare\Ecommerce JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'return_row_ids': [201],
    'return_amount': 29.99,
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Create Subscription Invoice

Creates an invoice for a subscription billing cycle. Handles pending plan downgrades before invoicing.


Arguments

token
Required
The subscription token (GUID).

Data Attributes

invoice
object
The created invoice.
  → partition_id
    string
The partition ID of the invoice.
  → invoice_id
    int
The invoice ID.
  → invoice_token
    string
The invoice token (GUID).
  → invoice_number
    string
The formatted invoice number.
  → total
    float
The invoice total.
credit_transaction
object
Account credit applied toward the invoice, if any.
  → trans_id
    int
The credit transaction ID.
  → total
    float
The amount credited.
transaction
object
The auto-pay transaction, if auto-pay was successful.
  → trans_id
    int
The payment transaction ID.
  → total
    float
The amount charged.
Example Request

\DotSquare\Ecommerce::createSubscriptionInvoice([
  'token' => 'sub_XXXXXXXXXXXXXX'
]);
Example Response

DotSquare\Ecommerce JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'invoice': {
      'partition_id': '12',
      'invoice_id': 1015,
      'invoice_token': 'inv_f9e8d7c6b5a43210fedc',
      'invoice_number': 'INV-001015',
      'total': 49.99,
    },
    'credit_transaction': {
      'trans_id': 401,
      'total': 10.00,
    },
    'transaction': {
      'trans_id': 402,
      'total': 39.99,
    },
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Create Transaction

Creates a payment transaction record. Can be associated with invoices and includes notification options.


Arguments

contact_id
Required
The billing contact ID.
transaction_amount
optional
The transaction total. Default is 0.
invoice_id
optional
Associated invoice ID.
toward_invoice_ids
optional
Array of invoice IDs this transaction pays toward.
method_id
optional
Payment method ID.
transaction_number
optional
A custom transaction number.
notify_payer
optional
Whether to notify the payer. Default is false.
payer_name
optional
The payer's name.

Data Attributes

transaction_id
int
The newly created transaction ID.
Example Request

\DotSquare\Ecommerce::createTransaction([
  'contact_id' => 42,
  'transaction_amount' => 99.99,
  'invoice_id' => 1001,
  'method_id' => 3,
  'notify_payer' => true
]);
Example Response

DotSquare\Ecommerce JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'transaction_id': 5502,
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Get Cart

Retrieves full cart details including items, contact info, payment method, and address.


Arguments

token
Required
The cart token.
partition_id
optional
Filter cart items by partition ID.

Data Attributes

items
list
Array of cart items with product details, quantities, and pricing.
contact
list
The billing contact information.
method
list
The selected payment method details.
address
list
The shipping/billing address.
Example Request

\DotSquare\Ecommerce::getCart([
  'token' => 'cart_XXXXXXXXXXXXXX'
]);
Example Response

DotSquare\Ecommerce JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'items': [
      {'item_id': 201, 'title': 'Blue T-Shirt', 'qty': 2, 'price': 24.99},
      {'item_id': 305, 'title': 'Running Shoes', 'qty': 1, 'price': 89.99},
    ],
    'contact': {
      'contact_id': 42,
      'name_first': 'John',
      'name_last': 'Doe',
      'email': 'john@example.com',
    },
    'method': {
      'method_token': 'card_3a4b5c6d7e8f9012',
      'type': 'card',
      'last4': '4242',
      'brand': 'Visa',
    },
    'address': {
      'street': '123 Main St',
      'city': 'San Diego',
      'subdivision': 'US-CA',
      'postal_code': '92101',
      'country': 'US',
    },
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Get Cart Totals

Calculates and returns the totals for a cart including base price, modifiers, discounts, subtotal, tax, gateway fees, and grand total.


Arguments

token
Required
The cart token.
partition_id
optional
Filter by partition ID.
location_id
optional
Location ID for tax/fee calculations.
multi_order
optional
Multi-order flag. Default is false.

Data Attributes

base
decimal
The base item total before modifiers.
modifiers
decimal
Total modifier charges (fees, add-ons).
discounts
decimal
Total discount amount.
subtotal
decimal
Subtotal before tax.
tax
decimal
Calculated tax amount.
gateway_fees
decimal
Payment gateway processing fees.
total
decimal
The grand total.
Example Request

\DotSquare\Ecommerce::getCartTotals([
  'token' => 'cart_XXXXXXXXXXXXXX',
  'location_id' => 1
]);
Example Response

DotSquare\Ecommerce JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'base': 89.97,
    'modifiers': 5.00,
    'discounts': -10.00,
    'subtotal': 84.97,
    'tax': 6.59,
    'gateway_fees': 0,
    'total': 91.56,
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Get Payment Token

Retrieves the details of a previously created payment token including card or bank account information.


Arguments

token
Required
The payment method token to look up.

Data Attributes

method_type
string
The payment method type (card or bank_account).
address
list
The billing address on file.
card
list
Card details (if method_type is card).
bank_account
list
Bank account details (if method_type is bank_account).
Example Request

\DotSquare\Ecommerce::getPaymentToken([
  'token' => 'tok_XXXXXXXXXXXXXX'
]);
Example Response

DotSquare\Ecommerce JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'method_type': 'card',
    'address': {
      'postal_code': '92101',
    },
    'card': {
      'holder_name': 'John Doe',
      'last4': '4242',
      'brand': 'Visa',
      'exp_month': 12,
      'exp_year': 2027,
    },
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Get Subscription

Retrieves subscription details including plan info, items, and calculated totals.


Arguments

token
Required
The subscription token (GUID).

Data Attributes

plan
list
The subscription plan details.
items
list
The subscription line items.
base
decimal
Base price total.
extras
decimal
Extra charges total.
discounts
decimal
Total discount amount.
subtotal
decimal
Subtotal before tax.
tax
decimal
Tax amount.
total
decimal
Grand total.
gateway_fees
decimal
Payment gateway processing fees.
Example Request

\DotSquare\Ecommerce::getSubscription([
  'token' => 'sub_XXXXXXXXXXXXXX'
]);
Example Response

DotSquare\Ecommerce JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'plan': {
      'plan_id': 3,
      'name': 'Pro Monthly',
      'billing_cycle': 'monthly',
    },
    'items': [
      {'item_id': 10, 'title': 'Pro Plan License', 'qty': 1, 'price': 49.99},
      {'item_id': 11, 'title': 'Additional User Seat', 'qty': 2, 'price': 9.99},
    ],
    'base': 69.97,
    'extras': 0,
    'discounts': -10.00,
    'subtotal': 59.97,
    'tax': 4.65,
    'total': 64.62,
    'gateway_fees': 0,
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

UPC

Universal Product Code Lookup

Use this API class to look up product data by barcode (UPC, EAN, ISBN).

Get Item from UPC

Looks up product data by barcode. Supports UPC, EAN, ISBN-10, ISBN-13, ASIN, Model, and MPN identifiers. Returns product title, categories, brand, description, attributes, and images.


Arguments

barcode
Required
The UPC, EAN, or ISBN barcode string.
partition_type_id
optional
The partition type ID.

Data Attributes

title
string
The product title.
brand
string
The product brand.
description
string
The product description.
categories
list
Product categories.
identifiers
list
Product identifiers (UPC, EAN, ISBN, ASIN, etc.).
images
list
Product image URLs.
Example Request

\DotSquare\UPC::getItemFromUPC([
  'barcode' => '012345678901'
]);
Example Response

DotSquare\UPC JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'title': 'Example Product',
    'brand': 'Example Brand',
    'description': 'A great product.',
    'categories': ['Electronics', 'Accessories'],
    'identifiers': {
      'upc': '012345678901',
      'ean': '0012345678901',
    },
    'images': ['https://example.com/image.jpg'],
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Shipping

Calculate Shipping Rates

Use this API class to calculate USPS domestic shipping rates and dynamic shipping costs.

Get Dynamic Shipping Cost

Calculates combined shipping cost from multiple items based on dimensions, weight, origin, and destination.


Arguments

delivery_speed_code
Required
Delivery speed: same_day, next_day, 1-2, 2-3, 3-5, 5-7, 7-14, 14-21, 21+, or unknown.
origin_zip
Required
Origin 5-digit US zip code.
destination_zip
Required
Destination 5-digit US zip code.
items
Required
Array of item objects.
  → height
    Required
Item height in inches.
  → width
    Required
Item width in inches.
  → length
    Required
Item length in inches.
  → weight
    Required
Item weight in pounds.

Data Attributes

rate
decimal
The combined shipping cost for all items.
service
string
The USPS service type used.
Example Request

\DotSquare\Shipping::getDynamicShippingCost([
  'delivery_speed_code' => '3-5',
  'origin_zip' => '92101',
  'destination_zip' => '07416',
  'items' => [
    ['height'=>6, 'width'=>4, 'length'=>8, 'weight'=>2],
    ['height'=>12, 'width'=>10, 'length'=>10, 'weight'=>5]
  ]
]);
Example Response

DotSquare\Shipping JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'rate': 18.75,
    'service': 'Priority Mail',
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Get USPS Domestic Rate

Retrieves USPS domestic shipping rates for a single package based on dimensions, weight, and delivery speed.


Arguments

delivery_speed_code
Required
Delivery speed: same_day, next_day, 1-2, 2-3, 3-5, 5-7, 7-14, 14-21, 21+, or unknown.
origin_zip
Required
Origin 5-digit US zip code.
destination_zip
Required
Destination 5-digit US zip code.
weight_pounds
optional
Weight in pounds. Default is 1.
weight_ounces
optional
Weight in ounces. Default is 0.
height
optional
Height in inches. Default is 12.
width
optional
Width in inches. Default is 12.
length
optional
Length in inches. Default is 12.

Data Attributes

rate
decimal
The shipping rate in USD.
service
string
The USPS service type used.
Example Request

\DotSquare\Shipping::getUSPSDomesticRate([
  'delivery_speed_code' => '3-5',
  'origin_zip' => '92101',
  'destination_zip' => '10001',
  'weight_pounds' => 3,
  'height' => 8,
  'width' => 6,
  'length' => 10
]);
Example Response

DotSquare\Shipping JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'rate': 12.40,
    'service': 'Priority Mail',
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Partitions

Create and Manage Partitions

Use this API class to create new partitions and their directory structures for multi-partition setups.

Create Partition

Creates a new partition with organization, admin user, location, and optional billing/payment gateway setup. Automatically creates the partition directory structure.


Arguments

org_name
Required
The organization name.
partition
Required
Partition configuration.
  → partition_type_id
    Required
The partition type ID.
  → parent_id
    optional
Parent partition ID.
  → segment_id
    optional
Partition segment ID.
  → active
    optional
Active flag.
  → approved
    optional
Approved flag.
  → domain
    optional
Domain name.
  → slug
    optional
Profile URL slug.
  → organization_type_name
    optional
Organization type. Default is Shop.
admin
Required
Admin user details.
  → email
    Required
Admin email address.
  → password
    Required
Admin password.
  → name_first
    Required
Admin first name.
  → name_last
    optional
Admin last name.

Data Attributes

partition_id
int
The newly created partition ID.
admin_id
int
The created admin user ID.
Example Request

\DotSquare\Partitions::createPartition([
  'org_name' => 'My New Shop',
  'partition' => [
    'partition_type_id' => 2,
    'active' => 1,
    'approved' => 1,
    'slug' => 'my-new-shop'
  ],
  'admin' => [
    'email' => 'admin@mynewshop.com',
    'password' => 'securePassword123',
    'name_first' => 'John',
    'name_last' => 'Doe'
  ]
]);
Example Response

DotSquare\Partitions JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {
    'partition_id': 5,
    'admin_id': 102,
  },
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}

Create Partition Directory

Creates the full upload directory structure for a partition including folders for admins, batches, cache, calendar, documents, ecommerce, and more.

Note: This is already created inside the createPartition API if you are using that.


Arguments

id
Required
The partition ID to create the directory structure for.
Example Request

\DotSquare\Partitions::createPartitionDirectory([
  'id' => 5
]);
Example Response

DotSquare\Partitions JSON: {
  'success': true,
  'message': 'Success',
  'http_code': 200,
  'data': {},
  'error': {
    // Error Data will be displayed here in the event of an error.
  }
}