3dcart (now Shift4Shop)

Log in to your Shift4Shop merchant dashboard (store.3dcart.com or your custom domain). Navigate to Apps & Addons in the left sidebar, then click on API. If you do not see an API section, look under Settings → API or contact Shift4Shop support — the location changed in some dashboard versions. On the API page, you will find your Private Key (also shown as 'Private API Key'). This is a long alphanumeric string unique to your store. Copy and save it in a password manager immediately. Do not confuse this with any 'Public Key' that may be displayed on the same page — the Public Key is for client-side integrations and does NOT work as the PrivateKey header. While you are here, also note your store's URL. This is the SecureURL header value — the full HTTPS domain of your storefront, for example https://myshop.3dcart.com or https://shop.mydomain.com if you use a custom domain. Write down both values. You now have everything you need to configure the API Connector in Bubble.

In your Bubble app editor, go to Plugins tab → Add plugins → search for 'API Connector' (published by Bubble) and install it. Open the API Connector and click 'Add another API'. Name the group 'Shift4Shop API'. This is the most important step in the entire tutorial, and the single biggest gotcha in this integration: the base URL is https://apirest.3dcart.com/3dCartWebAPI/v2. Copy this URL exactly. Do NOT use any shift4shop.com URL — the API does not operate on the shift4shop.com domain and will return SSL errors or no response if you use it. Now add the two required shared headers. Click 'Add shared headers'. First header: name it exactly PrivateKey (case-sensitive, no space, capital P capital K), value is your store Private Key, and check the 'Private' checkbox. Second header: name it exactly SecureURL (capital S capital URL, no space), value is your full storefront URL (e.g., https://myshop.3dcart.com), and check the 'Private' checkbox. Also add a third header: Content-Type with value application/json (no Private checkbox needed). Both PrivateKey and SecureURL are marked Private, which means Bubble will only send them from its servers and they will never appear in browser requests. Save the group configuration.

1// Shift4Shop API Connector Group Configuration
2// CRITICAL: Base URL uses 3dcart.com domain even after rebrand to Shift4Shop
3{
4  "groupName": "Shift4Shop API",
5  "rootURL": "https://apirest.3dcart.com/3dCartWebAPI/v2",
6  "sharedHeaders": [
7    {
8      "name": "PrivateKey",
9      "value": "YOUR_STORE_PRIVATE_API_KEY",
10      "private": true
11    },
12    {
13      "name": "SecureURL",
14      "value": "https://yourstore.3dcart.com",
15      "private": true
16    },
17    {
18      "name": "Content-Type",
19      "value": "application/json",
20      "private": false
21    },
22    {
23      "name": "Accept",
24      "value": "application/json",
25      "private": false
26    }
27  ]
28}

With both headers configured, add a test call to verify authentication. In the Shift4Shop API group, click 'Add another call'. Name it 'Get Orders'. Set the method to GET and the path to /Orders. Add a query parameter named limit with value 1 (used only for initialization, to keep the response small). Click 'Initialize call'. Bubble will send a real HTTP request to Shift4Shop's API. A successful response returns an array of order objects. Bubble detects the fields and shows you the schema including OrderID, OrderDate, BillingFirstName, OrderStatusID, InvoiceNumber, and OrderTotal. If initialization fails with HTTP 401: verify that the PrivateKey header contains the store Private Key (not a public key or login password), verify that the SecureURL header contains your full storefront URL (https:// included), and check that both header names are spelled exactly PrivateKey and SecureURL. An HTTP 401 without any body message almost always means one of the two headers is missing or misnamed — the API does not distinguish between wrong PrivateKey and missing SecureURL in its error response. If you get an SSL error or no response at all, the base URL is wrong — confirm it contains apirest.3dcart.com, not any shift4shop.com domain.

1// Expected Shift4Shop GET /Orders?limit=1 response structure
2[
3  {
4    "OrderID": "ABC-20240101-001",
5    "InvoiceNumber": "10001",
6    "OrderDate": "2024-01-15 09:30:00",
7    "OrderStatusID": 1,
8    "BillingFirstName": "Jane",
9    "BillingLastName": "Smith",
10    "BillingEmail": "jane@example.com",
11    "OrderTotal": 129.99,
12    "CardType": "Visa",
13    "ShipmentList": [],
14    "ProductList": [
15      {
16        "CatalogID": 123,
17        "SKU": "PROD-001",
18        "Name": "Ceramic Mug",
19        "Price": 25.99,
20        "Quantity": 2
21      }
22    ]
23  }
24]

With authentication confirmed, build an order management page. Create a new Bubble page named 'Orders'. Add a Repeating Group and set its data source to 'Get data from an external API' → Shift4Shop API → Get Orders. Add UI elements inside the Repeating Group: a Text element for OrderID, a Text element for customer name (combine BillingFirstName and BillingLastName), a Text element for OrderTotal, and a Text element for OrderDate. For filtering by date, the Shift4Shop REST API uses ISO format dates (YYYY-MM-DD) — for example, the datestart and dateend query parameters on the /Orders endpoint. In your API call parameters, use Bubble's 'Format as date' expression with format YYYY-MM-DD when passing date values. This is different from BigCommerce v2, which requires RFC 2822 format — Shift4Shop uses the more standard ISO format. To filter by status, add an orderstatus parameter to your Get Orders call with values like 1 for New, 2 for Processing, 3 for Shipped. Add a dropdown to the Orders page so users can filter by status. When a Repeating Group row is clicked, navigate to an Order Detail page passing the OrderID as a URL parameter, then fetch the specific order using GET /Orders/{OrderID} and display all details including the line items from the ProductList array.

