API Reference

Base URL

All API requests are made to:

https://api.firmly.work

Authentication

All endpoints require authentication via the x-firmly-authorization header:

curl -X GET https://api.firmly.work/api/v2/domains/staging.luma.gift/cart \
  -H "x-firmly-authorization: YOUR_ACCESS_TOKEN"

See Authentication for obtaining access tokens.

Request Format

Content-Type: application/json for all POST/PUT requests
Accept: application/json
Domain Parameter: Most endpoints require a merchant domain (e.g., staging.luma.gift)

Response Format

All responses return JSON with consistent structure:

Success Response

{
  "cart_id": "cart_123",
  "line_items": [...],
  "total": { "value": 99.99, "currency": "USD" }
}

Error Response

{
  "code": 400,
  "error": "ErrorCode",
  "description": "Human-readable error message"
}

HTTP Status Codes

Status	Description
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing token
404	Not Found - Resource doesn’t exist
409	Conflict - Business logic error
422	Unprocessable Entity - Validation failed
500	Internal Server Error

API Versioning

Firmly provides two API versions:

v1 - Simple Cart API endpoints
v2 - Full Cart API endpoints

Version is specified in the URL path: /api/v1/ or /api/v2/

Available APIs

Authentication

Token generation and session management

Catalog

Browse products and retrieve variant information

Session

Manage device sessions and preferences

Cart Management

Core cart operations for Full Cart API

Simple Cart

Streamlined cart operations for standard shipping

Promotions

Apply and manage promotional codes

Shipment Configuration

Configure fulfillment and shipping methods

Addon Management

Manage warranties and protection plans

Checkout

Complete the purchase flow

Payment

Secure payment processing

Common Headers

Required Headers

Header	Description	Example
`x-firmly-authorization`	Access token from authentication	`Bearer eyJhbGc...`

Optional Headers

Header	Description	Example
`x-firmly-request-id`	Unique request identifier for tracking	`req_123abc`

Rate Limits

Contact support for current rate limit information.

Support

API Status: status.firmly.work
Support: support@firmly.work

Need Implementation Help?

Implementation Guides

Step-by-step guides for building with Firmly APIs

Home

Core Concepts

Implementation Guides

Ask Agent SDK

firmly Connect

Resources

API Reference

Base URL

Authentication

Request Format

Response Format

Success Response

Error Response

HTTP Status Codes

API Versioning

Available APIs

Authentication

Catalog

Session

Cart Management

Simple Cart

Promotions

Shipment Configuration

Addon Management

Checkout

Payment

Common Headers

Required Headers

Optional Headers

Rate Limits

Support

Need Implementation Help?

Implementation Guides

​Base URL

​Authentication

​Request Format

​Response Format

​Success Response

​Error Response

​HTTP Status Codes

​API Versioning

​Available APIs

Authentication

Catalog

Session

Cart Management

Simple Cart

Promotions

Shipment Configuration

Addon Management

Checkout

Payment

​Common Headers

​Required Headers

​Optional Headers

​Rate Limits

​Support

​Need Implementation Help?

Implementation Guides

Base URL

Authentication

Request Format

Response Format

Success Response

Error Response

HTTP Status Codes

API Versioning

Available APIs

Common Headers

Required Headers

Optional Headers

Rate Limits

Support

Need Implementation Help?