Newstore customer-profile API

openapi: 3.2.0
info:
  version: '1.0'
  title: NewStore Customer Profile API
  description: NewStore public APIs
  contact:
    email: support@newstore.com
    name: NewStore API Support
    url: https://developer.newstore.com
servers:
- url: https://dodici-demo.p.newstore.net/
security: []
tags:
- name: customer-profile
  description: Customer Profiles
paths:
  /customer/profiles:
    get:
      description: 'Returns a searchable list of consumer profiles.


        Note: This endpoint is designed for paginated front-end use with a search function. It is not suitable for exporting a comprehensive list of all customers due to the following limitations:

        - Pagination Per Page Limit: Up to 500 profiles can be fetched per page.

        - Total Profiles Limit: There is a maximum limit of 10,000 profiles.

        - API Error Beyond Limit: When trying to paginate beyond 10,000 profiles, the API will start returning errors.

        '
      summary: listProfiles
      tags:
      - customer-profile
      operationId: GetlistProfiles
      deprecated: false
      parameters:
      - name: q
        in: query
        required: false
        description: 'The search term to filter customers. The term is compared to the

          values in the `email`, `fullname` and `phonenumber` fields. A partial match is also

          considered a match.


          The term will also be compared to the values in the `id` and `display_id` fields.

          Only an exact match is considered a match.'
        schema:
          type: string
      - name: sort
        in: query
        required: false
        description: The sort to be applied to customers response.
        schema:
          type: string
      - name: offset
        in: query
        required: false
        description: The customer profiles page offset.
        schema:
          type: integer
          format: int32
          default: 0
          minimum: 0.0
      - name: count
        in: query
        required: false
        description: The number of requested customer profiles.
        schema:
          type: integer
          format: int32
          default: 10
          maximum: 500.0
          minimum: 1.0
      responses:
        default:
          description: Unexpected error
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '200':
          description: The list customer profiles response.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ListProfilesResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ListProfilesResponse'
        '400':
          description: Bad Request.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Forbidden.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal server error.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Bad Gateway
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - oauth:
        - customer:profile:read
    post:
      description: "\n<div style=\"background-color: rgba(243, 156, 18, 0.15); border: 1px solid #f39c12; border-left: 4px solid #f39c12; padding: 12px; margin: 10px 0; border-radius: 4px; color: #f39c12;\">\n  <strong>\U0001F6A7 BETA:</strong> This endpoint is in beta and may change.\n  <br />\n  See <a href=\"https://docs.newstore.com/docs/api-lifecycle\" target=\"_blank\" style=\"color: #f39c12; text-decoration: underline;\">API Lifecycle Documentation</a> for details.\n</div>\n\nGet-or-create by email. Creates a new customer profile, or, if a profile\nalready exists for the given email, returns that existing profile\nunchanged. It does NOT update an existing profile — use the update\nendpoint (`PATCH /profiles/{profile_id}`) to change fields on an existing\nprofile.\n\nKNOWN LIMITATION: on success this endpoint always responds `201 Created`,\neven when it returned a pre-existing profile instead of creating one. The\nstatus code therefore cannot be used to tell a create apart from a get;\nif you need to distinguish them, compare the returned profile's\n`created_at` and `updated_at`. Neither a `200` nor a `409` is returned by\nthis endpoint.\n\n**Note:**\nThe Consumer Profile V2 API allows for a single approach to create customer names. When creating a profile, the client must choose one of the following name approaches:\n\n- first_name and last_name\n- full_name\n\nProviding both approaches will result in a bad request error from the API.\n"
      summary: createOrShowProfile
      tags:
      - customer-profile
      operationId: createOrShowProfile
      deprecated: false
      parameters:
      - name: Content-Type
        in: header
        required: false
        description: ''
        schema:
          type: string
          enum:
          - application/json
      responses:
        default:
          description: Unexpected error
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '201':
          description: Success. A new profile was created, OR an existing profile with the same email was returned unchanged. Per the known limitation in the operation description, 201 is returned in both cases.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProfileResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileResponse'
        '400':
          description: Bad Request.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Forbidden.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '422':
          description: Unable to process the entity.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal server error.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Bad Gateway
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - oauth:
        - customer:profile:write
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProfileRequest'
        description: Request payload
        required: true
  /customer/profiles/{profile_id}:
    get:
      description: 'Returns a single customer profile for the given customer `profile_id`.

        '
      summary: showProfile
      tags:
      - customer-profile
      operationId: GetshowProfile
      deprecated: false
      parameters:
      - name: profile_id
        in: path
        required: true
        description: Profile ID
        schema:
          type: string
      responses:
        default:
          description: Unexpected error
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '200':
          description: The customer profile response.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProfileResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileResponse'
        '400':
          description: Bad Request.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Forbidden.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: Not Found.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal server error.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Bad Gateway
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - oauth:
        - customer:profile:read
    patch:
      description: 'Updates an existing customer profile for the given `profile_id`.


        **Note:**

        The Consumer Profile V2 API allows for a single approach to update customer names. When updating a profile, the client must choose one of the following name approaches:


        - first_name and last_name

        - full_name


        Providing both approaches will result in a bad request error from the API.


        **Note:**

        If `extended_attributes` is provided, it will replace any existing attributes for the customer.

        '
      summary: updateProfile
      tags:
      - customer-profile
      operationId: updateProfile
      deprecated: false
      parameters:
      - name: profile_id
        in: path
        required: true
        description: Profile ID
        schema:
          type: string
      - name: Content-Type
        in: header
        required: false
        description: ''
        schema:
          type: string
          enum:
          - application/json
      responses:
        default:
          description: Unexpected error
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '200':
          description: The update customer profile response.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProfileResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileResponse'
        '403':
          description: Forbidden.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: Profile not found.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: 'Conflict response.

            It happens when profile has a newer state, than given last_updated_at.'
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '422':
          description: Unable to process the entity.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal server error.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Bad Gateway
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - oauth:
        - customer:profile:write
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProfileRequest'
        description: Request payload
        required: true
    post:
      description: Creates request for customer profile deletion.
      summary: createProfileDeletionRequest
      tags:
      - customer-profile
      operationId: createProfileDeletionRequest
      deprecated: false
      parameters:
      - name: profile_id
        in: path
        required: true
        description: Profile ID
        schema:
          type: string
      - name: Content-Type
        in: header
        required: false
        description: ''
        schema:
          type: string
          enum:
          - application/json
      responses:
        default:
          description: Unexpected error
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '202':
          description: Deletion request accepted.
          headers: {}
        '400':
          description: Bad Request.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Forbidden.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: Profile not found.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: Deletion already requested.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal server error.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Bad Gateway
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - oauth:
        - customer:profile:write
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProfileDeletionRequest'
        description: Request payload
        required: true
