API Documentation - Custom Safety Products

Overview

All API endpoints are served by Laravel under the `api` route group and use store key authentication. Include both required headers on every request.

Authentication

Header	Description
`X-Store-Key`	32-character store authentication key
`X-Store-Hash`	Store identifier hash used to resolve the store

Common response

{
  "success": true,
  "message": "...",
  "data": { ... }
}

Endpoint summary

POST

Configure Store

/api/stores/configure

POST

Generate Token

/api/stores/generate-token

Generate a backward-compatible token for the store.

POST

Save Design

/api/design/save

Save or update design metadata in the local database.

GET

Design Details

/api/design/details/{design_id}

Retrieve stored design details, optionally syncing with CSP.

POST

Update Quantities

/api/design/update-quantities

Update design item quantities and propagate changes to CSP.

POST

Duplicate Design

/api/design/duplicate

Duplicate one or more designs in CSP and store the new records locally.

GET

Design Proof

/api/design/proof/{design_id}

Retrieve the proof URL for a design associated with an order.

GET

Design Files

/api/design/files/{design_id}

Retrieve ZIP URL and legacy metadata for design files.

POST

Create Print File

/api/design/print-file

Create a print-ready file for a design.

POST

Create Sheet Label

/api/design/sheet-label

Generate a sheet label for a design using a template.

POST

Update PO Number

/api/design/update-po

Update the purchase order number for a design.

POST

Place Order

/api/order/place

Place an order for one or more designs with customer details.

Endpoint details

POST

/api/stores/configure

Register or update CSP configuration for the store. If the store does not yet exist, this endpoint will create it and store the key.

Authorization

Header	Required
`X-Store-Key`	Yes
`X-Store-Hash`	Yes

Parameters

Parameter	Type	Description
`is_first_time`	boolean	Optional. Set true for first-time setup so the store key is registered.
`store_name`	string	Optional. Friendly name for the store.
`store_url`	url	Optional. Store website URL.
`csp_api_endpoint`	url	Required. CSP API base endpoint.
`csp_api_user`	string	Required. CSP API username.
`csp_api_password`	string	Required. CSP API password.

Request example

{
  "is_first_time": true,
  "store_name": "My Store",
  "store_url": "https://example.com",
  "csp_api_endpoint": "https://csp.example.com/api",
  "csp_api_user": "apiuser",
  "csp_api_password": "apipassword"
}

Success response

{
  "success": true,
  "message": "Store configuration saved and store key registered successfully",
  "data": {
    "store_id": 123,
    "store_hash": "abc123...",
    "is_first_time": true
  }
}

POST

/api/stores/generate-token

Generate a store token while still using the standard store key authentication headers.

Authorization

Header	Required
`X-Store-Key`	Yes
`X-Store-Hash`	Yes

Parameters

Parameter	Type	Description
`token_name`	string	Optional. Name for the generated token. Defaults to `api-token`.

Request example

{
  "token_name": "api-token"
}

Success response

{
  "success": true,
  "message": "Token generated successfully",
  "data": {
    "token": "plain-text-token-value",
    "store_id": 123,
    "store_hash": "abc123...",
    "token_name": "api-token"
  }
}

POST

/api/design/save

Save or update a design record in the local database.

Authorization

Header	Required
`X-Store-Key`	Yes
`X-Store-Hash`	Yes

Parameters

Parameter	Type	Description
`design_id`	integer	Required. Unique design identifier.
`product_sku`	string	Optional. Product SKU.
`customer_id`	string	Optional. Customer identifier.
`visitor_id`	string	Optional. Visitor or session identifier.
`items`	array	Optional. Item list for the design.
`items.*.sku`	string	Required when items are provided. Item SKU.
`items.*.quantity`	integer	Required when items are provided. Item quantity.
`items.*.thumbnail`	url	Optional. Item thumbnail URL.
`art_cost`	numeric	Optional. Art cost.
`decorator_cost`	numeric	Optional. Decorator cost.
`setup_cost`	numeric	Optional. Setup cost.
`preview_url`	url	Optional. Preview URL.
`status`	integer	Optional. Design status code.

Request example

