Bootic Customers API

openapi: 3.2.0
info:
  title: Bolder API v2 Customers API
  version: '2.0'
  description: '## Getting Started


    The Bolder API provides programmatic access to your Bolder Shop data through a

    hypermedia-driven REST interface.'
  contact:
    name: Bolder API Support
    url: https://www.onbolder.com
servers:
- url: https://api.onbolder.com/v2
  description: Production
security:
- bearerAuth: []
tags:
- name: Customers
  description: Shop customers. Includes customer authentication and password-reset flows.
paths:
  /customer_tags:
    get:
      tags:
      - Customers
      summary: List customer tags
      description: 'Returns customer tags across the account.

        Optionally filter by `shop_id` or `seller_id` query parameter.'
      operationId: listCustomerTags
      parameters:
      - name: shop_id
        in: query
        schema:
          type: integer
        description: Filter by shop ID
      - name: seller_id
        in: query
        schema:
          type: integer
        description: Filter by seller ID
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: per_page
        in: query
        schema:
          type: integer
          default: 50
      responses:
        '200':
          description: Customer tags list
  /shops/{shop_id}/customer_tags:
    parameters:
    - name: shop_id
      in: path
      required: true
      schema:
        type: integer
      example: 1
    get:
      tags:
      - Customers
      summary: List customer tags
      description: Returns all tags currently applied to customers in this shop.
      operationId: listContactTags
      x-codeSamples:
      - lang: Shell
        label: cURL
        source: "curl -s -H \"Authorization: Bearer $BOLDER_TOKEN\" \\\n  \"https://api.onbolder.com/v2/shops/1/customer_tags\"\n"
      responses:
        '200':
          description: Customer tags list
          content:
            application/json:
              example:
                _class:
                - results
                - tags
                _embedded:
                  items:
                  - name: vip
                  - name: newsletter
  /contact_groups:
    get:
      tags:
      - Customers
      summary: List contact groups (flat)
      description: Returns customer groups (segments). Optionally filter by `shop_id` or `seller_id`; without either, returns groups across all of the account's sellers.
      operationId: listContactGroupsFlat
      parameters:
      - name: shop_id
        in: query
        schema:
          type: integer
      - name: seller_id
        in: query
        schema:
          type: integer
      x-codeSamples:
      - lang: Shell
        label: cURL
        source: "curl -s -H \"Authorization: Bearer $BOLDER_TOKEN\" \\\n  \"https://api.onbolder.com/v2/contact_groups?seller_id=5\"\n"
      responses:
        '200':
          description: Contact groups list
          content:
            application/json:
              example:
                _class:
                - results
                - contactGroups
                total_items: 2
                _embedded:
                  items:
                  - id: 1
                    name: VIP Customers
                    customers_count: 42
    post:
      tags:
      - Customers
      summary: Create a contact group (flat)
      description: '`seller_id` is required in the body.'
      operationId: createContactGroupFlat
      x-codeSamples:
      - lang: Shell
        label: cURL
        source: "curl -s -X POST \\\n  -H \"Authorization: Bearer $BOLDER_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"seller_id\":5,\"name\":\"VIP Customers\"}' \\\n  \"https://api.onbolder.com/v2/contact_groups\"\n"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - seller_id
              properties:
                seller_id:
                  type: integer
                name:
                  type: string
                cart_requirements_list_id:
                  type: integer
                price_list_id:
                  type: integer
                allow_local_pickup:
                  type: boolean
                allow_shipping:
                  type: boolean
            example:
              seller_id: 5
              name: VIP Customers
      responses:
        '201':
          description: Contact group created
        '422':
          description: Validation error
  /shops/{shop_id}/customer_groups:
    parameters:
    - name: shop_id
      in: path
      required: true
      schema:
        type: integer
      example: 1
    get:
      tags:
      - Customers
      summary: List contact groups (legacy shop-nested)
      description: Returns customer groups (segments) for the shop.
      operationId: listContactGroups
      x-codeSamples:
      - lang: Shell
        label: cURL
        source: "curl -s -H \"Authorization: Bearer $BOLDER_TOKEN\" \\\n  \"https://api.onbolder.com/v2/shops/1/customer_groups\"\n"
      responses:
        '200':
          description: Contact groups list
          content:
            application/json:
              example:
                _class:
                - results
                - contactGroups
                total_items: 2
                _embedded:
                  items:
                  - id: 1
                    name: VIP Customers
                    customers_count: 42
                    allow_local_pickup: true
                    allow_shipping: true
                    allow_signups: false
    post:
      tags:
      - Customers
      summary: Create a contact group (legacy shop-nested)
      description: Creates a customer group for the shop.
      operationId: createContactGroup
      x-codeSamples:
      - lang: Shell
        label: cURL
        source: "curl -s -X POST \\\n  -H \"Authorization: Bearer $BOLDER_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"VIP Customers\"}' \\\n  \"https://api.onbolder.com/v2/shops/1/customer_groups\"\n"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                cart_requirements_list_id:
                  type: integer
                price_list_id:
                  type: integer
                allow_local_pickup:
                  type: boolean
                allow_shipping:
                  type: boolean
            example:
              name: VIP Customers
      responses:
        '201':
          description: Contact group created
        '422':
          description: Validation error
  /contact_groups/{id}:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: integer
      example: 1
    get:
      tags:
      - Customers
      summary: Get a contact group
      operationId: getContactGroup
      x-codeSamples:
      - lang: Shell
        label: cURL
        source: "curl -s -H \"Authorization: Bearer $BOLDER_TOKEN\" \\\n  \"https://api.onbolder.com/v2/contact_groups/1\"\n"
      responses:
        '200':
          description: Contact group entity
          content:
            application/json:
              example:
                id: 1
                name: VIP Customers
                customers_count: 42
        '403':
          description: Access denied
        '404':
          description: Not found
    put:
      tags:
      - Customers
      summary: Update a contact group
      operationId: updateContactGroup
      x-codeSamples:
      - lang: Shell
        label: cURL
        source: "curl -s -X PUT \\\n  -H \"Authorization: Bearer $BOLDER_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"Premium Customers\"}' \\\n  \"https://api.onbolder.com/v2/contact_groups/1\"\n"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                cart_requirements_list_id:
                  type: integer
                price_list_id:
                  type: integer
                allow_local_pickup:
                  type: boolean
                allow_shipping:
                  type: boolean
            example:
              name: Premium Customers
      responses:
        '200':
          description: Contact group updated
        '403':
          description: Access denied
    delete:
      tags:
      - Customers
      summary: Delete a contact group
      operationId: deleteContactGroup
      responses:
        '204':
          description: Contact group deleted
        '403':
          description: Access denied
  /contact_groups/{id}/contacts:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: integer
      example: 1
    get:
      tags:
      - Customers
      summary: List contacts in a group
      description: Returns all contacts belonging to this contact group.
      operationId: listContactGroupContacts
      x-codeSamples:
      - lang: Shell
        label: cURL
        source: "curl -s -H \"Authorization: Bearer $BOLDER_TOKEN\" \\\n  \"https://api.onbolder.com/v2/contact_groups/1/contacts\"\n"
      responses:
        '200':
          description: Contacts in this group
          content:
            application/json:
              example:
                _class:
                - results
                - customers
                total_items: 42
                _embedded:
                  items:
                  - id: 3001
                    email: jane@example.com
                    name: Jane Smith
  /customers:
    get:
      tags:
      - Customers
      summary: List customers
      description: 'Returns customers for a shop, or for a whole seller across all of its shops.


        `shop_id` and `seller_id` are both optional. If the token covers exactly

        one shop, that shop is auto-resolved and results are scoped to it. If the

        token covers multiple shops belonging to a single seller, omitting both

        params returns customers across all of that seller''s shops. A token

        covering multiple sellers (or a god token) must pass `shop_id` or

        `seller_id` explicitly — there is no "all sellers" search.'
      operationId: listCustomers
      x-codeSamples:
      - lang: Shell
        label: cURL
        source: "# List all customers for a shop\ncurl -s -H \"Authorization: Bearer $BOLDER_TOKEN\" \\\n  \"https://api.onbolder.com/v2/customers?shop_id=1\"\n\n# List customers across all of a seller's shops\ncurl -s -H \"Authorization: Bearer $BOLDER_TOKEN\" \\\n  \"https://api.onbolder.com/v2/customers?seller_id=1\"\n\n# Search by name or email\ncurl -s -H \"Authorization: Bearer $BOLDER_TOKEN\" \\\n  \"https://api.onbolder.com/v2/customers?shop_id=1&q=jane\"\n"
      parameters:
      - name: shop_id
        in: query
        required: false
        schema:
          type: integer
        description: 'ID of the shop whose contacts to list. Optional if the token covers exactly one shop, or if `seller_id` is given instead.

          '
        example: 1
      - name: seller_id
        in: query
        required: false
        schema:
          type: integer
        description: 'ID of the seller whose contacts to list, across all of its shops. Only needed when `shop_id` is omitted and the token covers more than one shop or seller.

          '
        example: 1
      - name: q
        in: query
        schema:
          type: string
        description: Full-text search across name and email.
        example: jane
      - name: customer_status
        in: query
        schema:
          type: string
          enum:
          - public
          - private
          - pending
        description: Filter by customer account status.
        example: private
      - name: tags
        in: query
        schema:
          type: string
        description: Comma-separated tag names.
      - name: opt_in
        in: query
        schema:
          type: boolean
      - name: page
        in: query
        schema:
          type: integer
          default: 1
          minimum: 1
        example: 1
      - name: per_page
        in: query
        schema:
          type: integer
          default: 20
          minimum: 1
          maximum: 200
        example: 20
      - name: created_on_gte
        in: query
        schema:
          type: string
          format: date-time
        description: Contacts created on or after this ISO 8601 timestamp.
        example: '2024-01-01T00:00:00Z'
      - name: created_on_lte
        in: query
        schema:
          type: string
          format: date-time
        description: Contacts created on or before this ISO 8601 timestamp.
        example: '2024-12-31T23:59:59Z'
      - name: sort
        in: query
        schema:
          type: string
          enum:
          - created_on_asc
          - created_on_desc
          - name_asc
          - name_desc
          default: created_on_desc
        description: Sort order for results.
        example: created_on_desc
      responses:
        '200':
          description: Paginated list of contacts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactList'
              example:
                _class:
                - results
                - customers
                total_items: 1
                per_page: 20
                page: 1
                _links:
                  self:
                    href: https://api.onbolder.com/v2/customers?shop_id=1
                  customers:authenticate:
                    href: https://api.onbolder.com/v2/customers/sessions
                    method: post
                  customers:reset_password:
                    href: https://api.onbolder.com/v2/customers/reset_password
                    method: post
                _embedded:
                  items:
                  - id: 3001
                    shop_id: 1
                    email: jane@example.com
                    name: Jane Smith
                    customer_status: private
                    phone_validated: false
                    created_on: '2024-03-10T11:00:00Z'
                    _links:
                      self:
                        href: https://api.onbolder.com/v2/customers/3001
                      orders:
                        href: https://api.onbolder.com/v2/orders?shop_id=1&contact_email=jane@example.com
        '403':
          description: Access denied
        '422':
          description: '`shop_id` or `seller_id` required — the token covers more than one shop and more than one seller (or is a god token), so neither can be auto-resolved.

            '
    post:
      tags:
      - Customers
      summary: Create a customer
      description: If a contact with the given `email` already exists for this shop, it is updated rather than duplicated.
      operationId: createCustomer
      x-codeSamples:
      - lang: Shell
        label: cURL
        source: "curl -s -X POST \\\n  -H \"Authorization: Bearer $BOLDER_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"shop_id\":1,\"email\":\"newcustomer@example.com\",\"name\":\"Jane Smith\"}' \\\n  \"https://api.onbolder.com/v2/customers\"\n"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/ContactInput'
              - type: object
                required:
                - shop_id
                properties:
                  shop_id:
                    type: integer
            example:
              shop_id: 1
              email: newcustomer@example.com
              name: Jane Smith
      responses:
        '201':
          description: Customer created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
              example:
                id: 3001
                shop_id: 1
                email: newcustomer@example.com
                name: Jane Smith
                customer_status: public
                phone_validated: false
                created_on: '2024-06-20T14:00:00Z'
                _links:
                  self:
                    href: https://api.onbolder.com/v2/customers/3001
                  orders:
                    href: https://api.onbolder.com/v2/orders?shop_id=1&contact_email=newcustomer@example.com
        '422':
          description: Validation error
  /customers/{id}:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: integer
    get:
      tags:
      - Customers
      summary: Get a customer
      operationId: getCustomer
      x-codeSamples:
      - lang: Shell
        label: cURL
        source: "curl -s -H \"Authorization: Bearer $BOLDER_TOKEN\" \\\n  \"https://api.onbolder.com/v2/customers/3001\"\n"
      responses:
        '200':
          description: Customer entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
              example:
                id: 3001
                shop_id: 1
                email: jane@example.com
                name: Jane Smith
                customer_status: private
                phone_number: '+15551234567'
                phone_validated: true
                created_on: '2024-03-10T11:00:00Z'
                _links:
                  self:
                    href: https://api.onbolder.com/v2/customers/3001
                  orders:
                    href: https://api.onbolder.com/v2/orders?shop_id=1&contact_email=jane@example.com
                  customers:update:
                    href: https://api.onbolder.com/v2/customers/3001
                    method: put
        '403':
          description: Access denied
        '404':
          description: Customer not found
    put:
      tags:
      - Customers
      summary: Update a customer
      operationId: updateCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactInput'
            example:
              name: Janet Smith-Jones
              phone_number: '+15559876543'
      responses:
        '200':
          description: Customer updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
              example:
                id: 3001
                email: jane@example.com
                name: Janet Smith-Jones
                phone_number: '+15559876543'
                _links:
                  self:
                    href: https://api.onbolder.com/v2/customers/3001
  /customers/{id}/last_ordered_products:
    get:
      tags:
      - Customers
      summary: Get last ordered products
      operationId: getCustomerLastOrderedProducts
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Last ordered products
  /customers/{id}/activations:
    post:
      tags:
      - Customers
      summary: Start contact activation
      operationId: startContactActivation
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '201':
          description: Activation started
  /customers/{id}/phone_validations:
    post:
      tags:
      - Customers
      summary: Start phone validation
      operationId: startPhoneValidation
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '201':
          description: Phone validation started
  /customers/{id}/activation:
    delete:
      tags:
      - Customers
      summary: Demote a contact
      operationId: demoteContact
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: Contact demoted
  /customers/sessions:
    post:
      tags:
      - Customers
      summary: Authenticate a customer
      description: 'Validates email + password credentials for a shop''s customer account.

        Returns the contact entity with a session token on success.

        Requires a Bearer token with `customers.write` scope (the same token used for

        all v2 requests) and `shop_id` in the request body.'
      operationId: authenticateCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - password
              - shop_id
              properties:
                shop_id:
                  type: integer
                  description: ID of the shop the customer belongs to.
                email:
                  type: string
                password:
                  type: string
            example:
              shop_id: 1
              email: jane@example.com
              password: s3cr3tpassword
      responses:
        '200':
          description: Authentication successful
          content:
            application/json:
              example:
                id: 3001
                email: jane@example.com
                name: Jane Smith
                customer_status: private
                token: eyJhbGciOiJIUzI1NiJ9...
                _links:
                  self:
                    href: https://api.onbolder.com/v2/customers/3001
        '422':
          description: Invalid credentials
  /customers/reset_password:
    post:
      tags:
      - Customers
      summary: Request a password reset
      description: 'Sends a password-reset email to the customer''s address.

        Returns 200 even if the email is not found, to avoid user enumeration.

        Use the 422 response only for missing `shop_id`.'
      operationId: resetCustomerPassword
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - shop_id
              properties:
                shop_id:
                  type: integer
                email:
                  type: string
            example:
              shop_id: 1
              email: jane@example.com
      responses:
        '200':
          description: Reset email sent (or silently ignored if not found)
          content:
            application/json:
              example:
                message: If that email is registered, a reset link has been sent.
        '422':
          description: '`shop_id` required'
  /customers/activations/{token}:
    put:
      tags:
      - Customers
      summary: Activate a customer account
      description: 'Completes the customer account activation flow by setting the initial

        password. The `token` is sent to the customer''s email after the

        merchant triggers `customers:start_activation`.'
      operationId: activateCustomer
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
        description: Activation token from the email link.
        example: abc123def456ghi789
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - password
              properties:
                password:
                  type: string
                  description: The new password for the account (min 8 chars).
            example:
              password: newSecureP@ss1
      responses:
        '200':
          description: Account activated
          content:
            application/json:
              example:
                id: 3001
                email: jane@example.com
                status: private
                _links:
                  self:
                    href: https://api.onbolder.com/v2/customers/3001
        '422':
          description: Invalid or expired token
