> ## Documentation Index
> Fetch the complete documentation index at: https://firespark.cloud/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Get customer
> Retrieve the authenticated customer's profile.
Returns the customer record for the given external `id`. The access token only grants access to the customer linked to the original OIDC `sub` claim, so `id` must match the token's customer id.
Requires a Fire spark access token obtained through [token
exchange](/docs/storefront-api/oauth/exchange/post).
## Path parameters
| Parameter | Required | Description |
| --------- | -------- | ----------------------------------------------------------------- |
| `id` | Yes | External customer identifier. Must match the token's customer id. |
## Request
```bash theme={null}
curl "https://firespark.cloud/api/storefront/v1/customers/auth0|abc123" \
-H "Authorization: Bearer ACCESS_TOKEN"
```
## Response
The response wraps a single customer object in `data`. Storefront responses omit internal fields such as `birthday`.
```json Success theme={null}
{
"data": {
"uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"organization_id": "11111111-1111-1111-1111-111111111111",
"merchant_id": "22222222-2222-2222-2222-222222222222",
"id": "auth0|abc123",
"name": "John Smith",
"email": "john@example.com",
"status": "ACTIVE",
"is_anonymous": false,
"email_verified": false,
"phone_verified": false,
"phone": "+593991234567",
"registration_date": "2026-01-15T10:30:00Z",
"gender": "MALE",
"dob": "1990-05-20T00:00:00Z",
"document_type": "CI",
"document_number": "1712345678",
"country": "EC",
"delivery_addresses": [
{
"alias": "Home",
"address_line1": "Av. Amazonas 123",
"address_line2": "Apt 4B",
"city": "Quito",
"state": "Pichincha",
"zip": "170150",
"country": "EC",
"reference": "Near the park",
"latitude": -0.1807,
"longitude": -78.4678,
"instructions": "Ring the bell",
"preferred": true,
"metadata": null
}
],
"billing_profiles": [
{
"alias": "Personal",
"type": "INDIVIDUAL",
"legal_name": "John Smith",
"address_line1": "Av. Amazonas 123",
"city": "Quito",
"country": "EC",
"tax_id": "1712345678",
"tax_id_type": "CI",
"preferred": true,
"metadata": null
}
],
"devices": [
{
"id": "iphone-15-pro",
"os": "IOS",
"fcm_token": "fcm-token-abc123",
"created_at": "2026-01-10T08:00:00Z",
"updated_at": "2026-01-15T10:30:00Z"
}
],
"consent": {
"email": true,
"push_notifications": true,
"in_app_messages": false,
"phone_calls": false,
"sms": false,
"whatsapp": false
},
"metadata": {}
}
}
```
## Customer fields
| Field | Required | Type | Description |
| -------------------- | -------- | ------------------ | ----------------------------------------------- |
| `uid` | Yes | uuid | Fire spark internal identifier. |
| `organization_id` | Yes | uuid | Fire spark organization identifier. |
| `merchant_id` | Yes | uuid | Fire spark merchant identifier. |
| `id` | Yes | string | Your external customer identifier. |
| `name` | Yes | string | Full name. |
| `email` | Yes | string \ \| null | Email address. Null for anonymous customers. |
| `status` | Yes | string | `ACTIVE` or `INACTIVE`. |
| `is_anonymous` | Yes | boolean | Whether this is a guest customer. |
| `email_verified` | Yes | boolean | Whether the email address is verified. |
| `phone_verified` | Yes | boolean | Whether the phone number is verified. |
| `gender` | No | string \ \| null | `MALE`, `FEMALE`, or `OTHER`. |
| `dob` | No | datetime \ \| null | Date of birth (ISO 8601 with offset). |
| `document_type` | No | string \ \| null | Government ID type. |
| `document_number` | No | string \ \| null | Government ID number. |
| `country` | No | string \ \| null | Customer country. |
| `phone` | Yes | string \ \| null | Phone number in international format. |
| `registration_date` | Yes | datetime | When the customer was registered. |
| `delivery_addresses` | No | array | Saved delivery addresses (max 10). |
| `billing_profiles` | No | array | Billing profiles with tax identifiers (max 10). |
| `devices` | No | array | Push devices (max 10). |
| `consent` | No | object \ \| null | Channel consent preferences. |
| `metadata` | No | object \ \| null | Custom metadata (max 1MB serialized). |
### Delivery address
| Field | Required | Type | Description |
| --------------- | -------- | ---------------- | --------------------------------------------------------------------------- |
| `alias` | Yes | string | Label such as "Home" or "Office". |
| `address_line1` | Yes | string | Primary street address. |
| `address_line2` | No | string | Apartment, suite, or floor. |
| `city` | No | string | City. |
| `state` | No | string | State or province. |
| `zip` | No | string | Postal code. |
| `country` | No | string | Country. |
| `reference` | No | string | Landmark or reference point. |
| `latitude` | No | number | Latitude between -90 and 90. |
| `longitude` | No | number | Longitude between -180 and 180. |
| `instructions` | No | string | Delivery instructions. |
| `preferred` | No | boolean | Default address. Defaults to `false`. At most one address may be preferred. |
| `metadata` | No | object \ \| null | Custom metadata for this address. |
### Billing profile
| Field | Required | Type | Description |
| --------------- | -------- | ---------------- | ------------------------------------------------------------------------------------------------------------------ |
| `alias` | Yes | string | Label such as "Personal" or "Business". |
| `type` | Yes | string | `INDIVIDUAL` or `BUSINESS`. |
| `legal_name` | Yes | string | Legal name for invoicing. |
| `address_line1` | Yes | string | Primary billing address. |
| `address_line2` | No | string | Additional address line. |
| `city` | No | string | City. |
| `state` | No | string | State or province. |
| `zip` | No | string | Postal code. |
| `country` | No | string | Country. |
| `tax_id` | Yes | string | Tax identifier value. |
| `tax_id_type` | Yes | string | One of `VAT`, `EIN`, `SSN`, `TIN`, `NIF`, `CUIT`, `RUT`, `NIT`, `RCN`, `RUC`, `CI`, `DNI`, `PASSPORT`, or `OTHER`. |
| `preferred` | No | boolean | Default profile. Defaults to `false`. At most one profile may be preferred. |
| `metadata` | No | object \ \| null | Custom metadata for this profile. |
### Device
| Field | Required | Type | Description |
| ------------ | -------- | -------- | --------------------------------- |
| `id` | Yes | string | External device identifier. |
| `os` | Yes | string | `IOS`, `ANDROID`, or `WEB`. |
| `fcm_token` | Yes | string | Firebase Cloud Messaging token. |
| `created_at` | Yes | datetime | When the device was registered. |
| `updated_at` | Yes | datetime | When the device was last updated. |
### Consent
| Field | Type | Default | Description |
| -------------------- | ------- | ------- | ------------------ |
| `email` | boolean | `false` | Email marketing |
| `push_notifications` | boolean | `false` | Push notifications |
| `in_app_messages` | boolean | `false` | In-app messages |
| `phone_calls` | boolean | `false` | Phone calls |
| `sms` | boolean | `false` | SMS messages |
| `whatsapp` | boolean | `false` | WhatsApp messages |
## Error responses
| Status | Description |
| ------ | ------------------------------------------------ |
| `401` | Missing or invalid access token. |
| `403` | The `id` does not match the token's customer id. |
| `404` | No customer found with the given `id`. |
## OpenAPI
````yaml GET /customers/{id}
openapi: 3.0.1
info:
title: Fire spark Storefront API
description: Customer-facing channel endpoints for Fire spark.
version: 1.0.0
servers:
- url: https://firespark.cloud/api/storefront/v1
security:
- bearerAuth: []
paths:
/customers/{id}:
get:
summary: Get customer
description: Get a customer by id
parameters:
- in: path
name: id
description: The customer unique identifier in your system
required: true
schema:
type: string
responses:
'200':
description: Ok
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/StoreFrontCustomer'
'404':
description: Customer not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
StoreFrontCustomer:
type: object
description: >-
Customer profile returned by Storefront API endpoints. Omits internal
fields such as `birthday`.
required:
- uid
- id
- name
- status
- registration_date
- organization_id
- merchant_id
properties:
uid:
type: string
format: uuid
description: Fire spark internal customer identifier
organization_id:
type: string
format: uuid
description: Fire spark organization identifier
merchant_id:
type: string
format: uuid
description: Fire spark merchant identifier
id:
type: string
description: Your customer unique identifier
status:
description: The status of the customer
type: string
enum:
- ACTIVE
- INACTIVE
is_anonymous:
description: Whether the customer is anonymous
type: boolean
default: false
name:
description: The full name of the customer
type: string
example: John Smith
email:
description: The email of the customer
type: string
format: email
nullable: true
email_verified:
description: Whether the customer's email is verified
type: boolean
default: false
gender:
description: The gender of the customer
type: string
nullable: true
enum:
- MALE
- FEMALE
- OTHER
dob:
description: The date of birth of the customer
type: string
nullable: true
format: date-time
document_type:
description: The document type of the customer
type: string
nullable: true
document_number:
description: The document number of the customer
type: string
nullable: true
maxLength: 50
country:
description: The country of the customer
type: string
nullable: true
maxLength: 100
phone:
description: The customer's phone number in international format
type: string
nullable: true
example: +593 99 123 4567
phone_verified:
description: Whether the customer's phone number is verified
type: boolean
default: false
registration_date:
description: The date when the customer was registered
type: string
format: date-time
devices:
type: array
maxItems: 10
description: Customer devices for push notifications
items:
$ref: '#/components/schemas/CustomerDevice'
delivery_addresses:
type: array
maxItems: 10
items:
$ref: '#/components/schemas/DeliveryAddress'
billing_profiles:
type: array
maxItems: 10
items:
$ref: '#/components/schemas/BillingProfile'
consent:
$ref: '#/components/schemas/Consent'
description: The customer's consent preferences
nullable: true
metadata:
description: Custom metadata for the customer. Must serialize to 1MB or less.
type: object
nullable: true
additionalProperties: true
Error:
required:
- error
- details
type: object
properties:
error:
type: string
details:
type: string
CustomerDevice:
type: object
required:
- id
- os
- fcm_token
- created_at
- updated_at
properties:
id:
type: string
minLength: 1
maxLength: 64
pattern: ^[a-zA-Z0-9_-]+$
description: External device identifier
os:
type: string
enum:
- IOS
- ANDROID
- WEB
description: Device operating system
fcm_token:
type: string
minLength: 1
maxLength: 64
pattern: ^[a-zA-Z0-9_-]+$
description: Firebase Cloud Messaging token
created_at:
type: string
format: date-time
description: When the device was registered
updated_at:
type: string
format: date-time
description: When the device was last updated
DeliveryAddress:
type: object
required:
- alias
- address_line1
properties:
alias:
type: string
maxLength: 100
address_line1:
type: string
maxLength: 100
address_line2:
type: string
maxLength: 100
city:
type: string
maxLength: 100
state:
type: string
maxLength: 100
zip:
type: string
maxLength: 100
country:
type: string
maxLength: 100
reference:
type: string
maxLength: 100
latitude:
type: number
minimum: -90
maximum: 90
longitude:
type: number
minimum: -180
maximum: 180
instructions:
type: string
maxLength: 100
preferred:
type: boolean
default: false
metadata:
description: Custom metadata. Must serialize to 1MB or less.
type: object
nullable: true
additionalProperties: true
BillingProfile:
type: object
required:
- alias
- type
- legal_name
- address_line1
- tax_id
- tax_id_type
properties:
alias:
type: string
maxLength: 100
type:
type: string
enum:
- INDIVIDUAL
- BUSINESS
description: Whether this profile is for an individual or a business
legal_name:
type: string
maxLength: 100
address_line1:
type: string
maxLength: 100
address_line2:
type: string
maxLength: 100
city:
type: string
maxLength: 100
state:
type: string
maxLength: 100
zip:
type: string
maxLength: 100
country:
type: string
maxLength: 100
tax_id:
type: string
minLength: 1
maxLength: 64
pattern: ^[a-zA-Z0-9_-]+$
tax_id_type:
type: string
enum:
- VAT
- EIN
- SSN
- TIN
- NIF
- CUIT
- RUT
- NIT
- RCN
- RUC
- CI
- DNI
- PASSPORT
- OTHER
preferred:
type: boolean
default: false
metadata:
description: Custom metadata. Must serialize to 1MB or less.
type: object
nullable: true
additionalProperties: true
Consent:
type: object
description: >-
Channel-level marketing and messaging consent preferences. Omitted flags
default to false.
properties:
email:
type: boolean
description: Consent for email marketing
default: false
push_notifications:
type: boolean
description: Consent for push notifications
default: false
in_app_messages:
type: boolean
description: Consent for in-app messages
default: false
phone_calls:
type: boolean
description: Consent for phone calls
default: false
sms:
type: boolean
description: Consent for SMS messages
default: false
whatsapp:
type: boolean
description: Consent for WhatsApp messages
default: false
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````