{
  "design_id": 456,
  "product_sku": "SKU-001",
  "customer_id": "CUST-123",
  "visitor_id": "VIS-789",
  "items": [
    {
      "sku": "ITEM-001",
      "quantity": 10,
      "thumbnail": "https://example.com/thumb.jpg"
    }
  ],
  "art_cost": 25.50,
  "decorator_cost": 10.00,
  "setup_cost": 5.00,
  "preview_url": "https://example.com/preview.png",
  "status": 1
}

Success response

{
  "success": true,
  "message": "Design saved successfully",
  "data": {
    "id": 789,
    "design_id": 456,
    "store_id": 123
  }
}

GET

/api/design/details/{design_id}

Retrieve stored design details. Use the sync flag to refresh from CSP.

Authorization

Header	Required
`X-Store-Key`	Yes
`X-Store-Hash`	Yes

Parameters

Parameter	Type	Description
`design_id`	path integer	Required. The design identifier in the URL.
`sync`	boolean	Optional query parameter to refresh data from CSP.

Example request

GET /api/design/details/456?sync=true

Success response

{
  "success": true,
  "data": {
    "design_id": 456,
    "product_sku": "SKU-001",
    "status": 1,
    "job_id": "JOB-123",
    "fees": {
      "art_cost": 25.50,
      "decorator_cost": 10.00,
      "setup_cost": 5.00
    },
    "items": [
      {
        "sku": "ITEM-001",
        "quantity": 10,
        "thumbnail": "https://example.com/thumb.jpg"
      }
    ],
    "preview_url": "https://example.com/preview.png",
    "proof_url": "https://example.com/proof.pdf",
    "created_at": "2026-04-17T12:00:00Z",
    "updated_at": "2026-04-17T12:05:00Z"
  }
}

POST

/api/design/update-quantities

Update item quantities for a design and submit the changes to CSP.

Authorization

Header	Required
`X-Store-Key`	Yes
`X-Store-Hash`	Yes

Parameters

Parameter	Type	Description
`design_id`	integer	Required. The design ID.
`items`	array	Required. List of items to update.
`items.*.sku`	string	Required. Item SKU.
`items.*.quantity`	integer	Required. Quantity for each item.
`combine_skus_for_qty_limits`	boolean	Optional. Whether to combine SKUs for CSP quantity limits.

Request example

{
  "design_id": 456,
  "items": [
    {
      "sku": "ITEM-001",
      "quantity": 15
    }
  ],
  "combine_skus_for_qty_limits": true
}

Success response

{
  "success": true,
  "message": "Quantities updated successfully",
  "data": {
    "design_id": 456,
    "items": [
      {
        "sku": "ITEM-001",
        "quantity": 15
      }
    ]
  }
}

POST

/api/design/duplicate

Duplicate original designs through CSP and store new design records locally.

Authorization

Header	Required
`X-Store-Key`	Yes
`X-Store-Hash`	Yes

Parameters

Parameter	Type	Description
`designs`	array	Required. List of designs to duplicate.
`designs.*.design_id`	integer	Required. Original design ID.
`designs.*.skus_and_qtys`	array	Required. SKU and quantity list for duplication.
`designs..skus_and_qtys..sku`	string	Required. Item SKU.
`designs..skus_and_qtys..quantity`	integer	Required. Item quantity.
`reuse_decorator`	boolean	Optional. Reuse the decorator during duplication.

Request example

{
  "designs": [
    {
      "design_id": 456,
      "skus_and_qtys": [
        { "sku": "ITEM-001", "quantity": 10 }
      ]
    }
  ],
  "reuse_decorator": false
}

Success response

{
  "success": true,
  "message": "Design(s) duplicated successfully",
  "data": {
    "designs": [
      {
        "old_design_id": 456,
        "new_design_id": 457,
        "fees": {
          "art_cost": 25.50,
          "decorator_cost": 10.00,
          "setup_cost": 5.00
        },
        "items": [
          {
            "sku": "ITEM-001",
            "quantity": 10
          }
        ]
      }
    ]
  }
}

GET

/api/design/proof/{design_id}

Fetch the proof URL for a design using a specific order ID.

Authorization

Header	Required
`X-Store-Key`	Yes
`X-Store-Hash`	Yes

Parameters

Parameter	Type	Description
`design_id`	path integer	Required. Design ID in the URL.
`order_id`	query integer	Required. Order ID to retrieve the proof.

Example request