components:
  schemas:
    ListProfilesResponse:
      title: ListProfilesResponse
      description: List profiles response.
      type: object
      properties:
        pagination_info:
          type: object
          allOf:
          - $ref: '#/components/schemas/PaginationInfo'
          - description: Pagination info.
        profiles:
          type: array
          items:
            $ref: '#/components/schemas/ProfileResponse'
      required:
      - pagination_info
      - profiles
    CreateProfileRequest:
      title: CreateProfileRequest
      type: object
      properties:
        email:
          description: Email of the customer.
          type: string
        created_by:
          description: The identifier of the associate creating profile
          type: string
        extended_attributes:
          description: Additional attributes for a customer.
          example:
            loyalty_id:
              data_type: string
              value: 0123456789
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ExtendedAttributeModel'
        first_name:
          description: The first name of the customer.
          type: string
        full_name:
          description: Full name of the customer, including first, middle and last name.
          type: string
          maxLength: 256
        last_name:
          description: The last name of the customer.
          type: string
        phone_number:
          description: Phone number of the customer in E.164 format.
          type: string
        store_id:
          description: The identifier of the store, profile is being created in.
          type: string
      required:
      - email
    ProfileDeletionRequest:
      title: ProfileDeletionRequest
      description: Profile deletion request payload.
      type: object
      properties:
        operation:
          type: string
          default: delete
      required:
      - operation
    UpdateProfileRequest:
      title: UpdateProfileRequest
      description: Update profile request.
      type: object
      properties:
        email:
          description: Email of the customer.
          type: string
        last_updated_at:
          description: Timestamp of the latest profile update.
          type: string
          format: date-time
        created_by:
          description: The identifier of the associate creating profile
          type: string
        extended_attributes:
          description: Additional attributes for a customer.
          example:
            loyalty_id:
              data_type: string
              value: 0123456789
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ExtendedAttributeModel'
        first_name:
          description: The first name of the customer.
          type: string
        full_name:
          description: Full name of the customer, including first, middle and last name.
          type: string
          maxLength: 256
        last_name:
          description: The last name of the customer.
          type: string
        phone_number:
          description: Phone number of the customer in E.164 format.
          type: string
        store_id:
          description: The identifier of the store, profile is being created in.
          type: string
      required:
      - last_updated_at
    Problem:
      title: Problem
      type: object
      properties:
        detail:
          description: A human readable explanation specific to this occurrence of the problem that is helpful to locate the problem and give advice on how to proceed. Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized.
          example: some description for the error situation
          type: string
        error_code:
          type: string
        instance:
          description: A URI reference that identifies the specific occurrence of the problem, e.g. by adding a fragment identifier or sub-path to the problem type. May be used to locate the root of this problem in the source code.
          example: /some/uri-reference#specific-occurrence-context
          type: string
        message:
          type: string
        messages:
          type: array
          items:
            type: string
        request_id:
          type: string
        status:
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
          type: integer
          minimum: 100.0
          format: int32
          exclusiveMaximum: 600.0
        title:
          description: A short summary of the problem type. Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized.
          example: some title for the error situation
          type: string
        type:
          description: A URI reference that uniquely identifies the problem type only in the context of the provided API. Opposed to the specification in RFC-7807, it is neither recommended to be dereferenceable and point to a human-readable documentation nor globally unique for the problem type.
          example: /some/uri-reference
          type: string
          default: about:blank
    ProfileResponse:
      title: ProfileResponse
      type: object
      properties:
        created_at:
          description: Timestamp of the profile creation.
          type: string
          format: date-time
        created_by:
          description: The identifier of the associate creating profile
          type: string
        display_id:
          description: The human readable profile identifier.
          type: string
        email:
          description: Email of the customer.
          type: string
        extended_attributes:
          description: Additional attributes for a customer.
          example:
            loyalty_id:
              data_type: string
              value: 0123456789
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ExtendedAttributeModel'
        first_name:
          description: First name of the customer.
          type: string
        full_name:
          description: Full name of the customer, including first, middle and last name.
          type: string
          maxLength: 256
        id:
          description: The profile identifier.
          example: NS-EU-01FXX4RSTKMVBFPBVZFPGM97ZW-01FXX4S1V1R8M4PF9H1S1D82CX
          type: string
        last_name:
          description: Last name of the customer.
          type: string
        phone_number:
          description: Phone number of the customer in E.164 format.
          type: string
        store_id:
          description: The identifier of the store, profile is being created in.
          type: string
        updated_at:
          description: Timestamp of the latest profile update.
          type: string
          format: date-time
      required:
      - created_at
      - created_by
      - display_id
      - email
      - extended_attributes
      - first_name
      - full_name
      - id
      - last_name
      - phone_number
      - store_id
      - updated_at
    ExtendedAttributeModel:
      title: ExtendedAttributeModel
      description: Key-value pair describing a custom attribute associated with the profile.
      type: object
      properties:
        data_type:
          description: Data type of the additional attribute.
          example: string
          type: string
        value:
          description: Value of the additional attribute.
          example: 0123456789
          type: string
      required:
      - data_type
      - value
    PaginationInfo:
      title: PaginationInfo
      description: Pagination info.
      type: object
      properties:
        count:
          description: Amount of items in the current page.
          type: integer
          format: int64
        offset:
          description: Offset of the current page.
          type: integer
          format: int64
        total:
          description: Total amount of the items for given filters set.
          type: integer
          format: int64
      required:
      - count
      - offset
      - total
  securitySchemes:
    oauth:
      type: oauth2
      flows:
        clientCredentials:
          scopes:
            catalog:import-schemas:read: Grants privileges to read import schema
            catalog:import-schemas:write: Grants privileges to write import schema
            catalog:pricebook-export:read: Grants privileges to export pricebook data
            catalog:product-export:read: Grants privileges to export product data
            checkout:carts:read: Grants privileges to read cart data
            checkout:carts:write: Grants privileges to write cart data
            clienteling:profile:read: Grants privileges to read clienteling profiles
            customer:profile:read: Grants privileges to read API customer data
            customer:profile:write: Grants privileges to modify API customer data
            newstore:configuration:read: Grants privileges to read configuration
            newstore:configuration:write: Grants privileges to write configuration
            fiscalization:orders:read: View orders with fiscal transactions and signatures
            fiscalization:orders:write: Create orders with fiscal transactions and signatures
            shipments:read: Read Shipping Options and Audits
            iam:providers:read: ' Grants read privileges to provider resources'
            iam:providers:write: ' Grants write privileges to provider resources'
            iam:roles:read: ' Grants privileges to read roles data'
            iam:roles:write: ' Grants privileges to write roles data'
            iam:users:read: ' Grants privileges to read user data'
            iam:users:write: ' Grants privileges to write user data'
            inventory:reservations:read: Allows access to retrieve reservations
            inventory:reservations:write: Allows access to create and update reservations
            promotions:config:read: Grants privileges to read configuration
            promotions:config:write: Grants privileges to write into configuration
            promotions:reason-codes:read: Grants privileges to list reason codes
            promotions:reason-codes:write: Grants privileges to create and update reason codes
            audit-events:read: Grants read access to the tenant's audit events.
            taxes:preview-transactions:write: Preview tax transactions
            taxes:transactions:read: Read tax transactions
          tokenUrl: https://id.p.newstore.net/auth/realms/dodici-demo/protocol/openid-connect/token