Store

The Store resource represents your project’s global configuration - name, currency settings, allowed origins, and pricing structure. Every API key is scoped to a single store, so there is no store ID parameter; the authenticated key determines which store you are operating on.

Base URL: https://api.hydrajs.dev

Endpoints

Method	Path	Auth	Description
GET	/v1/store	Publishable	Get store configuration
PATCH	/v1/store	Secret	Update store configuration
GET	/v1/store/domain/record	Secret	Get expected DNS verification record
POST	/v1/store/domain/verify	Secret	Verify domain ownership via DNS
GET	/v1/store/price-keys	Secret	List price keys
POST	/v1/store/price-keys	Secret	Create a price key
PATCH	/v1/store/price-keys/{slug}	Secret	Update or archive a price key

---

Get store configuration

GET /v1/store

Returns the store’s current configuration. Publishable keys can read store settings - useful for storefronts that need the store name, currency, or enabled extensions.

Query parameters

Parameter	Type	Description
fields	string	Comma-separated fields to return

Request

curl https://api.hydrajs.dev/v1/store \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

Response 200

{
	"data": {
		"id": "store_abc123",
		"name": "Acme Store",
		"slug": "acme-store",
		"domain": "shop.acme.com",
		"domain_verified": true,
		"currency": "USD",
		"enabled_currencies": ["USD", "EUR", "GBP"],
		"currency_conversion_margin": 1.5,
		"currency_rounding": "up",
		"timezone": "America/New_York",
		"plan": "pro",
		"tax_calculation": "disabled",
		"tax_inclusive": false,
		"brand_logo_url": null,
		"brand_primary_color": "#2563eb",
		"brand_secondary_color": null,
		"brand_tertiary_color": null,
		"brand_accent_color": null,
		"enabled_extensions": ["subtitle", "qty_step"],
		"pricing_config": {
			"next_key_index": 3,
			"price_keys": [
				{
					"key": "price_key_1",
					"slug": "wholesale",
					"label": "Wholesale",
					"archived": false,
					"created_at": "2026-03-01T12:00:00Z"
				}
			]
		},
		"created_at": "2026-01-10T08:00:00Z",
		"updated_at": "2026-08-15T16:45:00Z"
	}
}

---

Update store configuration

PATCH /v1/store

Partially updates the store’s configuration. Send only the fields you want to change. Returns the full updated store object.

Request body

Field	Type	Required	Description
name	string	No	Store name (1–200 chars)
domain	string	No	Custom domain (max 253 chars)
currency	string	No	Base currency - 3-letter ISO code (e.g. USD)
enabled_currencies	string[]	No	List of enabled currency codes (max 20). Must include the base currency
currency_conversion_margin	number	No	Margin percentage applied to currency conversions (0–25)
currency_rounding	string	No	Rounding mode for converted prices: none, up, down
timezone	string	No	IANA timezone string (max 100 chars)
allowed_origins	string[]	No	CORS allowed origins. Use ["*"] to allow all
enabled_extensions	string[]	No	Feature extensions to enable (max 20, each max 50 chars)
tax_calculation	string	No	Tax mode: disabled, automatic, manual
tax_inclusive	boolean	No	Whether product prices include tax
brand_logo_url	string | null	No	HTTPS URL to merchant logo (max 2048 chars). Set to null to remove
brand_primary_color	string | null	No	Primary brand color as 6-digit hex (e.g. #2563eb). Used for CTA buttons and links
brand_secondary_color	string | null	No	Secondary brand color as 6-digit hex (e.g. #475569). Used for borders and dividers
brand_tertiary_color	string | null	No	Tertiary brand color as 6-digit hex (e.g. #f1f5f9). Used for badges and callout backgrounds
brand_accent_color	string | null	No	Accent color as 6-digit hex (e.g. #16a34a). Used for focus rings and hover states

Request

curl -X PATCH https://api.hydrajs.dev/v1/store \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Store",
    "currency": "USD",
    "enabled_currencies": ["USD", "EUR", "GBP"],
    "currency_conversion_margin": 1.5,
    "currency_rounding": "up"
  }'

Response 200

Returns the full updated store object (same shape as Get store configuration).

---

Get domain verification record

GET /v1/store/domain/record

Returns the expected DNS TXT record for domain verification without performing a DNS lookup. Use this to display the record the merchant needs to add at their DNS provider before clicking “Verify”.

The store must have a domain set, otherwise this returns a 400 error.

Request

curl https://api.hydrajs.dev/v1/store/domain/record \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
	"data": {
		"domain": "shop.acme.com",
		"record": {
			"type": "TXT",
			"name": "_hydra-verification.shop.acme.com",
			"value": "hydra-verification=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
		}
	}
}

---

Verify domain ownership

POST /v1/store/domain/verify

Checks the DNS TXT record for the store’s domain via DNS-over-HTTPS. If the expected _hydra-verification TXT record is found, the store’s domain_verified is set to true. No request body required.

The store must have a domain set, otherwise this returns a 400 error.

Request

curl -X POST https://api.hydrajs.dev/v1/store/domain/verify \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
	"data": {
		"domain": "shop.acme.com",
		"verified": true,
		"record": {
			"type": "TXT",
			"name": "_hydra-verification.shop.acme.com",
			"value": "hydra-verification=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
		}
	}
}

The verified field reflects the result of the DNS check. The record object is always included so the caller knows exactly what TXT record to add if verification failed.

---

List price keys

GET /v1/store/price-keys

Returns all price keys configured for the store, including archived ones. Price keys enable multi-currency or multi-tier pricing on variants (e.g. wholesale, VIP, regional pricing).

Request

curl https://api.hydrajs.dev/v1/store/price-keys \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
	"data": [
		{
			"key": "price_key_1",
			"slug": "wholesale",
			"label": "Wholesale",
			"archived": false,
			"created_at": "2026-03-01T12:00:00Z"
		},
		{
			"key": "price_key_2",
			"slug": "vip",
			"label": "VIP Pricing",
			"archived": false,
			"created_at": "2026-05-20T09:15:00Z"
		}
	]
}