components:
  schemas:
    Contact:
      type: object
      properties:
        _links:
          $ref: '#/components/schemas/HalLinks'
        id:
          type: integer
        shop_id:
          type: integer
        email:
          type: string
        name:
          type: string
          description: Full name (first and last)
        phone_number:
          type: string
        phone_validated:
          type: boolean
        validation_method:
          type: string
        company_name:
          type: string
        company_id_number:
          type: string
          description: Company tax/ID number (RUT, DNI, etc.), formatted
        company_activity_code:
          type: string
        customer_status:
          type: string
          enum:
          - public
          - private
          - pending
          description: Customer account status.
        opt_in:
          type: boolean
          description: Whether the contact has opted in to marketing emails.
        source:
          type: string
        last_logged_on:
          type: string
          format: date-time
        last_ip_address:
          type: string
        has_password:
          type: boolean
        total_spent:
          type: integer
          description: In cents
        available_orders_count:
          type: integer
        salesperson_id:
          type: integer
        favorite_product_ids:
          type: array
          items:
            type: integer
        used_promotion_ids:
          type: array
          items:
            type: integer
        tags:
          type: array
          items:
            type: string
        created_on:
          type: string
          format: date-time
        updated_on:
          type: string
          format: date-time
        _embedded:
          type: object
          properties:
            contact_group:
              type: object
              description: Present when the contact belongs to a group
            addresses:
              type: array
              items:
                $ref: '#/components/schemas/Address'
    Pagination:
      type: object
      properties:
        total_items:
          type: integer
          example: 42
        per_page:
          type: integer
          example: 20
        page:
          type: integer
          example: 1
    Address:
      type: object
      properties:
        street:
          type: string
        street_2:
          type: string
        locality_name:
          type: string
        region_name:
          type: string
        country_name:
          type: string
        postal_code:
          type: string
    ContactList:
      allOf:
      - $ref: '#/components/schemas/Pagination'
      - type: object
        properties:
          _links:
            $ref: '#/components/schemas/HalLinks'
          _class:
            type: array
            items:
              type: string
            example:
            - results
            - customers
          _embedded:
            type: object
            properties:
              contacts:
                type: array
                items:
                  $ref: '#/components/schemas/Contact'
    HalLinks:
      type: object
      additionalProperties:
        oneOf:
        - $ref: '#/components/schemas/HalLink'
        - type: array
          items:
            $ref: '#/components/schemas/HalLink'
    ContactInput:
      type: object
      required:
      - email
      - name
      description: 'Input schema for creating or updating a contact. On create, `email` and `name` are required. On update (PUT), all fields are optional. If a contact with the given `email` already exists, it is updated rather than duplicated.

        '
      properties:
        email:
          type: string
          format: email
          description: Contact email address. Used as the unique identifier for find-or-create.
        name:
          type: string
          description: Full name (first and last).
        phone_number:
          type: string
        company_name:
          type: string
          description: Company name. Creates or finds a company record automatically.
        company_id_number:
          type: string
          description: Company tax/ID number (RUT, DNI, etc.), stored with the company record.
        tags:
          type: array
          items:
            type: string
          description: Tag names. Replaces all existing tags.
        opt_in:
          type: boolean
          description: Whether the contact accepts marketing emails/newsletters.
        contact_group_id:
          type: integer
          description: Contact group ID to assign this contact to.
        salesperson_id:
          type: string
          description: Shop admin user ID
        source:
          type: string
          enum:
          - signup-form
          - register-form
          - contact-form
          - checkout
          description: Origin of the contact record. Defaults to `API` if omitted on create.
        custom_data:
          type: array
          description: Custom field values for this contact.
          items:
            type: object
            properties:
              key:
                type: string
                description: Field key (slug)
              field_id:
                type: integer
                description: Field definition ID (optional alternative to key)
              value:
                description: Field value
    HalLink:
      type: object
      required:
      - href
      properties:
        href:
          type: string
        templated:
          type: boolean
        method:
          type: string
          enum:
          - get
          - post
          - put
          - patch
          - delete
        title:
          type: string
        type:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.onbolder.com/oauth/token
          scopes:
            products.read: View products, variants and collections
            products.write: Create and update products
            orders.read: View orders
            orders.write: Create and update orders
            customers.read: View customer profiles
            customers.write: Update customer profiles
            shops.read: View shop configuration
            shops.write: Update shop configuration
            hub.read: View content (posts, pages)
            hub.write: Create and update content
            store.read: View themes and assets
            store.write: Manage themes and assets
            sellers.read: View seller information
            batches.read: View batch job status
            batches.write: Create and run batch jobs
        authorizationCode:
          authorizationUrl: https://auth.onbolder.com/oauth/authorize
          tokenUrl: https://auth.onbolder.com/oauth/token
          scopes:
            products.read: View products, variants and collections
            products.write: Create and update products
            orders.read: View orders
            orders.write: Create and update orders
            customers.read: View customer profiles
            customers.write: Update customer profiles
            shops.read: View shop configuration
            shops.write: Update shop configuration
            hub.read: View content (posts, pages)
            hub.write: Create and update content
            store.read: View themes and assets
            store.write: Manage themes and assets
            sellers.read: View seller information
            batches.read: View batch job status
            batches.write: Create and run batch jobs