Hydra is now in beta|Get started free|Follow our journey on X.com

Customer Self-Service API
On this page

Customer Self-Service

Self-service endpoints for authenticated storefront customers. These endpoints let customers view and update their profile, change their password, browse order history, and manage shipping addresses.

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

Endpoints

Method Path Auth Description
GET /v1/me Customer JWT Get customer profile
PATCH /v1/me Customer JWT Update profile (name, phone)
POST /v1/me/password Customer JWT Change password
GET /v1/me/orders Customer JWT List order history
GET /v1/me/addresses Customer JWT List addresses
POST /v1/me/addresses Customer JWT Add an address
PATCH /v1/me/addresses/{id} Customer JWT Update an address
DELETE /v1/me/addresses/{id} Customer JWT Delete an address

ℹAuthentication

All /v1/me endpoints require two headers: a publishable API key (X-API-Key: pk_live_*) and a customer access token (Authorization: Bearer <jwt>). The access token is obtained from the Customer Auth endpoints.

Get profile

GET /v1/me

Returns the authenticated customer’s profile including order count and total spent.

Request

curl https://api.hydrajs.dev/v1/me \
  -H "X-API-Key: pk_live_YOUR_KEY" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response 200

{
	"data": {
		"id": "cus_abc123",
		"email": "jane@example.com",
		"first_name": "Jane",
		"last_name": "Smith",
		"phone": "+1-555-0123",
		"locale": null,
		"order_count": 5,
		"total_spent": 24500,
		"tags": ["vip"],
		"metadata": {},
		"active_price_key": null,
		"company": null,
		"status": "active",
		"email_verified": false,
		"created_at": "2026-08-01T10:00:00Z",
		"updated_at": "2026-08-31T12:00:00Z"
	}
}

Update profile

PATCH /v1/me

Updates the authenticated customer’s profile. Customers can change their name, phone, and locale. Email, tags, metadata, status, and price key are merchant-controlled and cannot be changed by the customer.

Request body

Field Type Required Description
first_name string No First name (1-100 chars)
last_name string No Last name (1-100 chars)
phone string|null No Phone number (max 30 chars), or null to clear
locale string|null No Preferred language (BCP 47, max 10 chars, e.g. en, es-419), or null to clear

Request

curl -X PATCH https://api.hydrajs.dev/v1/me \
  -H "X-API-Key: pk_live_YOUR_KEY" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Janet",
    "phone": "+1-555-9999"
  }'

Response 200

{
	"data": {
		"id": "cus_abc123",
		"email": "jane@example.com",
		"first_name": "Janet",
		"last_name": "Smith",
		"phone": "+1-555-9999",
		"locale": "es-419",
		"order_count": 5,
		"total_spent": 24500,
		"tags": ["vip"],
		"metadata": {},
		"active_price_key": null,
		"company": null,
		"status": "active",
		"email_verified": false,
		"created_at": "2026-08-01T10:00:00Z",
		"updated_at": "2026-08-31T14:00:00Z"
	}
}

Change password

POST /v1/me/password

Changes the authenticated customer’s password. Requires the current password. Invalidates all existing sessions and returns new tokens so the customer stays logged in on the current device.

Request body

Field Type Required Description
current_password string Yes Current password
new_password string Yes New password (8-128 chars, must include uppercase, lowercase, and digit)

Request

curl -X POST https://api.hydrajs.dev/v1/me/password \
  -H "X-API-Key: pk_live_YOUR_KEY" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "current_password": "OldPass1",
    "new_password": "NewSecurePass1"
  }'

Response 200

{
	"access_token": "eyJhbGciOiJIUzI1NiIs...",
	"refresh_token": "bmV3IHJlZnJlc2ggdG9r...",
	"expires_in": 3600
}

List order history

GET /v1/me/orders

Returns the authenticated customer’s order history, cursor-paginated. Only orders belonging to the authenticated customer are returned.

Query parameters

Parameter Type Default Description
limit integer 25 Results per page (1-100)
cursor string - Pagination cursor from a previous response
sort string created_at Sort field (only created_at is supported)
order string desc Sort direction: asc, desc

Request

curl "https://api.hydrajs.dev/v1/me/orders?limit=10" \
  -H "X-API-Key: pk_live_YOUR_KEY" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response 200

{
	"data": [
		{
			"id": "ord_xyz789",
			"order_number": 1042,
			"status": "fulfilled",
			"total": 4500,
			"currency": "usd",
			"created_at": "2026-08-20T15:00:00Z",
			"updated_at": "2026-08-22T10:00:00Z"
		}
	],
	"pagination": {
		"cursor": "eyJ0IjoiMjAyNi...",
		"has_more": false,
		"total": 5
	}
}

List addresses

GET /v1/me/addresses

Returns the authenticated customer’s addresses.

Request

curl https://api.hydrajs.dev/v1/me/addresses \
  -H "X-API-Key: pk_live_YOUR_KEY" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response 200

{
	"data": [
		{
			"id": "addr_abc123",
			"first_name": "Jane",
			"last_name": "Smith",
			"line1": "123 Main St",
			"line2": "Apt 4",
			"city": "San Francisco",
			"state": "CA",
			"postal_code": "94105",
			"country": "US",
			"phone": "+1-555-0123",
			"is_default": true
		}
	]
}

Add an address

POST /v1/me/addresses

Creates a new address for the authenticated customer.

Request body

Field Type Required Description
first_name string Yes First name
last_name string Yes Last name
line1 string Yes Address line 1
line2 string No Address line 2
city string Yes City
state string No State/province
postal_code string Yes Postal/ZIP code
country string Yes ISO 3166-1 alpha-2 country code
phone string No Phone number
is_default boolean No Set as default address

Request

curl -X POST https://api.hydrajs.dev/v1/me/addresses \
  -H "X-API-Key: pk_live_YOUR_KEY" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Smith",
    "line1": "456 Oak Ave",
    "city": "Oakland",
    "state": "CA",
    "postal_code": "94612",
    "country": "US"
  }'

Response 201

{
	"data": {
		"id": "addr_def456",
		"first_name": "Jane",
		"last_name": "Smith",
		"line1": "456 Oak Ave",
		"line2": null,
		"city": "Oakland",
		"state": "CA",
		"postal_code": "94612",
		"country": "US",
		"phone": null,
		"is_default": false
	}
}

Update an address

PATCH /v1/me/addresses/{id}

Updates an existing address for the authenticated customer.

Path parameters

Parameter Type Description
id string Address ID

Request body

Same fields as Add an address, all optional.

Request

curl -X PATCH https://api.hydrajs.dev/v1/me/addresses/addr_def456 \
  -H "X-API-Key: pk_live_YOUR_KEY" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "is_default": true
  }'

Response 200

{
	"data": {
		"id": "addr_def456",
		"first_name": "Jane",
		"last_name": "Smith",
		"line1": "456 Oak Ave",
		"line2": null,
		"city": "Oakland",
		"state": "CA",
		"postal_code": "94612",
		"country": "US",
		"phone": null,
		"is_default": true
	}
}

Delete an address

DELETE /v1/me/addresses/{id}

Deletes an address for the authenticated customer.

Path parameters

Parameter Type Description
id string Address ID

Request

curl -X DELETE https://api.hydrajs.dev/v1/me/addresses/addr_def456 \
  -H "X-API-Key: pk_live_YOUR_KEY" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response 204

No body.