Shift4shop

Shift4Shop App Development and API Integration

Overview

Shift4Shop (formerly 3dcart) is a SaaS eCommerce platform offering hosted online stores with built-in product management, order processing, payment handling, and marketing tools. The platform was rebranded from 3dcart to Shift4Shop in 2020 after acquisition by Shift4 Payments. Many API endpoints and documentation references still use the 3dcart naming.

Shift4Shop provides a REST API for data access and integration, an OAuth-based authentication system for third-party apps, a template engine for storefront customization, and an App Store for distributing extensions. The platform targets small-to-medium businesses and offers a free plan for merchants using Shift4 Payments processing.

Developers can build three types of integrations:

• Public apps -- Listed on the Shift4Shop App Store, available to all merchants. Require OAuth authentication and app review.
• Private apps -- Built for a single store using a private API token. No OAuth flow required.
• Custom modules -- Server-side or client-side code injected into the storefront for custom functionality.

The REST API supports two versions: v1 (legacy, limited endpoints) and v2 (current, broader coverage). New integrations should target API v2 exclusively.

App Development

Authentication Methods

Shift4Shop supports two authentication methods depending on the integration type:

OAuth 2.0 (Public Apps): Register the app in the Shift4Shop Developer Portal to obtain a Client ID and Client Secret. Implement the standard OAuth 2.0 authorization code flow:

1. Redirect the merchant to the Shift4Shop authorization URL.
2. Merchant approves the requested permissions.
3. Shift4Shop redirects back with an authorization code.
4. Exchange the code for an access token.
5. Use the access token in API requests via the Authorization: Bearer {token} header.

Private Token (Private Apps): Generate an API token directly in the Shift4Shop admin panel under Settings > API. Include the token in API requests via the SecureURL and PrivateKey headers. Private tokens are appropriate for single-store integrations where OAuth overhead is unnecessary.

App Registration

Register apps through the Shift4Shop Developer Portal:

1. Create a developer account at the Shift4Shop Developer Portal.
2. Register a new application with name, description, and redirect URIs.
3. Select required API permission scopes.
4. Receive Client ID and Client Secret credentials.
5. Implement OAuth flow in the application.
6. Submit for review before publishing to the App Store.

For complete authentication details, OAuth flow implementation, and developer portal usage, see references/app-development.md.

API Capabilities

The Shift4Shop REST API v2 provides comprehensive access to store data through standard CRUD operations.

Core Resources

• Products -- Full product lifecycle management including variants, options, images, pricing tiers, inventory tracking, SEO fields, and custom fields. Supports advanced product types (grouped, configurable, downloadable).
• Orders -- Order retrieval, status updates, shipment tracking, refund processing, and order notes. Access line items, shipping details, payment information, and customer data per order.
• Customers -- Customer account management, address books, customer groups, and account status. Query by email, name, or registration date.
• Categories -- Category hierarchy management, category-product assignments, SEO fields, and sorting.
• Manufacturers -- Brand/manufacturer management with logo, description, and URL fields.
• CRM -- Customer relationship data including communication logs, tags, and segmentation.

Webhooks

Shift4Shop supports webhooks for real-time event notification. Configure webhooks through the admin panel or API to receive HTTP POST callbacks when events occur:

• Order placed, updated, or shipped
• Product created, updated, or deleted
• Customer registered or updated
• Inventory level changed

Webhook payloads include the affected resource ID and event type. Fetch full resource data via the API after receiving the webhook notification.

Filtering and Pagination

API list endpoints support query parameter filtering and cursor-based pagination. Use limit and offset parameters to paginate results. Filter by date ranges, status values, and resource-specific fields.

Rate Limiting

The API enforces rate limits per access token:

• Public apps: 150 requests per minute
• Private tokens: 100 requests per minute

Rate-limited responses return 429 Too Many Requests with a Retry-After header.

For complete API endpoint documentation, filtering, pagination, and rate limiting details, see references/rest-api.md.

Template Customization

Shift4Shop uses the Core Template Engine for storefront rendering. Themes consist of HTML templates with embedded template tags that render dynamic content.

Core Template Engine

Templates use a tag-based syntax with Shift4Shop-specific tags:

• [product_name] -- Render product title
• [product_price] -- Render product price
• [category_name] -- Render category name
• [store_name] -- Render store name
• [thumbnail] -- Render product thumbnail image

