This guide provides detailed instructions for using the Grouptify Product Group API to manage product groups in your e-commerce platform. The API allows you to create, retrieve, update, and delete product groups, with support for customizable options and Shopify integration. This document is tailored for advanced users who have obtained their API key from the Grouptify settings panel.

Obtaining Your API Key

To use the API, you need an API key, which can be found in your Shopify admin:

1. Log in to your Shopify admin.
2. Go to the app G: Combined Listings.
3. Click on Settings.
4. Find the section Manage product groups through API.
5. Here you will find the API key for your store (available with Advanced plan).
6. You can refresh the token if needed. The token does not expire.

Important: Keep your API key secure and do not expose it publicly.

Support

For technical support or questions about the API, contact us at: support@tapita.io

Authentication

All API requests require the following header for authentication:

Headers: {
  "gtf-api-key": "YOUR_API_KEY"
}

Base URL

https://grouptify.pwa-commerce.com/

Product Group Structure

A product group is represented as a JSON object with the following structure. Note that identifiers (id fields) must be unique across the system to prevent conflicts.

{
  "_id": "64f9a12c456b789d0e123a45",
  "id": "group1",
  "name": "Summer Collection",
  "is_active": true,
  "options": [
    {
      "id": "option1",
      "name": "Color",
      "template_card": "mpg-swatch-circle",
      "template_prod": "mpg-swatch-circle",
      "values": [
        {
          "id": "color1",
          "name": "Red",
          "style": "color1",
          "color1": "#FF0000",
          "color2": "",
          "image_custom": ""
        },
        {
          "id": "color2",
          "name": "Custom Image",
          "style": "custom_image",
          "color1": "",
          "color2": "",
          "image_custom": "https://example.com/images/custom.jpg"
        }
      ]
    }
  ],
  "products": [
    {
      "id": "14676221886832",
      "title": "Red Summer Shirt",
      "handle": "red-summer-shirt",
      "status": "ACTIVE",
      "images": ["https://example.com/images/shirt.jpg"],
      "options": ["color1"],
      "regular_price": 100,
      "sale_price": 80,
      "available": true
    }
  ]
}

Field Explanation