---

Create a price key

POST /v1/store/price-keys

Creates a new price key. Once created, you can set per-key prices on individual variants.

Request body

Field	Type	Required	Description
label	string	Yes	Human-readable label (1–100 chars)
slug	string	No	URL-safe identifier (1–50 chars). Auto-generated from label if omitted

Request

curl -X POST https://api.hydrajs.dev/v1/store/price-keys \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Wholesale",
    "slug": "wholesale"
  }'

Response 201

{
	"data": {
		"key": "price_key_1",
		"slug": "wholesale",
		"label": "Wholesale",
		"archived": false,
		"created_at": "2026-08-17T10:00:00Z"
	}
}

---

Update a price key

PATCH /v1/store/price-keys/{slug}

Updates a price key’s label, slug, or archived status. Returns the updated price key.

Request body

Field	Type	Required	Description
label	string	No	Updated label (1–100 chars)
slug	string	No	Updated slug (1–50 chars). Must be unique
archived	boolean	No	Set to true to archive, false to restore

Request

curl -X PATCH https://api.hydrajs.dev/v1/store/price-keys/wholesale \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Wholesale (B2B)",
    "archived": false
  }'

Response 200

{
	"data": {
		"key": "price_key_1",
		"slug": "wholesale",
		"label": "Wholesale (B2B)",
		"archived": false,
		"created_at": "2026-03-01T12:00:00Z"
	}
}

---

The store object

Field	Type	Description
id	string	Unique ID (prefix: store_)
name	string	Store name
slug	string	URL-safe identifier
domain	string | null	Custom domain
domain_verified	boolean	Whether domain ownership is verified via DNS TXT record
currency	string	Base currency (3-letter ISO code)
enabled_currencies	string[]	List of enabled currency codes
currency_conversion_margin	number	Margin percentage for conversions (0–25)
currency_rounding	string	Rounding mode: none, up, down
timezone	string	IANA timezone
plan	string	Current plan: free, pro
enabled_extensions	string[]	Active feature extensions
tax_calculation	string	Tax mode: disabled, automatic, manual
tax_inclusive	boolean	Whether product prices include tax
brand_logo_url	string | null	HTTPS URL to merchant logo
brand_primary_color	string | null	Primary brand color (6-digit hex)
brand_secondary_color	string | null	Secondary brand color (6-digit hex)
brand_tertiary_color	string | null	Tertiary brand color (6-digit hex)
brand_accent_color	string | null	Accent brand color (6-digit hex)
pricing_config	object	Price key configuration (see below)
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp

The price key object

Field	Type	Description
key	string	Internal key identifier (e.g. price_key_1)
slug	string	URL-safe slug (unique within the store)
label	string	Human-readable label
archived	boolean	Whether the key is archived
created_at	string	ISO 8601 timestamp