Templates support conditional blocks and loops for more complex rendering than simple variable substitution:

[if product_saleprice]
  <span class="sale-price">[product_saleprice]</span>
  <span class="original-price">[product_price]</span>
[else]
  <span class="price">[product_price]</span>
[/if]

Theme Structure

A Shift4Shop theme consists of:

• frame.html -- The master layout wrapping all pages (header, footer, navigation)
• product.html -- Product detail page template
• listing.html -- Category/product listing template
• home.html -- Homepage template
• cart.html -- Shopping cart template
• CSS files -- Stylesheets in the /assets/ directory
• JavaScript files -- Custom scripts in the /assets/ directory

Edit themes through the Shift4Shop admin (Design > Themes > HTML Editor) or via FTP access.

Custom JavaScript

Inject custom JavaScript for enhanced functionality:

<script>
  // Add to cart animation
  document.querySelectorAll('.add-to-cart-btn').forEach(function(btn) {
    btn.addEventListener('click', function() {
      var cartIcon = document.querySelector('.cart-icon');
      cartIcon.classList.add('bounce');
      setTimeout(function() { cartIcon.classList.remove('bounce'); }, 600);
    });
  });
</script>

For detailed template customization, JavaScript SDK usage, and custom module development, see references/app-development.md.

Payment and Shipping Integrations

Payment Processing

Shift4Shop includes built-in support for Shift4 Payments (primary processor) and major third-party gateways:

• Shift4 Payments (native integration, enables free plan)
• PayPal (Standard, Express Checkout, Payflow Pro)
• Stripe
• Authorize.Net
• Square

Custom payment gateway integration requires building a payment module that implements the Shift4Shop payment interface. The module handles authorization, capture, void, and refund operations.

Shipping Integration

Built-in real-time shipping rate calculators:

• UPS, USPS, FedEx, DHL, Canada Post
• Flat rate, free shipping, table-based rates

Custom shipping integrations use the Shipping API to provide real-time rates at checkout. Register a shipping module that receives cart details and returns available shipping options with calculated rates.

Fulfillment Automation

Use the Orders API to automate fulfillment workflows:

1. Subscribe to order webhooks for new order notifications.
2. Fetch order details via GET /3dCartWebAPI/v2/Orders/{orderId}.
3. Push order data to the fulfillment provider.
4. Update order status and tracking via PUT /3dCartWebAPI/v2/Orders/{orderId}.

Limitations

Understand these constraints before developing for Shift4Shop:

• Legacy naming -- API endpoints still use 3dCartWebAPI in the URL path. Documentation mixes 3dcart and Shift4Shop naming, causing confusion.
• API v1 deprecation -- API v1 has limited endpoints and is no longer actively maintained. Use v2 exclusively for new development.
• Template engine constraints -- The Core Template Engine is less powerful than Liquid (Shopify) or Twig (Sylius). Complex logic requires client-side JavaScript.
• Limited webhook events -- Not all resource changes trigger webhooks. Some integrations still require polling for specific data changes.
• App Store review timeline -- Public app review can take several weeks. Plan submission timelines accordingly.
• Developer documentation -- Documentation quality varies. Test API behavior empirically and expect undocumented edge cases.
• No staging environment -- Template and configuration changes affect the live store directly. Back up templates before editing.

Anti-Patterns

• Using API v1 for new integrations -- Always use API v2. V1 has fewer endpoints, inconsistent responses, and will eventually be deprecated.
• Ignoring OAuth token refresh -- OAuth access tokens expire. Implement token refresh logic to avoid authentication failures in long-running integrations.
• Hardcoding the store URL -- Store URLs can change. Use the SecureURL provided during OAuth installation rather than hardcoding domain names.
• Polling when webhooks are available -- Use webhooks for supported events. Reserve polling for events without webhook coverage.
• Exposing private tokens -- Never include private API tokens in client-side code, public repositories, or browser requests.

Reference Files

• REST API -- REST API v1/v2, authentication, endpoints, filtering, pagination, webhooks, rate limiting
• App Development -- App registration, OAuth flow, developer portal, template customization, JavaScript SDK, custom modules
• Marketplace -- Shift4Shop App Store, submission process, requirements, partner program