• _id (string, auto-generated): MongoDB object ID automatically generated by the system. This is used for API operations that require an ID parameter.
• id (string, required): A human-readable unique identifier for the group (e.g., group1). Must be distinct across all groups to avoid conflicts.
• name (string, required): Descriptive name for the group (e.g., "Summer Collection").
• is_active (boolean, required): Indicates whether the group is published (true) or unpublished (false).
• options (array, optional): Array of option objects defining attributes like color or size.
  • id (string, required): A unique identifier for the option within the group (e.g., option1).
  • name (string, required): Name of the option (e.g., "Color").
  • template_card (string, required): Template for displaying options on product cards. Valid values:
    • mpg-button
    • mpg-button-pill
    • mpg-dropdown
    • mpg-swatch-circle
    • mpg-swatch-square
    • mpg-swatch-polaroid
    • mpg-swatch-circle-button
    • mpg-swatch-square-button
    • mpg-swatch-image-button
  • template_prod (string, required): Template for displaying options on product pages (same valid values as template_card).
  • values (array, required): Array of value objects for the option.
    • id (string, required): A unique identifier for the value within the group (e.g., color1).
    • name (string, required): Name of the value (e.g., "Red").
    • style (string, required): Display style for the swatch. Valid values:
      • color1: Single-color swatch.
      • color2: Two-color swatch.
      • custom_image: Custom image swatch.
    • color1 (string, optional): Hex color code for color1 or color2 styles (e.g., #FF0000).
    • color2 (string, optional): Hex color code for color2 style.
    • image_custom (string, optional): Image URL for custom_image style.
• products (array, optional): Array of product objects in the group.
  • id (string, required): Shopify product ID - a numeric string like "14824372961648". You can find this ID in your Shopify admin URL when viewing a product: https://admin.shopify.com/store/your-store-name/products/14824372961648
  • title (string, required): Product title from Shopify.
  • handle (string, required): Shopify product handle.
  • status (string, required): Product status from Shopify (e.g., ACTIVE, DRAFT).
  • images (array, required): List of product image URLs from Shopify.
  • options (array, required): List of unique value IDs (from options.values) associated with the product.
  • regular_price (number, required): Original price from Shopify.
  • sale_price (number, optional): Discounted price from Shopify.
  • available (boolean, required): Product availability status.

Note on Unique IDs: All IDs must be unique across the system. Use simple, meaningful identifiers that help you understand the relationship between elements (e.g., group1, option1, color1, product1).

Endpoints

1. Get All Product Groups

Retrieve a paginated list of product groups with optional filtering.

• Method: GET

• URL: /grouptify

• Permission: read_product_group

• Query Parameters:

  • page (integer, optional, default: 1): Page number for pagination.
  • page_size (integer, optional, default: 10): Number of items per page.
  • query (string, optional): Filter groups by name, product title, or product handle.
  • create_method (string, optional): Filter by creation method (manual, automation, all; default: all).

• Response:

  • 200 OK: Paginated list of product groups.
  • 401 Unauthorized: Invalid or missing API key.
  • 403 Forbidden: Insufficient permissions.
  • 500 Internal Server Error: Server error with message.

• Example Request:

  GET https://grouptify.pwa-commerce.com/grouptify?page=1&page_size=10&query=shirt&create_method=manual HTTP/1.1
  Headers:
    gtf-api-key: YOUR_API_KEY
  
  

• Example Response:

  {
    "results": [
      {
        "_id": "64f9a12c456b789d0e123a45",
        "id": "group1",
        "name": "Shirt Collection",
        "is_active": true,
        "options": [...],
        "products": [...]
      }
    ],
    "total": 25,
    "page": 1,
    "page_size": 10,
    "total_pages": 3
  }
  
  

2. Get Product Group by ID

Retrieve a single product group by its unique MongoDB ID.

• Method: GET

• URL: /grouptify/:id

• Permission: read_product_group

• URL Parameters:

  • id (string, required): The MongoDB _id of the product group (e.g., 64f9a12c456b789d0e123a45).

• Response:

  • 200 OK: Product group details.
  • 401 Unauthorized: Invalid or missing API key.
  • 404 Not Found: Group not found.
  • 500 Internal Server Error: Server error with message.

• Example Request:

  GET https://grouptify.pwa-commerce.com/grouptify/64f9a12c456b789d0e123a45 HTTP/1.1
  Headers:
    gtf-api-key: YOUR_API_KEY
  
  

• Example Response:

  {
    "_id": "64f9a12c456b789d0e123a45",
    "id": "group1",
    "name": "Shirt Collection",
    "is_active": true,
    "options": [...],
    "products": [...]
  }
  
  

3. Create a Product Group

Create a new product group. The system will automatically generate a unique _id for the group.

• Method: POST

• URL: /grouptify

• Permission: write_product_group

• Body: JSON object matching the product group structure (excluding _id and shop, which are determined by the system and your API key respectively).

• Response:

  • 201 Created: Created product group with auto-generated _id.
  • 400 Bad Request: Invalid request body.
  • 401 Unauthorized: Invalid or missing API key.
  • 403 Forbidden: Insufficient permissions.
  • 500 Internal Server Error: Server error with message.

• Example Request:

  POST https://grouptify.pwa-commerce.com/grouptify HTTP/1.1
  Headers:
    gtf-api-key: YOUR_API_KEY
  Content-Type: application/json
  
  {
    "id": "summer-collection-2024",
    "name": "Summer Collection 2024",
    "is_active": true,
    "options": [
      {
        "id": "color-option",
        "name": "Color",
        "template_card": "mpg-swatch-circle",
        "template_prod": "mpg-swatch-circle",
        "values": [
          {
            "id": "red-color",
            "name": "Red",
            "style": "color1",
            "color1": "#FF0000",
            "color2": "",
            "image_custom": ""
          }
        ]
      }
    ],
    "products": [
      {
        "id": "14824372961648",
        "title": "Red Summer Shirt",
        "handle": "red-summer-shirt",
        "status": "ACTIVE",
        "images": ["https://example.com/images/shirt.jpg"],
        "options": ["red-color"],
        "regular_price": 100,
        "sale_price": 80,
        "available": true
      }
    ]
  }
  
  

• Example Response:

  {
    "_id": "64f9a12c456b789d0e123a47",
    "id": "summer-collection-2024",
    "name": "Summer Collection 2024",
    "is_active": true,
    "shop": "shop123",
    "options": [...],
    "products": [...]
  }
  
  

4. Update a Product Group by ID

Update an existing product group by its unique MongoDB ID.

• Method: PUT

• URL: /grouptify/:id

• Permission: write_product_group

• URL Parameters:

  • id (string, required): The MongoDB _id of the product group (e.g., 64f9a12c456b789d0e123a45).

• Body: JSON object with fields to update (partial updates supported).

• Response:

  • 200 OK: Updated product group.
  • 400 Bad Request: Invalid request body.
  • 401 Unauthorized: Invalid or missing API key.
  • 403 Forbidden: Insufficient permissions.
  • 404 Not Found: Group not found.
  • 500 Internal Server Error: Server error with message.

• Example Request:

  PUT https://grouptify.pwa-commerce.com/grouptify/64f9a12c456b789d0e123a45 HTTP/1.1
  Headers:
    gtf-api-key: YOUR_API_KEY
  Content-Type: application/json
  
  {
    "name": "Updated Summer Collection",
    "is_active": false
  }
  
  

• Example Response:

  {
    "_id": "64f9a12c456b789d0e123a45",
    "id": "group1",
    "name": "Updated Summer Collection",
    "is_active": false,
    "shop": "shop123",
    "options": [...],
    "products": [...]
  }
  
  

5. Delete a Product Group by ID

Delete a product group by its unique MongoDB ID.

• Method: DELETE

• URL: /grouptify/:id

• Permission: write_product_group

• URL Parameters:

  • id (string, required): The MongoDB _id of the product group (e.g., 64f9a12c456b789d0e123a45).

• Response:

  • 200 OK: Group deleted successfully with message.
  • 401 Unauthorized: Invalid or missing API key.
  • 403 Forbidden: Insufficient permissions.
  • 404 Not Found: Group not found.
  • 500 Internal Server Error: Server error with message.

• Example Request:

  DELETE https://grouptify.pwa-commerce.com/grouptify/64f9a12c456b789d0e123a45 HTTP/1.1
  Headers:
    gtf-api-key: YOUR_API_KEY
  
  

• Example Response:

  {
    "message": "Deleted successfully"
  }
  
  

6. Bulk Delete Product Groups

Delete multiple product groups by their unique MongoDB IDs.

• Method: POST

• URL: /grouptify/bulk-delete

• Permission: write_product_group

• Body:

  {
    "ids": [
      "64f9a12c456b789d0e123a45",
      "64f9a12c456b789d0e123a46"
    ]
  }
  
  

• Response:

  • 200 OK: Success message.
  • 400 Bad Request: Invalid request body or empty IDs array.
  • 401 Unauthorized: Invalid or missing API key.
  • 403 Forbidden: Insufficient permissions.
  • 500 Internal Server Error: Server error with message.

• Example Request:

  POST https://grouptify.pwa-commerce.com/grouptify/bulk-delete HTTP/1.1
  Headers:
    gtf-api-key: YOUR_API_KEY
  Content-Type: application/json
  
  {
    "ids": [
      "64f9a12c456b789d0e123a45",
      "64f9a12c456b789d0e123a46"
    ]
  }
  
  

• Example Response:

  {
    "message": "Deleted successfully"
  }
  
  

Error Handling

Errors are returned with standard HTTP status codes and a JSON body:

{
  "message": "Detailed error message"
}

Common HTTP status codes:

• 400 Bad Request: Invalid request body or parameters.
• 401 Unauthorized: Missing or invalid API key.
• 403 Forbidden: Insufficient permissions.
• 404 Not Found: Resource not found.
• 500 Internal Server Error: Server-side error.

Best Practices

1. Use the Correct ID: When making API calls that require an ID parameter (GET, PUT, DELETE), always use the MongoDB _id field value, not the human-readable id field.
2. Product ID Format: When adding products to a group, use the Shopify product ID, which is a numeric string like "14824372961648". You can find this in your Shopify admin URL when viewing the product.
3. Secure Your API Key: Store it securely and avoid embedding it in client-side code.
4. Paginate Large Datasets: Use page and page_size parameters for efficient retrieval of large group lists.
5. Validate Template Values: Ensure template_card and template_prod use valid values including the new mpg-swatch-image-button option.
6. Unique Identifiers: All id fields must be unique across the system to prevent conflicts.
7. Test in Development: Test API calls in a non-production environment to avoid unintended changes.
8. Handle Errors Gracefully: Always check response status codes and handle errors appropriately in your application.

Rate Limiting

To ensure optimal performance for all users, the API implements rate limiting. If you exceed the rate limit, you'll receive a 429 Too Many Requests response. In such cases, wait a moment before making additional requests.