GET /api/design/proof/456?order_id=1001

Success response

{
  "success": true,
  "data": {
    "design_id": 456,
    "order_id": "1001",
    "proof_url": "https://example.com/proof.pdf"
  }
}

GET

/api/design/files/{design_id}

Retrieve ZIP URL and legacy metadata for design files.

Authorization

Header	Required
`X-Store-Key`	Yes
`X-Store-Hash`	Yes

Parameters

Parameter	Type	Description
`design_id`	path integer	Required. Design ID in the URL.

Example request

GET /api/design/files/456

Success response

{
  "success": true,
  "data": {
    "design_id": 456,
    "zip_url": "https://example.com/design-456-files.zip",
    "is_legacy": false
  }
}

POST

/api/design/print-file

Request creation of a print-ready design file.

Authorization

Header	Required
`X-Store-Key`	Yes
`X-Store-Hash`	Yes

Parameters

Parameter	Type	Description
`design_id`	integer	Required. Design ID.
`job_id`	integer	Optional. CSP job ID if available.

Request example

{
  "design_id": 456,
  "job_id": 1001
}

Success response

{
  "success": true,
  "data": {
    "design_id": 456,
    "print_file_url": "https://example.com/print-file.pdf"
  }
}

POST

/api/design/sheet-label

Generate a sheet label for a design using a template value.

Authorization

Header	Required
`X-Store-Key`	Yes
`X-Store-Hash`	Yes

Parameters

Parameter	Type	Description
`design_id`	integer	Required. Design ID.
`template_value`	integer	Required. Template value 1-6.

Request example

{
  "design_id": 456,
  "template_value": 2
}

Success response

{
  "success": true,
  "data": {
    "design_id": 456,
    "template_info": {
      "label_url": "https://example.com/label.pdf"
    }
  }
}

POST

/api/design/update-po

Update the purchase order number for a design in CSP.

Authorization

Header	Required
`X-Store-Key`	Yes
`X-Store-Hash`	Yes

Parameters

Parameter	Type	Description
`design_id`	integer	Required. Design ID.
`po_number`	string	Required. Purchase order number.

Request example

{
  "design_id": 456,
  "po_number": "PO-9999"
}

Success response

{
  "success": true,
  "message": "PO number updated successfully"
}

POST

/api/order/place

Place an order for one or more designs with customer details.

Authorization

Header	Required
`X-Store-Key`	Yes
`X-Store-Hash`	Yes

Parameters

Parameter	Type	Description
`order_number`	string	Required. Order identifier.
`design_ids`	array<integer>	Required. Design IDs included in the order.
`customer.first_name`	string	Required. Customer first name.
`customer.last_name`	string	Required. Customer last name.
`customer.address1`	string	Required. Street address line 1.
`customer.address2`	string	Optional. Street address line 2.
`customer.city`	string	Required. City.
`customer.region`	string	Required. Region or state.
`customer.postal_code`	string	Required. Postal code.
`customer.country`	string	Required. Country code or name.
`customer.email`	email	Required. Contact email.
`customer.phone`	string	Optional. Contact phone number.
`order_total`	numeric	Required. Order total value.
`additional_info`	array	Optional. Extra metadata key/value pairs.
`additional_info.*.key`	string	Required when `additional_info` is provided.
`additional_info.*.value`	string	Required when `additional_info` is provided.

Request example

{
  "order_number": "ORDER-1001",
  "design_ids": [456, 457],
  "customer": {
    "first_name": "Jane",
    "last_name": "Doe",
    "address1": "123 Main St",
    "address2": "Suite 4",
    "city": "City",
    "region": "State",
    "postal_code": "12345",
    "country": "US",
    "email": "[email protected]",
    "phone": "555-1234"
  },
  "order_total": 150.00,
  "additional_info": [
    { "key": "SalesPerson", "value": "Alice" }
  ]
}

Success response

{
  "success": true,
  "message": "Order placed successfully",
  "data": {
    "job_id": "JOB-999",
    "design_ids": [456, 457],
    "csp_response": {
      "JobID": "JOB-999",
      "OrderStatus": "Success"
    }
  }
}

Notes

Important: Every API request requires both X-Store-Key and X-Store-Hash headers.

Use GET /api/design/details/{design_id}?sync=true to refresh local design data from CSP.