Adding Products to the Social Print Studio Shopify Cart

Overview

Social Print Studio provides an API endpoint that lets external applications add products to our Shopify cart. Your app sends a simple JSON payload describing what to add, and receives a URL to redirect the customer to. The customer lands on our Shopify cart with the product already added, and can then checkout and pay for their order directly on our website. We will process and print the order and handle any customer service or issues.

You do need:

• The variant SKU of the product (must exactly match a SKU in our Shopify store — see SKU Requirements). You should have access to other files which include our product library and the variant SKUs specific to each product.
• A source identifier for your app. You can create this yourself, based on your own app name.
• Project data with at least one publicly accessible photo URL. All products offered via this API are custom printed and require project data so we know what to print. If you need a way to host images, see our optional Image Upload API.
• The ability to make an HTTP POST request and redirect the user's browser.

Endpoint

POST https://editor-staging.socialprintstudio.com/api/cart/external-app-addToCart
Content-Type: application/json

Request Body

Required Fields

Optional Fields

Project Data

The projectData object contains the custom content (photos, designs, etc.) that our fulfillment team needs to access when producing the order. Since all products offered via this API are custom printed, this field is required.

When you include projectData, the data is saved to our project database and a unique projectId is generated. This ID is automatically attached to the Shopify line item so our fulfillment team can access your photos and project data when producing the order.

Photo URL Requirements

Line Item Properties

The properties object lets you attach key-value string pairs directly to the Shopify cart line item. These are visible in the Shopify order admin and available to our fulfillment systems.

Response

Success (200)

{
  "success": true,
  "redirectUrl": "https://socialprintstudio.com/pages/newcart?cartKey=prod_1707400000_abc123def",
  "projectId": "65a1b2c3d4e5f6a7b8c9d0e1"
}

Error Responses

All error responses include an error field with a human-readable message:

{
  "error": "Missing required field: \"sku\" (string). This should be the Shopify product SKU."
}

Examples

Minimal Example — Simple Photo Product

A minimal request with required fields. All products offered via this API are custom printed and require project data with at least one photo URL.

const response = await fetch(
  'https://editor-staging.socialprintstudio.com/api/cart/external-app-addToCart',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      sku: 'metal-print-4x4',
      source: 'my-partner-app',
      projectData: {
        photos: [
          'https://cdn.example.com/uploads/user123/photo-sunset.jpg',
        ],
      },
    }),
  }
);

const { redirectUrl } = await response.json();

// Send the customer to the Shopify cart
window.location.href = redirectUrl;

Full Example — Photo Product with Metadata

A product that includes customer photos and extra metadata for fulfillment.

const response = await fetch(
  'https://editor-staging.socialprintstudio.com/api/cart/external-app-addToCart',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      sku: 'softcover-8x8-40',
      quantity: 1,
      source: 'my-partner-app',

      projectData: {
        photos: [
          'https://cdn.example.com/uploads/user123/cover-file.jpg',
          'https://cdn.example.com/uploads/user123/photo-beach-sunset.jpg',
          'https://cdn.example.com/uploads/user123/photo-family-portrait.jpg',
        ],
        metadata: {
          bookTitle: 'Summer Vacation 2025',
          customerNotes: 'Extra information stored on the order as a record',
        },
      },

      properties: {
        'Project Name': 'Summer Vacation 2025',
        _cover_preview_url:
          'https://cdn.example.com/previews/user123/cover-thumb.jpg',
      },
    }),
  }
);

const data = await response.json();

if (!response.ok) {
  console.error('Failed to add to cart:', data.error);
  return;
}

// Optionally save the projectId for your own records
console.log('Project saved with ID:', data.projectId);

// Redirect the customer to the Shopify cart
window.location.href = data.redirectUrl;

Example with Multiple Quantity

const response = await fetch(
  'https://editor-staging.socialprintstudio.com/api/cart/external-app-addToCart',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      sku: 'photo-print-30x40',
      quantity: 3,
      source: 'my-partner-app',
      projectData: {
        photos: [
          'https://cdn.example.com/photo1.jpg'
        ],
      },
    }),
  }
);

const { redirectUrl } = await response.json();
window.location.href = redirectUrl;

SKU Requirements

The sku value must exactly match a product variant SKU in our Shopify store. If the SKU doesn't match, the API will return a 502 error.

Things to keep in mind:

• SKUs are case-sensitive and typically lowercase with hyphens (e.g. softcover-8x8-40, classic-prints-4x4)
• Some products include a page count in the SKU (e.g. softcover-8x8-40 is a softcover 8x8 book with 40 pages)
• Some products include material or style qualifiers (e.g. -oatmeal, -flex)
• If you're unsure about a SKU, verify it against the SKU list provided to you. An incorrect or misspelled SKU will cause the request to fail, or worse, succeed but print the wrong product.

Integration Flow Diagram

┌─────────────────────┐
│   Your Application   │
│                     │
│  1. User finishes   │
│     creating their  │
│     product         │
│                     │
│  2. POST to         │
│     /api/cart/      │
│     external-app-   │
│     addToCart        │
│     with SKU +      │
│     project data    │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│   Our API Endpoint   │
│                     │
│  3. Saves project   │
│     data to our DB  │
│                     │
│  4. Resolves SKU to │
│     Shopify variant │
│                     │
│  5. Stages cart     │
│     items           │
│                     │
│  6. Returns         │
│     redirectUrl     │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│  Your app redirects  │
│  the user's browser  │
│  to redirectUrl      │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│   Shopify Cart Page  │
│                     │
│  7. Fetches staged  │
│     cart data       │
│                     │
│  8. Adds items to   │
│     the Shopify     │
│     cart             │
│                     │
│  9. Customer sees   │
│     their cart and  │
│     can check out   │
└─────────────────────┘

Important Notes

1. The redirect URL is single-use. Once the Shopify cart page retrieves the cart data, the key is deleted. Do not attempt to reuse it.
2. Photo URLs must be publicly accessible. Our fulfillment system needs to download these images when producing the order. URLs behind authentication or on localhost will not work. URLs must remain valid for at least one week — see Photo URL Requirements for format, size, and quality guidance. If you need a simple way to host images, we provide an optional Image Upload API that returns public URLs you can use directly in projectData.photos.
3. The source field is important. It helps us track which app generated the order and debug issues. Pick a consistent, descriptive identifier for your app and use it on every request.
4. CORS is enabled. You can call this endpoint from client-side JavaScript in the browser. If you call it from a backend server, just pass the redirect URL to the customer's browser for the final redirect step.
5. Request size limit is 10 MB. If you're including many photo URLs or large metadata objects, keep the total payload under 10 MB.
6. The projectId in the response is the database reference for the saved project. You may want to store this in your own system for debugging or support conversations.