> ## 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. # Register customer > Create a customer record for the authenticated user after token exchange. Creates a customer in Fire spark for the user identified by the access token. Call this endpoint after [token exchange](/docs/storefront-api/oauth/exchange/post) 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](/docs/storefront-api/oauth/exchange/post). ## 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](/docs/storefront-api/customers/\[id]/patch) 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 | Channel consent preferences. Each omitted flag defaults to `false`. | | `metadata` | No | Custom key-value metadata. Must serialize to 1MB or less. | \* Required for non-anonymous customers. ### 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 | ### 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 ```bash theme={null} 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": { "email": true, "push_notifications": true, "in_app_messages": false, "phone_calls": false, "sms": false, "whatsapp": false }, "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](/docs/storefront-api/customers/\[id]/get). ## 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. ```bash theme={null} 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. | ## OpenAPI ````yaml POST /customers 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: post: summary: Register customer description: >- Register a customer. For anonymous customers, only the `id` and `is_anonymous: true` are required. For regular customers, `id`, `name`, and `email` are required. `registration_date` is optional and defaults to the current time. Anonymous customers can later be identified using the `/customers/{id}/identify/anonymous` endpoint. requestBody: content: application/json: schema: $ref: '#/components/schemas/CustomerInsert' responses: '201': description: Customer created content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/StoreFrontCustomer' '422': description: Customer already exists content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: CustomerInsert: type: object required: - id description: >- Schema for registering a new customer. For anonymous customers, only `id` and `is_anonymous: true` are required. For regular customers, `id`, `name`, and `email` are required. `registration_date` is optional and defaults to the current time. properties: id: type: string description: >- Your customer unique identifier. Must match the `sub` claim from the customer's OIDC ID token. is_anonymous: type: boolean description: >- Set to true to create an anonymous customer. When true, name and email are not required. default: false name: description: The full name of the customer. Required unless is_anonymous is true. type: string example: John Smith email: description: The email of the customer. Required unless is_anonymous is true. type: string format: email status: description: The status of the customer type: string enum: - ACTIVE - INACTIVE default: ACTIVE 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 registration_date: description: >- The date when the customer was registered. Defaults to the current time when omitted. type: string format: date-time devices: type: array description: >- Optional device payloads on registration. Use PATCH /customers/{id} with a `devices` array to manage structured push devices after registration. items: type: object additionalProperties: true 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 additionalProperties: true 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 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 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 securitySchemes: bearerAuth: type: http scheme: bearer ````