Register customer

Creates a customer in Fire spark for the user identified by the access token. Call this endpoint after token exchange when the customer signs in for the first time. The id in the request body must match the sub claim from the customer’s OIDC ID token (the same value bound to the access token).

Requires a Fire spark access token obtained through token exchange.

Request body

Field	Required	Description
`id`	Yes	External customer identifier. Must match the token’s customer id.
`is_anonymous`	No	Set to `true` for guest checkout. Defaults to `false`.
`name`	Yes*	Full name. Not required when `is_anonymous` is `true`.
`email`	Yes*	Email address. Not required when `is_anonymous` is `true`.
`status`	No	`ACTIVE` or `INACTIVE`. Defaults to `ACTIVE`.
`gender`	No	`MALE`, `FEMALE`, or `OTHER`.
`dob`	No	Date of birth (ISO 8601 with offset).
`document_type`	No	Government ID type.
`document_number`	No	Government ID number.
`country`	No	Customer country.
`phone`	No	Phone number in international format.
`registration_date`	No	When the customer registered in your system. Defaults to the current time.
`devices`	No	Optional device payloads on registration. Use update customer with a `devices` array to manage structured push tokens after registration. Defaults to `[]`.
`delivery_addresses`	No	Up to 10 saved delivery addresses. At most one may have `preferred: true`.
`billing_profiles`	No	Up to 10 billing profiles with tax identifiers. At most one may have `preferred: true`.
`consent`	No	Marketing consent. `marketing` defaults to `false`.
`notification_preferences`	No	Email and push delivery preferences. Omitted flags default to `true`.
`metadata`	No	Custom key-value metadata. Must serialize to 1MB or less.

* Required for non-anonymous customers. Transactional messages only require the matching channel in notification_preferences. Marketing messages also require consent.marketing.

Field	Type	Default	Description
`marketing`	boolean	`false`	Advertising and promotions on any channel

Notification preferences

Field	Type	Default	Description
`email`	boolean	`true`	Receive emails
`push`	boolean	`true`	Receive push notifications
`push_token`	string	—	Push notification token. Must be sent together with `push_token_expires_at`.
`push_token_expires_at`	datetime	—	Required when `push_token` is set. Must not be sent without `push_token`. Must be in the future and at most 180 days from now.

Delivery address

Field	Required	Description
`alias`	Yes	Label such as “Home” or “Office”.
`address_line1`	Yes	Primary street address.
`address_line2`	No	Apartment, suite, or floor.
`city`	No	City.
`state`	No	State or province.
`zip`	No	Postal code.
`country`	No	Country.
`reference`	No	Landmark or reference point.
`latitude`	No	Latitude between -90 and 90.
`longitude`	No	Longitude between -180 and 180.
`instructions`	No	Delivery instructions.
`preferred`	No	Mark as the default address. Defaults to `false`.
`metadata`	No	Custom metadata for this address (`object` or `null`).

Billing profile

Field	Required	Description
`alias`	Yes	Label such as “Personal” or “Business”.
`type`	Yes	`INDIVIDUAL` or `BUSINESS`.
`legal_name`	Yes	Legal name for invoicing.
`address_line1`	Yes	Primary billing address.
`address_line2`	No	Additional address line.
`city`	No	City.
`state`	No	State or province.
`zip`	No	Postal code.
`country`	No	Country.
`tax_id`	Yes	Tax identifier value.
`tax_id_type`	Yes	One of `VAT`, `EIN`, `SSN`, `TIN`, `NIF`, `CUIT`, `RUT`, `NIT`, `RCN`, `RUC`, `CI`, `DNI`, `PASSPORT`, or `OTHER`.
`preferred`	No	Mark as the default profile. Defaults to `false`.
`metadata`	No	Custom metadata for this profile (`object` or `null`).

Request

curl -X POST "https://firespark.cloud/api/storefront/v1/customers" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "auth0|abc123",
    "name": "John Smith",
    "email": "john@example.com",
    "phone": "+593991234567",
    "consent": {
      "marketing": true
    },
    "notification_preferences": {
      "email": true,
      "push": true,
      "push_token": "ExponentPushToken[abc]",
      "push_token_expires_at": "2026-12-15T00:00:00Z"
    },
    "delivery_addresses": [
      {
        "alias": "Home",
        "address_line1": "Av. Amazonas 123",
        "city": "Quito",
        "preferred": true,
        "metadata": null
      }
    ],
    "billing_profiles": [
      {
        "alias": "Personal",
        "type": "INDIVIDUAL",
        "legal_name": "John Smith",
        "address_line1": "Av. Amazonas 123",
        "tax_id": "1712345678",
        "tax_id_type": "CI",
        "preferred": true,
        "metadata": null
      }
    ]
  }'

Response

Returns the created customer in data. The shape matches get customer.

Anonymous customers

For guest checkout, send only id and is_anonymous: true. Fire spark uses the id as the display name when no name is provided.

curl -X POST "https://firespark.cloud/api/storefront/v1/customers" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "guest-7f3a", "is_anonymous": true}'

Error responses

Status	Description
`400`	Invalid request body.
`401`	Missing or invalid access token.
`403`	The `id` does not match the token’s customer id.
`422`	A customer with this `id` already exists.

API Documentation

Endpoints

Guides

Resources

Request body

Notification preferences

Delivery address

Billing profile

Request

Response

Anonymous customers

Error responses

​Request body

​Consent

​Notification preferences

​Delivery address

​Billing profile

​Request

​Response

​Anonymous customers

​Error responses

Request body

Consent

Notification preferences

Delivery address

Billing profile

Request

Response

Anonymous customers

Error responses