1// Shift4Shop GET /Orders parameters for date and status filtering
2// API Connector call parameters to add:
3// datestart: YYYY-MM-DD format (use Bubble 'Format as date' expression)
4// dateend: YYYY-MM-DD format
5// orderstatus: numeric status ID
6// limit: number of records to return (max verify in docs)
7// offset: for pagination
8
9// Order status codes (verify current codes in Shift4Shop documentation):
10// 1  = New
11// 2  = Processing
12// 3  = Awaiting Fulfillment
13// 5  = Shipped
14// 6  = Delivered
15// 7  = Cancelled
16// 8  = Refunded
17
18// Date format for Shift4Shop: ISO 8601 (YYYY-MM-DD)
19// Example: datestart=2024-01-01&dateend=2024-01-31

Product management in Shift4Shop has a structure that differs from other e-commerce platforms and causes silent failures when not understood: variant-level inventory (different quantities for different sizes, colors, etc.) is stored at the OptionSets level, not on the top-level product record. If you call GET /Products/{CatalogID} and update the Stock field directly on a product that uses OptionSets for variants, the API returns 200 OK but the inventory does not change. Add two new calls to your Shift4Shop API group: (1) 'Get Products' — GET /Products with parameters limit and offset; (2) 'Get Product OptionSets' — GET /Products/{catalogID}/OptionSets with catalogID as a dynamic parameter. The OptionSets response returns an array of variant combinations, each with its own MFGID (manufacturer SKU), Price, Stock, and optionSetID. When building a product management page in Bubble, first load products with Get Products. For each product that has variants (check the OptionSetList array in the product response — if it contains items, the product uses OptionSets), trigger a Get Product OptionSets call to see variant-level quantities. To update variant stock, use PUT /Products/{catalogID}/OptionSets/{optionSetID} from a Backend Workflow. Bulk operations (updating multiple products or multiple variants) require a loop in a Backend Workflow — each PUT call consumes Bubble Workload Units, so scope your usage accordingly for large catalogs. Backend Workflows for write operations require a paid Bubble plan.

1// Shift4Shop GET /Products/{catalogID}/OptionSets response structure
2[
3  {
4    "optionSetID": 1001,
5    "MFGID": "MUG-BLUE-SM",
6    "Stock": 15,
7    "Price": 24.99,
8    "OptionList": [
9      { "OptionID": 5, "OptionName": "Color", "OptionValue": "Blue" },
10      { "OptionID": 6, "OptionName": "Size",  "OptionValue": "Small" }
11    ]
12  },
13  {
14    "optionSetID": 1002,
15    "MFGID": "MUG-BLUE-LG",
16    "Stock": 3,
17    "Price": 24.99,
18    "OptionList": [
19      { "OptionID": 5, "OptionName": "Color", "OptionValue": "Blue" },
20      { "OptionID": 6, "OptionName": "Size",  "OptionValue": "Large" }
21    ]
22  }
23]
24
25// To update variant stock, PUT /Products/{catalogID}/OptionSets/{optionSetID}
26// Body: { "Stock": 20 }
27// Returns 200 OK if successful — changes the variant's stock (not the parent product's stock field)

Order status updates in Shift4Shop require a PUT call to /Orders/{OrderID} with the new status fields. Set this up as a Backend Workflow since it is a write operation that should stay server-side. In the API Connector, add a call named 'Update Order Status' — method PUT, path /Orders/{OrderID}, with OrderID as a dynamic parameter. The request body is a JSON object: { 'OrderStatusID': 'new_status_id' }. Add this as a body parameter in the API call configuration. In Bubble, create a Backend Workflow called 'Update_Order_Status' that takes OrderID (text) and NewStatusID (number) as inputs. The workflow calls 'Update Order Status' with those parameters. On your Orders page, add an 'Update Status' button or dropdown next to each order in the Repeating Group. When clicked, trigger the Backend Workflow with the order's OrderID and the selected new status. Important caveats: the API Workflows (Backend Workflows) feature requires a paid Bubble plan. Bulk status updates for many orders require a loop of PUT calls in a Backend Workflow — each call consumes Workload Units. For processing 100+ orders, schedule the workflow during off-peak hours rather than triggering it from user interaction to avoid WU spikes. For RapidDev's full implementation guide on building Bubble order management apps with e-commerce APIs, see rapidevelopers.com/contact.

1// Shift4Shop PUT /Orders/{OrderID} — update order status
2// API Connector call configuration:
3{
4  "method": "PUT",
5  "path": "/Orders/<OrderID dynamic>",
6  "headers": {
7    "PrivateKey": "<private>",
8    "SecureURL": "<private>",
9    "Content-Type": "application/json"
10  },
11  "body": {
12    "OrderStatusID": "<NewStatusID dynamic>"
13  }
14}
15
16// PUT /Orders returns HTTP 200 with an empty or minimal response body on success
17// If you receive 400 Bad Request, check that OrderStatusID is a valid numeric status code
18// If you receive 404 Not Found, verify the OrderID matches exactly (check for leading zeros or format differences)