Skip to main content

​
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

StatusDescription
200Success
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing token
404Not Found - Resource doesn’t exist
409Conflict - Business logic error
422Unprocessable Entity - Validation failed
500Internal 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

HeaderDescriptionExample
x-firmly-authorizationAccess token from authenticationBearer eyJhbGc...

​
Optional Headers

HeaderDescriptionExample
x-firmly-request-idUnique request identifier for trackingreq_123abc

​
Rate Limits

Contact support for current rate limit information.

​
Support

​
Need Implementation Help?

Implementation Guides

Step-by-step guides for building with Firmly APIs